add architecture

2026-05-19 10:16:14 +00:00
parent a92b9f4726
commit 7e34765e61
5 changed files with 1943 additions and 0 deletions
--- a/docs/architecture/hud-overview.md
+++ b/docs/architecture/hud-overview.md
@@ -0,0 +1,137 @@
+# HUD System Architecture — Modular Game Framework
+
+**Architecture Overview | UE 5.5–5.7 | Widget Blueprint**
+
+This document explains how the 14 UI widgets in `docs/blueprints/06-ui/` connect and interact. Use this as a wiring reference when implementing the HUD layer.
+
+---
+
+## Widget Hierarchy
+
+```mermaid
+flowchart TD
+    WBP_HUDController[WBP_HUDController — Root HUD Container] --> Diegetic[WBP_DiegeticHUDFrame — Health, Stress, Stamina, Compass]
+    WBP_HUDController --> Prompt[WBP_InteractionPromptDisplay — Interaction cues]
+    WBP_HUDController --> Subtitle[WBP_AccessibilityUI — Subtitles, Accessibility overlays]
+    WBP_HUDController --> Toast[WBP_NotificationToast — Toast messages]
+    WBP_HUDController --> Objective[WBP_ObjectiveDisplay — Active objectives]
+    WBP_HUDController --> ScreenFX[WBP_ScreenEffectController — Damage, Stress, Flash]
+    
+    SS_UIManager[SS_UIManager — Menu Stack Manager] --> MainMenu[WBP_MainMenu]
+    SS_UIManager --> PauseMenu[WBP_PauseMenu]
+    SS_UIManager --> Inventory[WBP_InventoryMenu]
+    SS_UIManager --> Journal[WBP_JournalDocumentViewer]
+    SS_UIManager --> Settings[WBP_SettingsMenu]
+    SS_UIManager --> MenuFlow[WBP_MenuFlowController — State Machine]
+    
+    SS_UIManager -.->|Input Mode Sync| SS_EnhancedInputManager
+    SS_UIManager -.->|Visibility| WBP_HUDController
+```
+
+---
+
+## Two-Layer Architecture
+
+| Layer | Manager | Widgets | When Visible |
+|-------|---------|---------|-------------|
+| **HUD Layer** | `WBP_HUDController` | 45-48, 53-54, 56 | Gameplay only |
+| **Menu Layer** | `SS_UIManager` (44) | 49-52, 55, 57 | On top of gameplay (pause, menu, inventory) |
+
+**Rule:** `WBP_HUDController` hides when any full-screen menu opens. `SS_UIManager` handles the menu stack (push/pop). Only one layer is interactive at a time.
+
+---
+
+## Widget Quick Reference
+
+| # | Widget | Lines | Role | Key Input | Key Output |
+|---|--------|-------|------|-----------|------------|
+| 44 | `SS_UIManager` | — | Menu stack subsystem | `PushMenu`/`PopMenu` | Input mode, cursor state |
+| 45 | `WBP_AccessibilityUI` | 141 | Subtitles + accessibility | `OnDialogueLine` dispatcher | Subtitle text on screen |
+| 46 | `WBP_DiegeticHUDFrame` | 89 | In-world HUD skin | Player state dispatchers | Health/stress/stamina display |
+| 47 | `WBP_HUDController` | 114 | Root HUD container | Game phase changes | Child widget visibility |
+| 48 | `WBP_InteractionPromptDisplay` | 135 | Interaction cues | `OnFocusGained`/`OnFocusLost` | Prompt text + progress ring |
+| 49 | `WBP_InventoryMenu` | — | Inventory grid UI | `BPC_InventorySystem` data | Drag-drop, equip, drop |
+| 50 | `WBP_JournalDocumentViewer` | — | Document/journal reader | `BPC_DocumentArchiveSystem` | Paged text with font styles |
+| 51 | `WBP_MainMenu` | — | Main menu screen | Game start/load events | New game, continue, settings |
+| 52 | `WBP_MenuFlowController` | — | Menu state machine | Menu transitions | Back navigation |
+| 53 | `WBP_NotificationToast` | 52 | Toast notifications | Any system dispatcher | Slide-in text + icon |
+| 54 | `WBP_ObjectiveDisplay` | 86 | Objective overlay | `BPC_ObjectiveSystem` events | Objective text + progress |
+| 55 | `WBP_PauseMenu` | — | Pause menu | Pause input action | Resume, save, load, quit |
+| 56 | `WBP_ScreenEffectController` | 43 | Full-screen effects | Health/stress events | Damage vignette, flash |
+| 57 | `WBP_SettingsMenu` | — | Settings screen | `SS_SettingsSystem` | Audio/video/controls tabs |
+
+---
+
+## Data Flow: HUD Widgets
+
+```
+Player State Components          HUD Layer
+┌─────────────────────┐          ┌──────────────────────────┐
+│ BPC_HealthSystem     │─OnHealthChanged──→│ WBP_DiegeticHUDFrame     │
+│ BPC_StressSystem     │─OnStressTierChanged→│ WBP_ScreenEffectController│
+│ BPC_StaminaSystem    │─OnStaminaChanged─→│ (via WBP_HUDController)  │
+│ BPC_InteractionDetector│─OnFocusGained───→│ WBP_InteractionPromptDisplay│
+│ BPC_DialoguePlayback │─OnDialogueLine───→│ WBP_AccessibilityUI      │
+│ BPC_ObjectiveSystem  │─OnObjectiveUpdate→│ WBP_ObjectiveDisplay     │
+│ Any System           │─ShowToast───────→│ WBP_NotificationToast    │
+└─────────────────────┘          └──────────────────────────┘
+
+Key: WBP_ widgets NEVER write to game state. They only read via dispatchers.
+```
+
+---
+
+## Data Flow: Menu Widgets
+
+```
+Input Event                    Menu Layer (SS_UIManager)
+┌──────────────────┐           ┌─────────────────────────┐
+│ IA_Pause          │──→       │ PushMenu(PauseMenu)      │
+│ IA_Inventory      │──→       │ PushMenu(InventoryMenu)  │
+│ IA_Journal        │──→       │ PushMenu(JournalViewer)  │
+│ IA_Escape (back)  │──→       │ PopMenu() — back nav     │
+│                   │           │                         │
+│ WBP_SettingsMenu  │──SetFloat→│ SS_SettingsSystem        │
+│                   │           │  └→ SS_AudioManager.SetBusVolume│
+│                   │           │  └→ Save to persistent storage│
+└──────────────────┘           └─────────────────────────┘
+```
+
+---
+
+## Implementation Order (Dependency-Safe)
+
+| Step | Widget | Depends On | Reason |
+|------|--------|-----------|--------|
+| 1 | `WBP_HUDController` (47) | *(none)* | Root container — must exist first |
+| 2 | `WBP_DiegeticHUDFrame` (46) | 47 | Parented by HUDController |
+| 3 | `WBP_InteractionPromptDisplay` (48) | 47, `BPC_InteractionDetector` (16) | Needs prompt data |
+| 4 | `WBP_NotificationToast` (53) | 47 | Parented by HUDController |
+| 5 | `WBP_ObjectiveDisplay` (54) | 47, `BPC_ObjectiveSystem` (59) | Needs objective data |
+| 6 | `WBP_ScreenEffectController` (56) | 47 | Parented by HUDController |
+| 7 | `WBP_AccessibilityUI` (45) | 47, `BPC_DialoguePlaybackSystem` (60) | Needs dialogue events |
+| 8 | `SS_UIManager` (44) | *(none — subsystem)* | Menu stack manager |
+| 9 | `WBP_MenuFlowController` (52) | 44 | Menu state machine |
+| 10 | `WBP_MainMenu` (51) | 44, 52 | First menu pushed |
+| 11 | `WBP_PauseMenu` (55) | 44, 52 | Push on pause |
+| 12 | `WBP_SettingsMenu` (57) | 44, 52, `SS_SettingsSystem` (105) | Push from menus |
+| 13 | `WBP_InventoryMenu` (49) | 44, `BPC_InventorySystem` (31) | Needs inventory data |
+| 14 | `WBP_JournalDocumentViewer` (50) | 44, `BPC_DocumentArchiveSystem` (29) | Needs document data |
+
+---
+
+## Key Integration Points with New Systems (130-135)
+
+| Widget | Integration |
+|--------|------------|
+| `WBP_HUDController` | Reads `BPC_StateManager (130).OnStateChanged` — hides HUD during `InCutscene`, `InMainMenu`, `Loading` |
+| `WBP_InteractionPromptDisplay` | Calls `BPC_StateManager.IsActionPermitted(ActionTag)` — shows "Blocked: [Reason]" when action denied |
+| `WBP_InteractionPromptDisplay` | Reads `BPC_StateManager.OnStateChangeDenied` — displays `BlockReason` to player |
+| `WBP_SettingsMenu` | Calls `SS_AudioManager (132).SetBusVolume()` for each volume slider |
+| `WBP_SettingsMenu` | Calls `SS_AudioManager.GetBusVolume()` to populate slider defaults |
+| `WBP_AccessibilityUI` | Reads `BPC_StateManager.GetHeartRate()` for visual heartbeat indicator (deaf accessibility) |
+| `WBP_DiegeticHUDFrame` | Reads `BPC_StateManager.GetVitalSignal()` to show heart rate tier indicator |
+
+---
+
+*Architecture Overview: HUD System. See [`44_SS_UIManager.md`](../blueprints/06-ui/44_SS_UIManager.md) for the menu stack subsystem spec. See [`47_WBP_HUDController.md`](../blueprints/06-ui/47_WBP_HUDController.md) for the root HUD container spec.*