scenes

Scenes

Scenes are the organizational backbone of a Phaser game. Each Scene has its own lifecycle (init, preload, create, update), its own set of injected systems (this.add, this.input, this.cameras, etc.), and can be started, stopped, paused, slept, or run in parallel with other Scenes. The ScenePlugin (this.scene) controls all multi-scene orchestration.

Key source paths: src/scene/Scene.js, src/scene/Systems.js, src/scene/SceneManager.js, src/scene/ScenePlugin.js, src/scene/Settings.js, src/scene/const.js, src/scene/events/, src/scene/InjectionMap.js Related skills: ../game-setup-and-config/SKILL.md, ../loading-assets/SKILL.md, ../events-system/SKILL.md

Quick Start

// Minimal scene with all lifecycle methods
class GameScene extends Phaser.Scene {
    constructor() {
        super('GameScene');
    }

    init(data) {
        // Called first. Receives data passed from other scenes.
        // 'data' is whatever was passed via scene.start('GameScene', { level: 1 })
        this.level = data.level || 1;
    }

    preload() {
        // Called after init. Load assets here.
        this.load.image('logo', 'assets/logo.png');
    }

    create(data) {
        // Called after preload completes. Set up game objects.
        // 'data' is the same object passed to init.
        this.add.image(400, 300, 'logo');
    }

    update(time, delta) {
        // Called every frame while scene is RUNNING.
        // time: current time (ms), delta: ms since last frame (smoothed)
    }
}

const config = {
    width: 800,
    height: 600,
    scene: [GameScene]
};

const game = new Phaser.Game(config);

Core Concepts

Scene Lifecycle

The lifecycle is driven by SceneManager.bootScene() and SceneManager.create():

1. PENDING (0) - Scene is registered but not yet started.
2. INIT (1) - scene.init(data) is called if defined. Data comes from settings.data.
3. START (2) - Systems.start() fires. Events start and ready are emitted.
4. LOADING (3) - scene.preload() is called if defined. Loader runs. On completion, proceeds to create.
5. CREATING (4) - scene.create(data) is called if defined. Same data as init.
6. RUNNING (5) - scene.update(time, delta) called every frame. Scene renders.
7. PAUSED (6) - No update, but still renders.
8. SLEEPING (7) - No update, no render. State preserved in memory.
9. SHUTDOWN (8) - Scene is shut down, systems emit shutdown. Can be restarted.
10. DESTROYED (9) - Scene is fully destroyed. Cannot be restarted.

State constants are on Phaser.Scenes: Phaser.Scenes.PENDING, Phaser.Scenes.RUNNING, etc.

Flow when no preload exists: init() -> create() -> update() loop (preload is skipped entirely).

Flow with preload: init() -> preload() -> loader runs -> create() -> update() loop.

Scene-Injected Properties

These properties are injected into every Scene instance via the InjectionMap (src/scene/InjectionMap.js). The left side is the Systems key, the right is the Scene property name.

Global Managers (shared across all scenes)

Scene Property	Type	Description
this.game	Phaser.Game	The Game instance
this.renderer	CanvasRenderer | WebGLRenderer	The active renderer
this.anims	Phaser.Animations.AnimationManager	Global animation manager
this.cache	Phaser.Cache.CacheManager	Global cache for non-image assets
this.plugins	Phaser.Plugins.PluginManager	Global plugin manager
this.registry	Phaser.Data.DataManager	Global data manager (shared between scenes)
this.scale	Phaser.Scale.ScaleManager	Global scale manager
this.sound	NoAudio | HTML5Audio | WebAudioSoundManager	Sound manager
this.textures	Phaser.Textures.TextureManager	Global texture manager

Scene-Specific Systems (unique per scene)

Scene Property	Type	Description
this.sys	Phaser.Scenes.Systems	Scene systems (never overwrite)
this.events	Phaser.Events.EventEmitter	Scene-specific event emitter
this.cameras	Phaser.Cameras.Scene2D.CameraManager	Scene camera manager
this.add	Phaser.GameObjects.GameObjectFactory	Factory: creates and adds to display list
this.make	Phaser.GameObjects.GameObjectCreator	Creator: creates but does NOT add to display list
this.scene	Phaser.Scenes.ScenePlugin	Scene manager plugin (start/stop/launch)
this.children	Phaser.GameObjects.DisplayList	The scene display list
this.lights	Phaser.GameObjects.LightsManager	Scene lights (plugin)
this.data	Phaser.Data.DataManager	Scene-specific data manager
this.input	Phaser.Input.InputPlugin	Scene input manager (plugin)
this.load	Phaser.Loader.LoaderPlugin	Scene loader (plugin)
this.time	Phaser.Time.Clock	Scene time/clock (plugin)
this.tweens	Phaser.Tweens.TweenManager	Scene tween manager (plugin)
this.physics	Phaser.Physics.Arcade.ArcadePhysics	Arcade physics (if configured)
this.matter	Phaser.Physics.Matter.MatterPhysics	Matter physics (if configured)

