0
# Actions System
1

2
Phaser's Actions system provides over 65 utility functions for performing batch operations on arrays of GameObjects. These functions enable efficient manipulation of multiple objects simultaneously, perfect for managing groups, collections, and bulk transformations.
3

4
## Capabilities
5

6
### Positioning Actions
7

8
Bulk positioning and alignment operations for multiple GameObjects:
9

10
```javascript { .api }
11
// Set absolute positions
12
Phaser.Actions.SetX(gameObjects, 100);              // Set all X positions to 100
13
Phaser.Actions.SetY(gameObjects, 200);              // Set all Y positions to 200
14
Phaser.Actions.SetXY(gameObjects, 100, 200);        // Set both X and Y positions
15

16
// Incremental positioning
17
Phaser.Actions.IncX(gameObjects, 50);               // Add 50 to each X position
18
Phaser.Actions.IncY(gameObjects, -30);              // Subtract 30 from each Y position
19
Phaser.Actions.IncXY(gameObjects, 10, 20);          // Add to both X and Y
20

21
// Shift positions (with optional distance and direction)
22
Phaser.Actions.ShiftPosition(gameObjects, 100, 45); // Shift 100 pixels at 45 degrees
23

24
// Alignment operations
25
Phaser.Actions.AlignTo(gameObjects, Phaser.Display.Align.CENTER);
26
Phaser.Actions.AlignTo(gameObjects, Phaser.Display.Align.TOP_LEFT);
27
Phaser.Actions.AlignTo(gameObjects, Phaser.Display.Align.BOTTOM_RIGHT);
28

29
// Grid alignment
30
Phaser.Actions.GridAlign(gameObjects, {
31
    width: 5,                    // 5 columns
32
    height: 4,                   // 4 rows
33
    cellWidth: 64,               // Cell width
34
    cellHeight: 64,              // Cell height
35
    x: 100,                      // Starting X
36
    y: 100                       // Starting Y
37
});
38
```
39

40
### Geometric Placement
41

42
Place GameObjects along geometric shapes and patterns:
43

44
```javascript { .api }
45
// Circle placement
46
Phaser.Actions.PlaceOnCircle(gameObjects, new Phaser.Geom.Circle(400, 300, 150));
47

48
// Ellipse placement
49
Phaser.Actions.PlaceOnEllipse(gameObjects, new Phaser.Geom.Ellipse(400, 300, 200, 100));
50

51
// Line placement
52
Phaser.Actions.PlaceOnLine(gameObjects, new Phaser.Geom.Line(100, 100, 500, 400));
53

54
// Rectangle placement (around perimeter)
55
Phaser.Actions.PlaceOnRectangle(gameObjects, new Phaser.Geom.Rectangle(200, 150, 300, 200));
56

57
// Triangle placement
58
Phaser.Actions.PlaceOnTriangle(gameObjects, new Phaser.Geom.Triangle(400, 100, 200, 400, 600, 400));
59

60
// Advanced circle placement with start angle and step
61
Phaser.Actions.PlaceOnCircle(gameObjects, circle, 0, Math.PI / 4); // Start at 0, step by 45 degrees
62
```
63

64
### Random Placement
65

66
Randomly position GameObjects within geometric bounds:
67

68
```javascript { .api }
69
// Random positions within shapes
70
Phaser.Actions.RandomCircle(gameObjects, new Phaser.Geom.Circle(400, 300, 100));
71
Phaser.Actions.RandomEllipse(gameObjects, new Phaser.Geom.Ellipse(400, 300, 200, 100));
72
Phaser.Actions.RandomLine(gameObjects, new Phaser.Geom.Line(100, 100, 500, 100));
73
Phaser.Actions.RandomRectangle(gameObjects, new Phaser.Geom.Rectangle(100, 100, 400, 300));
74
Phaser.Actions.RandomTriangle(gameObjects, new Phaser.Geom.Triangle(400, 100, 200, 400, 600, 400));
75

76
// Shuffle array order
77
Phaser.Actions.Shuffle(gameObjects);
78

79
// Example: Randomly scatter enemies
80
const enemies = scene.add.group();
81
for (let i = 0; i < 10; i++) {
82
    enemies.create(0, 0, 'enemy');
83
}
84
Phaser.Actions.RandomRectangle(enemies.children.entries, new Phaser.Geom.Rectangle(0, 0, 800, 600));
85
```
86

