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 — 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
• Audio: 150+ sound triggers + 14-surface material table. Full catalog in 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 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).

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 — add/update the file entry in the master index
2. docs/developer/INDEX.md — if the change affects how a system works internally (data flow, state machines, integration points)
3. The relevant docs/developer/ category document — if the change modifies a system's behavior, dependencies, or implementation pattern
4. docs/architecture/animation-catalog.md — if the change adds/modifies animation requirements
5. 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 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

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