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:
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, andmodel.traverse(node => …)walks them (look one up bynode.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
scaleof 0.01, which is why the code never touches scale at all). If a model is invisible afteradd, or fills half the screen, that's the first thing to look at:model.scale = 0.01on 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 plainhttps://URL as here. The promise rejects on an HTTP error or a bad file; in production wrap it intry/catchand show something human.
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:
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 toawait: it resolvestruewhen the clip reaches its end andfalsewhen something cut it short — a newplay(), aplayLoop(),stop(). There's no end-of-clip event to subscribe to; chain clips withawait.- 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()takesfadeIn/fadeOut.anim.speedis the rate multiplier (0pauses),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 whyanim.clipsis 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:
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. CallingModel.loadagain for the same URL is wasted work and a hitch exactly at spawn time. RAD2DEGandMathf.TAUare 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:
// 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-levelawait, so wrap it inasync function main().- Check a model's scale against the file: it's often already baked into the GLB's root node, and an extra
scalemakes the model invisible. - A
Modelis aNode: transform,scaleinto meters,castShadows,traverseover its internals. model.animis anAnimator: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.