Tempusxr English
Menu
  1. Documentation
  2. 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

OptionCe qu'elle fait
containerL'élément qui contient la caméra et le canvas 3D. Toutes les options de create() marchent aussi (overlay, language, debug).
baseUrlD'où partent les chemins relatifs. Par défaut : l'adresse du fichier de scène.
onProgressAppelée à chaque fichier chargé : la scène, les fichiers cibles, puis chaque asset.
onEventDit 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.
loadersVos propres chargeurs de modèles, pour les pages qui ne peuvent pas importer les modules complémentaires de Three.js.
signalUn AbortSignal qui annule le chargement.

Ce que vous recevez

Ce que devient chaque asset

TypeCe qui est construit
modelLe GLB, copié pour chaque nœud. Les animations se lancent avec animation.clip.
imageUn plan plat avec l'image. Jamais gardée au-dessus de 2048 pixels.
videoUn plan qui joue la vidéo, en ligne. Le poster s'affiche jusqu'à la lecture.
audioUn son sans image, piloté par play et pause.
textUn 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éclencheurQuand
found, lostUne cible est trouvée ou perdue.
loadJuste après start().
tapUn 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 :

CodeSens
invalid-sceneLa scène n'est pas valide. error.issues liste chaque problème avec son code et son chemin.
fetch-failedLe fichier de scène n'a pas pu être chargé. error.file est son adresse.
asset-failedUne cible ou un asset n'a pas pu être chargé. error.file est son adresse.
tracker-unavailableLa scène a besoin d'un traqueur que vous n'avez pas importé.
abortedLe 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>