# 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.5: RENDER PIPELINE                                    │
│  Quality presets, Lumen/Baked, upscaling, platform profiles     │
├────────────────────────────────────────────────────────────────┤
│  LAYER 7: HAPTICS                                              │
│  Controller vibration, DualSense triggers, heartbeat pulse      │
├────────────────────────────────────────────────────────────────┤
│  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 `DA_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. GameplayTag-Driven Haptics
All controller vibration routes through `BPC_HapticsController` on the Player Controller. Gameplay systems trigger haptics by GameplayTag (e.g., `Haptic.Damage.Heavy`) — never calling raw `Play Force Feedback` nodes. The component detects platform (Xbox rumble vs PS5 DualSense adaptive triggers), respects accessibility toggles, and manages effect priority. Heartbeat pulse is driven by `BPC_StateManager.GetCurrentHeartRate()`.

### 9. Per-Platform Render Pipeline
All render quality decisions route through `BPC_RenderPipelineManager`. The system reads `DA_RenderPipelineProfile` Data Assets to determine Lumen vs Baked Lightmass, Virtual Shadow Maps vs Cascaded Shadow Maps, Nanite vs traditional LODs, and the appropriate upscaler (DLSS/FSR/TSR/PSSR) for the detected platform and selected quality preset. Destructive pipeline changes (GI method, shadow method) are queued and applied on level load. The Planar Capture system adjusts its quality budget based on the active pipeline.

### 10. 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 |
| `BPC_` Components (settings) | 2 | HapticsController, RenderPipelineManager |
| `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** | **142** | |

---

## 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.*
