phaser-scene-transition-patterns

name	phaser-scene-transition-patterns
description	Common Phaser scene transition patterns, data passing, and test seam integration for scene management. Use when implementing scene navigation, passing data between scenes, or integrating test seams for scene transitions. Reduces scene transition implementation time by 30-40%.

Phaser Scene Transition Patterns

Common Phaser scene transition patterns, data passing, and test seam integration. Reduces scene transition implementation time by 30-40%.

Overview

Standardized patterns for:

• Scene navigation (this.scene.start())
• Data passing between scenes
• Test seam integration for transitions
• State management on transitions

Core Patterns

Pattern 1: Scene Navigation

Use this.scene.start() for transitions:

// Navigate to new scene
this.scene.start('GameScene');

// Navigate with data
this.scene.start('GameOverScene', {
  score: this.gameState.score,
  level: this.gameState.level
});

Each scene receives data via init(data?) method:

export default class GameOverScene extends Phaser.Scene {
  init(data?: { score?: number; level?: number }) {
    // Receive data from previous scene
    this.finalScore = data?.score || 0;
    this.completedLevel = data?.level || 1;
  }

  create() {
    // Use received data
    this.add.text(100, 100, `Score: ${this.finalScore}`);
  }
}

Pattern 2: Data Passing

Pass data via scene.start() second parameter:

// In GameScene
gameOver() {
  this.scene.start('GameOverScene', {
    score: this.gameState.score,
    timer: this.gameState.timer,
    level: this.gameState.level
  });
}

Store in shared state object for test seam access:

// Store in registry for cross-scene access
this.registry.set('gameState', {
  score: this.gameState.score,
  level: this.gameState.level
});

// Access in another scene
const gameState = this.registry.get('gameState');

Use Phaser's scene data mechanism for reliability:

// Phaser automatically manages scene data
this.scene.start('NextScene', { key: 'value' });

// Access in next scene
init(data?: { key?: string }) {
  const value = data?.key;
}

Pattern 3: Test Seam Integration

Add test seam in scene create() method:

create() {
  // Scene initialization
  this.initScene();

  // Test seam setup
  if (window.__TEST__) {
    window.__TEST__.sceneKey = this.scene.key;
    window.__TEST__.commands.goToScene = (key: string, data?: any) => {
      this.scene.start(key, data);
    };
  }
}

Expose sceneKey, commands, and state getters:

window.__TEST__ = {
  sceneKey: this.scene.key,
  gameState: () => ({
    scene: this.scene.key,
    score: this.gameState.score,
    timer: this.gameState.timer
  }),
  commands: {
    goToScene: (key: string, data?: any) => {
      this.scene.start(key, data);
    }
  }
};

Wait for test seam initialization after transitions:

# After scene transition, wait for test seam
agent-browser eval "window.__TEST__.commands.goToScene('GameScene')"
agent-browser wait 500  # Wait for scene initialization
agent-browser eval "window.__TEST__.sceneKey"  # Verify transition

Pattern 4: State Management

Game state clears when transitioning to fresh scenes:

// Each scene initializes state in create() method
create() {
  // Initialize fresh state
  this.gameState = {
    score: 0,
    timer: 60,
    level: 1
  };
}

Test seam enables programmatic state verification:

// Test seam exposes state for verification
window.__TEST__.gameState = () => ({
  scene: this.scene.key,
  score: this.gameState.score,
  timer: this.gameState.timer,
  level: this.gameState.level
});

Complete Scene Transition Example

GameScene → GameOverScene

In GameScene:

export default class GameScene extends Phaser.Scene {
  private gameState = {
    score: 0,
    timer: 60,
    level: 1
  };

  gameOver() {
    // Transition with data
    this.scene.start('GameOverScene', {
      score: this.gameState.score,
      timer: this.gameState.timer,
      level: this.gameState.level
    });
  }

  create() {
    // Test seam setup
    if (window.__TEST__) {
      window.__TEST__.sceneKey = this.scene.key;
      window.__TEST__.commands.triggerGameOver = () => {
        this.gameOver();
      };
    }
  }
}

