From ccd1872e59080f6f5debc5b0a4d1cfd1e07a2cef Mon Sep 17 00:00:00 2001
From: Lefteris Notas <lefteris@hugintech.com>
Date: Thu, 21 May 2026 18:41:43 +0300
Subject: [PATCH] Update documentation for player, inventory, and weapon
 systems

- Added C++ status updates for player systems (02-player-systems.md) indicating the implementation status of systems 08-11 and their relation to BPC_StateManager.
- Enhanced inventory systems documentation (04-inventory-systems.md) with C++ status for BPC_InventorySystem and DA_ItemData, clarifying their implementation details.
- Updated weapons systems documentation (08-weapons-systems.md) to reflect the C++ implementation status of BPC_DamageReceptionSystem and stubs for hit reaction and shield defense systems.
---
 UE5_Modular_Game_Framework.md          | 601 ++++++++++++++++++-------
 docs/developer/02-player-systems.md    |   2 +
 docs/developer/04-inventory-systems.md |   2 +
 docs/developer/08-weapons-systems.md   |   2 +
 4 files changed, 434 insertions(+), 173 deletions(-)

diff --git a/UE5_Modular_Game_Framework.md b/UE5_Modular_Game_Framework.md
index c650ad6..e25777b 100644
--- a/UE5_Modular_Game_Framework.md
+++ b/UE5_Modular_Game_Framework.md
@@ -1,6 +1,8 @@
 # Reusable UE5 Modular Game Framework
 ### A Complete Blueprint Architecture for First-Person Narrative Horror (and Beyond)
 
+> **C++ Status (2026-05-21):** 22 C++ classes implemented in `Source/PG_Framework/` — 12 full implementations (GI_GameFramework, GM_CoreGameMode, GS_CoreGameState, DA_GameTagRegistry, FL_GameUtilities, I_InterfaceLibrary, BPC_InventorySystem, SS_SaveManager, BPC_DamageReceptionSystem, SS_EnhancedInputManager, BPC_StateManager, DA_ItemData) + 10 stubs (BPC_HealthSystem, BPC_StaminaSystem, BPC_StressSystem, BPC_MovementStateSystem, PC_CoreController, PS_CorePlayerState, BPC_HitReactionSystem, BPC_ShieldDefenseSystem, DA_EquipmentConfig, DA_StateGatingTable). See [`docs/checklists/cpp-blueprint-status.md`](docs/checklists/cpp-blueprint-status.md) for the full grid. All 135 Blueprint spec files exist in [`docs/blueprints/`](docs/blueprints/INDEX.md) with Manual Implementation Guides.
+
 ---
 
 ## Naming Conventions
@@ -20,7 +22,7 @@
 | `S_` | Struct | `S_ItemData`, `S_NarrativeFlag` |
 | `I_` | Interface | `I_Interactable`, `I_Damageable` |
 | `FL_` | Function Library | `FL_GameUtilities`, `FL_MathHelpers` |
-| `SS_` | Game Instance Subsystem | `SS_SaveSystem`, `SS_AchievementSystem` |
+| `SS_` | Game Instance Subsystem | `SS_SaveManager`, `SS_AchievementSystem` |
 | `AI_` | AI Blueprint | `AI_PatrolAgent`, `AI_EncounterDirector` |
 | `BTT_` | Behaviour Tree Task | `BTT_Investigate`, `BTT_Chase` |
 | `BTS_` | Behaviour Tree Service | `BTS_PerceptionUpdate` |
@@ -64,11 +66,16 @@ Content/
 3. **Data Owns Itself** — Interactable objects carry their own interaction data (via Data Asset or struct). The Interaction System reads it; it does not define it.
 4. **UI Reads, Never Writes** — Widget Blueprints consume data from systems. They never own game logic or write game state directly.
 5. **No Hardcoded Names** — All game-specific configuration lives in Data Assets, Gameplay Tags, or config structs. Nothing is hardcoded in Blueprint logic.
-6. **Save-System Aware** — Any component that needs to persist state must implement the `I_Persistable` interface and register with `SS_SaveSystem`.
+6. **Save-System Aware** — Any component that needs to persist state must implement the `I_Persistable` interface and register with `SS_SaveManager`.
 7. **Tag-Driven Filtering** — Use Gameplay Tags for categorisation, filtering, and condition checks everywhere. Never use string comparisons or hardcoded booleans for state.
 8. **Manager vs Worker Split** — Managers (subsystems, game instance) coordinate. Workers (components on actors) execute. Managers do not tick actors. Workers do not manage global state.
 9. **GASP Is Sacred** — Do not touch GASP locomotion internals. Layer all new systems around GASP via its extension points, Smart Object hooks, and animation notify support.
 10. **Fail Gracefully** — All interface calls check validity before execution. Missing components should log a warning, not crash.
+11. **Central State Authority** — `BPC_StateManager` (130) 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` (131). 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).
 
 ---
 
@@ -76,10 +83,12 @@ Content/
 
 ```
 GI_GameFramework
-  └─ owns ─► SS_SaveSystem
+  └─ owns ─► SS_SaveManager
   └─ owns ─► SS_AchievementSystem
   └─ owns ─► SS_SettingsSystem
-  └─ owns ─► SS_AnalyticsSystem (optional)
+  └─ owns ─► SS_EnhancedInputManager
+  └─ owns ─► SS_AudioManager
+  └─ owns ─► SS_UIManager
 
 GM_CoreGameMode
   └─ spawns ─► PC_CoreController
@@ -87,13 +96,13 @@ GM_CoreGameMode
   └─ routes ─► narrative phase changes
 
 PC_CoreController
-  └─ owns ─► BPC_InteractionSystem (detect + execute)
-  └─ owns ─► BPC_ActiveItemSystem
+  └─ reads ─► SS_EnhancedInputManager (input contexts)
   └─ reads ─► BPC_HealthSystem (on Pawn)
   └─ reads ─► BPC_StaminaSystem (on Pawn)
   └─ reads ─► BPC_StressSystem (on Pawn)
 
 PlayerPawn (GASP base)
+  └─ BPC_StateManager          ← CENTRAL STATE AUTHORITY
   └─ BPC_HealthSystem
   └─ BPC_StaminaSystem
   └─ BPC_StressSystem
@@ -102,24 +111,21 @@ PlayerPawn (GASP base)
   └─ BPC_CameraStateLayer
   └─ BPC_PlayerMetricsTracker
   └─ BPC_InventorySystem
