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 ```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` | | `PropertyValueInc` | `(items, key, value, step?, index?, direction?)` | Generic: increment any named property | ### Placement on Geometry | Action | Signature | Description | |---|---|---| | `PlaceOnCircle` | `(items, circle, startAngle?, endAngle?)` | Evenly space on circle perimeter | | `PlaceOnEllipse` | `(items, ellipse, startAngle?, endAngle?)` | Evenly space on ellipse perimeter | | `PlaceOnLine` | `(items, line)` | Evenly space along a line | | `PlaceOnRectangle` | `(items, rect, shift?)` | Evenly space on rectangle perimeter | | `PlaceOnTriangle` | `(items, triangle, stepRate?)` | Evenly space on triangle perimeter | | `RandomCircle` | `(items, circle)` | Random positions within a circle | | `RandomEllipse` | `(items, ellipse)` | Random positions within an ellipse | | `RandomLine` | `(items, line)` | Random positions along a line | | `RandomRectangle` | `(items, rect)` | Random positions within a rectangle | | `RandomTriangle` | `(items, triangle)` | Random positions within a triangle | ### Layout and Alignment | Action | Signature | Description | |---|---|---| | `GridAlign` | `(items, config)` | Arrange in grid; config: `{ width, height, cellWidth, cellHeight, position, x, y }` | | `AlignTo` | `(items, position, offsetX?, offsetY?)` | Chain-align each item next to the previous one using `Phaser.Display.Align` constants | | `FitToRegion` | `(items, scaleMode?, region?, itemCoverage?)` | Scale/position each GO to fill a rectangle (v4.0.0+). scaleMode: 0=stretch, -1=fit inside, 1=cover outside | ### Distribution and Interpolation | Action | Signature | Description | |---|---|---| | `Spread` | `(items, property, min, max, inc?)` | Linearly distribute a property from `min` to `max` across all items | | `SmoothStep` | `(items, property, min, max, inc?)` | Distribute using Hermite smoothstep interpolation | | `SmootherStep` | `(items, property, min, max, inc?)` | Distribute using Ken Perlin's smootherstep | ### Rotation and Movement | Action | Signature | Description | |---|---|---| | `RotateAround` | `(items, point, angle)` | Rotate all items around a point (radians) | | `RotateAroundDistance` | `(items, point, angle, distance)` | Rotate around a point at a fixed distance | | `ShiftPosition` | `(items, x, y, direction?, output?)` | Snake-like: move head to x/y, each item takes position of the previous | | `WrapInRectangle` | `(items, rect, padding?)` | Wrap x/y to stay within rectangle bounds | ### Queries and Iteration | Action | Signature | Description | |---|---|---| | `GetFirst` | `(items, compare, index?)` | Find first item matching all properties in `compare` object | | `GetLast` | `(items, compare, index?)` | Find last item matching all properties in `compare` object | | `Call` | `(items, callback, context)` | Invoke callback for each item | | `Shuffle` | `(items)` | Randomly reorder the array (Fisher-Yates) | | `ToggleVisible` | `(items)` | Toggle `visible` on each item | | `PlayAnimation` | `(items, key, ignoreIfPlaying?)` | Play animation on all items with an `anims` component | ### Effects (v4.0.0+) | Action | Signature | Description | |---|---|---| | `AddEffectBloom` | `(items, config?)` | Add Bloom filter effect to a Camera or GO. Returns `{ parallelFilters, threshold, blur }[]` | | `AddEffectShine` | `(items, config?)` | Add Shine filter effect | | `AddMaskShape` | `(items, config?)` | Apply a shape-based mask (circle, square, rectangle, ellipse) with optional blur | --- ## Array Utilities Namespace: `Phaser.Utils.Array` | Function | Signature | Description | |---|---|---| | `Add` | `(array, item, limit?, callback?, context?)` | Add item(s) if not already present; optional size limit | | `AddAt` | `(array, item, index?, limit?, callback?, context?)` | Insert item(s) at index | | `BringToTop` | `(array, item)` | Move item to end of array | | `CountAllMatching` | `(array, property, value, startIndex?, endIndex?)` | Count items where property equals value | | `Each` | `(array, callback, context, ...args)` | Iterate with callback; passes item + extra args | | `EachInRange` | `(array, callback, context, startIndex, endIndex, ...args)` | Iterate a slice with callback | | `FindClosestInSorted` | `(value, array, key?)` | Binary-search style closest match in sorted array | | `Flatten` | `(array, output?)` | Flatten nested arrays into a single array | | `GetAll` | `(array, property?, value?, startIndex?, endIndex?)` | Filter items matching property/value | | `GetFirst` | `(array, property?, value?, startIndex?, endIndex?)` | First item matching property/value | | `GetRandom` | `(array, startIndex?, length?)` | Return a random element | | `MoveAbove` | `(array, item1, item2)` | Move item2 directly above item1 | | `MoveBelow` | `(array, item1, item2)` | Move item2 directly below item1 | | `MoveDown` | `(array, item)` | Move item one position toward index 0 | | `MoveTo` | `(array, item, index)` | Move item to specific index | | `MoveUp` | `(array, item)` | Move item one position toward end | | `NumberArray` | `(start, end, prefix?, suffix?)` | Generate `[start..end]` range; optional string prefix/suffix | | `NumberArrayStep` | `(start?, end?, step?)` | Generate range with custom step size | | `QuickSelect` | `(array, k, left?, right?, compare?)` | Partial sort: kth smallest element in-place | | `Range` | `(a, b, options?)` | Generate array from range config |