Models & animation

Step 2 of the 3D track. Primitives from the previous step are great for a set, but you can't build a character out of boxes. Characters arrive as GLB — a file holding meshes, a skeleton and baked animation clips. In le.codes that's its own node kind: Model.

A fox moves into the yard: we'll load the model, work through its clips, multiply it without loading it again, and send it running in circles.

Loading a model

Model.load() returns a promise. And here's the first runtime quirk: there is no top-level await in a program — the bundle runs as an ordinary function. Wrap anything that loads in an async function and call it:

TypeScript
const scene = new Scene({ skybox: "#1b2233" })
scene.add(Light.sun({ direction: [-1, -2, 0.7], intensity: 90000, shadowsQuality: 2 }))
scene.add(Mesh.plane({ material: Material.lit({ color: "#2f4a35", roughness: 1 }), normal: [0, 1, 0], scale: 24, receiveShadows: true }))
scene.camera.position = [0, 0.9, 1.9]
scene.camera.lookAt([0, 0.2, 0])

const status = UIText("Loading the model…").style({ fontSize: 13, color: "#c7ccd6" })
const hud = UIWidget(status).style({ top: "comfort-top", left: 16, right: 16 })
scene.widgets(hud)
scene.open()

// The fox turns her head side to side: a per-frame behavior, so an aspect (the previous step's Spin)
class Sway extends Aspect<"sway"> {
  t = 0
  update(dt: number) { this.t += dt; this.node.eulerAngles = [0, Math.sin(this.t * 0.5) * 35, 0] }
}

