game-object-components

# 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 ```js // 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. ```js // 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 |