Load and play a GLTF model

quick start Beginner ⏱ 6 min vgai 0.1.0

Prerequisites: Installed vgai and run the editor

What you'll learn

• Load a GLTF model through the shared, DRACO-enabled loader
• Play the model's baked clips with a THREE.AnimationMixer
• Know where the loader and the asset cache live

What you'll build: A look at Littlest Tokyo — a GLTF diorama loaded and animated at runtime.

Walkthrough — Load and play a GLTF model · generated by site/media/lessons/tierc-batch.lesson.ts (4 steps)

Littlest Tokyo is a GLTF diorama with baked animation. The example loads it through vgai’s shared loader — one GLTFLoader on one LoadingManager, with DRACO decompression wired in — then plays its clips with a plain THREE.AnimationMixer.

Steps

1. Open a scene with a GLTF model. Load examples/scenes/littlest-tokyo.vscn.json.

   

   A GLTF diorama, ready to load at runtime.

2. Enter play mode — the shared gltfLoader loads the model. The example loads the model through the engine’s shared loader, so DRACO meshes are handled for you. Note the path is a plain relative URL — the shared LoadingManager rewrites it with the asset prefix, so loaders don’t need resolveUrl (that helper is only for raw fetch() calls):

   // littlest-tokyo loads the model directly for mixer access
   import { gltfLoader } from '@engine/loader';
   gltfLoader.load('examples/models/LittlestTokyo.glb', (result) => {
     // result.scene, result.animations
   });

   

   The GLTF, decoded and added to the scene.

3. A THREE.AnimationMixer plays the model clips. The baked clips ride along in the GLTF; the example drives them with a mixer (no AnimGraph needed for a fixed-playback asset):

   const mixer = new THREE.AnimationMixer(tokyoModel);
   for (const clip of gltf.animations) mixer.clipAction(clip).play();
   // ...ticked each frame: mixer.update(dt)

   

   The mixer plays every baked clip.

4. Stop play mode. Press Stop (or Escape).

Three ways a model gets loaded

This example calls gltfLoader directly because it wants the raw result for mixer access. The engine also has two URL-keyed dedup layers on top of the same shared LoadingManager: the scene loader caches GLTF for mesh defs via loadGLTF (scene/asset-loaders.ts), and gameplay code gets createAssetCache() exposed as ctx.assets (assets.ts, create-runtime.ts). Same loader underneath; different entry points.

Recap

New functionality

• Loaded a GLTF model at runtime
• Played its baked clips with a THREE.AnimationMixer

New concepts & skills

• One shared GLTFLoader + LoadingManager (DRACO-enabled) handles model loading
• The LoadingManager rewrites loader URLs with the asset prefix; resolveUrl is only for raw fetch()
• Two dedup layers sit on top: the scene loader's loadGLTF cache, and ctx.assets (createAssetCache) for gameplay

Next lesson → Manual: assets & loading

On Your Own!

Extend what you built:

• Open loader.ts and find where DRACO is attached to the GLTFLoader
• Read createAssetCache() and trace how a repeated URL returns the cached promise
• Adjust the animation-speed slider and watch mixer.timeScale change

See also

• Assets & loading · Technical Artist pathway