-  └─ BPC_EquipmentSlotSystem
   └─ BPC_DamageReceptionSystem
+  └─ BPC_ShieldDefenseSystem
+  └─ BPC_HitReactionSystem
   └─ BPC_HidingSystem
+  └─ BPC_InteractionDetector
+  └─ BPC_ActiveItemSystem
+  └─ BPC_EquipmentSlotSystem
+  └─ BPC_ConsumableSystem
+  └─ BPC_KeyItemSystem
 
 World Actors
   └─ implement I_Interactable (define their own data)
   └─ implement I_Damageable (if destructible)
   └─ implement I_Persistable (if world-state must save)
-  └─ BPC_AdaptiveEnvironmentReactor (if adaptive)
-
-UI Layer
-  └─ WBP_HUDController (root HUD, reads everything via dispatcher/interface)
-  └─ WBP_DiegeticHUDFrame (swap per game skin)
-  └─ WBP_InventoryMenu
-  └─ WBP_JournalViewer
-  └─ WBP_DialogueDisplay
-  └─ WBP_ObjectiveDisplay
-  └─ WBP_PauseMenu / WBP_MainMenu / WBP_SettingsMenu
+  └─ BP_RoomAudioZone (acoustic zones)
 ```
 
 **Communication Priority:**
@@ -134,20 +140,26 @@ UI Layer
 
 | # | Category | Systems Count |
 |---|----------|--------------|
-| 1 | Core Framework Systems | 8 |
-| 2 | Player State & Embodiment | 9 |
-| 3 | Interaction & World Manipulation | 11 |
-| 4 | Inventory, Items & Collectibles | 12 |
-| 5 | Weapon, Equipment & Damage | 10 |
-| 6 | UI, Menus & Diegetic Presentation | 13 |
+| 0 | Project Setup & Starter | 1 |
+| 1 | Core Framework Systems | 7 |
+| 2 | Player State & Embodiment | 8 (+2 controller/state stubs) |
+| 3 | Interaction & World Manipulation | 8 |
+| 4 | Inventory, Items & Collectibles | 11 |
+| 5 | Save, Load, Persistence & Death Loop | 9 |
+| 6 | UI, Menus & Diegetic Presentation | 14 |
 | 7 | Narrative, Dialogue, Objective & Choice | 11 |
-| 8 | Save, Load, Persistence & Death Loop | 11 |
-| 9 | Adaptive Environment, Atmosphere & Scare | 9 |
-| 10 | AI, Perception & Encounters | 9 |
-| 11 | Achievements, Progression & Meta | 10 |
-| 12 | Settings, Accessibility & Platform | 9 |
-| 13 | Editor / Data / Content Authoring | 9 |
-| **Total** | | **~131 systems** |
+| 8 | Weapons, Equipment & Damage | 11 |
+| 9 | AI, Perception & Encounters | 9 |
+| 10 | Adaptive Environment, Atmosphere & Scare | 13 + 2 Audio = 15 |
+| 11 | Achievements, Progression & Meta | 2 |
+| 12 | Settings, Accessibility & Platform | 2 |
+| 13 | Polish & Support Systems | 9 |
+| 14 | Data Assets (content definitions) | 16 |
+| 15 | Enhanced Input System | 1 |
+| 16 | State Management | 2 |
+| **Total** | | **135 numbered + 1 starter = 136 specs** |
+
+> **Note:** The full spec index lives in [`docs/blueprints/INDEX.md`](docs/blueprints/INDEX.md). Each of the 135 numbered systems has a detailed blueprint specification with a Manual Implementation Guide. The design document below describes the *architecture and intent* of each system; the spec files define the *exact enum values, structs, variables, functions, and node-by-node implementation logic*.
 
 ---
 
@@ -223,7 +235,7 @@ The single persistent object that lives for the entire application session. It o
   └─► InitPlatformServices()
   └─► Create all SS_ Subsystems
   └─► Load persistent settings (SS_SettingsSystem)
-  └─► Check for existing save data (SS_SaveSystem)
+  └─► Check for existing save data (SS_SaveManager)
   └─► SetGamePhase(MainMenu)
   └─► Broadcast OnGamePhaseChanged
 ```
@@ -233,10 +245,12 @@ Replace `E_PlatformType` routing with new platform entries. Add new subsystems t
 
 ---
 
-### SS_SaveSystem — GameInstance Subsystem
+### SS_SaveManager — GameInstance Subsystem (35)
+
+**C++ Status:** ✅ Full implementation — `Source/PG_Framework/Public/Save/SS_SaveManager.h`
 
 **Purpose:**
-Handles all serialisation and deserialisation of game state to disk. Supports multiple save slots, checkpoint saves, hard saves, and world object persistence.
+Handles all serialisation and deserialisation of game state to disk. Supports multiple save slots, checkpoint saves, hard saves, and world object persistence. C++ uses `FArchive` for direct binary serialization — far more powerful than Blueprint `SaveGame`/`LoadGame` nodes.
 
 **Responsibilities:**
 - Write and read `USaveGame`-derived objects per slot
@@ -346,15 +360,18 @@ Persists and distributes audio, graphics, controls, and accessibility settings a
 
 ---
 
-### GI_GameTagRegistry — Data Asset (Gameplay Tag Table)
+### DA_GameTagRegistry — Primary Data Asset (01)
+
+**C++ Status:** ✅ Full implementation — `Source/PG_Framework/Public/Core/DA_GameTagRegistry.h`
 
 **Purpose:**
-Centralises all Gameplay Tag definitions used across the framework in a single `.ini`-sourced asset.
+Centralises all Gameplay Tag definitions used across the framework. Wraps `UGameplayTagsManager` APIs directly in C++, bypassing the Data Table proxy workaround required in Blueprint. The Data Table array (`TagDataTables` — 11 entries) is maintained for Blueprint implementations.
 
 **Responsibilities:**
 - Define all framework-level tags (Player.State.*, Interaction.Type.*, Narrative.Flag.*, etc.)
 - Provide the canonical tag namespace so no system uses raw FName comparisons
 - Document each tag's meaning inline via comments in the ini
