0
# Phaser 3.90.0
1
2
## Overview
3
4
Phaser is a fast, free, and fun HTML5 game framework for desktop and mobile web browsers. It provides a comprehensive suite of tools for 2D game development with WebGL and Canvas rendering support, physics engines, input handling, audio management, and much more.
5
6
Phaser follows a modular architecture centered around Scenes, GameObjects, and Systems that work together to create interactive games and applications.
7
8
## Package Information
9
10
- **Package Name**: phaser
11
- **Package Type**: npm
12
- **Language**: JavaScript/TypeScript
13
- **Installation**: `npm install phaser`
14
15
## Core Imports
16
17
### CommonJS
18
```javascript { .api }
19
const Phaser = require('phaser');
20
```
21
22
### ES Modules
23
```javascript { .api }
24
import Phaser from 'phaser';
25
```
26
27
### CDN
28
```html { .api }
29
<script src="https://cdn.jsdelivr.net/npm/phaser@3.90.0/dist/phaser.min.js"></script>
30
```
31
32
## Basic Usage
33
34
### Game Initialization
35
```javascript { .api }
36
const config = {
37
type: Phaser.AUTO,
38
width: 800,
39
height: 600,
40
scene: {
41
preload: preload,
42
create: create,
43
update: update
44
}
45
};
46
47
const game = new Phaser.Game(config);
48
49
function preload() {
50
this.load.image('logo', 'assets/logo.png');
51
}
52
53
function create() {
54
this.add.image(400, 300, 'logo');
55
}
56
57
function update() {
58
// Game loop logic
59
}
60
```
61
62
### Scene Class Approach
63
```javascript { .api }
64
class GameScene extends Phaser.Scene {
65
constructor() {
66
super({ key: 'GameScene' });
67
}
68
69
preload() {
70
this.load.image('background', 'assets/bg.jpg');
71
this.load.spritesheet('player', 'assets/player.png', {
72
frameWidth: 32,
73
frameHeight: 48
74
});
75
}
76
77
create() {
78
this.add.image(0, 0, 'background').setOrigin(0);
79
this.player = this.add.sprite(100, 450, 'player');
80
}
81
82
update() {
83
// Update logic
84
}
85
}
86
87
const game = new Phaser.Game({
88
type: Phaser.AUTO,
89
width: 800,
90
height: 600,
91
scene: GameScene
92
});
93
```
94
95
## Architecture
96
97
Phaser uses a component-based architecture with the following key concepts:
98
99
### Game Instance
100
The root `Phaser.Game` object manages the entire game lifecycle, including scenes, rendering, input, and system updates.
101
102
### Scenes
103
Scenes are self-contained game states (menu, gameplay, game over). Each scene has its own:
104
- Display list (rendered objects)
105
- Update list (objects that receive update calls)
106
- Input handling
107
- Physics world
108
- Camera system
109
110
### GameObjects
111
All visual and interactive elements inherit from `Phaser.GameObjects.GameObject`. Common objects include Sprites, Images, Text, Graphics, and Containers.
112
113
### Systems
114
Scenes contain various systems for managing different aspects:
115
- `scene.add` - GameObject factory
116
- `scene.input` - Input handling
117
- `scene.physics` - Physics simulation
118
- `scene.cameras` - Camera management
119
- `scene.tweens` - Animation tweening
120
121
## Capabilities
122
123
### [Game Objects](game-objects.md)
124
Comprehensive collection of display objects for creating game content.
125
126
**Key APIs:**
127
```javascript { .api }
128
// Sprites with texture animation support
129
scene.add.sprite(x, y, 'texture', frame);
130
131
// Static images
132
scene.add.image(x, y, 'texture');
133
134
// Text rendering with styling
135
scene.add.text(x, y, 'Hello World', { fontSize: '32px', fill: '#000' });
136
137
// Vector graphics drawing
138
const graphics = scene.add.graphics();
139
graphics.fillRect(0, 0, 100, 100);
140
141
// Containers for grouping objects
142
const container = scene.add.container(x, y);
143
container.add([sprite1, sprite2, text]);
144
```
145
146
**Coverage:** Sprites, Images, Text, Graphics, Containers, Shapes, Particle Systems, Video, DOM Elements, WebGL Shaders, 3D Objects
147
148
### [Scene Management](scenes.md)
149
Scene lifecycle management and transitions between game states.
150
151
**Key APIs:**
152
```javascript { .api }
153
// Scene transitions
154
scene.scene.start('NextScene', data);
155
scene.scene.pause();
156
scene.scene.resume();
157
158
// Multiple scenes
159
scene.scene.launch('UIScene');
160
scene.scene.run('BackgroundScene');
161
```
162
163
**Coverage:** Scene lifecycle, transitions, parallel scenes, data passing, scene plugins
164
165
### [Input Handling](input.md)
166
Multi-platform input support for keyboard, mouse, touch, and gamepad.
167
168
**Key APIs:**
169
```javascript { .api }
170
// Keyboard input
171
const cursors = scene.input.keyboard.createCursorKeys();
172
if (cursors.left.isDown) { /* move left */ }
173
174
// Mouse/touch input
175
scene.input.on('pointerdown', (pointer) => {
176
console.log('Clicked at:', pointer.x, pointer.y);
177
});
178
179
// Interactive objects
180
sprite.setInteractive();
181
sprite.on('pointerdown', () => { /* handle click */ });
182
```
183
184
**Coverage:** Keyboard, mouse, touch, gamepad, interactive objects, drag and drop
185
186
### [Animation Systems](animation.md)
187
Frame-based animations and tweening for smooth visual effects.
188
189
**Key APIs:**
190
```javascript { .api }
191
// Create frame animation
192
scene.anims.create({
193
key: 'walk',
194
frames: scene.anims.generateFrameNumbers('player', { start: 0, end: 3 }),
195
frameRate: 10,
196
repeat: -1
197
});
198
199
// Tween animations
200
scene.tweens.add({
201
targets: sprite,
202
x: 400,
203
duration: 2000,
204
ease: 'Power2'
205
});
206
```
207
208
**Coverage:** Sprite animations, tweens, timelines, easing functions, animation events
209
210
### [Physics Systems](physics.md)
211
Physics simulation with Arcade Physics (fast) and Matter.js (realistic).
212
213
**Key APIs:**
214
```javascript { .api }
215
// Enable Arcade Physics
216
scene.physics.add.sprite(x, y, 'texture');
217
218
// Collision detection
219
scene.physics.add.collider(player, platforms);
220
221
// Matter.js physics bodies
222
scene.matter.add.rectangle(x, y, width, height);
223
```
224
225
**Coverage:** Arcade Physics, Matter.js integration, collision detection, physics groups, constraints
226
227
### [Camera System](cameras.md)
228
Flexible camera system with effects, following, and multi-camera support.
229
230
**Key APIs:**
231
```javascript { .api }
232
// Camera controls
233
scene.cameras.main.startFollow(player);
234
scene.cameras.main.setZoom(2);
235
236
// Camera effects
237
scene.cameras.main.shake(1000, 0.05);
238
scene.cameras.main.fade(1000);
239
240
// Multiple cameras
241
const camera2 = scene.cameras.add(100, 100, 200, 200);
242
```
243
244
**Coverage:** Camera movement, following, effects, bounds, multiple cameras
245
246
### [Audio Management](audio.md)
247
Comprehensive audio system with Web Audio API and HTML5 Audio support.
248
249
**Key APIs:**
250
```javascript { .api }
251
// Load and play sounds
252
scene.load.audio('music', 'assets/music.mp3');
253
const music = scene.sound.add('music');
254
music.play();
255
256
// Audio sprites
257
scene.load.audioSprite('sfx', 'assets/sounds.json', 'assets/sounds.mp3');
258
scene.sound.playAudioSprite('sfx', 'jump');
259
```
260
261
**Coverage:** Audio loading, playback, audio sprites, 3D audio, sound effects
262
263
### [Asset Loading](loading.md)
264
Flexible asset loading system supporting multiple file types and loading strategies.
265
266
**Key APIs:**
267
```javascript { .api }
268
// Load various asset types
269
scene.load.image('logo', 'assets/logo.png');
270
scene.load.spritesheet('player', 'assets/player.png', { frameWidth: 32, frameHeight: 48 });
271
scene.load.atlas('atlas', 'assets/atlas.png', 'assets/atlas.json');
272
scene.load.audio('music', 'assets/music.mp3');
273
274
// Loading events
275
scene.load.on('progress', (percent) => {
276
console.log('Loading:', Math.round(percent * 100) + '%');
277
});
278
```
279
280
**Coverage:** Image loading, spritesheets, atlases, audio, JSON, XML, binary data, asset packs
281
282
### [Math & Geometry](math-geometry.md)
283
Comprehensive mathematical functions and geometric operations.
284
285
**Key APIs:**
286
```javascript { .api }
287
// Vector math
288
const vector = new Phaser.Math.Vector2(x, y);
289
vector.normalize().scale(100);
290
291
// Geometric shapes
292
const circle = new Phaser.Geom.Circle(x, y, radius);
293
const rect = new Phaser.Geom.Rectangle(x, y, width, height);
294
295
// Intersection testing
296
Phaser.Geom.Intersects.CircleToRectangle(circle, rect);
297
```
298
299
**Coverage:** Vector math, matrices, geometric shapes, intersection testing, interpolation, easing
300
301
### [Rendering & Display](rendering.md)
302
WebGL and Canvas rendering with textures, effects, and display management.
303
304
**Key APIs:**
305
```javascript { .api }
306
// Texture management
307
scene.textures.addBase64('key', base64Data);
308
scene.textures.create('canvas', canvasElement);
309
310
// Blend modes and effects
311
sprite.setBlendMode(Phaser.BlendModes.ADD);
312
sprite.setTint(0xff0000);
313
314
// Render textures
315
const renderTexture = scene.add.renderTexture(x, y, width, height);
316
renderTexture.draw(sprite);
317
```
318
319
**Coverage:** WebGL/Canvas rendering, textures, blend modes, shaders, render textures, display utilities
320
321
### [Tweens & Timeline Animation](tweens.md)
322
Property tweening and complex animation sequences for smooth visual transitions.
323
324
**Key APIs:**
325
```javascript { .api }
326
// Property tweening
327
scene.tweens.add({
328
targets: sprite,
329
x: 400,
330
alpha: 0.5,
331
duration: 2000,
332
ease: 'Power2'
333
});
334
335
// Timeline sequences
336
const timeline = scene.tweens.timeline();
337
timeline.add({ targets: sprite1, x: 200, duration: 1000 });
338
timeline.add({ targets: sprite2, y: 300, duration: 500 });
339
```
340
341
**Coverage:** Individual tweens, tween chains, timelines, easing functions, tween control, property interpolation
342
343
[Tweens](./tweens.md)
344
345
### [Data Management](data-management.md)
346
Key-value data storage with event-driven updates for GameObjects and Scenes.
347
348
**Key APIs:**
349
```javascript { .api }
350
// Store data with events
351
scene.data.set('score', 1500);
352
sprite.data.set('health', 100);
353
354
// Listen for data changes
355
scene.data.on('setdata-score', (parent, key, value) => {
356
updateScoreDisplay(value);
357
});
358
359
// Manipulate numeric data
360
scene.data.inc('score', 100);
361
sprite.data.dec('health', 25);
362
```
363
364
**Coverage:** Scene data management, GameObject data storage, data events, serialization, cross-scene data sharing
365
366
[Data Management](./data-management.md)
367
368
### [Events System](events.md)
369
Comprehensive event-driven communication system throughout the framework.
370
371
**Key APIs:**
372
```javascript { .api }
373
// Event handling
374
scene.events.on('eventName', callback);
375
gameObject.on('pointerdown', handleClick);
376
377
// Event emission
378
scene.events.emit('customEvent', data);
379
380
// Scene lifecycle events
381
scene.events.on('preupdate', updateLogic);
382
scene.events.on('shutdown', cleanup);
383
```
384
385
**Coverage:** EventEmitter pattern, scene events, GameObject events, input events, physics events, custom events
386
387
[Events](./events.md)
388
389
### [Actions System](actions.md)
390
Batch operations for efficiently manipulating arrays of GameObjects.
391
392
**Key APIs:**
393
```javascript { .api }
394
// Bulk positioning
395
Phaser.Actions.SetXY(gameObjects, 100, 200);
396
Phaser.Actions.PlaceOnCircle(gameObjects, circle);
397
Phaser.Actions.GridAlign(gameObjects, { width: 5, height: 4 });
398
399
// Visual properties
400
Phaser.Actions.SetAlpha(gameObjects, 0.5);
401
Phaser.Actions.SetScale(gameObjects, 2);
402
Phaser.Actions.RandomRectangle(gameObjects, bounds);
403
```
404
405
**Coverage:** Positioning actions, geometric placement, random placement, visual properties, utility operations
406
407
[Actions](./actions.md)
408
409
### [Utilities](utilities.md)
410
Essential utility functions for arrays, objects, strings, device detection, and data encoding.
411
412
**Key APIs:**
413
```javascript { .api }
414
// Array manipulation
415
Phaser.Utils.Array.Shuffle(array);
416
Phaser.Utils.Array.GetRandom(array);
417
418
// Object operations
419
Phaser.Utils.Objects.Clone(object);
420
Phaser.Utils.Objects.GetValue(config, 'key', defaultValue);
421
422
// Device detection
423
const device = scene.sys.game.device;
424
if (device.os.mobile) { /* mobile optimizations */ }
425
426
// String utilities
427
const uuid = Phaser.Utils.String.UUID();
428
const encoded = Phaser.Utils.Base64.Encode(data);
429
```
430
431
**Coverage:** Array utilities, object manipulation, string formatting, device/browser detection, Base64 encoding, NOOP functions
432
433
[Utilities](./utilities.md)
434
435
## Constants and Configuration
436
437
### Renderer Types
438
```javascript { .api }
439
Phaser.AUTO // Auto-detect (WebGL with Canvas fallback)
440
Phaser.WEBGL // Force WebGL
441
Phaser.CANVAS // Force Canvas
442
Phaser.HEADLESS // Headless mode for testing
443
```
444
445
### Common Constants
446
```javascript { .api }
447
Phaser.FOREVER // -1 (infinite loops)
448
Phaser.VERSION // '3.90.0'
449
```
450
451
### Direction Constants
452
```javascript { .api }
453
Phaser.LEFT // 7
454
Phaser.RIGHT // 8
455
Phaser.UP // 5
456
Phaser.DOWN // 6
457
```
458
459
## Game Configuration
460
461
### Basic Configuration
462
```javascript { .api }
463
const config = {
464
type: Phaser.AUTO,
465
width: 800,
466
height: 600,
467
backgroundColor: '#2c3e50',
468
scene: [MenuScene, GameScene, GameOverScene],
469
physics: {
470
default: 'arcade',
471
arcade: {
472
gravity: { y: 300 },
473
debug: false
474
}
475
},
476
scale: {
477
mode: Phaser.Scale.FIT,
478
autoCenter: Phaser.Scale.CENTER_BOTH
479
}
480
};
481
```
482
483
### Advanced Configuration
484
```javascript { .api }
485
const config = {
486
type: Phaser.WEBGL,
487
width: 1024,
488
height: 768,
489
canvas: document.getElementById('game-canvas'),
490
canvasStyle: 'width: 100%; height: 100%;',
491
scene: {
492
preload: preloadAssets,
493
create: createGame,
494
update: updateGame
495
},
496
physics: {
497
default: 'matter',
498
matter: {
499
gravity: { y: 0.8 },
500
debug: true
501
}
502
},
503
input: {
504
keyboard: true,
505
mouse: true,
506
touch: true,
507
gamepad: true
508
},
509
loader: {
510
baseURL: 'https://cdn.example.com/assets/',
511
crossOrigin: 'anonymous'
512
},
513
plugins: {
514
global: [
515
{ key: 'MyPlugin', plugin: MyPluginClass, start: true }
516
],
517
scene: [
518
{ key: 'ScenePlugin', plugin: ScenePluginClass, mapping: 'myPlugin' }
519
]
520
}
521
};
522
```
523
524
## Namespace Organization
525
526
Phaser organizes its functionality into logical namespaces:
527
528
- `Phaser.Actions` - Bulk operations on GameObject arrays
529
- `Phaser.Animations` - Animation system
530
- `Phaser.Cameras` - Camera management
531
- `Phaser.Core` - Core game systems
532
- `Phaser.Display` - Display utilities
533
- `Phaser.GameObjects` - All GameObject types
534
- `Phaser.Geom` - Geometric shapes and operations
535
- `Phaser.Input` - Input handling systems
536
- `Phaser.Loader` - Asset loading
537
- `Phaser.Math` - Mathematical functions
538
- `Phaser.Physics` - Physics engines
539
- `Phaser.Scale` - Game scaling
540
- `Phaser.Scene` - Scene base class
541
- `Phaser.Sound` - Audio system
542
- `Phaser.Textures` - Texture management
543
- `Phaser.Tweens` - Animation tweening
544
- `Phaser.Utils` - Utility functions
545
546
This modular organization allows for efficient development and easy navigation of Phaser's extensive API surface covering over 1000 methods across 200+ classes.