# WBP_AccessibilityUI — Widget (Subtitle Display, Accessibility Overlays)

**Parent Class:** `UUserWidget` (created via Widget Blueprint)
**Dependencies:** `BPC_DialoguePlaybackSystem`, `BPC_NarrativeStateSystem`, `SS_SettingsSystem`
**File:** `WBP_AccessibilityUI`

---

## Purpose

Provides subtitle rendering, speaking-name display, subtitle background styling, and accessibility-focused UI overlays (high-contrast mode, colorblind filters, font scaling). Listens to dialogue events from `BPC_DialoguePlaybackSystem` and settings changes from `SS_SettingsSystem`.

---

## Responsibilities

- Display subtitles at the bottom-center of the screen with speaker name, dialogue text, and optional background
- Support multi-line subtitle display with timed progression
- Display speaker name above the subtitle text (optional per settings)
- React to accessibility settings: font size scaling, background opacity, colorblind mode, high-contrast mode
- Fade subtitles in/out on line start/end
- Queue subtitle lines if multiple fire rapidly
- Handle subtitle grouping: one line at a time per speaker, multi-speaker stacking

---

## Variables

| Name | Type | Description |
|------|------|-------------|
| `SubtitleContainer` | `VerticalBox` | Vertical stack for active subtitle lines |
| `SpeakerNameText` | `TextBlock` | Current speaker's display name |
| `SubtitleText` | `TextBlock` | Current subtitle line text |
| `SubtitleBackground` | `Image` or `Border` | Background behind subtitle text |
| `AnimSubtitleIn` | `WidgetAnimation` | Fade in subtitle |
| `AnimSubtitleOut` | `WidgetAnimation` | Fade out subtitle |
| `ActiveSubtitles` | Array of `FSubtitleLine` | Currently displayed subtitle lines |
| `SubtitleQueue` | Array of `FSubtitleLine` | Queue if multiple lines arrive simultaneously |
| `bSubtitlesEnabled` | Bool | From settings |
| `SubtitleFontScale` | Float | 0.8, 1.0, 1.2, 1.5 from settings |
| `SubtitleBackgroundOpacity` | Float | 0.0 to 1.0 from settings |
| `bHighContrastMode` | Bool | From settings |
| `bIsCurrentlySpeaking` | Bool | Prevents flicker between rapid lines |

---

## Structs

```cpp
FSubtitleLine
{
    FText SpeakerName;      // "Dr. Hartmann"
    FText LineText;         // "The tumor is benign..."
    float Duration;          // seconds, from dialogue data
    float StartTime;         // world time when line started
    bool bIsFinalLine;       // if true, marks end of dialogue sequence
    FColor SpeakerColor;     // optional per-speaker color
}
```

---

## Functions / Events

| Name | Inputs | Outputs | Description |
|------|--------|---------|-------------|
| `Construct` | — | — | Bind to dialogue dispatchers, load accessibility settings |
| `OnDialogueLineStarted` | Data: `FSubtitleLine` | — | Add subtitle to display, start fade-in timer |
| `OnDialogueLineComplete` | Data: `FSubtitleLine` | — | Start fade-out, remove from active list after animation |
| `OnDialogueSequenceEnded` | — | — | Clear all subtitles, fade out |
| `DisplaySubtitle` | Line: `FSubtitleLine` | — | Set speaker name, text, background; play AnimSubtitleIn |
| `HideSubtitle` | Line: `FSubtitleLine` | — | Play AnimSubtitleOut, remove from container |
| `SetSubtitlesEnabled` | bEnabled: Bool | — | Show/hide subtitle container |
| `ApplyFontScale` | Scale: Float | — | Set subtitle text font size (scalar) |
| `SetBackgroundOpacity` | Opacity: Float | — | Set subtitle background render opacity |
| `ApplyHighContrastMode` | bEnabled: Bool | — | Toggle high-contrast subtitle background/text colors |
| `OnAccessibilitySettingsChanged` | Settings: `S_AccessibilitySettings` | — | Apply all accessibility settings at once |
| `ClearAllSubtitles` | — | — | Remove all active subtitles immediately |

---

## Blueprint Flow — Subtitle Lifecycle

```mermaid
sequenceDiagram
    participant Dialogue as BPC_DialoguePlaybackSystem
    participant Sub as WBP_AccessibilityUI
    participant Timer as Internal Timer

    Dialogue->>Sub: OnDialogueLineStarted LineData
    Sub->>Sub: DisplaySubtitle LineData
    Sub->>Sub: Set SpeakerNameText, SubtitleText
    Sub->>Sub: PlayAnimation FadeIn
    Sub->>Timer: SetTimer by LineData.Duration
    Timer-->>Sub: Timer expired
    Sub->>Sub: PlayAnimation FadeOut
    Sub->>Sub: OnDialogueLineComplete LineData
    Dialogue->>Sub: OnDialogueSequenceEnded
    Sub->>Sub: ClearAllSubtitles
```

---

## Accessibility Settings Consumption

```mermaid
flowchart LR
    A[SS_SettingsSystem] -->|Read on Construct| B[Cache settings]
    B --> C[SetSubtitlesEnabled]
    B --> D[ApplyFontScale]
    B --> E[SetBackgroundOpacity]
    B --> F[ApplyHighContrastMode]
    A -->|OnAccessibilitySettingsChanged dispatcher| G[Re-apply all]
```

---

## Event Dispatchers

| Name | Parameters | Fired When |
|------|-----------|------------|
| `OnSubtitleStarted` | Line: `FSubtitleLine` | A new subtitle line appears |
| `OnSubtitleEnded` | Line: `FSubtitleLine` | A subtitle line ends |
| `OnAllSubtitlesCleared` | — | All subtitles removed |

---

## Communications With

| Target System | Method | Why |
|--------------|--------|-----|
| [`BPC_DialoguePlaybackSystem`](../07-narrative/) | Dispatchers (`OnLineStarted`, `OnLineComplete`, `OnSequenceEnded`) | Receive subtitle data |
| [`SS_SettingsSystem`] | Direct reads, dispatcher on settings changed | Apply accessibility preferences |
| [`WBP_HUD`](33_WBP_HUD.md) | Parent reference | Positioning within HUD canvas |
| [`BPC_NarrativeStateSystem`] | Query | Speaker display name overrides |

---

## Reuse Notes

The subtitle display widget is purely reactive — it never fetches or filters dialogue data. It can be embedded in any HUD canvas (first-person, third-person, diegetic screen overlay). The `FSubtitleLine` struct is intentionally compatible with the `DA_DialogueSequence` line format. If no speaker name is provided, the `SpeakerNameText` collapses and the subtitle text fills the full width. High-contrast mode inverts colors for readability against any background.