fee12b115f
- Updated references from GI_GameTagRegistry to DA_GameTagRegistry in architecture overview and implementation patterns documentation. - Added new Blueprint specification for GI_StarterGameInstance, detailing its purpose, configuration, and integration pattern. - Introduced DA_GameTagRegistry Blueprint specification, centralizing GameplayTag management and providing functions for tag validation and logging. - Created documentation for the Starter GameInstance, outlining its role in the project setup and how other systems can integrate with it.
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 `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. 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.*
|