Benimator

A sprite sheet animation plugin for bevy

Features

• A SpriteSheetAnimation asset
• Automatic update indices of a TextureAtlasSprite
• Animation modes: once, repeat and ping_pong
• An animation is playing if, and only if, a Play component is present in the entity
  • Simply remove/insert the Play component to pause/resume an animation
• The animation can be defined from an index-range, or an arbitrary list of indices
• Each frame may have a different duration

Usage

fn main() {
  App::new()
    .add_plugins(DefaultPlugins)
    .add_plugin(AnimationPlugin::default()) // <-- Add the plugin
    .add_startup_system(spawn)
    .run();
}

fn spawn(
  mut commands: Commands,
  asset_server: Res<AssetServer>,
  mut textures: ResMut<Assets<TextureAtlas>>,
  mut animations: ResMut<Assets<SpriteSheetAnimation>>,
) {
  // Don't forget the camera ;-)
  commands.spawn_bundle(OrthographicCameraBundle::new_2d());

  // Create an animation
  // Here we use an index-range (from 0 to 4) where each frame has the same duration
  let animation_handle = animations.add(SpriteSheetAnimation::from_range(
    0..=4,
    Duration::from_millis(100),
  ));

  commands
          // Spawn a bevy sprite-sheet
          .spawn_bundle(SpriteSheetBundle {
            texture_atlas: textures.add(TextureAtlas::from_grid(asset_server.load("coin.png"), Vec2::new(16.0, 16.0), 5, 1)),
            transform: Transform::from_scale(Vec3::splat(10.0)),
            ..Default::default()
          })
          // Insert the asset handle of the animation
          .insert(animation_handle)
          // Start the animation immediately. Remove this component in order to pause the animation.
          .insert(Play);
}

Here is the result:

(Asset by La Red Games - CC0)

For more details see the documentation

Installation

Add the dependency to your project

cargo add benimator

Cargo features

• yaml deserialization from yaml asset files (also requires unstable-load-from-file)
• ron deserialization from ron asset files (also requires unstable-load-from-file)
• bevy-07 all integrations with bevy 0.7

Unstable features

Any API behind one of theses feature flags is unstable, should not be considered complete nor part of the public API. Breaking changes to that API may happen in minor releases

• unstable-load-from-file Load animation assets from yaml/ron files. It also requires either ron or yaml (or both) features.

MSRV

The minimum supported rust version is currently: 1.60

It may be increased to a newer stable version in a minor release. (but only if needed)

It will be increased to the latest stable version in a major release. (even if not needed)

Bevy Version Compatibility

Note: Only the latest published version of benimator is supported

Contribute / Contact

Discussions, issues and pull requests are welcome.

It is possible to directly discuss with me (Jomag#2675) via the bevy discord.

If you want to understand the "architecture" decisions made you may look at the doc/adr directory.

License

Licensed under either of

• The Unlicense (UNLICENSE or https://opensource.org/licenses/Unlicense)
• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.