Byte Engine Docs

Animation

Look up the skeleton, clip, pose, and sampling model, the blend and inertialization rules, root motion, the animation graph and its spaces, animators and their updates and data stream, the look chain, the clip pool, and flipbooks.

Animation turns clips baked from glTF, GLB, and FBX files into poses that the renderer skins with. This page specifies the data model, how a clip is sampled and blended, what the animation graph guarantees, how animators play graphs and post their updates, and the limits of the clip pool. To author the source files, follow Author assets; the importer rules are in the asset formats reference.

Skeletons and clips

A skeleton is a list of nodes in parent-before-child order. Each node has an optional name, an optional parent index, and a rest local transform. A local transform is a translation in the parent's space, a rotation, and a scale; the identity transform has zero translation, identity rotation, and unit scale.

A clip holds:

FieldValue
nameOptional.
skeletonThe skeleton the clip was authored for.
durationSeconds. Finite and zero or more.
frame_rateOptional. Frames per second when the source format records one; glTF records none. Finite and positive when present.
tracksOne track per animated node, in strictly ascending node order. A track has at least one of a translation curve, a rotation curve, and a scale curve.

A curve is one of three kinds: step, linear, or cubic spline with in and out tangents. A rotation curve's tangents are quaternion derivatives. Every curve has the same number of times and values, at least one key, times in [0, duration] that strictly increase, and finite values; a cubic curve has one tangent pair per key.

Sampling

Sampling a clip at a time in seconds produces a local pose for every node of the skeleton:

RuleBehavior
Missing curveThe node keeps its rest local value for that channel.
Before the first keyThe first key's value.
After the last keyThe last key's value.
Step curveThe value of the last key at or before the time.
Linear curveTranslation and scale interpolate linearly. Rotation uses normalized linear interpolation along the shorter arc.
Cubic curveHermite interpolation with tangents scaled by the span between the two keys. A span of zero length yields the lower key.
LoopingNot part of sampling. The animation graph loops by phase.

A global pose is the list of matrices for every node, where a node's global matrix is its parent's global matrix times its local matrix, and a local matrix applies scale, then rotation, then translation.

A pose map remaps a clip onto another skeleton by node name. Target nodes with no source keep the target's rest pose. Mapped target nodes start from the source rest pose. When several source nodes map to one target, the last one wins.

Blending

OperationRule
Two posesThe factor clamps to [0, 1]. Translation and scale interpolate linearly; rotation uses normalized linear interpolation.
Several posesWeights must be finite and zero or more, and at least one must be positive. They normalize by their sum. Rotations flip to the hemisphere of the first positively weighted pose before mixing.
1D blend spaceAt least one position, finite and strictly ascending. A value interpolates linearly between its two neighbors and clamps to the end samples outside the range.
2D blend spaceAt least three positions and one non-degenerate triangle. A value takes the barycentric weights of the first triangle that contains it; outside every triangle, the closest point on any triangle edge or vertex. Weights clamp to [0, 1] and renormalize.

Inertialization

An inertializer carries the pose that was on screen into a new destination without a visible discontinuity. It starts from a source pose and its previous frame, a destination pose and its previous frame, the sample delta between those frames, and a duration.

RuleBehavior
Sample deltaFinite and positive.
DurationFinite and zero or more. A zero duration applies the destination at once.
At the startThe output equals the source pose.
At the endThe output equals the destination exactly, with zero velocity and acceleration.
OffsetSettles along a quintic curve that leaves the source without acceleration.
Velocity differenceDecays so that one thousandth remains at the end of the duration.
RotationOffsets are rotation vectors composed onto the destination rotation.

Root motion

Root motion is the movement of one named node, taken out of the visual pose so that the owning object moves instead. A root motion delta is a translation and a rotation; deltas compose by adding translations and composing rotations, and blend by linear and normalized linear interpolation. Scale is never part of root motion.

SettingValue
NodeBy name. The name must exist exactly once in the skeleton.
TranslationAny subset of the X, Y, and Z axes, or none.
RotationNone or full.

The delta is measured between the node's previous and current sampled poses, with the unselected channels replaced by the node's rest values, in object space. When a looping clip wraps, the delta covers the remainder to the clip's end, any whole loops, and the start to the current time. In a blend, each positively weighted clip contributes its own delta, mixed as a weighted mean. In a transition, the source and destination deltas blend by the transition factor. The visual pose keeps the rest values on the extracted channels.

