- Documentation
- Construire avec le SDK
Ouvrir une scène avec loadScene
loadScene() transforme un fichier de scène en expérience de RA qui tourne : elle lit et vérifie le fichier, charge les fichiers cibles et les assets, construit le contenu 3D, branche les comportements et démarre la caméra. C'est ce que fait le Viewer. Elle vit dans @tempusxr/sdk-three.
Un premier exemple
import { loadScene } from '@tempusxr/sdk-three';
import '@tempusxr/sdk-tracker-image'; // enregistre le traqueur 'image'
const experience = await loadScene('https://example.com/s/abc123/scene.json', {
container: '#ar',
onProgress: ({ loaded, total }) => bar.set(loaded / total),
});
// Appelez-la depuis un toucher : les téléphones ne lancent le son et la vidéo qu'après un geste.
startButton.addEventListener('click', () => experience.start());
loadScene se termine quand tout est chargé et que rien n'a démarré. Montrez votre écran de chargement jusque-là, puis un bouton Démarrer.
Essayez : ouvrez l'exemple de scène, ou donnez-lui votre fichier avec ?scene=votre.json.
Options
| Option | Ce qu'elle fait |
|---|---|
container | L'élément qui contient la caméra et le canvas 3D. Toutes les options de create() marchent aussi (overlay, language, debug). |
baseUrl | D'où partent les chemins relatifs. Par défaut : l'adresse du fichier de scène. |
onProgress | Appelée à chaque fichier chargé : la scène, les fichiers cibles, puis chaque asset. |
onEvent | Dit ce qui se passe : start, found, lost, tap, et chaque action exécutée. Pour les statistiques et les journaux. |
decoders | { dracoPath, meshopt } : lire des modèles compressés. Chargés seulement si besoin. |
loaders | Vos propres chargeurs de modèles, pour les pages qui ne peuvent pas importer les modules complémentaires de Three.js. |
signal | Un AbortSignal qui annule le chargement. |
Ce que vous recevez
scene: la scène vérifiée, avec toutes les valeurs par défaut.session: le même objet que renvoiecreate()(caméra, scène 3D, overlay).nodes: le groupe de chaque nœud, par identifiant.start(): démarre la caméra et les traqueurs.dispose(): arrête tout et libère la mémoire. Sans danger à tout moment.
Ce que devient chaque asset
| Type | Ce qui est construit |
|---|---|
model | Le GLB, copié pour chaque nœud. Les animations se lancent avec animation.clip. |
image | Un plan plat avec l'image. Jamais gardée au-dessus de 2048 pixels. |
video | Un plan qui joue la vidéo, en ligne. Le poster s'affiche jusqu'à la lecture. |
audio | Un son sans image, piloté par play et pause. |
text | Un plan avec le texte dessiné dessus. |
Les positions sont en largeurs d'image. Quand une cible a une largeur imprimée, le chargeur convertit en mètres pour vous : une même scène marche dans les deux cas. Un GLB garde ses unités : 1 unité vaut 1 largeur d'image.
Comportements
| Déclencheur | Quand |
|---|---|
found, lost | Une cible est trouvée ou perdue. |
load | Juste après start(). |
tap | Un toucher atteint un nœud, ou une partie de lui. Un toucher sur un enfant compte pour son parent si l'enfant n'a pas de comportement. |
Les actions sont show, hide, play, pause et openUrl. openUrl ne marche qu'avec tap, car les téléphones n'ouvrent une adresse qu'après un toucher. Les comportements d'un même déclencheur s'exécutent dans l'ordre du fichier.
Erreurs
loadScene lève une SceneLoadError avec un code :
| Code | Sens |
|---|---|
invalid-scene | La scène n'est pas valide. error.issues liste chaque problème avec son code et son chemin. |
fetch-failed | Le fichier de scène n'a pas pu être chargé. error.file est son adresse. |
asset-failed | Une cible ou un asset n'a pas pu être chargé. error.file est son adresse. |
tracker-unavailable | La scène a besoin d'un traqueur que vous n'avez pas importé. |
aborted | Le signal a annulé le chargement. |
Les problèmes de caméra et de permission continuent d'afficher les écrans d'erreur de l'overlay, avec un bouton Réessayer.
Pages et import maps
Le paquet de scène et les modules complémentaires de Three.js ne sont lus que si une scène en a besoin : les pages qui n'ouvrent jamais de scène ne paient rien. Dans une page sans bundler, ajoutez-les à l'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>