Expand description

A sprite-sheet animation plugin for bevy


  1. Add the AnimationPlugin plugin
use std::time::Duration;
use bevy::prelude::*;
use benimator::*;

fn main() {
        .add_plugin(AnimationPlugin::default()) // <-- Enable sprite-sheet animations
        // ...

fn spawn() { /* ... */ }
  1. Create a SpriteSheetAnimation and insert the asset handle to the sprite sheet entity you want to animate

fn spawn(mut commands: Commands, mut animations: ResMut<Assets<SpriteSheetAnimation>>) {

    // Create an animation
    let animation_handle = animations.add(SpriteSheetAnimation::from_range(
        0..=2,                               // Indices of the sprite atlas
        Duration::from_secs_f64(1.0 / 12.0), // Duration of each frame

        .spawn_bundle(SpriteSheetBundle {
            // TODO: Configure the sprite sheet
        // Insert the asset handle of the animation
        // Start the animation immediately

Run the animation only once

By default the animation loops forever. But it is possible to configure it differently:

SpriteSheetAnimation::from_range(0..=2, Duration::from_millis(100))
     .once(); // <-- Runs the animation only once

Note that, for animations that run once, the Play component is automatically removed when the animation is done. So you can use the RemovedComponents<Play> system parameter to execute logic at the end of the animation.


Animations proceed only if the Play component is present in the entity.

To pause or resume an animation, simply remove/insert the Play component.

Fine-grained frame-duration

For a more precise configuration, it is possible to define the duration of each frame:

    Frame::new(0, Duration::from_millis(120)),
    Frame::new(1, Duration::from_millis(100)),
    Frame::new(2, Duration::from_millis(80)),

Reset animation

For each entity with a SpriteSheetAnimation, a SpriteSheetAnimationState component is automatically inserted. It can be used to reset the animation state by calling SpriteSheetAnimationState::reset

fn restart_anim_from_start(mut query: Query<&mut SpriteSheetAnimationState>) {
  for mut state in query.iter_mut() {

Load animation from file (Unstable)

By enabling the cargo feature: unstable-load-from-file you can write the animation in an asset file.

First, create an asset file with the extension .animation.yml:

mode: PingPong
frame_duration: 100  # duration of the frame in milliseconds
frames: [0, 1, 2]  # Sequence of frame index

You can specify different duration on each frame if you need to:

  - index: 0
    duration: 100
  - index: 1
    duration: 200

And then load it with bevy’s AssetServer:

let handle: Handle<SpriteSheetAnimation> = asset_server.load("player_run.animation.yml");

It is also possible to use ron instead of yaml.

For more info on the format see: SpriteSheetAnimation::from_yaml_str and SpriteSheetAnimation::from_ron_str.


Plugin to enable sprite-sheet animation

A single animation frame

Components that indicates the animation is playing

Component that, when applied, can change the playback’s rate of the animation.

Asset that define an animation of TextureAtlasSprite

Animation state component which is automatically inserted/removed


Labels of systems that run during the post-update stage