AppleHillsProduction/docs/managed_behavior/technical_reference.md

# 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
}
```

---