/animations

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

// 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.

// 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).

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).

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.

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

Yoyo and Repeat

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

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

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

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.

this.anims.addMix('idle', 'w