Drive an animation blend tree

quick start Beginner ⏱ 6 min vgai 0.1.0

Prerequisites: Installed vgai and run the editor

What you'll learn

• See an AnimGraph blend tree mix idle → walk → run by speed
• Recognize how gameplay drives animation via setParameter
• Know where the blend graph and the anim system live

What you'll build: A look at the third-person character — its locomotion blend driven by a speed parameter.

Walkthrough — Drive an animation blend tree · generated by site/media/lessons/tierc-batch.lesson.ts (4 steps)

The third-person character animates through an AnimGraph — a blend tree whose output is mixed from a few inputs (speed, grounded) the gameplay code sets each frame. You never play clips by hand; you set parameters and the graph blends.

Steps

1. Open a scene with an animated character. Load examples/scenes/third-person.vscn.json.

   

   A character whose locomotion is driven by an AnimGraph.

2. Enter play mode — the AnimGraph drives the character. The anim system advances the graph each frame in the animation phase. At rest, speed is ~0, so the blend tree outputs the idle pose.

   

   speed ≈ 0 → the blend tree outputs idle.

3. Drive with W — the blend tree mixes idle → walk → run by speed. The character controller computes a horizontal speed and pushes it into the graph:

   // third-person/components.ts — gameplay drives animation, not the reverse
   const graph = ctx.animGraphs.get(this.object3D);
   graph?.setParameter('speed', horizontalSpeed * ANIM_SPEED_SCALE);
   graph?.setParameter('grounded', nowGrounded);

   As speed rises the 1-D blend node crossfades idle → walk → run. No clip names appear in the gameplay code.

   

   Higher speed → the blend tree shifts toward run.

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

Where this lives

The graph and its blend nodes are packages/engine/src/animation/anim-graph.ts and blend-node.ts; the system that ticks every graph in the animation phase is anim-system.ts. See the Animation manual for the full model.

Recap

New functionality

• Watched an AnimGraph blend idle → walk → run
• Saw gameplay drive animation via setParameter

New concepts & skills

• A blend tree mixes clips from parameters — you set values, not clips
• The anim system advances each graph in the animation phase
• speed and grounded are the inputs the third-person controller writes each frame

Next lesson → Manual: the AnimGraph

On Your Own!

Extend what you built:

• Open anim-graph.ts and find where the speed parameter selects the blend
• Trigger the jump state by jumping (the controller calls graph.trigger('jump'))
• Change ANIM_SPEED_SCALE and observe the walk→run threshold shift

See also

• The AnimGraph · Third-person capstone