87
### Visual Property Actions
88

89
Bulk manipulation of visual properties:
90

91
```javascript { .api }
92
// Alpha/transparency
93
Phaser.Actions.SetAlpha(gameObjects, 0.5);          // Set all to 50% opacity
94
Phaser.Actions.SetAlpha(gameObjects, 0.2, 0.1);     // Start at 0.2, increment by 0.1
95
Phaser.Actions.IncAlpha(gameObjects, -0.1);         // Decrease alpha by 0.1
96

97
// Scaling
98
Phaser.Actions.SetScale(gameObjects, 2);            // Set all to 2x scale
99
Phaser.Actions.SetScale(gameObjects, 0.5, 1.5);     // Start at 0.5, end at 1.5
100
Phaser.Actions.SetScaleX(gameObjects, 2);           // Set X scale only
101
Phaser.Actions.SetScaleY(gameObjects, 0.5);         // Set Y scale only
102
Phaser.Actions.ScaleX(gameObjects, 1.1);            // Multiply X scale by 1.1
103
Phaser.Actions.ScaleY(gameObjects, 0.9);            // Multiply Y scale by 0.9
104
Phaser.Actions.ScaleXY(gameObjects, 1.1, 0.9);      // Scale both axes
105

106
// Rotation
107
Phaser.Actions.SetRotation(gameObjects, Math.PI / 4); // Set all to 45 degrees
108
Phaser.Actions.SetRotation(gameObjects, 0, Math.PI / 8); // Start at 0, increment by 22.5 degrees
109
Phaser.Actions.Rotate(gameObjects, 0.1);             // Add 0.1 radians to rotation
110

111
// Origin point
112
Phaser.Actions.SetOrigin(gameObjects, 0.5, 0);       // Set origin to top-center
113
Phaser.Actions.SetOrigin(gameObjects, 0, 1);         // Set origin to bottom-left
114

115
// Visibility
116
Phaser.Actions.SetVisible(gameObjects, false);       // Hide all objects
117
Phaser.Actions.ToggleVisible(gameObjects);           // Toggle visibility state
118

119
// Depth (z-order)
120
Phaser.Actions.SetDepth(gameObjects, 100);           // Set all to depth 100
121
Phaser.Actions.SetDepth(gameObjects, 50, 10);        // Start at 50, increment by 10
122

123
// Tinting
124
Phaser.Actions.SetTint(gameObjects, 0xff0000);       // Tint all red
125
Phaser.Actions.SetTint(gameObjects, 0xffffff);       // Remove tint (white)
126

127
// Blend modes
128
Phaser.Actions.SetBlendMode(gameObjects, Phaser.BlendModes.ADD);
129
Phaser.Actions.SetBlendMode(gameObjects, Phaser.BlendModes.MULTIPLY);
130
```
131

132
### Selection and Filtering Actions
133

134
Get specific objects from arrays:
135

136
```javascript { .api }
137
// Get first/last objects
138
const first = Phaser.Actions.GetFirst(gameObjects, { active: true });
139
const last = Phaser.Actions.GetLast(gameObjects, { visible: true });
140

141
// Get objects by properties
142
const healthyEnemies = Phaser.Actions.GetFirst(enemies, { health: 100 }, 5); // Get first 5 with health = 100
143

144
// Custom filtering with callback
145
function isAlive(gameObject) {
146
    return gameObject.getData('health') > 0;
147
}
148
const aliveEnemies = gameObjects.filter(isAlive);
149
```
150

151
### Property Manipulation
152

153
Set or increment custom properties on multiple objects:
154

155
```javascript { .api }
156
// Set property values
157
Phaser.Actions.PropertyValueSet(gameObjects, 'health', 100);           // Set health to 100
158
Phaser.Actions.PropertyValueSet(gameObjects, 'speed', 150, 50);        // Start at 150, increment by 50
159

160
// Increment property values
161
Phaser.Actions.PropertyValueInc(gameObjects, 'experience', 25);        // Add 25 experience
162
Phaser.Actions.PropertyValueInc(gameObjects, 'level', 1, 0);           // Add 1 level, starting at 0
163

164
// Example: Level up all players
165
const players = scene.children.getByName('player');
166
Phaser.Actions.PropertyValueInc(players, 'level', 1);
167
Phaser.Actions.PropertyValueSet(players, 'experience', 0); // Reset experience
168
```
169

