138 lines
7.9 KiB
Markdown
138 lines
7.9 KiB
Markdown
# 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.*
|