game-object-components

name	game-object-components
description	Use this skill when working with Phaser 4 game object components and the mixin system. Covers Transform, Alpha, Tint, Origin, Depth, Flip, Mask, GetBounds, Lighting, and other shared component behaviors. Triggers on: component, mixin, transform, mask, bounds, lighting.

Phaser 4 -- Game Object Components Reference

Component mixins that provide shared behavior to all Game Objects: Alpha, BlendMode, Depth, Flip, GetBounds, Lighting, Mask, Origin, ScrollFactor, Size, Texture, TextureCrop, Tint, Transform, Visible, PathFollower, RenderNodes, RenderSteps, Filters, FilterList.

Quick Start

// Every Game Object gets its component methods via mixins.
// Just call them directly on any game object:
const sprite = this.add.sprite(400, 300, 'hero');

sprite.setAlpha(0.5);                          // Alpha
sprite.setBlendMode(Phaser.BlendModes.ADD);    // BlendMode
sprite.setDepth(10);                           // Depth
sprite.setFlip(true, false);                   // Flip
sprite.setOrigin(0, 0);                        // Origin
sprite.setScrollFactor(0);                     // ScrollFactor (HUD)
sprite.setDisplaySize(64, 64);                 // Size
sprite.setTexture('hero', 'walk-1');           // Texture
sprite.setTint(0xff0000);                      // Tint
sprite.setPosition(100, 200);                  // Transform
sprite.setVisible(false);                      // Visible
sprite.setScale(2);                            // Transform
sprite.setAngle(45);                           // Transform

// Per-corner alpha (WebGL only)
sprite.setAlpha(1, 0.5, 0.5, 1);

// Crop a texture region
sprite.setCrop(0, 0, 32, 32);

// Enable WebGL filters (post-processing)
sprite.enableFilters();
sprite.filters.internal.addBlur(1, 2, 2, 1);

// Lighting (WebGL only, v4 feature)
sprite.setLighting(true);

Core Concepts

The Mixin System

Phaser uses Phaser.Class with a Mixins array to compose Game Objects from reusable component objects. Each component is a plain JS object whose properties and methods are copied onto the class prototype. This is NOT prototypal inheritance -- it is property copying at class definition time.

// How Phaser defines Sprite internally:
var Sprite = new Class({
    Extends: GameObject,
    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
    ],
    initialize: function Sprite (scene, x, y, texture, frame) { /* ... */ }
});

Key Rules

1. Components are mixed in at class creation, not per-instance.
2. Most setter methods return this for chaining: sprite.setAlpha(0.5).setDepth(10).setPosition(100, 200).
3. Many properties use getters/setters internally (e.g., alpha, depth, visible, scale, rotation). Setting alpha = 0 or scale = 0 clears render flags, skipping rendering.
4. renderFlags is a bitmask: bit 0 = visible, bit 1 = alpha, bit 2 = scale, bit 3 = texture. All bits must be set for the object to render.
5. Alpha vs AlphaSingle: Alpha supports per-corner alpha (WebGL), AlphaSingle only supports a single global alpha. Containers use AlphaSingle.
6. Texture vs TextureCrop: TextureCrop extends Texture with setCrop() support. Sprites and Images use TextureCrop; some objects use plain Texture.
7. Filters and RenderSteps are v4-only, WebGL-only systems for post-processing.

Complete Component Reference

Alpha

Provides per-corner transparency. Used by Sprite, Image, Text, and most renderable objects.

Member	Type	Description
alpha	number (get/set)	Global alpha 0-1. Setting this also sets all four corners. Setting to 0 disables rendering. Default: 1
alphaTopLeft	number (get/set)	Top-left corner alpha. WebGL only.
alphaTopRight	number (get/set)	Top-right corner alpha. WebGL only.
alphaBottomLeft	number (get/set)	Bottom-left corner alpha. WebGL only.
alphaBottomRight	number (get/set)	Bottom-right corner alpha. WebGL only.
setAlpha(topLeft?, topRight?, bottomLeft?, bottomRight?)	method	Set alpha. One arg = uniform. Four args = per-corner (WebGL). Returns this.
clearAlpha()	method	Resets alpha to 1. Returns this.

