Bevy 2D animation

When to use

Load this when a 2D actor needs clip playback on a sprite entity. Pair with bevy-animation for the player and clip types. Pair with bevy-animation-graph when clips must blend.

ECS shape

• Components: Sprite (bevy::sprite) on the visible entity. AnimationPlayer and AnimationTargetId / AnimatedBy (bevy::animation) link a clip to that entity.
• Resources: clip assets are AnimationClip handles, not a global player.
• Systems: advance_animations and animate_targets are the engine systems named on the animation page. Gameplay code should not reimplement them.
• Schedule: those systems are engine-owned. Gameplay that reacts to a finished clip chains after them.

Playback choices

Scope

• Frame sheets use Sprite::from_atlas_image and TextureAtlas. Clip curves use animated_field! plus AnimatableCurve.
• A cutout limb is an entity with AnimationTargetId and AnimatedBy pointing at the entity that owns AnimationPlayer.

Examples

Atlas frame on a sprite. TextureAtlas.index is the cell.

fn spawn_sheet(
    mut commands: Commands,
    assets: Res<AssetServer>,
    mut layouts: ResMut<Assets<TextureAtlasLayout>>,
) {
    let layout = TextureAtlasLayout::from_grid(UVec2::splat(32), 4, 1, None, None);
    let layout = layouts.add(layout);
    let image = assets.load("actor.png");
    commands.spawn((
        Sprite::from_atlas_image(image, TextureAtlas { layout, index: 0 }),
        FrameClock {
            timer: Timer::from_seconds(0.12, TimerMode::Repeating),
            frames: 4,
        },
    ));
}

#[derive(Component)]
struct FrameClock {
    timer: Timer,
    frames: usize,
}

fn tick_frames(time: Res<Time>, mut sprites: Query<(&mut Sprite, &mut FrameClock)>) {
    for (mut sprite, mut clock) in &mut sprites {
        clock.timer.tick(time.delta());
        if clock.timer.just_finished() {
            if let Some(atlas) = sprite.texture_atlas.as_mut() {
                atlas.index = (atlas.index + 1) % clock.frames;
            }
        }
    }
}

Clip playback. The player stores an AnimationNodeIndex from the graph, not a raw clip handle.

use bevy::animation::animated_field;
use bevy::animation::{AnimatedBy, AnimationTargetId};

#[derive(Component)]
struct IdleNode(AnimationNodeIndex);

fn spawn_clip(
    mut commands: Commands,
    mut clips: ResMut<Assets<AnimationClip>>,
    mut graphs: ResMut<Assets<AnimationGraph>>,
) {
    let name = Name::new("actor");
    let target = AnimationTargetId::from_name(&name);
    let samples = UnevenSampleAutoCurve::new([
        (0.0, Vec3::ZERO),
        (0.4, Vec3::new(8.0, 0.0, 0.0)),
    ])
    .expect("two samples");
    let mut clip = AnimationClip::default();
    clip.add_curve_to_target(
        target,
        AnimatableCurve::new(animated_field!(Transform::translation), samples),
    );
    let clip_handle = clips.add(clip);
    let (graph, indices) = AnimationGraph::from_clips([clip_handle]);
    let idle = indices[0];
    let graph_handle = graphs.add(graph);
    let player = commands
        .spawn((
            name,
            Sprite::from_color(Color::WHITE, Vec2::splat(32.0)),
            AnimationPlayer::default(),
            AnimationGraphHandle(graph_handle),
            target,
            IdleNode(idle),
        ))
        .id();
    commands.entity(player).insert(AnimatedBy(player));
}

fn play_idle(mut actors: Query<(&mut AnimationPlayer, &IdleNode)>) {
    for (mut player, idle) in &mut actors {
        player.play(idle.0).repeat();
    }
}

fn cutout_id(root: &Name, limb: &Name) -> AnimationTargetId {
    AnimationTargetId::from_names([root, limb].into_iter())
}

Facing and frame ticks both write Sprite, so they share one chain.

fn face_keys(keys: Res<ButtonInput<KeyCode>>, mut sprites: Query<&mut Sprite>) {
    let left = keys.pressed(KeyCode::KeyA);
    let right = keys.pressed(KeyCode::KeyD);
    if !left && !right {
        return;
    }
    for mut sprite in &mut sprites {
        sprite.flip_x = left;
    }
}

#[derive(Component)]
struct SheetClock {
    timer: Timer,
    frames: usize,
}

fn advance_sheet(time: Res<Time>, mut sprites: Query<(&mut Sprite, &mut SheetClock)>) {
    for (mut sprite, mut clock) in &mut sprites {
        clock.timer.tick(time.delta());
        if clock.timer.just_finished() {
            if let Some(atlas) = sprite.texture_atlas.as_mut() {
                atlas.index = (atlas.index + 1) % clock.frames;
            }
        }
    }
}

pub struct SpriteAnimPlugin;

impl Plugin for SpriteAnimPlugin {
    fn build(&self, app: &mut App) {
        app.add_systems(Update, (face_keys, advance_sheet).chain());
    }
}

Expert Knowledge Delta

Target: Bevy 0.20+.

Core ECS types: Component, Resource, Query, Commands, Startup, Update, Fixed / FixedMain (bevy::time), .chain(), Plugin, DefaultPlugins, MinimalPlugins. Messages and observers are an ownership slot. See bevy-events-messaging for their APIs. Systems run in parallel unless .chain() orders the ones that conflict.

Who owns state

Borrow rule: two systems that both mutably query the same component must be ordered (.chain()) or split so only one writes. Unrelated systems stay parallel. That is the ECS page rule, not a guess at a system-set API.

Decision

Load references/ecs-ownership.md for the ownership table.

NEVER

• Do not pin /0.20.0/ in docs URLs. WHY: links stay on latest; the 0.20 target is stated once in prose.

• Do not mutably query the same component from two unordered systems. WHY: the schedule runs systems in parallel unless .chain() orders them.

• Do not invent a physics, navigation, networking, or XR crate here. WHY: this skill only names documented Bevy crates and modules.

• No sprite-frame type outside Sprite, TextureAtlas, and AnimationClip. WHY: those are the documented owners of a 2D frame and a sampled curve.

• No invented APIs or unnamed third-party crates as the chosen solver. WHY: Bevy code stays idiomatic ECS and uses only documented Bevy APIs.

Reference

The library pin on bevy-master stays 0.20.0. Permalinks stay unversioned.

Official Documentation

• Assets - Official asset catalog. No third-party crate was selected.
• Examples - Example tree on the latest branch.
• 2D examples - Sprite and atlas samples.
• Animation examples - AnimationPlayer, clips, and graphs.
• ECS - Component, systems, Query, Startup, Update, and .chain().
• Plugins - Plugin, DefaultPlugins, MinimalPlugins, and add_plugins.

Related Skills

Prerequisites

• bevy-master - Hub and schedules.
• bevy-ecs-composition - Components and systems.
• bevy-animation - AnimationPlayer and AnimationClip.

Complements

• bevy-animation-graph - Blend clips.

Downstream / consumers

• None yet.

Master

• bevy-master - Bevy router.