admin/UE5-Modular-Game-Framework
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9fd679fd5ba50127a877f7637b948f110a6d60ca
UE5-Modular-Game-Framework/CONTEXT.md
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

257 lines
18 KiB
Markdown
Raw Blame History

# UE5 Modular Game Framework — Project Context
## Purpose
Single Source of Truth for the Unreal Engine 5.5-5.7 Blueprint-based Modular Game Framework. This project converts the design document `UE5_Modular_Game_Framework.md` into 135 per-system Blueprint specification files across 16 directories, plus 5 enums, 5 Data Assets, and 5 architecture catalogs. Clean Slate refactoring complete — all 135 files renamed, renumbered, and verified. State Management + MetaSounds Audio architecture phases complete.
## Tech Stack
- **Engine:** Unreal Engine 5.5 - 5.7
- **Scripting:** Blueprint-Only (no C++)
- **Locomotion:** GASP (Ground Animation Strafing Platform) — read-only, extended via notifies
- **Input:** Enhanced Input System (UE5) — Input Actions + Input Mapping Contexts with priority-based context switching
- **Assets:** UPrimaryDataAsset for all content definitions
- **State:** [`BPC_StateManager`](docs/architecture/bpc-statemanager.md) — Central state authority (42 exclusive action states, 18 overlay states). Systems query `IsActionPermitted(Tag)` instead of checking other systems directly.
- **Animation:** GASP Motion Matching + overlay notifies. Full catalog in [`docs/architecture/animation-catalog.md`](docs/architecture/animation-catalog.md)
- **Audio:** 150+ sound triggers + 14-surface material table. Full catalog in [`docs/architecture/sound-catalog.md`](docs/architecture/sound-catalog.md)
- **Networking:** Server-authoritative replication model. Full architecture in [`docs/architecture/multiplayer-networking.md`](docs/architecture/multiplayer-networking.md)
- **BP Limitations:** Catalog of C++-only UE5 functions + 100% Blueprint workarounds. See [`docs/architecture/blueprint-limitations-workarounds.md`](docs/architecture/blueprint-limitations-workarounds.md)
## Directory Structure
```
Content/
Framework/
Core/
Player/
Interaction/
Inventory/
Weapons/
UI/
Narrative/
Save/
Adaptive/
AI/
Audio/ # MetaSounds Audio System (NEW)
MS_MasterBus.uasset
MS_SFXBus.uasset
MS_AmbientBus.uasset
MS_MusicBus.uasset
MS_DialogueBus.uasset
SS_AudioManager.uasset
DA_AudioSettings.uasset
RoomPresets/
DA_RoomAcousticPreset.uasset
DA_RP_SmallRoom/Outdoor/Cave/etc.uasset
BP_RoomAudioZone.uasset
Input/ # Enhanced Input assets (NEW)
Actions/ # IA_* Input Action assets
Contexts/ # IMC_* Input Mapping Context assets
DataTables/ # Gameplay Tag Data Tables (NEW — 11 per-category CSV files)
DT_Tags_Player.csv
DT_Tags_Interaction.csv
DT_Tags_Item.csv
DT_Tags_Narrative.csv
DT_Tags_AI.csv
DT_Tags_Save.csv
DT_Tags_Environment.csv
DT_Tags_Combat.csv
DT_Tags_State.csv
DT_Tags_Audio.csv
DT_Tags_Achievement.csv
Achievements/
Settings/
State/ # State Management assets (NEW)
E_PlayerActionState.uasset # 42 exclusive action states
E_OverlayState.uasset # 18 upper-body overlay states
E_PlayerVitalSignals.uasset # 5 vital signal tiers
E_ActionRequestResult.uasset # 8 request result codes
S_StateChangeRequest.uasset # State change request struct
S_StateGatingRule.uasset # Gating rule struct
S_ActionPermissionResult.uasset # Permission result struct
DA_StateGatingTable.uasset # All gating rules (37 action rules)
BPC_StateManager.uasset # Central state authority component
Capture/ # Planar Capture assets (NEW — Phase 17)
BP_Mirror.uasset # Standard mirror surface
BP_Portal.uasset # Portal surface with linked target
BP_Monitor.uasset # Security camera monitor
BP_HorrorMirror.uasset # Horror mirror with wrong reflection
BP_FakeWindow.uasset # Architectural fake window
M_CaptureSurface_Master.uasset # Master unlit material (9-layer)
MPC_CaptureSurface.uasset # Global MPC (10 scalar params)
DA_PlanarCaptureProfile.uasset # Per-surface capture config
MI_Mirror_Clean.uasset # Material instances
MI_Mirror_Dirty.uasset
MI_Mirror_Steam.uasset
MI_Mirror_Horror.uasset
MI_Portal_Standard.uasset
MI_Monitor_Security.uasset
MI_FakeWindow_Interior.uasset
docs/
blueprints/
INDEX.md # Master Blueprint Index — all 135 files + folder structure
TEMPLATE.md # Blueprint Spec template format
AUDIT_REPORT.md # Clean Slate audit (all ✅)
01-core/ # Foundation systems (7 files, 01-07)
02-player/ # Player State & Embodiment (8 files, 08-15)
03-interaction/ # Interaction & World Manipulation (8 files, 16-23)
04-inventory/ # Inventory, Items & Collectibles (11 files, 24-34)
05-saveload/ # Save, Load, Persistence & Death Loop (9 files, 35-43)
06-ui/ # UI, Menus & Diegetic Presentation (14 files, 44-57)
07-narrative/ # Narrative, Dialogue, Objective & Choice (11 files, 58-68)
08-weapons/ # Weapon, Equipment & Damage (11 files, 69-79)
09-ai/ # AI, Perception & Encounters (9 files, 80-88)
10-adaptive/ # Adaptive Environment, Atmosphere & Scare (15 files, 89-101, 132-133)
11-meta/ # Achievements, Progression & Meta (2 files, 102-103)
12-settings/ # Settings, Accessibility & Platform (2 files, 104-105)
13-polish/ # Tutorial, Loading, Credits, Debug (9 files, 106-114)
14-data-assets/ # Data Asset definitions (16 files, 115-127, 129, 134-135)
15-input/ # Enhanced Input System (1 file, 128)
16-state/ # State Management (2 files, 130-131)
17-capture/ # Planar Capture System (12 files, 136-147)
developer/ # Developer Reference Docs (NEW)
INDEX.md # Master developer docs index (12 docs)
architecture-overview.md # Framework-wide architecture walkthrough
implementation-patterns.md # Common UE5 Blueprint patterns used
project-setup-migration.md # Project setup & migration guide (NEW — Project Settings, plugins, init sequence)
01-core-foundation.md # Foundation systems explained
02-player-systems.md # Player state & embodiment explained
03-interaction-systems.md # Interaction & world manipulation explained
04-inventory-systems.md # Inventory, items & collectibles explained
05-saveload-systems.md # Save/load, persistence, death loop explained
06-ui-systems.md # UI, menus & diegetic presentation explained
07-narrative-systems.md # Narrative, dialogue, objectives explained
08-weapons-systems.md # Weapons, equipment & damage explained
09-ai-systems.md # AI, perception & encounters explained
10-adaptive-systems.md # Adaptive environment & atmosphere explained
11-16-systems.md # Meta, Settings, Polish, Data Assets, Input, State explained
architecture/ # Architecture & Design Documents (9 files)
bpc-statemanager.md # BPC_StateManager full spec + Chooser Table Audit
metasounds-audio-system.md # MetaSounds audio architecture (mix buses, room zones, settings)
animation-catalog.md # Animation requirements for all 135 systems
sound-catalog.md # Sound/audio requirements for all 135 systems
enhanced-input-system.md # Enhanced Input System architecture
hud-overview.md # HUD system architecture — 14 widgets, wiring, integration points
multiplayer-networking.md # Multiplayer networking architecture — authority model, RPCs, prediction
blueprint-limitations-workarounds.md # UE5 C++-only functions + 100% Blueprint workarounds (NEW)
planar-capture-system.md # Planar Capture System — mirrors, portals, monitors, horror surfaces (Phase 17)
CLEAN_SLATE_PLAN.md # Clean slate refactoring plan
reports/ # Condensed audit reports
blueprint_condensed_summary.md # ASK agent audit of all 129 files
checklists/ # Implementation checklists
clean-slate-refactor.md
enhanced-input-system.md
bpc-statemanager.md # NEW — State Manager implementation checklist
```
**Total: 147 numbered Blueprint files + 5 enums + 5 Data Assets + 11 Data Table CSVs + TEMPLATE.md + AUDIT_REPORT.md + INDEX.md + 13 developer docs + 9 architecture docs + 1 audit report = 192 files in 20 directory groups**
## Naming Conventions
| Prefix | Type |
|--------|------|
| `BP_` | Blueprint Actor |
| `BPC_` | Blueprint Component |
| `WBP_` | Widget Blueprint |
| `GI_` | Game Instance |
| `GM_` | Game Mode |
| `GS_` | Game State |
| `PC_` | Player Controller |
| `PS_` | Player State |
| `DA_` | Data Asset |
| `E_` | Enum |
| `S_` | Struct |
| `I_` | Interface |
| `FL_` | Function Library |
| `SS_` | Game Instance Subsystem |
| `AI_` | AI Controller |
| `BB_` | Blackboard |
## Architectural Principles (from source doc)
1. **Single Responsibility** — One concern per component
2. **Interface-First Communication** — Systems talk via I_ interfaces or dispatchers
3. **Data Owns Itself** — Objects carry their own data
4. **UI Reads, Never Writes** — Widgets never own game logic
5. **No Hardcoded Names** — All config in Data Assets / Gameplay Tags
6. **Save-System Aware** — I_Persistable for anything that saves
7. **Tag-Driven Filtering** — Gameplay Tags everywhere, no string comparisons
8. **Manager vs Worker Split** — Subsystems coordinate, Components execute
9. **GASP Is Sacred** — Extend via notifies, don't touch internals
10. **Fail Gracefully** — Interface calls check validity before execution
11. **Central State Authority** — [`BPC_StateManager`](docs/architecture/bpc-statemanager.md) is the single source of truth for "what can the player do right now?" Systems call `IsActionPermitted(Tag)` instead of checking other systems' states directly.
12. **State Gating via Data Asset** — All gating rules in `DA_StateGatingTable`. Designers modify rules without touching blueprints.
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).
## Build Order (Dependency-Safe)
- **Phase 0:** Foundation + Input (01-core, 15-input — 8 systems)
- **Phase 1:** Player Core (02-player, 8 systems)
- **Phase 2:** Interaction (03-interaction, 8 systems)
- **Phase 3:** Inventory (04-inventory, 11 systems)
- **Phase 4:** Save/Load (05-saveload, 9 systems)
- **Phase 5:** UI Layer (06-ui, 14 systems)
- **Phase 6:** Narrative (07-narrative, 11 systems)
- **Phase 7:** Weapons & Combat (08-weapons, 11 systems)
- **Phase 8:** AI (09-ai, 9 systems)
- **Phase 9:** Adaptive & Atmosphere (10-adaptive, 15 systems)
- **Phase 10:** Data Assets (14-data-assets, 16 systems)
- **Phase 11:** Meta/Progression (11-meta, 2 systems)
- **Phase 12:** Settings/Platform (12-settings, 2 systems)
- **Phase 13:** Polish (13-polish, 9 systems)
- **Phase 14:** State Management (BPC_StateManager + 4 enums + 3 structs + DA_StateGatingTable — 130, 131)
- **Phase 15:** MetaSounds Audio (SS_AudioManager + BP_RoomAudioZone + DA_AudioSettings + DA_RoomAcousticPreset — 132-135)
- **Phase 16:** Multiplayer Networking — All systems updated with `HasAuthority()` gates, `Server_` RPCs, `RepNotify` handlers, and client prediction patterns. See [`docs/architecture/multiplayer-networking.md`](docs/architecture/multiplayer-networking.md).
- **Phase 17:** Planar Capture System — Mirrors, portals, monitors, horror surfaces. C++ core (136-138) + Blueprint actors (139-143) + Material/MPC (144-145) + Data Assets (146-147). See [`docs/architecture/planar-capture-system.md`](docs/architecture/planar-capture-system.md).
## Key Communication Rules
1. Gameplay Tags + Subsystem lookup (global, decoupled)
2. Interface calls (local, type-safe)
3. Event Dispatchers (one-to-many, fire-and-forget)
4. Direct reference (only within tightly-coupled pairs)
## Enhanced Input Conventions
- **Input Actions:** Prefix `IA_`, one per gameplay action (e.g., `IA_Move`, `IA_Reload`).
- **Input Mapping Contexts:** Prefix `IMC_`, groups related actions (e.g., `IMC_Default`, `IMC_Hiding`).
- **Context Priority Ladder:** Default(0) < Hiding(5) < WristwatchUI(10) < Inspection(20) < UI(100).
- **Input Manager:** `SS_EnhancedInputManager` (Game Instance Subsystem) is the sole authority for Push/Pop context, key rebinding, and input mode changes. Gameplay systems query input state through it — never through raw Enhanced Input calls.
- **Platform Profiles:** `DA_InputMappingProfile` Data Asset defines all bindings per platform (PC, Xbox, PS5). No hardcoded key references anywhere.
- **Input Mode Coordination:** `SS_EnhancedInputManager` syncs cursor visibility and input blocking with `SS_UIManager` on menu open/close.
## Conventions for Blueprint Spec Files
Each file in `docs/blueprints/` follows the template defined in [`docs/blueprints/TEMPLATE.md`](docs/blueprints/TEMPLATE.md) (v2.0). Files define: Enums, Structs, Variables, Functions, Event Dispatchers, Flow Diagram, Communication Matrix, Reuse Notes, **Manual Implementation Guide** (node-by-node logic for human implementers), and Build Checklist.
## Documentation Update Protocol (CRITICAL RULE)
**Any change to the framework MUST also update these files in the same commit:**
1. [`docs/blueprints/INDEX.md`](docs/blueprints/INDEX.md) — add/update the file entry in the master index
2. [`docs/developer/INDEX.md`](docs/developer/INDEX.md) — if the change affects how a system works internally (data flow, state machines, integration points)
3. The relevant [`docs/developer/`](docs/developer/) category document — if the change modifies a system's behavior, dependencies, or implementation pattern
4. [`docs/architecture/animation-catalog.md`](docs/architecture/animation-catalog.md) — if the change adds/modifies animation requirements
5. [`docs/architecture/sound-catalog.md`](docs/architecture/sound-catalog.md) — if the change adds/modifies audio triggers or surfaces
6. [`docs/architecture/blueprint-limitations-workarounds.md`](docs/architecture/blueprint-limitations-workarounds.md) — if the change uses a new C++-only UE5 function that needs a Blueprint workaround
No PR is accepted without these files being current. This ensures the animator, sound designer, developers, and all team members always have an up-to-date reference.
## MetaSounds Audio Conventions
- **Single Entry Point:** All audio playback routes through [`SS_AudioManager`](docs/architecture/metasounds-audio-system.md) Game Instance Subsystem. Never call `UGameplayStatics::PlaySound*` directly.
- **Mix Buses:** 4 categories — SFX, Ambience, Music, Dialogue → Master Bus. Each has its own MetaSound patch.
- **Room Zones:** `BP_RoomAudioZone` trigger volumes automatically switch reverb/occlusion via `SS_AudioManager.SetRoomPreset()`.
- **Settings Integration:** Volume sliders in `WBP_SettingsMenu` call `SS_AudioManager.SetBusVolume(Category, Volume)` which writes to the bus MetaSound patch.
- **Gameplay Parameters:** Heart rate, stress, fear, music intensity pushed as MetaSound float parameters from gameplay systems — not hardcoded in audio assets.
- **Deprecated:** `BPC_AudioAtmosphereController` (95) is phased out in favor of `SS_AudioManager`.
- **Full Spec:** See [`docs/architecture/metasounds-audio-system.md`](docs/architecture/metasounds-audio-system.md)
## Multiplayer Networking Conventions
- **Authority Model:** Server-authoritative. All state mutations (`ApplyDamage`, `AddItem`, `SetDoorState`) execute on the server with `HasAuthority()` gate. Clients request state changes via `Server_` RPCs.
- **RPC Naming:** `Server_` (Client→Server), `Multicast_` (Server→All Clients), `Client_` (Server→Specific Client). All reliable unless marked otherwise.
- **RepNotify Pattern:** All replicated variables use `RepNotify` with `OnRep_` handlers that fire the same event dispatchers single-player code already binds to. UI widgets, audio, and effects need zero changes for multiplayer.
- **Client Prediction:** Cosmetic effects (muzzle flash, recoil, camera shake) play immediately on client. State values (health, ammo, stamina) are predicted but corrected via `RepNotify` if server disagrees.
- **Inventory Authority:** Server validates all add/remove/transfer operations against slot space, weight capacity, and stack limits. Client predicts UI; server corrects via `OnRep_Slots`.
- **AI Server-Only:** Behavior trees run on server. Position/rotation/animations replicate via standard Actor replication. Perception events replicate for client awareness indicators.
- **UI Local Only:** All `WBP_*` widgets are local per-client. They bind to replicated dispatchers — no networking code in widgets.
- **Anti-Cheat:** Server validates all state-changing RPCs. Never trust client-provided values (damage amount, item quantity, target actor). Re-validate conditions server-side.
- **Full Spec:** See [`docs/architecture/multiplayer-networking.md`](docs/architecture/multiplayer-networking.md)
## Clean Slate Refactoring Status
- **Branch:** `refactor/clean-slate`
- **Phases 1-7:** COMPLETE — all 127 files created, renamed, reorganized, renumbered
- **Phase 8-13:** COMPLETE — AUDIT_REPORT updated, CONTEXT.md updated, verification, final commit
- **Phase 14-15:** COMPLETE — State Management (130-131) + MetaSounds Audio (132-135) blueprint specs created
- **Phase 16:** IN PROGRESS — Multiplayer Networking: all 135 blueprint specs being updated with replication stubs, RPC definitions, and server-authoritative patterns. Developer docs updated. Architecture doc created at [`docs/architecture/multiplayer-networking.md`](docs/architecture/multiplayer-networking.md)
- **Remaining:** Cross-reference pass across all 147 files; deprecated BPC_AudioAtmosphereController (95) references to update; Planar Capture System (Phase 17) C++ written, blueprint specs created, pending UE5 editor compile and BP child creation
Reference in New Issue View Git Blame Copy Permalink