Tempusxr Français
Menu
  1. Docs
  2. 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

OptionWhat it does
containerThe element that holds the camera and the 3D canvas. All options of create() work too (overlay, language, debug).
baseUrlWhere relative paths start. Default: the address of the scene file.
onProgressCalled each time a file is loaded: the scene, the target files, then each asset.
onEventTells 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.
loadersYour own model loaders, for pages that cannot import the Three.js addons.
signalAn AbortSignal that cancels the loading.

What you get back

What each asset becomes

TypeWhat is built
modelThe GLB, copied for each node. Animations play with animation.clip.
imageA flat plane with the picture. Never kept larger than 2048 pixels.
videoA plane that plays the video, inline. The poster shows until it plays.
audioA sound with no picture, controlled by play and pause.
textA 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

TriggerWhen
found, lostA target is found or lost.
loadRight after start().
tapA 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:

CodeMeaning
invalid-sceneThe scene is not valid. error.issues lists every problem with its code and path.
fetch-failedThe scene file could not be loaded. error.file is its address.
asset-failedA target or an asset could not be loaded. error.file is its address.
tracker-unavailableThe scene needs a tracker you did not import.
abortedThe 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>