# 137 — Planar Capture Actor (`BP_PlanarCaptureActor`)

## Purpose
Placeable actor wrapping a `BPC_PlanarCapture` component. Owns the surface mesh, material dynamic instances, proximity trigger for quality scoring, and the capture component. Blueprint children (139-143) extend this for specific modes.

## Dependencies
- **Requires:** `BPC_PlanarCapture` (136), `SS_PlanarCaptureManager` (138)
- **Required By:** `BP_Mirror` (139), `BP_Portal` (140), `BP_Monitor` (141), `BP_HorrorMirror` (142), `BP_FakeWindow` (143)
- **Engine/Plugin Requirements:** Renderer module

## Class Info
| Property | Value |
|----------|-------|
| **Parent Class** | `Actor` (C++ `ABP_PlanarCaptureActor`) |
| **Class Type** | Blueprint Actor |
| **Asset Path** | `Content/Framework/Capture/` |
| **C++ Header** | `Source/PG_Framework/Public/Capture/BP_PlanarCaptureActor.h` |
| **C++ Status** | ✅ Full Implementation |
| **BP Asset** | BP children: `BP_Mirror`, `BP_Portal`, `BP_Monitor`, `BP_HorrorMirror`, `BP_FakeWindow` |

## 1. Components
| Component | Type | Description |
|-----------|------|-------------|
| `Root` | SceneComponent | Root transform |
| `SurfaceMesh` | StaticMeshComponent | Surface plane/quad mesh, collision enabled |
| `ProximityTrigger` | BoxComponent | Overlap volume for player proximity scoring (500x500x500 default) |
| `CaptureComponent` | UBPC_PlanarCapture | Core capture logic |

## 2. Variables

### Configuration
| Variable | Type | Default | Category | Description |
|----------|------|---------|----------|-------------|
| `SurfaceDisplayName` | FString | "" | `Capture\|Config` | Debug/display name |
| `bStartEnabled` | bool | true | `Capture\|Config` | Start active on BeginPlay |
| `bDestructible` | bool | false | `Capture\|Config` | Can be destroyed (shattered mirror) |
| `SurfaceMPC` | UMaterialParameterCollection* | — | `Capture\|Material` | Global MPC reference |

### Runtime
| Variable | Type | Description |
|----------|------|-------------|
| `bIsActive` | bool | Current active state |
| `SurfaceMaterialInstance` | UMaterialInstanceDynamic* | Created dynamic material instance |

### Replicated
| Variable | Type | Condition | Description |
|----------|------|-----------|-------------|
| `bRepIsActive` | bool | ReplicatedUsing OnRep_IsActive | Server-authoritative active state |

## 3. Functions

#### `EnableSurface()`
- **Description:** Activates the surface, initializes capture component
- **Flow:** Set bIsActive=true → CaptureComponent.InitializeCapture()

#### `DisableSurface()`
- **Description:** Deactivates the surface, shuts down capture
- **Flow:** Set bIsActive=false → CaptureComponent.ShutdownCapture()

#### `SetCaptureMode(NewMode: EPlanarCaptureMode)`
- **Description:** Change capture mode at runtime
- **Flow:** Shutdown → Change CaptureComponent.CaptureMode → Re-initialize → Broadcast OnModeChanged

#### `SetSurfaceMaterial(NewMaterial: UMaterialInterface*)`
- **Description:** Swap surface material at runtime (clean ↔ dirty mirror, etc.)
- **Flow:** SurfaceMesh.CreateDynamicMaterialInstance(NewMaterial) → Store as SurfaceMaterialInstance

#### `SetSurfaceMPCParameter(ParameterName: FName, Value: float)`
- **Description:** Set a single MPC scalar parameter on the surface's MID

#### `DestroySurface()`
- **Description:** Destroy the surface (shatter mirror, break monitor). Respects bDestructible flag.
- **Flow:** DisableSurface → Broadcast OnSurfaceDestroyed → (BP child handles visual FX)

## 4. Event Dispatchers
| Dispatcher | Parameters | Description |
|------------|-----------|-------------|
| `OnModeChanged` | NewMode: EPlanarCaptureMode | Mode changed at runtime |
| `OnSurfaceDestroyed` | Surface: ABP_PlanarCaptureActor* | Surface destroyed |

## 5. Overlap Events
| Event | Logic |
|-------|-------|
| `OnProximityBeginOverlap` | If OtherActor has Tag "Player" → CaptureComponent.SetScriptedPriority(0.3) |
| `OnProximityEndOverlap` | If OtherActor has Tag "Player" → CaptureComponent.SetScriptedPriority(0.0) |

## 6. Communication Matrix
| Target System | Method | What |
|---------------|--------|------|
| `SS_PlanarCaptureManager` | Direct (RegisterSurface) | Registers on BeginPlay |
| `BPC_PlanarCapture` | Direct (owns) | Full component access |
| `BPC_ScareEventSystem` (101) | Dispatcher / Interface | Horror mirror scare triggers |
| `SS_AudioManager` (132) | Direct | Surface audio (shatter, portal whoosh) |

## 7. Manual Implementation Guide

### 7.1 Blueprint Child Setup
1. Create Blueprint Class: Parent = `BP_PlanarCaptureActor`, Name = `BP_Mirror` (or `BP_Portal`, etc.)
2. Assign a plane/quad StaticMesh to `SurfaceMesh` in Components panel
3. Set `CaptureComponent.CaptureMode` in Class Defaults
4. Assign `SurfaceMPC` to `MPC_CaptureSurface`
5. Assign material to SurfaceMesh slot 0

### 7.2 Proximity Trigger Adjustments
- Resize `ProximityTrigger.BoxExtent` per surface (larger mirrors = larger trigger)
- The trigger boosts priority when player is near — adjust size for desired quality bump radius

### 7.3 Destruction Handling
```
Event OnSurfaceDestroyed
  → Play shatter sound via SS_AudioManager.PlaySoundAtLocation()
  → Spawn particle effect at actor location
  → (Optional) Notify BPC_ScareEventSystem for jump scare
  → (Optional) Set narrative flag via BPC_NarrativeStateSystem
```

## 8. Build Checklist
- [ ] C++ base class compiles
- [ ] Create BP child with correct mesh
- [ ] Assign material and MPC
- [ ] Configure CaptureComponent defaults
- [ ] Adjust proximity trigger size
- [ ] Test BeginPlay registration with manager
- [ ] Test Enable/Disable surface
- [ ] Test proximity overlap quality boost