# 142 — Horror Mirror Actor (`BP_HorrorMirror`)

## Purpose
Horror mirror extending `BP_Mirror` with wrong-reflection Metahuman, delayed frame ring buffer, steam text reveal, mirror darkness, UV distortion, and coordinated scare events.

## Dependencies
- **Requires:** `BP_Mirror` (139), `BP_PlanarCaptureActor` (137), `BPC_PlanarCapture` (136)
- **Requires (Horror Integration):** `BPC_ScareEventSystem` (101), `SS_AudioManager` (132), `BPC_StressSystem` (10)
- **Engine/Plugin Requirements:** M_CaptureSurface_Master material (horror layers)

## Class Info
| Property | Value |
|----------|-------|
| **Parent Class** | `BP_Mirror` (child of `BP_PlanarCaptureActor`) |
| **Class Type** | Blueprint Actor |
| **Asset Path** | `Content/Framework/Capture/BP_HorrorMirror.uasset` |
| **C++ Status** | 🔵 BP Spec Only — uses C++ horror API (ActivateHorrorReflection, PushDelayedFrame) |
| **BP Asset** | Create in editor: `BP_HorrorMirror` |

## 1. Configuration

| Variable | Value | Description |
|----------|-------|-------------|
| `CaptureComponent.CaptureMode` | `HorrorMirror` | Fixed to HorrorMirror mode |
| `CaptureComponent.WrongReflectionActor` | (Set per instance) | Metahuman/ghost actor for wrong reflection |
| `CaptureComponent.QualityProfiles[3].DelayedFrameCount` | `5` | Hero tier gets 5-frame delay |

### Horror-Specific Properties (Add to BP)
| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `WrongReflectionBlendCurve` | UCurveFloat | — | 0→1→0 blend curve for wrong reflection event |
| `MirrorDarknessCurve` | UCurveFloat | — | 0→1 darkness ramp curve |
| `UVDistortionCurve` | UCurveFloat | — | Distortion amplitude over time |
| `SteamTextRevealTexture` | UTexture2D | — | Mask texture for "HELP ME" text in steam |
| `ScareEventTag` | FGameplayTag | — | Tag identifying this scare in BPC_ScareEventSystem |
| `HorrorAudioCue` | USoundBase | — | Audio cue for horror event (played via SS_AudioManager) |
| `ScareDuration` | float | 5.0 | Total duration of the scare event |

## 2. Material Setup
| Slot | Material | Description |
|------|----------|-------------|
| SurfaceMesh[0] | `MI_Mirror_Horror` | Horror mirror with wrong reflection and darkness layers enabled |

## 3. Event Graph

### Event BeginPlay
```
Event BeginPlay
  ├─ Parent: BeginPlay (from BP_Mirror)
  ├─ Set CaptureComponent.CaptureMode = HorrorMirror
  ├─ Validate CaptureComponent.WrongReflectionActor != nullptr
  │    └─ If null → Log Warning: "BP_HorrorMirror missing WrongReflectionActor!"
  └─ EnableSurface()
```

### Core Event: TriggerHorrorScare()
```
TriggerHorrorScare()
  ├─ [Check] BPC_StateManager.IsActionPermitted(Scare.Tag) → if denied, return
  ├─ [Notify] BPC_ScareEventSystem.TriggerScareEvent(ScareEventTag)
  │    └─ This coordinates with other systems (lights, audio, pacing)
  │
  ├─ [Audio] SS_AudioManager.PlaySoundAtLocation(HorrorAudioCue, GetActorLocation())
  │
  ├─ [Reflection Swap] CaptureComponent.ActivateHorrorReflection()
  │    └─ C++ swaps ShowOnly list to WrongReflectionActor
  │
  ├─ [Start Timeline] Play HorrorScareTimeline
  │    └─ Timeline drives: WrongReflectionBlend, MirrorDarkness, UVDistortion, TextReveal
  │
  └─ [After ScareDuration] Call FinalizeHorrorScare()
```

