Actions And UtilitiesSAFE

Phaser is a fun, free and fast 2D game framework for making HTML5 games for desktop and mobile web browsers, supporting Canvas and WebGL rendering.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

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

##

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Actions And Utilities](https://modelsatlas.com/skills/phaserjs/actions-and-utilities/badge.svg)](https://modelsatlas.com/skills/phaserjs/actions-and-utilities/)

Not your listing, or something out of date? Claim or update your listing.