// The bundle runs without top-level await — wrap loading in an async function
async function main() {
  const fox = await Model.load("https://le.codes/guide-assets/fox-anim.glb")
  fox.castShadows = true
  scene.add(fox.aspect(Sway))

  // What the file actually holds is the only source of truth about clips
  status.text = fox.anim.clips.map(c => `${c.name} — ${c.duration.toFixed(1)}s`).join("\n")
  fox.anim.playLoop("walk")
}
main()
  • Open the scene first, add the model later. The scene is already drawn while the file downloads — the view is empty but not black, and there's somewhere to write "Loading…". Do the same for any slow resource.
  • A model is a Node, just another kind: position, scale, eulerAngles, castShadows, events — all as on a mesh. The GLB's internal nodes hang under it as children, and model.traverse(node => …) walks them (look one up by node.name).
  • Check the scale — GLB units can be anything. A model arrives in whatever units it was exported in, and the multiplier is often baked into the file itself (our fox's root node already carries a scale of 0.01, which is why the code never touches scale at all). If a model is invisible after add, or fills half the screen, that's the first thing to look at: model.scale = 0.01 on top of an already-shrunk file gives you a speck a tenth of a millimeter across. Think in meters: a grown fox is about 70 cm at the shoulder.
  • The source is an asset path — asset("./fox.glb") — in a real project, or a plain https:// URL as here. The promise rejects on an HTTP error or a bad file; in production wrap it in try/catch and show something human.
Caution

A top-level await in main.ts compiles without an error but the program silently never runs: both the web runner and the desktop host execute the bundle as a function. Blank screen and a quiet console? Look for an await outside a function first.

Clips

Animations ship inside the GLB and live on model.anim — an Animator, already attached, nothing to create. clips is what's baked into the file. There are two verbs: playLoop() sets what the fox does when nothing else happens, and play() runs a clip once over that loop. Both take a name or an index:

TypeScript
const scene = new Scene({ skybox: "#1b2233" })
scene.add(Light.sun({ direction: [-1, -2, 0.7], intensity: 90000, shadowsQuality: 2 }))
scene.add(Mesh.plane({ material: Material.lit({ color: "#2f4a35", roughness: 1 }), normal: [0, 1, 0], scale: 24, receiveShadows: true }))
scene.camera.position = [0, 0.9, 1.9]
scene.camera.lookAt([0, 0.2, 0])

const label = UIText("…").style({ fontSize: 13, color: "#c7ccd6" })
const row = UIRow().style({ gap: 8 })
const hud = UIWidget(label, row).style({ top: "comfort-top", left: 16, right: 16, gap: 8 })
scene.widgets(hud)
scene.open()

async function main() {
  const fox = await Model.load("https://le.codes/guide-assets/fox-anim.glb")
  fox.castShadows = true
  scene.add(fox)

  // Build the chips from what's actually in the file, not from a list of names off the top of your head
  const chip = (name: string) =>
    UIButton(UIText(name).style({ color: "#fff", fontSize: 13, fontWeight: 700 }))
      .style({ bgColor: "#ffffff22", borderRadius: 999, px: 12, py: 7, $pressed: { opacity: 0.6 } })
      .onClick(() => { fox.anim.playLoop(name, { fade: 0.25 }); label.text = `loop: ${name}` })
  row.append(...fox.anim.clips.map(c => chip(c.name)))

  // The loop is what she does at rest; play() runs one walk over it and resolves at the clip's end
  fox.anim.playLoop("idle")
  label.text = "loop: idle · one walk on top…"
  const finished = await fox.anim.play("walk", { fadeIn: 0.2, fadeOut: 0.3 })
  if (finished) label.text = "walk finished → back to idle"
}
main()

The fox walks one cycle and settles back into idle — the await on play() was the whole "when it ends" logic. The chips are built straight from anim.clips: as many buttons as the file has clips.

  • A loop and one-shots — that's the whole model. playLoop(clip) is what the model shows when nothing else happens (idle, walk, run); setting another loop transitions to it. play(clip) plays a clip once over the loop and hands back to it at the end.
  • play() returns something to await: it resolves true when the clip reaches its end and false when something cut it short — a new play(), a playLoop(), stop(). There's no end-of-clip event to subscribe to; chain clips with await.
  • Transitions are opt-in, and the default is a cut. playLoop(next, { fade: 0.25 }) blends from whatever the model shows over a quarter of a second; play() takes fadeIn / fadeOut. anim.speed is the rate multiplier (0 pauses), anim.stop({ fade }) returns to the rest pose.
  • An unknown name only warns: playLoop("Runn") doesn't throw — it logs a warning and keeps the previous clip. Which is why anim.clips is the only source of truth: re-export the model with different names and code with hardcoded strings quietly stops animating. Playing by index (playLoop(0)) is safe from typos, but not from clips being reordered in the file.
  • Speed blends (idle → walk → run by speed), clips from separate files (Mixamo: one GLB per animation), upper-body layers and clip events are all the same anim — see Animator.

The HUD buttons are ordinary UIButtons from the UI track: a UIWidget over a scene behaves like any container, imperative append/setContent included.

Many instances

The second character is not a second Model.load. A loaded model can clone(): the copy reuses the already-decoded GLB (no refetch, no reparse) and gets its own animation state:

TypeScript
const scene = new Scene({ skybox: "#1b2233" })
scene.add(Light.sun({ direction: [-1, -2, 0.7], intensity: 90000, shadowsQuality: 2 }))
scene.add(Mesh.plane({ material: Material.lit({ color: "#2f4a35", roughness: 1 }), normal: [0, 1, 0], scale: 30, receiveShadows: true }))
scene.camera.position = [0, 1.8, 3.2]
scene.camera.lookAt([0, 0.2, 0])
const label = UIText("…").style({ fontSize: 13, color: "#c7ccd6" })
const hud = UIWidget(label).style({ top: "comfort-top", left: 16, right: 16 })
scene.widgets(hud)
scene.open()

async function main() {
  const template = await Model.load("https://le.codes/guide-assets/fox-anim.glb")
  const foxes = [template, ...Array.from({ length: 4 }, () => template.clone())]
  foxes.forEach((fox, i) => {
    const a = (i / foxes.length) * Mathf.TAU
    fox.position = [Math.cos(a) * 1.1, 0, Math.sin(a) * 1.1]
    fox.eulerAngles = [0, -a * RAD2DEG, 0]
    fox.castShadows = true
    scene.add(fox)
    // Every copy owns its animation state: its own clip and its own speed
    fox.anim.playLoop(i % 2 ? "walk" : "run")
    fox.anim.speed = 0.6 + i * 0.2
  })
  label.text = `${foxes.length} foxes, one load`
}
main()

Five foxes, one network request and one file decode. Clones inherit the original's transform as of the copy, then live their own lives — own position, own clip and own speed (different speeds are enough to keep them from marching in lockstep).

  • Do the same for a pool of enemies or projectiles: one load at start-up, clone() on demand. Calling Model.load again for the same URL is wasted work and a hitch exactly at spawn time.
  • RAD2DEG and Mathf.TAU are globals. Node angles are in degrees, trigonometry is in radians; convert right at the boundary.
  • To remove a node, node.destroy() — after that it's unusable. Often it's cheaper to hide it (visible = false) and reuse it.

The whole screen

Bring back the yard from step 1 and send three foxes around it: each with its own radius, speed and clip. The circle is an aspect, Circle: one class, three instances with their own settings, each computing its fox's position every frame and the heading from the same angle:

TypeScript
// The yard from step 1 plus foxes: one GLB load, three instances, each with its own animation.
const scene = new Scene({ skybox: "#1b2233" })
scene.add(Light.sun({ direction: [-1, -2, 0.7], intensity: 90000, shadowsQuality: 2 }))

const lit = (color: string, roughness = 1) => Material.lit({ color, roughness })
scene.add(Mesh.plane({ material: lit("#2f4a35"), normal: [0, 1, 0], scale: 30, receiveShadows: true }))

function Tree(x: number, z: number, height = 1.6) {
  const tree = new Node()
  tree.position = [x, 0, z]
  const crown = Geometry.cylinder({ radiusTop: 0, radiusBottom: 0.55, edges: 8, smooth: false })
    .scale(1, height, 1).translate(0, height / 2 + 0.6, 0)
  tree.add(
    Mesh.cylinder({ material: lit("#6b4a2b"), radius: 0.12, scale: [1, 0.7, 1], position: [0, 0.35, 0], castShadows: true }),
    Mesh.from(crown, { material: lit("#3d8b4f"), castShadows: true }),
  )
  return tree
}
scene.add(Tree(-1.9, -2.2, 2), Tree(1.9, -2.8, 1.6), Tree(-2, 1.8, 1.3), Tree(2, 1.4, 2.2))

scene.camera.position = [0, 3.2, 5.5]
scene.camera.lookAt([0, 0.3, 0])

const status = UIText("Loading foxes…").style({ fontSize: 13, color: "#c7ccd6" })
const hud = UIWidget(
  UIText("The yard").style({ fontSize: 22, fontWeight: 800, color: "#ffffff" }),
  status,
).style({ top: "comfort-top", left: 16, right: 16, gap: 2 })
scene.widgets(hud)
scene.open()

// A fox running a circle: radius and speed are the aspect's settings, the angle its state
class Circle extends Aspect<"circle"> {
  radius = 1
  speed = 0.5                                      // radians per second
  t = 0
  update(dt: number) {
    this.t += dt
    const a = this.t * this.speed
    this.node.position = [Math.cos(a) * this.radius, 0, Math.sin(a) * this.radius]
    this.node.eulerAngles = [0, -a * RAD2DEG, 0]
  }
}

async function main() {
  const template = await Model.load("https://le.codes/guide-assets/fox-anim.glb")

  // Each fox runs its own circle; clone() copies without loading again
  const walkers = [
    { model: template, radius: 1.2, speed: 0.5, clip: "walk" },
    { model: template.clone(), radius: 2, speed: 0.9, clip: "run" },
    { model: template.clone(), radius: 0.6, speed: 0.3, clip: "walk" },
  ]

  walkers.forEach(({ model, radius, speed, clip }, i) => {
    model.castShadows = true
    scene.add(model.aspect(Circle, { radius, speed }))
    model.anim.playLoop(clip)
    model.anim.speed = 0.9 + i * 0.2
  })

  status.text = `${walkers.length} foxes · clips: ${template.anim.clips.map(c => c.name).join(", ")}`
}
main()

Step speed and clip speed are matched by eye: anim.speed is tuned so the paws don't skate over the ground. That's normal hand-tuning for a fox on a circle; when a character needs the link, anim.rootMotion = true lets a travelling clip move the node itself — see Animator and Locomotion.

Moving a node by assigning position is fine right up until physics takes it over — which is what the next steps are about.

What you learned

  • Model.load(url | asset("./file.glb")) returns a promise; there's no top-level await, so wrap it in async function main().
  • Check a model's scale against the file: it's often already baked into the GLB's root node, and an extra scale makes the model invisible.
  • A Model is a Node: transform, scale into meters, castShadows, traverse over its internals.
  • model.anim is an Animator: clips, playLoop(name | index) for what the model does at rest, await play(name) for a clip once over it, { fade } for transitions, speed.
  • An unknown clip name only warns — build UI from anim.clips, not from hardcoded strings.
  • clone() is a cheap copy of a loaded model with its own animation state — that's how pools are built.
  • A behavior with settings is one aspect class and an instance per node: model.aspect(Circle, { radius, speed }).

Reference: Model · Animator · Node · Aspects · Host globals.

Next: Camera & picking — orbit the yard with a finger and hit things.