# WBP_DiegeticHUDFrame — Widget (Diegetic HUD Skin Container)

**File:** [`Content/Framework/UI/WBP_DiegeticHUDFrame`](Content/Framework/UI/WBP_DiegeticHUDFrame.uasset)
**Parent Class:** `UUserWidget`
**Dependencies:** [`I_DiegeticDisplay`](../01-core/03_I_InterfaceLibrary.md), [`WBP_HUDController`](WBP_HUDController.md), all player state component dispatchers

**Purpose:** The swappable container for the game's diegetic HUD presentation. This is the "skin" that changes per project — wristwatch, visor, bracelet, handheld device, etc. All data displayed here comes from system dispatchers; it contains zero game logic.

---

## Variables

| Name | Type | Description |
|------|------|-------------|
| `HealthIndicator` | Widget | Child widget showing health (bar, number, pulse) |
| `StressIndicator` | Widget | Child widget showing stress tier |
| `StaminaBar` | Widget | Optional stamina display |
| `CompassWidget` | Widget | Optional directional compass |
| `ActiveItemWidget` | Widget | Currently held item icon and name |
| `TimeDisplay` | TextBlock | In-game world time or session timer |
| `ObjectivePreview` | TextBlock | Single-line current objective snippet |
| `bAnimatedEntries` | Bool | Whether values animate in/out with lerp |
| `PresentationSkin` | E_DiegeticSkin | Current visual skin (watch, visor, handheld) |

## Enums

```cpp
E_DiegeticSkin
{
    Wristwatch,
    VisorHUDSuit,
    HandheldDevice,
    BraceletCharm,
    DiegeticSignage,
    CustomProjectSkin
}
```

## Functions / Events

| Name | Inputs | Outputs | What it does |
|------|--------|---------|--------------|
| `SetDiegeticValue` | Tag: GameplayTag, Value: Float/Text | — | Implements `I_DiegeticDisplay`. Routes to correct child widget |
| `RefreshDisplay` | — | — | Implements `I_DiegeticDisplay`. Force-refreshes all children |
| `SetSkin` | Skin: E_DiegeticSkin | — | Swaps visual presentation without changing data bindings |
| `SetAnimatedEntries` | bAnimated: Bool | — | Toggle value animation lerp |
| `UpdateHealth` | NormalisedValue: Float | — | Bound to BPC_HealthSystem dispatcher |
| `UpdateStress` | Tier: E_StressTier, Value: Float | — | Bound to BPC_StressSystem dispatcher |
| `UpdateStamina` | NormalisedValue: Float | — | Bound to BPC_StaminaSystem dispatcher |
| `UpdateActiveItem` | ItemTag: GameplayTag, DisplayName: FText | — | Bound to BPC_ActiveItemSystem dispatcher |
| `UpdateObjective` | ObjectiveText: FText | — | Bound to BPC_ObjectiveSystem dispatcher |
| `ShowHUD` | — | — | Animate all elements in |
| `HideHUD` | — | — | Animate all elements out |

## Blueprint Flow Diagram

```mermaid
flowchart TD
    A[WBP_HUDController creates WBP_DiegeticHUDFrame] --> B[bAnimatedEntries = Settings value]
    B --> C[Bind to player component dispatchers]
    C --> D[Wait for game phase = InGame]
    D --> E[ShowHUD - animate all elements in]

    F[Health changed] --> G[UpdateHealth - lerp HealthIndicator]
    H[Stress changed] --> I[UpdateStress - update StressIndicator]
    J[Item equipped] --> K[UpdateActiveItem - show icon + name]

    L[Game phase changes to Cutscene] --> M[HideHUD]
    N[Game phase returns to InGame] --> E
```

## Communications With

| Target System | Method | Why |
|---------------|--------|-----|
| `WBP_HUDController` | Parent reference | Visibility control via game phase |
| `BPC_HealthSystem` | Dispatcher `OnHealthChanged` | Health display |
| `BPC_StressSystem` | Dispatcher `OnStressTierChanged` | Stress display |
| `BPC_StaminaSystem` | Dispatcher `OnStaminaChanged` | Stamina display |
| `BPC_ActiveItemSystem` | Dispatcher | Active hand item display |
| `BPC_ObjectiveSystem` | Dispatcher `OnObjectiveActivated` | Objective preview |
| `SS_SettingsSystem` | Direct read | Animated entries preference |

## Reuse Notes

- For a sci-fi game, create `WBP_DiegeticHUD_VisorSkin`. For period horror, create `WBP_DiegeticHUD_WatchSkin`. Only the art/layout changes — all data bindings use the same `I_DiegeticDisplay` interface.
- The `E_DiegeticSkin` enum can be extended per project without modifying this widget's logic.
- This widget implements `I_DiegeticDisplay` so external systems can push data without knowing which skin is active.
- All child widgets are created in `NativeConstruct` and bound to dispatchers there.