From 4a7c871f29d3220aac1c4c41619b7326abc417f2 Mon Sep 17 00:00:00 2001 From: Lefteris Notas Date: Wed, 20 May 2026 15:16:32 +0300 Subject: [PATCH] Update Developer Reference and add C++ Integration Guide - Updated version in INDEX.md from 1.3 to 1.4, reflecting new files and C++ systems migrated. - Added cpp-integration-guide.md detailing setup and usage for 12 C++ classes. - Introduced cpp-blueprint-status.md to track the status of all 135 systems, including C++ and Blueprint specifications. --- docs/checklists/cpp-blueprint-status.md | 235 +++++++++ docs/developer/INDEX.md | 22 +- docs/developer/cpp-integration-guide.md | 626 ++++++++++++++++++++++++ 3 files changed, 872 insertions(+), 11 deletions(-) create mode 100644 docs/checklists/cpp-blueprint-status.md create mode 100644 docs/developer/cpp-integration-guide.md diff --git a/docs/checklists/cpp-blueprint-status.md b/docs/checklists/cpp-blueprint-status.md new file mode 100644 index 0000000..b27b11e --- /dev/null +++ b/docs/checklists/cpp-blueprint-status.md @@ -0,0 +1,235 @@ +# C++ & Blueprint Status Checklist — All 135 Systems + +**Version:** 1.0 | **Generated:** 2026-05-20 + +Complete status grid for every system in the UE5 Modular Game Framework. Use this to track: which systems have C++ code written, which Blueprint specs are complete, and what Blueprint assets remain to create. + +--- + +## Legend + +| Symbol | Meaning | +|--------|---------| +| ✅ | **Done** — C++ files written, BP spec complete | +| 🟡 | **Partial** — C++ stub (references siblings, needs subsystem wiring) | +| 🔵 | **BP Spec Only** — Full Blueprint spec exists, no C++ written | +| ⬜ | **Content Asset** — Create Data Asset/Table instances (not code) | +| ❌ | **Not Started** — Spec exists but asset not created | + +Abbreviations: +- **C++ H/CPP** = C++ header and source files exist in `Source/Framework/` +- **BP Spec** = Blueprint specification file exists in `docs/blueprints/` +- **BP Asset** = Blueprint asset to create in UE5 Content Browser +- **MI Guide** = Manual Implementation Guide (node-by-node) in spec file + +--- + +## Phase 0: Foundation (01-core — 7 systems) + +| # | System | C++ H/CPP | BP Spec | BP Asset to Create | Status | +|---|--------|-----------|---------|--------------------|--------| +| 01 | `DA_GameTagRegistry` | ✅ `Core/DA_GameTagRegistry` | ✅ `01_DA_GameTagRegistry.md` | Data Asset instance: `DA_GameTagRegistry` (assign TagDataTables) | ✅ | +| 02 | `FL_GameUtilities` | ✅ `Core/FL_GameUtilities` | ✅ `02_FL_GameUtilities.md` | None (static library) | ✅ | +| 03 | `I_InterfaceLibrary` | ✅ `Core/I_InterfaceLibrary.h` | ✅ `03_I_InterfaceLibrary.md` | None (implement on actors) | ✅ | +| 04 | `GI_GameFramework` | ✅ `Core/GI_GameFramework` | ✅ `04_GI_GameFramework.md` | **BP_GameFramework** (GameInstance child) | ✅ | +| 05 | `GM_CoreGameMode` | ✅ `Core/GM_CoreGameMode` | ✅ `05_GM_CoreGameMode.md` | **BP_CoreGameMode** (GameMode child) | ✅ | +| 06 | `GS_CoreGameState` | ✅ `Core/GS_CoreGameState` | ✅ `06_GS_CoreGameState.md` | **BP_CoreGameState** (GameState child) | ✅ | +| 07 | `DA_ItemData` | ✅ `Inventory/DA_ItemData` | ✅ `07_DA_ItemData.md` | Data Asset instances: `DA_Item_*` per item | ✅ | +| — | `GI_StarterGameInstance` | 🔵 (superseded by 04) | ✅ `GI_StarterGameInstance.md` | **BP_StarterGameInstance** (or skip, use 04) | 🟡 | + +### Data Tables (01-core root) +| Asset | Status | +|-------|--------| +| `DT_Tags_Player.csv` | ⬜ Create Data Table, import CSV | +| `DT_Tags_Interaction.csv` | ⬜ Create Data Table, import CSV | +| `DT_Tags_Item.csv` | ⬜ Create Data Table, import CSV | +| `DT_Tags_Narrative.csv` | ⬜ Create Data Table, import CSV | +| `DT_Tags_AI.csv` | ⬜ Create Data Table, import CSV | +| `DT_Tags_Save.csv` | ⬜ Create Data Table, import CSV | +| `DT_Tags_Environment.csv` | ⬜ Create Data Table, import CSV | +| `DT_Tags_Combat.csv` | ⬜ Create Data Table, import CSV | +| `DT_Tags_State.csv` | ⬜ Create Data Table, import CSV | +| `DT_Tags_Audio.csv` | ⬜ Create Data Table, import CSV | +| `DT_Tags_Achievement.csv` | ⬜ Create Data Table, import CSV | + +--- + +## Phase 1: Player Core (02-player — 8 systems) + +| # | System | C++ H/CPP | BP Spec | BP Asset to Create | Status | +|---|--------|-----------|---------|--------------------|--------| +| 08 | `BPC_HealthSystem` | 🔵 BP-only | ✅ `08_BPC_HealthSystem.md` | BP child → attach to pawn | 🔵 | +| 09 | `BPC_StaminaSystem` | 🔵 BP-only | ✅ `09_BPC_StaminaSystem.md` | BP child → attach to pawn | 🔵 | +| 10 | `BPC_StressSystem` | 🔵 BP-only | ✅ `10_BPC_StressSystem.md` | BP child → attach to pawn | 🔵 | +| 11 | `BPC_MovementStateSystem` | 🔵 BP-only | ✅ `11_BPC_MovementStateSystem.md` | BP child → attach to pawn | 🔵 | +| 12 | `BPC_HidingSystem` | 🔵 BP-only | ✅ `12_BPC_HidingSystem.md` | BP child → attach to pawn | 🔵 | +| 13 | `BPC_EmbodimentSystem` | 🔵 BP-only | ✅ `13_BPC_EmbodimentSystem.md` | BP child → attach to pawn | 🔵 | +| 14 | `BPC_CameraStateLayer` | 🔵 BP-only | ✅ `14_BPC_CameraStateLayer.md` | BP child → attach to pawn | 🔵 | +| 15 | `BPC_PlayerMetricsTracker` | 🔵 BP-only | ✅ `15_BPC_PlayerMetricsTracker.md` | BP child → attach to pawn | 🔵 | + +--- + +## Phase 2-14: All Remaining Systems + +### Interaction (03-interaction — 8 systems) + +| # | System | C++ | BP Spec | BP Asset | +|---|--------|-----|---------|----------| +| 16 | `BPC_InteractionDetector` | 🔵 | ✅ | BP child | +| 17 | `I_HidingSpot` | 🔵 | ✅ | Implement on BP actors | +| 18 | `BPC_DiegeticDisplay` | 🔵 | ✅ | BP child | +| 19 | `BP_DoorActor` | 🔵 | ✅ | BP actor child | +| 20 | `BP_PuzzleDeviceActor` | 🔵 | ✅ | BP actor child | +| 21 | `BPC_ContextualTraversalSystem` | 🔵 | ✅ | BP child | +| 22 | `BPC_PhysicsDragSystem` | 🔵 | ✅ | BP child | +| 23 | `BPC_UsableWorldObjectSystem` | 🔵 | ✅ | BP child | + +### Inventory (04-inventory — 11 systems) + +| # | System | C++ | BP Spec | BP Asset | +|---|--------|-----|---------|----------| +| 24 | `BPC_ContainerInventory` | 🔵 | ✅ | BP child | +| 25 | `BP_ItemPickup` | 🔵 | ✅ | BP actor child | +| 26 | `BPC_ActiveItemSystem` | 🔵 | ✅ | BP child | +| 27 | `BPC_CollectibleTracker` | 🔵 | ✅ | BP child | +| 28 | `BPC_ConsumableSystem` | 🔵 | ✅ | BP child | +| 29 | `BPC_DocumentArchiveSystem` | 🔵 | ✅ | BP child | +| 30 | `BPC_EquipmentSlotSystem` | 🔵 | ✅ | BP child | +| 31 | `BPC_InventorySystem` | ✅ `Inventory/BPC_InventorySystem` | ✅ | None (use C++ component directly) | +| 32 | `BPC_ItemCombineSystem` | 🔵 | ✅ | BP child | +| 33 | `BPC_JournalSystem` | 🔵 | ✅ | BP child | +| 34 | `BPC_KeyItemSystem` | 🔵 | ✅ | BP child | + +### Save/Load (05-saveload — 9 systems) + +| # | System | C++ | BP Spec | BP Asset | +|---|--------|-----|---------|----------| +| 35 | `SS_SaveManager` | ✅ `Save/SS_SaveManager` | ✅ | None (auto-created subsystem) | +| 36 | `I_Persistable` | ✅ `Core/I_InterfaceLibrary.h` | ✅ | Implement on actors | +| 37 | `BP_Checkpoint` | 🔵 | ✅ | BP actor child | +| 38 | `BPC_AltDeathSpaceSystem` | 🔵 | ✅ | BP child | +| 39 | `BPC_DeathHandlingSystem` | 🔵 | ✅ | BP child | +| 40 | `BPC_PersistentCorpseSystem` | 🔵 | ✅ | BP child | +| 41 | `BPC_PersistentWorldStateRecorder` | 🔵 | ✅ | BP child | +| 42 | `BPC_PlayerRespawnSystem` | 🔵 | ✅ | BP child | +| 43 | `BPC_RunHistoryTracker` | 🔵 | ✅ | BP child | + +### UI (06-ui — 14 systems) + +| # | System | C++ | BP Spec | BP Asset | +|---|--------|-----|---------|----------| +| 44 | `SS_UIManager` | 🔵 | ✅ | BP child (auto-created subsystem) | +| 45 | `WBP_AccessibilityUI` | 🔵 | ✅ | Widget BP | +| 46 | `WBP_DiegeticHUDFrame` | 🔵 | ✅ | Widget BP | +| 47 | `WBP_HUDController` | 🔵 | ✅ | Widget BP | +| 48 | `WBP_InteractionPromptDisplay` | 🔵 | ✅ | Widget BP | +| 49 | `WBP_InventoryMenu` | 🔵 | ✅ | Widget BP | +| 50 | `WBP_JournalDocumentViewer` | 🔵 | ✅ | Widget BP | +| 51 | `WBP_MainMenu` | 🔵 | ✅ | Widget BP | +| 52 | `WBP_MenuFlowController` | 🔵 | ✅ | Widget BP | +| 53 | `WBP_NotificationToast` | 🔵 | ✅ | Widget BP | +| 54 | `WBP_ObjectiveDisplay` | 🔵 | ✅ | Widget BP | +| 55 | `WBP_PauseMenu` | 🔵 | ✅ | Widget BP | +| 56 | `WBP_ScreenEffectController` | 🔵 | ✅ | Widget BP | +| 57 | `WBP_SettingsMenu` | 🔵 | ✅ | Widget BP | + +### Narrative (07-narrative — 11 systems) + +| # | System | C++ | BP Spec | BP Asset | +|---|--------|-----|---------|----------| +| 58-68 | All 11 systems | 🔵 | ✅ | BP children + DA instances | + +### Weapons (08-weapons — 11 systems) + +| # | System | C++ | BP Spec | BP Asset | +|---|--------|-----|---------|----------| +| 69 | `BP_WeaponBase` | 🔵 | ✅ | BP actor child | +| 70 | `BPC_AmmoComponent` | 🔵 | ✅ | BP child | +| 71 | `BPC_CombatFeedbackComponent` | 🔵 | ✅ | BP child | +| 72 | `BPC_DamageReceptionSystem` | ✅ `Weapons/BPC_DamageReceptionSystem` | ✅ | None (use C++ component) | +| 73 | `BPC_DeathCauseTracker` | 🔵 | ✅ | BP child | +| 74 | `BPC_FirearmSystem` | 🔵 | ✅ | BP child | +| 75 | `BPC_HitReactionSystem` | 🔵 | ✅ | BP child | +| 76 | `BPC_MeleeSystem` | 🔵 | ✅ | BP child | +| 77 | `BPC_RecoilSystem` | 🔵 | ✅ | BP child | +| 78 | `BPC_ReloadSystem` | 🔵 | ✅ | BP child | +| 79 | `BPC_ShieldDefenseSystem` | 🔵 | ✅ | BP child | + +### AI (09-ai — 9 systems) + +| # | System | C++ | BP Spec | BP Asset | +|---|--------|-----|---------|----------| +| 80-88 | All 9 systems | 🔵 | ✅ | BP children | + +### Adaptive (10-adaptive — 15 systems) + +| # | System | C++ | BP Spec | BP Asset | +|---|--------|-----|---------|----------| +| 89-101 | All 13 core | 🔵 | ✅ | BP children | +| 132 | `SS_AudioManager` | 🔵 | ✅ | BP child (auto-created subsystem) | +| 133 | `BP_RoomAudioZone` | 🔵 | ✅ | BP actor child | + +### Meta, Settings, Polish (11-13 — 13 systems) + +| # | System | C++ | BP Spec | BP Asset | +|---|--------|-----|---------|----------| +| 102-114 | All 13 systems | 🔵 | ✅ | BP children + widget BPs | + +### Data Assets (14-data-assets — 16 systems) + +| # | System | C++ | BP Spec | BP Asset | +|---|--------|-----|---------|----------| +| 115-127, 129, 134-135 | All 16 systems | 🔵 | ✅ | ⬜ Data Asset instances (per content item) | + +### Input + State (15-16 — 3 systems) + +| # | System | C++ | BP Spec | BP Asset | +|---|--------|-----|---------|----------| +| 128 | `SS_EnhancedInputManager` | ✅ `Input/SS_EnhancedInputManager` | ✅ | None (auto-created subsystem) | +| 130 | `BPC_StateManager` | ✅ `Player/BPC_StateManager` | ✅ | None (use C++ component) | +| 131 | `DA_StateGatingTable` | 🔵 | ✅ | ⬜ Data Asset instance (37 rules) | + +--- + +## Summary Counts + +| Category | Count | +|----------|-------| +| **C++ systems written** | 12 | +| **BP spec files complete** | 135 + 1 starter = 136 | +| **BP components to create** | 76 (80 BPC_ total − 4 C++) | +| **BP actors to create** | 11 | +| **Widget BPs to create** | 14 | +| **Data Asset instances to create** | Per-project (18 DA_ definitions) | +| **GameInstance subsystems** (auto-created) | 7 (3 in C++, 4 BP) | +| **Data Tables to create** | 11 | + +--- + +## Quick Action List — What to Build Next + +### Immediate (Phase 0 — Foundation) +- [ ] Create 11 Data Tables, import CSVs, register in Project Settings +- [ ] Create `DA_GameTagRegistry` Data Asset, assign TagDataTables +- [ ] Create `BP_GameFramework` (child of `GI_GameFramework`), assign TagRegistry +- [ ] Create `BP_CoreGameMode` (child of `GM_CoreGameMode`), set in Project Settings +- [ ] Create `BP_CoreGameState` (child of `GS_CoreGameState`), set in GameMode defaults +- [ ] Create `BP_CorePlayerController` + `BP_CorePlayerState` (BP specs 08 area) +- [ ] Create `DA_ItemData` instances for initial items (weapons, consumables) + +### Player Pawn Setup +- [ ] Create player pawn BP with GASP +- [ ] Add `BPC_StateManager` component → assign GatingTable +- [ ] Add `BPC_InventorySystem` component → set grid size +- [ ] Add `BPC_DamageReceptionSystem` component → set thresholds +- [ ] Add remaining 76 `BPC_*` BP children as needed + +### Data Asset Content +- [ ] Create `DA_StateGatingTable` instance with 37 rules +- [ ] Create `DA_EquipmentConfig` instance(s) for armor/weapons +- [ ] Create `DA_AudioSettings`, `DA_RoomAcousticPreset` instances +- [ ] Create remaining `DA_*` instances per project content + +--- + +*Status Checklist v1.0 — Updated 2026-05-20. Regenerate after each implementation phase.* diff --git a/docs/developer/INDEX.md b/docs/developer/INDEX.md index 3cdf687..a2c2282 100644 --- a/docs/developer/INDEX.md +++ b/docs/developer/INDEX.md @@ -1,6 +1,6 @@ # Developer Reference — UE5 Modular Game Framework -**Version:** 1.3 | **Generated:** 2026-05-20 | **Files:** 16 (1 index + 2 overview + 1 migration + 1 starter + 10 category docs + 1 combined) | **Networking:** All docs include multiplayer sections +**Version:** 1.4 | **Generated:** 2026-05-20 | **Files:** 17 (1 index + 2 overview + 1 migration + 1 integration + 1 starter + 10 category docs + 1 combined) | **C++:** 12 systems migrated This directory contains developer-facing reference documentation for every system in the framework. Unlike the blueprint spec files (which define *what* to build), these documents explain *how each system works internally* — the data flow, state machines, integration points, and design rationale. Use these when you need to understand a system's behavior to implement, debug, or extend it. @@ -18,9 +18,8 @@ docs/developer/ ├── INDEX.md ← THIS FILE ├── 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 (systems 01-07) +├── cpp-integration-guide.md ← C++ per-system integration & setup (NEW — 12 systems) +├── project-setup-migration.md ← Project setup & migration guide ├── 00-starter-gameinstance.md ← Starter GameInstance: GI_StarterGameInstance setup guide ├── 02-player-systems.md ← Player state & embodiment (systems 08-15) ├── 03-interaction-systems.md ← Interaction & world manipulation (systems 16-23) @@ -179,11 +178,12 @@ docs/developer/ 1. **New to the framework?** Start with [`architecture-overview.md`](architecture-overview.md) to understand the big picture. 2. **Setting up a new project?** Read [`00-starter-gameinstance.md`](00-starter-gameinstance.md) first — create `GI_StarterGameInstance` to validate your GameplayTags immediately. Then follow [`project-setup-migration.md`](project-setup-migration.md) for full Project Settings, plugins, Data Tables, and init sequence. -3. **Implementing a system?** Read the Blueprint Spec in `docs/blueprints/` — every file has a Manual Implementation Guide with node-by-node logic. -4. **Need to understand internals?** Read the corresponding Developer Reference doc in this directory. -5. **Debugging?** Each category doc includes a data flow section showing how data moves between systems. -6. **Need UE5 Blueprint patterns?** See [`implementation-patterns.md`](implementation-patterns.md). -7. **Multiplayer networking?** See [`../architecture/multiplayer-networking.md`](../architecture/multiplayer-networking.md). Every doc has a Multiplayer Networking section. +3. **Using the C++ classes?** Read [`cpp-integration-guide.md`](cpp-integration-guide.md) — per-system setup steps, Blueprint children to create, usage patterns, and build order. See [`../checklists/cpp-blueprint-status.md`](../checklists/cpp-blueprint-status.md) for the full 135-system status grid. +4. **Implementing a system?** Read the Blueprint Spec in `docs/blueprints/` — every file has a Manual Implementation Guide with node-by-node logic. +5. **Need to understand internals?** Read the corresponding Developer Reference doc in this directory. +6. **Debugging?** Each category doc includes a data flow section showing how data moves between systems. +7. **Need UE5 Blueprint patterns?** See [`implementation-patterns.md`](implementation-patterns.md). +8. **Multiplayer networking?** See [`../architecture/multiplayer-networking.md`](../architecture/multiplayer-networking.md). Every doc has a Multiplayer Networking section. ## Relationship to Spec Files @@ -192,8 +192,8 @@ docs/developer/ | **Purpose** | Define what to build with node-by-node logic (v2.0) | Explain how it works (understanding) | | **Audience** | Implementers building Blueprints manually | Anyone needing to understand internals | | **Content** | Enums, structs, variables, functions, **Manual Implementation Guide** | Data flow, state machines, design rationale | -| **Format** | TEMPLATE.md v2.0 — includes Build Checklist | Per-category reference docs + project-setup-migration.md | +| **Format** | TEMPLATE.md v2.0 — includes Build Checklist | Per-category reference docs + cpp-integration-guide + project-setup-migration | --- -*Developer Reference Index v1.2 — Companion to the Blueprint Spec system. Update both together.* +*Developer Reference Index v1.4 — Companion to the Blueprint Spec system. Update both together.* diff --git a/docs/developer/cpp-integration-guide.md b/docs/developer/cpp-integration-guide.md new file mode 100644 index 0000000..c1fe0d1 --- /dev/null +++ b/docs/developer/cpp-integration-guide.md @@ -0,0 +1,626 @@ +# C++ Integration Guide — UE5 Modular Game Framework + +**Version:** 1.0 | **Generated:** 2026-05-20 | **Systems:** 12 C++ classes | **Pages:** Full per-system setup + +This guide covers every C++ class in `Source/Framework/`. For each system: what Blueprint child to create, what Project Settings to change, what assets to assign, and how other systems call into it. + +--- + +## Setup Before You Start + +### 1. Add Framework Module to Your Project + +In `Source/YourProject/YourProject.Build.cs`: +```csharp +PublicDependencyModuleNames.Add("Framework"); +``` + +In `Source/YourProject.Target.cs`: +```csharp +ExtraModuleNames.Add("Framework"); +``` + +### 2. Verify GameplayTags Plugin + +`YourProject.uproject` must include: +```json +"Plugins": [ + { "Name": "GameplayTags", "Enabled": true } +] +``` + +### 3. Create 11 Per-Category Data Tables + +Before any C++ code compiles usefully, create 11 Data Tables in `Content/Framework/Core/DataTables/` with Row Structure = `GameplayTagTableRow`. Register all 11 in `Project Settings → GameplayTags → Gameplay Tag Table List`. + +--- + +## System 01 — DA_GameTagRegistry + +### C++ Class +| | | +|---|---| +| **Header** | `Source/Framework/Public/Core/DA_GameTagRegistry.h` | +| **Source** | `Source/Framework/Private/Core/DA_GameTagRegistry.cpp` | +| **Parent** | `UPrimaryDataAsset` | +| **Blueprint Child** | **Not needed** — use directly as a Data Asset instance | + +### Data Asset Setup +1. Right-click in Content Browser → **Miscellaneous → Data Asset** +2. Class: `DA_GameTagRegistry` +3. Name: `DA_GameTagRegistry` +4. Save to: `Content/Framework/Core/` +5. Open the asset → assign the `TagDataTables` array with all 11 Data Tables + +### Usage Pattern +```cpp +// From any C++ code: +UDA_GameTagRegistry* Registry = LoadObject(...); + +// Validate a tag: +bool bValid = Registry->ValidateTag(SomeTag); + +// Get all tags: +TArray AllTags = Registry->GetAllRegisteredTags(); + +// Create tag from string: +FGameplayTag Tag = Registry->RequestTag(FName("Framework.Player.State.Alive")); +``` +```blueprint +// In Blueprint: Load Data Asset → cast to DA_GameTagRegistry → call functions +// All functions are BlueprintCallable/Pure — identical API to BP-only version +``` + +### Key Win vs Blueprint +The BP version required nested `ForEachLoop` over 11 Data Tables. C++ calls `UGameplayTagsManager::Get().RequestAllGameplayTags()` — one line. + +--- + +## System 02 — FL_GameUtilities + +### C++ Class +| | | +|---|---| +| **Header** | `Source/Framework/Public/Core/FL_GameUtilities.h` | +| **Source** | `Source/Framework/Private/Core/FL_GameUtilities.cpp` | +| **Parent** | `UBlueprintFunctionLibrary` | +| **Blueprint Child** | **None** — static function library, callable from anywhere | + +### Usage Pattern +```cpp +// Template subsystem access — single call replaces 3 BP nodes: +USS_SaveManager* SaveMgr = UFL_GameUtilities::GetSubsystemSafe(this); + +// Math: +float Remapped = UFL_GameUtilities::RemapFloat(0.5f, 0.0f, 1.0f, 0.0f, 100.0f); // → 50.0 + +// Tag creation: +FGameplayTag Tag = UFL_GameUtilities::MakeTagFromString(TEXT("Framework.Player.State.Alive")); + +// Debug (stripped from shipping): +UFL_GameUtilities::DebugLog(TEXT("Hello"), true, 5.0f, FColor::Green); +``` +```blueprint +// All UFUNCTIONS appear in Blueprint context menu under "Framework|Utilities" +// Template function not callable from BP — use "Get Game Framework" / "Get Subsystem by Class" nodes +``` + +### Key Win vs Blueprint +Replaces "Get Game Instance → Get Subsystem(Class)" chains everywhere with one template call. + +--- + +## System 03/04 — GI_GameFramework (I_InterfaceLibrary has no setup) + +### C++ Class +| | | +|---|---| +| **Header** | `Source/Framework/Public/Core/GI_GameFramework.h` | +| **Source** | `Source/Framework/Private/Core/GI_GameFramework.cpp` | +| **Parent** | `UGameInstance` | +| **Blueprint Child to Create** | `BP_GameFramework` (or use `GI_StarterGameInstance` BP for early prototyping) | + +### Project Settings +1. **Project Settings → Maps & Modes → Game Instance Class** → Set to your BP child of `GI_GameFramework` +2. Open the BP → Class Defaults → assign `TagRegistry` to the `DA_GameTagRegistry` Data Asset + +### Blueprint Child Setup +1. Create Blueprint Class → Parent: `GI_GameFramework` +2. Name: `BP_GameFramework` +3. In Class Defaults: + - `TagRegistry` → assign `DA_GameTagRegistry` + - `bValidateTagsOnInit` → `true` + - `bLogTagsOnInit` → `false` (true for debugging) + +### Usage Pattern +```cpp +// Get the framework from anywhere: +UGI_GameFramework* FW = Cast(GetGameInstance()); + +// Change game phase: +FW->SetGamePhase(EGamePhase::InGame); + +// Session flags: +FW->SetSessionFlag(Tag, true); +bool bFlag = FW->GetSessionFlag(Tag); + +// Type-safe subsystem access: +USS_SaveManager* Save = FW->GetService(); + +// Check if framework ready: +if (FW->IsFrameworkReady()) { ... } + +// Bind to dispatchers: +FW->OnFrameworkReady.AddDynamic(this, &UMyClass::OnReady); +FW->OnGamePhaseChanged.AddDynamic(this, &UMyClass::OnPhaseChange); +``` + +### Replace GI_StarterGameInstance +When ready for the full GameInstance: +1. Make `BP_GameFramework` your `Game Instance Class` in Project Settings +2. Update any `Cast to GI_StarterGameInstance` → `Cast to GI_GameFramework` +3. Both share the `OnFrameworkReady` dispatcher — bindings are compatible + +--- + +## System 05 — GM_CoreGameMode + +### C++ Class +| | | +|---|---| +| **Header** | `Source/Framework/Public/Core/GM_CoreGameMode.h` | +| **Source** | `Source/Framework/Private/Core/GM_CoreGameMode.cpp` | +| **Parent** | `AGameModeBase` | +| **Blueprint Child to Create** | `BP_CoreGameMode` | + +### Blueprint Child Setup +1. Create Blueprint Class → Parent: `GM_CoreGameMode` +2. Name: `BP_CoreGameMode` +3. In Class Defaults: + - `GameState Class` → your `BP_CoreGameState` + - `PlayerController Class` → your `BP_CorePlayerController` + - `Default Pawn Class` → your player pawn + - `HUD Class` → your `WBP_HUDController` + +### Project Settings +**Project Settings → Maps & Modes → Default GameMode** → `BP_CoreGameMode` + +### Usage Pattern +```cpp +AGM_CoreGameMode* GM = Cast(GetWorld()->GetAuthGameMode()); + +// Chapter transition: +GM->TransitionToChapter(ChapterTag); + +// Death routing: +GM->HandlePlayerDead(DeadController); + +// Ending trigger: +GM->TriggerEnding(EndingTag); + +// Pause check: +if (GM->bPauseAllowed) { /* show pause menu */ } +``` + +### Key Win vs Blueprint +Server-authoritative `HasAuthority()` gates are compile-time checked. Chapter transitions are level-agnostic (tag-driven, no hardcoded map names). + +--- + +## System 06 — GS_CoreGameState + +### C++ Class +| | | +|---|---| +| **Header** | `Source/Framework/Public/Core/GS_CoreGameState.h` | +| **Source** | `Source/Framework/Private/Core/GS_CoreGameState.cpp` | +| **Parent** | `AGameStateBase` | +| **Blueprint Child to Create** | `BP_CoreGameState` | + +### Usage Pattern +```cpp +AGS_CoreGameState* GS = GetGameState(); + +// Set chapter (server only — auto-replicates): +GS->SetChapter(ChapterTag); + +// Add objective: +GS->AddObjective(ObjectiveTag); + +// Bind to dispatchers: +GS->OnChapterChanged.AddDynamic(this, &UMyHUD::OnChapterChanged); +GS->OnObjectiveTagsChanged.AddDynamic(this, &UMyHUD::RefreshObjectives); +GS->OnEncounterActiveStateChanged.AddDynamic(this, &UMyHUD::OnEncounterToggle); +``` + +### Multiplayer +All 5 variables are fully replicated with `OnRep_` handlers. UI widgets bind to dispatchers — they fire for both local (server/listen-host) and remote (OnRep) clients with zero code changes. + +--- + +## System 07 — DA_ItemData + +### C++ Class +| | | +|---|---| +| **Header** | `Source/Framework/Public/Inventory/DA_ItemData.h` | +| **Source** | `Source/Framework/Private/Inventory/DA_ItemData.cpp` | +| **Parent** | `UPrimaryDataAsset` | +| **Blueprint Child** | **Not needed** — create Data Asset instances per item | + +### Data Asset Instance Setup +1. Right-click → **Miscellaneous → Data Asset** +2. Class: `DA_ItemData` +3. Name: `DA_Item_[Name]` (e.g. `DA_Item_MedKit`) +4. Fill in properties — the editor hides irrelevant fields based on `ItemType` + +### Editor UX Win +The C++ `EditCondition` metadata means: +- When `ItemType = Weapon`, EquipmentData shows (Damage, FireRate, MagazineSize...) +- When `ItemType = Consumable`, ConsumableData shows (HealthRestore, StressReduce...) +- When `bHasInspectMode = false`, InspectData is hidden entirely + +### Usage Pattern +```cpp +UDA_ItemData* Item = LoadObject(...); + +// Validate: +FString Errors; +if (!Item->ValidateItemData(Errors)) +{ + UE_LOG(..., Warning, TEXT("Item has errors: %s"), *Errors); +} + +// Read properties: +float Weight = Item->Weight; +int32 StackLimit = Item->StackLimit; +EItemType Type = Item->ItemType; +``` + +### Remaining BP to Create +- `DA_Item_*` instances — one per game item (content, not code) +- `WBP_InventoryMenu` (49) — uses `DA_ItemData` properties for display + +--- + +## System 31 — BPC_InventorySystem + +### C++ Class +| | | +|---|---| +| **Header** | `Source/Framework/Public/Inventory/BPC_InventorySystem.h` | +| **Source** | `Source/Framework/Private/Inventory/BPC_InventorySystem.cpp` | +| **Parent** | `UActorComponent` | +| **Blueprint Child to Create** | **None** — attach C++ component directly to player pawn | + +### Setup +1. Open your player pawn Blueprint +2. Add Component → `BPC_InventorySystem` +3. In component defaults: + - `Grid Width` → 8 + - `Grid Height` → 5 + - `Max Weight` → 50.0 + +### Usage Pattern +```cpp +UBPC_InventorySystem* Inv = GetOwner()->FindComponentByClass(); + +// Add item: +int32 Added = Inv->AddItem(ItemData, 5); + +// Check if we can pick up: +if (Inv->CanAddItem(ItemData, 1)) +{ + // Show pickup prompt +} + +// Query: +int32 Count = Inv->GetItemCount(ItemData); +TArray AllItems = Inv->GetAllItems(); +float RemainingWeight = Inv->GetRemainingWeight(); + +// Organize: +Inv->SortInventory(); +Inv->ConsolidateStacks(); + +// Bind: +Inv->OnInventoryChanged.AddDynamic(this, &UWBP_InventoryMenu::RefreshGrid); +Inv->OnItemAdded.AddDynamic(this, &UWBP_InventoryMenu::OnItemAddedAnim); +Inv->OnWeightChanged.AddDynamic(this, &UWBP_InventoryMenu::UpdateWeightBar); +``` + +### Key Win vs Blueprint +`SortInventory` uses `Algo::Sort` with a C++ lambda — instantaneous. BP array sort requires manual iteration and comparison nodes. `AddItem` stacks automatically — no BP branching for each stack check. + +--- + +## System 35 — SS_SaveManager + +### C++ Class +| | | +|---|---| +| **Header** | `Source/Framework/Public/Save/SS_SaveManager.h` | +| **Source** | `Source/Framework/Private/Save/SS_SaveManager.cpp` | +| **Parent** | `UGameInstanceSubsystem` | +| **Blueprint Child** | **None** — auto-initialized by UE's subsystem system | + +### No Manual Setup Required +`UGameInstanceSubsystem` auto-creates when `GI_GameFramework` initializes. No BP child, no spawn, no BeginPlay needed. + +### Usage Pattern +```cpp +USS_SaveManager* Save = UFL_GameUtilities::GetSubsystemSafe(this); + +// Save: +Save->SaveGame(0, TEXT("Chapter 3 — Laboratory")); + +// Load: +Save->LoadGame(0); + +// Quick save/load: +Save->QuickSave(); +Save->QuickLoad(); + +// Checkpoint: +Save->CreateCheckpoint(CheckpointTag); +Save->LoadCheckpoint(SlotIndex); + +// Manifest: +TArray Slots = Save->GetSlotManifest(); + +// Backup: +Save->BackupAllSaves(TEXT("Pre-Chapter4")); + +// Bind: +Save->OnSaveComplete.AddDynamic(this, &UMyClass::OnSaved); +Save->OnLoadComplete.AddDynamic(this, &UMyClass::OnLoaded); + +// Bind to manifest updates (when slots change): +Save->OnSaveManifestUpdated.AddDynamic(this, &UWBP_SaveMenu::RefreshSlotList); +``` + +### Key Win vs Blueprint +C++ uses `FArchive` for direct binary serialization. BP `Save Game`/`Load Game` nodes hide disk errors — C++ catches and reports them. `FMemoryWriter`/`FMemoryReader` is faster than BP serialization. + +--- + +## System 72 — BPC_DamageReceptionSystem + +### C++ Class +| | | +|---|---| +| **Header** | `Source/Framework/Public/Weapons/BPC_DamageReceptionSystem.h` | +| **Source** | `Source/Framework/Private/Weapons/BPC_DamageReceptionSystem.cpp` | +| **Parent** | `UActorComponent` | +| **Blueprint Child to Create** | **None** — attach to player and enemy pawns | + +### Setup +1. Open player pawn Blueprint (and enemy pawn Blueprint) +2. Add Component → `BPC_DamageReceptionSystem` +3. Optionally assign `EquipmentConfig` Data Asset for armor values + +### Usage Pattern +```cpp +UBPC_DamageReceptionSystem* Dmg = GetOwner()->FindComponentByClass(); + +// Apply damage (full pipeline: resistance → armor → shield → health → hit reaction): +float ActualDamage = Dmg->ApplyDamage( + 50.0f, // Raw damage + DamageCauser, // Who dealt it + DamageType, // Framework.Combat.Damage.Physical + HitLocation, // Where on the body + HitDirection // Direction of the hit +); + +// Preview damage (for UI): +float EffectiveResist = Dmg->CalculateResistance(DamageType); + +// Bind: +Dmg->OnDamageReceived.AddDynamic(this, &UMyClass::OnDamageReceived); +Dmg->OnStaggered.AddDynamic(this, &UMyClass::OnStaggered); +Dmg->OnKnockedDown.AddDynamic(this, &UMyClass::OnKnockedDown); +Dmg->OnDamageResisted.AddDynamic(this, &UMyClass::OnDamageResisted); +``` + +### Key Win vs Blueprint +The damage pipeline (resistance → multiplier → flat reduction → shield → health → hit reaction) is a single function call. In BP, this would be a 20+ node chain with multiple branches. + +--- + +## System 128 — SS_EnhancedInputManager + +### C++ Class +| | | +|---|---| +| **Header** | `Source/Framework/Public/Input/SS_EnhancedInputManager.h` | +| **Source** | `Source/Framework/Private/Input/SS_EnhancedInputManager.cpp` | +| **Parent** | `UGameInstanceSubsystem` | +| **Blueprint Child** | **None** — auto-initialized | + +### No Manual Setup Required +Auto-created by UE's subsystem system. No BP child needed. + +### Usage Pattern +```cpp +USS_EnhancedInputManager* Input = UFL_GameUtilities::GetSubsystemSafe(this); + +// Push context (e.g., when player hides): +Input->PushContext(IMC_Hiding, EInputContextPriority::Hiding, + FGameplayTag::RequestGameplayTag(FName("Framework.Input.Context.Hiding"))); + +// Pop context (e.g., when player exits hiding): +Input->PopContext(IMC_Hiding); + +// Switch to UI mode: +Input->SetInputMode(true, true); // UI mode, show cursor + +// Switch back to game mode: +Input->SetInputMode(false, false); + +// Rebind key: +Input->RebindKey(IA_Reload, EKeys::R); + +// Query: +bool bHidingActive = Input->IsContextActive(HidingTag); +float MoveValue = Input->GetActionValue(IA_Move); +bool bSprinting = Input->IsActionPressed(IA_Sprint); + +// Bind: +Input->OnContextPushed.AddDynamic(this, &UMyClass::OnContextPushed); +Input->OnContextPopped.AddDynamic(this, &UMyClass::OnContextPopped); +Input->OnInputModeChanged.AddDynamic(this, &UMyClass::OnInputModeChanged); +Input->OnKeyRebound.AddDynamic(this, &UMyClass::OnKeyRebound); +``` + +### Remaining BP to Create +- `IA_*` Input Action assets (one per gameplay action) +- `IMC_*` Input Mapping Context assets (groups of actions) +- `DA_InputMappingProfile` (129) — per-platform binding Data Asset + +--- + +## System 130 — BPC_StateManager + +### C++ Class +| | | +|---|---| +| **Header** | `Source/Framework/Public/Player/BPC_StateManager.h` | +| **Source** | `Source/Framework/Private/Player/BPC_StateManager.cpp` | +| **Parent** | `UActorComponent` | +| **Blueprint Child to Create** | **None** — attach C++ component directly | + +### Setup +1. Open your player pawn Blueprint +2. Add Component → `BPC_StateManager` +3. In component defaults: + - `Gating Table` → assign `DA_StateGatingTable` Data Asset + - `Default Action State` → `Framework.State.Action.Idle` + - `Heart Rate Smooth Speed` → 2.0 + +### Usage Pattern +```cpp +UBPC_StateManager* State = GetOwner()->FindComponentByClass(); + +// THE central query — every gameplay system calls this: +if (State->IsActionPermitted(ActionTag)) +{ + // Player can perform this action +} + +// Request state change: +EActionRequestResult Result = State->RequestStateChange(NewState, Requester); +switch (Result) +{ + case EActionRequestResult::Granted: /* proceed */ break; + case EActionRequestResult::Denied: /* gated */ break; + case EActionRequestResult::BlockedByForce: /* death/etc */ break; + case EActionRequestResult::AlreadyActive: /* no-op */ break; +} + +// Force state (death, cutscene, void space): +State->ForceStateChange(DeathTag, TEXT("Player died")); +// Later, on respawn: +State->RestorePreviousState(); + +// Vital signs: +float CurrentBPM = State->HeartRateBPM; +EHeartRateTier Tier = State->HeartRateTier; // Resting/Elevated/Stressed/Panic/Critical + +// Bind: +State->OnActionStateChanged.AddDynamic(this, &UMyClass::OnActionStateChanged); +State->OnOverlayStateChanged.AddDynamic(this, &UMyClass::OnOverlayStateChanged); +State->OnForceStackPushed.AddDynamic(this, &UMyClass::OnForceStackPushed); +State->OnForceStackPopped.AddDynamic(this, &UMyClass::OnForceStackPopped); +State->OnVitalSignChanged.AddDynamic(this, &UMyClass::OnVitalSignChanged); +``` + +### Key Win vs Blueprint +`IsActionPermitted()` is on the **hot path** — called potentially per-frame by 10+ systems. In C++, it's a native `TArray`/`TMap` lookup. In BP, it would be interpretive graph traversal each call. Heart rate smoothing is `FMath::FInterpTo` in tick — one native call vs BP interpolation nodes. + +### Remaining BP to Create +- `DA_StateGatingTable` (131) — 37 gating rules Data Asset + +--- + +## Quick Reference — C++ Class at a Glance + +| # | C++ Class | Parent | BP Child? | Project Settings Change? | +|---|-----------|--------|-----------|--------------------------| +| 01 | `UDA_GameTagRegistry` | `UPrimaryDataAsset` | No — use Data Asset instance | Register 11 Data Tables in GameplayTags | +| 02 | `UFL_GameUtilities` | `UBlueprintFunctionLibrary` | No — static library | None | +| 03 | 9 `UInterface`s | `UInterface` | No — implement on actors | None | +| 04 | `UGI_GameFramework` | `UGameInstance` | **Yes** — `BP_GameFramework` | Set as Game Instance Class | +| 05 | `AGM_CoreGameMode` | `AGameModeBase` | **Yes** — `BP_CoreGameMode` | Set as Default GameMode | +| 06 | `AGS_CoreGameState` | `AGameStateBase` | **Yes** — `BP_CoreGameState` | Set in GameMode defaults | +| 07 | `UDA_ItemData` | `UPrimaryDataAsset` | No — create per-item instances | None | +| 31 | `UBPC_InventorySystem` | `UActorComponent` | No — add to pawn directly | None | +| 35 | `USS_SaveManager` | `UGameInstanceSubsystem` | No — auto-created | None | +| 72 | `UBPC_DamageReceptionSystem` | `UActorComponent` | No — add to pawn/enemy | None | +| 128 | `USS_EnhancedInputManager` | `UGameInstanceSubsystem` | No — auto-created | None | +| 130 | `UBPC_StateManager` | `UActorComponent` | No — add to pawn directly | None | + +### What "No BP Child" Means + +Systems marked **"No — add to pawn directly"** mean you place the raw C++ component on your Blueprint pawn. The C++ class exposes all configuration via `EditAnywhere` properties — designers tweak those in the Details panel instead of a Blueprint child. + +Systems marked **"No — auto-created"** are `UGameInstanceSubsystem`s. UE creates them automatically when the GameInstance initializes. No spawning, no placement, no BeginPlay required. + +--- + +## Build Order (Dependency Chain) + +``` +1. DA_GameTagRegistry ← No dependencies (can build first) +2. I_InterfaceLibrary ← No dependencies +3. FL_GameUtilities ← Needs GI_GameFramework (forward declare ok) +4. GI_GameFramework ← Needs DA_GameTagRegistry +5. GM_CoreGameMode ← Needs GI_GameFramework +6. GS_CoreGameState ← Needs GI_GameFramework +7. DA_ItemData ← No C++ dependencies +8. BPC_InventorySystem ← Needs DA_ItemData +9. SS_SaveManager ← Needs GI_GameFramework +10. BPC_DamageReceptionSystem ← Needs DA_ItemData (EquipmentConfig) +11. SS_EnhancedInputManager ← No C++ framework deps (EnhancedInput plugin only) +12. BPC_StateManager ← Needs DA_StateGatingTable (stub) +``` + +--- + +## Blueprint Assets Still Required (Not Converted to C++) + +These Blueprint specs remain Blueprint-only. They have full spec files in `docs/blueprints/` with Manual Implementation Guides. + +### GameInstance Subsystems (auto-created, need BP children) +| # | System | BP to Create | C++ Status | +|---|--------|-------------|------------| +| 44 | `SS_UIManager` | `BP_UIManager` | C++ available (not in this batch — low priority) | +| 103 | `SS_AchievementSystem` | `BP_AchievementSystem` | C++ available (not in this batch) | +| 105 | `SS_SettingsSystem` | `BP_SettingsSystem` | C++ available (not in this batch) | +| 132 | `SS_AudioManager` | `BP_AudioManager` | C++ available (not in this batch) | + +### Actor Components (attach to pawn) +All 80 `BPC_*` specs except the 4 converted above remain Blueprint-only. Create BP children, attach to pawn. + +### Widgets (all 14 remain Blueprint — UMG is designed for BP) +| # | System | +|---|--------| +| 45-57 | All `WBP_*` widgets (HUD, menus, notifications, etc.) | +| 112-114 | Credits, Debug, Splash screens | + +### Data Assets (create instances, not children) +| # | System | +|---|--------| +| 115-127, 129, 131, 134-135 | All `DA_*` Data Asset definitions — create instances per content item | + +### Actors (create BP children) +| # | System | +|---|--------| +| 19, 20, 25, 37, 67, 69, 80, 81, 133 | All `BP_*` actors | + +### Interfaces +| 17 | `I_HidingSpot` — remains BP interface (simple, no C++ advantage) | +| 36 | `I_Persistable` — already in C++ `I_InterfaceLibrary.h` | + +--- + +*C++ Integration Guide v1.0 — Companion to Source/Framework/ source files.*