---
name: ferret-animation
description: Use for animation in Ferret: Animator and animation graphs (states, blend spaces, layers, transitions), montages, notifies, locomotionGraph, retargetGroup between skeletons, and buildPuppet to run a game before real models exist. Deterministic with the fixed step.
---

# Animation graphs

## When to use
Making a character animate, adding a one-shot action, moving clips between skeletons, or testing with a stand-in body.

## The model
An `Animator` plays a `GraphDef` on an entity: state machines, 1D/2D blend spaces driven by speed or direction, layers, `Montage`s for one-shot actions, and notifies at named times in a clip. The graph does **not** use Babylon's animation clock: poses are requested and applied each fixed step, so animation is deterministic with the world.

## Steps
1. Start from `locomotionGraph` (walk / run / jump) or write a `GraphDef` and check it with `validateGraphDef`.
2. Bind clips to a skeleton with `bindClips`; `retargetGroup` moves a clip from one skeleton to another.
3. No real model yet: `buildPuppet` makes a stand-in skinned character.
4. One-shots (attack, wave): a `Montage`; react to notifies for footsteps and hits.
5. Graphs can live in the level manifest (`animGraphs`) and be edited by commands (`anim.*`, `edit.anim.*`).

## Check afterwards
`anim.list`, `anim.graph`, `anim.play`, `anim.scrub` show the state; every transition target and initial state exists; a retargeted clip moves the bones.

## What usually goes wrong
- A transition to a removed state (the editor refuses removing a state still used).
- Clips whose bones the target body does not have: they are noted in the report, not errors; check the clip really moves something.
- Driving animation from `onUpdate` timing instead of the graph's own step.

## Files

- `reference/packages.md` — Characters, animation graphs, NPC navigation, interactables, zones and transformations.
- `reference/api-animation.md` — every export of `@ferret/animation` with signature and doc comment