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:

First argument is always an array of Game Objects (or any objects with the required public properties like x, y, alpha, etc.).
Returns the same array, enabling chaining or pass-through.
Works with Groups by passing group.getChildren().
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
`Remove`	`(array, item, callback?, context?)`	Remove item(s) from array
`RemoveAt`	`(array, index, callback?, context?)`	Remove item at index
`RemoveBetween`	`(array, startIndex, endIndex, callback?, context?)`	Remove items in range
`RemoveRandomElement`	`(array, startIndex?, length?)`	Remove and return a random element
`Replace`	`(array, oldItem, newItem)`	Swap one item for another
`RotateLeft`	`(array, total?)`	Shift elements left; last wraps to front
`RotateRight`	`(array, total?)`	Shift elements right; first wraps to end
`SafeRange`	`(array, startIndex, endIndex, throwError?)`	Validate index range is within bounds
`SendToBack`	`(array, item)`	Move item to index 0
`SetAll`	`(array, property, value, startIndex?, endIndex?)`	Set a property on all items in range
`Shuffle`	`(array)`	Fisher-Yates shuffle; modifies in-place
`SortByDigits`	`(array)`	Sort strings by embedded numeric values
`SpliceOne`	`(array, index)`	Fast single-element splice
`StableSort`	`(array, compare?)`	Guaranteed stable sort (merge sort fallback for engines without native stable sort)
`Swap`	`(array, item1, item2)`	Swap two items in-place

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

Object Utilities

Namespace: Phaser.Utils.Objects

Function	Signature	Description
`Clone`	`(obj)`	Shallow clone of object
`DeepCopy`	`(obj)`	Recursive deep copy of object or array
`Extend`	`(target, ...sources)`	jQuery-style extend; copies properties from sources to target
`GetAdvancedValue`	`(source, key, defaultValue)`	Like `GetValue` but resolves random/callback config values
`GetFastValue`	`(source, key, defaultValue?)`	Top-level-only property lookup; no dot-path support. Faster than `GetValue`
`GetMinMaxValue`	`(source, key, min, max, defaultValue)`	Get value clamped between min and max
`GetValue`	`(source, key, defaultValue, altSource?)`	Dot-path property lookup (e.g. `'render.screen.width'`). Falls back to altSource then defaultValue
`HasAll`	`(source, keys)`	True if source has ALL listed keys
`HasAny`	`(source, keys)`	True if source has ANY listed key
`HasValue`	`(source, key)`	True if source has the key
`IsPlainObject`	`(obj)`	True if obj is a plain `{}` object (not DOM, not window)
`Merge`	`(obj1, obj2)`	Merge obj2 into a clone of obj1
`MergeRight`	`(obj1, obj2)`	Merge obj1 into a clone of obj2
`Pick`	`(source, keys)`	Return new object with only the specified keys
`SetValue`	`(source, key, value)`	Set a dot-path property value

String Utilities

Namespace: Phaser.Utils.String

Function	Signature	Description
`Format`	`(string, values)`	Replace `%1`, `%2`, etc. markers with array values
`Pad`	`(str, len?, pad?, dir?)`	Pad string to length. dir: 1=left, 2=right, default=both
`RemoveAt`	`(string, index)`	Remove character at index
`Reverse`	`(string)`	Reverse the string
`UppercaseFirst`	`(string)`	Capitalize first character
`UUID`	`()`	Generate RFC4122 v4 UUID 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

Area	Path
All Actions	`src/actions/`
Actions index	`src/actions/index.js`
Core set/inc helpers	`src/actions/PropertyValueSet.js`, `src/actions/PropertyValueInc.js`
GridAlign config typedef	`src/actions/typedefs/`
Array utilities	`src/utils/array/`
Array matrix utils	`src/utils/array/matrix/`
Object utilities	`src/utils/object/`
String utilities	`src/utils/string/`

actions-and-utilities