NEOLearn

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.

Updated October 20, 2026

On this page

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:

NodeAdded withWhat it does
Clipadd_clip(handle, weight, parent)Plays one AnimationClip.
Blendadd_blend(weight, parent)Blends its children by their weights, scaled by its own weight.
Additive blendadd_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.

Rust
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 methodWhat 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:

MethodWhat 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.
Rust
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:

Rust
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:

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

  1. Put targets into mask groups (0 to 63): graph.add_target_to_mask_group(target_id, group).
  2. Give a node a mask: add_clip_with_mask(clip, mask, weight, parent) or add_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.

Next steps#