# ManagedBehaviour System - Technical Reference
**Version:** 2.0
**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`.
Click to see more details
##### `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).
#### Configuration Properties
Virtual properties that control automatic behaviors like pause registration and save system participation.
Click to see more details
##### `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.
### Private Lifecycle Methods
Click to see more details
##### `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.
---
## 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.
Click to see more details
##### `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 BroadcastSceneSaveRequested()
```
Broadcasts `OnSceneSaveRequested()` to all components with `AutoRegisterForSave == true`. Returns dictionary of SaveId → serialized data.
##### `BroadcastSceneRestoreRequested(Dictionary saveData)`
```csharp
public void BroadcastSceneRestoreRequested(Dictionary saveData)
```
Distributes save data to components by matching `SaveId`, then broadcasts `OnSceneRestoreCompleted()`.
##### `BroadcastGlobalSaveRequested()`
```csharp
public Dictionary BroadcastGlobalSaveRequested()
```
Broadcasts `OnGlobalSaveRequested()` to all components with `AutoRegisterForSave == true`. Returns dictionary of SaveId → serialized data.
##### `BroadcastGlobalRestoreRequested(Dictionary saveData)`
```csharp
public void BroadcastGlobalRestoreRequested(Dictionary 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
}
```
---