add blueprints

2026-05-19 13:22:27 +03:00
parent f71bc678b2
commit 411edea8ce
138 changed files with 23330 additions and 0 deletions
--- a/docs/blueprints/06-ui/48_WBP_InteractionPromptDisplay.md
+++ b/docs/blueprints/06-ui/48_WBP_InteractionPromptDisplay.md
@@ -0,0 +1,135 @@
+# WBP_InteractionPromptDisplay — Widget (Interaction Prompt Display)
+
+**Parent Class:** `UUserWidget` (created via Widget Blueprint)
+**Dependencies:** `BPC_InteractionDetector`, `I_Interactable`
+**File:** `WBP_InteractionPromptDisplay`
+
+---
+
+## Purpose
+
+Displays a context-sensitive interaction prompt at the center of the screen (or offset near the interactable world-location). Shows the interaction action name, hold-to-interact progress bar, and platform-specific input key icon.
+
+---
+
+## Responsibilities
+
+- Listen to `BPC_InteractionDetector.OnFocusGained` and `OnFocusLost` dispatchers
+- When focus gained: fade in prompt text ("Press E to Open", "Hold F to Pull Lever")
+- When hold interaction required: display a circular progress fill ring around the prompt
+- When focus lost: fade out prompt immediately or animate out
+- Display _context tags_ from the interactable (e.g. [Safe], [Dangerous], [Locked])
+- Avoid overlapping with other HUD elements — offset from world-location if `bUseWorldOffset` is true
+- Support a "look-at" mode (interaction prompt tracks the world location of the interactable)
+
+---
+
+## Variables
+
+| Name | Type | Description |
+|------|------|-------------|
+| `OwningDetector` | `BPC_InteractionDetector` | Cached reference (set on Construct) |
+| `CurrentInteractable` | `I_Interactable` | Object currently in focus |
+| `PromptText` | `TextBlock` | "Open Door", "Pick Up Note", etc. |
+| `ActionKeyIcon` | `Image` | Platform-specific key icon |
+| `HoldProgressRing` | `Image` | Circular fill ring for hold interactions |
+| `ContextTagsContainer` | `HorizontalBox` | Row of context tag labels |
+| `bIsVisible` | Bool | Current visibility state |
+| `bUseWorldOffset` | Bool | If true, offset prompt to world location |
+| `AnimFadeIn` | `WidgetAnimation` | Fade in animation |
+| `AnimFadeOut` | `WidgetAnimation` | Fade out animation |
+| `AnimHoldProgress` | `WidgetAnimation` | Hold fill progress animation |
+| `PromptYOffset` | Float | Vertical offset from screen center (pixels) |
+
+---
+
+## Functions / Events
+
+| Name | Inputs | Outputs | Description |
+|------|--------|---------|-------------|
+| `Construct` | — | — | Cache detector, bind dispatchers, set to hidden |
+| `OnInteractionFocusGained` | Interactable: `I_Interactable`, InteractionInfo: `S_InteractionInfo` | — | Update prompt text/icon, play fade in |
+| `OnInteractionFocusLost` | Interactable: `I_Interactable` | — | Play fade out, clear state |
+| `UpdatePrompt` | Info: `S_InteractionInfo` | — | Set PromptText, ActionKeyIcon, hold duration |
+| `SetHoldProgress` | Progress: Float (0-1) | — | Update HoldProgressRing fill amount |
+| `OnHoldStarted` | Duration: Float | — | Play hold progress animation over Duration |
+| `OnHoldCancelled` | — | — | Stop hold animation, reset ring to 0 |
+| `OnHoldCompleted` | — | — | Ring fills to 1 at end of hold |
+| `SetContextTags` | Tags: Array of Text | — | Add context tag labels to ContextTagsContainer |
+| `UpdateScreenPosition` | — | — | Tick: if bUseWorldOffset, project world location to screen |
+
+---
+
+## Structs
+
+```cpp
+// Consumed from BPC_InteractionDetector
+S_InteractionInfo
+{
+    FText ActionLabel;           // "Open", "Pick Up", etc
+    FText ObjectName;            // "Wooden Door", "Old Note"
+    bool bRequiresHold;
+    float HoldDuration;          // seconds
+    UTexture2D* ActionKeyIcon;   // platform-specific input icon
+    TArray<FText> ContextTags;   // "Safe", "Locked", "Hold"
+}
+```
+
+---
+
+## Blueprint Flow — Focus Gained
+
+```mermaid
+sequenceDiagram
+    participant Player as Player
+    participant Detector as BPC_InteractionDetector
+    participant UI as WBP_InteractionPromptDisplay
+    participant Interactable as I_Interactable
+
+    Player->>Detector: Look at interactable
+    Detector->>Interactable: GetInteractionInfo()
+    Interactable-->>Detector: S_InteractionInfo
+    Detector-->>UI: OnFocusGained Interactable, Info
+    UI->>UI: UpdatePrompt Info
+    UI->>UI: SetVisibility Visible
+    UI->>UI: PlayAnimation FadeIn
+    Note over UI: Hold required?
+    alt Hold interaction
+        UI->>UI: OnHoldStarted Duration
+        loop Each tick
+            UI->>UI: SetHoldProgress elapsed/Duration
+        end
+        UI->>UI: OnHoldCompleted
+    else Tap interaction
+        UI->>UI: OnHoldCompleted instantly
+    end
+```
+
+---
+
+## Event Dispatchers
+
+| Name | Parameters | Fired When |
+|------|-----------|------------|
+| `OnPromptShown` | — | Prompt becomes visible |
+| `OnPromptHidden` | — | Prompt becomes hidden |
+| `OnHoldComplete` | — | Hold-fill reaches 100% |
+
+---
+
+## Communications With
+
+| Target System | Method | Why |
+|--------------|--------|-----|
+| [`BPC_InteractionDetector`](../03-interaction/16_BPC_InteractionDetector.md) | Dispatchers | Receive focus gain/loss, hold progress |
+| [`WBP_HUDController`](WBP_HUDController.md) | Parent reference | Positioning coordination |
+| [`I_Interactable`](../01-core/03_I_InterfaceLibrary.md) | Function call | GetInteractionInfo for prompt data |
+
+---
+
+## Reuse Notes
+
+The prompt rendering pattern is used in both first-person and third-person contexts. The `bUseWorldOffset` flag lets this widget serve both diegetic HUD skins (watch screen show prompts) and traditional screen-center prompt systems. Context tags are optional — if the array is empty, the container collapses.
+
+- Renamed from `WBP_InteractionUI` to `WBP_InteractionPromptDisplay` per Master naming convention.
+- Cross-references updated: `WBP_HUD` → `WBP_HUDController`.