+- Provide `GetAllRegisteredTags()`, `ValidateTag()`, `RequestTag()`, `ExportTagNamespace()` in C++ (BlueprintCallable)
 
 **Tag Namespace Structure:**
 ```
@@ -445,7 +462,38 @@ This library ships verbatim to every project. Add project-specific helpers in a
 | `I_ScareTarget` | `OnScareEventFired(ScareTag)` | Actors that respond to scare events |
 
 **Reuse Notes:**
-All interfaces are project-agnostic. Add project-specific interfaces in a `I_Project*` namespace.
+All interfaces are project-agnostic. Add project-specific interfaces in a `I_Project*` namespace. All 9 interfaces are defined in C++ (`Source/PG_Framework/Public/Core/I_InterfaceLibrary.h`) with `BlueprintNativeEvent` — implement them in Blueprint actors.
+
+---
+
+### SS_EnhancedInputManager — GameInstance Subsystem (128)
+
+**C++ Status:** ✅ Full implementation — `Source/PG_Framework/Public/Input/SS_EnhancedInputManager.h`
+
+**Purpose:**
+Sole authority for Push/Pop input context, key rebinding, and input mode changes. All gameplay systems query input state through this manager — never through raw Enhanced Input calls.
+
+**Responsibilities:**
+- Manage a priority-ordered context stack (Default(0) < Hiding(5) < WristwatchUI(10) < Inspection(20) < UI(100))
+- Push/Pop `UInputMappingContext` assets with duplicate protection
+- Coordinate input mode (Game/UI) with `SS_UIManager` — cursor visibility, input blocking
+- Handle key rebinding requests and persist via `SS_SettingsSystem`
+- Provide `IsActionPressed()`, `GetActionValue()` queries for gameplay systems
+
+**Key Variables:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `ContextStack` | Array of FInputContextEntry | Ordered by priority, highest at top |
+| `DefaultContexts` | Array of UInputMappingContext | Loaded on Initialize |
+| `bCurrentUIMode` | Bool | UI mode active |
+
+**Input Assets to Create (in UE5 editor):**
+- 22 `IA_*` Input Action assets (IA_Move, IA_Look, IA_Jump, IA_Sprint, IA_Interact, IA_Fire, IA_Aim, IA_Reload, IA_Melee, IA_Block, IA_UseItem, IA_Hotkey1-8, IA_NextItem, IA_PreviousItem, IA_Pause, IA_Inventory, IA_Journal, IA_Map, IA_SkipCutscene, IA_SkipDialogue, IA_Grab)
+- 5 `IMC_*` Input Mapping Contexts (IMC_Default, IMC_Hiding, IMC_WristwatchUI, IMC_Inspection, IMC_UI)
+- `DA_InputMappingProfile` (129) — per-platform binding Data Asset
+
+**Full Spec:** [`docs/architecture/enhanced-input-system.md`](docs/architecture/enhanced-input-system.md)
 
 ---
 
@@ -464,7 +512,7 @@ Sets the rules of the game session: which pawn, controller, player state, HUD, a
 **Does NOT Handle:**
 - Gameplay logic (that's components on actors)
 - UI construction
-- Save/load (that's SS_SaveSystem)
+- Save/load (that's SS_SaveManager)
 
 **Key Variables:**
 
@@ -493,7 +541,7 @@ Sets the rules of the game session: which pawn, controller, player state, HUD, a
 |---------------|--------|-----|
 | GI_GameFramework | Direct | Phase transitions |
 | BPC_DeathHandlingSystem | Dispatcher | Receives death event |
-| SS_SaveSystem | Direct | Load checkpoint on respawn |
+| SS_SaveManager | Direct | Load checkpoint on respawn |
 | BPC_NarrativeSystem | Interface | Chapter start/end hooks |
 
 **Blueprint Flow:**
@@ -502,7 +550,7 @@ Sets the rules of the game session: which pawn, controller, player state, HUD, a
   └─► BPC_DeathHandlingSystem fires OnPlayerDied dispatcher
   └─► GM_CoreGameMode receives → HandlePlayerDead()
       ├─► Has alt death space? → SetGamePhase(AltDeathSpace)
-      └─► No → SetGamePhase(Loading) → SS_SaveSystem.LoadCheckpoint
+      └─► No → SetGamePhase(Loading) → SS_SaveManager.LoadCheckpoint
 ```
 
 **Reuse Notes:**
@@ -938,7 +986,85 @@ Silently records player behaviour data throughout the session to drive adaptive
 
 ---
 