A step in which a one-shot hands over to its target with a hand-over turn rotates by the turn at the hand-over moment, whatever the rotation setting: the delta's rotation composes the motion before the hand-over, the turn, and the motion after it. The motion after the hand-over is in the turned frame, so its translation rotates by the turn before it adds.

Animation graph

A graph is a state machine built in code. Its states can be grouped into spaces that share one blend position. Any number of animators can play one graph, and each keeps its own playback.

States

StateHoldsPlayback
ClipOne clip, looping or played once.
Round robinOne or more clips, in order.Plays one clip at a time, as a clip state. Each time the animator enters the state, it plays the next clip, starting with the first and wrapping after the last.
Linear blendClips at scalar positions, as a 1D blend space.Its space's position picks the weights.
Planar blendClips at 2D positions, as a 2D blend space with explicit or fan triangulation.Its space's position picks the weights.

Every clip in a blend or a round robin shares one playback mode. A blend's duration is the weighted sum of its clips' durations, so all its clips share one phase.

Each animator keeps its own turn for each round robin, so animators that play one graph don't advance each other's turns. Entering a round robin takes a turn whether the animator enters it through a route, a hand-over, or a redirect. A blend position never changes which clip a round robin plays, and a route point on a round robin names one of its clips, as on a blend.

Spaces

A space is a named group of states that share one blend position. A linear space's position is a scalar; a planar space's position is a 2D point.

RuleBehavior
MembershipA state belongs to at most one space. A clip state may belong to one. A blend state always belongs to one: a blend state built outside a space forms a space of its own, named after the state, that holds only it.
KindEvery blend state of a linear space is a linear blend, and every blend state of a planar space is a planar blend.
SamplesEach blend state of a space has its own clips and positions. Two blends of one space need not share positions or a clip count.
PositionEach animator keeps one position for each space. A request for a state of the space that carries a position sets it. Before any request sets it, the position is the origin.
WeightsA blend weighs its clips at its space's position every step, whether it loops or plays once, until a blend played once finishes and holds its last pose.
NestingA space can't hold another space.
Other spacesA space's position never changes the weights of another space's blends.

Routes

A route leads from a source state to a target state.

RouteBehavior
Direct, taken when the source settlesWaits until the source has reached its wait point, or its end for a clip played once, then inertializes into the target over the route's duration. A zero duration switches at once.
Direct, taken anytimeAlso cuts short a blend into the source or a one-shot leading to it.
Through a one-shot clipPlays a clip once between source and target, then inertializes into the target over the exit duration. The one-shot either must complete or may be interrupted, as Routes resolve describes.
Through a one-shot blendPlays a blend of clips once between source and target, like a one-shot clip. The blend belongs to the target's space, or to the source's when the target belongs to no space or to a space of the other kind. It weighs its clips at that space's position and follows the position while it plays, so a start re-aimed by a new request heads where the request points.
From a spaceA route every state of a space can take, considered after the state's own routes.
From any stateA route every state can take, considered after the state's own routes and its space's routes.

A route through a one-shot can carry a hand-over turn: an angle in radians about +Y, by the right-hand rule. It suits a one-shot that turns the body in its pose into a target whose pose faces where the one-shot started, like a turn in place into an idle. When the one-shot completes and hands over to its target, the entity takes over the turn through root motion, so the pose and the entity together keep the body where the one-shot left it. A one-shot cut short by another route hands over no turn.

A route through a one-shot plays a state of its own, named after the route's source and target, as in Walk -> Stop. The second one-shot between the same source and target, in the order the graph is built, is named Walk -> Stop 2; each later one takes the next number.

A wait point is a frame on the source clip, frames on one or more clips of a blend, or a time. When a route names frames on several clips of a blend, it waits for the frames of the named clip that weighs the most; between clips of equal weight, the first named wins. Frames count at the clip's authored frame rate; a clip without a frame rate never reaches a frame point. A route can also enter the target at a frame instead of its start. When it names frames on several clips of a blend, the named clip that weighs the most where the target starts picks the frame, by the same rule.

