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

Components are mixed in at class creation, not per-instance.
Most setter methods return this for chaining: sprite.setAlpha(0.5).setDepth(10).setPosition(100, 200).
Many properties use getters/setters internally (e.g., alpha, depth, visible, scale, rotation). Setting alpha = 0 or scale = 0 clears render flags, skipping rendering.
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.
Alpha vs AlphaSingle: Alpha supports per-corner alpha (WebGL), AlphaSingle only supports a single global alpha. Containers use AlphaSingle.
Texture vs TextureCrop: TextureCrop extends Texture with setCrop() support. Sprites and Images use TextureCrop; some objects use plain Texture.
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

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

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.
Flip does not affect physics: Flipping is rendering-only. Physics bodies remain unchanged. Account for this in collision code.
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.
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.
Mask component is Canvas-only in v4: For WebGL masking, use enableFilters() then filters.internal.addMask(). The setMask() method logs a warning in WebGL.
setTintFill is removed in v4: Use setTint(color).setTintMode(Phaser.TintModes.FILL) instead.
Tint modes in v4: Tint mode is now separate from tint color. Available modes: MULTIPLY (default), FILL, ADD, SCREEN, OVERLAY, HARD_LIGHT.
displayWidth/displayHeight adjusts scale: Setting displayWidth or displayHeight modifies scaleX/scaleY. It does NOT change width/height.
setSize vs setDisplaySize: setSize() changes internal dimensions (used for frames, physics). setDisplaySize() changes the rendered size by adjusting scale.
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.
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.
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

game-object-components