animations

What this skill does

# Phaser 4 -- Sprite Animations

> AnimationManager (global), AnimationState (per-sprite), creating animations from spritesheets and atlases, playing/pausing/chaining, animation events, frame callbacks.

**Related skills:** ../sprites-and-images/SKILL.md, ../loading-assets/SKILL.md

---

## Quick Start

```js
// In preload -- load a spritesheet
this.load.spritesheet('explosion', 'explosion.png', {
    frameWidth: 64,
    frameHeight: 64
});

// In create -- define a global animation
this.anims.create({
    key: 'explode',
    frames: this.anims.generateFrameNumbers('explosion', { start: 0, end: 11 }),
    frameRate: 24,
    repeat: 0
});

// Play it on a sprite
const sprite = this.add.sprite(400, 300, 'explosion');
sprite.play('explode');
```

---

## Core Concepts

### AnimationManager vs AnimationState

Phaser has two distinct animation objects:

| Aspect | AnimationManager | AnimationState |
|---|---|---|
| Access | `this.anims` (in a Scene) or `this.game.anims` | `sprite.anims` |
| Scope | Global -- shared across all scenes | Per-sprite instance |
| Purpose | Create/store animation definitions | Control playback on one Game Object |
| Class | `Phaser.Animations.AnimationManager` | `Phaser.Animations.AnimationState` |

The AnimationManager is a singleton owned by the Game. Animations registered there are available in every Scene. The AnimationState lives on each Sprite and handles playback for that specific object.

An `Animation` is a sequence of `AnimationFrame` objects plus timing data. Created via `this.anims.create(config)` (global) or `sprite.anims.create(config)` (local to one sprite).

### Local vs Global Animations

When `sprite.anims.play(key)` is called, it first checks for a local animation with that key, then falls back to the global AnimationManager. Use local for sprite-specific animations; use global when shared across sprites.

```js
// Global animation -- available to all sprites
this.anims.create({ key: 'walk', frames: 'player_walk', frameRate: 12, repeat: -1 });

// Local animation -- only on this sprite
sprite.anims.create({ key: 'walk', frames: 'npc_walk', frameRate: 10, repeat: -1 });

// This plays the LOCAL version because local takes priority
sprite.play('walk');
```

---

## Common Patterns

### Spritesheet Animation

Use `generateFrameNumbers` for spritesheets (numeric frame indices).

```js
this.load.spritesheet('dude', 'dude.png', { frameWidth: 32, frameHeight: 48 });

// All frames
this.anims.create({
    key: 'run',
    frames: this.anims.generateFrameNumbers('dude', { start: 0, end: 7 }),
    frameRate: 10,
    repeat: -1
});

// Custom frame sequence
this.anims.create({
    key: 'idle',
    frames: this.anims.generateFrameNumbers('dude', { frames: [0, 1, 2, 1] }),
    frameRate: 6,
    repeat: -1
});
```

`generateFrameNumbers` config:
- `start` (default `0`) -- first frame index
- `end` (default `-1`, meaning last frame) -- final frame index
- `first` -- a single frame to prepend before the range
- `frames` -- explicit array of frame indices (overrides start/end)

### Atlas Animation

Use `generateFrameNames` for texture atlases (string-based frame names).

```js
this.load.atlas('gems', 'gems.png', 'gems.json');

this.anims.create({
    key: 'ruby_sparkle',
    frames: this.anims.generateFrameNames('gems', {
        prefix: 'ruby_',
        start: 1,
        end: 6,
        zeroPad: 4   // produces ruby_0001 through ruby_0006
    }),
    frameRate: 12,
    repeat: -1
});
```

`generateFrameNames` config:
- `prefix` -- prepended to each frame number
- `suffix` -- appended after each frame number
- `start`, `end` -- numeric range
- `zeroPad` -- left-pad numbers to this length with zeros
- `frames` -- explicit array of frame numbers (overrides start/end)

If you call `generateFrameNames(key)` with no config, it returns all frames from the atlas.

### String as Frames

Pass a texture key string as `frames` to use all frames from that texture, sorted numerically by default. Set `sortFrames: false` to disable sorting.

