Tempusxr Français
Menu
  1. Docs
  2. About Tempusxr

Scene format v1

A scene is a JSON file that describes a whole AR experience: which images to find, what to show on them, and what happens when people look or tap. The Viewer and the Studio read and write this format, and the SDK will load it with loadScene(). The package @tempusxr/scene checks it. It is pure data: it knows nothing about cameras, Three.js or A-Frame.

An example

{
  "version": 1,
  "id": "poster-chair",
  "tracker": { "kind": "image", "targets": [{ "id": "poster", "file": "poster.txr" }] },
  "assets": [
    { "id": "chair", "type": "model", "src": "chair.glb" },
    { "id": "promo", "type": "video", "src": "promo.mp4", "loop": true }
  ],
  "nodes": [
    { "id": "chair-node", "asset": "chair", "anchor": "poster", "position": [0, 0, 0.1] },
    { "id": "video-node", "asset": "promo", "anchor": "poster", "fit": "image" }
  ],
  "behaviors": [
    { "on": "found", "target": "poster", "do": "play", "node": "video-node" },
    { "on": "tap", "node": "chair-node", "do": "openUrl", "url": "https://example.com/chair" }
  ]
}

The parts

PartWhat it holds
trackerHow the content is anchored. kind: "image": one .txr file per image (the image compiler makes them), and maxTrack, how many are followed at once. kind: "world": no picture, see world tracking.
assetsThe things you can show: model (GLB, with an optional compression: ["meshopt"]), image (with "projection": "equirect" for a 360 photo), video, audio, text and portal (a doorway to another world, see the portal guide).
nodesWhat is placed on a target: one asset, a position, a rotation, a scale. A node without an asset is a group, and other nodes name it as their parent.
behaviorsWhat happens: found, lost, tap or load, then play, pause, show, hide or openUrl. A tap names the node that is tapped with from (or node), and the node acted on with node. openUrl works only with tap or press. cover names a virtual button (below), enter and exit name a portal node with from (world tracking only), and forward and reverse play an animation to its end or back to its start.
buttons (in a target)Virtual buttons: zones printed on the image, { id, rect: [x, y, width, height], sensitivity }, the rectangle in fractions of the image from its top left corner. A cover behavior fires when a finger covers the zone, so a poster can have printed Explode and Normal buttons. The zone needs a printed pattern to be read well. A zone counts as covered when about half of it is hidden (sensitivity moves that). Only one zone of a target is pressed at a time, so a hand over two of them presses the one it covers most. A zone cannot be pressed during its first 0.7 s after the target is found, nor while the target moves fast.
controlsButtons of the experience (type: "button" and a label). A press behavior names one.
metaFree space for a title, a description and the brand of the Viewer.

Units

Positions and sizes are in image widths: 1 is the width of the target image, and +Z comes out of the image toward you. With a world tracker they are in meters (+Y is up). Rotations are in degrees. The file holds no matrices.

Addresses

A src or file is a path relative to the scene file, or an https address. Any other kind of address is refused. A button can open https, mailto or tel links.

Checking a scene

import { parseScene } from '@tempusxr/scene';

const result = parseScene(json);
if (result.ok) console.log(result.scene.nodes.length);
else for (const issue of result.issues) console.log(issue.code, issue.path, issue.message);

parseScene migrates an older scene first, then checks the shape, then the links between ids. It returns every problem at once and never throws. Each problem has a stable code (for example unknown-asset, duplicate-id, unsafe-url), a path such as nodes[0].asset, and an English message. The Studio shows its own French or English text for each code.

Versions

The file says "version": 1. When the format changes, the version goes up and a migration turns old scenes into the new version, so scenes made today keep loading. A scene with a newer version than the software knows is refused with version-too-new and is never guessed at.