Routes resolve in this order. A persistent state ignores a request for itself, then takes the first of its own routes to the requested state, then its space's routes, then any-state routes. A one-shot takes its own routes first. While a one-shot that may be interrupted plays, a request other than its completion may take the anytime routes of the completion state or its space, or any-state routes. While a one-shot that must complete plays, such a request may take only any-state routes; otherwise the request holds and the one-shot plays to its end. Once a one-shot finishes, it takes its completion route, and the request that held resolves from the completion state. A blend in progress can only be redirected along anytime routes, of its destination state or that state's space, and any-state routes, and never toward a one-shot.

A route can be a fitted alternative: one of several routes from a state to the same destination, each fitting the source clips it names wait frames in. When the first route from the state to the requested destination is a fitted alternative, the alternatives compete:

RuleBehavior
EligibilityAn alternative is eligible when it fits every source clip that contributes more than 0.001 weight and that any alternative fits. Clips that no alternative fits don't restrict the choice.
ChoiceThe eligible alternative whose next wait frame comes first wins. Equal times keep the order the graph is built in.
Blending inWhile the source blends in, fitted alternatives wait for it to settle instead of falling back to a route from its space.
One-shotsWhile a one-shot plays, a request resolved from its completion state's alternatives takes the first one without waiting, since their frames name moments of a state that isn't playing.

Building a graph

Building validates the graph and reports the first problem:

ErrorCause
InitialStateOutOfRange, TransitionSourceOutOfRange, TransitionTargetOutOfRange, TransitionStateCompletionOutOfRangeA state index names no state.
EmptyStateName, DuplicateStateNameA state has no name, or two share one.
EmptySpaceName, DuplicateSpaceNameA space has no name, or two share one.
EmptyResourceIdA clip has no resource ID.
TransitionStateMustPlayOnceA one-shot transition clip, or a clip of a one-shot transition blend, loops.
NegativeTransitionDurationA route or exit duration is negative.
InvalidBlend, MixedBlendPlaybackA blend space is invalid, or the clips of a blend or a round robin mix looping and once.
EmptyRoundRobinA round robin has no clips.
SpaceKindMismatchA blend state's kind differs from its space's.
BlendOutsideSpaceA one-shot transition blend's source and target belong to no space of its kind.
RoutePointClipMissing, RoutePointNeedsClipA wait or entry point names a clip its state lacks, or a point on a blend names no clip.

Animators

An animator plays one graph for one entity. The animation system steps every animator of the world scope it's created on, and posts each animator's pose and root motion to the world.

Creating and removing

An animator is created through the world's animator factory under the handle of the entity it poses, usually a skinned renderable.

FieldValue
GraphThe graph to play. Any number of animators can play one graph.
Root motionOptional. The settings in Root motion.
Look chainOptional. The settings in Look chain.
RuleBehavior
SystemThe application creates one animation system on a world scope, with the clip pool it plays from, and steps it once per frame from its own tick. The system belongs to the animators of that scope.
AdoptionThe system adopts animators created after the system, at the start of its next step. It never adopts one created before it.
ReplacementAn animator created again under the same handle replaces the previous one and starts over at its graph's initial state.
RemovalA deletion of the handle removes the animator at the start of the next step. Nothing more is posted for that handle.
Canonical skeletonThe skeleton of the first clip of the graph's initial state. Every animator of a graph shares it. Every clip an animator samples maps onto it, and the root motion and look chain node names resolve against it once it's resident.
RejectionAn animator whose settings don't resolve against the canonical skeleton is rejected. The system reports the error and posts nothing for the handle.

Requests

A request is a targeted message on an animator's handle. It names a state and whether a position change is inertialized. A request for a blend state can also carry a position of its space's kind.

RuleBehavior
Latest winsA step applies the last request posted for each handle since the previous step.
PersistenceA request holds until another replaces it. Before its first request, an animator plays its graph's initial state.
Other graphA request for a state of another graph is discarded and reported as StateFromDifferentGraph. The previous request holds.
No animatorA request for a handle without an animator is discarded.

Playback

Each step advances every animator by the step's delta toward its latest request, through the routes of its graph.

