admin/UE5-Modular-Game-Framework
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
08fe41d2966832472e781112f7cfbe4bbd2e2416
UE5-Modular-Game-Framework/CONTEXT.md
admin a92b9f4726 Upload files to "/" 
add context
2026-05-19 10:15:05 +00:00

12 KiB
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 — 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)
 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 + 6 architecture docs + 1 audit report = 153 files in 17 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 3 files in the same commit:

  1. docs/blueprints/INDEX.md — add/update the file entry in the master index
  2. docs/architecture/animation-catalog.md — if the change adds/modifies animation requirements
  3. docs/architecture/sound-catalog.md — if the change adds/modifies audio triggers or surfaces

No PR is accepted without these 3 files being current. This ensures the animator, sound designer, 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