AnimationsSAFE

Phaser is a fun, free and fast 2D game framework for making HTML5 games for desktop and mobile web browsers, supporting Canvas and WebGL rendering.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: animations
description: "Use this skill when creating or controlling sprite animations in Phaser 4. Covers spritesheets, atlases, AnimationManager, AnimationState, play/stop/chain, frame callbacks, and animation events. Triggers on: sprite animation, spritesheet, play animation, animation frames."
---

# 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', 'w

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Animations](https://modelsatlas.com/skills/phaserjs/animations/badge.svg)](https://modelsatlas.com/skills/phaserjs/animations/)

Not your listing, or something out of date? Claim or update your listing.