RuleBehavior
PhaseAdvances by the delta divided by the clip's duration. A looping clip wraps; a clip played once stops at its end. A clip of zero duration stays at its start.
Clips sampled per stepAt most three per motion: the triangle of a planar blend, the pair of a linear blend, or one clip, which for a round robin is the clip of its current turn. Only positive weights are sampled.
TransitionThe destination is sampled at its start phase, both motions advance, and the inertializer carries the pose until the route's duration elapses.
Hand-over at a wait point or a one-shot's endThe time left in the step plays on the next state in the same step.
RedirectA blend in progress can be redirected along an anytime route once the animator has posted a pose, from the pose and velocity it posted last.
Position change on a blendAn inertialized request blends the playing blend from its current weights to the new ones, from the pose posted last. A blend played once blends this way while it has at least the request's duration left to play, and moves its weights at once otherwise, so its end is never held back by the blend. A request without a position leaves every blend's weights as they are. While a blend to a new position plays, later requests move only the position it heads to; the weights it left stay until it ends, so its root motion ramps across the blend.
PrefetchEntering a state requests the clips of every state its own routes and its space's routes can reach. A round robin needs all its clips resident before the animator enters it.
Initial clip not residentThe animator posts nothing.
Other clip not residentThe animator holds and posts its previous pose, with an identity root motion delta.

Stepping

The system steps once per frame, with the frame's delta. A step adopts new animators and removes deleted ones; applies the latest requests and look targets; admits the clips that finished loading; then evaluates every animator: it takes its routes, phases, and hand-overs for the delta, samples, blends, and inertializes its pose, extracts its root motion, applies its look chain, builds its global pose, and posts its updates. Evaluation only reads the clip pool, so an animator that needs a clip the pool doesn't hold lists it, and once every animator is evaluated, the pool requests the listed clips.

RuleBehavior
LanesA step spreads its animators over the alley's lanes in balanced shares: one lane for each 16 animators, and never more lanes than the processor's fastest cores have hardware threads. Fewer than 32 animators stay on the calling thread.
Missing clipsThe pool requests a clip that an animator needs but the pool lacks after the step, so the next step is the earliest that can play it.
IndependenceAn animator's pose, root motion, and state don't depend on the lane count or on the other animators, whatever graphs they play.
CompletionEvery update of a step is posted before the step returns.
OrderAnimators post in no particular order.

Updates

Every step posts two updates for every animator whose initial clip is resident.

UpdateRouteCarries
Pose updateThe world's pose route, in headed builds only.The global transform of every canonical skeleton node, in node order, after the look chain: an affine matrix of three rows and four columns, scale applied first, then rotation, then translation.
Root motion updateThe world's root motion route.The step's root motion delta, in the entity's object space, and the state playing after the step. An animator without root motion settings carries the identity delta.

The system never moves an entity: applying root motion to a transform is up to the code that owns the entity.

RuleBehavior
Same tickA step posts its updates before it returns, so code that steps the system and then reads the root motion route in the same tick moves the entity by the delta of the pose that frame draws. Reading the route a tick later shows the pose one frame ahead of the transform.
Order of a tickPost requests and look targets, step the system, apply the root motion updates to transforms, then step the systems that read transforms, such as physics.
Fixed-step simulationThe system steps with the frame, since poses are drawn every frame; a fixed-step physics then reads the transform root motion last moved at its next step.

Queries

Between steps, the system answers these for each animator, as of the last step:

QueryAnswer
Playing stateThe state playing, or none before the initial clip is resident.
Waiting forThe requested state whose route waits for the playing state to reach one of its wait points, or none. A new request cancels the wait.
Time until a routeHow long the playing state plays on before its route to a given state starts: zero for a route that doesn't wait, and the time to the nearest wait point for one that does. None when the playing state has no route to that state, a one-shot has played past every wait point, the animator is blending, or the initial clip isn't resident.

The system answers them through the animator's player, which it lends out between steps; the queries are the player's.

Data stream

An animator given a debug data stream (DDS) writes one record to it each time it advances, after the advance, with stream set to animation. An animator without a stream writes nothing. Times in data are seconds. A clip is named by its resource ID's file name, without its directory or extension; when the ID's fragment picks a clip by name or index, as in #animations/Walk, a # and that name or index follow, as in character#Walk.

