phaserjs/phaser

sprites-and-images

Use this skill when creating Sprites or Images in Phaser 4.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/phaserjs/phaser --skill sprites-and-images

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

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.).

FeatureImageSprite
Static texture displayYesYes
Tint, alpha, flip, scale, rotateYesYes
Physics bodyYesYes
Input / hit areaYesYes
Animation (play, stop, chain)NoYes
preUpdate called each frameNoYes (updates animation)
Added to Scene updateListNoYes

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.setCrop(10, 10, 50, 50);
// Reset crop
sprite.setCrop();

Common Patterns

Creating and Positioning

Transform component (src/gameobjects/components/Transform.js):

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} object

Size component (src/gameobjects/components/Size.js):

js
sprite.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

Scaling and Rotation

Transform component (continued):

js
// 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 0

Tinting and Alpha

Tint component (src/gameobjects/components/Tint.js) -- WebGL only:

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 mode

Phaser 4 change: setTintFill() is removed. Use setTint(color).setTintMode(Phaser.TintModes.FILL) instead.

Alpha component (src/gameobjects/components/Alpha.js):

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)

Setting alpha to 0 clears the render flag so the object is not drawn. Setting it back to any non-zero value restores it.

Flipping

Flip component (src/gameobjects/components/Flip.js):

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 false

Flipping is a rendering toggle only. It does not affect physics bodies or hit areas. Flip occurs from the middle of the texture and does not change the scale value.

Origin and Depth

Origin component (src/gameobjects/components/Origin.js):

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 normalized

Depth component (src/gameobjects/components/Depth.js):

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 list

Setting depth queues a depth sort in the Scene. The setToTop/setToBack/setAbove/setBelow methods change display list position without modifying the depth value.

Destroying Game Objects

js
sprite.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 called

For Sprites, destroy() also calls this.anims.destroy() to clean up the AnimationState.

Additional Components

Visible (src/gameobjects/components/Visible.js):

js
sprite.visible              // boolean (default: true)
sprite.setVisible(value)    // invisible objects skip rendering but still update

ScrollFactor (src/gameobjects/components/ScrollFactor.js):

js
sprite.scrollFactorX        // default: 1 (moves with camera)
sprite.scrollFactorY        // default: 1
sprite.setScrollFactor(x, y)  // 0 = fixed to camera; y defaults to x

BlendMode (src/gameobjects/components/BlendMode.js):

js
sprite.blendMode            // default: Phaser.BlendModes.NORMAL
sprite.setBlendMode(value)  // Phaser.BlendModes.ADD, MULTIPLY, SCREEN, ERASE, etc.

Performance note: Changing blend mode breaks WebGL batches. Group objects by blend mode when possible (e.g., render all ADD-mode sprites together) to minimize draw calls.

Factory Methods

this.add.sprite

Source: src/gameobjects/sprite/SpriteFactory.js

js
// Signature
this.add.sprite(x, y, texture, frame);
ParamTypeRequiredDescription
xnumberYesHorizontal position in world coordinates
ynumberYesVertical position in world coordinates
texture`string \Phaser.Textures.Texture`YesTexture key or Texture instance
frame`string \number`NoFrame name or index within the texture

Returns: Phaser.GameObjects.Sprite

Internally does: this.displayList.add(new Sprite(this.scene, x, y, texture, frame))

The Sprite constructor calls: setTexture -> setPosition -> setSizeToFrame -> setOriginFromFrame -> initRenderNodes.

this.add.image

Source: src/gameobjects/image/ImageFactory.js

js
// Signature
this.add.image(x, y, texture, frame);
ParamTypeRequiredDescription
xnumberYesHorizontal position in world coordinates
ynumberYesVertical position in world coordinates
texture`string \Phaser.Textures.Texture`YesTexture key or Texture instance
frame`string \number`NoFrame name or index within the texture

Returns: Phaser.GameObjects.Image

Internally does: this.displayList.add(new Image(this.scene, x, y, texture, frame))

The Image constructor calls the same init sequence as Sprite: setTexture -> setPosition -> setSizeToFrame -> setOriginFromFrame -> initRenderNodes.

Specialized Game Objects

NineSlice

Scalable UI panels with fixed-size corners and stretchable edges/center. Ideal for buttons, panels, and dialog boxes that need to resize without distorting borders.

js
// 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);

TileSprite

Repeating texture that fills an area. Supports atlas frames in v4 and a new tileRotation property.

js
const 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;

Blitter

High-performance batched rendering for large numbers of static or semi-static sprites. Blitter children (Bobs) have no rotation, scale, or physics, but render significantly faster than individual Sprites.

js
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());
}

Video

Video playback as a game object with position, scale, and filter support.

js
// Load in preload:
this.load.video('intro', 'intro.mp4');

// Create in create:
const video = this.add.video(400, 300, 'intro');
video.play();

For detailed configuration options, API reference tables, and source file maps, see the reference guide.

같은 저장소의 Skills

더 많은 Skills

모든 Skills
phaserjs
커뮤니티

cameras

Use this skill when working with cameras in Phaser 4. Covers camera effects (shake, fade, flash, pan, zoom), following sprites, scroll, bounds, viewports, multiple cameras, and minimap. Triggers on: camera, viewport, scroll, zoom, follow, shake, fade.

1시간 설치 수
1
GitHub Stars
4.1만
업데이트
8월 21일
phaserjs
커뮤니티

geometry-and-math

Use this skill when using Phaser 4 math and geometry utilities. Covers vectors, rectangles, circles, triangles, polygons, random number generation, angles, distance, interpolation, and snapping. Triggers on: Vector2, Rectangle, Circle, math, distance, angle, random, lerp.

1시간 설치 수
1
GitHub Stars
4.1만
업데이트
8월 21일
phaserjs
커뮤니티

loading-assets

Use this skill when loading assets in Phaser 4. Covers the Loader plugin, loading images, spritesheets, atlases, audio, JSON, tilemaps, bitmap fonts, and tracking load progress. Triggers on: preload, this.load, asset loading, spritesheet, atlas, load progress.

1시간 설치 수
1
GitHub Stars
4.1만
업데이트
8월 21일
phaserjs
커뮤니티

physics-arcade

Use this skill when using Arcade Physics in Phaser 4. Covers enabling physics, velocity, acceleration, gravity, collisions, overlap, world bounds, physics groups, static bodies, and collision categories. Triggers on: physics, arcade, velocity, gravity, collide, overlap, bounce, physics body.

1시간 설치 수
1
GitHub Stars
4.1만
업데이트
8월 21일