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:

= fixed to camera (HUD element),

= 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

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

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

NPX Install

Tags

SKILL.md Content

Phaser 4 -- Game Object Components Reference

Quick Start

Core Concepts

The Mixin System

Key Rules

Complete Component Reference

Alpha

AlphaSingle

BlendMode

Depth

Flip

GetBounds

Lighting (v4, WebGL only)

Mask (Canvas only in v4)

Origin

ScrollFactor

Size

Texture

TextureCrop

Tint (WebGL only)

Transform

Visible

PathFollower

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

Factory Registration and Display List

Custom Game Object Factory Registration

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

GetAdvancedValue for Flexible Config

Display List Ordering

Gotchas

Source File Map