AlphaSingle

Simplified alpha with no per-corner support. Used by Container.

Member	Type	Description
alpha	number (get/set)	Alpha 0-1. Default: 1
setAlpha(value?)	method	Set alpha. Returns this.
clearAlpha()	method	Resets alpha to 1. Returns this.

BlendMode

Controls how pixels are composited during rendering.

Member	Type	Description
blendMode	number/string (get/set)	Current blend mode. Accepts Phaser.BlendModes const, string, or integer.
setBlendMode(value)	method	Set the blend mode. Returns this.

WebGL blend modes: NORMAL, ADD, MULTIPLY, SCREEN, ERASE. Canvas supports additional browser-dependent modes.

Depth

Controls rendering order (z-index). Higher depth renders on top.

Member	Type	Description
depth	number (get/set)	Depth value. Setting it queues a depth sort. Default: 0
setDepth(value)	method	Set depth. Returns this.
setToTop()	method	Move to top of display list (no depth change). Returns this.
setToBack()	method	Move to back of display list. Returns this.
setAbove(gameObject)	method	Move above another Game Object in display list. Returns this.
setBelow(gameObject)	method	Move below another Game Object in display list. Returns this.

Flip

Visual mirroring without affecting physics bodies.

Member	Type	Description
flipX	boolean	Horizontal flip state. Default: false
flipY	boolean	Vertical flip state. Default: false
setFlipX(value)	method	Set horizontal flip. Returns this.
setFlipY(value)	method	Set vertical flip. Returns this.
setFlip(x, y)	method	Set both flip states. Returns this.
toggleFlipX()	method	Toggle horizontal flip. Returns this.
toggleFlipY()	method	Toggle vertical flip. Returns this.
resetFlip()	method	Reset both to false. Returns this.

GetBounds

Calculate positions and bounding rectangles regardless of origin.

Member	Type	Description
getCenter(output?, includeParent?)	method	Center coordinate. Returns Vector2Like.
getTopLeft(output?, includeParent?)	method	Top-left coordinate. Returns Vector2Like.
getTopCenter(output?, includeParent?)	method	Top-center coordinate. Returns Vector2Like.
getTopRight(output?, includeParent?)	method	Top-right coordinate. Returns Vector2Like.
getLeftCenter(output?, includeParent?)	method	Left-center coordinate. Returns Vector2Like.
getRightCenter(output?, includeParent?)	method	Right-center coordinate. Returns Vector2Like.
getBottomLeft(output?, includeParent?)	method	Bottom-left coordinate. Returns Vector2Like.
getBottomCenter(output?, includeParent?)	method	Bottom-center coordinate. Returns Vector2Like.
getBottomRight(output?, includeParent?)	method	Bottom-right coordinate. Returns Vector2Like.
getBounds(output?)	method	Full bounding rectangle. Returns Rectangle.

Set includeParent = true to factor in parent Container transforms.

Lighting (v4, WebGL only)

Enables light-based rendering with the Phaser 4 lighting system.

Member	Type	Description
lighting	boolean	Whether to use lighting. Default: false
selfShadow	object	{ enabled, penumbra, diffuseFlatThreshold }. Self-shadow settings.
setLighting(enable)	method	Enable/disable lighting. Returns this.
setSelfShadow(enabled?, penumbra?, diffuseFlatThreshold?)	method	Configure self-shadow. Pass null for enabled to use game config default. Returns this.

Mask (Canvas only in v4)

Geometry masking for Canvas renderer. In WebGL, use Filters.addMask() instead.

Member	Type	Description
mask	GeometryMask	The current mask, or null.
setMask(mask)	method	Apply a GeometryMask. Canvas only. In WebGL, logs a warning. Returns this.
clearMask(destroyMask?)	method	Remove the mask. Pass true to also destroy it. Returns this.
createGeometryMask(graphics?)	method	Create a GeometryMask from a Graphics/Shape object. Returns GeometryMask.

Origin

Controls the anchor point for position, rotation, and scale. Normalized 0-1.

