Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 36 ยท Game Architecture

Scene Architecture

Structure a Phaser game with boot, preloader, menu, gameplay and game over scenes. Learn the scene lifecycle, loading bars, cleanup and scene data.

A first Phaser game often lives in one scene with one big create() method. That is fine for a demo and a disaster at 3,000 lines. Real games are split into scenes with clear jobs, and the split is nearly the same in every project: something loads assets, something shows a menu, something runs the game and something shows the result. This lesson gives you that standard structure, explains the scene lifecycle that makes it work, and shows how to avoid the leaks and duplicated objects that appear when scenes restart.

You already know how to switch scenes. The new part is architecture: deciding which scene owns what, how they talk to each other, and how they clean up after themselves.

The standard scene flow

Most Phaser games use a chain like this:

flowchart LR
  B["Boot<br/>tiny config + loader bar assets"] --> P["Preloader<br/>loads everything, shows progress"]
  P --> M["MainMenu"]
  M --> G["Game<br/>+ HUD in parallel"]
  G --> O["GameOver"]
  O --> M
  O --> G

Each scene has one responsibility, and data flows forward through scene.start(key, data).

  • Boot: runs first and loads the few assets that the preloader needs (a logo, a loading bar frame). It sets global options and starts the next scene. It is often tiny.
  • Preloader: loads all game assets while it draws a progress bar, so the player never sees a half-loaded game. It may also create animations and texture atlases that other scenes use.
  • MainMenu: title, buttons, settings.
  • Game: the gameplay itself. A HUD scene can run next to it (see HUDs, Menus and Pause Screens).
  • GameOver / Results: shows the score and offers retry or menu.

Putting loading in its own scene has a practical benefit: assets live in Phaser's global caches, so once they are loaded every scene can use them, and a restart of the game scene does not load anything again.

The scene lifecycle

Every scene class can define four methods. Phaser calls them in a fixed order:

Method When it runs Typical use
init(data) First, before loading. Receives the data from scene.start Store incoming values, reset fields
preload() After init; Phaser waits for the loader to finish Queue this.load.* calls
create(data) After preload finishes Build game objects, input, physics
update(time, delta) Every frame while running Game logic

Scenes also emit lifecycle events through this.events: create, update, pause, resume, sleep, wake, shutdown and destroy. The most important one is shutdown, emitted when the scene stops or restarts. Phaser removes the scene's display list, its tweens and its timers for you. It does not remove listeners you added to long-lived emitters such as this.game.events, this.registry.events or another scene's events. Those are your responsibility.

JavaScript
create() {
  const onHit = () => this.cameras.main.shake(100);
  this.game.events.on('player-hit', onHit);
  this.events.once('shutdown', () => this.game.events.off('player-hit', onHit));
}

Also remember that class fields and variables of a scene object survive a restart, because the same instance is reused. Reset them in init() or create(), never only in the constructor.

A preloader with a progress bar

The loader emits progress (a number from 0 to 1) and complete events. A loading scene draws a bar and updates it. Real projects load PNG and audio files here. In the lesson sandbox we feed the loader SVG pictures written as data: addresses (base64 encoded, which is what Phaser's loader expects for inline data). The loader fetches them exactly like files, so the progress bar and the code are real.

Boot, Preloader, Menu, Game, GameOver

Walk through what the structure gives you:

  1. Boot runs, starts Preloader, which loads eight pictures while the bar grows, then starts Menu.
  2. Menu reads the best score from the registry, a game-wide key/value store (see Events, Registry and Saving).
  3. Game receives { level: 1 } in init, resets its own counters there and sends the final score to GameOver with scene.start('GameOver', { score }).
  4. Restarting the game scene creates it again from scratch, because init and create run again. Nothing is loaded twice: the textures stay in the global cache.

Where to put shared things

Beginners sometimes put everything in a single huge scene to avoid passing data. Here is a quick guide for placing state:

What Where
Values that only one scene needs Fields on that scene (this.score)
Values that several scenes read or change (best score, settings) this.registry
One-off messages between scenes Events on the sender scene or this.game.events
Data for the next scene only The data argument of scene.start
Long-lived services (audio manager, save system) A plain JavaScript class stored on the registry or a scene plugin

Transitions

A direct scene.start cuts to the next scene instantly. A smoother way is to fade the camera and switch when the fade ends:

JavaScript
goTo(key, data) {
  const cam = this.cameras.main;
  cam.fadeOut(300, 0, 0, 0);
  cam.once(Phaser.Cameras.Scene2D.Events.FADE_OUT_COMPLETE, () => this.scene.start(key, data));
}

Phaser also has this.scene.transition({ target: 'Game', duration: 500, ... }), which runs both scenes at once and lets you animate between them in the transitionstart handler. For most games a fade is enough.

Sleep or stop?

Use scene.stop when the scene can be rebuilt from scratch next time (levels). Use scene.sleep when you want to keep its state but hide it and stop its updates, for example an inventory screen with many objects that opens often. A sleeping scene does not run create again when woken; it emits wake, so any refresh must happen in that handler.

Watching the lifecycle

Press restart and watch the console: init runs again with the new data, runs increases because the same scene object is reused, and fresh is back to 1 because it is reset on purpose. The fields that you do not reset in init are exactly the bugs that appear on the second round of a game: an enemy count that is still 12, a boolean gameOver that is still true.

Rules of thumb

  • One responsibility per scene. If you describe a scene with "and", split it.
  • Reset state in init. Assume that your scene will be started many times.
  • Unsubscribe from outside emitters in shutdown.
  • Load once. Assets belong in the preloader; calling this.load.* in gameplay scenes makes hitches.
  • Give scenes string keys as constants (export const SCENES = { MENU: 'Menu' }) so a typo is caught by search.
  • Keep gameplay scenes data-driven. Pass a level number or a level key instead of copying the scene for each level.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In what order does Phaser call a scene's methods when it starts?

    init gets the incoming data, preload queues assets and waits, create builds the scene and update runs each frame.
  2. 2. Why does a scene property set in the constructor cause bugs after scene.restart()?

    Phaser keeps the scene object. Only methods you call again (init, create) run on a restart, so state that must start fresh belongs there.
  3. 3. Which listener MUST you remove yourself when a scene shuts down?

    Phaser cleans up the scene's own display list, tweens and timers. Listeners on emitters that outlive the scene stay until you call off.
  4. 4. What is the main purpose of a Preloader scene?

    Loading in its own scene gives the player a progress bar and means other scenes find every asset ready.

Summary

  • A typical flow is Boot, Preloader, Menu, Game (with HUD), GameOver, each scene with one job.
  • The lifecycle is init(data), preload(), create(data) and update(), with shutdown and destroy events for cleanup.
  • Scene objects are reused: reset state in init, and unsubscribe from long-lived emitters on shutdown.
  • Put shared state in the registry, one-time data in scene.start(key, data) and messages in events.
  • Fade transitions, sleep versus stop, and constants for scene keys keep larger games tidy.

Next: Custom Game Objects and Object Pools