Animation system
Read this before you change animation playback, to learn how one frame's data flows through a player, what players share, how a crowd spreads over lanes, and what a change must keep.
Read this note before you change animation playback: the graph player, the clip
pool, packed clips, or how players advance together. Its behavior is specified
in the animation reference. This note explains how
playback is built and why, states the rules a change must keep, and names the
tests and benchmarks that guard them. The code lives in
crates/byte-engine/src/animation.
The animation system the reference specifies lives in animation/system.rs:
AnimationSystem adopts the Animator values created on its world scope,
applies the requests and look targets sent to their handles, advances their
players together with AnimationPool::advance_players, and posts each pose and
root motion. The evaluation it drives is below it: graph players, a clip pool
they share, and the lanes the players spread over.
The system owns the graphs it plays: AnimationSystem::register takes a graph
and returns the AnimationGraphId animators name it by. A player keeps only
its graph's ID. Whoever owns the graph lends it to every call that evaluates,
advance and advance_players, and to time_until_route, and the player
checks that it's the graph it was created with. Systems and players have no
lifetime and share nothing. A player's playback state never holds part of the
graph either: a playing motion reads its clips from the graph's binding by
state, and a pending route names its wait and entry points by where the graph
keeps them. Keep it that way: a reference counted handle in per-frame playback
state made crowds that switch states slower, because players on several lanes
start the same state in one frame.
How a frame flows
The typical frame is a character walking: a planar blend of locomotion clips keyed at 30 frames per second, with root motion. Each stage reads and writes these:
| Stage | Reads | Writes |
|---|---|---|
| Routes | The request, the graph, the player's playback | The playback's states, phases, and weights |
| Residency | The pool, read only | The player's list of clips the pool lacks |
| Sampling | Each weighted clip's packed words and its binding's track targets | One pose for each weighted clip, in the thread's scratch; a single clip writes the player's active pose directly |
| Blending | The scratch poses | The player's active pose |
| Root motion | Each weighted clip's root chain, the root motion node and its ancestors, at the previous and current phase | The step's root motion delta |
| Visual pose | The active pose, and during a transition the inertializer | The local pose, with the extracted root channels at rest |
| Global pose | The local pose and the skeleton's parents | One affine transform for each node, the form rendering stores |
On an Apple M4 in October 2026, with 64-node skeletons, sampling a 31-key clip took about 0.35 µs, blending three poses 0.27 µs, building the global pose 0.4 µs, and sampling one clip's root chain 0.03 µs. A walking character took about 1.8 µs, and sampling was most of it, so that's where a change most likely pays.
Packed clips
A pose samples every track of a clip at one time, so the packed layout serves that access:
- Timelines. Curves keyed at the same times share one timeline, so a pose searches each timeline's keys once instead of each curve's. Clips baked from FBX key every curve at the same frames, so they have one timeline.
- Rows. A timeline stores its values key by key, with every curve's value at a key side by side. A sample reads two rows of adjacent words, the keys before and after the time.
- Track targets. A clip's binding maps each track to the canonical node it writes, and each canonical node to the track that writes it. A pose samples straight into the canonical pose, and root motion samples only the chain's nodes.
A pose places up to 16 timelines on the stack before it samples. A clip with more, such as a glTF clip with keys of its own on every channel, places each curve's time as it reads the curve, the way every curve did before timelines.
What players share
Many characters play one graph, so everything that doesn't depend on one character's playback is shared:
| Shared data | Held once per | Holds |
|---|---|---|
| Graph | Graph | States, spaces, routes, and clip resource IDs. Players refer to it, never copy it. |
| Graph binding | Graph and canonical skeleton | For every state, its clips' track targets, durations, and frame rates. The graph owns it. The first player takes the canonical skeleton from the initial clip, and a state binds the first time any player enters it with its clips resident. |
| Clip pool | Pool | Packed clips in one arena. |
| Scratch poses | Thread | A blend's per-clip poses and a hand-over's spans: poses a frame fills and reads, which no player keeps between frames. Lanes are persistent threads, so each lane's scratch lasts across steps. |
A player keeps only what lasts from one frame to the next: its playback, whose weights fit inline because a blend weighs at most three clips; its pending route; one blend position for each space of its graph; the active and destination poses with their previous samples; the posted local pose and the one before it; the global pose; its inertializer; and its root chain. Nothing grows after the player's first frames.
How a crowd advances
AnimationPool::advance_players advances every player by one delta toward its
latest request:
- Evaluate. Players only read the pool while they evaluate. A residency check reads the clip map, sampling reads the arena, and the least-recently-used stamp is an atomic counter that only a step's first use of a clip writes. A clip a player needs but the pool doesn't hold goes on that player's list. Crowds of at least 32 players spread over the alley's lanes in balanced shares, one lane for each 16 players.
- Request. Once no player reads the pool, the pool requests every listed clip, which queues loads and can admit or evict clips. Each lane reports whether its share listed anything, so a step with nothing to request doesn't visit the players again.
Each player decides its routes and samples its pose in one pass, because both read only its own state and data that every player shares. That keeps a player's data in one core's cache for the whole frame. The only state players used to change in common was the pool, through requests and leases, so requests moved after evaluation and leases went away. The borrow checker now keeps any eviction from running while a player samples.
Why crowds stay on the fastest cores
A step waits for its slowest lane, and balanced shares give every lane the same work. On the M4, which has 4 performance and 6 efficiency cores, 1,024 walking characters took 0.60 ms on 4 lanes, 0.72 ms on 6, 0.58 ms on 8, and 0.62 ms on 10. Lanes on efficiency cores fall behind and hold the step up, so a step uses at most as many lanes as the fastest cores have hardware threads, as physics does. Spreading work so that faster lanes take more, rather than balanced shares, is what would let the efficiency cores help.
Rules a change must keep
- Evaluation only reads the pool, the graph, and the binding. Whatever changes the pool, a request, an admission, or an eviction, runs before or after evaluation, never during it.
- A player's pose, root motion, and state depend only on its own requests and the step deltas. They don't depend on the lane count, the order players are evaluated in, or the other players.
- A graph binds a state once. A player that enters a bound state resolves no track targets.
- Nothing allocates in a step for a player that has played a frame, except the transforms a pose update owns. Weights live inline and scratch belongs to the thread.
- Sampling a packed clip gives the same values as sampling the resource curves it was packed from. Curves share a timeline only when their key times match bit for bit.
- Root motion samples the root chain only, never a whole pose.
Tests and benchmarks
| Guard | Rules |
|---|---|
players_advanced_together_match_each_player_advanced_alone | 1, 2 |
players_sharing_a_graph_play_as_each_would_alone | 2, 3 |
pool_evicts_the_least_recently_sampled_clip_to_admit_another | 1 |
packed_poses_match_the_resource_curves_they_were_packed_from | 5 |
The playback tests in animation/graph/runtime/player.rs | 6, and the playback rules of the reference |
characters_* benchmarks | 3, 4, 6 |
active_pose, active_root_motion, and inertialized_transition benchmarks | The cost of one player by skeleton size |
The characters_* benchmarks time one frame of 1, 64, and 1,024 characters
with 64-node skeletons that share one graph and clip pool, advanced together on
an alley. The locomotion case steers through a planar blend of five clips keyed
at 30 frames per second, with root motion, the typical frame above. The root
motion case plays one looping clip, the transitioning case keeps every
character inside an inertialized transition, and the switching case enters a
state on every frame. Each character starts at its own phase, so characters
don't sample in lockstep.
Run the tests, then the benchmarks before and after your change:
cargo nextest run -p byte-engine -E 'test(/animation/)'
cargo bench -p byte-engine --bench animation_graphCompare builds run by run: keep each build's benchmark binary and run them in turns, because other load on the machine shifts results from one run to the next.