Member	Type	Description
originX	number	Horizontal origin. Default: 0.5 (center)
originY	number	Vertical origin. Default: 0.5 (center)
displayOriginX	number (get/set)	Origin in pixels. Setting recalculates originX.
displayOriginY	number (get/set)	Origin in pixels. Setting recalculates originY.
setOrigin(x?, y?)	method	Set origin (normalized). y defaults to x. Default: 0.5. Returns this.
setOriginFromFrame()	method	Set origin from texture Frame pivot. Returns this.
setDisplayOrigin(x?, y?)	method	Set origin in pixels. Returns this.
updateDisplayOrigin()	method	Recalculate display origin cache. Returns this.

ScrollFactor

Controls how camera scrolling affects the object's rendered position.

Member	Type	Description
scrollFactorX	number	Horizontal scroll factor. Default: 1
scrollFactorY	number	Vertical scroll factor. Default: 1
setScrollFactor(x, y?)	method	Set scroll factor. y defaults to x. Returns this.

Key values: 0 = fixed to camera (HUD element), 1 = moves with camera, 0.5 = parallax half-speed.

Size

Manages native and display dimensions.

Member	Type	Description
width	number	Native (un-scaled) width.
height	number	Native (un-scaled) height.
displayWidth	number (get/set)	Scaled width. Setting adjusts scaleX.
displayHeight	number (get/set)	Scaled height. Setting adjusts scaleY.
setSize(width, height)	method	Set native size. Does NOT affect rendered size. Returns this.
setDisplaySize(width, height)	method	Set rendered size (adjusts scale). Returns this.
setSizeToFrame(frame?)	method	Set size from a texture Frame. Returns this.

Texture

Gets and sets the texture and frame for rendering.

Member	Type	Description
texture	Phaser.Textures.Texture	The current Texture.
frame	Phaser.Textures.Frame	The current Frame.
setTexture(key, frame?, updateSize?, updateOrigin?)	method	Set texture by key. Returns this.
setFrame(frame, updateSize?, updateOrigin?)	method	Set frame by name, index, or Frame instance. Updates size and origin by default. Returns this.

TextureCrop

Extends Texture with cropping support. Used by Sprite and Image.

Member	Type	Description
texture	Phaser.Textures.Texture	The current Texture.
frame	Phaser.Textures.Frame	The current Frame.
isCropped	boolean	Whether cropping is active.
setTexture(key, frame?)	method	Set texture by key. Returns this.
setFrame(frame, updateSize?, updateOrigin?)	method	Set frame. Also updates crop UVs if cropped. Returns this.
setCrop(x?, y?, width?, height?)	method	Set crop rectangle. Pass no args to clear. Accepts a Rectangle as first arg. Returns this.

Tint (WebGL only)

Applies color tinting to the texture via per-corner vertex colors.

Member	Type	Description
tint	number (get/set)	Uniform tint color (reads tintTopLeft). Default: 0xffffff
tintTopLeft	number	Top-left vertex tint. Default: 0xffffff
tintTopRight	number	Top-right vertex tint. Default: 0xffffff
tintBottomLeft	number	Bottom-left vertex tint. Default: 0xffffff
tintBottomRight	number	Bottom-right vertex tint. Default: 0xffffff
tintMode	number	Tint blend mode. Default: Phaser.TintModes.MULTIPLY
isTinted	boolean (readonly)	True if any tint or mode is set.
setTint(topLeft?, topRight?, bottomLeft?, bottomRight?)	method	Set tint colors. One arg = uniform. Returns this.
setTintMode(mode)	method	Set tint mode (v4). Modes: MULTIPLY, FILL, ADD, SCREEN, OVERLAY, HARD_LIGHT. Returns this.
clearTint()	method	Reset to white + MULTIPLY. Returns this.

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

Transform

Position, scale, rotation, and coordinate transforms.

