Add developer documentation for systems 11-16, including architecture overview and implementation patterns
- Created detailed documentation for systems 102-135 covering achievements, settings, polish, data assets, input management, and state management. - Added INDEX.md for easy navigation of developer reference materials. - Introduced architecture-overview.md to provide a high-level understanding of the framework's structure and communication methods. - Compiled implementation-patterns.md to outline common UE5 Blueprint patterns for consistent development practices.
This commit is contained in:
Lefteris Notas
156
docs/developer/architecture-overview.md
Normal file
156
docs/developer/architecture-overview.md
Normal file
@@ -0,0 +1,156 @@
|
||||
# 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** | |
|
||||
|
||||
---
|
||||
|
||||
*Architecture Overview v1.0 — Start here before reading category-specific developer docs.*
|
||||
Reference in New Issue
Block a user