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

NPX Install

Tags

SKILL.md Content

Phaser 4 -- Actions & Utility Functions

Quick Start

Core Concepts

The Actions Pattern

PropertyValueSet and PropertyValueInc

Geometry-Based Placement

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

Object Utilities

String Utilities

Common Patterns

Using Actions with Groups

Step Parameter for Staggered Values

Scatter Then Constrain

GetValue for Config Parsing

NumberArray for Asset Keys

Gotchas

Source File Map