1437 lines
51 KiB
Markdown
1437 lines
51 KiB
Markdown
# ManagedBehaviour Lifecycle System - Implementation Guide
|
|
|
|
## Overview
|
|
This document provides a step-by-step implementation plan for creating a custom lifecycle management system that extends MonoBehaviour with deterministic, ordered lifecycle hooks. The system integrates with existing bootstrap, scene management, save/load, and game state management infrastructure.
|
|
|
|
---
|
|
|
|
## Current System Analysis
|
|
|
|
### Existing Lifecycle Flow
|
|
1. **Unity Bootstrap Phase**
|
|
- `RuntimeInitializeOnLoadMethod(BeforeSplashScreen)` → `CustomBoot.Initialise()`
|
|
- Loads CustomBootSettings via Addressables
|
|
- BootstrapScene loads with initial GameObjects
|
|
|
|
2. **Unity Standard Lifecycle**
|
|
- `Awake()` - All MonoBehaviours (unordered within frame)
|
|
- `OnEnable()` - After Awake phase
|
|
- `Start()` - After OnEnable phase
|
|
- Game loop: `Update()`, `FixedUpdate()`, `LateUpdate()`
|
|
|
|
3. **Custom Bootstrap Integration**
|
|
- Components register with `BootCompletionService.RegisterInitAction()` in `Awake()`
|
|
- `CustomBoot` completes → triggers `BootCompletionService.HandleBootCompleted()`
|
|
- `BootCompletionService` executes registered actions (priority-sorted, 0-1000+)
|
|
- Components implement `InitializePostBoot()` methods
|
|
|
|
4. **Scene Lifecycle Integration**
|
|
- `SceneManagerService` manages additive scene loading/unloading
|
|
- Components subscribe to `SceneLoadCompleted` and `SceneUnloadStarted` events
|
|
- `SceneManagerService.SwitchSceneAsync()` handles scene transitions
|
|
|
|
5. **Save/Load System**
|
|
- `SaveLoadManager` maintains registry of `ISaveParticipant` components
|
|
- Components call `RegisterParticipant()` in post-boot initialization
|
|
- Components call `UnregisterParticipant()` in `OnDestroy()`
|
|
- State restoration happens after load or when new participants register
|
|
|
|
6. **Game State Management (GameManager)**
|
|
- Pause/Resume system with counter-based requests
|
|
- `IPausable` component registration (manual Subscribe/Unsubscribe)
|
|
- Settings initialization (ServiceLocator pattern)
|
|
- Developer settings integration
|
|
|
|
### Existing Patterns
|
|
- **Singleton Pattern**: All managers use `_instance` field with `Instance` property
|
|
- **Two-Phase Init**: `Awake()` + `InitializePostBoot()`
|
|
- **Priority-Based Boot**: Components specify boot priority (10-100+, lower = earlier)
|
|
- **Manual Event Management**: Subscribe in OnEnable/Start, unsubscribe in OnDestroy
|
|
- **Inheritance Example**: `InteractionActionBase` provides `protected virtual` lifecycle hooks
|
|
|
|
---
|
|
|
|
## Architecture Design
|
|
|
|
### Core Components
|
|
|
|
#### 1. LifecycleManager (Singleton)
|
|
Central orchestrator that:
|
|
- Maintains registries of all ManagedBehaviours (separate lists per lifecycle phase)
|
|
- Broadcasts lifecycle events in priority-sorted order
|
|
- Integrates with BootCompletionService, SceneManagerService, SaveLoadManager, GameManager
|
|
- Handles late registration and edge cases
|
|
- Provides optional debug/profiling tools
|
|
|
|
#### 2. ManagedBehaviour (Base Class)
|
|
Enhanced MonoBehaviour providing:
|
|
- Virtual lifecycle hooks (opt-in via override)
|
|
- Automatic registration/unregistration with LifecycleManager
|
|
- Priority/ordering support via properties
|
|
- Built-in managed event subscription system (auto-cleanup)
|
|
- Optional auto-integration with SaveLoadManager and GameManager
|
|
|
|
#### 3. ManagedEvent System
|
|
Helper system for automatic event subscription cleanup:
|
|
- Stores event subscriptions internally
|
|
- Auto-unsubscribes all events on destruction
|
|
- Prevents memory leaks and manual cleanup
|
|
|
|
---
|
|
|
|
## Lifecycle Phases
|
|
|
|
### Complete Lifecycle Flow
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ PHASE 1: UNITY ENGINE BOOTSTRAP │
|
|
│ - RuntimeInitializeOnLoadMethod (CustomBoot.Initialise) │
|
|
│ - BootstrapScene loads │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ PHASE 2: UNITY STANDARD LIFECYCLE │
|
|
│ - Unity Awake() [all MonoBehaviours] │
|
|
│ └→ ManagedBehaviour.Awake() auto-registers with Manager │
|
|
│ - Unity OnEnable() │
|
|
│ - Unity Start() │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ PHASE 3: MANAGED AWAKE (Deterministic) │
|
|
│ - LifecycleManager.BroadcastManagedAwake() │
|
|
│ - Calls OnManagedAwake() in priority order (0→1000) │
|
|
│ - Singleton initialization, component setup │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ PHASE 4: BOOT COMPLETION │
|
|
│ - CustomBoot completes │
|
|
│ - BootCompletionService.HandleBootCompleted() │
|
|
│ - LifecycleManager.BroadcastBootComplete() │
|
|
│ - Calls OnBootComplete() in priority order │
|
|
│ - Settings loaded, services initialized │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ PHASE 5: SCENE READY │
|
|
│ - SceneManagerService finishes loading │
|
|
│ - LifecycleManager.BroadcastSceneReady() │
|
|
│ - Calls OnSceneReady() for all active ManagedBehaviours │
|
|
│ - Scene-specific initialization │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ PHASE 6: GAME LOOP (Runtime) │
|
|
│ - Unity Update/FixedUpdate/LateUpdate │
|
|
│ - Optional: OnManagedUpdate() (priority-ordered) │
|
|
│ - Optional: OnManagedFixedUpdate() (priority-ordered) │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ PHASE 7: PAUSE/RESUME (State Change) │
|
|
│ - GameManager.RequestPause() / ReleasePause() │
|
|
│ - LifecycleManager.BroadcastPause/Resume() │
|
|
│ - Calls OnPaused() / OnResumed() for all active │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ PHASE 8: SCENE UNLOADING (Transition) │
|
|
│ - SceneManagerService.SwitchSceneAsync() starts │
|
|
│ - LifecycleManager.BroadcastSceneUnloading() │
|
|
│ - Calls OnSceneUnloading() for scene-specific components │
|
|
│ - Cleanup before scene unload │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ PHASE 9: DESTRUCTION │
|
|
│ - Unity OnDisable() │
|
|
│ - Unity OnDestroy() │
|
|
│ └→ ManagedBehaviour.OnDestroy() auto-unregisters │
|
|
│ - LifecycleManager.BroadcastManagedDestroy() │
|
|
│ - Calls OnManagedDestroy() in reverse priority order │
|
|
│ - Auto-cleanup of managed events │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Lifecycle Hook Reference
|
|
| Hook Name | Priority Order | When Called | Use Case |
|
|
|-----------|----------------|-------------|----------|
|
|
| `OnManagedAwake()` | Low→High (0→∞) | After Unity Awake, before Start | Deterministic initialization |
|
|
| `OnBootComplete()` | Low→High (0→∞) | After CustomBoot completes | Post-boot initialization (replaces InitializePostBoot) |
|
|
| `OnSceneReady()` | Low→High (0→∞) | After scene fully loaded | Scene-specific setup |
|
|
| `OnManagedUpdate()` | Low→High (0→∞) | Every frame (optional) | Ordered per-frame logic |
|
|
| `OnManagedFixedUpdate()` | Low→High (0→∞) | Every physics frame (optional) | Ordered physics logic |
|
|
| `OnPaused()` | Low→High (0→∞) | When game pauses | Pause state handling |
|
|
| `OnResumed()` | Low→High (0→∞) | When game resumes | Resume state handling |
|
|
| `OnSceneUnloading()` | High→Low (∞→0) | Before scene unloads | Scene cleanup |
|
|
| `OnManagedDestroy()` | High→Low (∞→0) | Before Unity OnDestroy | Guaranteed cleanup |
|
|
|
|
---
|
|
|
|
## Implementation Steps
|
|
|
|
### STEP 1: Create Core Enums and Interfaces
|
|
**File**: `Assets/Scripts/Core/Lifecycle/LifecycleEnums.cs`
|
|
|
|
**Actions**:
|
|
1. Create namespace `Core.Lifecycle`
|
|
2. Define `LifecyclePhase` enum with all phases
|
|
3. Define `LifecycleFlags` enum for component opt-in (bitflags)
|
|
4. Add XML documentation for each value
|
|
|
|
**Key Details**:
|
|
- LifecyclePhase: ManagedAwake, BootComplete, SceneReady, Update, FixedUpdate, Paused, Resumed, SceneUnloading, ManagedDestroy
|
|
- LifecycleFlags: None, ManagedAwake, BootComplete, SceneReady, ManagedUpdate, ManagedFixedUpdate, Pause, SceneUnloading, ManagedDestroy, All (bitwise OR of all)
|
|
|
|
---
|
|
|
|
### STEP 2: Create ManagedEvent System
|
|
**File**: `Assets/Scripts/Core/Lifecycle/ManagedEventSubscription.cs`
|
|
|
|
**Actions**:
|
|
1. Create internal struct `ManagedEventSubscription` to store event delegate and target
|
|
2. Create class `ManagedEventManager` with:
|
|
- List of subscriptions per ManagedBehaviour
|
|
- `RegisterEvent<T>(target, action)` method
|
|
- `UnregisterAllEvents()` method that invokes `-=` on all stored subscriptions
|
|
3. Handle both `Action` and generic `Action<T>` delegates
|
|
4. Use reflection to dynamically unsubscribe
|
|
|
|
**Key Details**:
|
|
- Store event info as: object target (event owner), Delegate handler, string eventName
|
|
- Support common Unity event patterns (Action, Action\<T\>, UnityEvent, etc.)
|
|
- Provide safe null checks before unsubscribing
|
|
|
|
---
|
|
|
|
### STEP 3: Create ManagedBehaviour Base Class (Structure)
|
|
**File**: `Assets/Scripts/Core/Lifecycle/ManagedBehaviour.cs`
|
|
|
|
**Actions**:
|
|
1. Create abstract class `ManagedBehaviour : MonoBehaviour`
|
|
2. Add virtual properties for priorities:
|
|
- `ManagedAwakePriority` (default 100)
|
|
- `BootCompletePriority` (default 100)
|
|
- `SceneReadyPriority` (default 100)
|
|
- `UpdatePriority` (default 100)
|
|
- `DestroyPriority` (default 100)
|
|
3. Add property `ActiveLifecyclePhases` (returns LifecycleFlags, default None)
|
|
4. Add property `AutoRegisterSaveParticipant` (default false)
|
|
5. Add property `AutoRegisterPausable` (default false)
|
|
6. Add property `IsPersistent` (default false) - survives scene changes
|
|
7. Add private field `ManagedEventManager _eventManager`
|
|
8. Add private bool `_isRegistered` to track registration state
|
|
|
|
**Key Details**:
|
|
- All priority properties are virtual so subclasses can override
|
|
- ActiveLifecyclePhases determines which hooks are called (opt-in)
|
|
- IsPersistent flag controls whether component persists across scenes
|
|
|
|
---
|
|
|
|
### STEP 4: Implement ManagedBehaviour Lifecycle Hooks (Virtual Methods)
|
|
**File**: `Assets/Scripts/Core/Lifecycle/ManagedBehaviour.cs` (continued)
|
|
|
|
**Actions**:
|
|
1. Add virtual protected methods (empty by default):
|
|
- `OnManagedAwake()`
|
|
- `OnBootComplete()`
|
|
- `OnSceneReady()`
|
|
- `OnManagedUpdate()`
|
|
- `OnManagedFixedUpdate()`
|
|
- `OnPaused()`
|
|
- `OnResumed()`
|
|
- `OnSceneUnloading()`
|
|
- `OnManagedDestroy()`
|
|
2. Add XML documentation for each method
|
|
3. Add protected helper methods:
|
|
- `RegisterManagedEvent<T>(target, action)` - wraps _eventManager
|
|
- `IsLifecyclePhaseActive(LifecyclePhase)` - checks flags
|
|
|
|
**Key Details**:
|
|
- All hooks are `protected virtual void` (no return value)
|
|
- Empty implementations allow opt-in override pattern
|
|
- Use `[Conditional("UNITY_EDITOR")]` attribute for debug-only hooks if needed
|
|
|
|
---
|
|
|
|
### STEP 5: Implement ManagedBehaviour Unity Integration
|
|
**File**: `Assets/Scripts/Core/Lifecycle/ManagedBehaviour.cs` (continued)
|
|
|
|
**Actions**:
|
|
1. Implement `protected virtual void Awake()`:
|
|
- Initialize _eventManager
|
|
- Register with LifecycleManager (call `LifecycleManager.Instance.Register(this)`)
|
|
- Set _isRegistered = true
|
|
2. Implement `protected virtual void OnDestroy()`:
|
|
- Unregister from LifecycleManager (call `LifecycleManager.Instance.Unregister(this)`)
|
|
- Call _eventManager.UnregisterAllEvents()
|
|
- Auto-unregister from SaveLoadManager and GameManager if applicable
|
|
- Set _isRegistered = false
|
|
3. Make both methods call base implementation warning (for subclasses)
|
|
|
|
**Key Details**:
|
|
- Use null checks for LifecycleManager.Instance (may not exist during shutdown)
|
|
- Provide clear error logging if registration fails
|
|
- Support scenario where subclass overrides Awake/OnDestroy (must call base)
|
|
|
|
---
|
|
|
|
### STEP 6: Create LifecycleManager (Structure)
|
|
**File**: `Assets/Scripts/Core/Lifecycle/LifecycleManager.cs`
|
|
|
|
**Actions**:
|
|
1. Create class `LifecycleManager : MonoBehaviour`
|
|
2. Implement singleton pattern (private static _instance, public static Instance)
|
|
3. Add separate `List<ManagedBehaviour>` for each lifecycle phase:
|
|
- `_managedAwakeList`
|
|
- `_bootCompleteList`
|
|
- `_sceneReadyList`
|
|
- `_updateList`
|
|
- `_fixedUpdateList`
|
|
- `_pauseList`
|
|
- `_sceneUnloadingList`
|
|
- `_destroyList`
|
|
4. Add Dictionary<ManagedBehaviour, int> for tracking which lists each component is in (bitmask)
|
|
5. Add bool flags: `_isBootComplete`, `_isSceneReady`, `_isPaused`
|
|
6. Add queue for late registrations: `Queue<ManagedBehaviour> _pendingRegistrations`
|
|
|
|
**Key Details**:
|
|
- Each list must be kept sorted by priority
|
|
- Use SortedList or List with manual sorting after registration
|
|
- Dictionary tracks which phases each component participates in
|
|
|
|
---
|
|
|
|
### STEP 7: Implement LifecycleManager Registration System
|
|
**File**: `Assets/Scripts/Core/Lifecycle/LifecycleManager.cs` (continued)
|
|
|
|
**Actions**:
|
|
1. Implement `public void Register(ManagedBehaviour component)`:
|
|
- Check component.ActiveLifecyclePhases flags
|
|
- Add to appropriate lists based on flags
|
|
- Insert in priority-sorted position
|
|
- Handle auto-registration with SaveLoadManager if component is ISaveParticipant && AutoRegisterSaveParticipant
|
|
- Handle auto-registration with GameManager if component is IPausable && AutoRegisterPausable
|
|
- If boot already complete and component has BootComplete flag, immediately call OnBootComplete
|
|
- If scene already ready and component has SceneReady flag, immediately call OnSceneReady
|
|
2. Implement `public void Unregister(ManagedBehaviour component)`:
|
|
- Remove from all lists
|
|
- Handle auto-unregistration from SaveLoadManager and GameManager
|
|
|
|
**Key Details**:
|
|
- Use binary search for insertion point (lists sorted by priority)
|
|
- Handle edge case: registration during broadcast (queue and process later)
|
|
- Validate component is not null and has valid priorities
|
|
|
|
---
|
|
|
|
### STEP 8: Implement LifecycleManager Broadcast System
|
|
**File**: `Assets/Scripts/Core/Lifecycle/LifecycleManager.cs` (continued)
|
|
|
|
**Actions**:
|
|
1. Implement broadcast methods for each phase:
|
|
- `BroadcastManagedAwake()`
|
|
- `BroadcastBootComplete()`
|
|
- `BroadcastSceneReady()`
|
|
- `BroadcastPause()`
|
|
- `BroadcastResume()`
|
|
- `BroadcastSceneUnloading()`
|
|
- `BroadcastManagedDestroy()`
|
|
2. Each method iterates through corresponding list and calls hook
|
|
3. Add try-catch around each call with error logging
|
|
4. Process pending registrations after broadcast completes
|
|
5. Set state flags (_isBootComplete, _isSceneReady, _isPaused)
|
|
|
|
**Key Details**:
|
|
- Iterate forward for normal phases (low→high priority)
|
|
- Iterate backward for cleanup phases (SceneUnloading, ManagedDestroy)
|
|
- Use `for` loop with index (not foreach) to handle list modifications
|
|
- Log phase start/end with timing info (use Stopwatch)
|
|
|
|
---
|
|
|
|
### STEP 9: Implement LifecycleManager Update Handlers
|
|
**File**: `Assets/Scripts/Core/Lifecycle/LifecycleManager.cs` (continued)
|
|
|
|
**Actions**:
|
|
1. Implement `void Update()`:
|
|
- Check if _updateList is empty (skip if so)
|
|
- Iterate _updateList and call OnManagedUpdate() on each
|
|
- Add try-catch with error logging
|
|
2. Implement `void FixedUpdate()`:
|
|
- Check if _fixedUpdateList is empty (skip if so)
|
|
- Iterate _fixedUpdateList and call OnManagedFixedUpdate() on each
|
|
- Add try-catch with error logging
|
|
3. Add optimization: disable Update/FixedUpdate when lists are empty
|
|
|
|
**Key Details**:
|
|
- Use `enabled = false` when no components registered for updates
|
|
- Re-enable when first component registers
|
|
- Consider pooling/caching for performance
|
|
|
|
---
|
|
|
|
### STEP 10: Integrate LifecycleManager with Bootstrap
|
|
**File**: `Assets/Scripts/Core/Lifecycle/LifecycleManager.cs` (continued)
|
|
|
|
**Actions**:
|
|
1. In `Awake()`:
|
|
- Set singleton instance
|
|
- Subscribe to BootCompletionService.OnBootComplete
|
|
- Set up initial state
|
|
2. Implement handler for `BootCompletionService.OnBootComplete`:
|
|
- Set _isBootComplete = true
|
|
- Call BroadcastManagedAwake() first (if not already called)
|
|
- Then call BroadcastBootComplete()
|
|
3. Add `Start()` method:
|
|
- Call BroadcastManagedAwake() if boot not complete yet (fallback)
|
|
|
|
**Key Details**:
|
|
- LifecycleManager should exist in BootstrapScene (persistent)
|
|
- Must handle both editor and runtime initialization
|
|
- Consider RuntimeInitializeOnLoadMethod for creation if needed
|
|
|
|
---
|
|
|
|
### STEP 11: Integrate LifecycleManager with SceneManagerService
|
|
**File**: `Assets/Scripts/Core/Lifecycle/LifecycleManager.cs` (continued)
|
|
|
|
**Actions**:
|
|
1. In post-boot initialization:
|
|
- Subscribe to SceneManagerService.Instance.SceneLoadCompleted
|
|
- Subscribe to SceneManagerService.Instance.SceneUnloadStarted
|
|
2. Implement handler for `SceneLoadCompleted`:
|
|
- Set _isSceneReady = true
|
|
- Call BroadcastSceneReady()
|
|
- Handle scene-specific vs persistent components (check IsPersistent flag)
|
|
3. Implement handler for `SceneUnloadStarted`:
|
|
- Set _isSceneReady = false
|
|
- Call BroadcastSceneUnloading()
|
|
- Only call on scene-specific components (IsPersistent = false)
|
|
4. In `OnDestroy()`:
|
|
- Unsubscribe from all events
|
|
|
|
**Key Details**:
|
|
- Track which scene each component belongs to (use component.gameObject.scene)
|
|
- Only broadcast SceneReady/Unloading to components in affected scene
|
|
- Persistent components (BootstrapScene) should not receive scene lifecycle events
|
|
|
|
---
|
|
|
|
### STEP 12: Integrate LifecycleManager with GameManager (Pause System)
|
|
**File**: `Assets/Scripts/Core/Lifecycle/LifecycleManager.cs` (continued)
|
|
|
|
**Actions**:
|
|
1. In post-boot initialization:
|
|
- Subscribe to GameManager.Instance.OnGamePaused
|
|
- Subscribe to GameManager.Instance.OnGameResumed
|
|
2. Implement handler for `OnGamePaused`:
|
|
- Set _isPaused = true
|
|
- Call BroadcastPause()
|
|
3. Implement handler for `OnGameResumed`:
|
|
- Set _isPaused = false
|
|
- Call BroadcastResume()
|
|
|
|
**Key Details**:
|
|
- Components can opt-in to pause events via ActiveLifecyclePhases flags
|
|
- BroadcastPause/Resume iterates _pauseList only
|
|
- Late-registered components get immediate pause state if game is paused
|
|
|
|
---
|
|
|
|
### STEP 13: Add Debug and Profiling Tools
|
|
**File**: `Assets/Scripts/Core/Lifecycle/LifecycleManager.cs` (continued)
|
|
|
|
**Actions**:
|
|
1. Add `[SerializeField] private bool enableDebugLogging = false`
|
|
2. Add `[SerializeField] private bool enableProfilingMarkers = true`
|
|
3. Create LogDebugMessage() helper that checks flag
|
|
4. Add Unity Profiler markers around each broadcast phase
|
|
5. Implement GetRegisteredComponents() method for inspector/debugging
|
|
6. Add OnGUI() debug overlay showing:
|
|
- Registered component counts per phase
|
|
- Current lifecycle state flags
|
|
- Last broadcast timings
|
|
|
|
**Key Details**:
|
|
- Use `UnityEngine.Profiling.ProfilerMarker` for zero-cost profiling in builds
|
|
- Debug overlay only active in editor or development builds
|
|
- Consider creating custom inspector for LifecycleManager
|
|
|
|
---
|
|
|
|
### STEP 14: Create LifecycleManager Prefab
|
|
**File**: `Assets/Prefabs/Core/LifecycleManager.prefab`
|
|
|
|
**Actions**:
|
|
1. Create empty GameObject named "LifecycleManager"
|
|
2. Add LifecycleManager component
|
|
3. Configure default settings (debug logging off, profiling on)
|
|
4. Save as prefab
|
|
5. Add to BootstrapScene if not already present
|
|
6. Verify it persists across scenes (should be in BootstrapScene which is additive)
|
|
|
|
**Key Details**:
|
|
- Only one instance should exist (singleton)
|
|
- Should be in BootstrapScene, not in gameplay scenes
|
|
- Consider adding validation script to prevent duplicates
|
|
|
|
---
|
|
|
|
### STEP 15: Update Bootstrap Integration
|
|
**File**: `Assets/Scripts/Bootstrap/BootCompletionService.cs`
|
|
|
|
**Actions**:
|
|
1. In `HandleBootCompleted()` method, add:
|
|
- Before executing initialization actions, notify LifecycleManager
|
|
- Call `LifecycleManager.Instance?.OnBootCompletionStarting()` (new method)
|
|
2. After initialization actions complete:
|
|
- Call existing `OnBootComplete?.Invoke()`
|
|
- LifecycleManager handles this via event subscription
|
|
|
|
**File**: `Assets/Scripts/Bootstrap/CustomBoot.cs`
|
|
|
|
**Actions**:
|
|
1. Verify LifecycleManager exists before CustomBoot completes
|
|
2. Add fallback: if LifecycleManager doesn't exist, log warning
|
|
|
|
**Key Details**:
|
|
- BootCompletionService remains authoritative for boot completion
|
|
- LifecycleManager observes and broadcasts to ManagedBehaviours
|
|
- Maintain backward compatibility with existing RegisterInitAction pattern
|
|
|
|
---
|
|
|
|
### STEP 16: Extend SaveLoadManager Integration
|
|
**File**: `Assets/Scripts/Core/SaveLoad/SaveLoadManager.cs`
|
|
|
|
**Actions**:
|
|
1. Add public method `AutoRegisterParticipant(ISaveParticipant participant, ManagedBehaviour owner)`:
|
|
- Same as RegisterParticipant but stores reference to owner ManagedBehaviour
|
|
- Allows automatic unregistration when owner is destroyed
|
|
2. Add public method `AutoUnregisterParticipant(ManagedBehaviour owner)`:
|
|
- Looks up participant by owner reference and unregisters
|
|
3. Store Dictionary<ManagedBehaviour, string> to track auto-registrations
|
|
|
|
**File**: `Assets/Scripts/Core/Lifecycle/ManagedBehaviour.cs`
|
|
|
|
**Actions**:
|
|
1. In Awake() registration:
|
|
- Check if `this is ISaveParticipant` and `AutoRegisterSaveParticipant == true`
|
|
- If yes, call SaveLoadManager.Instance.AutoRegisterParticipant(this as ISaveParticipant, this)
|
|
2. In OnDestroy() cleanup:
|
|
- Call SaveLoadManager.Instance.AutoUnregisterParticipant(this)
|
|
|
|
**Key Details**:
|
|
- Only auto-register after boot completes (SaveLoadManager must be initialized)
|
|
- Handle null checks (SaveLoadManager may not exist in editor)
|
|
- Log when auto-registration occurs (debug mode)
|
|
|
|
---
|
|
|
|
### STEP 17: Extend GameManager Pausable Integration
|
|
**File**: `Assets/Scripts/Core/GameManager.cs`
|
|
|
|
**Actions**:
|
|
1. Add public method `AutoRegisterPausable(IPausable component, ManagedBehaviour owner)`:
|
|
- Same as RegisterPausableComponent but stores owner reference
|
|
2. Add public method `AutoUnregisterPausable(ManagedBehaviour owner)`:
|
|
- Looks up pausable by owner and unregisters
|
|
3. Store Dictionary<ManagedBehaviour, IPausable> to track auto-registrations
|
|
|
|
**File**: `Assets/Scripts/Core/Lifecycle/ManagedBehaviour.cs`
|
|
|
|
**Actions**:
|
|
1. In post-boot registration (called by LifecycleManager):
|
|
- Check if `this is IPausable` and `AutoRegisterPausable == true`
|
|
- If yes, call GameManager.Instance.AutoRegisterPausable(this as IPausable, this)
|
|
2. In OnDestroy() cleanup:
|
|
- Call GameManager.Instance.AutoUnregisterPausable(this)
|
|
|
|
**Key Details**:
|
|
- Wait until boot completes before registering with GameManager
|
|
- Handle case where component implements both ISaveParticipant and IPausable
|
|
- Verify GameManager exists before calling
|
|
|
|
---
|
|
|
|
### STEP 18: Create Migration Helper Attribute
|
|
**File**: `Assets/Scripts/Core/Lifecycle/RequiresManagedBehaviourAttribute.cs`
|
|
|
|
**Actions**:
|
|
1. Create custom attribute `[RequiresManagedBehaviour]`
|
|
2. Can be applied to classes that should be converted to ManagedBehaviour
|
|
3. Create custom inspector that shows warning if class derives from MonoBehaviour instead
|
|
|
|
**File**: `Assets/Editor/ManagedBehaviourValidation.cs`
|
|
|
|
**Actions**:
|
|
1. Create editor script that scans project for components with attribute
|
|
2. Shows list of components needing migration
|
|
3. Provides "Convert to ManagedBehaviour" button for each
|
|
4. Automatic string replacement in source files
|
|
|
|
**Key Details**:
|
|
- Editor-only functionality (Assets/Editor folder)
|
|
- Use AssetDatabase to find and modify scripts
|
|
- Show before/after preview before conversion
|
|
|
|
---
|
|
|
|
### STEP 19: Create Example ManagedBehaviour Implementations
|
|
**File**: `Assets/Scripts/Core/Lifecycle/Examples/ExampleManagedSingleton.cs`
|
|
|
|
**Actions**:
|
|
1. Create example showing singleton pattern with ManagedBehaviour
|
|
2. Demonstrate priority usage
|
|
3. Show lifecycle hook overrides
|
|
4. Include code comments explaining each part
|
|
|
|
**File**: `Assets/Scripts/Core/Lifecycle/Examples/ExampleManagedComponent.cs`
|
|
|
|
**Actions**:
|
|
1. Create example showing scene-specific component
|
|
2. Demonstrate managed event subscription
|
|
3. Show auto-save participant integration
|
|
4. Show auto-pausable integration
|
|
|
|
**File**: `Assets/Scripts/Core/Lifecycle/Examples/ExampleManagedManager.cs`
|
|
|
|
**Actions**:
|
|
1. Create example showing persistent manager
|
|
2. Demonstrate all lifecycle phases
|
|
3. Show priority ordering
|
|
4. Include performance considerations
|
|
|
|
**Key Details**:
|
|
- Well-commented code for reference
|
|
- Cover common use cases (singleton, scene component, manager)
|
|
- Include unit tests if applicable
|
|
|
|
---
|
|
|
|
### STEP 20: Migrate Core Systems (Phase 1)
|
|
**Priority Order**: GameManager → SceneManagerService → SaveLoadManager → InputManager
|
|
|
|
**File**: `Assets/Scripts/Core/GameManager.cs`
|
|
|
|
**Actions**:
|
|
1. Change class declaration: `public class GameManager : ManagedBehaviour`
|
|
2. Override properties:
|
|
- `protected override int ManagedAwakePriority => 10;` (very early)
|
|
- `protected override int BootCompletePriority => 10;`
|
|
3. Remove `BootCompletionService.RegisterInitAction(InitializePostBoot)` from Awake
|
|
4. Rename `InitializePostBoot()` to `protected override void OnBootComplete()`
|
|
5. Move Awake logic to `protected override void OnManagedAwake()`
|
|
6. Add `protected override LifecycleFlags ActiveLifecyclePhases => LifecycleFlags.ManagedAwake | LifecycleFlags.BootComplete;`
|
|
7. Keep existing pause/resume system (don't double-integrate)
|
|
8. Remove manual singleton setup (handled by base class)
|
|
9. Test thoroughly
|
|
|
|
**Key Details**:
|
|
- GameManager initializes early (priority 10)
|
|
- Keep existing functionality intact
|
|
- Verify settings loading still works
|
|
- Ensure pause system integration works
|
|
|
|
---
|
|
|
|
### STEP 21: Migrate Core Systems (Phase 2)
|
|
**Target**: SceneManagerService, SaveLoadManager, InputManager, ItemManager
|
|
|
|
**For Each File**:
|
|
1. Change base class to ManagedBehaviour
|
|
2. Set appropriate priorities (15-30 range)
|
|
3. Move InitializePostBoot → OnBootComplete
|
|
4. Remove manual BootCompletionService registration
|
|
5. Add ActiveLifecyclePhases flags
|
|
6. Test scene transitions, save/load, input handling
|
|
|
|
**Priorities**:
|
|
- SceneManagerService: 15 (after GameManager)
|
|
- SaveLoadManager: 20 (after SceneManagerService)
|
|
- InputManager: 25 (after SaveLoadManager)
|
|
- ItemManager: 30 (general manager)
|
|
|
|
**Key Details**:
|
|
- Verify event subscriptions still work
|
|
- Check scene loading/unloading
|
|
- Validate save/load system
|
|
- Test input handling in different modes
|
|
|
|
---
|
|
|
|
### STEP 22: Migrate UI Systems
|
|
**Target**: UIPageController, LoadingScreenController, PauseMenu, CardSystemUI components
|
|
|
|
**For Each File**:
|
|
1. Change base class to ManagedBehaviour
|
|
2. Set priority 50-100 (standard range)
|
|
3. Convert InitializePostBoot → OnBootComplete
|
|
4. Use RegisterManagedEvent for event subscriptions
|
|
5. Add OnSceneReady override if needed for scene-specific UI
|
|
6. Test UI navigation, loading screens, pause menu
|
|
|
|
**Key Details**:
|
|
- UI generally has lower priority than managers
|
|
- Scene-specific UI should override OnSceneReady
|
|
- Use AutoRegisterSaveParticipant for UI with state
|
|
|
|
---
|
|
|
|
### STEP 23: Migrate Gameplay Systems
|
|
**Target**: PuzzleManager, DivingGameManager, CinematicsManager, CardSystemManager
|
|
|
|
**For Each File**:
|
|
1. Change base class to ManagedBehaviour
|
|
2. Set priority 100-200 (gameplay systems)
|
|
3. Convert InitializePostBoot → OnBootComplete
|
|
4. Use OnSceneReady for scene-specific setup
|
|
5. Use OnSceneUnloading for cleanup
|
|
6. Consider AutoRegisterSaveParticipant
|
|
7. Test gameplay features
|
|
|
|
**Key Details**:
|
|
- Scene-specific managers should handle OnSceneReady/Unloading
|
|
- Persistent managers (like CardSystemManager) set IsPersistent = true
|
|
- Verify minigame transitions work correctly
|
|
|
|
---
|
|
|
|
### STEP 24: Migrate Interaction Systems
|
|
**Target**: Interactable, InteractionActionBase, DialogueComponent
|
|
|
|
**File**: `Assets/Scripts/Interactions/InteractionActionBase.cs`
|
|
|
|
**Actions**:
|
|
1. Change base class from MonoBehaviour to ManagedBehaviour
|
|
2. Change `protected virtual void Awake()` to `protected override void OnManagedAwake()`
|
|
3. Keep OnEnable/OnDisable as-is (Unity lifecycle needed for enable/disable)
|
|
4. Consider using RegisterManagedEvent for parentInteractable events
|
|
|
|
**Key Details**:
|
|
- InteractionActionBase is itself a base class (virtual methods remain)
|
|
- Subclasses inherit ManagedBehaviour capabilities
|
|
- Test interaction flow thoroughly
|
|
|
|
---
|
|
|
|
### STEP 25: Migrate Player and Movement Systems
|
|
**Target**: PlayerTouchController, FollowerController
|
|
|
|
**For Each File**:
|
|
1. Change base class to ManagedBehaviour
|
|
2. Keep Update() as Unity Update (movement needs every frame)
|
|
3. Use OnBootComplete for post-boot initialization
|
|
4. Use RegisterManagedEvent for InputManager event subscriptions
|
|
5. Test movement, pathfinding, interactions
|
|
|
|
**Key Details**:
|
|
- Performance-critical components should use Unity Update, not OnManagedUpdate
|
|
- Only use ManagedBehaviour for initialization/cleanup benefits
|
|
- Verify A* pathfinding still works
|
|
|
|
---
|
|
|
|
### STEP 26: Update InteractionActionBase Pattern
|
|
**File**: `Assets/Scripts/Interactions/InteractionActionBase.cs`
|
|
|
|
**Actions**:
|
|
1. Since this is a base class, ensure subclasses can override lifecycle hooks
|
|
2. Add example subclass showing proper override chain
|
|
3. Document pattern for action components
|
|
|
|
**Pattern**:
|
|
```csharp
|
|
public class MyAction : InteractionActionBase
|
|
{
|
|
protected override void OnManagedAwake()
|
|
{
|
|
base.OnManagedAwake(); // Calls parent registration
|
|
// Custom initialization
|
|
}
|
|
}
|
|
```
|
|
|
|
**Key Details**:
|
|
- Base.OnManagedAwake() must be called in subclasses
|
|
- Provide clear documentation for this pattern
|
|
- Consider sealed methods if override not intended
|
|
|
|
---
|
|
|
|
### STEP 27: Create Validation and Testing Suite
|
|
**File**: `Assets/Editor/Tests/LifecycleSystemTests.cs`
|
|
|
|
**Actions**:
|
|
1. Create Unity Test Runner tests for:
|
|
- Registration/unregistration
|
|
- Priority ordering
|
|
- Lifecycle hook execution order
|
|
- Event subscription cleanup
|
|
- Save/load integration
|
|
- Pause system integration
|
|
- Scene transition handling
|
|
2. Create test ManagedBehaviour subclasses
|
|
3. Mock managers for isolated testing
|
|
|
|
**File**: `Assets/Scripts/Core/Lifecycle/LifecycleValidator.cs`
|
|
|
|
**Actions**:
|
|
1. Create runtime validator that checks:
|
|
- No duplicate registrations
|
|
- All ManagedBehaviours properly registered
|
|
- Priority conflicts (warnings)
|
|
- Missing overrides (if flags set but no override)
|
|
2. Add menu item "Tools/Lifecycle/Validate Scene"
|
|
|
|
**Key Details**:
|
|
- Tests should cover all lifecycle phases
|
|
- Include edge cases (late registration, scene transitions)
|
|
- Performance benchmarks for Update broadcasts
|
|
|
|
---
|
|
|
|
### STEP 28: Create Documentation
|
|
**File**: `docs/ManagedBehaviour_Usage_Guide.md`
|
|
|
|
**Content**:
|
|
1. Quick start guide
|
|
2. Common patterns and examples
|
|
3. Lifecycle phase reference
|
|
4. Priority guidelines
|
|
5. Performance considerations
|
|
6. Migration guide from MonoBehaviour
|
|
7. Troubleshooting section
|
|
|
|
**File**: `docs/ManagedBehaviour_API_Reference.md`
|
|
|
|
**Content**:
|
|
1. Complete API documentation
|
|
2. All virtual methods with parameters
|
|
3. All properties and their defaults
|
|
4. Integration points (SaveLoadManager, GameManager)
|
|
5. Best practices
|
|
|
|
**File**: `docs/ManagedBehaviour_Architecture.md`
|
|
|
|
**Content**:
|
|
1. System architecture diagram
|
|
2. Component interaction flows
|
|
3. Performance characteristics
|
|
4. Design decisions and rationale
|
|
5. Future extension points
|
|
|
|
---
|
|
|
|
### STEP 29: Performance Optimization Pass
|
|
**File**: `Assets/Scripts/Core/Lifecycle/LifecycleManager.cs`
|
|
|
|
**Actions**:
|
|
1. Profile Update/FixedUpdate broadcasts
|
|
2. Consider using Unity Jobs for parallel execution (if applicable)
|
|
3. Add object pooling for event subscriptions
|
|
4. Cache frequently accessed lists
|
|
5. Add compile-time flags for debug features
|
|
6. Optimize sort algorithms for registration
|
|
7. Consider lazy initialization for empty lists
|
|
|
|
**Targets**:
|
|
- Registration: < 0.1ms per component
|
|
- Update broadcast: < 0.5ms for 100 components
|
|
- Memory overhead: < 100 bytes per ManagedBehaviour
|
|
|
|
**Key Details**:
|
|
- Use Unity Profiler to identify bottlenecks
|
|
- Compare against baseline (vanilla MonoBehaviour)
|
|
- Optimize hot paths (Update broadcasts)
|
|
|
|
---
|
|
|
|
### STEP 30: Create Editor Tools
|
|
**File**: `Assets/Editor/LifecycleManagerInspector.cs`
|
|
|
|
**Actions**:
|
|
1. Custom inspector for LifecycleManager
|
|
2. Show registered components grouped by phase
|
|
3. Display component priorities
|
|
4. Show current state flags
|
|
5. Add "Force Broadcast" buttons for testing
|
|
6. Real-time component count display
|
|
|
|
**File**: `Assets/Editor/ManagedBehaviourInspector.cs`
|
|
|
|
**Actions**:
|
|
1. Custom inspector for ManagedBehaviour
|
|
2. Show active lifecycle phases (visual flags)
|
|
3. Display current registration status
|
|
4. Show priority values
|
|
5. List registered managed events
|
|
6. Add "Test Lifecycle" button
|
|
|
|
**File**: `Assets/Editor/LifecycleDebugWindow.cs`
|
|
|
|
**Actions**:
|
|
1. Custom editor window "Window/Lifecycle/Debug"
|
|
2. Real-time lifecycle event log
|
|
3. Component hierarchy view
|
|
4. Priority visualization
|
|
5. Performance metrics
|
|
6. Event subscription viewer
|
|
|
|
---
|
|
|
|
### STEP 31: Final Integration Testing
|
|
**Test Scenarios**:
|
|
|
|
1. **Boot Sequence Test**:
|
|
- Start game from BootstrapScene
|
|
- Verify all lifecycle phases execute in order
|
|
- Check priority ordering is respected
|
|
- Validate settings load correctly
|
|
|
|
2. **Scene Transition Test**:
|
|
- Switch between multiple scenes
|
|
- Verify OnSceneReady called for new scenes
|
|
- Verify OnSceneUnloading called for old scenes
|
|
- Check persistent components don't receive scene events
|
|
|
|
3. **Save/Load Test**:
|
|
- Save game state
|
|
- Switch scenes
|
|
- Load saved state
|
|
- Verify all ISaveParticipant components restored
|
|
|
|
4. **Pause System Test**:
|
|
- Pause game (multiple requests)
|
|
- Verify all pausable components paused
|
|
- Resume game
|
|
- Verify all components resumed
|
|
|
|
5. **Late Registration Test**:
|
|
- Instantiate ManagedBehaviour after boot
|
|
- Verify it receives appropriate lifecycle calls
|
|
- Check it gets current state (paused, scene ready, etc.)
|
|
|
|
6. **Destruction Test**:
|
|
- Destroy ManagedBehaviours during gameplay
|
|
- Verify cleanup happens correctly
|
|
- Check no memory leaks (event subscriptions cleaned)
|
|
|
|
7. **Performance Test**:
|
|
- Spawn 100+ ManagedBehaviours
|
|
- Measure frame time impact
|
|
- Profile Update broadcasts
|
|
- Check memory usage
|
|
|
|
---
|
|
|
|
### STEP 32: Migration Strategy for Remaining Components
|
|
**Approach**: Gradual, category-by-category migration
|
|
|
|
**Phase 1: Critical Path** (Already covered in steps 20-25)
|
|
- Core managers
|
|
- UI systems
|
|
- Gameplay systems
|
|
|
|
**Phase 2: Scene-Specific Components**
|
|
- Level switches
|
|
- Minigame components
|
|
- Puzzle elements
|
|
- Scene triggers
|
|
|
|
**Phase 3: Utility Components**
|
|
- Camera systems
|
|
- Audio managers
|
|
- Effect spawners
|
|
- Pooling systems
|
|
|
|
**Phase 4: Low-Priority/External**
|
|
- Experimental scripts
|
|
- Test components
|
|
- External plugin wrappers
|
|
|
|
**For Each Component**:
|
|
1. Assess if it benefits from ManagedBehaviour (needs lifecycle control?)
|
|
2. If yes: follow migration pattern (change base class, update hooks)
|
|
3. If no: leave as MonoBehaviour (simple utility scripts)
|
|
4. Test after each file migrated
|
|
5. Commit to version control
|
|
|
|
**Key Details**:
|
|
- Not all components need migration (only those needing lifecycle control)
|
|
- Prioritize components with InitializePostBoot, scene event subscriptions, or complex initialization
|
|
- Simple components (visual effects, UI elements) can stay MonoBehaviour
|
|
- Document migration decisions in code comments
|
|
|
|
---
|
|
|
|
### STEP 33: Backward Compatibility Layer
|
|
**File**: `Assets/Scripts/Core/Lifecycle/LegacyMonoBehaviourAdapter.cs`
|
|
|
|
**Actions**:
|
|
1. Create adapter class for existing MonoBehaviour components
|
|
2. Allows non-migrated components to participate in lifecycle
|
|
3. Implement manual registration helper:
|
|
```csharp
|
|
public static class LifecycleHelper
|
|
{
|
|
public static void RegisterLegacyComponent(MonoBehaviour component, Action onBootComplete)
|
|
{
|
|
BootCompletionService.RegisterInitAction(onBootComplete);
|
|
}
|
|
}
|
|
```
|
|
4. Document when to use adapter vs. migration
|
|
|
|
**Key Details**:
|
|
- Provides bridge during migration period
|
|
- Allows incremental adoption
|
|
- Eventually can be deprecated once migration complete
|
|
|
|
---
|
|
|
|
### STEP 34: Code Cleanup and Refactoring
|
|
**Actions**:
|
|
|
|
1. **Remove Redundant Code**:
|
|
- Search for `BootCompletionService.RegisterInitAction` in migrated files (should be removed)
|
|
- Search for manual event subscription patterns (Convert to RegisterManagedEvent)
|
|
- Remove empty InitializePostBoot methods
|
|
|
|
2. **Standardize Patterns**:
|
|
- Consistent priority values across similar components
|
|
- Consistent ActiveLifecyclePhases usage
|
|
- Consistent logging patterns
|
|
|
|
3. **Update Comments**:
|
|
- Remove outdated references to old lifecycle
|
|
- Add references to ManagedBehaviour lifecycle
|
|
- Document priority decisions
|
|
|
|
4. **Code Review**:
|
|
- Review all migrated files
|
|
- Check for proper base.OnManagedAwake() calls
|
|
- Verify no breaking changes to public APIs
|
|
|
|
---
|
|
|
|
### STEP 35: Update Project Documentation
|
|
**Files to Update**:
|
|
|
|
1. `docs/bootstrap_readme.md`:
|
|
- Add section on ManagedBehaviour integration
|
|
- Update lifecycle flow diagrams
|
|
- Reference new lifecycle guide
|
|
|
|
2. `README.md`:
|
|
- Add link to ManagedBehaviour documentation
|
|
- Update project structure description
|
|
|
|
3. Create `docs/ManagedBehaviour_Migration_Log.md`:
|
|
- List of migrated components
|
|
- Migration dates
|
|
- Issues encountered and solutions
|
|
- Components intentionally not migrated
|
|
|
|
4. Update inline documentation:
|
|
- Update XML comments in migrated files
|
|
- Reference ManagedBehaviour lifecycle in comments
|
|
- Add examples where helpful
|
|
|
|
---
|
|
|
|
### STEP 36: Performance Profiling and Optimization
|
|
**Actions**:
|
|
|
|
1. **Baseline Measurements**:
|
|
- Measure current performance (before optimization)
|
|
- Profile Update broadcasts (100+ components)
|
|
- Memory allocation tracking
|
|
- GC pressure measurement
|
|
|
|
2. **Optimization Targets**:
|
|
- LifecycleManager.Update < 0.5ms (100 components)
|
|
- LifecycleManager.FixedUpdate < 0.3ms (100 components)
|
|
- Registration < 0.1ms per component
|
|
- Zero GC allocations during broadcasts
|
|
|
|
3. **Implementation**:
|
|
- Cache component counts
|
|
- Use for loops instead of foreach (no allocator)
|
|
- Avoid boxing in generic methods
|
|
- Pool event subscription objects
|
|
- Use struct enumerators
|
|
|
|
4. **Validation**:
|
|
- Re-profile after optimizations
|
|
- Compare against baseline
|
|
- Ensure optimizations don't break functionality
|
|
|
|
---
|
|
|
|
### STEP 37: Edge Case Handling
|
|
**Scenarios to Handle**:
|
|
|
|
1. **Editor Mode**:
|
|
- Handle domain reload
|
|
- Handle enter/exit play mode
|
|
- Handle script recompilation during play
|
|
|
|
2. **Build Scenarios**:
|
|
- Development builds (debug logging enabled)
|
|
- Release builds (debug code stripped)
|
|
- Platform-specific behavior
|
|
|
|
3. **Error Recovery**:
|
|
- Handle missing LifecycleManager gracefully
|
|
- Handle null component references
|
|
- Handle exceptions during lifecycle hooks (isolate failures)
|
|
|
|
4. **Threading**:
|
|
- Ensure thread safety for registration queue
|
|
- Handle registration from background threads (queue for main thread)
|
|
|
|
5. **Scene Edge Cases**:
|
|
- Handle multiple scenes loaded additively
|
|
- Handle rapid scene switches
|
|
- Handle scene unload during lifecycle broadcast
|
|
|
|
**Implementation**: Add defensive checks, logging, and fallbacks throughout LifecycleManager and ManagedBehaviour.
|
|
|
|
---
|
|
|
|
### STEP 38: Create Tutorial Scene
|
|
**File**: `Assets/Scenes/ManagedBehaviourTutorial.unity`
|
|
|
|
**Actions**:
|
|
1. Create tutorial scene demonstrating system
|
|
2. Include examples of:
|
|
- Simple ManagedBehaviour
|
|
- Priority ordering demonstration
|
|
- Lifecycle phase visualization
|
|
- Event subscription examples
|
|
- Save/load integration
|
|
- Pause system integration
|
|
3. Add UI showing lifecycle events in real-time
|
|
4. Include interactive elements to trigger phases
|
|
|
|
**File**: `Assets/Scripts/Tutorial/LifecycleEventLogger.cs`
|
|
|
|
**Actions**:
|
|
1. Create component that logs all lifecycle events to UI
|
|
2. Shows order of execution
|
|
3. Shows timing information
|
|
4. Color-codes by priority
|
|
|
|
---
|
|
|
|
### STEP 39: Community Documentation and Examples
|
|
**File**: `docs/ManagedBehaviour_FAQ.md`
|
|
|
|
**Content**:
|
|
1. Frequently asked questions
|
|
2. Common mistakes and solutions
|
|
3. When to use ManagedBehaviour vs MonoBehaviour
|
|
4. Performance considerations
|
|
5. Debugging tips
|
|
|
|
**File**: `docs/ManagedBehaviour_Recipes.md`
|
|
|
|
**Content**:
|
|
1. Common patterns and recipes
|
|
2. Singleton pattern with ManagedBehaviour
|
|
3. Scene-specific manager pattern
|
|
4. Persistent service pattern
|
|
5. Component with managed events pattern
|
|
6. Save/load participant pattern
|
|
|
|
---
|
|
|
|
### STEP 40: Final Review and Release Preparation
|
|
**Checklist**:
|
|
|
|
- [ ] All core systems migrated
|
|
- [ ] All tests passing
|
|
- [ ] Performance targets met
|
|
- [ ] Documentation complete
|
|
- [ ] Examples created and tested
|
|
- [ ] Editor tools working
|
|
- [ ] No console errors or warnings
|
|
- [ ] Code reviewed
|
|
- [ ] Backward compatibility maintained
|
|
- [ ] Migration guide complete
|
|
|
|
**Final Actions**:
|
|
1. Create release notes
|
|
2. Tag version in git
|
|
3. Update project version number
|
|
4. Create migration checklist for team
|
|
5. Schedule team training/walkthrough
|
|
6. Monitor for issues after deployment
|
|
|
|
---
|
|
|
|
## Appendix A: Priority Guidelines
|
|
|
|
### Recommended Priority Ranges
|
|
| Component Type | Priority Range | Reasoning |
|
|
|----------------|----------------|-----------|
|
|
| Core Infrastructure | 0-20 | LifecycleManager, CustomBoot integration |
|
|
| Core Managers | 10-30 | GameManager, SceneManager, SaveManager |
|
|
| Service Providers | 30-50 | Settings providers, factories |
|
|
| Gameplay Managers | 50-100 | PuzzleManager, CardSystem, Minigames |
|
|
| UI Controllers | 100-150 | Page controllers, loading screens |
|
|
| Scene Components | 150-200 | Level-specific logic |
|
|
| Gameplay Objects | 200-500 | Interactables, pickups, NPCs |
|
|
| Visual Effects | 500-1000 | Particles, animations, decorative |
|
|
|
|
### Priority Best Practices
|
|
- Use increments of 5 or 10 for easy insertion
|
|
- Document priority decisions in code comments
|
|
- Avoid priority 0 (reserved for system use)
|
|
- Group related components in same priority range
|
|
- Consider dependencies when assigning priorities
|
|
|
|
---
|
|
|
|
## Appendix B: Common Migration Patterns
|
|
|
|
### Pattern 1: Basic Singleton Manager
|
|
**Before**:
|
|
```csharp
|
|
public class MyManager : MonoBehaviour
|
|
{
|
|
private static MyManager _instance;
|
|
public static MyManager Instance => _instance;
|
|
|
|
void Awake()
|
|
{
|
|
_instance = this;
|
|
BootCompletionService.RegisterInitAction(InitializePostBoot);
|
|
}
|
|
|
|
private void InitializePostBoot()
|
|
{
|
|
// Setup
|
|
}
|
|
}
|
|
```
|
|
|
|
**After**:
|
|
```csharp
|
|
public class MyManager : ManagedBehaviour
|
|
{
|
|
private static MyManager _instance;
|
|
public static MyManager Instance => _instance;
|
|
|
|
protected override int BootCompletePriority => 50;
|
|
protected override LifecycleFlags ActiveLifecyclePhases =>
|
|
LifecycleFlags.ManagedAwake | LifecycleFlags.BootComplete;
|
|
|
|
protected override void OnManagedAwake()
|
|
{
|
|
_instance = this;
|
|
}
|
|
|
|
protected override void OnBootComplete()
|
|
{
|
|
// Setup
|
|
}
|
|
}
|
|
```
|
|
|
|
### Pattern 2: Component with Event Subscriptions
|
|
**Before**:
|
|
```csharp
|
|
public class MyComponent : MonoBehaviour
|
|
{
|
|
void Start()
|
|
{
|
|
SomeManager.Instance.OnEvent += HandleEvent;
|
|
}
|
|
|
|
void OnDestroy()
|
|
{
|
|
if (SomeManager.Instance != null)
|
|
SomeManager.Instance.OnEvent -= HandleEvent;
|
|
}
|
|
|
|
private void HandleEvent() { }
|
|
}
|
|
```
|
|
|
|
**After**:
|
|
```csharp
|
|
public class MyComponent : ManagedBehaviour
|
|
{
|
|
protected override LifecycleFlags ActiveLifecyclePhases =>
|
|
LifecycleFlags.BootComplete;
|
|
|
|
protected override void OnBootComplete()
|
|
{
|
|
RegisterManagedEvent(SomeManager.Instance,
|
|
m => m.OnEvent += HandleEvent);
|
|
}
|
|
|
|
private void HandleEvent() { }
|
|
// No OnDestroy needed - auto cleanup
|
|
}
|
|
```
|
|
|
|
### Pattern 3: Scene-Specific Component
|
|
**Before**:
|
|
```csharp
|
|
public class LevelComponent : MonoBehaviour
|
|
{
|
|
void Start()
|
|
{
|
|
SceneManagerService.Instance.SceneLoadCompleted += OnSceneLoaded;
|
|
Initialize();
|
|
}
|
|
|
|
void OnDestroy()
|
|
{
|
|
if (SceneManagerService.Instance != null)
|
|
SceneManagerService.Instance.SceneLoadCompleted -= OnSceneLoaded;
|
|
}
|
|
|
|
private void OnSceneLoaded(string sceneName) { }
|
|
private void Initialize() { }
|
|
}
|
|
```
|
|
|
|
**After**:
|
|
```csharp
|
|
public class LevelComponent : ManagedBehaviour
|
|
{
|
|
protected override LifecycleFlags ActiveLifecyclePhases =>
|
|
LifecycleFlags.SceneReady | LifecycleFlags.SceneUnloading;
|
|
|
|
protected override void OnSceneReady()
|
|
{
|
|
Initialize();
|
|
}
|
|
|
|
protected override void OnSceneUnloading()
|
|
{
|
|
Cleanup();
|
|
}
|
|
|
|
private void Initialize() { }
|
|
private void Cleanup() { }
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Appendix C: Troubleshooting Guide
|
|
|
|
### Issue: Lifecycle hook not being called
|
|
**Symptoms**: OnBootComplete or other hook not executing
|
|
**Solutions**:
|
|
1. Check ActiveLifecyclePhases includes the appropriate flag
|
|
2. Verify LifecycleManager exists in scene
|
|
3. Ensure base.OnManagedAwake() called if overriding
|
|
4. Check LifecycleManager debug logs
|
|
|
|
### Issue: Wrong execution order
|
|
**Symptoms**: Components initialize in unexpected order
|
|
**Solutions**:
|
|
1. Verify priority values (lower = earlier)
|
|
2. Check for priority conflicts (same priority = undefined order)
|
|
3. Add debug logging to verify execution order
|
|
4. Use LifecycleDebugWindow to visualize order
|
|
|
|
### Issue: Events not cleaning up
|
|
**Symptoms**: Memory leaks or errors after component destruction
|
|
**Solutions**:
|
|
1. Use RegisterManagedEvent instead of manual subscription
|
|
2. Verify OnDestroy calls base.OnDestroy()
|
|
3. Check event target is not null when registering
|
|
4. Review LifecycleManager event cleanup logs
|
|
|
|
### Issue: Performance degradation
|
|
**Symptoms**: Frame time increases with many ManagedBehaviours
|
|
**Solutions**:
|
|
1. Only override lifecycle hooks you need
|
|
2. Don't use OnManagedUpdate if Unity Update suffices
|
|
3. Profile with Unity Profiler to find bottleneck
|
|
4. Check for excessive logging in release builds
|
|
5. Optimize ActiveLifecyclePhases (don't include unused phases)
|
|
|
|
---
|
|
|
|
## Appendix D: Integration Checklist
|
|
|
|
Use this checklist when migrating each component:
|
|
|
|
**Pre-Migration**:
|
|
- [ ] Component has InitializePostBoot or complex initialization
|
|
- [ ] Component subscribes to manager events
|
|
- [ ] Component needs deterministic initialization order
|
|
- [ ] Component is ISaveParticipant or IPausable
|
|
|
|
**Migration**:
|
|
- [ ] Changed base class to ManagedBehaviour
|
|
- [ ] Set appropriate priority values
|
|
- [ ] Added ActiveLifecyclePhases flags
|
|
- [ ] Moved Awake logic to OnManagedAwake
|
|
- [ ] Moved InitializePostBoot to OnBootComplete
|
|
- [ ] Converted event subscriptions to RegisterManagedEvent
|
|
- [ ] Removed manual BootCompletionService registration
|
|
- [ ] Set AutoRegisterSaveParticipant if ISaveParticipant
|
|
- [ ] Set AutoRegisterPausable if IPausable
|
|
- [ ] Updated XML documentation
|
|
|
|
**Post-Migration**:
|
|
- [ ] No compiler errors
|
|
- [ ] Component still functions correctly
|
|
- [ ] Lifecycle hooks called at appropriate times
|
|
- [ ] Priority ordering correct relative to dependencies
|
|
- [ ] No memory leaks (events cleaned up)
|
|
- [ ] Performance acceptable
|
|
- [ ] Code reviewed
|
|
- [ ] Tests updated/added
|
|
|
|
---
|
|
|
|
## Appendix E: Future Enhancements
|
|
|
|
Potential future additions to the system:
|
|
|
|
1. **Async Lifecycle Hooks**: Support for async/await in lifecycle methods
|
|
2. **Conditional Phases**: Enable/disable phases at runtime
|
|
3. **Lifecycle Groups**: Group related components for batch operations
|
|
4. **Visual Editor**: Node-based lifecycle flow visualization
|
|
5. **Hot Reload Support**: Better handling of domain reload in editor
|
|
6. **Multi-threading**: Parallel execution of independent components
|
|
7. **Lifecycle Templates**: Pre-configured setups for common patterns
|
|
8. **Analytics Integration**: Track lifecycle performance in production
|
|
9. **Memory Pooling**: Pool ManagedBehaviour instances for performance
|
|
10. **Dependency Injection**: Auto-resolve dependencies in OnManagedAwake
|
|
|
|
---
|
|
|
|
## Document Metadata
|
|
|
|
**Version**: 1.0
|
|
**Last Updated**: October 30, 2025
|
|
**Author**: AI Assistant
|
|
**Status**: Ready for Implementation
|
|
|
|
**Implementation Estimate**: 40-60 hours across 2-3 weeks
|
|
**Risk Level**: Medium (significant refactoring, but incremental approach reduces risk)
|
|
**Prerequisites**: Unity 2021.3+, C# 8.0+, existing bootstrap system
|
|
|
|
**Next Steps**:
|
|
1. Review this document thoroughly
|
|
2. Get team approval
|
|
3. Begin with STEP 1
|
|
4. Progress sequentially through steps
|
|
5. Test thoroughly at each phase
|
|
6. Document any deviations or issues
|
|
|