UE5-Modular-Game-Framework/CONTEXT.md

# 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

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 (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 (8 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)
   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 + 11 Data Table CSVs + TEMPLATE.md + AUDIT_REPORT.md + INDEX.md + 12 developer docs + 8 architecture docs + 1 audit report = 178 files in 19 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).

## 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 135 files; deprecated BPC_AudioAtmosphereController (95) references to update