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.5: 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. 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 (haptics)	1	HapticsController (PlayerController)
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	141

---

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.