14441c000c
- Introduced comprehensive guide for setting up controller haptics and force feedback. - Detailed directory structure for haptic profiles and creation steps for DA_HapticProfile instances. - Included platform-specific configurations for Xbox and PS5 DualSense adaptive triggers. - Outlined wiring of BPC_HapticsController to various gameplay systems and events. - Provided accessibility integration options and testing checklist for haptic functionality.
259 lines
19 KiB
Markdown
259 lines
19 KiB
Markdown
# 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: 148 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 + 1 haptics game example = 193 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, 3 systems — includes BPC_HapticsController 148)
|
|
- **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).
|
|
- **Phase 18:** Haptics Controller — BPC_HapticsController (148) for GameplayTag-driven force feedback, DualSense adaptive triggers, heartbeat pulse. See [`docs/blueprints/12-settings/148_BPC_HapticsController.md`](docs/blueprints/12-settings/148_BPC_HapticsController.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)
|
|
- **Phase 18:** COMPLETE — Haptics Controller (148) blueprint spec created with full Manual Implementation Guide, DA_HapticProfile (121) enhanced, game example (`docs/game/haptics-example.md`) created. All developer docs and indexes updated.
|
|
- **Remaining:** Cross-reference pass across all 148 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 |