FieldTypeMeaning
statusloading, ready, or rejectedWhether the animator waits for its initial clip, plays, or never plays because it was rejected.
errorString or nullWhy the animator was rejected; null otherwise.
missingArray of stringsThe clips the advance needed but the pool didn't hold, by resource ID. The pool requests them.
requestRequestThe latest request.
motionMotion or nullThe state playing, or the state a blend moves to. Null until the initial clip plays.
transitionTransition or nullThe blend in progress; null when one state plays alone.
pendingPending or nullA route the animator selected but hasn't started; null when there's none.
root_motionRoot motionThe motion the advance extracted for the entity to apply.
lookLook or nullWhat the look chain measured and turned in the advance; null without a look chain or while it's released.

A request:

FieldTypeMeaning
stateStringThe requested state's name.
positionNull, number, or array of two numbersThe requested blend position: null for none, a number on a line, or a point on a plane.
inertializationNumberHow long the request blends to its position; zero changes the weights at once.

A motion:

FieldTypeMeaning
stateStringThe state's name.
playbackloop or onceWhether the state's clips repeat or hold their last pose.
phaseNumberProgress through the clips, from 0 at their start to 1 at their end.
timeNumberThe phase in seconds: the phase times the duration.
durationNumberOne cycle: the clips' durations weighed by how much each plays.
clipsArray of clip weightsThe clips that contribute to the pose, at most three. Their weights sum to one.

A clip weight:

FieldTypeMeaning
clipStringThe clip's resource ID.
weightNumberHow much the clip contributes, above 0 and at most 1.

A transition:

FieldTypeMeaning
fromMotionThe state the blend leaves, which keeps playing until the blend ends.
routeRouteWhy the blend started.
elapsedNumberHow far the blend has progressed.
durationNumberHow long the blend takes.

A pending route:

FieldTypeMeaning
requestedStringThe state the application requested.
targetStringThe state the route enters first, which is requested or a one-shot state on the way to it.
blendNumber or nullHow long the route blends from the playing state; null starts the target with nothing to blend from.
routeRouteWhere the route came from.
waitWait or nullThe moment of the playing state the route waits for; null when the route doesn't wait for one, which starts it as soon as its target's clips load.

A route:

FieldTypeMeaning
kindstate, space, any-state, completion, position, or initialWhich list the route came from: the routes of a state, of a space, or of every state; a one-shot's completion; a position change of the playing blend, which takes no route; or the start of the initial state.
ownerString or nullThe state or space whose routes held it, or the one-shot that completes. A one-shot that takes its completion state's routes names that state. Null for any-state, position, and initial.

A wait:

FieldTypeMeaning
clipStringThe named clip whose wait points the route follows: the one that weighs the most, as Routes specifies.
weightNumberThat clip's weight in the playing state, which is 0 for a clip that doesn't play.
pointPoint or nullThe wait point of that clip the playing state reaches next; null when it reaches none, like a one-shot past all of them. A point is {"frame": n} or {"seconds": s}, as authored.
starts_inNumber or nullHow long the playing state plays before it reaches point; null with it.

Root motion:

FieldTypeMeaning
translationArray of three numbersThe translation, in the skeleton root's parent space.
rotationArray of four numbersThe rotation quaternion, as x, y, z, w.

A look, in radians about +Y in the entity's object space:

FieldTypeMeaning
targetNumberThe target's yaw the advance looked toward, after any hand-over turn.
bodyNumberThe body node's animated yaw.
endNumberThe end node's animated yaw before the chain turns it.
clampedNumberThe target's yaw clamped around body.
easedNumberThe eased yaw the chain looks along.
turnNumberHow far the chain turns the end node: eased minus end.

The key, which changes-only streams compare, is status, missing, the request's state, the motion's state and clips, the transition's from state and route, and the pending route's requested, target, route, and wait clip. Phases, times, the request's position, a blend's elapsed, the wait's point and starts_in, root motion, and the look aren't part of it.

Look chain

A look chain turns a chain of nodes toward a direction on top of the graph's pose, before the global pose is built.

SettingValue
NodesOne or more node names with a share each, from the chain's base to its end. Each name must exist exactly once in the canonical skeleton, and each node must descend from the node before it.
SharesFinite and positive. They normalize by their sum.
Body nodeA node name that must exist exactly once. Its animated yaw centers the yaw limit.
Yaw limitRadians, from 0 to π.
Up and down limitsRadians, from 0 to π/2 each.
ResponsePer second, finite and positive, or none for no easing.