-# 3. Interaction & World Manipulation Systems
+# 2.5. State Management — Central State Authority
+
+*These two systems form the central nervous system of the framework. Every gameplay system queries `BPC_StateManager.IsActionPermitted(Tag)` instead of checking other systems' states directly. This decouples all 135 systems from each other.*
+
+---
+
+### BPC_StateManager — Actor Component (130) — on Player Pawn
+
+**C++ Status:** ✅ Full implementation — `Source/PG_Framework/Public/Player/BPC_StateManager.h`
+
+**Purpose:**
+The single source of truth for "what can the player do right now?" Manages exclusive action states (42), upper-body overlay states (18), action gating, vital signs (heart rate), and the force-stack pattern for nested overrides (death, cutscenes, void space).
+
+**Responsibilities:**
+- Accept state change requests from any system via `RequestStateChange(NewState, Requester)`
+- Evaluate gating rules from `DA_StateGatingTable` (37 rules) to permit or deny actions
+- Maintain a force stack — death/cutscenes push a forced state, `RestorePreviousState()` pops
+- Track and smooth heart rate BPM based on stress tier + stamina exhaustion + combat
+- Broadcast `OnActionStateChanged`, `OnOverlayStateChanged`, `OnVitalSignChanged`, `OnForceStackPushed/Popped`
+
+**Key Variables:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `CurrentActionState` | GameplayTag | Currently active exclusive action (only one) |
+| `CurrentOverlayState` | GameplayTag | Upper-body overlay (aiming, reloading, etc.) |
+| `GatingTable` | DA_StateGatingTable | 37 gating rules |
+| `HeartRateBPM` | Float | Smoothed heart rate (60–180+) |
+| `HeartRateTier` | EHeartRateTier | Resting/Elevated/Stressed/Panic/Critical |
+| `ForceStack` | Array of (State, Reason) | Nested force override history |
+
+**Core Query (Hot Path):**
+```
+IsActionPermitted(ActionTag) → Bool
+  └─ Check force stack → blocked?
+  └─ Evaluate gating rules → blocked?
+  └─ Return true/false
+```
+
+**Communicates With:**
+
+| Target System | Method | Why |
+|---------------|--------|-----|
+| ALL gameplay systems (10+) | `IsActionPermitted()` query | Per-frame action validation |
+| BPC_HealthSystem | Direct bind | Death triggers force state |
+| BPC_StaminaSystem | Direct bind | Exhaustion affects heart rate |
+| BPC_StressSystem | Direct bind | Stress tier drives heart rate |
+| BPC_MovementStateSystem | Direct bind | Movement mode affects state |
+| DA_StateGatingTable | Direct reference | Reads gating rules |
+
+---
+
+### DA_StateGatingTable — Primary Data Asset (131)
+
+**C++ Status:** 🟡 Stub — `Source/PG_Framework/Public/State/DA_StateGatingTable.h` (struct + query method)
+
+**Purpose:**
+Defines all state gating rules in one Data Asset. Designers modify rules here without touching Blueprints or C++.
+
+**Key Variables:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `GatingRules` | Array of FStateGatingRule | 37 rules: ActionTag, BlockedByState, bIsBlocked |
+
+**Examples:**
+- `Framework.Action.FireWeapon` blocked by `Framework.State.Action.Dead` → true
+- `Framework.Action.Sprint` blocked by `Framework.State.Action.Hiding` → true
+- `Framework.Action.Jump` blocked by `Framework.State.Action.Dead` → true
+
+**Required Enums (create in UE5 editor):**
+- `E_PlayerActionState` — 42 exclusive action states (Idle, Sprinting, Hiding, Dead, InCutscene, etc.)
+- `E_OverlayState` — 18 upper-body overlay states (AimingDownSights, Reloading, Inspecting, etc.)
+- `E_ActionRequestResult` — 8 result codes (Granted, Denied, BlockedByForce, AlreadyActive, etc.)
+- `E_PlayerVitalSignals` — 5 vital tiers (Resting, Elevated, Stressed, Panic, Critical)
+
+**Full Spec:** [`docs/architecture/bpc-statemanager.md`](docs/architecture/bpc-statemanager.md) — enum values, gating table, force stack pattern, Chooser Table audit.
+
+---
 
 *These systems handle everything the player can do with the world: examining, opening, grabbing, hiding, climbing, and solving puzzles. The key principle is that each interactable object defines its own data — the Interaction System only detects and routes.*
 
@@ -2194,7 +2320,7 @@ The authoritative store of all narrative flags. Every story decision, discovered
 | BPC_ObjectiveSystem | Dispatcher | Objectives unlock/complete |
 | BPC_EndingAccumulator | Direct | Ending condition evaluation |
 | BPC_DialogueSystem | Direct | Dialogue condition checks |
-| SS_SaveSystem | I_Persistable | Flags persist |
+| SS_SaveManager | I_Persistable | Flags persist |
 
 ---
 
@@ -2478,7 +2604,7 @@ Defines and manages checkpoint triggers in the level. Determines when auto-saves
 **Responsibilities:**
 - Register checkpoint volumes/triggers in the level
 - Detect player crossing checkpoint boundary
-- Trigger SS_SaveSystem.SaveCheckpoint with the checkpoint tag
+- Trigger SS_SaveManager.SaveCheckpoint with the checkpoint tag
 - Respect "no save zone" flag for tension segments
 - Update the "last valid respawn point" for death handling
 
@@ -2534,7 +2660,7 @@ Manages persistent death traces: player corpse markers, blood trails, and contex
 **Responsibilities:**
 - Record death location and cause on player death
 - Spawn a persistent corpse/echo actor at the death location
-- Persist death trace data via SS_SaveSystem
+- Persist death trace data via SS_SaveManager
 - Optionally allow interacting with death echoes (narrative hook)
 - Limit total persistent corpses (oldest removed when limit reached)
 
@@ -2565,7 +2691,7 @@ The central orchestrator for all death outcomes. Routes the death event to the c
 - Determine death outcome type (respawn, game over, alt death space)
 - Trigger death animation and camera
 - Invoke persistent corpse system
-- Route to SS_SaveSystem for checkpoint load OR to alt death space
+- Route to SS_SaveManager for checkpoint load OR to alt death space
 - Update death counter in metrics
 
 **Key Variables:**
@@ -2603,7 +2729,7 @@ The central orchestrator for all death outcomes. Routes the death event to the c
   └─► BPC_PlayerMetricsTracker.IncrementDeaths()
   └─► SS_AchievementSystem.CheckDeathAchievements()
   └─► Determine DeathOutcome:
-      ├─► StandardRespawn → SS_SaveSystem.LoadCheckpoint
+      ├─► StandardRespawn → SS_SaveManager.LoadCheckpoint
       ├─► GameOver → WBP_GameOverScreen
       └─► AltDeathSpace → GI_GameFramework.SetGamePhase(AltDeathSpace)
                            → Stream in death-space level layer
@@ -2664,7 +2790,7 @@ Restores the player after checkpoint load: repositions pawn, restores snapshot v
 
 **Responsibilities:**
 - Receive respawn trigger from BPC_DeathHandlingSystem
-- Wait for SS_SaveSystem load to complete
+- Wait for SS_SaveManager load to complete
 - Teleport player to checkpoint respawn transform
 - Restore health, stress, stamina from snapshot
 - Fade camera in
@@ -2879,10 +3005,9 @@ Controls scripted and adaptive light events: flickers, fade-outs, colour shifts,
 
 ### BPC_AudioAtmosphereController — Actor Component (on Game State)
 
-**Purpose:**
-Controls all ambient and adaptive audio layers: music states, ambient sound morphs, and stinger playback.
+**⚠️ DEPRECATED** — Replaced by `SS_AudioManager` (132) GameInstance Subsystem and `BP_RoomAudioZone` (133) trigger volumes. The MetaSounds audio architecture (`docs/architecture/metasounds-audio-system.md`) replaces the component-based approach with bus management, room presets, and gameplay parameter injection. Migrate any audio atmosphere logic to `SS_AudioManager.SetRoomPreset()` and `BP_RoomAudioZone` triggers.
 
-**Key Variables:**
+**Key Variables (legacy reference only):**
 
 | Name | Type | Description |
 |------|------|-------------|
@@ -2919,6 +3044,8 @@ Monitors overall session pacing: tension curves, quiet beats, and escalation pat
 
 ---
 
+---
+
 ### BPC_RareEventSystem — Actor Component (on GameMode)
 
 **Purpose:**
