sprites-and-images

Sprites and Images

Creating and manipulating Sprite and Image game objects in Phaser 4 -- factory methods, texture/frame selection, the component mixin system, and common visual operations (position, scale, rotation, tint, flip, alpha, origin, depth).

Key source paths: src/gameobjects/sprite/, src/gameobjects/image/, src/gameobjects/GameObject.js, src/gameobjects/components/ Related skills: ../loading-assets/SKILL.md, ../animations/SKILL.md, ../physics-arcade/SKILL.md, ../game-object-components/SKILL.md

Quick Start

// In a Scene's create() method:

// Static image (no animation support, slightly cheaper)
const bg = this.add.image(400, 300, 'background');

// Sprite (supports animations)
const player = this.add.sprite(100, 200, 'player', 'idle-0');

// Common operations -- all methods return `this` for chaining
player.setPosition(200, 300);
player.setScale(2);
player.setAngle(45);
player.setTint(0xff0000);
player.setAlpha(0.8);
player.setOrigin(0, 1);       // bottom-left
player.setDepth(10);
player.setFlip(true, false);  // flip horizontally
player.setVisible(false);

// Chained
this.add.sprite(100, 100, 'coin')
    .setScale(0.5)
    .setTint(0xffff00)
    .play('spin');

Core Concepts

Sprite vs Image

Both extend GameObject and share the same set of component mixins. The only difference is that Sprite includes an AnimationState instance (sprite.anims) and animation convenience methods (play, stop, chain, etc.).

Feature	Image	Sprite
Static texture display	Yes	Yes
Tint, alpha, flip, scale, rotate	Yes	Yes
Physics body	Yes	Yes
Input / hit area	Yes	Yes
Animation (play, stop, chain)	No	Yes
preUpdate called each frame	No	Yes (updates animation)
Added to Scene updateList	No	Yes

Rule of thumb: Use Image for anything that does not need frame-by-frame animation. It skips the per-frame preUpdate cost and has a smaller API surface. Use Sprite only when you need the Animation component.