dev-phaser-scene-management

name	dev-phaser-scene-management
description	Scene transitions, data passing, and scene lifecycle management

Phaser Scene Management

"Orchestrating your game scenes with smooth transitions and data flow."

Before/After: Manual Screen Management vs Phaser Scene System

❌ Before: Manual Screen Management

// Manual scene management without Phaser
type ScreenType = 'title' | 'game' | 'pause' | 'gameover';
let currentScreen: ScreenType = 'title';

const screens: { [key in ScreenType]: HTMLElement } = {};

function showScreen(screen: ScreenType, data?: any) {
  // Hide current screen
  if (screens[currentScreen]) {
    screens[currentScreen].style.display = 'none';
  }

  // Show new screen
  if (!screens[screen]) {
    screens[screen] = document.getElementById(`screen-${screen}`)!;
  }
  screens[screen].style.display = 'block';

  // Manual data passing
  if (data && screen === 'game') {
    const levelElement = screens[screen].querySelector('.level')!;
    levelElement.textContent = data.level || '1';
  }

  // Manual cleanup
  if (currentScreen === 'game') {
    // Save game state manually
    saveGameState();
  }

  currentScreen = screen;
}

// Problems:
// - Manual DOM manipulation
// - No automatic lifecycle management
// - Data passing is manual
// - No transition effects built-in
// - Cleanup must be manual
// - No parallel scene support

✅ After: Phaser Scene System

// Phaser handles scene lifecycle automatically
export class TitleScene extends Phaser.Scene {
  create() {
    // Start new scene - ONE line!
    // Data passed automatically, transition handled
    this.scene.start('GameScene', { level: 1, difficulty: 'normal' });
  }
}

export class GameScene extends Phaser.Scene {
  init(data: { level: number; difficulty: string }) {
    // Data received automatically in init()
    this.level = data.level || 1;
    this.difficulty = data.difficulty || 'normal';
  }

  create() {
    // Launch UI scene in parallel (not sequential)
    this.scene.launch('UIScene', { health: 100 });

    // Automatic cleanup on shutdown
    this.events.once(,  {
      
    });
  }

  () {
    
    ..();
    ..();
  }

  () {
    
    ...(, , , );
    ...(,  {
      ..(, {
        : .,
        : .
      });
    });
  }
}

When to Use This Skill

Use when:

• Managing multiple game scenes
• Passing data between scenes
• Implementing scene transitions
• Running parallel scenes (UI overlay)
• Pausing/resuming game state

Quick Start

// Start new scene
this.scene.start("GameScene", { level: 1, score: 0 });

// Launch scene in parallel
this.scene.launch("UIScene", { health: 100 });

// Sleep/scene (keeps rendering, stops update)
this.scene.sleep("BackgroundScene");

Decision Framework

Need	Use
Switch scenes	scene.start()
Parallel scene	scene.launch()
Pause scene	scene.pause()
Scene transition effects	Transition effects
Pass data to scene	Data parameter

Progressive Guide

Level 1: Basic Scene Operations

export class TitleScene extends Phaser.Scene {
  create() {
    // Start game scene
    this.input.on("pointerdown", () => {
      this.scene.start("GameScene", { difficulty: "normal" });
    });
  }
}

export class GameScene extends Phaser.Scene {
  private difficulty!: string;

  init(data: { difficulty: string }) {
    // Receive data from previous scene
    this.difficulty = data.difficulty || "normal";
  }

  create() {
    // Return to title
    this.events.on("shutdown", () => {
      console.log("Game scene shutting down");
    });

    this.input.keyboard!.on("keydown-ESC",  {
      ..();
    });
  }
}

Level 2: Scene Transitions with Data

export class LevelSelectScene extends Phaser.Scene {
  selectLevel(level: number) {
    // Pass player progress to game scene
    const sceneData = {
      level: level,
      stars: this.getPlayerStars(level),
      unlocked: this.isLevelUnlocked(level),
    };

    // Fade transition
    this.cameras.main.fadeOut(300, 0, 0, 0);
    this.cameras.main.once("camerafadeoutcomplete", () => {
      this.scene.start("GameScene", sceneData);
    });
  }
}

export class GameScene extends Phaser.Scene {
  private level!: number;
  private stars!: number;
  private unlocked!: boolean;
  private score = 0;

  init() {
    . = data. || ;
    . = data. || ;
    . = data. || ;
  }

  () {
    
     returnData = {
      : .,
      : .(),
      : .,
    };

    ..(, returnData);
  }
}

Level 3: Parallel Scenes (UI Overlay)

export class GameScene extends Phaser.Scene {
  create() {
    // Launch UI scene on top
    this.scene.launch("UIScene", { maxHealth: 100 });

    // Get reference to UI scene
    const uiScene = this.scene.get("UIScene") as UIScene;

    // Listen for UI events
    this.scene.get("UIScene").events.on("pause", () => {
      this.scene.pause();
    });

    this.scene.get("UIScene").events.on("resume", () => {
      this.scene.resume();
    });
  }