@@ -2934,6 +3061,72 @@ Controls ultra-rare, randomised world events that can occur once per session or
 
 ---
 
+### MetaSounds Audio Subsystem (132-135)
+
+*The framework uses UE5 MetaSounds for all audio. These systems replace the deprecated `BPC_AudioAtmosphereController` with a modern bus-based architecture.*
+
+---
+
+### SS_AudioManager — GameInstance Subsystem (132)
+
+**C++ Status:** 🔵 BP-only (planned C++ stub)
+
+**Purpose:**
+Single entry point for all audio playback. Routes through `MS_MasterBus` → 4 category buses (SFX, Ambience, Music, Dialogue). Never call `UGameplayStatics::PlaySound*` directly — always use this subsystem.
+
+**Responsibilities:**
+- Manage 4 MetaSound mix buses with volume/effect controls
+- Accept `SetBusVolume(Category, Volume)` calls from settings menu
+- Push gameplay float parameters (heart rate, stress, fear, music intensity) to MetaSound patches
+- Switch room acoustic presets when `BP_RoomAudioZone` triggers overlap
+- Play 150+ sound triggers from the sound catalog (`docs/architecture/sound-catalog.md`)
+
+**Key Variables:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `MasterBus` | MetaSound Patch | Final output bus |
+| `SFXBus` | MetaSound Patch | Weapon, impact, interaction sounds |
+| `AmbientBus` | MetaSound Patch | Environmental ambience |
+| `MusicBus` | MetaSound Patch | Adaptive music layers |
+| `DialogueBus` | MetaSound Patch | Voice-over and subtitles |
+| `CurrentRoomPreset` | DA_RoomAcousticPreset | Active reverb/occlusion profile |
+| `GameplayParameters` | Map (FName → Float) | HeartRate, Stress, Fear, MusicIntensity |
+
+**Full Spec:** [`docs/architecture/metasounds-audio-system.md`](docs/architecture/metasounds-audio-system.md)
+
+---
+
+### BP_RoomAudioZone — Actor (133)
+
+**Purpose:**
+Trigger volume that automatically switches reverb/occlusion settings when the player enters/leaves a room. Communicates with `SS_AudioManager.SetRoomPreset()`.
+
+**Key Variables:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `RoomPreset` | DA_RoomAcousticPreset | The acoustic profile for this zone |
+| `BlendDuration` | Float | Crossfade time between presets |
+| `Priority` | Integer | For overlapping zones |
+
+---
+
+### Audio Data Assets (134-135)
+
+- **DA_AudioSettings** (134) — Global audio config: bus volumes, default presets, subtitle settings
+- **DA_RoomAcousticPreset** (135) — Per-zone profile: reverb params, occlusion curves, EQ settings. Pre-built presets: SmallRoom, LargeHall, Outdoor, Cave, Corridor, Basement, VentilationShaft
+
+### MetaSounds Audio Conventions (Summary)
+- **Single Entry Point:** All playback via `SS_AudioManager` — never raw `PlaySound*`
+- **Mix Buses:** 4 categories → Master Bus, each with own MetaSound patch
+- **Room Zones:** `BP_RoomAudioZone` trigger volumes handle reverb/occlusion switching
+- **Settings Integration:** Volume sliders in `WBP_SettingsMenu` call `SS_AudioManager.SetBusVolume()`
+- **Gameplay Parameters:** Heart rate, stress, fear pushed as MetaSound float parameters from gameplay systems
+- **Deprecated:** `BPC_AudioAtmosphereController` (95) → migrate to `SS_AudioManager`
+
+---
+
 # 10. AI, Perception & Encounter Systems
 
 ---
@@ -3478,7 +3671,7 @@ MigrationTable:
   Version 1 → 2: Added AltDeathSpaceEnterCount field (default 0)
   Version 2 → 3: Renamed NarrativeFlags map key format
 
-All migration handled in SS_SaveSystem.MigrateSaveVersion().
+All migration handled in SS_SaveManager.MigrateSaveVersion().
 Never remove save fields — mark as deprecated with bLEGACY_ prefix.
 ```
 
@@ -3492,7 +3685,7 @@ RULE 2: Systems never reference UI Widgets directly — use dispatchers.
 RULE 3: Components never import other components by class — use interfaces.
 RULE 4: Narrative flags are the ONLY cross-system currency — never pass actor references across narrative boundaries.
 RULE 5: All player metrics funnel through BPC_PlayerMetricsTracker — no system self-reports to achievements.
-RULE 6: SS_SaveSystem is the ONLY system that touches disk — nothing else reads/writes save files.
+RULE 6: SS_SaveManager is the ONLY system that touches disk — nothing else reads/writes save files.
 RULE 7: GASP internals are read-only — extend via notify events and Smart Object hooks only.
 RULE 8: Platform APIs only through BPC_PlatformServiceAbstraction — never call Steam/PS/Xbox SDK directly.
 ```
@@ -3501,188 +3694,245 @@ RULE 8: Platform APIs only through BPC_PlatformServiceAbstraction — never call
 
 # Build Order & Implementation Roadmap
 
+> **Note:** The definitive prioritized build list with C++ status per system lives in [`docs/checklists/remaining-blueprint-build-order.md`](docs/checklists/remaining-blueprint-build-order.md). Below is the architectural build order showing the major phases. All 22 C++ classes are already implemented and compile-ready.
+
 ---
 
 ## Recommended Build Order (Dependency-Safe)
 
-### Phase 0 — Foundation (Week 1–2)
+### Phase 0 — Foundation + Input (Week 1–2)
 Build these first. Everything else depends on them.
 
 ```
-1. GI_GameTagRegistry         — All tags defined before any system uses them
-2. FL_GameUtilities            — Static helpers available everywhere
-3. I_InterfaceLibrary          — All interfaces declared before implementors
-4. GI_GameFramework            — GameInstance shell + subsystem init stubs
-5. GM_CoreGameMode             — Establishes pawn/controller/state classes
-6. GS_CoreGameState            — Global state store
-7. DA_ItemData (empty shell)   — Data asset class before any items exist
+ 1. 11 Data Tables (import CSVs, register in Project Settings)
+ 2. DA_GameTagRegistry           ← Data Asset instance with 11 table refs
+ 3. FL_GameUtilities             ← Static library, no build needed
+ 4. I_InterfaceLibrary           ← 9 interfaces, implement on actors as needed
+ 5. GI_GameFramework             ← BP child → set as Default GameInstance
+ 6. GM_CoreGameMode              ← BP child → set as Default GameMode
+ 7. GS_CoreGameState             ← BP child
+ 8. PC_CoreController + PS_CorePlayerState  ← BP children
+ 9. SS_EnhancedInputManager      ← Auto-created subsystem (C++)
+10. 22 IA_* + 5 IMC_* assets     ← Create in editor
+11. DA_InputMappingProfile       ← Per-platform instances
 ```
 
