benimator 3.4.0

A sprite sheet animation plugin for Bevy
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

# Benimator

[![License](https://img.shields.io/badge/license-Unlicense%20OR%20MIT-green)](#License)
[![Crates.io](https://img.shields.io/crates/v/benimator)](https://crates.io/crates/benimator)
[![Docs](https://docs.rs/benimator/badge.svg)](https://docs.rs/benimator)
[![Bevy tracking](https://img.shields.io/badge/Bevy%20tracking-released%20version-lightblue)](https://github.com/bevyengine/bevy/blob/main/docs/plugins_guidelines.md#main-branch-tracking)
[![Build](https://img.shields.io/github/workflow/status/jcornaz/benimator/build)](https://github.com/jcornaz/benimator/actions/workflows/build.yml)

A sprite sheet animation plugin for [bevy](https://bevyengine.org)


## 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

```rust
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:

![Example result](docs/coin.gif)

*(Asset by [La Red Games](https://laredgames.itch.io/gems-coins-free) - CC0)*

For more details see the [documentation](https://docs.rs/benimator)


## Installation

Add to `Cargo.toml`:

```toml
benimator = "3"
```

## Cargo features

### 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` API to create animation from yaml files.

## MSRV

The minimum supported rust version is currently: `1.59`

**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

| bevy | benimator |
|------|-----------|
| 0.7  | 3         |
| 0.6  | 1, 2      |
| 0.5  | 0.1 - 0.3 |

*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](https://discord.com/invite/gMUk5Ph) 

## License

Licensed under either of

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

at your option.