AppleHillsProduction/docs/managed_behavior/architecture_overview.md

ManagedBehaviour System - Architecture Overview

Version: 2.0
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