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.

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

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

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({
    key: 'appear', frames: 'sparkle', frameRate: 12,
    showOnStart: true,      // sprite.visible = true when anim starts (after delay)
    hideOnComplete: true,   // sprite.visible = false when anim completes
    showBeforeDelay: true   // show first frame immediately even during delay
});

// Random start frame -- each sprite begins on a different frame
this.anims.create({
    key: 'ambient', frames: 'fire', frameRate: 10, repeat: -1,
    randomFrame: true
});

// TimeScale -- per-sprite or global speed control
sprite.anims.timeScale = 2;                         // 2x speed
sprite.play({ key: 'walk', timeScale: 0.5 });       // half speed via config
this.anims.globalTimeScale = 0.5;                    // affects ALL animations

Staggered Playback

const enemies = this.add.group({ key: 'enemy', repeat: 9 });
this.anims.staggerPlay('walk', enemies.getChildren(), 100);
// Each sprite starts 100ms after the previous. Pass staggerFirst: false to skip delay on first.

JSON Export and Import

// Export all global animations to JSON
const data = this.anims.toJSON();

// Import animations from JSON (pass true to clear existing animations first)
this.anims.fromJSON(data);
this.anims.fromJSON(data, true);

// Check before creating to avoid duplicate warning
if (!this.anims.exists('walk')) {
    this.anims.create({ key: 'walk', frames: 'player_walk', frameRate: 12, repeat: -1 });
}

Modifying Animation Frames at Runtime

const anim = this.anims.get('walk');

// Add frames to the end
anim.addFrame(this.anims.generateFrameNumbers('player', { start: 8, end: 10 }));

// Insert frames at a specific index
anim.addFrameAt(this.anims.generateFrameNumbers('player', { frames: [5] }), 2);

// Remove a specific frame object
const frame = anim.frames[3];
anim.removeFrame(frame);

// Remove frame at index
anim.removeFrameAt(0);

Aseprite Support

this.load.aseprite('paladin', 'paladin.png', 'paladin.json');
// In create:
this.anims.createFromAseprite('paladin');               // all tags
this.anims.createFromAseprite('paladin', ['walk']);      // specific tags only
sprite.play('walk');                                     // play by tag name

Configuration Reference

AnimationConfig (used with

this.anims.create()

)

Property	Type	Default	Description
`key`	string	--	Unique identifier for the animation
`frames`	string or AnimationFrame[]	`[]`	Texture key string (uses all frames) or array of frame config objects
`sortFrames`	boolean	`true`	Numerically sort frames when using a string key
`defaultTextureKey`	string	`null`	Fallback texture key if not set per-frame
`frameRate`	number	`24`	Playback rate in frames per second (used if `duration` is null)
`duration`	number	`null`	Total animation length in ms (derives frameRate if set)
`skipMissedFrames`	boolean	`true`	Skip frames when lagging behind
`delay`	number	`0`	Delay before playback starts (ms)
`repeat`	number	`0`	Times to repeat after first play (-1 = infinite)
`repeatDelay`	number	`0`	Delay before each repeat (ms)
`yoyo`	boolean	`false`	Reverse back to start before repeating
`showBeforeDelay`	boolean	`false`	Show first frame immediately during delay period
`showOnStart`	boolean	`false`	Set visible=true when animation starts
`hideOnComplete`	boolean	`false`	Set visible=false when animation completes
`randomFrame`	boolean	`false`	Start from a random frame

PlayAnimationConfig (used with

sprite.play()

)

All AnimationConfig timing properties are available, plus:

Property	Type	Default	Description
`key`	string or Animation	--	Animation key or instance to play
`startFrame`	number	`0`	Frame index to begin playback from
`timeScale`	number	`1`	Speed multiplier for this playback

Values in PlayAnimationConfig override the animation definition for this specific playback instance.

Duration vs FrameRate Priority

If both
```
duration
```
and
```
frameRate
```
are null: defaults to 24 fps.
If only
```
duration
```
is set: frameRate is calculated as
```
totalFrames / (duration / 1000)
```
.
If
```
frameRate
```
is set (even if duration is also set): frameRate wins, and duration is derived as
```
(totalFrames / frameRate) * 1000
```
.

Events

Sprite Event Flow

```
animationstart
```
-- after delay expires, before first update
```
animationupdate
```
-- each frame change
```
animationrepeat
```
-- each repeat cycle
```
animationcomplete
```
-- natural end (finite repeat)
```
animationcomplete-{key}
```
-- same, with animation key appended

Stopped manually:

animationstop

fires instead of complete. Restarted mid-play:

animationrestart

fires.

All callbacks:

(animation, frame, gameObject, frameKey)

AnimationManager Events

Fire on

this.anims

addanimation

removeanimation

pauseall

resumeall

API Quick Reference

AnimationManager (

this.anims

)

Method	Description
`create(config)`	Create and register a global animation
`remove(key)`	Remove a global animation by key
`get(key)`	Get an Animation instance by key
`exists(key)`	Check if a key is already registered
`generateFrameNumbers(key, config)`	Generate frame array from a spritesheet
`generateFrameNames(key, config)`	Generate frame array from an atlas
`play(key, children)`	Play an animation on an array of Game Objects
`staggerPlay(key, children, stagger)`	Staggered play across multiple Game Objects
`pauseAll()` / `resumeAll()`	Pause/resume all animations globally
`addMix(animA, animB, delay)`	Set transition delay between two animations
`removeMix(animA, animB?)`	Remove a mix pairing
`getMix(animA, animB)`	Get the mix delay between two animations
`createFromAseprite(key, tags?, target?)`	Create animations from Aseprite JSON
`toJSON()`	Export all animations as JSON data
`fromJSON(data, clear?)`	Load animations from JSON data (pass `true` to clear existing first)

