Blend trees

A state doesn’t have to play a single clip — it can hold a blend tree that mixes several clips by a continuous parameter, so locomotion blends smoothly instead of snapping between states. Blend trees are evaluated by evaluateBlendTree (packages/engine/src/animation/blend-node.ts).

1D and 2D blend trees.

The three types

A BlendTreeDef has a type of 1D, 2D, or direct, a driving parameter (and parameterY for 2D), and children (each { clip, threshold, thresholdY?, weight? }).

1D

Interpolates between sorted child points along one parameter. With children at walk:1 and run:5, a speed of 3 yields weights [0.5, 0.5] — the two nearest points share weight by proximity.

2D

Uses two parameters (e.g. strafing locomotion). Each child sits at a (threshold, thresholdY) position; a child’s weight is proportional to 1 / distance from the (parameter, parameterY) sample point to that child, then normalized so all weights sum to 1. (It’s a deliberately simple inverse-distance scheme — distant children still receive a small share.)

direct

You set each child’s weight yourself — for cases where you want explicit manual control rather than parameter-driven interpolation.

See also

• The animation graph — where blend trees live (inside a state).
• Capstone: Third-person character — an idle/walk/run blend in a real build.