Member	Type	Description
x	number	X position. Default: 0
y	number	Y position. Default: 0
z	number	Z position (NOT rendering order; use depth). Default: 0
w	number	W position. Default: 0
scale	number (get/set)	Uniform scale. Get returns average of scaleX and scaleY.
scaleX	number (get/set)	Horizontal scale. Default: 1
scaleY	number (get/set)	Vertical scale. Default: 1
angle	number (get/set)	Rotation in degrees (clockwise, 0 = right).
rotation	number (get/set)	Rotation in radians.
setPosition(x?, y?, z?, w?)	method	Set position. y defaults to x. Returns this.
copyPosition(source)	method	Copy x/y/z/w from a Vector-like object. Returns this.
setRandomPosition(x?, y?, width?, height?)	method	Randomize position within area. Returns this.
setRotation(radians?)	method	Set rotation in radians. Returns this.
setAngle(degrees?)	method	Set rotation in degrees. Returns this.
setScale(x?, y?)	method	Set scale. y defaults to x. Returns this.
setX(value?)	method	Set x. Returns this.
setY(value?)	method	Set y. Returns this.
setZ(value?)	method	Set z. Returns this.
setW(value?)	method	Set w. Returns this.
getLocalTransformMatrix(tempMatrix?)	method	Get local transform matrix. Returns TransformMatrix.
getWorldTransformMatrix(tempMatrix?, parentMatrix?)	method	Get world transform including parent Containers. Returns TransformMatrix.
getLocalPoint(x, y, point?, camera?)	method	Convert world coords to local space. Returns Vector2.
getWorldPoint(point?, tempMatrix?, parentMatrix?)	method	Get world position factoring parent containers. Returns Vector2.
getParentRotation()	method	Sum of all parent container rotations in radians.

Visible

Controls whether the Game Object renders. Invisible objects still run update logic.

Member	Type	Description
visible	boolean (get/set)	Visibility state. Default: true
setVisible(value)	method	Set visibility. Returns this.

PathFollower

Manages following a Phaser.Curves.Path using an internal tween.

Member	Type	Description
path	Phaser.Curves.Path	The Path being followed.
rotateToPath	boolean	Auto-rotate to face path direction. Default: false
pathRotationOffset	number	Rotation offset in degrees when rotateToPath is true.
pathOffset	Vector2	Position offset from path coordinates.
pathVector	Vector2	Current point on the path.
pathDelta	Vector2	Distance traveled since last update.
pathTween	Tween	The tween driving path movement.
setPath(path, config?)	method	Set a new Path. Returns this.
setRotateToPath(value, offset?)	method	Enable auto-rotation. Returns this.
isFollowing()	method	Returns true if actively following.
startFollow(config?, startAt?)	method	Start following. config can be duration (number) or PathConfig. Returns this.
pauseFollow()	method	Pause movement. Returns this.
resumeFollow()	method	Resume movement. Returns this.
stopFollow()	method	Stop following. Returns this.

RenderNodes, RenderSteps, Filters, FilterList (v4, WebGL only)

For RenderNodes, RenderSteps, and FilterList details, see the filters-and-postfx skill and references/REFERENCE.md.

Key points: Call enableFilters() on game objects before accessing filters. Cameras have filters by default. Use filters.internal for object-local effects and filters.external for screen-space effects.

For a full component-to-game-object matrix, see references/REFERENCE.md.

Factory Registration and Display List

Custom Game Object Factory Registration

Register custom game objects on the factory so they can be created via this.add.myObject():

class LaserBeam extends Phaser.GameObjects.Sprite {
    constructor(scene, x, y) {
        super(scene, x, y, 'laser');
    }
}

Phaser.GameObjects.GameObjectFactory.register('laserBeam', function (x, y) {
    const beam = new LaserBeam(this.scene, x, y);
    this.displayList.add(beam);
    return beam;
});

// Now usable in any scene:
const laser = this.add.laserBeam(100, 200);

Factory (this.add) vs Creator (this.make)

this.add creates the object AND adds it to the display list. this.make creates the object but does NOT add it -- useful for off-screen preparation or deferred display.

// Added to display list immediately
const visible = this.add.sprite(100, 100, 'hero');

// Created but NOT on the display list
const offscreen = this.make.sprite({ key: 'hero', x: 100, y: 100 });

// Add it later when ready
this.add.existing(offscreen);

GetAdvancedValue for Flexible Config

GetAdvancedValue resolves static values, random arrays, randInt/Float ranges, and callbacks from config objects:

// Static value
{ speed: 100 }

// Random from array
{ speed: [100, 200, 300] }

// Random integer range
{ speed: { randInt: [50, 150] } }