  update() {
    // Update UI with game data
    const uiScene = this.scene.()  ;
    uiScene.(..);
    uiScene.(.);
  }
}

     {
   healthBar!: ..;
   scoreText!: ..;

  () {
    
    . = ..();
    . = ..(, , );

    
     pauseBtn = ..(.. - , , );
    pauseBtn.();
    pauseBtn.(,  {
      ..();
    });

    
    ..();
  }

  () {
    ..();
    ..();
    ..(, , current * , );
  }

  () {
    ..();
  }
}

Level 4: Scene Sleep and Wake

export class BackgroundScene extends Phaser.Scene {
  private stars!: Phaser.GameObjects.Group;

  create() {
    this.stars = this.add.group();

    for (let i = 0; i < 100; i++) {
      const star = this.add.image(
        Phaser.Math.Between(0, this.scale.width),
        Phaser.Math.Between(0, this.scale.height),
        "star",
      );
      star.setScrollFactor(0.1);
      this.stars.add(star);
    }

    // Listen for sleep/wake
    this.events.on("sleep", () => {
      console.log();
    });

    ..(,  {
      .();
    });
  }

  () {
    
    ....( {
      star. -= ;
       (star. < -) star. = .. + ;
    });
  }
}

     {
  () {
    
    ..();

    
     overlay = ..(
      .. / ,
      .. / ,
      ..,
      ..,
      ,
      ,
    );

     resumeBtn = ..(.. / , , );
    resumeBtn.();
    resumeBtn.();
    resumeBtn.(,  {
      ..();
      ..();
    });

     quitBtn = ..(.. / , , );
    quitBtn.();
    quitBtn.();
    quitBtn.(,  {
      ..();
      ..();
      ..();
    });
  }
}

Level 5: Advanced Scene Manager

class SceneManager {
  private scene: Phaser.Scene;
  private sceneData = new Map<string, any>();

  constructor(scene: Phaser.Scene) {
    this.scene = scene;
  }

  // Transition with data persistence
  transition(targetKey: string, data?: any, transition?: string) {
    // Save current scene data
    this.sceneData.set(this.scene.scene.key, this.getCurrentSceneData());

    // Merge new data
    const combinedData = {
      ...this.sceneData.get(targetKey),
      ...data,
    };

    // Apply transition effect
    if (transition === "fade") {
      this.fadeTransition(targetKey, combinedData);
    } else if (transition === "slide") {
      .(targetKey, combinedData);
    }  {
      ...(targetKey, combinedData);
    }
  }

   () {
     camera = ...;
    camera.(, , , );

    camera.(,  {
      ...(targetKey, data);
    });
  }

   () {
     width = ...;
     camera = ...;

    
    ...({
      : camera,
      : -width,
      : ,
      :  {
        camera. = width;
        ...(targetKey, data);

        
      },
    });
  }

   ():  {
     {
      
      : (.  ). || ,
      : (.  ).?. || ,
    };
  }

  
  () {
    ...(overlayKey, data);
    ...();
  }

  
  () {
    ...(overlayKey);
    ...();

     (returnData) {
      .(returnData);
    }
  }

   () {
    
     (data. === ) {
      .();
    }
  }
}


     {
   sceneManager!: ;

  () {
    . =  ();
  }

  () {
    ..(, {
      : .,
      : .,
    });
  }

  () {
    ..(
      ,
      { : ., :  },
      ,
    );
  }
}

Anti-Patterns

❌ DON'T:

• Use start() when you need launch() for UI
• Forget to handle scene shutdown cleanup
• Pass circular references in scene data
• Use restart() frequently - expensive
• Stop scenes before retrieving data
• Mix scene keys as strings (use constants)

✅ DO:

• Use launch() for parallel UI scenes
• Clean up in shutdown event handler
• Keep scene data serializable
• Use scene manager for complex flows
• Retrieve data before stopping scenes
• Define scene key constants

Code Patterns

Scene Key Constants

// constants.ts
export const SCENE_KEYS = {
  BOOT: "BootScene",
  PRELOAD: "PreloadScene",
  TITLE: "TitleScene",
  GAME: "GameScene",
  UI: "UIScene",
  PAUSE: "PauseScene",
} as const;

// Usage
this.scene.start(SCENE_KEYS.GAME, { level: 1 });

Global Scene Manager

// game.ts
const config: Phaser.Types.Core.GameConfig = {
  scene: [BootScene, PreloadScene, TitleScene, GameScene, UIScene],
  // ...
};

// Access from any scene
const gameScene = this.scene.get(SCENE_KEYS.GAME);

Scene Methods Reference

Method	Description	Data Passed
start(key, data)	Switch to scene, stop current	Yes
launch(key, data)	Start scene in parallel	Yes
sleep(key)	Pause scene updates	No
wake(key, data)	Resume sleeping scene	Optional
stop(key, data)	Stop and remove scene	Optional
pause()	Pause current scene	No
resume()	Resume current scene	No
get(key)	Get scene reference	No

Checklist

• Scene keys defined as constants
• Data passed in init() method
• Shutdown handlers for cleanup
• Parallel scenes use launch()
• Transition effects complete before scene switch
• Scene manager for complex flows
• Global state managed properly

Reference

• Scene Manager — Scene API
• Scene Plugin — Scene operations