Sprites et images

--- name: sprites-and-images description: "Use this skill when creating Sprites or Images in Phaser 4. Covers factory methods, texture/frame selection, position, scale, rotation, tint, flip, alpha, origin, depth, and the component mixin system. Triggers on: Sprite, Image, this.add.sprite, this.add.image, texture, setTint, setAlpha." --- # 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 ``js // 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. ### The Component Mixin System Phaser builds Game Object classes by mixing component objects into the prototype. Both Sprite and Image share this identical Mixins array (sourced from src/gameobjects/sprite/Sprite.js and src/gameobjects/image/Image.js): ` Mixins: [ Components.Alpha, Components.BlendMode, Components.Depth, Components.Flip, Components.GetBounds, Components.Lighting, Components.Mask, Components.Origin, Components.RenderNodes, Components.ScrollFactor, Components.Size, Components.TextureCrop, Components.Tint, Components.Transform, Components.Visible, SpriteRender / ImageRender // render-specific (differs per class) ] ` The base GameObject class itself mixes in: ` Mixins: [ Components.Filters, Components.RenderSteps ] ` Each component adds specific properties and methods to every instance. For example, Components.Transform adds x, y, scale, rotation, setPosition(), etc. The full list of available components is in src/gameobjects/components/index.js. **Key point for agents:** When you see a method like setAlpha() on a Sprite, it comes from Components.Alpha, not from the Sprite class itself. The component source file is the authoritative reference for that method's signature and behavior. ### Texture and Frame Both Sprite and Image use the TextureCrop component which provides: - texture -- the Phaser.Textures.Texture instance - frame -- the current Phaser.Textures.Frame instance - setTexture(key, frame) -- change the texture (and optionally the frame) - setFrame(frame, updateSize, updateOrigin) -- change only the frame - setCrop(x, y, width, height) -- crop a rectangular region of the texture - isCropped -- boolean, toggle cropping on/off after setCrop The texture parameter in factory methods and constructors accepts either a string key (as registered in the Texture Manager) or a Phaser.Textures.Texture instance. The frame parameter accepts a string name or numeric index into the texture's frame collection. If omitted, the base frame (frame 0 / '__BASE') is used. ``js // Change texture at runtime sprite.setTexture('enemies', 'goblin-walk-1'); // Change only the frame (must belong to current texture) sprite.setFrame('goblin-walk-2'); // setFrame signature: // setFrame(frame, updateSize=true, updateOrigin=true) // Pass false to prevent automatic resize/origin recalculation sprite.setFrame('small-frame', false, false); // Crop to show only a 50x50 region starting at (10, 10) sprite.