Unreal Engine · Loading

Loading files

What opens a file, what it builds, and how to do it without stalling the frame.

Loading a CAD file, step by step: Load CAD File Async on BeginPlay, a progress bar fed by On Load Progress, and Get Last Frame Stats once it is in. The quadcopter is one STEP assembly of 3,174 nodes, modelled with our own kernel.
Where the document lives

One component, three actors

Everything is on UCadaclysmComponent: loading, the tree, per-part edits, picking, collision. The actors differ only in what they put the component on.

ActorWhat it is for
Cadaclysm ActorA document in the level, drawn from triangles. The plainest, and the one to start with.
Cadaclysm Surface ActorThe same, with the surface component on it: parts drawn from their own surfaces and never meshed. See triangles or surfaces.
Cadaclysm Part Bodies ActorThe single primitive, plus one physics body per part, for parts that fall and collide.
Cadaclysm Static Mesh ActorGives up the single primitive and hands every part to the engine as a static mesh component, optionally with Nanite. For projects that want ordinary Unreal actors.
The Details panel, Cadaclysm Load category: Load Edges, Load Curves, Load Isocurves, Load Mesh and Load Unreachable Geometry
What a load builds, set on the Document component before the file is opened.

Or add a Cadaclysm component to an actor of your own: the actors forward loading and nothing else.

Without stalling

Loading at run time

Load CAD File blocks until the document is drawable. That is right at a loading screen and wrong anywhere else: a large assembly takes seconds, and no frame happens during them. Load CAD File Async returns at once, does the work on a worker, and reports its progress through OnLoadProgress — the phase (parsing, meshing, reading, building) and how far through it. The geometry appears as soon as it exists.

Document->OnLoadProgress.AddDynamic(this, &AMyActor::OnProgress);
Document->LoadFileAsync(Path, ECadaclysmConvention::Unreal);
// ... later, to give up on it:
Document->CancelLoad();
A Blueprint graph: BeginPlay calls Load CAD File Async; the Document component's On Load Progress event switches on the phase and prints when it reaches Complete
The same in Blueprint: Load CAD File Async, and On Load Progress bound from the Document component, switching on the phase.

A second call supersedes the first. IsLoading and GetLoadPhase answer where it is, and Get Load Diagnostics hands back what the reader and the mesher complained about — a face that would not trim, a body that could not be read — as a list you can show or log. A file that opens with diagnostics is normal; a file that opens with none is a good file.

Units and axes

The convention

CAD is Z up, right-handed, usually millimetres. Unreal is Z up, left-handed, centimetres. The Convention pin on the load node decides which space the document arrives in, and defaults to Unreal: the conversion is done as the geometry is built, triangle winding included, so nothing is mirrored by a negative scale on the actor and normals point out.

ConventionSpace
UnrealZ up, left-handed, centimetres. The default.
NativeExactly what the file says, in its own units.
Unity, YUp, BlenderThe other engines' spaces, for a project that shares code with them.
Where the file put it

Documents far from the origin

A site on its survey grid sits millions of units out, where a GPU's single-precision float is a quarter of a unit apart. The component keeps its triangles, surfaces and lines about a point near the document and puts that point back in double precision, so a building 2,600 km out draws exactly as it does at the origin — faces, edges and picking alike.

Shadows need virtual shadow maps that far out. Measured on a site 2,600 km from the world origin: Unreal's cascaded and ray-traced shadows drop out there for every mesh, its own static meshes included, while virtual shadow maps (r.Shadow.Virtual.Enable=1) keep them. A project that loads survey-grid files wants them on.

STEP and IFC schemas

Usually nothing to set

STEP and IFC files name the EXPRESS schema they were written against, and every schema the library ships — the STEP application protocols, the IFC releases — is compiled in. A file opens with nothing configured and nothing staged beside the plugin.

Express Schema Paths is for a schema the library does not carry: a house schema, or a release newer than the plugin. Any entry may be a directory, walked to its depths with every .exp under it registered, so a project can point at the folder its schemas live in. They are read in sorted order, so where two files declare the same schema name the same one wins on every machine. A schema with the same name as a built-in replaces it.

What a load builds

Decided before the file is opened

These are read when the load starts, because they decide what is built and kept. Changing one afterwards does nothing until the file is opened again — the component builds its buffers and closes the file, which is what lets a very large assembly be drawn without also being held twice.

PropertyDefaultWhat it decides
Load MeshonWhether parts are meshed at all. Off, with the surface component, is a document with no triangles in it.
Load Edges, Load Curves, Load IsocurvesonWhich families of lines are built. A kind that was not built cannot be shown later. See edges and isocurves.
Generate Levels Of DetailonSimplified copies of each part, chosen by screen size while drawing.
Use Vertex Color BufferonFour bytes a vertex so parts can be recoloured at run time. Off saves the memory and fixes the colours.
Generate Texture CoordinatesoffWorld-scale UVs, for a material that needs them.
Generate Collision, Hull Triangle Budgetoff, 255One convex hull fitted per part, or several with Max Hulls Per Part. See collision.
Keep Document For QueriesonKeeps the file's tree open — names, properties, the query language — after the geometry is built. The meshes are let go either way.
Load Unreachable GeometryoffBodies the file's own tree never places. Useful for inspecting a file, wrong for drawing one.

The one exception to “read at load” among the heavy things is the distance field, which can be rebuilt in place at a new resolution because it is built from the buffers the component already holds. A collision fit cannot: it needs the document itself.

What comes back

The tree

A document is a tree of nodes: assemblies, sub-assemblies and parts, with names, colours, placements and whatever properties the file carried. Get Num Nodes, Get Node, Get Root Nodes and Get Node Details walk it; Get Node Bounds and Get Node Transform place it. A part used a hundred times is read once and placed a hundred times, and is drawn that way too. The parts page is about working with them.