AnimationState (

sprite.anims

)

Method	Description
`play(key, ignoreIfPlaying?)`	Play an animation
`playReverse(key, ignoreIfPlaying?)`	Play an animation in reverse
`playAfterDelay(key, delay)`	Play after a delay in ms
`playAfterRepeat(key, repeatCount?)`	Play after current anim repeats N times
`chain(key)`	Queue animation(s) to play after current one
`stop()`	Stop immediately
`stopAfterDelay(delay)`	Stop after a delay in ms
`stopAfterRepeat(repeatCount?)`	Stop after N more repeats
`stopOnFrame(frame)`	Stop when a specific frame is reached
`pause(atFrame?)`	Pause playback
`resume(fromFrame?)`	Resume playback
`restart(includeDelay?, resetRepeats?)`	Restart from beginning
`reverse()`	Reverse direction mid-playback
`getName()`	Get the current animation key
`getFrameName()`	Get the current frame key
`getProgress()`	Get progress 0-1
`setProgress(value)`	Set progress 0-1
`setRepeat(value)`	Change repeat count during playback
`getTotalFrames()`	Get total frame count
`create(config)`	Create a local animation on this sprite
`exists(key)`	Check if a local animation exists
`get(key)`	Get a local animation by key

Key properties:

isPlaying

hasStarted

currentAnim

currentFrame

forward

inReverse

timeScale

Gotchas

Animations are global by default.
```
this.anims.create()
```
registers across all Scenes. Do not recreate in every Scene -- it logs a warning and returns the existing one.
repeat: -1
never fires
animationcomplete
. Use
```
stop()
```
to end infinite animations. Listen for
```
animationstop
```
instead.
frameRate
beats
duration
. If both are set, frameRate wins. Set only
```
duration
```
(leave frameRate null) to control total length.
Per-frame
duration
is additive. Added on top of base msPerFrame, not a replacement.
play()
stops the current animation (fires
```
animationstop
```
). Use
```
play(key, true)
```
to skip if already playing.
Mix delays only work with
play()
.
```
playAfterDelay
```
/
```
playAfterRepeat
```
bypass mixes.
Local animations override global. Same key on a sprite's local map takes priority.

Sprite shorthand methods.

sprite.play()

sprite.playReverse()

sprite.chain()

sprite.stop()

wrap

sprite.anims.*

Chained anims fire after stop too. Clear the queue with
```
sprite.anims.chain()
```
before stopping if unwanted.
generateFrameNumbers
end=-1 means last frame. The
```
__BASE
```
frame is excluded automatically.

Source File Map

File	Purpose
`src/animations/AnimationManager.js`	Global singleton -- create, remove, get, generateFrame*, mix, staggerPlay
`src/animations/Animation.js`	Animation definition -- frames, timing, yoyo, repeat logic
`src/animations/AnimationState.js`	Per-sprite component -- play, stop, pause, chain, events
`src/animations/AnimationFrame.js`	Single frame data -- textureKey, textureFrame, duration, progress
`src/animations/events/index.js`	All animation event constants
`src/animations/typedefs/Animation.js`	AnimationConfig typedef
`src/animations/typedefs/PlayAnimationConfig.js`	PlayAnimationConfig typedef
`src/animations/typedefs/GenerateFrameNumbers.js`	Config for generateFrameNumbers
`src/animations/typedefs/GenerateFrameNames.js`	Config for generateFrameNames

animations

NPX Install

Tags

SKILL.md Content

Phaser 4 -- Sprite Animations

Quick Start

Core Concepts

AnimationManager vs AnimationState

Local vs Global Animations

Common Patterns

Spritesheet Animation

Atlas Animation

String as Frames

Yoyo and Repeat

Chaining Animations

Playing in Reverse

Play Variants

Animation Mixing

Pause, Resume, and Stop

Animation Events

Frame-Level Callbacks via animationupdate

Per-Frame Duration

Visibility, Random Start, and TimeScale

Staggered Playback

JSON Export and Import

Modifying Animation Frames at Runtime

Aseprite Support

Configuration Reference

AnimationConfig (used with
`this.anims.create()`
)

PlayAnimationConfig (used with
`sprite.play()`
)

Duration vs FrameRate Priority

Events

Sprite Event Flow

AnimationManager Events

API Quick Reference

AnimationManager (
`this.anims`
)

AnimationState (
`sprite.anims`
)

Gotchas

Source File Map

animations

NPX Install

Tags

SKILL.md Content

Phaser 4 -- Sprite Animations

Quick Start

Core Concepts

AnimationManager vs AnimationState

Local vs Global Animations

Common Patterns

Spritesheet Animation

Atlas Animation

String as Frames

Yoyo and Repeat

Chaining Animations

Playing in Reverse

Play Variants

Animation Mixing

Pause, Resume, and Stop

Animation Events

Frame-Level Callbacks via animationupdate

Per-Frame Duration

Visibility, Random Start, and TimeScale

Staggered Playback

JSON Export and Import

Modifying Animation Frames at Runtime

Aseprite Support

Configuration Reference

AnimationConfig (used with this.anims.create())

PlayAnimationConfig (used with sprite.play())

Duration vs FrameRate Priority

Events

Sprite Event Flow

AnimationManager Events

API Quick Reference

AnimationManager (this.anims)

AnimationState (sprite.anims)

Gotchas

Source File Map

AnimationConfig (used with
`this.anims.create()`
)

PlayAnimationConfig (used with
`sprite.play()`
)

AnimationManager (
`this.anims`
)

AnimationState (
`sprite.anims`
)