feat(core): Scene Management System

[danjdewhurst]

Summary

Implements comprehensive scene management system for multi-scene games, completing 2/5 features for Phase 7 (1.0.0 release).

Features

✅ Scene Management

• Scene class with lifecycle hooks (onLoad, onUnload, onEnter, onExit, onPause, onResume)
• SceneManager for managing multiple World instances
• Scene state management (unloaded, loading, loaded, active, paused)
• Active scene tracking and updates

✅ Scene Transitions

• Customizable scene transitions with fade effects
• Configurable transition duration and callbacks
• Smooth transitions between scenes

✅ Async Loading

• Async scene loading with progress tracking
• Scene preloading (manual and automatic)
• Progress callbacks for loading indicators

✅ Advanced Features

• Persistent scenes that maintain state across unload/load
• Batch scene preloading
• Inactive scene cleanup
• Concurrent transition prevention

Implementation

Core Files:

• src/core/scenes/Scene.ts - Scene class with World wrapper and lifecycle
• src/core/scenes/SceneManager.ts - Multi-scene management and transitions
• src/core/scenes/SceneTransition.ts - Configurable transition effects
• src/core/scenes/index.ts - Public API exports

Testing:

• tests/scenes.test.ts - 47 comprehensive tests
• All existing tests still passing (665 total tests)

Documentation:

• examples/scene-management-example.ts - Full working example with main menu, game, and pause menu
• Updated roadmap to mark Scene Management as complete

Test Coverage

Scene: 27 tests
SceneTransition: 5 tests
SceneManager: 15 tests
Total: 47 tests - all passing ✅

Example Usage

const sceneManager = new SceneManager();

// Register scenes
sceneManager.registerScene({
  name: 'MainMenu',
  lifecycle: {
    onLoad: async (world) => {
      // Load menu assets
    },
    onEnter: async () => {
      // Show menu
    }
  }
});

// Switch scenes with transition
await sceneManager.switchTo('MainMenu', {
  duration: 300,
  callbacks: {
    onFadeOut: (progress) => console.log(`Fading out: ${progress}`),
    onFadeIn: (progress) => console.log(`Fading in: ${progress}`)
  }
});

// Update active scene
sceneManager.update(deltaTime);

Roadmap Progress

Phase 7: Core Completeness - 40% (2/5)

• ✅ Serialization & Persistence
• ✅ Scene Management (this PR)
• ❌ Asset Management
• ❌ Transform Hierarchy
• ❌ Command Buffers

Checklist

• Implementation complete
• All tests passing (665 total)
• TypeScript compilation clean
• Linting passing
• Example provided
• Roadmap updated
• Conventional commit format

Breaking Changes

None - this is a new feature with no impact on existing APIs.