admin/UE5-Modular-Game-Framework
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0852386168ae2bcbaa02fcf80c974dd9d0f15e01
UE5-Modular-Game-Framework/CONTEXT.md

17 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
  • Networking: Server-authoritative replication model. Full architecture in docs/architecture/multiplayer-networking.md
  • BP Limitations: Catalog of C++-only UE5 functions + 100% Blueprint workarounds. See 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 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).
  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.

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.

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 (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 — 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
  6. 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 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

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

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
  • Remaining: Cross-reference pass across all 135 files; deprecated BPC_AudioAtmosphereController (95) references to update