### Timeline: HorrorScareTimeline
```
HorrorScareTimeline (Float Track, Length = ScareDuration)
  Track 0: WrongReflectionBlend
    Curve: WrongReflectionBlendCurve (0→1→0)
    → SetSurfaceMPCParameter("WrongReflectionBlend", curve value)

  Track 1: MirrorDarkness
    Curve: MirrorDarknessCurve (0→0.8→0.2 linger)
    → SetSurfaceMPCParameter("MirrorDarkness", curve value)

  Track 2: UVDistortion
    Curve: UVDistortionCurve (0→0.3 breath cycle)
    → SetSurfaceMPCParameter("DistortionAmplitude", curve value)

  Track 3: TextReveal
    Curve: 0→1 after 1.5s delay
    → SetSurfaceMPCParameter("TextRevealProgress", curve value)
```

### Event: FinalizeHorrorScare()
```
FinalizeHorrorScare()
  ├─ CaptureComponent.DeactivateHorrorReflection()
  │    └─ C++ restores original ShowOnly list
  ├─ SetSurfaceMPCParameter("WrongReflectionBlend", 0.0)
  ├─ SetSurfaceMPCParameter("MirrorDarkness", 0.0)
  ├─ SetSurfaceMPCParameter("DistortionAmplitude", 0.0)
  ├─ SetSurfaceMPCParameter("TextRevealProgress", 0.0)
  └─ [Notify] BPC_ScareEventSystem.OnScareEventComplete(ScareEventTag)
```

## 4. Communication Matrix
| Target | Method | What |
|--------|--------|------|
| `BPC_ScareEventSystem` (101) | Direct (TriggerScareEvent) | Coordinated scare |
| `SS_AudioManager` (132) | Direct | Horror SFX |
| `BPC_StressSystem` (10) | Dispatcher (optional) | Add stress on scare |
| `BPC_StateManager` (130) | IsActionPermitted() | Gate before triggering scare |
| `BPC_LightEventController` (96) | Dispatcher (optional) | Sync lights with mirror scare |
| `BPC_PacingDirector` (98) | Dispatcher (optional) | Notify of scare for pacing |

## 5. Manual Implementation Guide

### 5.1 Create BP_HorrorMirror
1. Create Blueprint Class: Parent = `BP_Mirror`, Name = `BP_HorrorMirror`
2. Set `CaptureComponent.CaptureMode = HorrorMirror` in defaults
3. Assign `MI_Mirror_Horror` to SurfaceMesh
4. Set `CaptureComponent.QualityProfiles[3].DelayedFrameCount = 5`

### 5.2 Setup Wrong Reflection Actor
1. Place a skeletal mesh actor (Metahuman, ghost mesh) in a hidden room/box near the mirror
2. Set its visibility to false in BeginPlay
3. In BP_HorrorMirror instance: set `CaptureComponent.WrongReflectionActor` → your hidden actor

### 5.3 Create Curves
Create Float Curve assets:
- `Curve_WrongReflectionBlend`: Keys: (0,0), (1.0,1.0), (3.0,1.0), (4.0,0), (5.0,0)
- `Curve_MirrorDarkness`: Keys: (0,0), (0.5,0.8), (2.0,0.6), (4.0,0.3), (5.0,0)
- `Curve_UVDistortion`: Keys: (0,0), (1.0,0.3), (2.0,0.2), (3.0,0.35), (5.0,0)

### 5.4 Build Timeline
1. Create Timeline node with Float Track
2. Add 4 float output tracks
3. Wire each track to `SetSurfaceMPCParameter` with corresponding param name
4. Set Timeline length to `ScareDuration`

### 5.5 Integration Hook
From any gameplay system (narrative trigger, AI event, proximity):
```
BP_HorrorMirror → TriggerHorrorScare()
```

From Sequencer:
```
Event Track → BP_HorrorMirror → TriggerHorrorScare()
```

## 6. Build Checklist
- [ ] Create BP_HorrorMirror Blueprint child
- [ ] Place WrongReflectionActor in level (hidden)
- [ ] Create all 3 Float Curves
- [ ] Build HorrorScareTimeline with 4 tracks
- [ ] Wire MPC parameter sets
- [ ] Wire BPC_ScareEventSystem integration
- [ ] Wire SS_AudioManager audio cue
- [ ] Test TriggerHorrorScare event
- [ ] Verify wrong reflection appears and fades
- [ ] Verify MPC params return to zero after scare