170
### Utility Actions
171

172
Additional utility functions for array manipulation:
173

174
```javascript { .api }
175
// Call function on each object
176
Phaser.Actions.Call(gameObjects, function(gameObject) {
177
    gameObject.setInteractive();
178
    gameObject.on('pointerdown', handleClick);
179
});
180

181
// Call method with parameters
182
Phaser.Actions.Call(gameObjects, 'setTint', 0xff0000);  // Call setTint(0xff0000) on each
183

184
// Wrap objects within boundaries
185
const bounds = new Phaser.Geom.Rectangle(0, 0, 800, 600);
186
Phaser.Actions.WrapInRectangle(gameObjects, bounds);
187

188
// Example: Update all enemies
189
Phaser.Actions.Call(enemies.children.entries, function(enemy) {
190
    // Custom update logic for each enemy
191
    enemy.update();
192
    
193
    // Check if enemy is dead
194
    if (enemy.getData('health') <= 0) {
195
        enemy.destroy();
196
    }
197
});
198
```
199

200
### Advanced Usage Patterns
201

202
```javascript { .api }
203
// Combine multiple actions
204
const powerUps = scene.add.group();
205
for (let i = 0; i < 8; i++) {
206
    powerUps.create(0, 0, 'powerup');
207
}
208

209
// Apply multiple transformations
210
Phaser.Actions.PlaceOnCircle(powerUps.children.entries, new Phaser.Geom.Circle(400, 300, 150));
211
Phaser.Actions.SetScale(powerUps.children.entries, 0.5, 0.1);  // Scale from 0.5 to 1.3
212
Phaser.Actions.SetRotation(powerUps.children.entries, 0, Math.PI / 4); // Rotate each differently
213
Phaser.Actions.SetDepth(powerUps.children.entries, 100);
214

215
// Conditional actions based on properties
216
function applyToVisibleObjects(gameObjects, action, ...params) {
217
    const visibleObjects = gameObjects.filter(obj => obj.visible);
218
    action(visibleObjects, ...params);
219
}
220

221
applyToVisibleObjects(enemies, Phaser.Actions.SetTint, 0xff0000);
222

223
// Animated sequences using actions
224
function createFormation(objects, formationType) {
225
    switch(formationType) {
226
        case 'circle':
227
            Phaser.Actions.PlaceOnCircle(objects, new Phaser.Geom.Circle(400, 300, 150));
228
            break;
229
        case 'line':
230
            Phaser.Actions.PlaceOnLine(objects, new Phaser.Geom.Line(100, 300, 700, 300));
231
            break;
232
        case 'grid':
233
            Phaser.Actions.GridAlign(objects, {
234
                width: Math.ceil(Math.sqrt(objects.length)),
235
                height: Math.ceil(Math.sqrt(objects.length)),
236
                cellWidth: 80,
237
                cellHeight: 80,
238
                x: 200,
239
                y: 200
240
            });
241
            break;
242
    }
243
}
244

245
// Performance optimization: Batch operations
246
function optimizedBulkUpdate(gameObjects) {
247
    // Collect all operations and apply them in batches
248
    const operations = [];
249
    
250
    operations.push(() => Phaser.Actions.IncY(gameObjects, -2)); // Move up
251
    operations.push(() => Phaser.Actions.Rotate(gameObjects, 0.01)); // Rotate slightly
252
    operations.push(() => Phaser.Actions.IncAlpha(gameObjects, -0.001)); // Fade out
253
    
254
    // Execute all operations
255
    operations.forEach(operation => operation());
256
    
257
    // Remove invisible objects
258
    const visibleObjects = gameObjects.filter(obj => obj.alpha > 0);
259
    return visibleObjects;
260
}
261
```
262

263
### Integration with Groups and Physics
264

