Game Object Components

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