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

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

AlphaSingle

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

BlendMode

Controls how pixels are composited during rendering.

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.

Flip

Visual mirroring without affecting physics bodies.

GetBounds

Calculate positions and bounding rectangles regardless of origin.

Set includeParent = true to factor in parent Container transforms.

Lighting (v4, WebGL only)

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

Mask (Canvas only in v4)

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

Origin

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

ScrollFactor

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

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

Size

Manages native and display dimensions.

Texture

Gets and sets the texture and frame for rendering.

TextureCrop

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

Tint (WebGL only)

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

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

Transform

Position, scale, rotation, and coordinate transforms.

Visible

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

PathFollower

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

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

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