Customizing the Injection Map

// Rename injected properties via scene config
const config = {
    key: 'MyScene',
    map: {
        add: 'makeStuff',   // this.makeStuff instead of this.add
        load: 'loader'      // this.loader instead of this.load
    }
};

Scene Manager

The SceneManager (src/scene/SceneManager.js) is a game-level system. Do not call its methods directly -- use this.scene (the ScenePlugin) instead. The SceneManager:

• Maintains an ordered array of scenes (determines render/update order)
• Processes a queue of operations (start, stop, sleep, etc.) at the start of each game step
• All ScenePlugin methods are queued, not immediate (they execute next frame)

Common Patterns

Switching Between Scenes

// start() -- shuts down current scene, starts target scene
// Current scene gets SHUTDOWN event; target gets full lifecycle
this.scene.start('LevelTwo', { score: 100 });

// restart() -- shuts down and restarts the same scene
this.scene.restart({ score: 0 });

// switch() -- sleeps current scene, starts/wakes target scene
// Current scene state is preserved in memory
this.scene.switch('PauseMenu', { fromScene: 'GameScene' });

// transition() -- animated transition with duration
this.scene.transition({
    target: 'LevelTwo',
    duration: 1000,
    moveAbove: true,        // render target above this scene
    sleep: false,           // false = stop this scene (default), true = sleep it
    remove: false,          // true = remove this scene from manager after transition
    allowInput: false,      // allow input on this scene during transition
    data: { score: 100 },
    onUpdate: function (progress) {
        // progress: 0 to 1 over duration
    }
});

Running Scenes in Parallel

// launch() -- starts another scene in parallel (does NOT stop current scene)
this.scene.launch('UIScene', { lives: 3 });

// run() -- smart launcher: starts if not running, resumes if paused, wakes if sleeping
this.scene.run('UIScene', { lives: 3 });

// Control render order of parallel scenes
this.scene.bringToTop('UIScene');      // render last (on top)
this.scene.sendToBack('Background');   // render first (behind)
this.scene.moveAbove('GameScene', 'UIScene');  // UIScene renders above GameScene
this.scene.moveBelow('GameScene', 'Background');
this.scene.moveUp('UIScene');          // move one position up
this.scene.moveDown('UIScene');        // move one position down
this.scene.swapPosition('SceneA', 'SceneB');

Passing Data Between Scenes

// Method 1: Pass data via start/launch/restart/switch/wake/run
this.scene.start('LevelScene', { level: 5, score: 1200 });
// In LevelScene:
// init(data) { data.level === 5 }
// create(data) { data.score === 1200 }

// Method 2: Access data later via sys.getData()
// In receiving scene, at any time:
const data = this.sys.getData(); // returns settings.data

// Method 3: Global registry (shared across ALL scenes)
// In Scene A:
this.registry.set('playerHP', 100);
// In Scene B:
const hp = this.registry.get('playerHP'); // 100

// Method 4: Scene-specific data manager
this.data.set('localValue', 42);
this.data.get('localValue'); // 42

// Method 5: Direct scene reference
const otherScene = this.scene.get('OtherScene');
otherScene.somePublicProperty;

// Method 6: Events on the global registry
// In Scene A:
this.registry.events.on('changedata-playerHP', (parent, value, previousValue) => {
    // react to change
});
// In Scene B:
this.registry.set('playerHP', 50); // triggers the event in Scene A

Pausing and Resuming

// Pause: stops update loop, still renders
this.scene.pause();               // pause this scene
this.scene.pause('OtherScene');   // pause another scene

// Resume: restart update loop
this.scene.resume();
this.scene.resume('OtherScene', { message: 'welcome back' });

// Sleep: no update AND no render, but state preserved
this.scene.sleep();
this.scene.sleep('OtherScene');

// Wake: restore from sleep
this.scene.wake();
this.scene.wake('OtherScene', { data: 'here' });

// Stop: full shutdown, clears display list and timers
this.scene.stop();
this.scene.stop('OtherScene');

// Check state
this.scene.isActive('OtherScene');    // boolean
this.scene.isPaused('OtherScene');    // boolean
this.scene.isSleeping('OtherScene');  // boolean
this.scene.isVisible('OtherScene');   // boolean

// Control visibility/activity independently
this.scene.setActive(false);          // pause
this.scene.setActive(true);           // resume
this.scene.setVisible(false);         // hide but still update
this.scene.setVisible(true);          // show

Adding and Removing Scenes at Runtime

// Add a new scene dynamically
this.scene.add('BonusLevel'

---

*Content truncated.*