advanced-game-bootstrapper

Advanced Game Bootstrapper

Overview

Eliminate "Singleton Hell" and race conditions during game startup. The game MUST start from a specialized Bootstrap scene that loads all Managers (Sound, Save, Network) in deterministic order before showing any UI or Gameplay.

When to Use

• Use when starting a new Unity project
• Use when experiencing race conditions between managers
• Use when "Manager X not ready" errors occur on scene load
• Use when replacing scattered static singletons with proper architecture
• Use when implementing async initialization (loading screens)

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    BUILD INDEX 0                            │
│                   BOOTSTRAP SCENE                           │
├─────────────────────────────────────────────────────────────┤
│  GameBootstrapper (DontDestroyOnLoad)                       │
│    ├── AudioManager (order: 0)                              │
│    ├── SaveManager (order: 5)                               │
│    ├── NetworkManager (order: 10)                           │
│    └── AnalyticsManager (order: 15)                         │
├─────────────────────────────────────────────────────────────┤
│  [Optional] Loading Screen UI                               │
└─────────────────────────────────────────────────────────────┘
                          ↓
                   MAIN MENU SCENE
                          ↓
                   GAMEPLAY SCENE

Components

Procedure

1. Create Bootstrap Scene: New scene, set as Build Index 0
2. Generate Components: Create IInitializable.cs, GameBootstrapper.cs, BaseManager.cs
3. Create Managers: Inherit from BaseManager for each system
4. Configure Order: Set InitializationOrder (0-10: core, 11-50: gameplay, 51+: UI)
5. Assign References: Drag managers to GameBootstrapper in inspector

Best Practices

• ✅ Always use async/await for initialization that may take time
• ✅ Implement IShutdownable for managers that need cleanup
• ✅ Use InitializationOrder to enforce dependencies
• ✅ Keep Bootstrap scene as lightweight as possible
• ✅ Show loading progress to users during initialization
• ❌ NEVER use Awake/Start for cross-manager dependencies
• ❌ NEVER use static singletons (use DI or service locator instead)
• ❌ NEVER skip the bootstrap scene in builds

Testing Protocol

Few-Shot Examples

Example 1: Race Condition Fix

User: "The game crashes because AudioManager isn't ready when Player spawns."

Agent:

1. Implement Bootstrap Scene pattern
2. Create AudioManager : BaseManager with order 0
3. Create PlayerSpawner that only runs after bootstrap complete
4. AudioManager guaranteed ready before any gameplay

Example 2: Loading Screen Integration

User: "I want a loading bar while systems initialize."

Agent:

1. Add loading UI prefab to Bootstrap scene
2. Connect to GameBootstrapper._progressBar and _statusText
3. Progress updates automatically during initialization

Example 3: Network + Save Dependencies

User: "SaveManager needs NetworkManager to be ready first."

Agent:

1. NetworkManager.InitializationOrder = 5
2. SaveManager.InitializationOrder = 10
3. Bootstrapper initializes in order: Network → Save

TDD Contract

⚠️ Legacy Skill — Refactor Pending Este skill NO tiene tests automatizados aún. El siguiente boilerplate es un punto de partida.

// Escribe estos tests ANTES de implementar:

// Test 1: should [expected behavior] when [condition]
[Test]
public void AdvancedGameBootstrapper_Should{ExpectedBehavior}_When{Condition}()
{{
    // Arrange
    // TODO: Setup test fixtures
    
    // Act
    // TODO: Execute system under test
    
    // Assert
    Assert.Fail("Not implemented — write test first");
}}

// Test 2: should handle [edge case]
[Test]
public void AdvancedGameBootstrapper_ShouldHandle{EdgeCase}()
{{
    // Arrange
    // TODO: Setup edge case scenario
    
    // Act
    // TODO: Execute
    
    // Assert
    Assert.Fail("Not implemented");
}}

// Test 3: should throw when [invalid input]
[Test]
public void AdvancedGameBootstrapper_ShouldThrow_When{InvalidInput}()
{{
    // Arrange
    var invalidInput = default;
    
    // Act & Assert
    Assert.Throws<Exception>(() => {{ /* execute */ }});
}}

Pasos para completar el TDD:

1. Descomenta los tests above
2. Implementa la funcionalidad mínima para que compile
3. Ejecuta los tests — deben fallar (RED)
4. Implementa la funcionalidad real
5. Verifica que los tests pasen (GREEN)
6. Refactorea manteniendo los tests verdes

Nota: Este skill fue marcado como tdd_first: false durante la auditoría v2.0.1. La sección TDD fue agregada automáticamente pero requiere customización manual para reflejar el comportamiento real del skill.

Related Skills

• @di-container-manager - For injecting bootstrapped managers
• @event-bus-system - For broadcasting initialization events
• @scriptableobject-architecture - For configuration data

Template Files

• templates/IInitializable.cs.txt - Core interface
• templates/GameBootstrapper.cs.txt - Main bootstrapper
• templates/BaseManager.cs.txt - Manager base class