Upload files to "/"

add context

CONTEXT.md

@@ -0,0 +1,190 @@
+# 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)
+ 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`](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 3 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/architecture/animation-catalog.md`](docs/architecture/animation-catalog.md) — if the change adds/modifies animation requirements
+3. [`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 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`](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