Byte Engine Docs

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:

StageReadsWrites
RoutesThe request, the graph, the player's playbackThe playback's states, phases, and weights
ResidencyThe pool, read onlyThe player's list of clips the pool lacks
SamplingEach weighted clip's packed words and its binding's track targetsOne pose for each weighted clip, in the thread's scratch; a single clip writes the player's active pose directly
BlendingThe scratch posesThe player's active pose
Root motionEach weighted clip's root chain, the root motion node and its ancestors, at the previous and current phaseThe step's root motion delta
Visual poseThe active pose, and during a transition the inertializerThe local pose, with the extracted root channels at rest
Global poseThe local pose and the skeleton's parentsOne 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 dataHeld once perHolds
GraphGraphStates, spaces, routes, and clip resource IDs. Players refer to it, never copy it.
Graph bindingGraph and canonical skeletonFor 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 poolPoolPacked clips in one arena.
Scratch posesThreadA 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:

  1. 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.
  2. 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

  1. 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.
  2. 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.
  3. A graph binds a state once. A player that enters a bound state resolves no track targets.
  4. 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.
  5. 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.
  6. Root motion samples the root chain only, never a whole pose.

Tests and benchmarks

GuardRules
players_advanced_together_match_each_player_advanced_alone1, 2
players_sharing_a_graph_play_as_each_would_alone2, 3
pool_evicts_the_least_recently_sampled_clip_to_admit_another1
packed_poses_match_the_resource_curves_they_were_packed_from5
The playback tests in animation/graph/runtime/player.rs6, and the playback rules of the reference
characters_* benchmarks3, 4, 6
active_pose, active_root_motion, and inertialized_transition benchmarksThe 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_graph

Compare 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.

On this page