# WBP_HUDController — Widget (Root HUD)

**Parent Class:** `UUserWidget` (created via HUD Blueprint)
**Dependencies:** `SS_UIManager`, `BPC_InteractionDetector`, `BPC_HealthSystem`, `BPC_StressSystem`, `BPC_StaminaSystem`, `BPC_NarrativeStateSystem`, `BPC_ObjectiveSystem`, `BPC_DialoguePlaybackSystem`
**File:** `WBP_HUDController`

---

## Purpose

The master HUD container. Owns all in-world HUD sub-widgets and manages their visibility based on game phase and player state. Does NOT own full-screen menus — those are managed by `SS_UIManager`.

---

## Responsibilities

- Create and manage all HUD sub-widgets (diegetic display, interaction prompt, subtitles, notifications, objective overlay, screen effects)
- React to `E_GamePhase` changes (hide HUD during cutscenes, show during play)
- Route visibility of individual HUD elements via gameplay tags
- Never display raw data — always delegates to child widgets
- Handle fade-to-black transitions for death/loading

---

## Variables

| Name | Type | Description |
|------|------|-------------|
| `DiegeticHUDWidget` | `WBP_DiegeticHUDFrame` | The diegetic UI element (watch/visor/etc) |
| `InteractionPromptWidget` | `WBP_InteractionPromptDisplay` | Interaction cues |
| `SubtitleWidget` | `WBP_SubtitleDisplay` | Dialogue/event subtitles |
| `NotificationWidget` | `WBP_NotificationToast` | Toast messages |
| `ObjectiveWidget` | `WBP_ObjectiveDisplay` | Objective overlay |
| `ScreenEffectWidget` | `WBP_ScreenEffectController` | Full-screen effects |
| `MinimapWidget` | Widget | Optional minimap/compass |
| `bHUDVisible` | Bool | Master visibility flag |
| `FadeWidget` | Image | Black full-screen image for fades |

---

## Sub-Widget Class References

| Variable Name | Default Class |
|--------------|---------------|
| `DiegeticHUDClass` | `WBP_DiegeticHUDFrame` (subclass per project) |
| `InteractionPromptClass` | `WBP_InteractionPromptDisplay` |
| `SubtitleClass` | `WBP_SubtitleDisplay` |
| `NotificationClass` | `WBP_NotificationToast` |
| `ObjectiveClass` | `WBP_ObjectiveDisplay` |
| `ScreenEffectClass` | `WBP_ScreenEffectController` |

---

## Functions / Events

| Name | Inputs | Outputs | Description |
|------|--------|---------|-------------|
| `ConstructChildren` | — | — | Spawns all sub-widgets, adds as children |
| `SetHUDVisibility` | bVisible: Bool | — | Master show/hide (for cutscenes) |
| `FadeToBlack` | Duration: Float | — | Lerps FadeWidget opacity to 1 |
| `FadeFromBlack` | Duration: Float | — | Lerps FadeWidget opacity to 0 |
| `TriggerDamageVignette` | Intensity: Float | — | Calls ScreenEffectWidget.TriggerDamageFlash |
| `TriggerJumpScareFlash` | — | — | Calls ScreenEffectWidget.TriggerJumpScareFlash |
| `SetStressDistortion` | Amount: Float | — | Routes to ScreenEffectWidget |
| `OnPhaseChanged` | NewPhase: `E_GamePhase` | — | Listen from GI_GameFramework; hide/show HUD |

---

## Event Dispatchers

| Name | Parameters | Fired When |
|------|-----------|------------|
| `OnHUDHidden` | — | HUD hidden (cutscene/loading) |
| `OnHUDShown` | — | HUD restored |
| `OnFadeComplete` | bFadedIn: Bool | Fade animation completes |

---

## Blueprint Flow — Phase Change Reaction

```mermaid
flowchart TD
    A[OnPhaseChanged received] --> B{NewPhase}
    B -->|InGame| C[SetHUDVisibility true]
    B -->|Cutscene| D[SetHUDVisibility false]
    B -->|Loading| E[FadeToBlack 0.5s]
    B -->|DeathLoop| F[FadeToBlack 1.0s]
    B -->|AltDeathSpace| G[Hide interaction prompt only]
    B -->|Paused| H[Keep HUD but hide diegetic]
    B -->|MainMenu / Credits| I[Destroy HUD entirely]
```

---

## Communications With

| Target System | Method | Why |
|--------------|--------|-----|
| [`SS_UIManager`](44_SS_UIManager.md) | Direct reference | Coordination with menus |
| [`GI_GameFramework`](../01-core/04_GI_GameFramework.md) | Dispatcher (`OnGamePhaseChanged`) | Phase-based visibility |
| [`BPC_InteractionDetector`](../03-interaction/16_BPC_InteractionDetector.md) | Dispatcher (`OnFocusGained`, `OnFocusLost`) | Show/hide interaction prompt |
| [`BPC_DialoguePlaybackSystem`](../07-narrative/) | Dispatcher (`OnLineStarted`, `OnLineComplete`) | Subtitle routing |
| [`BPC_ObjectiveSystem`](../07-narrative/) | Dispatcher (`OnObjectiveActivated`, `OnObjectiveCompleted`) | Objective overlay updates |
| [`BPC_HealthSystem`](../02-player/08_BPC_HealthSystem.md) | Dispatcher (`OnHealthChanged`, `OnHealthCritical`) | Damage vignette |
| [`BPC_StressSystem`](../02-player/10_BPC_StressSystem.md) | Dispatcher (`OnStressTierChanged`) | Stress distortion |
| [`BPC_NotificationSystem`] | Dispatcher | Toast messages |

---

## Reuse Notes

The HUD class references are configurable so each project can override `DiegeticHUDClass` with a themed skin (watch, visor, bracelet, etc.) without modifying any logic. The fade system is used by death handling, chapter transitions, and loading screens interchangeably.

- Renamed from `WBP_HUD` to `WBP_HUDController` per Master naming convention.