Loading...
Loading...
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.
npx skill4agent add phaserjs/phaser sprites-and-imagesCreating 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).
src/gameobjects/sprite/src/gameobjects/image/src/gameobjects/GameObject.jssrc/gameobjects/components/// 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');GameObjectAnimationStatesprite.animsplaystopchain| 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 ( | No | Yes |
| No | Yes (updates animation) |
Added to Scene | No | Yes |
ImagepreUpdateSpriteSpriteImagesrc/gameobjects/sprite/Sprite.jssrc/gameobjects/image/Image.jsMixins: [
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)
]GameObjectMixins: [
Components.Filters,
Components.RenderSteps
]Components.TransformxyscalerotationsetPosition()src/gameobjects/components/index.jssetAlpha()Components.AlphaTextureCroptexturePhaser.Textures.TextureframePhaser.Textures.FramesetTexture(key, frame)setFrame(frame, updateSize, updateOrigin)setCrop(x, y, width, height)isCroppedsetCroptexturePhaser.Textures.Textureframe'__BASE'// 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.setCrop(10, 10, 50, 50);
// Reset crop
sprite.setCrop();src/gameobjects/components/Transform.js// Properties (all read/write)
sprite.x // horizontal position (default: 0)
sprite.y // vertical position (default: 0)
sprite.z // z position (does NOT control render order -- use depth)
sprite.w // w position
// Methods
sprite.setPosition(x, y, z, w) // y defaults to x if omitted
sprite.setRandomPosition(x, y, w, h) // random within area; defaults to game size
sprite.copyPosition(source) // copy from any {x, y} objectsrc/gameobjects/components/Size.jssprite.width // native (un-scaled) width
sprite.height // native (un-scaled) height
sprite.displayWidth // scaled width (read/write -- setting adjusts scaleX)
sprite.displayHeight // scaled height (read/write -- setting adjusts scaleY)
sprite.setSize(width, height) // set internal size (not visual)
sprite.setDisplaySize(width, height) // set visual size (adjusts scale)
sprite.setSizeToFrame(frame) // reset size to match frame// Scale properties
sprite.scale // uniform scale (getter returns average of scaleX+scaleY)
sprite.scaleX // horizontal scale (default: 1)
sprite.scaleY // vertical scale (default: 1)
// Scale methods
sprite.setScale(x, y) // y defaults to x if omitted
// Rotation properties
sprite.rotation // in radians (right-hand clockwise: 0=right, PI/2=down)
sprite.angle // in degrees (0=right, 90=down, 180/-180=left, -90=up)
// Rotation methods
sprite.setRotation(radians) // defaults to 0
sprite.setAngle(degrees) // defaults to 0src/gameobjects/components/Tint.js// Properties
sprite.tint // overall tint (getter returns tintTopLeft)
sprite.tintTopLeft // default: 0xffffff
sprite.tintTopRight // default: 0xffffff
sprite.tintBottomLeft // default: 0xffffff
sprite.tintBottomRight // default: 0xffffff
sprite.tintMode // default: Phaser.TintModes.MULTIPLY
sprite.isTinted // read-only boolean
// Methods
sprite.setTint(topLeft, topRight, bottomLeft, bottomRight)
// If only topLeft given, applies uniformly to all four corners
sprite.setTintMode(mode) // Phaser.TintModes.MULTIPLY | FILL | ADD | SCREEN | OVERLAY | HARD_LIGHT
sprite.clearTint() // resets to 0xffffff + MULTIPLY modesetTintFill()setTint(color).setTintMode(Phaser.TintModes.FILL)src/gameobjects/components/Alpha.js// Properties
sprite.alpha // global alpha 0-1 (default: 1)
sprite.alphaTopLeft // per-corner alpha (WebGL only)
sprite.alphaTopRight
sprite.alphaBottomLeft
sprite.alphaBottomRight
// Methods
sprite.setAlpha(topLeft, topRight, bottomLeft, bottomRight)
// If only topLeft given, applies uniformly to whole object
sprite.clearAlpha() // resets to 1 (fully opaque)alphasrc/gameobjects/components/Flip.js// Properties
sprite.flipX // boolean (default: false)
sprite.flipY // boolean (default: false)
// Methods
sprite.setFlipX(value) // set horizontal flip
sprite.setFlipY(value) // set vertical flip
sprite.setFlip(x, y) // set both at once
sprite.toggleFlipX() // invert current horizontal flip
sprite.toggleFlipY() // invert current vertical flip
sprite.resetFlip() // set both to falsesrc/gameobjects/components/Origin.js// Properties (normalized 0-1)
sprite.originX // default: 0.5 (center)
sprite.originY // default: 0.5 (center)
sprite.displayOriginX // pixel value (originX * width)
sprite.displayOriginY // pixel value (originY * height)
// Methods
sprite.setOrigin(x, y) // y defaults to x; defaults to 0.5
sprite.setDisplayOrigin(x, y) // set origin in pixels; y defaults to x
sprite.setOriginFromFrame() // use Frame pivot if set, else 0.5
sprite.updateDisplayOrigin() // recalculate pixel origin from normalizedsrc/gameobjects/components/Depth.js// Properties
sprite.depth // default: 0 (higher = renders on top)
// Methods
sprite.setDepth(value)
sprite.setToTop() // move to top of display list (no depth change)
sprite.setToBack() // move to back of display list (no depth change)
sprite.setAbove(gameObject) // position above another object in the list
sprite.setBelow(gameObject) // position below another object in the listdepthsetToTopsetToBacksetAbovesetBelowdepthsprite.destroy(); // removes from display list, update list, and cleans up
sprite.ignoreDestroy = true; // prevent destruction (you manage lifecycle manually)
sprite.isDestroyed // boolean, true after destroy() has been calleddestroy()this.anims.destroy()src/gameobjects/components/Visible.jssprite.visible // boolean (default: true)
sprite.setVisible(value) // invisible objects skip rendering but still updatesrc/gameobjects/components/ScrollFactor.jssprite.scrollFactorX // default: 1 (moves with camera)
sprite.scrollFactorY // default: 1
sprite.setScrollFactor(x, y) // 0 = fixed to camera; y defaults to xsrc/gameobjects/components/BlendMode.jssprite.blendMode // default: Phaser.BlendModes.NORMAL
sprite.setBlendMode(value) // Phaser.BlendModes.ADD, MULTIPLY, SCREEN, ERASE, etc.src/gameobjects/sprite/SpriteFactory.js// Signature
this.add.sprite(x, y, texture, frame);| Param | Type | Required | Description |
|---|---|---|---|
| | Yes | Horizontal position in world coordinates |
| | Yes | Vertical position in world coordinates |
| | Yes | Texture key or Texture instance |
| | No | Frame name or index within the texture |
Phaser.GameObjects.Spritethis.displayList.add(new Sprite(this.scene, x, y, texture, frame))setTexturesetPositionsetSizeToFramesetOriginFromFrameinitRenderNodessrc/gameobjects/image/ImageFactory.js// Signature
this.add.image(x, y, texture, frame);| Param | Type | Required | Description |
|---|---|---|---|
| | Yes | Horizontal position in world coordinates |
| | Yes | Vertical position in world coordinates |
| | Yes | Texture key or Texture instance |
| | No | Frame name or index within the texture |
Phaser.GameObjects.Imagethis.displayList.add(new Image(this.scene, x, y, texture, frame))setTexturesetPositionsetSizeToFramesetOriginFromFrameinitRenderNodes// nineslice(x, y, texture, frame, width, height, leftWidth, rightWidth, topHeight, bottomHeight)
const panel = this.add.nineslice(400, 300, 'panel', null, 300, 200, 20, 20, 20, 20);
// Resize at runtime -- corners stay fixed, edges stretch
panel.setSize(500, 400);tileRotationconst bg = this.add.tileSprite(400, 300, 800, 600, 'grass');
// Scroll the tile in update() for parallax backgrounds
bg.tilePositionX += 0.5;
bg.tilePositionY += 0.25;
// v4: rotate the tile pattern
bg.tileRotation = 0.1;const blitter = this.add.blitter(0, 0, 'particles');
// Create Bobs (lightweight display objects)
for (let i = 0; i < 1000; i++) {
const bob = blitter.create(
Phaser.Math.Between(0, 800),
Phaser.Math.Between(0, 600),
'particle_01' // frame name within the texture
);
bob.setAlpha(Math.random());
}// Load in preload:
this.load.video('intro', 'intro.mp4');
// Create in create:
const video = this.add.video(400, 300, 'intro');
video.play();