- Docs
- Build with the SDK
Open a scene file with loadScene
loadScene() turns a scene file into a running AR experience: it reads and checks the file, loads the target files and the assets, builds the 3D content, connects the behaviors and starts the camera. It is what the Viewer does. It lives in @tempusxr/sdk-three.
A first example
import { loadScene } from '@tempusxr/sdk-three';
import '@tempusxr/sdk-tracker-image'; // registers the 'image' tracker
const experience = await loadScene('https://example.com/s/abc123/scene.json', {
container: '#ar',
onProgress: ({ loaded, total }) => bar.set(loaded / total),
});
// Call it from a tap: phones start sound and video only after a gesture.
startButton.addEventListener('click', () => experience.start());
loadScene finishes when everything is loaded and nothing has started yet. Show your loading screen until then, and a Start button after.
Try it: open the scene example, or give it your own file with ?scene=your.json.
Options
| Option | What it does |
|---|---|
container | The element that holds the camera and the 3D canvas. All options of create() work too (overlay, language, debug). |
baseUrl | Where relative paths start. Default: the address of the scene file. |
onProgress | Called each time a file is loaded: the scene, the target files, then each asset. |
onEvent | Tells what happens: start, found, lost, tap, and each action that ran. For analytics and logs. |
decoders | { dracoPath, meshopt }: read compressed models. Loaded only when needed. |
loaders | Your own model loaders, for pages that cannot import the Three.js addons. |
signal | An AbortSignal that cancels the loading. |
What you get back
scene: the checked scene, with every default filled in.session: the same objectcreate()returns (camera, stage, overlay).nodes: the group of each node, by id.start(): starts the camera and the trackers.dispose(): stops everything and frees the memory. Safe at any moment.
What each asset becomes
| Type | What is built |
|---|---|
model | The GLB, copied for each node. Animations play with animation.clip. |
image | A flat plane with the picture. Never kept larger than 2048 pixels. |
video | A plane that plays the video, inline. The poster shows until it plays. |
audio | A sound with no picture, controlled by play and pause. |
text | A plane with the text drawn on it. |
Positions are in image widths. When a target has a printed width, the loader converts to meters for you, so one scene works either way. A GLB keeps its own units: 1 unit is 1 image width.
Behaviors
| Trigger | When |
|---|---|
found, lost | A target is found or lost. |
load | Right after start(). |
tap | A tap hits a node, or a part of it. A tap on a child counts for its parent if the child has no behavior. |
Actions are show, hide, play, pause and openUrl. openUrl works only with tap, because phones open an address only after a person tapped. Behaviors of one trigger run in the order of the file.
Errors
loadScene throws a SceneLoadError with a code:
| Code | Meaning |
|---|---|
invalid-scene | The scene is not valid. error.issues lists every problem with its code and path. |
fetch-failed | The scene file could not be loaded. error.file is its address. |
asset-failed | A target or an asset could not be loaded. error.file is its address. |
tracker-unavailable | The scene needs a tracker you did not import. |
aborted | The signal cancelled the loading. |
Camera and permission problems keep showing the overlay's error screens, with a Try again button.
Pages and import maps
The scene package and the Three.js addons are read only when a scene needs them, so pages that never open a scene pay nothing. In a page without a bundler, add them to the import map:
<script type="importmap">
{
"imports": {
"three": "/node_modules/three/build/three.module.js",
"three/addons/": "/node_modules/three/examples/jsm/",
"@tempusxr/scene": "/packages/scene/dist/index.js",
"@tempusxr/sdk-three": "/packages/sdk-three/dist/index.js"
}
}
</script>