11 KiB
11 KiB
Planar Capture System Architecture — UE5 Modular Game Framework
Version: 1.0 | Systems: 136-147 (12 systems) | Phase: 17 — Rendering & Visual
This document specifies the architecture of the Planar Capture System — a unified rendering pipeline for mirrors, portals, monitors, and horror surfaces. One capture pipeline, one quality manager, one material interface.
Architecture Overview
┌─────────────────────────────────────────────────────────────────────────────┐
│ BLUEPRINT LAYER (Designer-Facing) │
│ BP_Mirror BP_HorrorMirror BP_Portal BP_Monitor BP_FakeWindow │
│ DA_PlanarCaptureProfile MPC_CaptureSurface MI_Mirror_Clean/Dirty/Steam │
├─────────────────────────────────────────────────────────────────────────────┤
│ C++ LAYER (Performance-Critical) │
│ UBPC_PlanarCapture — SceneCapture2D lifecycle, camera math │
│ ABP_PlanarCaptureActor — Surface mesh, MDI, overlap/proximity │
│ USS_PlanarCaptureManager — Global budget, RT pool, scoring (WorldSubsystem + FTickable) │
│ UPlanarCaptureCameraUtils — Mirror/Portal/Oblique math (static) │
├─────────────────────────────────────────────────────────────────────────────┤
│ UE5 ENGINE │
│ USceneCaptureComponent2D UTextureRenderTarget2D UMaterialParameterColl │
└─────────────────────────────────────────────────────────────────────────────┘
System Map (12 Systems — Files 136-147)
| # | System | Type | Parent Class | Purpose |
|---|---|---|---|---|
| 136 | BPC_PlanarCapture |
BPC_ Component | ActorComponent |
Core capture: SceneCapture2D lifecycle, camera math, RT management, actor lists, horror ring buffer |
| 137 | BP_PlanarCaptureActor |
BP_ Actor | Actor |
Placeable surface actor: mesh, MDI, proximity trigger, manager registration |
| 138 | SS_PlanarCaptureManager |
SS_ Subsystem | WorldSubsystem |
Global budget manager: surface scoring, quality tier assignment, RT pool |
| 139 | BP_Mirror |
BP_ Actor | BP_PlanarCaptureActor |
Standard mirror: Mode=Mirror, dirt/steam/condensation layers, aging |
| 140 | BP_Portal |
BP_ Actor | BP_PlanarCaptureActor |
Portal surface: Mode=Portal, linked target, teleport on overlap, clip plane |
| 141 | BP_Monitor |
BP_ Actor | BP_PlanarCaptureActor |
Security screen/TV: Mode=Monitor, fixed camera ref, low update rate, scanlines |
| 142 | BP_HorrorMirror |
BP_ Actor | BP_Mirror |
Horror mirror: wrong reflection actor, delayed frame, steam text reveal, scare events |
| 143 | BP_FakeWindow |
BP_ Actor | BP_PlanarCaptureActor |
Architectural fake window: Mode=FakeWindow, linked sublevel, weather overlay |
| 144 | M_CaptureSurface_Master |
Material | Material |
Master unlit material: RT sample, condensation, dirt, steam, horror layers |
| 145 | MPC_CaptureSurface |
MPC | MaterialParameterCollection |
Global MPC: SteamIntensity, DirtOpacity, MirrorDarkness, WrongReflectionBlend, etc. (10 params) |
| 146 | DA_PlanarCaptureProfile |
DA_ Data Asset | PrimaryDataAsset |
Per-surface capture config: default mode, quality profile overrides, actor lists |
| 147 | MI_Mirror_Clean/Dirty/Steam/Horror |
MI_ Instances | M_CaptureSurface_Master |
Pre-configured material instances for common mirror states |
Enums
EPlanarCaptureMode (C++: defined in PlanarCaptureCommon.h)
| Value | Description |
|---|---|
Mirror |
Standard planar mirror reflection |
Portal |
Portal with linked target surface |
Monitor |
Fixed-camera security screen / TV |
HorrorMirror |
Mirror with horror features (wrong reflection, delayed frame) |
HorrorPortal |
Portal with horror features |
FakeWindow |
Architectural fake window (parallax, weather) |
EPlanarCaptureQualityTier (C++: defined in PlanarCaptureCommon.h)
| Value | RT Size | FPS | Shadows | Lumen | Post | Clip Plane |
|---|---|---|---|---|---|---|
Off |
— | 0 | — | — | — | — |
Low |
256 | 4 | No | No | No | No |
Medium |
512 | 15 | Dynamic | Optional | No | Yes |
High |
1024 | 30 | Full | Yes | Minimal | Yes |
Hero |
2048 | 60 | Full | Yes | Full | Yes |
Communication Matrix
| Source | Target | Method | What |
|---|---|---|---|
BP_PlanarCaptureActor |
SS_PlanarCaptureManager |
Direct (RegisterSurface) | Registers on BeginPlay |
SS_PlanarCaptureManager |
BPC_PlanarCapture |
Direct (ApplyQualityTier) | Assigns quality tier |
BPC_PlanarCapture |
USceneCaptureComponent2D |
Direct (owns) | Camera math + CaptureScene |
BPC_PlanarCapture |
MPC_CaptureSurface |
Direct (SetScalarParameter) | Pushes steam/dirt/horror params |
BP_HorrorMirror |
BPC_ScareEventSystem (101) |
Interface / Dispatcher | Triggers coordinated scares |
BP_HorrorMirror |
SS_AudioManager (132) |
Direct | Plays mirror horror SFX |
BPC_PlanarCapture |
BPC_StateManager (130) |
IsActionPermitted() | Checks if capture can activate |
BP_Portal |
Player Pawn | Overlap Event | Teleports player through portal |
Quality Scoring Algorithm
CompositeScore = (ScreenCoverage × 0.5) + (FacingAngle × 0.3) + (DistanceFactor × 0.1) + (ScriptedPriority × 0.1)
Tier assignment:
Score ≥ 0.8 → Hero (capped at GlobalQualityCap, max MaxHeroSurfaces)
Score ≥ 0.5 → High (capped at max MaxHighSurfaces)
Score ≥ 0.2 → Medium (capped at max MaxMediumSurfaces)
Score > 0 → Low
Score = 0 or !inFrustum → Off
Material Layer Stack (M_CaptureSurface_Master)
Layer 0: Render target sample (UV-flipped for mirror, straight for portal/monitor)
Layer 1: Condensation normal map → distorts UV of RT sample
Layer 2: Fresnel edge fade mask
Layer 3: Dirt/scratch multiply (DirtOpacity MPC param)
Layer 4: Steam/fog lerp (animated noise, SteamIntensity MPC param)
Layer 5: Steam emissive glow (backlit fog, SteamEmissiveIntensity)
Layer 6: Text reveal mask lerp (TextRevealProgress, uses steam as carrier)
Layer 7: Mirror darkness multiply (MirrorDarkness MPC param)
Layer 8: Wrong reflection crossfade (WrongReflectionBlend MPC param)
Output: Unlit shading model
Horror Features
| Feature | Driven By | Layer |
|---|---|---|
| Mirror-only ghost actor | ShowOnly list in C++ | C++ |
| Wrong reflection Metahuman swap | ActivateHorrorReflection() | C++ |
| Delayed frame reflection | FrameRingBuffer + DelayedReflectionBlend MPC | C++ + Material |
| Steam fogging | SteamIntensity MPC → Layer 4 | Material |
| Dirt / scratches | DirtOpacity MPC → Layer 3 | Material |
| Condensation rivulets | CondensationFlow MPC → Layer 1 | Material |
| UV distortion / breathing | DistortionAmplitude MPC → Layer 1 | Material |
| Text in steam reveal | TextRevealProgress MPC → Layer 6 | Material |
| Mirror goes dark | MirrorDarkness MPC → Layer 7 | Material |
| Wrong reflection crossfade | WrongReflectionBlend MPC → Layer 8 | Material |
| Surface aging/oxidation | SurfaceAge MPC → Layer 3 (tint) | Material |
Blueprint Limitations & Workarounds
USceneCaptureComponent2D::CaptureScene() (C++ Only)
Workaround: Call from C++ in UBPC_PlanarCapture. Blueprint calls CaptureNow() which invokes C++ capture.
Affected Files: 136, 139-143
FSceneView::ViewMatrices for Oblique Projection (C++ Only)
Workaround: Use UPlanarCaptureCameraUtils::ComputeObliqueProjectionMatrix() (BlueprintCallable).
Affected Files: 136, 140
USceneCaptureComponent2D::ShowOnlyActors Runtime Modification (Partial C++)
Workaround: UBPC_PlanarCapture::UpdateActorLists() resolves TSoftObjectPtrs into the array.
Affected Files: 136, 142
Performance Budget Guidelines
| Tier | Max Simultaneous | RT Memory per Surface | GPU Cost |
|---|---|---|---|
| Hero | 1 | 16 MB (2048² × 4B) | Very High |
| High | 3 | 4 MB (1024² × 4B) | High |
| Medium | 6 | 1 MB (512² × 4B) | Medium |
| Low | Unlimited | 256 KB (256² × 4B) | Low |
| Off | — | 0 | None |
Total Budget: 128 MB default (configurable via SS_PlanarCaptureManager.MaxTotalRenderTargetMemoryMB)
Multiplayer Considerations
- Capture rendering is local-only — each client renders their own view
BP_PlanarCaptureActorreplicatesbIsActivefor server-authoritative surface control- Horror events (wrong reflection activation) are triggered server-side and replicated via gameplay tags
- No client prediction needed — captures are cosmetic
Integration Points with Existing Systems
| Existing System | Integration |
|---|---|
BPC_StateManager (130) |
Query IsActionPermitted() before enabling capture, teleport gating |
BPC_ScareEventSystem (101) |
Horror mirror events trigger coordinated scares |
SS_AudioManager (132) |
Mirror/portal SFX route through audio subsystem |
SS_EnhancedInputManager (128) |
Input context switch for portal inspection mode |
BPC_DiegeticDisplay (18) |
Monitors can display diegetic UI render targets |
BPC_CameraStateLayer (14) |
Camera FOV adjustments during portal transitions |
I_Persistable (36) |
Mirror surface state (destroyed, dirty, oxidized) saves/loads |
DA_ScareEvent (127) |
Mirror apparition scare event data asset |
WBP_SettingsMenu (57) |
Capture surface quality settings (Performance section) |
Build Order (Phase 17)
- Phase 17a: C++ Core —
PlanarCaptureCommon.h,PlanarCaptureCameraUtils,BPC_PlanarCapture,SS_PlanarCaptureManager,BP_PlanarCaptureActor - Phase 17b: Material Foundation —
M_CaptureSurface_Master,MPC_CaptureSurface,MI_Mirror_*instances - Phase 17c: Blueprint Actors —
BP_Mirror,BP_Portal,BP_Monitor,BP_HorrorMirror,BP_FakeWindow - Phase 17d: Data Assets —
DA_PlanarCaptureProfile - Phase 17e: Integration — Wire horror events to
BPC_ScareEventSystem, audio toSS_AudioManager, persistence toI_Persistable
Planar Capture System Architecture v1.0 — See docs/blueprints/17-capture/ for per-system blueprint specs.