Phaser 4 — système d'événements
/SKILLUtilisez cette compétence lorsque vous travaillez avec le système d'événements Phaser 4. Elle couvre EventEmitter, les événements de scène, les événem
name: events-system
description: "Use this skill when working with the Phaser 4 event system. Covers EventEmitter, scene events, game events, custom events, and event-driven communication. Triggers on: events, on, emit, EventEmitter, scene events, listeners."
Events System
Phaser uses the EventEmitter pattern (via eventemitter3) throughout the entire framework. Every major system -- Game, Scene, Input, Loader, Cameras, Sound, Tweens, Physics, Textures, Animations -- is an EventEmitter or contains one. Events use lowercase string keys. Phaser provides named constants for all built-in events to avoid typos and enable IDE autocomplete.
Key source paths: src/events/EventEmitter.js, src/scene/events/, src/core/events/, src/input/events/, src/loader/events/, src/animations/events/, src/cameras/2d/events/, src/sound/events/, src/tweens/events/, src/physics/arcade/events/, src/textures/events/, src/gameobjects/events/, src/time/events/
Related skills: ../scenes/SKILL.md, ../input-keyboard-mouse-touch/SKILL.md
Quick Start
// on — listen for an event (persists until removed)
this.input.on('pointerdown', (pointer) => {
console.log('clicked at', pointer.x, pointer.y);
});
// once — listen for an event, auto-removes after first fire
this.events.once('shutdown', () => {
console.log('scene shutting down');
});
// off — remove a specific listener (must pass same function reference)
const handler = (pointer) => { /* ... */ };
this.input.on('pointerdown', handler);
this.input.off('pointerdown', handler);
// emit — fire a custom event with arguments
this.events.emit('player-died', this.player, this.score);
// removeAllListeners — remove all listeners for an event (or all events)
this.events.removeAllListeners('player-died');
this.events.removeAllListeners(); // all eventsUsing Named Constants (Preferred)
// Always prefer constants over raw strings to prevent typos
this.events.on(Phaser.Scenes.Events.UPDATE, (time, delta) => {
// runs every frame
});
this.input.on(Phaser.Input.Events.POINTER_DOWN, (pointer) => {
// pointer pressed
});
this.game.events.on(Phaser.Core.Events.BLUR, () => {
// browser tab lost focus
});Core Concepts
EventEmitter Base Class
Phaser.Events.EventEmitter extends eventemitter3. It adds shutdown() and destroy() methods that both call removeAllListeners().
Full API (inherited from eventemitter3):
| Method | Description |
|---|---|
on(event, fn, context?) | Add persistent listener. Returns this for chaining |
addListener(event, fn, context?) | Alias for on |
once(event, fn, context?) | Add one-time listener; auto-removed after first fire |
off(event, fn?, context?, once?) | Remove listener(s). Must pass same fn reference to remove specific listener |
removeListener(event, fn?, context?, once?) | Alias for off |
removeAllListeners(event?) | Remove all listeners for event, or all events if no arg |
emit(event, ...args) | Fire event. Returns true if it had listeners |
listeners(event) | Return array of listener functions for an event |
listenerCount(event) | Return number of listeners for an event |
eventNames() | Return array of event names that have listeners |
shutdown() | Calls removeAllListeners() |
destroy() | Calls removeAllListeners() |
Event Strings vs Constants
Every built-in event is a lowercase string exported as a constant. The constant name maps predictably to the string:
Phaser.Scenes.Events.UPDATE // 'update'
Phaser.Scenes.Events.PRE_UPDATE // 'preupdate'
Phaser.Scenes.Events.SHUTDOWN // 'shutdown'
Phaser.Core.Events.BOOT // 'boot'
Phaser.Input.Events.POINTER_DOWN // 'pointerdown'Some events use a key-suffix pattern for per-key listening:
// Loader: listen for a specific file completing
this.load.on(Phaser.Loader.Events.FILE_KEY_COMPLETE + 'image-logo', (key, type, data) => {});
// String value: 'filecomplete-image-logo'
// Animations: listen for a specific animation completing on a sprite
sprite.on(Phaser.Animations.Events.ANIMATION_COMPLETE_KEY + 'walk', () => {});
// String value: 'animationcomplete-walk'
// Textures: listen for a specific texture being added
this.textures.on(Phaser.Textures.Events.ADD_KEY + 'myTexture', () => {});
// String value: 'addtexture-myTexture'Context (Third Argument)
The third argument to on/once sets this inside the callback. Defaults to the emitter.
// 'this' inside handler refers to the scene
this.input.on('pointerdown', function (pointer) {
this.cameras.main.shake(100); // 'this' = scene
}, this);
// Arrow functions ignore the context argument (they capture lexical 'this')
this.input.on('pointerdown', (pointer) => {
this.cameras.main.shake(100); // 'this' = enclosing scope (scene in create)
});Common Patterns
Scene Lifecycle Events
Frame loop order: preupdate -> `u
