Documentation is work in progress and not completeEditor
3D System
Model Import System
ModelLoader handles external 3D model files: format detection, loader instantiation, normalization and object-URL lifecycle. Five formats are supported.
Supported Formats
| Format | Extension | Data Supported | Notes |
|---|---|---|---|
| GLTF Binary | .glb | Geometry, materials, textures, animations, scene hierarchy | Recommended. Self-contained binary file. |
| GLTF | .gltf | Same as GLB | JSON file that may reference external .bin and texture files, which will not resolve through object URLs |
| Wavefront OBJ | .obj | Geometry only | No materials or textures. All meshes get a default material |
| FBX | .fbx | Geometry, basic materials, animations | Material fidelity varies |
| STL | .stl | Geometry only (triangulated mesh) | Gets a default blue material (#3B82F6, roughness 0.5, metalness 0.1) |
Import Pipeline
- •File picker — a hidden file input accepting the five supported extensions.
- •Extension detection — taken from the filename.
- •Object URL creation — a temporary URL the loader can fetch.
- •Loader selection — a switch picks GLTFLoader, OBJLoader, FBXLoader or STLLoader.
- •Normalization — the bounding box is computed, a scale factor of 2 / maxDim is applied so the largest dimension becomes 2 units, then the object is translated so its center sits at the origin.
- •Shadow setup — every mesh gets castShadow and receiveShadow.
- •URL revocation — the temporary URL is released.
- •Scene registration — the engine clears existing primitives, then registers the imported object.
Draco Decoder Setup
Draco is a compression format for GLTF meshes. Its decoder files must be served from public/draco/gltf/:
public/draco/gltf/
draco_decoder.js
draco_decoder.wasm
draco_wasm_wrapper.jsThe path is configured via dracoLoader.setDecoderPath("/draco/gltf/"). If these files are missing, Draco-compressed GLTF files fail silently or throw a network error.
Engine Safety
- •If the engine is disposed before loading starts, an error is thrown.
- •If the engine is disposed during the async load, the loaded object's geometries and materials are disposed immediately to prevent a leak.
- •On success, the existing scene is cleared before the model is added.
Loaders are lazily instantiated as module-level singletons, so the first call creates the loader and later calls reuse it.
Serialization Limitation
Imported models carry geometryType: "imported", and restoreScene() skips them because their binary mesh data is not stored in the JSON snapshot. If a project is saved and reloaded, imported models must be re-imported. Only primitive shapes survive serialization.