phaserjs/phaser624 installs

actions-and-utilities

Q: How do I install this agent skill?

Run npx skills add https://github.com/phaserjs/phaser --skill actions-and-utilities.

Q: Is this agent skill safe to install?

Review the displayed partner audits, complete source, permissions, dependencies, and exact revision before installing.

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.

How do I install this agent skill?

npx skills add https://github.com/phaserjs/phaser --skill actions-and-utilities

view source ↗

Is this agent skill safe to install?

Gen Agent Trust Hubpass
The skill provides documentation and code examples for Phaser 4 utility functions, batch actions, and object/array management. No security vulnerabilities or malicious patterns were detected.
Socketpass
No alerts
Snykpass
Risk: LOW · No issues

What does this agent skill do?

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/`

How can the creator link this skill?

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/phaserjs/phaser/actions-and-utilities">View actions-and-utilities on skillZs</a>