diff --git a/README.md b/README.md index 5653b35..4cef888 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ **A complete Blueprint architecture for first-person narrative horror games — and beyond.** -This is a production-ready, modular game framework for Unreal Engine 5.5–5.7. It provides 135 self-contained Blueprint systems across 16 categories, plus a fully documented example game prototype ("Project Void"). Built Blueprint-first with 22 supporting C++ classes for performance-critical paths. +This is a production-ready, modular game framework for Unreal Engine 5.5–5.7. It provides 147 self-contained Blueprint systems across 17 categories, plus a fully documented example game prototype ("Project Void"). Built Blueprint-first with 27 supporting C++ classes for performance-critical paths. --- @@ -50,6 +50,9 @@ Server-authoritative replication model. All state mutations gated by `HasAuthori ### State Management Central State Manager (42 exclusive action states + 18 overlay states). All systems query `IsActionPermitted(Tag)` instead of checking other systems directly. Gating rules configured in a designer-editable Data Asset (no Blueprint changes needed). Force Stack pattern for death/cutscenes/void space. GASP liaison for movement→action state mapping. Vital signal tracking (Normal → Critical). +### Planar Capture System (Phase 17) +Unified rendering pipeline for mirrors, portals, monitors, and horror surfaces. C++ core with Blueprint designer-interface. World Subsystem quality budget manager with 5-tier automatic quality scaling (Off → Low/256px/4fps → Medium/512px/15fps → High/1024px/30fps → Hero/2048px/60fps). Horror features: wrong-reflection actor swap, delayed frame ring buffer, 10-parameter MPC steam/dirt/darkness/text reveal material system. Render target pool with automatic reuse. Blueprint children: BP_Mirror, BP_Portal, BP_Monitor, BP_HorrorMirror, BP_FakeWindow. Integrates with scare events, audio manager, and state manager. + ### Polish & Tooling Tutorial system with contextual triggers, Loading screen with tips & progress, Credits screen, Analytics tracker (opt-in), Developer Cheat Manager (god mode, noclip, teleport, give item), Error Handler with crash recovery, FPS counter, Debug Menu (state viewer, AI debug, performance, audio). @@ -70,6 +73,15 @@ A complete psychological horror FPS prototype demonstrating every system. Set in - 6 atmosphere profiles with room audio zones - 6 scare events with anticipation/payoff/recovery cycles - Void space alternate-reality death system +- 8 planar capture surfaces (mirrors, horror mirrors, security monitors, void portals, fake windows) with automatic quality scaling +- 18 pickup items (weapons, tools, consumables, keys, documents, collectibles) +- 4 held weapons (pistol, shotgun, flashlight, crowbar) +- 3 enemy types with full AI (Patient, Orderly, Void Shade) +- 4 main objectives + 3 side objectives with branching narrative +- 3 endings determined by player choices, collectibles, sanity, and playstyle +- 6 atmosphere profiles with room audio zones +- 6 scare events with anticipation/payoff/recovery cycles +- Void space alternate-reality death system --- @@ -91,6 +103,7 @@ A complete psychological horror FPS prototype demonstrating every system. Set in | **Find Blueprint-only workarounds** | [`docs/architecture/blueprint-limitations-workarounds.md`](docs/architecture/blueprint-limitations-workarounds.md) | | **See the HUD architecture** | [`docs/architecture/hud-overview.md`](docs/architecture/hud-overview.md) | | **See the audio architecture** | [`docs/architecture/metasounds-audio-system.md`](docs/architecture/metasounds-audio-system.md) | +| **See the planar capture system** | [`docs/architecture/planar-capture-system.md`](docs/architecture/planar-capture-system.md) | | **See C++/BP implementation status** | [`docs/checklists/cpp-blueprint-status.md`](docs/checklists/cpp-blueprint-status.md) | --- @@ -98,7 +111,7 @@ A complete psychological horror FPS prototype demonstrating every system. Set in ## Tech Stack - **Engine:** Unreal Engine 5.5–5.7 -- **Scripting:** Blueprint-Only (with 22 C++ support classes) +- **Scripting:** Blueprint-Only (with 27 C++ support classes) - **Locomotion:** GASP (Ground Animation Strafing Platform) — read-only, extended via notifies - **Input:** Enhanced Input System — 30+ Input Actions, stack-based context switching - **Assets:** `UPrimaryDataAsset` for all content definitions @@ -113,20 +126,24 @@ A complete psychological horror FPS prototype demonstrating every system. Set in | What | How Many | |------|:--------:| -| Blueprint system specs | 135 | -| C++ classes | 22 | +| Blueprint system specs | 147 | +| C++ classes | 27 | | Widget Blueprints | 14 | | Blueprint Components | 80 | -| Blueprint Actors | 11 | +| Blueprint Actors | 16 | | Data Assets | 19 | | Game Instance Subsystems | 7 | +| World Subsystems | 1 | +| Materials | 1 | +| Material Instances | 7 | +| Material Parameter Collections | 1 | | Interfaces | 3 | | Gameplay Tags | 334 | | Input Actions | 30+ | | Animation Notifies | 14 | -| Architecture docs | 8 | -| Developer docs | 12 | -| Game prototype docs | 21 | +| Architecture docs | 9 | +| Developer docs | 13 | +| Game prototype docs | 22 | | Example game assets | 170+ | --- diff --git a/UE5_Modular_Game_Framework.md b/UE5_Modular_Game_Framework.md index e25777b..c142391 100644 --- a/UE5_Modular_Game_Framework.md +++ b/UE5_Modular_Game_Framework.md @@ -1,7 +1,7 @@ # Reusable UE5 Modular Game Framework ### A Complete Blueprint Architecture for First-Person Narrative Horror (and Beyond) -> **C++ Status (2026-05-21):** 22 C++ classes implemented in `Source/PG_Framework/` — 12 full implementations (GI_GameFramework, GM_CoreGameMode, GS_CoreGameState, DA_GameTagRegistry, FL_GameUtilities, I_InterfaceLibrary, BPC_InventorySystem, SS_SaveManager, BPC_DamageReceptionSystem, SS_EnhancedInputManager, BPC_StateManager, DA_ItemData) + 10 stubs (BPC_HealthSystem, BPC_StaminaSystem, BPC_StressSystem, BPC_MovementStateSystem, PC_CoreController, PS_CorePlayerState, BPC_HitReactionSystem, BPC_ShieldDefenseSystem, DA_EquipmentConfig, DA_StateGatingTable). See [`docs/checklists/cpp-blueprint-status.md`](docs/checklists/cpp-blueprint-status.md) for the full grid. All 135 Blueprint spec files exist in [`docs/blueprints/`](docs/blueprints/INDEX.md) with Manual Implementation Guides. +> **C++ Status (2026-05-22):** 27 C++ classes implemented in `Source/PG_Framework/` — 15 full implementations (GI_GameFramework, GM_CoreGameMode, GS_CoreGameState, DA_GameTagRegistry, FL_GameUtilities, I_InterfaceLibrary, BPC_InventorySystem, SS_SaveManager, BPC_DamageReceptionSystem, SS_EnhancedInputManager, BPC_StateManager, DA_ItemData, UBPC_PlanarCapture, ABP_PlanarCaptureActor, USS_PlanarCaptureManager) + 2 utility (UPlanarCaptureCameraUtils, PlanarCaptureCommon) + 10 stubs (BPC_HealthSystem, BPC_StaminaSystem, BPC_StressSystem, BPC_MovementStateSystem, PC_CoreController, PS_CorePlayerState, BPC_HitReactionSystem, BPC_ShieldDefenseSystem, DA_EquipmentConfig, DA_StateGatingTable). See [`docs/checklists/cpp-blueprint-status.md`](docs/checklists/cpp-blueprint-status.md) for the full grid. All 147 Blueprint spec files exist in [`docs/blueprints/`](docs/blueprints/INDEX.md) with Manual Implementation Guides. --- @@ -31,6 +31,9 @@ | `T_` | Texture | `T_WatchFace_D` | | `M_` | Material | `M_DiegeticHUD_Glass` | | `ABP_` | Animation Blueprint | `ABP_PlayerBody` | +| `M_` | Master Material | `M_CaptureSurface_Master` | +| `MI_` | Material Instance | `MI_Mirror_Clean` | +| `MPC` | Material Parameter Collection | `MPC_CaptureSurface` | **Asset Folder Structure:** ``` @@ -76,6 +79,7 @@ Content/ 13. **Force Stack Pattern** — Death, cutscenes, void space push state onto a force stack; `RestorePreviousState()` pops back. 14. **Animation Notify Contract** — 14 named notifies required in montages for framework synchronization (see [`animation-catalog.md`](docs/architecture/animation-catalog.md)). 15. **Server-Authoritative Replication** — All state mutations gated by `HasAuthority()`. Clients request via `Server_` RPCs; servers validate and replicate via `RepNotify`. See [`multiplayer-networking.md`](docs/architecture/multiplayer-networking.md). +16. **Capture Is Local-Only** — Scene capture rendering (mirrors, portals, monitors) is always local to each client. Each client renders their own camera view. The World Subsystem evaluates surface priorities independently per client. Only surface active state replicates — never render targets. --- @@ -126,6 +130,8 @@ World Actors └─ implement I_Damageable (if destructible) └─ implement I_Persistable (if world-state must save) └─ BP_RoomAudioZone (acoustic zones) + └─ BP_PlanarCaptureActor → Mirror/Portal/Monitor/Horror/FakeWindow surfaces + └─ SS_PlanarCaptureManager (World Subsystem — auto-created per world) ``` **Communication Priority:** @@ -157,9 +163,10 @@ World Actors | 14 | Data Assets (content definitions) | 16 | | 15 | Enhanced Input System | 1 | | 16 | State Management | 2 | -| **Total** | | **135 numbered + 1 starter = 136 specs** | +| 17 | Planar Capture System | 12 | +| **Total** | | **147 numbered + 1 starter = 148 specs** | -> **Note:** The full spec index lives in [`docs/blueprints/INDEX.md`](docs/blueprints/INDEX.md). Each of the 135 numbered systems has a detailed blueprint specification with a Manual Implementation Guide. The design document below describes the *architecture and intent* of each system; the spec files define the *exact enum values, structs, variables, functions, and node-by-node implementation logic*. +> **Note:** The full spec index lives in [`docs/blueprints/INDEX.md`](docs/blueprints/INDEX.md). Each of the 147 numbered systems has a detailed blueprint specification with a Manual Implementation Guide. The design document below describes the *architecture and intent* of each system; the spec files define the *exact enum values, structs, variables, functions, and node-by-node implementation logic*. --- @@ -1066,7 +1073,169 @@ Defines all state gating rules in one Data Asset. Designers modify rules here wi --- -*These systems handle everything the player can do with the world: examining, opening, grabbing, hiding, climbing, and solving puzzles. The key principle is that each interactable object defines its own data — the Interaction System only detects and routes.* +# 2.6. Planar Capture System — Mirrors, Portals, Monitors & Horror Surfaces + +*Systems 136-147 form a unified rendering pipeline for reflective and transmissive surfaces. A global World Subsystem manages quality budgets across all captures, while a single master material with 9 parameter-driven layers handles all visual effects from clean mirrors to horror wrong-reflections.* + +--- + +### BPC_PlanarCapture — Actor Component (136) — on capture surface actors + +**C++ Status:** ✅ Full implementation — `Source/PG_Framework/Public/Capture/BPC_PlanarCapture.h` + +**Purpose:** +Core capture component managing `USceneCaptureComponent2D` lifecycle. Performs camera math per mode (mirror reflection, portal relative, fixed monitor), manages render target allocation, show/hide actor lists, and horror-feature actuation. + +**Responsibilities:** +- Own `USceneCaptureComponent2D` — create, configure, destroy +- Compute capture camera transform per mode (mirror/portal/monitor/fake window) +- Apply quality tier profiles (render target size, capture interval, show flags) +- Manage ShowOnly/Hidden actor lists for selective rendering +- Actuate horror features: wrong-reflection swap, delayed frame ring buffer +- Push MPC parameters each frame (steam, dirt, darkness, etc.) +- Accept scripted priority overrides from gameplay systems + +**Key Variables:** + +| Name | Type | Description | +|------|------|-------------| +| `CaptureMode` | EPlanarCaptureMode | Mirror / Portal / Monitor / HorrorMirror / HorrorPortal / FakeWindow | +| `QualityProfiles` | Array of FPlanarCaptureQualityProfile | 4 entries [Low, Medium, High, Hero] — RT size, FPS, feature toggles | +| `CaptureFOV` | Float | Capture camera FOV (default 90) | +| `CurrentQualityTier` | EPlanarCaptureQualityTier | Assigned by SS_PlanarCaptureManager | +| `ShowOnlyActors` | Array of TSoftObjectPtr | Captured exclusively (for horror swaps) | +| `WrongReflectionActor` | TSoftObjectPtr〈AActor〉 | Swapped into ShowOnly on horror trigger | +| `LinkedTargetSurface` | TSoftObjectPtr〈ABP_PlanarCaptureActor〉 | Portal destination | +| `FixedCameraActor` | TSoftObjectPtr〈AActor〉 | Monitor fixed camera reference | + +**Functions / Events:** + +| Name | Inputs | Outputs | What it does | +|------|--------|---------|--------------| +| `InitializeCapture` | — | EPlanarCaptureInitResult | Creates SceneCapture2D, allocates RT from pool | +| `ApplyQualityTier` | Tier: EPlanarCaptureQualityTier | — | Applies quality profile: resize RT, update interval, toggle features | +| `CaptureNow` | — | — | Bypasses tick interval for event-driven capture | +| `ActivateHorrorReflection` | — | — | Saves ShowOnly list, swaps to WrongReflectionActor | +| `DeactivateHorrorReflection` | — | — | Restores original ShowOnly list | +| `SetScriptedPriority` | Priority: Float (0–1) | — | Forces higher quality tier for scare moments | +| `ComputeCaptureCameraTransform` | ViewerTransform: FTransform | FTransform | Mode-specific camera placement | + +**Communicates With:** + +| Target System | Method | Why | +|---------------|--------|-----| +| SS_PlanarCaptureManager | Direct | Receives quality tier assignment | +| UPlanarCaptureCameraUtils | Static calls | Mirror/portal/oblique math | +| MPC_CaptureSurface | Direct | Pushes 10 scalar params per frame | + +--- + +### BP_PlanarCaptureActor — Actor (137) — base for all capture surfaces + +**C++ Status:** ✅ Full implementation — `Source/PG_Framework/Public/Capture/BP_PlanarCaptureActor.h` + +**Purpose:** +Placeable actor wrapping the BPC_PlanarCapture component. Owns the surface mesh, dynamic material instance, proximity trigger for quality scoring, and registers with the global manager. + +**Responsibilities:** +- Own and configure the surface mesh (plane/quad) and material +- Create dynamic material instance from M_CaptureSurface_Master +- Handle proximity overlap events for quality scoring boost +- Register/unregister with SS_PlanarCaptureManager on BeginPlay/EndPlay +- Expose Enable/Disable surface, SetCaptureMode, SetSurfaceMaterial APIs +- Support surface destruction (shatter mirror, break monitor) + +**Blueprint Children (139-143):** +- `BP_Mirror` — Standard mirror with dirt/steam/aging layers +- `BP_Portal` — Linked portal with teleport-on-overlap +- `BP_Monitor` — Security screen with fixed camera, scanlines, static noise +- `BP_HorrorMirror` — Horror mirror extending BP_Mirror with wrong-reflection, delayed frame, steam text reveal, scare events +- `BP_FakeWindow` — Architectural fake window with parallax, sublevel streaming, weather overlay + +--- + +### SS_PlanarCaptureManager — World Subsystem (138) + +**C++ Status:** ✅ Full implementation — `Source/PG_Framework/Public/Capture/SS_PlanarCaptureManager.h` + +**Purpose:** +Global budget manager — one instance per World. Scores every registered capture surface by distance, screen coverage, facing angle, and scripted priority. Assigns quality tiers within budget limits. Owns the shared render target pool. + +**Responsibilities:** +- Maintain registry of all active capture surfaces +- Each frame evaluation cycle (0.5s interval): score and assign quality tiers +- Enforce budget limits: MaxHeroSurfaces(1), MaxHighSurfaces(3), MaxMediumSurfaces(6) +- Manage render target pool — allocate, reuse, resize to minimize memory churn +- Support force-tier overrides for cutscenes/scare moments +- Expose global quality cap for lower-end hardware targets + +**Key Variables:** + +| Name | Type | Description | +|------|------|-------------| +| `GlobalQualityCap` | EPlanarCaptureQualityTier (default: High) | Maximum tier for any surface | +| `MaxHeroSurfaces` | int32 (1) | Max simultaneous Hero captures | +| `MaxHighSurfaces` | int32 (3) | Max simultaneous High captures | +| `MaxMediumSurfaces` | int32 (6) | Max simultaneous Medium captures | +| `MaxTotalRenderTargetMemoryMB` | float (128) | Total RT memory budget | +| `MaxCaptureDistance` | float (10000) | Distance at which surface goes Off | + +**Quality Tier Summary:** + +| Tier | RT Size | FPS | Shadows | Lumen | Post | Memory | +|------|---------|-----|---------|-------|------|--------| +| Off | — | 0 | — | — | — | 0 | +| Low | 256 | 4 | No | No | No | 256 KB | +| Medium | 512 | 15 | Dynamic | Optional | No | 1 MB | +| High | 1024 | 30 | Full | Yes | Minimal | 4 MB | +| Hero | 2048 | 60 | Full | Yes | Full | 16 MB | + +**Communicates With:** + +| Target System | Method | Why | +|---------------|--------|-----| +| All capture surface actors | Direct (registry) | Quality tier assignment | +| BPC_PlanarCapture | Direct (ApplyQualityTier) | Per-surface tier application | +| UTextureRenderTarget2D | Direct (create/release) | RT pool management | + +--- + +### PlanarCaptureCameraUtils — Static Math Library + +**C++ Status:** ✅ Full implementation — utility class + +**Purpose:** +Static BlueprintFunctionLibrary providing mirror reflection math, portal relative transform, oblique near-plane projection, screen coverage estimation, and visibility frustum checks. All pure functions, callable from Blueprint. + +**Key Functions:** + +| Name | Inputs | Outputs | What it does | +|------|--------|---------|--------------| +| `ComputeMirroredTransform` | ViewerTransform, MirrorPlaneTransform | FTransform | Reflects camera across mirror plane | +| `ComputePortalTransform` | ViewerTransform, SourceSurface, TargetSurface | FTransform | Maps viewer position to portal exit | +| `ComputeObliqueProjectionMatrix` | FOV, Aspect, Near, Far, ClipPlane, SurfaceTransform | FMatrix | Oblique near-plane for flush portal geometry | +| `ComputeScreenCoverage` | SurfaceBounds, ViewerTransform, FOV, Width, Height | Float (0–1) | Estimates screen-space coverage | +| `IsSurfaceVisibleToViewer` | SurfaceBounds, ViewerTransform, FOV, Aspect, Near, Far | Bool | Frustum visibility check | +| `ComputeCompositeScore` | ScreenCoverage, FacingAngle, Distance, MaxDistance, Priority | Float (0–1) | Quality scoring | + +--- + +### Content Assets (144-147) + +| # | System | Type | Purpose | +|---|--------|------|---------| +| 144 | `M_CaptureSurface_Master` | Master Material (Unlit) | 9-layer stack: RT sample, condensation UV distort, fresnel fade, dirt/scratch multiply, steam/fog lerp, steam emissive glow, text reveal mask, mirror darkness, wrong reflection crossfade | +| 145 | `MPC_CaptureSurface` | Material Parameter Collection | 10 global scalar params: SteamIntensity, DirtOpacity, CondensationFlow, DistortionAmplitude, MirrorDarkness, WrongReflectionBlend, TextRevealProgress, SteamEmissiveIntensity, DelayedReflectionBlend, SurfaceAge | +| 146 | `DA_PlanarCaptureProfile` | Data Asset | Per-surface config: default mode, quality overrides, actor lists, material | +| 147 | `MI_Mirror_Clean/Dirty/Steam/Horror` | Material Instances | 7 pre-configured MICs for common surface states | + +**Full Architecture Spec:** [`docs/architecture/planar-capture-system.md`](docs/architecture/planar-capture-system.md) + +**Game Examples:** [`docs/game/planar-capture-examples.md`](docs/game/planar-capture-examples.md) — 8 capture surfaces placed across Project Void levels + +--- + +# 3. Interaction & World Manipulation Systems ---