UE5-Modular-Game-Framework/docs/developer/architecture-overview.md

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