265
```javascript { .api }
266
// Using with Phaser Groups
267
const bullets = scene.add.group();
268
const enemies = scene.add.group();
269

270
// Create bullets in formation
271
for (let i = 0; i < 5; i++) {
272
    bullets.create(100, 300, 'bullet');
273
}
274

275
// Arrange bullets and set properties
276
Phaser.Actions.PlaceOnLine(bullets.children.entries, new Phaser.Geom.Line(100, 300, 500, 300));
277
Phaser.Actions.PropertyValueSet(bullets.children.entries, 'speed', 200, 50); // Varying speeds
278

279
// Physics integration
280
const physicsSprites = scene.physics.add.group();
281
for (let i = 0; i < 10; i++) {
282
    physicsSprites.create(Phaser.Math.Between(100, 700), 100, 'falling_object');
283
}
284

285
// Set physics properties using actions
286
Phaser.Actions.Call(physicsSprites.children.entries, function(sprite) {
287
    sprite.body.setVelocityY(Phaser.Math.Between(100, 300));
288
    sprite.body.setBounce(0.8);
289
});
290
```
291

292
## Types
293

294
```javascript { .api }
295
// Action Function Signatures
296
namespace Phaser.Actions {
297
    // Positioning
298
    function SetX(items: any[], value: number, step?: number, index?: number, direction?: number): any[];
299
    function SetY(items: any[], value: number, step?: number, index?: number, direction?: number): any[];
300
    function SetXY(items: any[], x: number, y?: number, stepX?: number, stepY?: number, indexX?: number, indexY?: number, directionX?: number, directionY?: number): any[];
301
    function IncX(items: any[], value: number, index?: number, direction?: number): any[];
302
    function IncY(items: any[], value: number, index?: number, direction?: number): any[];
303
    function IncXY(items: any[], x: number, y?: number, index?: number, direction?: number): any[];
304
    
305
    // Geometric Placement
306
    function PlaceOnCircle(items: any[], circle: Phaser.Geom.Circle, startAngle?: number, endAngle?: number): any[];
307
    function PlaceOnEllipse(items: any[], ellipse: Phaser.Geom.Ellipse, startAngle?: number, endAngle?: number): any[];
308
    function PlaceOnLine(items: any[], line: Phaser.Geom.Line): any[];
309
    function PlaceOnRectangle(items: any[], rect: Phaser.Geom.Rectangle, shift?: number): any[];
310
    function PlaceOnTriangle(items: any[], triangle: Phaser.Geom.Triangle, stepRate?: number): any[];
311
    
312
    // Random Placement
313
    function RandomCircle(items: any[], circle: Phaser.Geom.Circle): any[];
314
    function RandomEllipse(items: any[], ellipse: Phaser.Geom.Ellipse): any[];
315
    function RandomLine(items: any[], line: Phaser.Geom.Line): any[];
316
    function RandomRectangle(items: any[], rect: Phaser.Geom.Rectangle): any[];
317
    function RandomTriangle(items: any[], triangle: Phaser.Geom.Triangle): any[];
318
    function Shuffle(items: any[]): any[];
319
    
320
    // Visual Properties
321
    function SetAlpha(items: any[], value: number, step?: number, index?: number, direction?: number): any[];
322
    function SetScale(items: any[], scaleX: number, scaleY?: number, stepX?: number, stepY?: number, index?: number, direction?: number): any[];
323
    function SetRotation(items: any[], value: number, step?: number, index?: number, direction?: number): any[];
324
    function SetTint(items: any[], topLeft: number, topRight?: number, bottomLeft?: number, bottomRight?: number): any[];
325
    function SetVisible(items: any[], value: boolean, index?: number, direction?: number): any[];
326
    
327
    // Utility
328
    function Call(items: any[], callback: string | function, ...args: any[]): any[];
329
    function GetFirst(items: any[], compare: object, index?: number): any;
330
    function GetLast(items: any[], compare: object, index?: number): any;
331
    function PropertyValueSet(items: any[], key: string, value: any, step?: number, index?: number, direction?: number): any[];
332
    function PropertyValueInc(items: any[], key: string, value: any, step?: number, index?: number, direction?: number): any[];
333
}
334
```