```js
this.anims.create({ key: 'walk', frames: 'player_walk', frameRate: 12, repeat: -1 });
```

### Yoyo and Repeat

```js
this.anims.create({
    key: 'pulse',
    frames: this.anims.generateFrameNumbers('orb', { start: 0, end: 5 }),
    frameRate: 10,
    yoyo: true,       // plays forward then backward
    repeat: -1,       // -1 = forever
    repeatDelay: 500   // ms pause between each repeat cycle
});
```

When `yoyo` is true, the animation plays forward then reverses. The full cycle counts as one play.

### Chaining Animations

```js
sprite.play('attack');
sprite.chain('idle');                        // play idle after attack completes
sprite.chain(['fall', 'land', 'idle']);       // chain multiple
sprite.anims.chain();                        // clear the chain queue
```

Chaining is per-sprite. Chained animations start after `animationcomplete` or `animationstop`. An animation with `repeat: -1` never completes -- call `stop()` to trigger the chain.

### Playing in Reverse

```js
// Play an animation from last frame to first
sprite.playReverse('walk');

// Reverse direction mid-playback
sprite.anims.reverse();
```

`playReverse` sets `forward = false` and `inReverse = true`. The `reverse()` method toggles direction mid-playback.

### Play Variants

```js
sprite.play('walk', true);                   // ignoreIfPlaying = true
sprite.anims.playAfterDelay('walk', 1000);   // play after 1s delay
sprite.anims.playAfterRepeat('walk', 2);     // play after current anim repeats 2x
```

### Animation Mixing

Adds a transition delay between two specific animations, set globally on the AnimationManager.

```js
this.anims.addMix('idle', 'walk', 200);
this.anims.addMix('walk', 'idle', 300);

sprite.play('idle');
sprite.play('walk');   // 200ms mix delay applied automatically

this.anims.removeMix('idle', 'walk');   // remove specific pair
this.anims.removeMix('idle');           // remove all mixes for 'idle'
```

Mix delays only apply with `sprite.play()`, not `playAfterDelay` or `playAfterRepeat`.

### Pause, Resume, and Stop

```js
sprite.anims.pause();                 // pause per-sprite
sprite.anims.resume();                // resume per-sprite
this.anims.pauseAll();                // global pause
this.anims.resumeAll();               // global resume

sprite.anims.stop();                  // stop immediately
sprite.anims.stopAfterDelay(2000);    // stop after 2 seconds
sprite.anims.stopAfterRepeat(1);      // stop after 1 more repeat
sprite.anims.stopOnFrame(frame);      // stop when a specific frame is reached
```

All stop methods fire `animationstop` (not `animationcomplete`). Chained animations trigger after stop.

### Animation Events

```js
sprite.on('animationcomplete', (anim, frame, gameObject, frameKey) => {
    console.log('completed:', anim.key);
});

// Key-specific complete -- only fires for the named animation
sprite.on('animationcomplete-explode', (anim, frame, gameObject, frameKey) => {
    gameObject.destroy();
});
```

Available events: `animationstart`, `animationcomplete`, `animationcomplete-{key}`, `animationupdate`, `animationstop`, `animationrepeat`, `animationrestart`. All share the same callback signature: `(animation, frame, gameObject, frameKey)`.

### Frame-Level Callbacks via animationupdate

```js
sprite.on('animationupdate', (anim, frame, gameObject, frameKey) => {
    if (anim.key === 'attack' && frame.index === 4) {
        this.checkHit(gameObject);
    }
});
```

### Per-Frame Duration

Individual frames can have a `duration` (ms) that is added to the base msPerFrame.

```js
this.anims.create({
    key: 'combo',
    frames: [
        { key: 'fighter', frame: 'punch1', duration: 50 },
        { key: 'fighter', frame: 'kick', duration: 200 },   // hold longer
        { key: 'fighter', frame: 'recover', duration: 100 }
    ],
    frameRate: 24
});
```

### Visibility, Random Start, and TimeScale

```js
// Visibility control
this.anims.create({
    key: 'appear', frames: '