Animations

--- name: animations description: "Use thisskill 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. Relatedskills :../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 textu