A look target is a targeted message on an animator's handle with a yaw and a pitch in the entity's object space, or none to release the chain. The latest target holds until another replaces it; before the first one, the chain is released.

RuleBehavior
AnglesYaw turns about +Y and pitch about +X, by the right-hand rule, in object space. The object faces -Z, so a positive pitch looks up. A turn pitches first, then yaws.
Animated yawFor a node, the angle about +Y from -Z to -Z turned by the node's object-space rotation times the inverse of its rest object-space rotation, projected onto the XZ plane.
ClampingThe target yaw clamps to within the yaw limit of the body node's animated yaw, and the target pitch to the up and down limits.
Unreachable yawA target yaw beyond the limit clamps toward the side the eased yaw already lies on when that side is more than half the limit from the body node's yaw, and toward the target's own side otherwise, so a target passing behind the body doesn't swing the chain across.
EasingThe eased yaw and pitch start at the clamped target. Each step, they move the fraction 1 − e^(−response × delta) of the way to it, yaw along the shorter way around. Without a response, they equal the clamped target.
TurnThe chain turns by the eased yaw minus the end node's animated yaw, and by the eased pitch.
DistributionThe turn is one rotation, the pitch then the yaw. Each node, from base to end, turns by its share of that rotation's angle about its axis, in object space after its animated object-space rotation, so the shares compose to the whole turn at the end node. Its descendants turn with it.
Entity turnA target may say how far the application turned the entity about +Y since the last step. The eased yaw turns the other way by that much before it eases, so the chain holds its direction in the world. The turn applies to one step. Turns the step's root motion carries aren't part of it.
Hand-over turnA step whose one-shot hands over with a hand-over turn turns the eased yaw and the target's yaw the other way by the turn, before the chain eases, so the chain holds its direction in the world once the entity applies the step's root motion. The target stays turned until another replaces it.
StepsThe chain turns once a step, on the step's last pose, after any hand-over within it.
ReleaseThe chain stops turning at once. The next target starts the easing over.
Root motionThe look chain never changes the root motion delta.

Errors

ErrorCauseResult
RootMotionNodeNotFound, DuplicateRootMotionNodeNameThe root motion node name is absent or ambiguous.The animator is rejected.
LookNodeNotFound, DuplicateLookNodeNameA look chain or body node name is absent or ambiguous.The animator is rejected.
LookChainOutOfOrderA look chain node doesn't descend from the node before it.The animator is rejected.
InvalidLookChainThe chain is empty, or a share, limit, or response is out of range.The animator is rejected.
StateFromDifferentGraphA request names a state of another graph.The request is discarded.

Clip pool

The animation system owns one pool, and every animator samples clips from it. The pool keeps packed clips in one arena sized by a byte budget that the application chooses, and loads clips on a worker.

Request resultMeaning
ReadyThe clip is resident.
LoadingThe load is queued or in flight.
WaitingForCapacityThe load queue holds 64 requests, or no room could be made. Request again later.
FailedThe load failed or the clip is larger than the whole budget.

The pool admits loaded clips and evicts clips only before and after animators are evaluated, never while they sample. When a clip doesn't fit, the pool evicts the clips whose last sampling step is the oldest first; clips that one step sampled are equally recent. Up to 64 loaded clips can wait for room; further ones are dropped. The pool reports LoadFailed, Oversized, and Evicted events, keeping the latest 64.

Flipbooks

A flipbook selects one image of a sequence by elapsed time. It needs at least one image and a positive frame rate. The frame index is the floor of the elapsed time times the frame rate, wrapped to the image count, so playback loops and a negative time wraps backward. Selection is stateless: the caller owns the clock, and skipped updates don't slow playback. The file format is in the asset formats reference.

Limits

LimitValue
Clip loads in flight, pool events kept, clips waiting for room64 each
Clips sampled per step per motion3
Remembered blend positionsOne per space per animator
Requests and look targets applied per stepThe last of each per animator
AnimatorsNo fixed limit
Animators for each lane a step adds16
Blend space samplesAt least 1 for 1D, at least 3 for 2D
Skeleton nodes, clips, states, spacesNo fixed limit; node indices are 32-bit
Engine time resolution28,224,000 ticks per second

Rust API

On this page