b2b6e1e7c7
- Created detailed documentation for systems 102-135 covering achievements, settings, polish, data assets, input management, and state management. - Added INDEX.md for easy navigation of developer reference materials. - Introduced architecture-overview.md to provide a high-level understanding of the framework's structure and communication methods. - Compiled implementation-patterns.md to outline common UE5 Blueprint patterns for consistent development practices.
207 lines
13 KiB
Markdown
207 lines
13 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)
|
|
|
|
## 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
|
|
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
|
|
|
|
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)
|
|
developer/ # Developer Reference Docs (NEW)
|
|
INDEX.md # Master developer docs index (11 docs)
|
|
architecture-overview.md # Framework-wide architecture walkthrough
|
|
implementation-patterns.md # Common UE5 Blueprint patterns used
|
|
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 (6 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
|
|
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: 135 numbered Blueprint files + 5 enums + 5 Data Assets + TEMPLATE.md + AUDIT_REPORT.md + INDEX.md + 11 developer docs + 6 architecture docs + 1 audit report = 164 files in 18 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)).
|
|
|
|
## 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:** Integration Pass — All systems updated to query `BPC_StateManager.IsActionPermitted()` instead of direct state checks. All audio calls routed through `SS_AudioManager` instead of `UGameplayStatics::PlaySound*`.
|
|
|
|
## 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`. Files define: Enums, Structs, Variables, Functions, Event Dispatchers, Flow Diagram, Communication Matrix, and Reuse Notes.
|
|
|
|
## 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
|
|
|
|
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)
|
|
|
|
## 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
|
|
- **Remaining:** Cross-reference pass across all 135 files; deprecated BPC_AudioAtmosphereController (95) references to update |