Phaser 4 : actions & utilities

--- 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 ``js // 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 | Action | Signature | Description | |---|---|---| | SetX | (items, value, step?, index?, direction?) | Set x property | | SetY | (items, value, step?, index?, direction?) | Set y property | | SetXY | (items, x, y?, stepX?, stepY?, index?, direction?) | Set both x and y; y defaults to x | | SetAlpha | (items, value, step?, index?, direction?) | Set alpha | | SetBlendMode | (items, value, index?, direction?) | Set blend mode | | SetDepth | (items, value, step?, index?, direction?) | Set render depth | | SetHitArea | (items, hitArea?, callback?) | Set interactive hit area | | SetOrigin | (items, originX, originY?, stepX?, stepY?, index?, direction?) | Set origin point | | SetRotation | (items, value, step?, index?, direction?) | Set rotation (radians) | | SetScale | (items, scaleX, scaleY?, stepX?, stepY?, index?, direction?) | Set both scale axes | | SetScaleX | (items, value, step?, index?, direction?) | Set scaleX | | SetScaleY | (items, value, step?, index?, direction?) | Set scaleY | | SetScrollFactor | (items, x, y?, stepX?, stepY?, index?, direction?) | Set scroll factor | | SetScrollFactorX | (items, value, step?, index?, direction?) | Set horizontal scroll factor | | SetScrollFactorY | (items, value, step?, index?, direction?) | Set vertical scroll factor | | SetTint | (items, topLeft, topRight?, bottomLeft?, bottomRight?) | Set tint color(s) | | SetVisible | (items, value, index?, direction?) | Set visibility | | PropertyValueSet | (items, key, value, step?, index?, direction?) | Generic: set any named property | ### Property Incrementers | Action | Signature | Description | |---|---|---| | IncX | (items, value, step?, index?, direction?) | Add to x | | IncXY | (items, x, y?, stepX?, stepY?, index?, direction?) | Add to x and y | | IncY | (items, value, step?, index?, direction?) | Add to y | | IncAlpha | (items, value, step?, index?, direction?) | Add to alpha | | Angle | (items, value, step?, index?, direction?) | Add to angle (degrees) | | Rotate | (items, value, step?, index?, direction?) | Add to rotation (radians) | | ScaleX | (items, value, step?, index?, direction?) | Add to scaleX | | ScaleXY | (items, scaleX, scaleY?, stepX?, stepY?, index?, direction?) | Add to both scale axes | | ScaleY | (items, value, step?, index?, direction?) | Add to scaleY | | PropertyValueI