# ManagedBehaviour System - Architecture Overview

**Version:** 2.0 <br>
**Updated:** 11.11.2025


---

## What is the ManagedBehaviour System?

Lifecycle orchestration framework that provides guaranteed execution order and deterministic lifecycle management for Unity components.

### Problems Solved

We've had quite a few things shoe-stringed together in various ways and dependant on references to each other.
Due to undefined initialization order - null references during access to yet uninitialized resources was becoming a problem.

### What You Get

- **Guaranteed Initialization Order** - Managers ready before components that depend on them
- **Deterministic Lifecycle Hooks** - Predictable callbacks at key moments
- **Automatic Registration** - No boilerplate for wiring up systems
- **Scene Lifecycle Events** - Built-in hooks for scene load/unload
- **Save/Load Coordination** - Centralized collection of save data
- **Bootstrap Integration** - Components know when bootstrap completes  

---

## Architecture Principles

### 1. Centralized Orchestration

Single `LifecycleManager` singleton coordinates all lifecycle events. Components auto-register and receive callbacks at appropriate times.

### 2. Sealed Framework Methods

`Awake()` and `OnDestroy()` are sealed. Use `OnManagedAwake()` and `OnManagedDestroy()` instead. Prevents forgetting to call `base.Awake()`.

### 3. Two-Phase Initialization

- **Early (`OnManagedAwake()`)**: During Unity's Awake, before bootstrap. Use for singleton setup.
- **Late (`OnManagedStart()`)**: After bootstrap completes. All managers guaranteed ready.

### 4. Registration Order Execution

Execution follows Unity's natural Awake order. No priority numbers to manage.

### 5. Automatic Cleanup

Framework handles unregistration automatically. Override `OnManagedDestroy()` only if you need custom cleanup.

---

## Lifecycle Flow Diagrams

### Boot Sequence

![Boot Sequence](../media/boot_sequence.png)

### Scene Transition Flow

![Scene Transition Flow](../media/Scene_transition_flow.png)

### Component Lifecycle (Individual Component)

![Component Lifecycle](../media/component_lifecycle.png)

---

## Class Diagram

![Class Diagram](../media/class_diagram.png)

---
## Key Guarantees

### Guaranteed

1. **Bootstrap Completion** - `OnManagedStart()` always fires after bootstrap completes
2. **Manager Availability** - All manager singletons exist when `OnManagedStart()` is called
3. **Scene Lifecycle** - `OnSceneReady()` fires after scene load, `OnSceneUnloading()` before unload
4. **Automatic Registration** - Can't forget to register (Awake is sealed)
5. **Automatic Cleanup** - Can't forget to unregister (OnDestroy is sealed)
6. **Save/Load Coordination** - All save participants called in one pass

### Not Guaranteed

1. **Initialization Order Between Components** - `OnManagedAwake()` follows Unity's unpredictable Awake order
2. **Thread Safety** - All methods must run on main thread
3. **Performance** - Broadcasting to 1000+ components may have overhead
4. **SaveId Uniqueness** - Developer responsible for unique SaveIds