Blend trees

A meta.animation 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) — the exact same function whether the caller is the XState animation binding or anything else, reused verbatim rather than reimplemented.

1D and 2D blend trees.

The three types

An AnimationBlendTree (meta.animation.blendTree, xstate-animation-meta.ts) 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

• XState animation binding — where blend trees live (inside a state’s meta.animation).
• Capstone: Third-person character — an idle/walk/run blend in a real build.