OptionalbaseOptional base URL used by formats that reference external resources
(e.g. glTF's separate .bin and texture files). When set, the loader
resolves relative URIs in the model file against this base — set this
to the directory the model lives in.
OptionalcoordinateDescribes the coordinate system of the model to load.
When provided, this enables the loader to automatically transform the model from its local oordinate system to the Scene's global coordinate system.
OptionaldataOptional parent DataObject id under which per-feature metadata DataObjects
(from EXT_structural_metadata) are aggregated.
OptionaldracoOptional Draco decoder module (draco3d), injected by the caller to decode
KHR_draco_mesh_compression content. The SDK does not bundle the Draco
WASM itself; when omitted, Draco-compressed content cannot be decoded.
import draco3d from "draco3d";
loader.load(params, { dracoModule: draco3d });
OptionallayerOptional layer ID to assign to all SceneObjects created by the loader.
See SceneObject.layerId for details on how this layer ID is used when the Scene is attached to a Viewer.
OptionalonOptional progress callback. Loaders fire this from inside their hot loops at roughly 60 Hz (paced by the same yieldToHost interval that keeps the main thread responsive). UIs subscribe to drive a progress bar / phase label / cancellable dialog.
The callback receives a LoaderProgress object literal. Loaders may reuse the same object across emits — copy out any fields you need to retain past the synchronous call.
OptionalprogressiveWhen false (the default), the SceneModel is marked
building for the duration of the
load, so a connected renderer suspends per-frame uploads + draws until the
model is fully assembled and then renders it once — fastest time to the
first frame showing the whole model, but the view is static during the load
(no progressive reveal, no camera interaction).
Set true to render the model incrementally as it loads (progressive
reveal), at the cost of redundant mid-load frames.
Has no effect when no renderer is attached.
OptionalretainRetain each texture's original encoded image bytes (the source PNG/JPEG) on the SceneTexture so exporters can re-emit them losslessly without re-encoding via a 2D canvas (which is unavailable under Node). Off by default — the viewer renders from the decoded image and the extra bytes are wasted memory. Conversion tools that re-export the model set this.
OptionalrootOptional 4×4 transform (column-major) pre-multiplied into every node's world matrix, placing the content without baking the transform into shared geometry.
OptionalsignalOptional AbortSignal. Loaders that have been swept to
cooperative-yield (every modern parser in formats/)
check signal.aborted at every yield point and throw a
DOMException("Aborted", "AbortError") when the caller
cancels — combine with the signal your UI uses for the
Cancel button on a load dialog.
Loaders that pre-date the sweep ignore this field and run to completion regardless — passing it is safe in either case.
OptionalyieldMinimum gap (in milliseconds) between cooperative yields
during the load. The default of 16ms (≈ 60 Hz) keeps the UI
fully responsive but pays the setTimeout(0) overhead
(~4 ms per yield on most browsers) on every animation
frame, which adds up across a long load. Raising this to
50–100ms cuts that overhead and noticeably speeds up large
loads, at the cost of progress-bar / paint updates landing
at 10–20 Hz instead of 60 Hz.
Values under 16ms are clamped to 16ms — going below the default doesn't increase perceived smoothness and only adds yield overhead.
Loaders that pre-date the cooperative-yield sweep ignore this field; passing it is safe in either case.
Options for GLTFLoader.load, extending the shared ModelLoadOptions with glTF-specific concerns.