8bc731e5ae
- Updated Master Blueprint Index to include Multiplayer Networking support. - Added detailed Multiplayer Networking sections across all developer documentation (01-11). - Introduced authority maps, key patterns, and RPC guidelines for each system. - Established a comprehensive multiplayer networking architecture document outlining core principles, replication strategies, and anti-cheat considerations. - Enhanced UI documentation to clarify local-only behavior and binding to replicated dispatchers. - Implemented client prediction strategies and RPC naming conventions for consistency across the framework.
198 lines
12 KiB
Markdown
198 lines
12 KiB
Markdown
# 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.*
|