Animations

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:

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

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

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

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.

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

// Visibility control
this.anims.create({