Add Planar Capture System implementation checklist and developer reference
- Created a comprehensive implementation checklist for the Planar Capture System (Systems 136-147) detailing tasks across multiple phases including C++ core, material foundation, Blueprint actors, data assets, integration, and performance testing. - Added a developer reference document outlining the architecture, data flow, state machine, budget enforcement, render target pooling, horror features, integration points, multiplayer networking, performance characteristics, debugging methods, and build order for the capture systems. - Introduced examples of capture surface usage in the Project Void horror game, including specific implementations for mirrors, monitors, portals, and fake windows, along with a checklist for integration tasks.
This commit is contained in:
Lefteris Notas
125
docs/blueprints/17-capture/137_BP_PlanarCaptureActor.md
Normal file
125
docs/blueprints/17-capture/137_BP_PlanarCaptureActor.md
Normal file
@@ -0,0 +1,125 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user