94 lines
3.0 KiB
Markdown
94 lines
3.0 KiB
Markdown
|
# 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
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
### Scene Transition Flow
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
### Component Lifecycle (Individual Component)
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Class Diagram
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
---
|
||
|
|
## 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
|
||
|
|
|
||
|
|
|