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
124
docs/blueprints/17-capture/140_BP_Portal.md
Normal file
124
docs/blueprints/17-capture/140_BP_Portal.md
Normal file
@@ -0,0 +1,124 @@
|
||||
# 140 — Portal Surface Actor (`BP_Portal`)
|
||||
|
||||
## Purpose
|
||||
Portal surface with linked target. Renders the view from another location in the world through a planar surface. Supports one-way vs two-way rendering, teleport on overlap, and clip plane for flush geometry placement.
|
||||
|
||||
## Dependencies
|
||||
- **Requires:** `BP_PlanarCaptureActor` (137), `BPC_PlanarCapture` (136), `BPC_StateManager` (130) for teleport gating
|
||||
- **Required By:** Narrative sequences, level transitions, horror portal variants
|
||||
- **Engine/Plugin Requirements:** Oblique clip plane requires Renderer module (C++)
|
||||
|
||||
## Class Info
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Parent Class** | `BP_PlanarCaptureActor` (C++ `ABP_PlanarCaptureActor`) |
|
||||
| **Class Type** | Blueprint Actor |
|
||||
| **Asset Path** | `Content/Framework/Capture/BP_Portal.uasset` |
|
||||
| **C++ Status** | 🔵 BP Spec Only |
|
||||
| **BP Asset** | Create in editor: `BP_Portal` |
|
||||
|
||||
## 1. Configuration (Class Defaults)
|
||||
|
||||
| Variable | Value | Description |
|
||||
|----------|-------|-------------|
|
||||
| `CaptureComponent.CaptureMode` | `Portal` | Fixed to Portal mode |
|
||||
| `CaptureComponent.LinkedTargetSurface` | (Set per instance) | Destination portal actor |
|
||||
| `bStartEnabled` | `true` | Active by default |
|
||||
| `SurfaceMPC` | `MPC_CaptureSurface` | Global MPC |
|
||||
|
||||
### Portal-Specific Properties (Custom Variables — add to BP)
|
||||
| Variable | Type | Default | Description |
|
||||
|----------|------|---------|-------------|
|
||||
| `bTeleportOnOverlap` | bool | true | Teleport player when they enter the portal volume |
|
||||
| `bOneWay` | bool | true | True = only source→target; false = bidirectional |
|
||||
| `TeleportTrigger` | BoxComponent | — | Overlap volume for teleport (separate from ProximityTrigger) |
|
||||
|
||||
## 2. Material Setup
|
||||
| Slot | Material | Description |
|
||||
|------|----------|-------------|
|
||||
| SurfaceMesh[0] | `MI_Portal_Standard` | Portal surface with edge fade |
|
||||
| Frame (optional) | Designer mesh + material | Portal frame decoration |
|
||||
|
||||
## 3. Event Graph
|
||||
|
||||
### Event BeginPlay
|
||||
```
|
||||
Event BeginPlay
|
||||
├─ Parent: BeginPlay (registers with manager)
|
||||
├─ Set CaptureComponent.CaptureMode = Portal
|
||||
├─ Validate CaptureComponent.LinkedTargetSurface != nullptr
|
||||
│ └─ If null → Log Warning: "BP_Portal missing LinkedTargetSurface!"
|
||||
├─ Bind TeleportTrigger.OnComponentBeginOverlap → OnPortalOverlap
|
||||
└─ EnableSurface()
|
||||
```
|
||||
|
||||
### Event: OnPortalOverlap(OtherActor, OtherComp, ...)
|
||||
```
|
||||
OnPortalOverlap(OtherActor)
|
||||
├─ Cast OtherActor to Player Pawn
|
||||
├─ [If bTeleportOnOverlap and HasAuthority]
|
||||
│ ├─ Query BPC_StateManager.IsActionPermitted(Framework.Action.Teleport)
|
||||
│ │ └─ If denied → return (play denied feedback)
|
||||
│ ├─ Get LinkedTargetSurface actor transform
|
||||
│ ├─ Compute exit location: TargetTransform + offset
|
||||
│ ├─ Teleport player: SetActorLocation + SetActorRotation
|
||||
│ └─ Play portal travel SFX via SS_AudioManager
|
||||
└─ [If client] Call Server_TeleportThroughPortal RPC
|
||||
```
|
||||
|
||||
### Server RPC: Server_TeleportThroughPortal
|
||||
```
|
||||
Server_TeleportThroughPortal (Server, Reliable)
|
||||
├─ Validate HasAuthority
|
||||
├─ Validate portal still active
|
||||
├─ Validate LinkedTargetSurface still valid
|
||||
├─ Teleport player (same as OnPortalOverlap logic)
|
||||
└─ Multicast_OnPlayerTeleported to notify all clients
|
||||
```
|
||||
|
||||
## 4. Communication Matrix
|
||||
| Target | Method | What |
|
||||
|--------|--------|------|
|
||||
| `BPC_StateManager` (130) | `IsActionPermitted()` | Teleport gating |
|
||||
| `SS_AudioManager` (132) | Direct | Portal whoosh/disappear SFX |
|
||||
| `SS_EnhancedInputManager` (128) | Direct (optional) | Context switch during portal transition |
|
||||
| `BPC_CameraStateLayer` (14) | Direct (optional) | Camera FOV transition during teleport |
|
||||
|
||||
## 5. Manual Implementation Guide
|
||||
|
||||
### 5.1 Create BP_Portal
|
||||
1. Create Blueprint Class: Parent = `BP_PlanarCaptureActor`, Name = `BP_Portal`
|
||||
2. In Components: add `BoxComponent` named `TeleportTrigger`
|
||||
3. Size `TeleportTrigger` slightly larger than surface mesh (50-100 units deep)
|
||||
4. Set `TeleportTrigger.CollisionEnabled = QueryOnly`, response to Pawn = Overlap
|
||||
5. Set `CaptureComponent.CaptureMode = Portal` in Class Defaults
|
||||
6. Assign `MI_Portal_Standard` to SurfaceMesh
|
||||
|
||||
### 5.2 Portal Link Setup
|
||||
1. Place `BP_Portal_Source` and `BP_Portal_Target` in level
|
||||
2. On Source: set `CaptureComponent.LinkedTargetSurface` → Target actor
|
||||
3. On Target: set `CaptureComponent.LinkedTargetSurface` → Source actor (if two-way)
|
||||
4. Position surfaces facing each other's expected viewing directions
|
||||
|
||||
### 5.3 Teleport Implementation
|
||||
```
|
||||
Create custom event OnPortalOverlap (bind to TeleportTrigger)
|
||||
→ Switch HasAuthority
|
||||
Authority:
|
||||
→ Get LinkedTargetSurface → Get Actor Transform
|
||||
→ Teleport: Set Actor Location (target location + forward * 200)
|
||||
→ Set Actor Rotation (target rotation)
|
||||
→ Play Sound 2D (portal whoosh cue via SS_AudioManager)
|
||||
Remote:
|
||||
→ Call Server_TeleportThroughPortal (RPC)
|
||||
```
|
||||
|
||||
## 6. Build Checklist
|
||||
- [ ] Create BP_Portal with TeleportTrigger component
|
||||
- [ ] Set CaptureMode=Portal
|
||||
- [ ] Assign MI_Portal_Standard material
|
||||
- [ ] Implement overlap teleport logic with HasAuthority gate
|
||||
- [ ] Add Server_TeleportThroughPortal RPC
|
||||
- [ ] Test one-way portal: source renders target view
|
||||
- [ ] Test teleport: player overlaps and appears at target
|
||||
- [ ] Test with BPC_StateManager gating (block teleport during certain states)
|
||||
Reference in New Issue
Block a user