-### Phase 1 — Player Core (Week 3–4)
+### Phase 1 — State Management (Week 2)
 ```
-8.  BPC_HealthSystem
-9.  BPC_StaminaSystem
-10. BPC_StressSystem
-11. BPC_MovementStateSystem
-12. BPC_DamageReceptionSystem
-13. BPC_DeathHandlingSystem (stub respawn only)
-14. BPC_PlayerMetricsTracker
+12. E_PlayerActionState enum (42 values)
+13. E_OverlayState enum (18 values)
+14. E_ActionRequestResult enum (8 values)
+15. DA_StateGatingTable          ← Data Asset with 37 gating rules
+16. BPC_StateManager             ← Attach to player pawn (C++)
 ```
 
-### Phase 2 — Interaction (Week 5–6)
+### Phase 2 — Player Core (Week 3–4)
 ```
-15. BPC_InteractionDetector
-16. BPC_InteractionExecutor
-17. BP_DoorActor
-18. BP_ContainerActor
-19. BPC_InspectItemSystem
-20. WBP_InteractionPromptDisplay (minimal)
+17. BPC_HealthSystem             ← C++ stub — BP child adds logic
+18. BPC_StaminaSystem            ← C++ stub — BP child adds logic
+19. BPC_StressSystem             ← C++ stub — BP child adds logic
+20. BPC_MovementStateSystem      ← C++ stub — BP child adds logic
+21. BPC_DamageReceptionSystem    ← Attach to pawn (C++)
+22. BPC_InventorySystem          ← Attach to pawn (C++)
+23. BPC_ShieldDefenseSystem      ← C++ stub — BP child adds logic
+24. BPC_HitReactionSystem        ← C++ stub — BP child adds logic
+25. BPC_PlayerMetricsTracker
+26. BPC_HidingSystem
+27. BPC_EmbodimentSystem
+28. BPC_CameraStateLayer
 ```
 
-### Phase 3 — Inventory (Week 7–8)
+### Phase 3 — Interaction (Week 5–6)
 ```
-21. BPC_InventorySystem
-22. BPC_KeyItemSystem
-23. BPC_EquipmentSlotSystem
-24. BPC_ActiveItemSystem
-25. WBP_InventoryMenu (minimal)
-26. DA_ItemData (populated)
+29. BPC_InteractionDetector
+30. BP_DoorActor
+31. BPC_ContextualTraversalSystem
+32. BPC_PhysicsDragSystem
+33. WBP_InteractionPromptDisplay
 ```
 
-### Phase 4 — Save/Load (Week 9–10)
+### Phase 4 — Inventory (Week 7–8)
 ```
-27. SS_SaveSystem
-28. BPC_CheckpointSystem
-29. I_Persistable (implement on all existing systems)
-30. BPC_PlayerRespawnSystem
+34. BPC_EquipmentSlotSystem
+35. BPC_ActiveItemSystem
+36. BPC_KeyItemSystem
+37. BPC_ConsumableSystem
+38. BPC_DocumentArchiveSystem
+39. BPC_JournalSystem
+40. BPC_CollectibleTracker
+41. BPC_ItemCombineSystem
+42. BP_ItemPickup
+43. BPC_ContainerInventory
+44. DA_ItemData instances
 ```
 
-### Phase 5 — UI Layer (Week 11–12)
+### Phase 5 — Save/Load (Week 9–10)
 ```
-31. WBP_HUDController
-32. WBP_DiegeticHUDFrame (project skin)
-33. WBP_ScreenEffectController
-34. WBP_PauseMenu
-35. WBP_MainMenu
-36. WBP_NotificationToast
+45. SS_SaveManager              ← Auto-created subsystem (C++)
+46. I_Persistable               ← Implement on actors
+47. BP_Checkpoint
+48. BPC_DeathHandlingSystem
+49. BPC_PlayerRespawnSystem
+50. BPC_PersistentWorldStateRecorder
+51. BPC_PersistentCorpseSystem
+52. BPC_RunHistoryTracker
+53. BPC_AltDeathSpaceSystem
 ```
 
-### Phase 6 — Narrative (Week 13–15)
+### Phase 6 — UI (Week 11–12)
 ```
-37. BPC_NarrativeStateSystem
-38. BPC_ObjectiveSystem
-39. BPC_DialoguePlaybackSystem
-40. BPC_DialogueChoiceSystem
-41. BPC_BranchingConsequenceSystem
-42. BPC_EndingAccumulatorSystem
-43. WBP_ObjectiveDisplay
-44. WBP_SubtitleDisplay
+54. SS_UIManager
+55. WBP_HUDController
+56. WBP_DiegeticHUDFrame
+57. WBP_InteractionPromptDisplay
+58. WBP_InventoryMenu
+59. WBP_ScreenEffectController
+60. WBP_NotificationToast
+61. WBP_PauseMenu
+62. WBP_MainMenu
+63. WBP_SettingsMenu
+64. WBP_MenuFlowController
+65. WBP_ObjectiveDisplay
+66. WBP_JournalDocumentViewer
+67. WBP_AccessibilityUI
 ```
 
-### Phase 7 — Weapons & Combat (Week 16–17)
+### Phase 7 — Narrative (Week 13–15)
 ```
-45. BPC_MeleeSystem
-46. BPC_FirearmSystem
-47. BPC_ReloadSystem
-48. BPC_RecoilSystem
-49. BPC_AmmoResourceSystem
-50. DA_WeaponData (populated)
+68. BPC_NarrativeStateSystem
+69. BPC_ObjectiveSystem
+70. BPC_DialoguePlaybackSystem
+71. BPC_DialogueChoiceSystem
+72. BPC_BranchingConsequenceSystem
+73. BPC_EndingAccumulator
+74. BPC_CutsceneBridge
+75. BPC_LoreUnlockSystem
+76. BPC_TrialScenarioSystem
+77. BP_NarrativeTriggerVolume
+78. DA_NarrativeDataAssets instances
 ```
 
