Phaser Scene Template

Phaser Scene Template

Overview

Standardized Phaser scene template with test seam, lifecycle methods, and common patterns. Accelerate scene creation and ensure consistency.

Template Structure

See assets/scene-template.ts for complete scene template code.

Key Components

• Lifecycle methods: preload(), create(), update()
• Test seam setup: Standardized test seam structure
• Game state management: Common state patterns
• Scene navigation: Transition methods

Mandatory Test Seam Setup Checklist

Every scene MUST include test seam setup:

• Check for window.__TEST__ availability
• Register scene with TestManager (if using singleton pattern)
• Set up window.__TEST__.commands object
• Implement gameState() method for state access
• Add scene-specific commands (navigation, actions)
• Set window.__TEST__.ready = true after initialization
• Set window.__TEST__.sceneKey to current scene key
• Document available commands in code comments

Example:

setupTestSeam() {
  if (!window.__TEST__) {
    window.__TEST__ = {};
  }
  
  window.__TEST__.sceneKey = this.scene.key;
  window.__TEST__.ready = true;
  
  window.__TEST__.commands = {
    goToScene: (key: string) => {
      this.scene.start(key);
    },
    gameState: () => {
      return {
        scene: this.scene.key,
        score: this.score,
        // Scene-specific state
      };
    }
  };
}

Test Seam Debugging Patterns

If test seam not working:

1. Check if window.__TEST__ is defined
2. Verify scene is initialized (check create() method)
3. Wait for window.__TEST__.ready === true
4. Check scene key matches Phaser scene registration
5. Verify commands are defined in window.__TEST__.commands

Common test seam issues:

• Test seam undefined: Scene not initialized, check create() method
• Commands not found: Commands not defined in window.__TEST__.commands
• SceneKey doesn't update: Known issue, use console logs as fallback
• Ready flag false: Scene still initializing, wait for ready

Verification Patterns for Test Seams

Verify test seam setup:

// In browser console or test
console.log(window.__TEST__); // Should be defined
console.log(window.__TEST__.ready); // Should be true
console.log(window.__TEST__.sceneKey); // Should match scene key
console.log(window.__TEST__.commands); // Should have commands

Test seam command verification:

# In agent-browser
agent-browser eval "window.__TEST__ && window.__TEST__.ready"
agent-browser eval "window.__TEST__.commands.gameState()"
agent-browser eval "window.__TEST__.commands.goToScene('MainMenu')"

Lifecycle Patterns

See references/lifecycle-patterns.md for detailed lifecycle patterns:

• preload() - Load assets
• create() - Initialize scene, set up test seam
• update() - Game loop

Usage

1. Copy assets/scene-template.ts to your scene file
2. Customize for your scene's needs
3. Add scene-specific logic
4. Update test seam commands

Component Test Scene Variant

When the scene's purpose is to test a single UI component, use the same lifecycle and test seam checklist but with minimal content: only that component plus the test seam. For the full workflow and naming (e.g. ComponentNameTestScene, boot via ?scene=...), use the phaser-component-test-scenes skill.

Resources

• assets/scene-template.ts - Template code for new scenes
• references/lifecycle-patterns.md - preload, create, update patterns
• phaser-component-test-scenes - Standalone test scenes for UI components (workflow and template)