# C++ Integration Guide — UE5 Modular Game Framework

**Version:** 1.1 | **Generated:** 2026-05-21 | **Systems:** 22 C++ classes (12 full + 10 stubs) | **Pages:** Full per-system setup

This guide covers every C++ class in `Source/PG_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.

---

## Quick Start — What to Do With Each C++ Class

If you just want to know what action to take for each C++ class, start here. Detailed setup follows in the per-system sections below.

| # | C++ Class | Status | **Exact Action to Take** |
|---|-----------|--------|--------------------------|
| 01 | `UDA_GameTagRegistry` | ✅ Full | Create a **Data Asset instance**: Right-click → Miscellaneous → Data Asset → pick `DA_GameTagRegistry`. Assign 11 Data Tables to `TagDataTables` array. |
| 02 | `UFL_GameUtilities` | ✅ Full | **Nothing.** Static library — functions appear under `Framework\|Utilities` in every BP right-click menu. |
| 03 | 9 `UInterface`s | ✅ Full | **Nothing to create.** On any BP actor: Class Settings → Interfaces → Add → type `UInteractable`, `UDamageable`, `ULockable`, etc. Events auto-appear. |
| 04 | `UGI_GameFramework` | ✅ Full | Create **BP child**: Blueprint Class → All Classes → `GI_GameFramework`. Set `TagRegistry` in Class Defaults. Assign in Project Settings as Game Instance Class. |
| 05 | `AGM_CoreGameMode` | ✅ Full | Create **BP child**: Blueprint Class → All Classes → `GM_CoreGameMode`. In Class Defaults → **"Classes"** section (inherited from AGameModeBase) → set all 4 class references. Assign in Project Settings as Default GameMode. |
| 06 | `AGS_CoreGameState` | ✅ Full | Create **BP child**: Blueprint Class → All Classes → `GS_CoreGameState`. No config needed — replicated state works automatically. |
| 07 | `UDA_ItemData` | ✅ Full | Create **Data Asset instances** (one per item): Right-click → Miscellaneous → Data Asset → `DA_ItemData`. Fill ItemTag, DisplayName, Icon, WorldMesh, Weight, ItemType, etc. See [game examples](../game/). |
| 08 | `UBPC_HealthSystem` | 🟡 Stub | Create **BP child** → attach to player pawn. C++ provides `MaxHealth`, `CurrentHealth`, `OnHealthChanged`, `OnDeath` dispatchers. Add `TakeDamage()`, `Heal()`, regen logic in BP. |
| 09 | `UBPC_StaminaSystem` | 🟡 Stub | Create **BP child** → attach to player pawn. C++ provides `MaxStamina`, `CurrentStamina`, `OnExhaustionStateChanged`. Add drain/regen/exhaustion logic in BP. |
| 10 | `UBPC_StressSystem` | 🟡 Stub | Create **BP child** → attach to player pawn. C++ provides `EStressTier` enum + `OnStressTierChanged` dispatcher. Add accumulation/decay/tier-transition logic in BP. |
| 11 | `UBPC_MovementStateSystem` | 🟡 Stub | Create **BP child** → attach to player pawn. C++ provides `CurrentMovementMode` GameplayTag + `OnMovementModeChanged` dispatcher. Add CMC reads, GASP bridge, posture detection in BP. |
| — | `APC_CoreController` | 🟡 Stub | Create **BP child** → set in `GM_CoreGameMode` Class Defaults. Add `BeginPlay`: cast to `GI_GameFramework` → `GetSubsystem<SS_EnhancedInputManager>` → `PushContext(IMC_Default)`. |
| — | `APS_CorePlayerState` | 🟡 Stub | Create **BP child** → set in `GM_CoreGameMode` Class Defaults. Add replicated variables (inventory, equipped items, narrative flags) with `OnRep_` handlers. |
| 31 | `UBPC_InventorySystem` | ✅ Full | **Attach directly to player pawn** — no BP child needed. Add Component → `BPC_InventorySystem`. Set `GridWidth=8`, `GridHeight=5`, `MaxWeight=50` in Details panel. |
| 35 | `USS_SaveManager` | ✅ Full | **Auto-created** by UE's subsystem system. Access from any BP: `FL_GameUtilities::GetSubsystemSafe<USS_SaveManager>()` or `Get Game Instance → Get Subsystem(SS_SaveManager)`. |
| 72 | `UBPC_DamageReceptionSystem` | ✅ Full | **Attach directly to player/enemy pawns** — no BP child needed. Add Component → `BPC_DamageReceptionSystem`. Call `ApplyDamage(RawDamage, Causer, DamageType, HitLocation, HitDirection)`. |
| 75 | `UBPC_HitReactionSystem` | 🟡 Stub | Create **BP child** → attach to player/enemy pawns. C++ provides `PlayHitReaction()` stub + `FlinchThreshold` + `RagdollThreshold`. Add animation selection/trigger logic in BP. |
| 79 | `UBPC_ShieldDefenseSystem` | 🟡 Stub | Create **BP child** → attach to player pawn. C++ provides `ShieldHealth`, `MaxShieldHealth`, `BlockAngle`, `bShieldBroken`. Add block/raise/lower/break logic in BP. |
| 120 | `UDA_EquipmentConfig` | 🟡 Stub | Create **Data Asset instances** (one per equipment piece). C++ provides `FDamageTypeResistance` struct + `GetResistance()` query. |
| 128 | `USS_EnhancedInputManager` | ✅ Full | **Auto-created** by UE. Access via `GetSubsystem<USS_EnhancedInputManager>()`. Call `PushContext()` / `PopContext()` / `SetInputMode()`. Create 22 IA_* + 5 IMC_* assets in editor. |
| 130 | `UBPC_StateManager` | ✅ Full | **Attach directly to player pawn** (component slot 0). Assign `GatingTable` → `DA_StateGatingTable`. Every system calls `IsActionPermitted(Tag)`. |
| 131 | `UDA_StateGatingTable` | 🟡 Stub | Create **Data Asset instance** — populate `GatingRules` with 37 rules (ActionTag, BlockedByState, bIsBlocked). C++ provides `FStateGatingRule` struct + `IsActionGated()`. |

### What "Full" vs "Stub" vs "Auto-Created" Means

| Term | Meaning | Example |
|------|---------|---------|
| **Full C++** | Complete gameplay logic compiled natively. The asset you create (BP child or Data Asset instance) is only for configuration — no logic to add. | `BPC_InventorySystem` — attach, set grid size, call `AddItem()` |
| **C++ Stub** | C++ has the UCLASS shell, basic variables, and event dispatchers so the module can compile (other classes forward-reference it). You must add all gameplay logic in the BP child. | `BPC_HealthSystem` — C++ gives you `MaxHealth` + `OnDeath`. You add `TakeDamage()`, regen, death sequence. |
| **Auto-Created** | `UGameInstanceSubsystem`. UE creates it automatically when GameInstance initializes. No spawning, no placement, no BP child needed. Access via `GetSubsystem<T>()`. | `SS_SaveManager`, `SS_EnhancedInputManager` |
| **Data Asset Instance** | Not a Blueprint at all. Right-click → Miscellaneous → Data Asset → pick the C++ class. Fill in properties. Systems reference it by pointer. | `DA_Item_MedKit`, `DA_StateGatingTable` |

### Interfaces: You Don't Build Them, You Implement Them

All 9 interfaces (`I_Interactable`, `I_Damageable`, `I_Persistable`, `I_Lockable`, `I_Holdable`, `I_UsableItem`, `I_Toggleable`, `I_Adjustable`, `I_Inspectable`) are in C++. You do **not** create Blueprint interface assets.

To use them on any BP actor:
1. **Class Settings → Interfaces → Add** → type `UInteractable` (or `UDamageable`, etc.)
2. **Compile** — the interface events appear in your Event Graph
3. Override `Interact`, `Can Interact`, `Get Interaction Prompt`, etc.

Other systems call these interfaces through C++ `BlueprintNativeEvent` functions — the framework never checks "Is this a BP_ItemPickup?" It checks "Does this implement I_Interactable?"

---

## Setup Before You Start

### 1. Add Framework Module to Your Project

In `Source/YourProject/YourProject.Build.cs`:
```csharp
PublicDependencyModuleNames.Add("PG_Framework");
```

In `Source/YourProject.Target.cs`:
```csharp
ExtraModuleNames.Add("PG_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/PG_Framework/Public/Core/DA_GameTagRegistry.h` |
| **Source** | `Source/PG_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/PG_Framework/Public/Core/FL_GameUtilities.h` |
| **Source** | `Source/PG_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/PG_Framework/Public/Core/GI_GameFramework.h` |
| **Source** | `Source/PG_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/PG_Framework/Public/Core/GM_CoreGameMode.h` |
| **Source** | `Source/PG_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 (Class Defaults → Classes section, inherited from `AGameModeBase`):
   - `Player Controller Class` → your `PC_CoreController` BP child
   - `Player State Class` → your `PS_CorePlayerState` BP child
   - `Game State Class` → your `BP_CoreGameState`
   - `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/PG_Framework/Public/Core/GS_CoreGameState.h` |
| **Source** | `Source/PG_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/PG_Framework/Public/Inventory/DA_ItemData.h` |
| **Source** | `Source/PG_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/PG_Framework/Public/Inventory/BPC_InventorySystem.h` |
| **Source** | `Source/PG_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/PG_Framework/Public/Save/SS_SaveManager.h` |
| **Source** | `Source/PG_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/PG_Framework/Public/Weapons/BPC_DamageReceptionSystem.h` |
| **Source** | `Source/PG_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/PG_Framework/Public/Input/SS_EnhancedInputManager.h` |
| **Source** | `Source/PG_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/PG_Framework/Public/Player/BPC_StateManager.h` |
| **Source** | `Source/PG_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
- **Data Asset instance:** `DA_StateGatingTable` — populate with 37 gating rules (C++ stub class is ready, create the asset instance)

---

## Stub Classes (UHT Resolution — 10 Systems)

These 10 classes are **forward-declared** in existing C++ headers as `TObjectPtr<>` or `TSubclassOf<>` UPROPERTY members. They must exist as C++ `UCLASS()` definitions for UHT to process the Framework module. The Blueprint child provides the actual runtime implementation.

### System 08 — BPC_HealthSystem

| | |
|---|---|
| **Header** | `Source/PG_Framework/Public/Player/BPC_HealthSystem.h` |
| **Source** | `Source/PG_Framework/Private/Player/BPC_HealthSystem.cpp` |
| **Parent** | `UActorComponent` |
| **Blueprint Child to Create** | `BPC_HealthSystem` — attach to player pawn, implement health logic |

Provides `CurrentHealth`, `MaxHealth`, `OnHealthChanged` dispatcher, `OnDeath` dispatcher. Referenced by `BPC_StateManager` (130) and `BPC_DamageReceptionSystem` (72).

### System 09 — BPC_StaminaSystem

| | |
|---|---|
| **Header** | `Source/PG_Framework/Public/Player/BPC_StaminaSystem.h` |
| **Source** | `Source/PG_Framework/Private/Player/BPC_StaminaSystem.cpp` |
| **Parent** | `UActorComponent` |
| **Blueprint Child to Create** | `BPC_StaminaSystem` — attach to player pawn |

Provides `CurrentStamina`, `MaxStamina`, `OnExhaustionStateChanged` dispatcher. Referenced by `BPC_StateManager` (130).

### System 10 — BPC_StressSystem

| | |
|---|---|
| **Header** | `Source/PG_Framework/Public/Player/BPC_StressSystem.h` |
| **Source** | `Source/PG_Framework/Private/Player/BPC_StressSystem.cpp` |
| **Parent** | `UActorComponent` |
| **Blueprint Child to Create** | `BPC_StressSystem` — attach to player pawn |

Provides `EStressTier` enum (Calm → Catatonic), `StressTier` property, `OnStressTierChanged` dispatcher. Referenced by `BPC_StateManager` (130).

### System 11 — BPC_MovementStateSystem

| | |
|---|---|
| **Header** | `Source/PG_Framework/Public/Player/BPC_MovementStateSystem.h` |
| **Source** | `Source/PG_Framework/Private/Player/BPC_MovementStateSystem.cpp` |
| **Parent** | `UActorComponent` |
| **Blueprint Child to Create** | `BPC_MovementStateSystem` — attach to player pawn |

Provides `CurrentMovementMode` (FGameplayTag), `OnMovementModeChanged` dispatcher. Referenced by `BPC_StateManager` (130).

### PC_CoreController / PS_CorePlayerState

| | APC_CoreController | APS_CorePlayerState |
|---|---|---|
| **Header** | `Public/Player/PC_CoreController.h` | `Public/Player/PS_CorePlayerState.h` |
| **Source** | `Private/Player/PC_CoreController.cpp` | `Private/Player/PS_CorePlayerState.cpp` |
| **Parent** | `APlayerController` | `APlayerState` |
| **Blueprint Child to Create** | `PC_CoreController` | `PS_CorePlayerState` |

Minimal stubs. Referenced as `TSubclassOf<>` in `GM_CoreGameMode` (05). Set your BP children as the default classes in `BP_CoreGameMode` Class Defaults.

### System 75 — BPC_HitReactionSystem

| | |
|---|---|
| **Header** | `Source/PG_Framework/Public/Weapons/BPC_HitReactionSystem.h` |
| **Source** | `Source/PG_Framework/Private/Weapons/BPC_HitReactionSystem.cpp` |
| **Parent** | `UActorComponent` |
| **Blueprint Child to Create** | `BPC_HitReactionSystem` — attach to player and enemy pawns |

Provides `PlayHitReaction()` stub, `FlinchThreshold`, `RagdollThreshold`. Referenced by `BPC_DamageReceptionSystem` (72).

### System 79 — BPC_ShieldDefenseSystem

| | |
|---|---|
| **Header** | `Source/PG_Framework/Public/Weapons/BPC_ShieldDefenseSystem.h` |
| **Source** | `Source/PG_Framework/Private/Weapons/BPC_ShieldDefenseSystem.cpp` |
| **Parent** | `UActorComponent` |
| **Blueprint Child to Create** | `BPC_ShieldDefenseSystem` — attach to player pawn |

Provides `ShieldHealth`, `MaxShieldHealth`, `BlockAngle`, `bShieldBroken`. Referenced by `BPC_DamageReceptionSystem` (72).

### System 120 — DA_EquipmentConfig

| | |
|---|---|
| **Header** | `Source/PG_Framework/Public/Inventory/DA_EquipmentConfig.h` |
| **Source** | `Source/PG_Framework/Private/Inventory/DA_EquipmentConfig.cpp` |
| **Parent** | `UPrimaryDataAsset` |
| **Blueprint Child** | **Not needed** — create Data Asset instances per equipment item |

Provides `FDamageTypeResistance` struct array, `Durability`, `Weight`, `GetResistance()` query. Referenced by `BPC_DamageReceptionSystem` (72).

### System 131 — DA_StateGatingTable

| | |
|---|---|
| **Header** | `Source/PG_Framework/Public/State/DA_StateGatingTable.h` |
| **Source** | `Source/PG_Framework/Private/State/DA_StateGatingTable.cpp` |
| **Parent** | `UPrimaryDataAsset` |
| **Blueprint Child** | **Not needed** — create one Data Asset instance with 37 gating rules |

Provides `FStateGatingRule` struct (ActionTag, BlockedByState, bIsBlocked), `IsActionGated()` query. Referenced by `BPC_StateManager` (130).

---

## 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 |
| 08 | `UBPC_HealthSystem` | `UActorComponent` | **Yes** — BP child implements logic | None |
| 09 | `UBPC_StaminaSystem` | `UActorComponent` | **Yes** — BP child implements logic | None |
| 10 | `UBPC_StressSystem` | `UActorComponent` | **Yes** — BP child implements logic | None |
| 11 | `UBPC_MovementStateSystem` | `UActorComponent` | **Yes** — BP child implements logic | 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 |
| 75 | `UBPC_HitReactionSystem` | `UActorComponent` | **Yes** — BP child implements logic | None |
| 79 | `UBPC_ShieldDefenseSystem` | `UActorComponent` | **Yes** — BP child implements logic | None |
| 120 | `UDA_EquipmentConfig` | `UPrimaryDataAsset` | No — create per-item instances | None |
| 128 | `USS_EnhancedInputManager` | `UGameInstanceSubsystem` | No — auto-created | None |
| 130 | `UBPC_StateManager` | `UActorComponent` | No — add to pawn directly | None |
| 131 | `UDA_StateGatingTable` | `UPrimaryDataAsset` | No — create one Data Asset instance | None |
| — | `APC_CoreController` | `APlayerController` | **Yes** — `PC_CoreController` BP child | Set in GameMode defaults |
| — | `APS_CorePlayerState` | `APlayerState` | **Yes** — `PS_CorePlayerState` BP child | Set in GameMode defaults |

### 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.

Systems marked **"Yes — BP child implements logic"** are C++ stubs that exist solely for UHT resolution. The stubs provide the necessary UCLASS definition and basic properties/dispatchers. The full gameplay logic lives in the Blueprint child.

---

## 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_HealthSystem (stub)        ← No C++ dependencies
 9. BPC_StaminaSystem (stub)       ← No C++ dependencies
10. BPC_StressSystem (stub)        ← No C++ dependencies
11. BPC_MovementStateSystem (stub) ← No C++ dependencies
12. PC_CoreController / PS_CorePlayerState (stubs) ← No C++ dependencies
13. DA_EquipmentConfig (stub)      ← No C++ dependencies
14. BPC_InventorySystem            ← Needs DA_ItemData
15. SS_SaveManager                 ← Needs GI_GameFramework
16. BPC_DamageReceptionSystem     ← Needs DA_EquipmentConfig, DA_ItemData
17. BPC_HitReactionSystem (stub)   ← No C++ dependencies
18. BPC_ShieldDefenseSystem (stub) ← No C++ dependencies
19. SS_EnhancedInputManager       ← No C++ framework deps (EnhancedInput plugin only)
20. BPC_StateManager              ← Needs DA_StateGatingTable, BPC_HealthSystem, BPC_StaminaSystem, BPC_StressSystem, BPC_MovementStateSystem
21. DA_StateGatingTable (stub)     ← No C++ dependencies
```

**Note:** Stub classes have zero C++ dependencies and can be built in any order before the systems that reference them. Build them first to satisfy UHT forward-declaration resolution.

---

## 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 `BPC_*` specs except the 4 fully converted C++ classes (InventorySystem, DamageReceptionSystem, StateManager, EnhancedInputManager) and the 8 stub classes listed 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/PG_Framework/ source files.*
