diff --git a/Architecture-Overview-%E2%80%94-UE5-Modular-Game-Framework.md b/Architecture-Overview-%E2%80%94-UE5-Modular-Game-Framework.md new file mode 100644 index 0000000..58199f7 --- /dev/null +++ b/Architecture-Overview-%E2%80%94-UE5-Modular-Game-Framework.md @@ -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.*