- 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.
| `FL_` | Function Library | `FL_GameUtilities`, `FL_MathHelpers` |
| `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` |
| `AI_` | AI Blueprint | `AI_PatrolAgent`, `AI_EncounterDirector` |
| `BTT_` | Behaviour Tree Task | `BTT_Investigate`, `BTT_Chase` |
| `BTT_` | Behaviour Tree Task | `BTT_Investigate`, `BTT_Chase` |
| `BTS_` | Behaviour Tree Service | `BTS_PerceptionUpdate` |
| `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.
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.
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.
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.
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.
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.
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.
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).
> **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()
└─► InitPlatformServices()
└─► Create all SS_ Subsystems
└─► Create all SS_ Subsystems
└─► Load persistent settings (SS_SettingsSystem)
└─► Load persistent settings (SS_SettingsSystem)
└─► Check for existing save data (SS_SaveSystem)
└─► Check for existing save data (SS_SaveManager)
└─► SetGamePhase(MainMenu)
└─► SetGamePhase(MainMenu)
└─► Broadcast OnGamePhaseChanged
└─► 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:**
**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:**
**Responsibilities:**
- Write and read `USaveGame`-derived objects per slot
- 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:**
**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:**
**Responsibilities:**
- Define all framework-level tags (Player.State.*, Interaction.Type.*, Narrative.Flag.*, etc.)
- Define all framework-level tags (Player.State.*, Interaction.Type.*, Narrative.Flag.*, etc.)
- Provide the canonical tag namespace so no system uses raw FName comparisons
- Provide the canonical tag namespace so no system uses raw FName comparisons
- Document each tag's meaning inline via comments in the ini
- Document each tag's meaning inline via comments in the ini
- Provide `GetAllRegisteredTags()`, `ValidateTag()`, `RequestTag()`, `ExportTagNamespace()` in C++ (BlueprintCallable)
**Tag Namespace Structure:**
**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 |
| `I_ScareTarget` | `OnScareEventFired(ScareTag)` | Actors that respond to scare events |
**Reuse Notes:**
**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.
**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))
├─► Has alt death space? → SetGamePhase(AltDeathSpace)
├─► Has alt death space? → SetGamePhase(AltDeathSpace)
└─► No → SetGamePhase(Loading) → SS_SaveSystem.LoadCheckpoint
└─► No → SetGamePhase(Loading) → SS_SaveManager.LoadCheckpoint
```
```
**Reuse Notes:**
**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
*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.*
*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_AudioAtmosphereController — Actor Component (on Game State)
### BPC_AudioAtmosphereController — Actor Component (on Game State)
**Purpose:**
**⚠️ 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.
Controls all ambient and adaptive audio layers: music states, ambient sound morphs, and stinger playback.
**Key Variables:**
**Key Variables (legacy reference only):**
| Name | Type | Description |
| Name | Type | Description |
|------|------|-------------|
|------|------|-------------|
@@ -2919,6 +3044,8 @@ Monitors overall session pacing: tension curves, quiet beats, and escalation pat
---
---
---
### BPC_RareEventSystem — Actor Component (on GameMode)
### BPC_RareEventSystem — Actor Component (on GameMode)
**Purpose:**
**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.*
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 |
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
- **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
# 10. AI, Perception & Encounter Systems
---
---
@@ -3478,7 +3671,7 @@ MigrationTable:
Version 1 → 2: Added AltDeathSpaceEnterCount field (default 0)
Version 1 → 2: Added AltDeathSpaceEnterCount field (default 0)
Version 2 → 3: Renamed NarrativeFlags map key format
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.
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 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 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 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 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.
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
# 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)
## 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.
Build these first. Everything else depends on them.
```
```
1. GI_GameTagRegistry — All tags defined before any system uses them
1. 11 Data Tables (import CSVs, register in Project Settings)
2. FL_GameUtilities — Static helpers available everywhere
2. DA_GameTagRegistry ← Data Asset instance with 11 table refs
3. I_InterfaceLibrary — All interfaces declared before implementors
3. FL_GameUtilities ← Static library, no build needed
✓ PC_CoreController + PS_CorePlayerState (BP children from C++ stubs)
✓ BPC_InteractionDetector
✓ SS_EnhancedInputManager (auto-created C++ subsystem)
✓ BPC_InteractionExecutor
✓ 8 IA_* + 1 IMC_Default (input assets)
✓ BP_DoorActor
✓ BPC_StateManager (C++ component → attach to pawn)
✓ WBP_HUDController (minimal)
✓ DA_StateGatingTable (Data Asset with 8 min rules)
✓ WBP_InteractionPromptDisplay
✓ BPC_HealthSystem (C++ stub → BP child adds logic)
✓ WBP_ScreenEffectController (damage flash, fade)
✓ BPC_StaminaSystem (C++ stub → BP child adds logic)
✓ SS_SaveSystem (checkpoint only)
✓ BPC_MovementStateSystem (C++ stub → BP child adds logic)
✓ BPC_CheckpointSystem
✓ BPC_DamageReceptionSystem (C++ component → attach to pawn)
✓ AI_BaseAgentController (one archetype)
✓ BPC_InventorySystem (C++ component → attach to pawn)
✓ BPC_AIPerceptionSystem
✓ SS_SaveManager (auto-created C++ subsystem)
✓ BB_AgentBoard
✓ BPC_InteractionDetector (BP child from spec)
✓ BPC_AtmosphereStateController (two states)
✓ WBP_HUDController (minimal widget)
✓ BPC_AudioAtmosphereController (two music states)
✓ 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.*
**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.
**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.
**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.
**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.
**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`.
**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
## System Index
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Lefteris Notas