Files

Lefteris Notas 0a2d08b2ad 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.

2026-05-22 15:36:08 +03:00

5.3 KiB

Raw Blame History

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

Create Blueprint Class: Parent = BP_PlanarCaptureActor, Name = BP_Portal
In Components: add BoxComponent named TeleportTrigger
Size TeleportTrigger slightly larger than surface mesh (50-100 units deep)
Set TeleportTrigger.CollisionEnabled = QueryOnly, response to Pawn = Overlap
Set CaptureComponent.CaptureMode = Portal in Class Defaults
Assign MI_Portal_Standard to SurfaceMesh

5.2 Portal Link Setup

Place BP_Portal_Source and BP_Portal_Target in level
On Source: set CaptureComponent.LinkedTargetSurface → Target actor
On Target: set CaptureComponent.LinkedTargetSurface → Source actor (if two-way)
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)

5.3 KiB Raw Blame History

140 — Portal Surface Actor (BP_Portal)