actions-and-utilities（动作和实用程序）

Phaser 4 -- Actions & Utility Functions

Phaser.Actions namespace for batch operations on Game Object arrays, plus Phaser.Utils.Array, Phaser.Utils.Objects, and Phaser.Utils.String helper functions.

Related skills:../groups-and-containers/SKILL.md,../sprites-and-images/SKILL.md

Quick Start

// Create 20 sprites and batch-position them in a grid
const sprites = [];
for (let i = 0; i < 20; i++) {
    sprites.push(this.add.sprite(0, 0, 'gem'));
}

// Arrange into a 5x4 grid
Phaser.Actions.GridAlign(sprites, {
    width: 5,
    height: 4,
    cellWidth: 64,
    cellHeight: 64,
    x: 100,
    y: 100
});

// Fade alpha from 0 to 1 across all sprites
Phaser.Actions.Spread(sprites, 'alpha', 0, 1);

// Offset each sprite's x by 10, with a step of 2 per item
Phaser.Actions.IncX(sprites, 10, 2);

// Works with Groups too
const group = this.add.group({ key: 'star', repeat: 11 });
Phaser.Actions.PlaceOnCircle(group.getChildren(), new Phaser.Geom.Circle(400, 300, 200));

Core Concepts

The Actions Pattern

Every Action in Phaser.Actions follows the same pattern:

1. First argument is always an array of Game Objects (or any objects with the required public properties like x, y, alpha, etc.).
2. Returns the same array, enabling chaining or pass-through.
3. Works with Groups by passing group.getChildren().
4. Actions do NOT store state. They are one-shot batch operations.

PropertyValueSet and PropertyValueInc

Most Set/Inc actions delegate to two core functions:

• PropertyValueSet(items, key, value, step, index, direction) -- Sets items[i][key] = value + (i * step).
• PropertyValueInc(items, key, value, step, index, direction) -- Adds items[i][key] += value + (i * step).

The step parameter adds an incremental offset per item. The index and direction parameters control iteration start point and order (1 = forward, -1 = backward).

Geometry-Based Placement

Actions like PlaceOnCircle, PlaceOnLine, RandomRectangle, etc. accept Phaser geometry objects (Phaser.Geom.Circle, Phaser.Geom.Line, etc.), NOT Game Object shapes. If using a Phaser.GameObjects.Circle, pass its .geom property instead.

All Actions

Property Setters

Property Incrementers

Placement on Geometry

Layout and Alignment

Distribution and Interpolation

Rotation and Movement

Queries and Iteration

Effects (v4.0.0+)

Array Utilities

Namespace: Phaser.Utils.Array

Also includes Phaser.Utils.Array.Matrix sub-namespace for 2D matrix operations.

Object Utilities

Namespace: Phaser.Utils.Objects

String Utilities

Namespace: Phaser.Utils.String

Common Patterns

Using Actions with Groups

const enemies = this.add.group({ key: 'enemy', repeat: 9 });

// Position all children in a grid
Phaser.Actions.GridAlign(enemies.getChildren(), {
    width: 5, height: 2,
    cellWidth: 80, cellHeight: 80,
    x: 100, y: 50
});

// Fan out alpha across all enemies
Phaser.Actions.Spread(enemies.getChildren(), 'alpha', 0.3, 1);

Step Parameter for Staggered Values

// Place sprites starting at x=100, each one 50px further right
Phaser.Actions.SetX(sprites, 100, 50);
// Result: items[0].x=100, items[1].x=150, items[2].x=200, ...

// Increment rotation with increasing step
Phaser.Actions.Rotate(sprites, 0.1, 0.05);
// Result: items[0].rotation += 0.1, items[1].rotation += 0.15, items[2].rotation += 0.2, ...

Scatter Then Constrain

const bounds = new Phaser.Geom.Rectangle(0, 0, 800, 600);
// Random scatter
Phaser.Actions.RandomRectangle(sprites, bounds);
// Keep wrapped in bounds during update
Phaser.Actions.WrapInRectangle(sprites, bounds);

GetValue for Config Parsing

// Deep property access with fallback
const width = Phaser.Utils.Objects.GetValue(config, 'render.screen.width', 800);

// Fast top-level lookup (no dot-path, better performance)
const speed = Phaser.Utils.Objects.GetFastValue(config, 'speed', 100);

NumberArray for Asset Keys

// Generate frame key strings
const keys = Phaser.Utils.Array.NumberArray(1, 10, 'frame_', '.png');
// Result: ['frame_1.png', 'frame_2.png', ..., 'frame_10.png']

Gotchas

• Actions operate on plain arrays, not Groups directly. Always call group.getChildren() to get the array.
• PlaceOn/Random geometry actions need Phaser.Geom objects, not Game Object shapes. For a Phaser.GameObjects.Circle, pass circle.geom.
• SetXY defaults y to x if y is undefined or null. Pass 0 explicitly if you want y=0 and x=something else.
• Spread with a single item places it at the midpoint (min + max) / 2, not at min.
• step is multiplied by iteration index, not added cumulatively. Item 0 gets value + 0*step, item 1 gets value + 1*step, etc.
• StableSort uses native Array.sort when the engine supports stable sorting, falling back to merge sort only when needed.
• Shuffle (both Actions and Utils.Array) modifies the array in-place and returns it.
• GetValue vs GetFastValue: Use GetFastValue when the key is always top-level (no dots). It skips dot-path parsing and is faster in hot loops.
• AddEffectBloom / AddEffectShine / AddMaskShape are v4-only filter-based effects. They return arrays of created effects instead of the input.

Source File Map