-### Phase 8 — AI (Week 18–20)
+### Phase 8 — Weapons (Week 16–17)
 ```
-51. BB_AgentBoard
-52. AI_BaseAgentController
-53. BPC_AIPerceptionSystem
-54. BPC_AIMemorySystem
-55. DA_EncounterData
-56. BPC_EncounterDirector
-57. BPC_BehaviourVariantSelector (late — needs playstyle)
+79. BP_WeaponBase
+80. BPC_MeleeSystem
+81. BPC_FirearmSystem
+82. BPC_ReloadSystem
+83. BPC_RecoilSystem
+84. BPC_AmmoComponent
+85. BPC_CombatFeedbackComponent
+86. BPC_DeathCauseTracker
+87. DA_EquipmentConfig instances
 ```
 
-### Phase 9 — Adaptive & Atmosphere (Week 21–23)
+### Phase 9 — AI (Week 18–20)
 ```
-58. BPC_PlaystyleClassifier
-59. BPC_AdaptiveEnvironmentDirector
-60. BPC_AtmosphereStateController
-61. BPC_ScareEventSystem
-62. BPC_LightEventController
-63. BPC_AudioAtmosphereController
-64. BPC_PacingDirector
-65. BPC_MemoryDriftSystem
-66. BPC_RareEventSystem
+88. BB_AgentBoard
+89. AI_BaseAgentController
+90. BP_EnemyBase
+91. BPC_AIPerceptionSystem
+92. BPC_AIMemorySystem
+93. BPC_AlertSystem
+94. BPC_AIStateMachine
+95. BP_PatrolPath
+96. BPC_BehaviourVariantSelector
 ```
 
-### Phase 10 — Polish & Meta (Week 24–26)
+### Phase 10 — Adaptive + Audio (Week 21–23)
 ```
-67. SS_AchievementSystem
-68. DA_AchievementData (all achievements)
-69. SS_SettingsSystem
-70. WBP_SettingsMenu
-71. BPC_HapticsController
-72. BPC_PlatformServiceAbstraction
-73. BPC_PersistentCorpseSystem
-74. BPC_AltDeathSpaceSystem
-75. BPC_RunSummarySystem
-76. BPC_MetaProgressionSystem
-77. WBP_JournalDocumentViewer
-78. BPC_DocumentArchiveSystem
-79. BPC_JournalSystem
-80. BPC_CollectibleTracker
+ 97. BPC_PlaystyleClassifier
+ 98. BPC_AdaptiveEnvironmentDirector
+ 99. BPC_AtmosphereStateController
+100. BPC_ScareEventSystem
+101. BPC_LightEventController
+102. BPC_PacingDirector
+103. BPC_MemoryDriftSystem
+104. BPC_RareEventSystem
+105. BPC_DifficultyManager
+106. BPC_FearSystem
+107. BPC_PerformanceScaler
+108. BPC_ProceduralEncounter
+109. SS_AudioManager              ← MetaSounds subsystem
+110. BP_RoomAudioZone             ← Acoustic trigger volumes
+111. DA_AudioSettings + DA_RoomAcousticPreset instances
+```
+
+### Phase 11 — Meta + Settings + Polish (Week 24–26)
+```
+112. BPC_ProgressStatTracker
+113. SS_AchievementSystem
+114. SS_SettingsSystem
+115. BPC_AccessibilitySettings
+116. BPC_TutorialSystem
+117. BPC_LoadingScreen
+118. BPC_AnalyticsTracker
+119. BPC_DevCheatManager
+120. BPC_ErrorHandler
+121. BPC_FPSCounter
+122. WBP_CreditsScreen
+123. WBP_DebugMenu
+124. WBP_SplashScreen
+125. All remaining DA_* Data Asset instances
 ```
 
 ---
 
-## Smallest Playable Horror Slice
+## Smallest Playable Prototype
 
-*The absolute minimum to have a functional first-person horror experience:*
+*The absolute minimum to have a functional first-person character. All C++ classes marked with ✅ are ready to use:*
 
 ```
-✓ GI_GameTagRegistry
-✓ FL_GameUtilities
-✓ I_Interactable, I_Damageable
-✓ GI_GameFramework (stub)
-✓ GM_CoreGameMode
-✓ BPC_HealthSystem
-✓ BPC_DamageReceptionSystem
-✓ BPC_DeathHandlingSystem (checkpoint respawn only)
-✓ BPC_InteractionDetector
-✓ BPC_InteractionExecutor
-✓ BP_DoorActor
-✓ WBP_HUDController (minimal)
-✓ WBP_InteractionPromptDisplay
-✓ WBP_ScreenEffectController (damage flash, fade)
-✓ SS_SaveSystem (checkpoint only)
-✓ BPC_CheckpointSystem
-✓ AI_BaseAgentController (one archetype)
-✓ BPC_AIPerceptionSystem
-✓ BB_AgentBoard
-✓ BPC_AtmosphereStateController (two states)
-✓ BPC_AudioAtmosphereController (two music states)
+✓ 11 Data Tables (import CSVs)
+✓ DA_GameTagRegistry (Data Asset + 11 table refs)
+✓ FL_GameUtilities (static library)
+✓ I_Interactable, I_Damageable, I_Persistable (C++ interfaces)
+✓ GI_GameFramework (BP child → GameInstance)
+✓ GM_CoreGameMode (BP child → GameMode)
+✓ GS_CoreGameState (BP child)
+✓ PC_CoreController + PS_CorePlayerState (BP children from C++ stubs)
+✓ SS_EnhancedInputManager (auto-created C++ subsystem)
+✓ 8 IA_* + 1 IMC_Default (input assets)
+✓ BPC_StateManager (C++ component → attach to pawn)
+✓ DA_StateGatingTable (Data Asset with 8 min rules)
+✓ BPC_HealthSystem (C++ stub → BP child adds logic)
+✓ BPC_StaminaSystem (C++ stub → BP child adds logic)
+✓ BPC_MovementStateSystem (C++ stub → BP child adds logic)
+✓ BPC_DamageReceptionSystem (C++ component → attach to pawn)
+✓ BPC_InventorySystem (C++ component → attach to pawn)
+✓ SS_SaveManager (auto-created C++ subsystem)
+✓ BPC_InteractionDetector (BP child from spec)
+✓ WBP_HUDController (minimal widget)
+✓ WBP_InteractionPromptDisplay (minimal widget)
+✓ Player Pawn BP (Character parent → 10+ components attached)
 ```
 
