Last life cycle refactor updates + add comprehensive documentation (#57)
Co-authored-by: Michal Pikulski <michal.a.pikulski@gmail.com> Reviewed-on: #57
This commit is contained in:
377
docs/managed_behavior/technical_reference.md
Normal file
377
docs/managed_behavior/technical_reference.md
Normal file
@@ -0,0 +1,377 @@
|
||||
# ManagedBehaviour System - Technical Reference
|
||||
|
||||
**Version:** 2.0 <br>
|
||||
**Updated:** 11.11.2025
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The ManagedBehaviour system provides a deterministic, ordered lifecycle management framework for Unity MonoBehaviours. This document provides complete technical documentation of all classes, methods, and APIs.
|
||||
|
||||
---
|
||||
|
||||
## Core Classes
|
||||
|
||||
### ManagedBehaviour (Abstract Base Class)
|
||||
|
||||
**Namespace:** `Core.Lifecycle`
|
||||
**Inherits:** `MonoBehaviour`
|
||||
**Location:** `Assets/Scripts/Core/Lifecycle/ManagedBehaviour.cs` → [View Source](../../Assets/Scripts/Core/Lifecycle/ManagedBehaviour.cs)
|
||||
|
||||
Abstract base class that all managed components must inherit from. Provides automatic registration with LifecycleManager and ordered lifecycle callbacks.
|
||||
|
||||
#### Lifecycle Hook Methods
|
||||
|
||||
Override these `internal virtual` methods to customize component behavior at different lifecycle stages. Called automatically by `LifecycleManager`.
|
||||
|
||||
<details>
|
||||
<summary>Click to see more details</summary>
|
||||
|
||||
##### `OnManagedAwake()`
|
||||
```csharp
|
||||
internal virtual void OnManagedAwake()
|
||||
```
|
||||
**Called:** During registration (within Unity's Awake phase)
|
||||
**Execution Order:** Natural Unity script execution order (not guaranteed between components)
|
||||
**Use For:**
|
||||
- Setting singleton instances (`_instance = this`)
|
||||
- Early GetComponent calls
|
||||
- One-time initialization that doesn't depend on other systems
|
||||
|
||||
**Timing Guarantees:**
|
||||
- ✅ GameObject and component exist
|
||||
- ✅ Scene is loaded
|
||||
- ❌ Other components may not be initialized yet
|
||||
- ❌ Bootstrap may not be complete
|
||||
|
||||
##### `OnManagedStart()`
|
||||
```csharp
|
||||
internal virtual void OnManagedStart()
|
||||
```
|
||||
**Called:** After bootstrap completes (for boot components) or immediately after registration (for late-registered components)
|
||||
**Execution Order:** Registration order
|
||||
**Use For:**
|
||||
- Initialization that depends on other managers
|
||||
- Accessing singleton instances safely
|
||||
- Setting up cross-system dependencies
|
||||
|
||||
**Timing Guarantees:**
|
||||
- ✅ All managers are initialized
|
||||
- ✅ Bootstrap resources are available
|
||||
- ✅ Safe to access `GameManager.Instance`, `AudioManager.Instance`, etc.
|
||||
|
||||
##### `OnSceneUnloading()`
|
||||
```csharp
|
||||
internal virtual void OnSceneUnloading()
|
||||
```
|
||||
**Called:** Before scene unload
|
||||
**Execution Order:** Registration order
|
||||
**Use For:**
|
||||
- Scene-specific cleanup
|
||||
- Saving temporary scene state
|
||||
|
||||
**Timing Guarantees:**
|
||||
- ✅ Scene is still loaded
|
||||
- ✅ Other components in scene still exist
|
||||
|
||||
##### `OnSceneReady()`
|
||||
```csharp
|
||||
internal virtual void OnSceneReady()
|
||||
```
|
||||
**Called:** After scene load completes
|
||||
**Execution Order:** Registration order
|
||||
**Use For:**
|
||||
- Scene-specific initialization
|
||||
- Finding scene objects
|
||||
- Setting up scene-specific state
|
||||
|
||||
**Timing Guarantees:**
|
||||
- ✅ All scene GameObjects are loaded
|
||||
- ✅ Batched components have received `OnManagedStart()`
|
||||
|
||||
##### `OnSceneSaveRequested()`
|
||||
```csharp
|
||||
internal virtual string OnSceneSaveRequested()
|
||||
```
|
||||
**Called:** Before scene unload during scene transitions
|
||||
**Returns:** Serialized scene-specific data (JSON string), or `null` if nothing to save
|
||||
**Use For:**
|
||||
- Level progress
|
||||
- Object positions
|
||||
- Puzzle states
|
||||
- Temporary scene data
|
||||
|
||||
**⚠️ Important:** Must return synchronously.
|
||||
|
||||
##### `OnSceneRestoreRequested(string serializedData)`
|
||||
```csharp
|
||||
internal virtual void OnSceneRestoreRequested(string serializedData)
|
||||
```
|
||||
**Called:** After scene load, during `OnSceneReady` phase
|
||||
**Parameters:**
|
||||
- `serializedData` - Previously saved data from `OnSceneSaveRequested()`
|
||||
|
||||
**Use For:**
|
||||
- Restoring level progress
|
||||
- Setting object positions
|
||||
- Restoring puzzle states
|
||||
|
||||
**⚠️ Important:** Must execute synchronously. Do not use coroutines or async/await.
|
||||
|
||||
##### `OnSceneRestoreCompleted()`
|
||||
```csharp
|
||||
internal virtual void OnSceneRestoreCompleted()
|
||||
```
|
||||
**Called:** After all `OnSceneRestoreRequested()` calls complete
|
||||
**Timing:** Always called after scene load, whether save data exists or not
|
||||
**Use For:**
|
||||
- Post-restore initialization
|
||||
- First-time initialization (when no save data exists)
|
||||
- Triggering events after state is restored
|
||||
|
||||
**Common Pattern:**
|
||||
```csharp
|
||||
internal override void OnSceneRestoreCompleted()
|
||||
{
|
||||
if (!_hasPlayed) // Check if this is first time
|
||||
{
|
||||
PlayIntroAudio();
|
||||
_hasPlayed = true;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
##### `OnGlobalSaveRequested()`
|
||||
```csharp
|
||||
internal virtual string OnGlobalSaveRequested()
|
||||
```
|
||||
**Called:** Once before save file is written to disk
|
||||
**Returns:** Serialized global persistent data (JSON string), or `null`
|
||||
**Use For:**
|
||||
- Player inventory
|
||||
- Unlocked features
|
||||
- Card collections
|
||||
- Persistent progression
|
||||
|
||||
**Timing:** Called once per game save (not per scene transition)
|
||||
|
||||
##### `OnGlobalRestoreRequested(string serializedData)`
|
||||
```csharp
|
||||
internal virtual void OnGlobalRestoreRequested(string serializedData)
|
||||
```
|
||||
**Called:** Once on game boot after save file is read
|
||||
**Parameters:**
|
||||
- `serializedData` - Previously saved data from `OnGlobalSaveRequested()`
|
||||
|
||||
**Use For:**
|
||||
- Restoring player inventory
|
||||
- Restoring unlocked features
|
||||
- Restoring persistent progression
|
||||
|
||||
**Timing:** Called once on boot, not during scene transitions
|
||||
|
||||
##### `OnGlobalLoadCompleted()`
|
||||
```csharp
|
||||
internal virtual void OnGlobalLoadCompleted()
|
||||
```
|
||||
**Called:** Once on game boot after all global restore operations complete
|
||||
**Use For:**
|
||||
- Triggering UI updates after load
|
||||
- Broadcasting load events
|
||||
- Post-load initialization
|
||||
|
||||
##### `OnGlobalSaveStarted()`
|
||||
```csharp
|
||||
internal virtual void OnGlobalSaveStarted()
|
||||
```
|
||||
**Called:** Once before save file is written
|
||||
**Use For:**
|
||||
- Final validation before save
|
||||
- Cleanup operations before save
|
||||
|
||||
##### `OnManagedDestroy()`
|
||||
```csharp
|
||||
internal virtual void OnManagedDestroy()
|
||||
```
|
||||
**Called:** During `OnDestroy`, before unregistration
|
||||
**Execution Order:** Registration order
|
||||
**Use For:**
|
||||
- Unsubscribing from events
|
||||
- Releasing resources
|
||||
- Custom cleanup logic
|
||||
|
||||
**Note:** Most cleanup is automatic (auto-registrations are handled by framework).
|
||||
</details>
|
||||
|
||||
#### Configuration Properties
|
||||
|
||||
Virtual properties that control automatic behaviors like pause registration and save system participation.
|
||||
|
||||
<details>
|
||||
<summary>Click to see more details</summary>
|
||||
|
||||
##### `AutoRegisterPausable`
|
||||
```csharp
|
||||
public virtual bool AutoRegisterPausable => false;
|
||||
```
|
||||
**Type:** `bool`
|
||||
**Default:** `false`
|
||||
**Description:** If true and component implements `IPausable`, automatically registers with `GameManager.Instance` during initialization. Automatic unregistration occurs on destruction.
|
||||
|
||||
##### `AutoRegisterForSave`
|
||||
```csharp
|
||||
public virtual bool AutoRegisterForSave => false;
|
||||
```
|
||||
**Type:** `bool`
|
||||
**Default:** `false`
|
||||
**Description:** If true, component participates in the save/load system. Should override `OnSceneSaveRequested()` and `OnSceneRestoreRequested()` or global equivalents.
|
||||
|
||||
##### `SaveId`
|
||||
```csharp
|
||||
public virtual string SaveId { get; }
|
||||
```
|
||||
**Type:** `string`
|
||||
**Default:** `"{SceneName}/{GameObjectName}/{ComponentType}"`
|
||||
**Description:** Unique identifier for this component in the save system. Cached on first access for performance. Override for singletons (e.g., `"PlayerController"`) or custom IDs.
|
||||
|
||||
**⚠️ Warning:** GameObject name changes at runtime will NOT update the cached SaveId.
|
||||
</details>
|
||||
|
||||
### Private Lifecycle Methods
|
||||
<details>
|
||||
<summary>Click to see more details</summary>
|
||||
|
||||
##### `Awake()`
|
||||
```csharp
|
||||
private void Awake()
|
||||
```
|
||||
**Visibility:** `private` (sealed, cannot be overridden)
|
||||
**Called By:** Unity
|
||||
**Description:** Automatically registers component with `LifecycleManager`. Calls `OnManagedAwake()` during registration.
|
||||
|
||||
**⚠️ Important:** This method is sealed. Use `OnManagedAwake()` for early initialization.
|
||||
|
||||
##### `OnDestroy()`
|
||||
```csharp
|
||||
private void OnDestroy()
|
||||
```
|
||||
**Visibility:** `private` (sealed, cannot be overridden)
|
||||
**Called By:** Unity
|
||||
**Description:** Calls `OnManagedDestroy()`, unregisters from `LifecycleManager`, and handles auto-unregistrations.
|
||||
|
||||
**⚠️ Important:** This method is sealed. Use `OnManagedDestroy()` for custom cleanup.
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## LifecycleManager (Singleton Orchestrator)
|
||||
|
||||
**Namespace:** `Core.Lifecycle`
|
||||
**Inherits:** `MonoBehaviour`
|
||||
**Location:** `Assets/Scripts/Core/Lifecycle/LifecycleManager.cs` → [View Source](../../Assets/Scripts/Core/Lifecycle/LifecycleManager.cs)
|
||||
|
||||
Central orchestrator that manages all `ManagedBehaviour` components and broadcasts lifecycle events.
|
||||
|
||||
### Static Properties
|
||||
|
||||
##### `Instance`
|
||||
Singleton instance. Created automatically by `CustomBoot` before bootstrap begins.
|
||||
|
||||
### Public Methods
|
||||
|
||||
Core methods for registration, lifecycle broadcasting, and save/restore operations. Most are called automatically by the framework.
|
||||
|
||||
<details>
|
||||
<summary>Click to see more details</summary>
|
||||
|
||||
##### `Register(ManagedBehaviour component)`
|
||||
```csharp
|
||||
public void Register(ManagedBehaviour component)
|
||||
```
|
||||
Registers a component with the lifecycle system. **Called automatically from `ManagedBehaviour.Awake()`.**
|
||||
|
||||
##### `Unregister(ManagedBehaviour component)`
|
||||
```csharp
|
||||
public void Unregister(ManagedBehaviour component)
|
||||
```
|
||||
Unregisters a component. **Called automatically from `ManagedBehaviour.OnDestroy()`.**
|
||||
|
||||
##### `OnBootCompletionTriggered()`
|
||||
```csharp
|
||||
public void OnBootCompletionTriggered()
|
||||
```
|
||||
Called by `CustomBoot` after bootstrap completes. Broadcasts `OnManagedStart()` to all registered components.
|
||||
|
||||
##### `BeginSceneLoad(string sceneName)`
|
||||
```csharp
|
||||
public void BeginSceneLoad(string sceneName)
|
||||
```
|
||||
Activates scene loading batching mode. Called by `SceneManagerService` when loading a scene.
|
||||
|
||||
##### `BroadcastSceneReady(string sceneName)`
|
||||
```csharp
|
||||
public void BroadcastSceneReady(string sceneName)
|
||||
```
|
||||
Processes batched components and broadcasts `OnSceneReady()` to all components in the scene. Called by `SceneManagerService` after scene load.
|
||||
|
||||
##### `BroadcastSceneUnloading(string sceneName)`
|
||||
```csharp
|
||||
public void BroadcastSceneUnloading(string sceneName)
|
||||
```
|
||||
Broadcasts `OnSceneUnloading()` to all components in the specified scene. Called by `SceneManagerService` before scene unload.
|
||||
|
||||
##### `BroadcastSceneSaveRequested()`
|
||||
```csharp
|
||||
public Dictionary<string, string> BroadcastSceneSaveRequested()
|
||||
```
|
||||
Broadcasts `OnSceneSaveRequested()` to all components with `AutoRegisterForSave == true`. Returns dictionary of SaveId → serialized data.
|
||||
|
||||
##### `BroadcastSceneRestoreRequested(Dictionary<string, string> saveData)`
|
||||
```csharp
|
||||
public void BroadcastSceneRestoreRequested(Dictionary<string, string> saveData)
|
||||
```
|
||||
Distributes save data to components by matching `SaveId`, then broadcasts `OnSceneRestoreCompleted()`.
|
||||
|
||||
##### `BroadcastGlobalSaveRequested()`
|
||||
```csharp
|
||||
public Dictionary<string, string> BroadcastGlobalSaveRequested()
|
||||
```
|
||||
Broadcasts `OnGlobalSaveRequested()` to all components with `AutoRegisterForSave == true`. Returns dictionary of SaveId → serialized data.
|
||||
|
||||
##### `BroadcastGlobalRestoreRequested(Dictionary<string, string> saveData)`
|
||||
```csharp
|
||||
public void BroadcastGlobalRestoreRequested(Dictionary<string, string> saveData)
|
||||
```
|
||||
Distributes save data to components by matching `SaveId`, then broadcasts `OnGlobalLoadCompleted()`.
|
||||
|
||||
##### `BroadcastGlobalSaveStarted()`
|
||||
```csharp
|
||||
public void BroadcastGlobalSaveStarted()
|
||||
```
|
||||
Broadcasts `OnGlobalSaveStarted()` to all components with `AutoRegisterForSave == true`.
|
||||
|
||||
## LifecyclePhase (Enum)
|
||||
|
||||
**Namespace:** `Core.Lifecycle`
|
||||
**Location:** `Assets/Scripts/Core/Lifecycle/LifecycleEnums.cs` → [View Source](../../Assets/Scripts/Core/Lifecycle/LifecycleEnums.cs)
|
||||
|
||||
Defines the different lifecycle phases for documentation and tooling purposes.
|
||||
|
||||
```csharp
|
||||
public enum LifecyclePhase
|
||||
{
|
||||
ManagedAwake, // During registration (Awake)
|
||||
ManagedStart, // After bootstrap or late registration
|
||||
SceneUnloading, // Before scene unload
|
||||
SceneReady, // After scene load
|
||||
SaveRequested, // Before scene unload (save)
|
||||
RestoreRequested, // After scene load (restore)
|
||||
ManagedDestroy // During OnDestroy
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user