README.md

# Bevy Sprite Animations

Easily manage complex 2D sprite animations

## Quick Start

- Add the `BanimatePluginGroup` to your app
- Load one or more animation sets (see below for defining animation sets in files)
- Spawn an entity with a `Sprite` and attach a `SpriteAnimation` and an `AnimationHandle`.

> Code examples have been moved to the examples folder - clone the source and see them in action!

## Types of Animation

### Simple Animations

- A single list of frames to loop through based on a set framerate. Ideal for low-overhead animation of simple entities like a flickering lamp sprite

### Sprite Animations

- Associate one or more named animations with a sprite-having entity
- Easily switch between looping and one-off animations by name
- Interrupt the current animation temporarily with an `AnimationOverride`

### Directional Animations

- Everything that a Sprite Animation does, but will automatically change between named animations based on the value of the associated `Directionality` component

### Child Animations

- Given an entity with a `Sprite` and a `ChildOf` relation, set the atlas index of the sprite based on the parent value

## Animation Sets

An animation set maps a name to a series of frames and a frame rate. A given animation has one frame rate for the whole
animation,
but different animations can have different frame rates (i.e. a "walk" animation could play at 100ms per frame,
and an "idle" animation could play at 250ms per frame, but you can not set the duration of an individual frame within
either animation).

An `AnimationSet` might contains many animations, and a given `AnimationSet` is likely to be attached to many entities.
As such,
animations use the `Asset` system to avoid passing around relatively large duplicate objects. Loaders are included
for `JSON` and `TOML`
data types, but only `JSON` is enabled by default. The loaders are not required, and so can therefore be disabled if
another method
of creating `AnimationSet` assets is desired.

### Defining animations with JSON

With the `json_loader` feature enabled, you can load an animation set from a file with a `.anim.json` suffix that looks
like this:

```json
{
  "idle": {
    "frames": [
      1,
      2,
      3
    ],
    "frame_time": 250
  },
  "shoot_right": {
    "frames": [
      34,
      34,
      34,
      35,
      36
    ],
    "frame_time": 100
  }
}
```

### Defining animations with TOML

With the `toml_loader` feature enabled, you can load an animation set from a file with a `.anim.toml` suffix that looks
like this:

```toml
[idle]
frames = [1, 2, 3]
frame_time = 250

[shoot_right]
frames = [34, 34, 34, 35, 36]
frame_time = 100
```

## Compatibility

| banimate version    | bevy version | tilemap version                          |
|---------------------|--------------|------------------------------------------|
| 0.11.0              | 0.16         | n/a                                      |
| 0.10.0              | 0.15         | n/a                                      |
| 0.9.x               | 0.14         | n/a                                      |
| 0.8.0               | 0.13         | n/a                                      |
| 0.7.0               | 0.12         | n/a                                      |
| 0.6.0-rc.1          | 0.11         | 55c15bfa43c7a9e2adef6b70007e92d699377454 |
| 0.5.x               | 0.10         | 0.10                                     |
| 0.5.x               | 0.10         | 0.10                                     |
| 0.2.x, 0.3.x, 0.4.x | 0.9          | 0.9                                      |
| 0.1.x               | 0.8          | 0.8                                      |