# 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.*