glTF animation
Play the skeletal animations in a glTF model - load clips by index or name, spawn the model, and start its AnimationPlayer once the model is ready.
On this page
A glTF file (.glb or .gltf) can hold meshes, a skeleton and animations together. The engine loads its animations as AnimationClip assets, and when you spawn the model, it adds an AnimationPlayer on the model's animation root and the target components on each bone. You build a graph from the clips, attach it to that player, and play.
glTF loading and glTF animation are both on in NEO's builds.
The usual pattern#
- Load the clips you want and build a graph.
- Spawn the model's scene with
WorldAssetRoot. - When the model is ready, find its
AnimationPlayer, give it the graph and play.
use neo::{prelude::*, world_serialization::WorldInstanceReady};
const FOX: &str = "models/animated/Fox.glb";
#[derive(Component)]
struct PlayOnReady {
graph: Handle<AnimationGraph>,
node: AnimationNodeIndex,
}
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.add_systems(Startup, setup)
.run();
}
fn setup(mut commands: Commands, assets: Res<AssetServer>, mut graphs: ResMut<Assets<AnimationGraph>>) {
// 1. the third animation in the file, as a one-clip graph
let (graph, node) = AnimationGraph::from_clip(assets.load(GltfAssetLabel::Animation(2).from_asset(FOX)));
// 2. the model; 3. an observer that runs when it has spawned
commands
.spawn((
PlayOnReady { graph: graphs.add(graph), node },
WorldAssetRoot(assets.load(GltfAssetLabel::Scene(0).from_asset(FOX))),
))
.observe(play_when_ready);
commands.spawn((Camera3d::default(), Transform::from_xyz(100.0, 100.0, 150.0).looking_at(Vec3::new(0.0, 20.0, 0.0), Vec3::Y)));
commands.spawn((DirectionalLight::default(), Transform::from_xyz(1.0, 2.0, 1.0).looking_at(Vec3::ZERO, Vec3::Y)));
}
fn play_when_ready(
ready: On<WorldInstanceReady>,
mut commands: Commands,
children: Query<&Children>,
to_play: Query<&PlayOnReady>,
mut players: Query<&mut AnimationPlayer>,
) {
let Ok(to_play) = to_play.get(ready.entity) else { return };
for child in children.iter_descendants(ready.entity) {
if let Ok(mut player) = players.get_mut(child) {
player.play(to_play.node).repeat();
commands.entity(child).insert(AnimationGraphHandle(to_play.graph.clone()));
}
}
}The AnimationPlayer is on an entity inside the spawned model, not on the entity you spawned, which is why the observer searches the descendants. WorldInstanceReady is triggered on your entity once everything in the model exists.
Choosing clips#
| Way | How |
|---|---|
| By index | GltfAssetLabel::Animation(i).from_asset(path) loads the file's ith animation. This is the same as loading "path#Animation2". |
| By name | Load the whole file as a Handle<Gltf>. Once it's loaded, gltf.named_animations["Run"] is that clip's handle and gltf.animations lists them all. |
#[derive(Resource)]
struct Fox(Handle<Gltf>);
fn build_graph(
fox: Res<Fox>,
assets: Res<AssetServer>,
gltfs: Res<Assets<Gltf>>,
mut graphs: ResMut<Assets<AnimationGraph>>,
) {
if !assets.is_loaded_with_dependencies(&fox.0) {
return;
}
let fox = gltfs.get(&fox.0).unwrap();
let (graph, nodes) = AnimationGraph::from_clips([
fox.named_animations["Run"].clone(),
fox.named_animations["Walk"].clone(),
]);
let _graph = graphs.add(graph);
// keep `nodes` to play "Run" (nodes[0]) and "Walk" (nodes[1])
}Several models, one graph#
Every copy of a model gets its own AnimationPlayer, so twenty foxes can share one graph asset and still play at different times and speeds. Give each player the same AnimationGraphHandle.
Skinning#
A skinned mesh in a glTF file becomes a SkinnedMesh component: the joints (bone entities) and their inverse bind poses. Animation moves the joints' Transforms and the GPU deforms the mesh. You rarely touch SkinnedMesh yourself; the custom_skinned_mesh example builds one in code.
Morph targets and retargeting#
- glTF morph target animations play the same way; see Morph targets.
- Retargeting an animation onto a different skeleton isn't part of the engine's animation system. NEO's character stack retargets to other skeletons; see Gameplay kit.
Examples: cargo run --example animated_mesh, animated_mesh_control, animated_mesh_events and custom_skinned_mesh. For loading glTF files in general, see glTF.