Events System

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 events

Using 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):

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 -> update -> Scene.update() -> postupdate -> prerender -> render

create() {
    this.events.on(Phaser.Scenes.Events.UPDATE, this.onUpdate, this);
    // CRITICAL: always clean up on shutdown to prevent leaks on scene restart
    this.events.on(Phaser.Scenes.Events.SHUTDOWN, () => {
        this.events.off(Phaser.Scenes.Events.UPDATE, this.onUpdate, this);
        this.input.off('pointerdown', this.onPointerDown, this);
    });
}

Game-Level Events

// game.events fires on the Game instance, shared across all scenes
// Access from a scene via this.game.events
this.game.events.on(Phaser.Core.Events.BLUR, this.handleBlur, this);
this.game.events.on(Phaser.Core.Events.VISIBLE, this.handleVisible, this);

Inter-Scene Communication

// METHOD 1: game.events — a global event bus accessible from all scenes
// Scene A emits:
this.game.events.emit('score-changed', this.score);
// Scene B listens:
this.game.events.on('score-changed', (score) => { this.scoreText.setText(score); });

// METHOD 2: this.registry — a shared DataManager across all scenes
// The registry is a Phaser.Data.DataManager on the Game instance.
// Scene A sets data:
this.registry.set('score', 100);
// Scene B listens for changes:
this.registry.events.on('changedata-score', (parent, value, previousValue) => {
    this.scoreText.setText(value);
});

// METHOD 3: Direct scene access via ScenePlugin
this.scene.get('UIScene').events.emit('update-health', hp);

Custom Events

// Emit custom events with arbitrary data arguments
this.events.emit('player-died', this.player, { lives: this.lives });
this.events.on('player-died', (player, data) => {
    console.log('Lives remaining:', data.lives);
});

All Event Namespaces Reference

Scene Events (Phaser.Scenes.Events)

Emitter: this.events (the Scene's Systems EventEmitter)

Game Events (Phaser.Core.Events)

Emitter: this.game.events or game.events

Input Events (Phaser.Input.Events)

Emitter: this.input (scene-level) or individual GameObjects. Events exist at three levels: scene-level (this.input), scene-level with gameobject prefix, and directly on interactive GameObjects. See ../input-keyboard-mouse-touch/SKILL.md for full usage.

Scene-level pointer events (on this.input): POINTER_DOWN 'pointerdown' | POINTER_UP 'pointerup' | POINTER_MOVE 'pointermove' | POINTER_OVER 'pointerover' | POINTER_OUT 'pointerout' | POINTER_WHEEL 'wheel' | POINTER_DOWN_OUTSIDE 'pointerdownoutside' | POINTER_UP_OUTSIDE 'pointerupoutside'

Scene-level gameobject events (on this.input): GAMEOBJECT_DOWN 'gameobjectdown' | GAMEOBJECT_UP 'gameobjectup' | GAMEOBJECT_MOVE 'gameobjectmove' | GAMEOBJECT_OVER 'gameobjectover' | GAMEOBJECT_OUT 'gameobjectout' | GAMEOBJECT_WHEEL 'gameobjectwheel'

Per-GameObject events (emitted on the GameObject itself, requires setInteractive()): GAMEOBJECT_POINTER_DOWN 'pointerdown' | GAMEOBJECT_POINTER_UP 'pointerup' | GAMEOBJECT_POINTER_MOVE 'pointermove' | GAMEOBJECT_POINTER_OVER 'pointerover' | GAMEOBJECT_POINTER_OUT 'pointerout' | GAMEOBJECT_POINTER_WHEEL 'wheel'

Drag events (on this.input and on GameObjects with same string): DRAG_START/GAMEOBJECT_DRAG_START 'dragstart' | DRAG/GAMEOBJECT_DRAG 'drag' | DRAG_END/GAMEOBJECT_DRAG_END 'dragend' | DRAG_ENTER/GAMEOBJECT_DRAG_ENTER 'dragenter' | DRAG_OVER/GAMEOBJECT_DRAG_OVER 'dragover' | DRAG_LEAVE/GAMEOBJECT_DRAG_LEAVE 'dragleave' | DROP/GAMEOBJECT_DROP 'drop'

Other: GAME_OUT 'gameout' | GAME_OVER 'gameover' | POINTERLOCK_CHANGE 'pointerlockchange'

Loader Events (Phaser.Loader.Events)

Emitter: this.load

Animation Events (Phaser.Animations.Events)

Emitter: individual sprites (per-sprite) or this.anims (global AnimationManager)

Camera Events (Phaser.Cameras.Scene2D.Events)

Emitter: individual camera instance (e.g. this.cameras.main). Each camera effect has a START and COMPLETE pair.

DESTROY 'cameradestroy' | FADE_IN_START 'camerafadeinstart' | FADE_IN_COMPLETE 'camerafadeincomplete' | FADE_OUT_START 'camerafadeoutstart' | FADE_OUT_COMPLETE 'camerafadeoutcomplete' | FLASH_START 'cameraflashstart' | FLASH_COMPLETE 'cameraflashcomplete' | PAN_START 'camerapanstart' | PAN_COMPLETE 'camerapancomplete' | ROTATE_START 'camerarotatestart' | ROTATE_COMPLETE 'camerarotatecomplete' | SHAKE_START 'camerashakestart' | SHAKE_COMPLETE 'camerashakecomplete' | ZOOM_START 'camerazoomstart' | ZOOM_COMPLETE 'camerazoomcomplete' | FOLLOW_UPDATE 'followupdate' | PRE_RENDER 'prerender' | POST_RENDER 'postrender'

Sound Events (Phaser.Sound.Events)

Emitter: individual sound instances or this.sound (SoundManager)

Per-sound instance events: PLAY 'play' | PAUSE 'pause' | RESUME 'resume' | STOP 'stop' | COMPLETE 'complete' | LOOP 'loop' | LOOPED 'looped' | SEEK 'seek' | MUTE 'mute' | VOLUME 'volume' | RATE 'rate' | DETUNE 'detune' | PAN 'pan' | DECODED 'decoded' | DESTROY 'destroy'

SoundManager-level events (on this.sound): GLOBAL_MUTE 'mute' | GLOBAL_VOLUME 'volume' | GLOBAL_RATE 'rate' | GLOBAL_DETUNE 'detune' | PAUSE_ALL 'pauseall' | RESUME_ALL 'resumeall' | STOP_ALL 'stopall' | DECODED_ALL 'decodedall' | UNLOCKED 'unlocked'