Crate benimator

A sprite-sheet animation plugin for bevy

Usage

1. Add the AnimationPlugin plugin

use benimator::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugin(AnimationPlugin::default()) // <-- Enable sprite-sheet animations
        .add_startup_system(spawn)
        // ...
        .run()
}

fn spawn() { /* ... */ }

2. 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
    ));

    commands
        .spawn_bundle(SpriteSheetBundle {
            // TODO: Configure the sprite sheet
            ..Default::default()
        })
        // Insert the asset handle of the animation
        .insert(animation_handle)
        // Start the animation immediately
        .insert(Play);
}

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.

Play/Pause

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:

SpriteSheetAnimation::from_frames(vec![
    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() {
    state.reset();
  }
}

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:

frames:
  - 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.

Modules

integration

Integration with third party crates

Structs

AnimationPlugin

Plugin to enable sprite-sheet animation

Frame

A single animation frame

Play

Components that indicates the animation is playing

PlaySpeedMultiplier

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

SpriteSheetAnimation

Asset that define an animation of TextureAtlasSprite

SpriteSheetAnimationState

Animation state component which is automatically inserted/removed

Enums

AnimationPostUpdateSystem

Labels of systems that run during the post-update stage