Use this skill when working with Phaser 4 scenes. Covers scene lifecycle methods, scene transitions, parallel scenes, scene communication, sleeping, pausing, restarting, and the SceneManager. Triggers on: Scene, scene lifecycle, preload, create, update, scene transition, SceneManager.

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 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 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 Running Scenes in Parallel Passing Data Between Scenes Pausing and Resuming Adding and Removing Scenes at Runtime Cross Scene Event Communication One scene emits custom events; another listens. The emitting scene is decoupled. Configuring Plugins Per Scene Disable all default plugins (only core plugins remain): Include only specific plugins: Scene Config in Constructor Pass config to super() for per scene physics, loader, or preloaded files: Safely Restarting Scenes Reset state in init() , not the constructor. The constructor runs once; init() runs every start. Events All events are emitted on this.events (the scene specific EventEmitter) and have string values. Listen via this.events.on('eventname', callback) . Lifecycle Events Event String Constant Callback Signature When 'boot' Phaser.Scenes.Events.BOOT (sys) Once, when scene is first instantiated (for plugins) 'start' Phaser.Scenes.Events.START (sys) Scene systems start (for plugins) 'ready' Phaser.Scenes.Events.READY (sys, data) After start, for user code 'create' Phaser.Scenes.Events.CREATE (scene) After create() method runs, scene is now RUNNING 'preupdate' Phaser.Scenes.Events.PRE UPDATE (time, delta) Before update each frame 'update' Phaser.Scenes.Events.UPDATE (time, delta) During update each frame 'postupdate' Phaser.Scenes.Events.POST UPDATE (time, delta) After update each frame 'prerender' Phaser.Scenes.Events.PRE RENDER (renderer) Before scene renders 'render' Phaser.Scenes.Events.RENDER (renderer) After scene renders State Change Events Event String Constant Callback Signature When 'pause' Phaser.Scenes.Events.PAUSE (sys, data) Scene is paused 'resume' Phaser.Scenes.Events.RESUME (sys, data) Scene is resumed 'sleep' Phaser.Scenes.Events.SLEEP (sys, data) Scene is sent to sleep 'wake' Phaser.Scenes.Events.WAKE (sys, data) Scene is woken up 'shutdown' Phaser.Scenes.Events.SHUTDOWN (sys, data) Scene is shutting down 'destroy' Phaser.Scenes.Events.DESTROY (sys) Scene is being destroyed Transition Events Event String Constant Callback Signature Emitted On 'transitionout' TRANSITION OUT (targetScene, duration) Source scene 'transitioninit' TRANSITION INIT (fromScene, duration) Target scene (during init) 'transitionstart' TRANSITION START (fromScene, duration) Target scene (after create) 'transitionwake' TRANSITION WAKE (fromScene, duration) Target scene (if woken from sleep) 'transitioncomplete' TRANSITION COMPLETE (scene) Target scene (when done) Game Object Events Event String Constant Callback Signature 'addedtoscene' ADDED TO SCENE (gameObject, scene) 'removedfromscene' REMOVED FROM SCENE (gameObject, scene) For detailed API reference tables and source file maps, see [the reference guide](references/REFERENCE.md). Gotchas and Common Mistakes 1. Operations are queued, not immediate. Calling this.scene.start('X') does not start X synchronously. It happens at the next SceneManager update. Do not rely on the target scene's state within the same frame. 2. start() shuts down the calling scene. this.scene.start('X') stops the current scene and starts X. If you want both running, use launch() or run() . 3. switch() sleeps, start() shuts down. switch() preserves the current scene in memory (sleep), while start() triggers a full shutdown. Sleeping scenes still have their events and references live. 4. Paused scenes still render. pause() only stops the update loop. The scene is still drawn. Use sleep() to stop both update and render. 5. Do not overwrite this.sys . The Scene class JSDoc explicitly warns: overwriting this.sys will break everything. 6. this.scene.start() with no key restarts the current scene. This is equivalent to this.scene.restart() . 7. Data passed to start() / launch() is available in both init(data) and create(data) . It is stored in settings.data and accessible later via this.sys.getData() . 8. Sleeping scenes can still receive events from other scenes. If Scene A is sleeping but Scene B emits on the global registry, Scene A's listeners still fire. Be careful with active listeners on sleeping scenes. 9. Scene render order = array order. Scenes later in the array render on top. Use bringToTop() , sendToBack() , moveAbove() , moveBelow() to control layering. 10. shutdown vs destroy . Shutdown puts a scene into hibernation (can restart). Destroy permanently removes it. Listen to 'shutdown' to free resources that should be recreated on restart. Listen to 'destroy' for final cleanup. 11. Plugin properties like this.physics and this.matter are only available if the physics system is configured. They will be undefined otherwise. 12. The create event fires AFTER the create() method returns , and after the status changes to RUNNING. If you need to do post create setup, listen for this event. 13. Reset state in init() , not the constructor. The constructor only runs once when the scene is first instantiated. init() runs every time the scene starts/restarts. Place state resets there. 14. Clean up on shutdown to avoid stale references. Listen for this.events.once('shutdown', ...) to clear arrays holding game objects, remove external event listeners, etc. Stale references to destroyed game objects cause errors on restart. 15. switch() restarts a paused scene, never resumes it. If you need resume behavior, use run() instead. 16. Scenes update in reverse order, render in forward order. The top scene updates first (gets input priority), but renders last (appears on top). Establish render order in the game config scene array.