add blueprints

docs/blueprints/06-ui/46_WBP_DiegeticHUDFrame.md

@@ -0,0 +1,89 @@
+# 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.