Animate a character
Play an animation graph on a skinned mesh, drive it from your gameplay state, and move the entity by its root motion.
Give a skinned renderable an animator, step the animation system once per tick, and each frame tell the animator which state your gameplay wants. The system samples, blends, and posts the pose. Your code keeps the decisions: which state to ask for, where the head looks, and where the root motion moves the entity.
This page shows the frame loop. The rules behind it, such as how routes resolve, what a request carries, and what a step posts, are in the animation reference.
Build the graph
Describe the states your character can be in and the routes between them once, at startup. A locomotion graph puts its walk loops in a space whose position is the direction and speed, with starts and stops as one-shots on the way in and out:
let graph = AnimationGraph::builder();
let standing = graph.planar_space("standing");
let idle = standing.state("idle").with(AnimationClip::looping("anims/idle.fbx#animation"));
let walk = standing.state("walk").planar(walk_ring());
idle.to(walk).with(start_ring()).exit(exit).anytime(blend);
walk.to(idle).with(stop_ring()).at_frames("walk_f", [4, 18]).anytime(settle);
let graph = graph.build(idle)?;To turn in place, play the turn clip once into an idle twin whose pose faces where the clip started, and say how far the clip turns the body. When the clip ends, its turn reaches your code as root-motion rotation, in the same frame the pose hands over:
idle.to(turned)
.with(AnimationClip::once("anims/turn_90.fbx#animation"))
.turning(90f32.to_radians())
.when(blend);Pass the angle the clip turns the body in its pose, about +Y.
Keep the state IDs it hands back; requests name states by ID. The graph itself goes to the animation system next.
Create the system, then the animators
The system steps every animator created on its world scope after it, so create it before the characters, as you do with physics. Give it the graph: the system owns it from then on and hands back the ID animators name it by:
let mut animation = byte_engine::application::graphics::setup_animation_system(&mut app);
let graph = animation.register(graph);
let character = app
.world()
.create(RenderableMesh::resource("MotusMan/MotusMan_v55.fbx"))
.with(Animator::new(graph).with_root_motion(RootMotionSettings {
node_name: "Hips",
translation: RootMotionTranslation::X.union(RootMotionTranslation::Z),
rotation: RootMotionRotation::None,
}))
.with(Transform::from_position(start))
.handle();Every character that plays the same graph gets its own Animator on the same
graph; the system shares the graph's bindings and clips between them.
Create the system before you start the application's loading thread. It creates
its own clip pool. Set animation.pool-bytes in your application parameters to
change the decoded clip budget from the default of 32 MiB; use a positive
number of bytes.
Drive it every tick
Keep the order below. The step posts the frame's pose and root motion before it returns, so the transform you write afterwards matches the pose on screen. Reading the root motion a tick later leaves the pose one frame ahead of the body.
let mut root_motion = app.world().channel::<RootMotionUpdate>().listener();
let mut playback: Option<RootMotionUpdate> = None;
while app.tick_with(|app, time| {
let world = app.world().clone();
controls.pull(time.delta());
// 1. Ask for the state gameplay wants. Requests persist, so asking every
// frame is fine, and a position moves the walk around its ring.
let state = playback.and_then(|update| update.state());
world.set(select_state(&controls, state)).on(character);
world.set(Some(LookTarget::new(view_yaw, view_pitch))).on(character);
// 2. Advance every animator. Poses reach the renderer here.
animation.step(time, app.alley_mut());
// 3. Move the entity by what the step extracted, in its own frame.
while let Some(update) = root_motion.read() {
if update.handle() == character {
playback = Some(update);
position += orientation.rotate_vector(update.delta().translation);
orientation = orientation.compose(update.delta().rotation);
}
}
world
.channel::<TransformationUpdate>()
.send(TransformationUpdate::new(character, Transform::new(position, Scale::identity(), orientation)));
// 4. Systems that read transforms step last.
physics.step(time, app.alley_mut());
})
.is_some()
{}If your application runs physics at a fixed step with tick_stepped_with,
step the animation system in the frame callback, since poses are drawn every
frame, and apply root motion there too. The fixed step then reads the
transform the last frame moved.
Decide from what's playing
Gameplay often needs to know what the animator is doing before it asks for the
next thing: which state plays, and whether a requested route still waits for
its wait point. Each step posts both in the animator's RootMotionUpdate, so
keep the latest one for your character until the next arrives:
if let Some(update) = playback {
if update.state().is_some_and(|state| catalog.is_turn(state)) {
// Keep asking for the idle; the turn plays through and hands over.
}
if update.waiting_for() == Some(jump_landing) {
// The jump waits for the stride to fit; do not replace the request.
}
}To let one idle request choose the earliest fitted stop, author several routes
to that idle with matching_frames(). Each route lists the source clips its
stop fits. The graph checks the playing blend's clips and chooses the route
whose next fitted frame comes first:
walk.to(idle)
.matching_frames()
.at_frames("walk.animation", [5, 20])
.with(AnimationClip::once("stop-left.animation"))
.anytime(blend);
walk.to(idle)
.matching_frames()
.at_frames("walk.animation", [12, 28])
.with(AnimationClip::once("stop-right.animation"))
.anytime(blend);Request idle when movement stops. The graph keeps the blend position, waits for the fitted frame, plays the chosen stop, and enters idle, so your code doesn't track feet. Clips that no alternative fits, such as a blend's idle center, don't restrict the choice. Equal wait times keep authoring order.
A one-shot built with when plays to its end whatever you request next, so a
jump or a turn needs one request to start and none to protect it. Routes built
with anytime cut short on the next request, which suits starts and stops.
Turn the head
Give the animator a look chain and send it a target in the entity's object space each frame. The system clamps the yaw around the hips, eases it, and turns the chain on top of the pose:
Animator::new(graph).with_look_chain(LookChainSettings {
nodes: &[("Spine2", 0.2), ("Neck", 0.3), ("Head", 0.5)],
body_node: "Hips",
yaw_limit: 70f32.to_radians(),
up_limit: 30f32.to_radians(),
down_limit: 40f32.to_radians(),
response: Some(8.0),
})The target is in the entity's object space, so when your code turns the
entity, say by how much with turned_by, and the chain holds its direction in
the world. Turns that arrive as root motion, like a turn in place, need no
turned_by: the chain already holds its direction across them. Send None to
let the chain follow the animation again.