name: actions-and-utilities

description: "Use this skill when working with Phaser 4 utility functions, actions, alignment, grid layout, or batch operations on game objects. Triggers on: align, grid layout, actions, set operations on groups of game objects."

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