// Random float range
{ speed: { randFloat: [0.5, 1.5] } }

// Callback
{ speed: function () { return Math.random() * 100; } }

Display List Ordering

Objects added later render on top of earlier objects. Control ordering with:

// Depth-based ordering (higher = on top, triggers sort)
sprite.setDepth(10);

// Display list position (no depth change)
sprite.setToTop();
sprite.setToBack();
sprite.setAbove(otherSprite);
sprite.setBelow(otherSprite);

When both depth and display list position are used, depth takes priority after the next sort pass.

Gotchas

1. alpha=0 prevents rendering entirely: Setting alpha to 0 clears a render flag bit. The object is not drawn at all, not merely transparent. Same applies to scale = 0 and visible = false.

2. Flip does not affect physics: Flipping is rendering-only. Physics bodies remain unchanged. Account for this in collision code.

3. ScrollFactor and physics: Physics collisions use world position. A scroll factor other than 1 offsets where the texture renders but not where the body is. For HUD elements with scroll factor 0, avoid adding physics bodies.

4. depth vs display list order: setDepth() queues a sort and is the primary z-ordering tool. setToTop(), setAbove(), etc. reorder the display list without changing depth. If you mix both, depth takes priority after the next sort.

5. Mask component is Canvas-only in v4: For WebGL masking, use enableFilters() then filters.internal.addMask(). The setMask() method logs a warning in WebGL.

6. setTintFill is removed in v4: Use setTint(color).setTintMode(Phaser.TintModes.FILL) instead.

7. Tint modes in v4: Tint mode is now separate from tint color. Available modes: MULTIPLY (default), FILL, ADD, SCREEN, OVERLAY, HARD_LIGHT.

8. displayWidth/displayHeight adjusts scale: Setting displayWidth or displayHeight modifies scaleX/scaleY. It does NOT change width/height.

9. setSize vs setDisplaySize: setSize() changes internal dimensions (used for frames, physics). setDisplaySize() changes the rendered size by adjusting scale.

10. Origin default is 0.5: All Game Objects default to center origin. Use setOrigin(0, 0) for top-left positioning. Text and BitmapText instead default to top-left positioning.

11. Transform.z is NOT depth: The z property on Transform is for custom use. Rendering order is controlled by depth (Depth component) or display list position.

12. Filters are expensive: Each object with active filters requires extra draw calls. Use renderFilters = false to temporarily disable. Internal filters are cheaper than external.

Source File Map

File	Description
src/gameobjects/components/index.js	Component registry, exports all components
src/gameobjects/components/Alpha.js	Per-corner alpha mixin
src/gameobjects/components/AlphaSingle.js	Single-value alpha mixin
src/gameobjects/components/BlendMode.js	Blend mode mixin
src/gameobjects/components/Depth.js	Depth/z-order mixin
src/gameobjects/components/Flip.js	Visual flip mixin
src/gameobjects/components/GetBounds.js	Bounds calculation mixin
src/gameobjects/components/Lighting.js	v4 lighting mixin
src/gameobjects/components/Mask.js	Canvas geometry mask mixin
src/gameobjects/components/Origin.js	Origin/anchor mixin
src/gameobjects/components/ScrollFactor.js	Camera scroll factor mixin
src/gameobjects/components/Size.js	Dimensions mixin
src/gameobjects/components/Texture.js	Texture/frame assignment mixin
src/gameobjects/components/TextureCrop.js	Texture with crop support mixin
src/gameobjects/components/Tint.js	Vertex color tinting mixin
src/gameobjects/components/Transform.js	Position/scale/rotation mixin
src/gameobjects/components/Visible.js	Visibility mixin
src/gameobjects/components/PathFollower.js	Path-following mixin
src/gameobjects/components/RenderNodes.js	v4 WebGL render node mixin
src/gameobjects/components/RenderSteps.js	v4 WebGL render step mixin
src/gameobjects/components/Filters.js	v4 WebGL filter system mixin
src/gameobjects/components/FilterList.js	v4 filter list class (add effects)
src/gameobjects/components/TransformMatrix.js	2D transform matrix utility

---

Related skills: sprites-and-images.md, custom-game-objects.md