admin/UE5-Modular-Game-Framework
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update Developer Reference and add C++ Integration Guide

Browse Source 
- 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.
This commit is contained in:
Lefteris Notas
2026-05-20 15:16:32 +03:00
parent f6c4f44827
commit 4a7c871f29
3 changed files with 872 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

235
docs/checklists/cpp-blueprint-status.md Normal file
View File

@@ -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.*

22
docs/developer/INDEX.md
View File

@@ -1,6 +1,6 @@
# Developer Reference — UE5 Modular Game Framework # 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. 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 ├── INDEX.md ← THIS FILE
├── architecture-overview.md ← Framework-wide architecture walkthrough ├── architecture-overview.md ← Framework-wide architecture walkthrough
├── implementation-patterns.md ← Common UE5 Blueprint patterns used ├── implementation-patterns.md ← Common UE5 Blueprint patterns used
├── project-setup-migration.md ← Project setup & migration guide (NEW — Project Settings, plugins, init sequence) ├── cpp-integration-guide.md ← C++ per-system integration & setup (NEW — 12 systems)
│ ├── project-setup-migration.md ← Project setup & migration guide
├── 01-core-foundation.md ← Foundation systems (systems 01-07)
├── 00-starter-gameinstance.md ← Starter GameInstance: GI_StarterGameInstance setup guide ├── 00-starter-gameinstance.md ← Starter GameInstance: GI_StarterGameInstance setup guide
├── 02-player-systems.md ← Player state & embodiment (systems 08-15) ├── 02-player-systems.md ← Player state & embodiment (systems 08-15)
├── 03-interaction-systems.md ← Interaction & world manipulation (systems 16-23) ├── 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. 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. 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. 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. **Need to understand internals?** Read the corresponding Developer Reference doc in this directory. 4. **Implementing a system?** Read the Blueprint Spec in `docs/blueprints/` — every file has a Manual Implementation Guide with node-by-node logic.
5. **Debugging?** Each category doc includes a data flow section showing how data moves between systems. 5. **Need to understand internals?** Read the corresponding Developer Reference doc in this directory.
6. **Need UE5 Blueprint patterns?** See [`implementation-patterns.md`](implementation-patterns.md). 6. **Debugging?** Each category doc includes a data flow section showing how data moves between systems.
7. **Multiplayer networking?** See [`../architecture/multiplayer-networking.md`](../architecture/multiplayer-networking.md). Every doc has a Multiplayer Networking section. 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 ## 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) | | **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 | | **Audience** | Implementers building Blueprints manually | Anyone needing to understand internals |
| **Content** | Enums, structs, variables, functions, **Manual Implementation Guide** | Data flow, state machines, design rationale | | **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.*

626
docs/developer/cpp-integration-guide.md Normal file
View File

@@ -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<UDA_GameTagRegistry>(...);
// Validate a tag:
bool bValid = Registry->ValidateTag(SomeTag);
// Get all tags:
TArray<FGameplayTag> 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<USS_SaveManager>(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<UGI_GameFramework>(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<USS_SaveManager>();
// 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<AGM_CoreGameMode>(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<AGS_CoreGameState>();
// 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<UDA_ItemData>(...);
// 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<UBPC_InventorySystem>();
// 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<UDA_ItemData*> 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<USS_SaveManager>(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<FSaveSlotInfo> 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<UBPC_DamageReceptionSystem>();
// 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<USS_EnhancedInputManager>(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<UBPC_StateManager>();
// 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.*