In GameOverScene:

export default class GameOverScene extends Phaser.Scene {
  private finalScore = 0;
  private completedLevel = 1;

  init(data?: { score?: number; level?: number }) {
    // Receive data from GameScene
    this.finalScore = data?.score || 0;
    this.completedLevel = data?.level || 1;
  }

  create() {
    // Display final score
    this.add.text(100, 100, `Final Score: ${this.finalScore}`);

    // Test seam setup
    if (window.__TEST__) {
      window.__TEST__.sceneKey = this.scene.key;
      window.__TEST__.commands.getFinalScore = () => {
        return this.finalScore;
      };
    }
  }
}

Test Seam Commands for Scene Transitions

Common Commands

// Navigate to scene
window.__TEST__.commands.goToScene = (key: string, data?: any) => {
  this.scene.start(key, data);
};

// Navigate to game
window.__TEST__.commands.clickStartGame = () => {
  this.scene.start('GameScene');
};

// Navigate to menu
window.__TEST__.commands.clickMainMenu = () => {
  this.scene.start('MainMenuScene');
};

// Play again
window.__TEST__.commands.clickPlayAgain = () => {
  this.scene.start('GameScene');
};

Scene Lifecycle

Scene Initialization Order

1. Constructor: Configuration constants
2. init(data?): Receive data from previous scene
3. preload(): Load assets (if needed)
4. create(): Initialize scene, set up test seam
5. update(): Game loop

State Clearing

Each scene initializes fresh state in create():

create() {
  // State clears naturally when transitioning
  // Each scene starts with fresh state
  this.gameState = {
    score: 0,
    timer: 60
  };
}

Common Patterns

Pattern 1: MainMenu → GameScene

// In MainMenuScene
create() {
  this.startButton.on('pointerdown', () => {
    this.scene.start('GameScene');
  });

  // Test seam
  window.__TEST__.commands.clickStartGame = () => {
    this.scene.start('GameScene');
  };
}

Pattern 2: GameScene → GameOverScene (with data)

// In GameScene
gameOver() {
  this.scene.start('GameOverScene', {
    score: this.gameState.score,
    level: this.gameState.level
  });
}

// In GameOverScene
init(data?: { score?: number; level?: number }) {
  this.finalScore = data?.score || 0;
  this.completedLevel = data?.level || 1;
}

Pattern 3: Any Scene → MainMenu

// Common pattern for returning to menu
window.__TEST__.commands.clickMainMenu = () => {
  this.scene.start('MainMenuScene');
};

Testing Scene Transitions

Test Seam Workflow

# Navigate to scene
agent-browser eval "window.__TEST__.commands.goToScene('GameScene')"

# Wait for transition
agent-browser wait 500

# Verify scene change
agent-browser eval "window.__TEST__.sceneKey === 'GameScene'"

# Verify state
agent-browser eval "window.__TEST__.gameState()"

Console Log Fallback

If test seam sceneKey doesn't update, use console logs:

// Add console log in scene create()
create() {
  console.log(`Scene created: ${this.scene.key}`);
  
  // Scene initialization
}

Verify in browser console:

agent-browser console
# Look for "Scene created: GameScene"

Best Practices

1. Use this.scene.start() for scene transitions
2. Pass data via second parameter of scene.start()
3. Receive data in init(data?) method
4. Set up test seam in create() method
5. Initialize fresh state in each scene's create()
6. Wait 500ms after transitions before checking test seam
7. Use console logs as fallback for scene verification

Integration with Other Skills

• phaser-scene-navigation: Complements with navigation patterns
• phaser-game-testing: Uses test seam for scene testing
• browser-test-seam-optimization: Optimizes scene transition testing

Related Skills

• phaser-scene-navigation - Scene navigation patterns
• phaser-game-testing - Phaser testing methodology
• browser-test-seam-optimization - Test seam optimization

Remember

1. Use scene.start() for transitions
2. Pass data via second parameter
3. Receive in init() method
4. Set up test seam in create()
5. Initialize fresh state per scene
6. Wait 500ms after transitions
7. Use console logs as fallback