-*Estimated: ~20 systems. Enough to walk, open doors, be chased, take damage, die, and respawn.*
+*Estimated: ~22 systems. Enough to walk, take damage, manage inventory, save/load, and query state permissions. Expand with weapons, AI, narrative, and UI as needed.*
+
+**Step-by-step guide:** [`docs/developer/project-prototype-guide.md`](docs/developer/project-prototype-guide.md)
 
 ---
 
 ## Full Production Framework
 
-*Everything. All 131 systems. Supports:*
+*All 135 numbered systems + 1 starter GameInstance. Supports:*
 
 ```
 ✓ Complete narrative with branching choices and multiple endings
-✓ Full inventory (bag, equipment, key items, consumables, ammo)
-✓ Melee + firearms + reload + recoil
+✓ Full inventory (grid, equipment, key items, consumables, ammo, documents)
+✓ Melee + firearms + reload + recoil + shield defense
+✓ State Management — 42 action states, 18 overlay states, 37 gating rules
 ✓ Adaptive AI that responds to player playstyle
 ✓ Diegetic HUD (swappable skin)
-✓ Full save system (auto, checkpoint, hard save)
+✓ Full save system (auto, checkpoint, hard save, slot manifest, backups)
 ✓ Persistent corpse/death traces
 ✓ Alternate death space (limbo mechanic)
 ✓ Scare system with pacing director and cooldowns
 ✓ Memory drift / room mutation
 ✓ Rare events
-✓ Achievements/trophies (Steam + PS + Xbox)
+✓ Achievements/trophies (Steam + PS + Xbox platform abstraction)
 ✓ Full accessibility settings
+✓ Enhanced Input — priority context stack, key rebinding
+✓ MetaSounds Audio — 4 bus categories, room zones, gameplay parameters
 ✓ DualSense haptics + adaptive triggers
 ✓ Post-game meta progression and ending tracker
 ✓ Run history and summary
@@ -3690,14 +3940,19 @@ Build these first. Everything else depends on them.
 ✓ Collectible tracking
 ✓ Full item combine system
 ✓ Puzzle device framework
-✓ Context traversal (vault, climb, ledge)
+✓ Contextual traversal (vault, climb, ledge, slide, squeeze)
 ✓ Physics drag/throw
 ✓ Subtitles + localisation hooks
 ✓ Hiding spots
+✓ 16 Data Asset types (item, equipment, encounter, atmosphere, scare, etc.)
+✓ Server-authoritative multiplayer networking (HasAuthority gates, Server_ RPCs, RepNotify)
+✓ Central state authority — systems never check each other directly
 ```
 
 ---
 
-*End of Reusable UE5 Modular Game Framework v1.0*
+*End of Reusable UE5 Modular Game Framework v2.0*
 *Framework designed for generic use. All system names are project-agnostic.*
 *Override in /Game/ folder. Never modify /Framework/ core assets.*
+*C++ source: 22 classes in Source/PG_Framework/ | BP specs: 135 numbered files in docs/blueprints/*
+*Companion docs: docs/checklists/ (build order, status), docs/developer/ (per-category references), docs/architecture/ (state management, audio, networking, animation, sound)*
diff --git a/docs/developer/02-player-systems.md b/docs/developer/02-player-systems.md
index 201aa7f..2d98aa1 100644
--- a/docs/developer/02-player-systems.md
+++ b/docs/developer/02-player-systems.md
@@ -2,6 +2,8 @@
 
 **Category Purpose:** These 8 systems form the player character's core simulation layer — health, stamina, stress, movement, hiding, first-person body, camera, and metrics tracking. They cascade: health affects stress, stress affects movement, movement affects camera. All feed into the animation system (ABP_GASP) via event dispatchers.
 
+**C++ Status:** Systems 08-11 have C++ stubs (`Source/PG_Framework/Public/Player/`) providing UCLASS definition, basic variables, and event dispatchers. The Blueprint child provides the full runtime implementation. Systems 12-15 are BP-only. All 8 are referenced by `BPC_StateManager` (130) for gating evaluations.
+
 ---
 
 ## System Index
diff --git a/docs/developer/04-inventory-systems.md b/docs/developer/04-inventory-systems.md
index 6f7a2b8..6afca16 100644
--- a/docs/developer/04-inventory-systems.md
+++ b/docs/developer/04-inventory-systems.md
@@ -2,6 +2,8 @@
 
 **Category Purpose:** These 11 systems form the complete inventory management layer — core item storage grid, world containers, item pickups, consumable usage, equipment slots, item combination/crafting, key item tracking, document archiving, quick slots, journal tracking, and collectible progression. The `BPC_InventorySystem` is the single source of truth for all item data; every other inventory subsystem reads from and writes through it.
 
+**C++ Status:** System 31 (`BPC_InventorySystem`) is a full C++ implementation (`Source/PG_Framework/Public/Inventory/BPC_InventorySystem.h`) with native-speed TArray operations, auto-stacking, and weight tracking. System 07 (`DA_ItemData`) is also full C++. System 120 (`DA_EquipmentConfig`) is a C++ stub. All other inventory systems are BP-only.
+
 ---
 
 ## System Index
diff --git a/docs/developer/08-weapons-systems.md b/docs/developer/08-weapons-systems.md
index 12873bf..bea82ab 100644
--- a/docs/developer/08-weapons-systems.md
+++ b/docs/developer/08-weapons-systems.md
@@ -2,6 +2,8 @@
 
 **Category Purpose:** These 11 systems form the complete combat layer — weapon actors (ranged and melee), ammo management, combat feedback (hit markers, kill confirm), damage reception and resistance, death cause tracking, firearm specialization, hit reactions, melee combat, recoil patterns, reload mechanics, and shield defense. The `BP_WeaponBase` is the base actor class extended by all weapons; combat flows through `BPC_DamageReceptionSystem` to `BPC_HealthSystem`.
 
+**C++ Status:** System 72 (`BPC_DamageReceptionSystem`) is a full C++ implementation — attach the component directly. Systems 75 (`BPC_HitReactionSystem`) and 79 (`BPC_ShieldDefenseSystem`) are C++ stubs with basic variables and dispatchers — create BP children for full logic. Systems 69-71, 73-74, 76-78 are BP-only.
+
 ---
 
 ## System Index