# Architecture Overview — UE5 Modular Game Framework **Purpose:** A high-level walkthrough of the entire framework architecture — the big picture before diving into individual system docs. Read this first if you're new to the framework. --- ## The Core Idea This framework provides a complete, modular, Blueprint-only game architecture for Unreal Engine 5.5-5.7 built on 14 architectural principles. Every system is a self-contained Blueprint Component or Actor that communicates through interfaces, event dispatchers, and GameplayTags — never through direct hard references unless they're tightly coupled by design. ## The Four Communication Methods ``` TIGHTLY COUPLED │ LOOSELY COUPLED (use sparingly) │ (preferred) │ Direct Reference │ Interface Calls GM → GS_CoreGameState │ I_Interactable, I_Damageable Player → Components │ Caller knows interface, not class │ │ Event Dispatchers │ OnHealthChanged, OnDeath │ Fire-and-forget, one-to-many │ │ GameplayTag + Subsystem Lookup │ GI_GameFramework.GetSubsystem(Tag) │ Fully decoupled, globally accessible ``` --- ## System Layers (Bottom-Up) ``` ┌────────────────────────────────────────────────────────────────┐ │ LAYER 8: POLISH & META │ │ Tutorials, Loading, Credits, Analytics, Achievements │ ├────────────────────────────────────────────────────────────────┤ │ LAYER 7: ADAPTIVE │ │ Difficulty, Atmosphere, Pacing, Scares, Audio (MetaSounds) │ ├────────────────────────────────────────────────────────────────┤ │ LAYER 6: AI │ │ Enemy Behavior, Perception, Memory, Patrol, Combat │ ├────────────────────────────────────────────────────────────────┤ │ LAYER 5: COMBAT │ │ Weapons, Damage, Ammo, Recoil, Reload, Melee, Defense │ ├────────────────────────────────────────────────────────────────┤ │ LAYER 4: NARRATIVE & UI │ │ Dialogue, Objectives, Cutscenes, HUD, Menus, Inventory UI │ ├────────────────────────────────────────────────────────────────┤ │ LAYER 3: INTERACTION & INVENTORY │ │ Doors, Puzzles, Pickups, Inventory, Containers, Equipment │ ├────────────────────────────────────────────────────────────────┤ │ LAYER 2: PLAYER SIMULATION │ │ Health, Stamina, Stress, Movement, Hiding, Camera, Body │ ├────────────────────────────────────────────────────────────────┤ │ LAYER 1: FOUNDATION │ │ GameInstance, GameMode, GameState, Interfaces, Tags, Items │ └────────────────────────────────────────────────────────────────┘ ``` Higher layers depend on lower layers. Foundation has no dependencies. Polish/Meta can observe everything. --- ## Key Architectural Decisions ### 1. Central State Authority (BPC_StateManager) Instead of System A checking "is System B in state X?", all systems query `BPC_StateManager.IsActionPermitted(Tag)`. The StateManager maintains 42 exclusive action states and 18 overlay states. Gating rules are in `DA_StateGatingTable` — designers modify rules without touching Blueprints. ### 2. Interface-First Communication All cross-system communication uses Blueprint Interfaces (`I_Interactable`, `I_Damageable`, `I_Persistable`, etc.). The caller queries "does this actor implement this interface?" and calls the interface function — never casts to a concrete class. ### 3. Data-Driven Everything No hardcoded values. Every configuration lives in Data Assets (`DA_ItemData`, `DA_EquipmentConfig`, `DA_AtmosphereProfile`). Designers edit Data Assets in the Content Browser; Blueprints read from them at runtime. ### 4. UI Reads, Never Writes Widgets display data from gameplay systems but never own game state. They bind to event dispatchers (`OnHealthChanged` → update health bar) and call functions (`UseItem()`) — but never store authoritative data. ### 5. GameplayTags for State, Not Booleans No `bIsDead`, `bIsHidden`, `bIsInCombat` booleans. Everything is a GameplayTag compared via `HasTag()` / `MatchesTag()`. Tags are documented in `GI_GameTagRegistry`. ### 6. Single Audio Entry Point (SS_AudioManager) Never call `UGameplayStatics::PlaySound*` directly. All audio routes through `SS_AudioManager` which manages 4 MetaSound buses (SFX, Ambience, Music, Dialogue → Master Bus). Room acoustics switch automatically via `BP_RoomAudioZone` triggers. ### 7. Enhanced Input Manager All input goes through `SS_EnhancedInputManager`. Context switching uses priority-based stack. Key rebinding is platform-aware via `DA_InputMappingProfile`. ### 8. Force Stack for State Overrides Death, cutscenes, void space push state onto a stack. `RestorePreviousState()` pops back — the player returns to exactly their previous state after a forced interruption. --- ## Data Flow: A Typical Interaction ``` Player looks at a locked door → BPC_InteractionDetector sphere trace hits BP_DoorActor → Detector checks: I_Interactable? ✓ Priority? High ✓ Distance? 150cm ✓ → Dispatches OnTargetFound → WBP_InteractionPromptDisplay shows "Locked Door [E]" Player presses E → Detector calls I_Interactable.ExecuteInteraction on door → BP_DoorActor.Interact_Implementation: → CurrentState = Locked → TryUnlockWithItem() queries BPC_InventorySystem.HasItem(RequiredKeyTag) → Player has key? Yes → RemoveItemOnUse = true → consume key → UnlockDoor() → Play unlock sound via SS_AudioManager → TryOpen() → Set state Opening → Play open animation → OnOpenComplete → Set state Open → Broadcast OnDoorOpened → AI Perception hears door sound → BPC_AlertSystem becomes Suspicious → BPC_PersistentWorldStateRecorder logs door state change for save → WBP_NotificationToast shows "Door Unlocked" ``` All this happens through interfaces, dispatchers, and the audio subsystem — no system directly references another's concrete class. --- ## Build-Order Rationale The 16 build phases follow dependency order: 1. **Foundation + Input** (01-core, 15-input) — zero dependencies, everything else builds on these 2. **Player Core** (02-player) — depends on foundation 3. **Interaction** (03-interaction) — depends on player + foundation 4. **Inventory** (04-inventory) — depends on interaction + player 5. **Save/Load** (05-saveload) — depends on inventory + player + interaction 6. **UI** (06-ui) — depends on everything below 7. **Narrative** (07-narrative) — depends on UI + save 8. **Weapons** (08-weapons) — depends on inventory + player + UI 9. **AI** (09-ai) — depends on player (for detection) + weapons 10. **Adaptive** (10-adaptive) — reads everything 11. **Data Assets** (14-data-assets) — referenced by all, created when content is stable 12-16. **Meta, Settings, Polish, State, Audio** — layered on top --- ## System Count by Type | Type | Count | Examples | |------|-------|----------| | `BPC_` Blueprint Components | 80 | HealthSystem, InventorySystem, AIPerception | | `BP_` Blueprint Actors | 11 | DoorActor, WeaponBase, EnemyBase | | `WBP_` Widget Blueprints | 14 | HUDController, InventoryMenu, MainMenu | | `DA_` Data Assets | 18 | ItemData, EquipmentConfig, AtmosphereProfile | | `SS_` GameInstance Subsystems | 7 | SaveManager, UIManager, AudioManager | | `GI_` Game Instances | 2 | GameFramework, GameTagRegistry | | `I_` Interfaces | 3 | InterfaceLibrary, HidingSpot, Persistable | | `GM_` GameMode, `GS_` GameState | 2 | CoreGameMode, CoreGameState | | `FL_` Function Library | 1 | GameUtilities | | `AI_` Controller, `BB_` Blackboard | 2 | BaseAgentController, AgentBoard | | **TOTAL** | **140** | | --- ## Multiplayer Networking Architecture The framework is built server-authoritative from the ground up. See [`docs/architecture/multiplayer-networking.md`](../architecture/multiplayer-networking.md) for the full specification. ### How Networking Fits the Layers ``` ┌────────────────────────────────────────────────────────────────┐ │ LOCAL-ONLY LAYER (never replicated) │ │ WBP_* Widgets, Camera, Embodiment, Debug, Analytics, Tutorials │ ├────────────────────────────────────────────────────────────────┤ │ REPLICATED STATE LAYER (server-authoritative) │ │ GS_CoreGameState (chapter, objectives, encounter, time) │ │ Player Components (health, stamina, stress, movement, hide) │ │ World Actors (doors, containers, pickups, puzzles) │ │ Inventory (slots, weight, equipment) │ │ Narrative (flags, dialogue state, objectives) │ │ AI (position, alert state, health — behavior trees on server) │ │ Adaptive (atmosphere tier, tension, difficulty params) │ ├────────────────────────────────────────────────────────────────┤ │ CLIENT PREDICTION LAYER (cosmetic, corrected by server) │ │ Weapon fire FX, muzzle flash, recoil, hit markers │ │ Stamina bar, health bar (predicted; RepNotify corrects) │ │ Door animations (predicted; OnRep confirms) │ ├────────────────────────────────────────────────────────────────┤ │ SERVER-ONLY LAYER │ │ AI Behavior Trees, Damage Calculation, Loot Generation │ │ Save/Load coordination, State Gating validation │ └────────────────────────────────────────────────────────────────┘ ``` ### Key Multiplayer Principles 1. **HasAuthority() gate** on every mutator function 2. **Server_ RPC** for client→server requests 3. **RepNotify** fires same dispatchers as SP code — UI needs zero changes 4. **Client prediction** for responsiveness; server correction for correctness 5. **AI runs on server** only — replicated to clients via Actor replication 6. **UI is local per-client** — binds to replicated dispatchers --- *Architecture Overview v1.0 — Start here before reading category-specific developer docs.*