Animation graphs and players
Play clips with AnimationPlayer through an AnimationGraph - pause, seek, speed and repeat - blend and layer clips with weights and masks, and cross-fade with AnimationTransitions.
Every clip plays through an AnimationGraph, an asset describing which clips can play and how their results combine. An AnimationPlayer component plays nodes of that graph: it keeps each playing node's time, speed, weight and repeat count.
Graphs#
A graph is a tree. Its root is graph.root. Nodes are:
| Node | Added with | What it does |
|---|---|---|
| Clip | add_clip(handle, weight, parent) | Plays one AnimationClip. |
| Blend | add_blend(weight, parent) | Blends its children by their weights, scaled by its own weight. |
| Additive blend | add_additive_blend(weight, parent) | Adds its children on top of what's already there, for layers such as breathing or a recoil. |
Each add_* returns the new node's AnimationNodeIndex. You play clips by that index.
let mut graph = AnimationGraph::new();
let idle = graph.add_clip(assets.load(GltfAssetLabel::Animation(0).from_asset("models/fox.glb")), 1.0, graph.root);
let blend = graph.add_blend(0.5, graph.root);
let walk = graph.add_clip(assets.load(GltfAssetLabel::Animation(1).from_asset("models/fox.glb")), 1.0, blend);
let run = graph.add_clip(assets.load(GltfAssetLabel::Animation(2).from_asset("models/fox.glb")), 1.0, blend);
let graph_handle = graphs.add(graph);Shortcuts: AnimationGraph::from_clip(handle) returns a one-clip graph and its node, and AnimationGraph::from_clips([..]) a graph with several clips under the root and their nodes.
Put AnimationGraphHandle(graph_handle) on the entity that has the AnimationPlayer.
Graph files#
Graphs can be saved and loaded as .animgraph.ron files: graph.save(&mut writer) writes one, and asset_server.load("graphs/fox.animgraph.ron") loads it, with clips referenced by asset path. The animation_graph example does both.
Playing#
AnimationPlayer method | What it does |
|---|---|
play(node) | Starts the node if it isn't playing, and returns its ActiveAnimation. |
start(node) | Starts it from the beginning, even if it's playing. |
stop(node), stop_all() | Stops one or every node. |
pause_all(), resume_all(), rewind_all() | All playing nodes at once. |
adjust_speeds(factor), seek_all_by(seconds) | Scales every node's speed, or moves every node's time. |
is_playing_animation(node), playing_animations() | What's playing. |
all_finished(), all_paused() | Whether every node has finished or is paused. |
animation(node), animation_mut(node) | One playing node's ActiveAnimation. |
An ActiveAnimation controls one node:
| Method | What it does |
|---|---|
repeat(), set_repeat(RepeatAnimation::Count(n)) | Loop forever, or n times. The default plays once (RepeatAnimation::Never). RepeatAnimation is in neo::animation. |
set_speed(s), speed() | Playback speed. Negative values play backwards. |
set_weight(w), weight() | How much this node counts in its blend. |
pause(), resume(), is_paused() | Pause just this node. |
seek_to(seconds), seek_time(), elapsed() | Jump in time, and read where it is. |
replay(), rewind() | Start again. |
is_finished(), completions(), just_completed() | Whether and how often it has finished. |
fn controls(keys: Res<ButtonInput<KeyCode>>, mut players: Query<&mut AnimationPlayer>) {
for mut player in &mut players {
let Some((&node, _)) = player.playing_animations().next() else { continue };
let anim = player.animation_mut(node).unwrap();
if keys.just_pressed(KeyCode::Space) {
if anim.is_paused() { anim.resume(); } else { anim.pause(); }
}
if keys.just_pressed(KeyCode::ArrowUp) {
let speed = anim.speed();
anim.set_speed(speed * 1.2);
}
}
}Blending#
When several nodes play, their results are mixed by weight. Change weights every frame to blend, for example from walk to run by speed:
fn blend_by_speed(speed: f32, walk: AnimationNodeIndex, run: AnimationNodeIndex, player: &mut AnimationPlayer) {
let t = (speed / 5.0).clamp(0.0, 1.0);
player.play(walk).repeat().set_weight(1.0 - t);
player.play(run).repeat().set_weight(t);
}Weights in the graph itself can also be changed, through graph.get_mut(node) on the asset.
Transitions#
To switch from one animation to another with a cross-fade, add AnimationTransitions next to the player and play through it:
use std::time::Duration;
fn switch(mut q: Query<(&mut AnimationPlayer, &mut AnimationTransitions)>, next: AnimationNodeIndex) {
for (mut player, mut transitions) in &mut q {
transitions.play(&mut player, next, Duration::from_millis(250)).repeat();
}
}The old animation's weight falls to zero over the duration, then it stops. Duration::ZERO switches instantly.
Masks#
Masks let part of a skeleton play something else, such as the upper body waving while the legs walk.
- Put targets into mask groups (0 to 63):
graph.add_target_to_mask_group(target_id, group). - Give a node a mask:
add_clip_with_mask(clip, mask, weight, parent)oradd_blend_with_mask. Bit N set means the node and its children don't animate group N.
The animation_masks example builds groups for a fox's legs, tail and head.
Examples: cargo run --example animated_mesh_control and animated_mesh. animation_graph and animation_masks need the neo_feathers cargo feature for their on-screen controls: cargo run --example animation_graph --features neo_feathers.