# Project Prototype Guide — PG_Framework Testing Setup

**Version:** 1.0 | **Target UE:** 5.5–5.7 | **C++ Module:** PG_Framework

This guide walks you through creating a minimal playable prototype in UE5 that tests the PG_Framework C++ source. By the end, you'll have a character that can move, take damage, manage inventory, and respond to state gating — all powered by the framework's C++ classes.

**Goal:** A working prototype you can expand with additional Blueprint components.

**Time estimate:** 2-4 hours for a developer familiar with UE5.

---

## Table of Contents

1. [Project Creation](#1-project-creation)
2. [C++ Module Integration](#2-c-module-integration)
3. [Gameplay Tags Setup](#3-gameplay-tags-setup)
4. [Foundation Blueprint Assets](#4-foundation-blueprint-assets)
5. [Player Pawn Assembly](#5-player-pawn-assembly)
6. [Input System Setup](#6-input-system-setup)
7. [State Management Wiring](#7-state-management-wiring)
8. [Test Level Setup](#8-test-level-setup)
9. [Data Asset Content](#9-data-asset-content)
10. [Verification Checklist](#10-verification-checklist)
11. [Next Steps — Expanding the Prototype](#11-next-steps--expanding-the-prototype)
12. [Troubleshooting](#12-troubleshooting)

---

## 1. Project Creation

### 1.1 Create New Project

1. Launch **UE5.5+** → **Games** → **Blank (C++)**
2. Project Name: `PG_Prototype` (or your choice)
3. Location: Anywhere outside the PG_Framework workspace
4. **Disable** Starter Content (we use framework assets)
5. **Enable** Raytracing: No (unless you need it)
6. Target Platform: Desktop
7. Quality Preset: Scalable

### 1.2 Enable Required Plugins

After the project opens:
1. `Edit → Plugins`
2. Search and enable:
   - ✅ **Enhanced Input** (Input category)
   - ✅ **GameplayTags** (should be on by default)
   - ✅ **Motion Warping** (Animation category — needed for traversal later)
3. Restart Editor when prompted.

### 1.3 Close the Editor

We need to add the PG_Framework module. Keep the project folder open in Explorer.

---

## 2. C++ Module Integration

### 2.1 Copy Source Files

Copy the entire `Source/PG_Framework/` directory from your PG_Framework workspace into your prototype project:

```
PG_Prototype/
├── Source/
│   ├── PG_Prototype/          ← Your project's module (keep)
│   ├── PG_Framework/          ← COPY from PG_Framework workspace
│   │   ├── PG_Framework.Build.cs
│   │   ├── PG_Framework.Target.cs
│   │   ├── PG_FrameworkEditor.Target.cs
│   │   ├── PG_Framework.h
│   │   ├── PG_Framework.cpp
│   │   ├── Public/
│   │   │   ├── Core/          (GI_GameFramework, GM_CoreGameMode, etc.)
│   │   │   ├── Player/        (BPC_HealthSystem, BPC_StateManager, etc.)
│   │   │   ├── Inventory/     (BPC_InventorySystem, DA_ItemData, etc.)
│   │   │   ├── Weapons/       (BPC_DamageReceptionSystem, etc.)
│   │   │   ├── Save/          (SS_SaveManager)
│   │   │   ├── Input/         (SS_EnhancedInputManager)
│   │   │   └── State/         (DA_StateGatingTable)
│   │   └── Private/
│   │       └── ...            (mirrors Public/ structure)
│   └── PG_PrototypeEditor.Target.cs
```

### 2.2 Add Module Dependency

Edit `Source/PG_Prototype/PG_Prototype.Build.cs`:

```csharp
// Find the PublicDependencyModuleNames array and add:
PublicDependencyModuleNames.AddRange(new string[] {
    "Core",
    "CoreUObject",
    "Engine",
    "InputCore",
    "EnhancedInput",      // Required by SS_EnhancedInputManager
    "GameplayTags",       // Required by all framework systems
    "PG_Framework"        // ← ADD THIS LINE
});
```

### 2.3 Register Module in Target

Edit `Source/PG_Prototype.Target.cs`:

```csharp
ExtraModuleNames.AddRange(new string[] {
    "PG_Prototype",
    "PG_Framework"     // ← ADD THIS LINE
});
```

### 2.4 Build

1. Right-click `PG_Prototype.uproject` → **Generate Visual Studio project files**
2. Open the `.sln` in your IDE, or right-click `.uproject` → **Switch Unreal Engine Version** if needed
3. Build from IDE, or open the project and let UE5 compile

If you get compile errors about missing includes, ensure `EnhancedInput` and `GameplayTags` are in the `PublicDependencyModuleNames` of `PG_Framework.Build.cs` (they should already be):

```csharp
// PG_Framework.Build.cs should contain:
PublicDependencyModuleNames.AddRange(new string[] {
    "Core",
    "CoreUObject",
    "Engine",
    "EnhancedInput",
    "GameplayTags",
    "InputCore"
});
```

### 2.5 Verify Compilation

After the project opens, check `Window → Developer Tools → Modules` and confirm `PG_Framework` appears as loaded.

---

## 3. Gameplay Tags Setup

### 3.1 Create Data Table Assets from CSV

For each CSV file in `docs/blueprints/01-core/data-tables/`, create a Data Table asset:

1. `Content Browser → Framework/DataTables/` (create folder if needed)
2. Right-click → **Miscellaneous → Data Table**
3. Row Structure: `GameplayTagTableRow`
4. Name: `DT_Tags_[Category]` (e.g., `DT_Tags_Player`)
5. Open the Data Table → **Import** → select the corresponding CSV

Repeat for all 11:

| File | Data Table Name |
|------|----------------|
| `DT_Tags_Player.csv` | `DT_Tags_Player` |
| `DT_Tags_Interaction.csv` | `DT_Tags_Interaction` |
| `DT_Tags_Item.csv` | `DT_Tags_Item` |
| `DT_Tags_Narrative.csv` | `DT_Tags_Narrative` |
| `DT_Tags_AI.csv` | `DT_Tags_AI` |
| `DT_Tags_Save.csv` | `DT_Tags_Save` |
| `DT_Tags_Environment.csv` | `DT_Tags_Environment` |
| `DT_Tags_Combat.csv` | `DT_Tags_Combat` |
| `DT_Tags_State.csv` | `DT_Tags_State` |
| `DT_Tags_Audio.csv` | `DT_Tags_Audio` |
| `DT_Tags_Achievement.csv` | `DT_Tags_Achievement` |

### 3.2 Register Data Tables in Project Settings

1. `Edit → Project Settings → Gameplay Tags`
2. Under **Gameplay Tag Table List**, click `+` eleven times
3. For each entry, click the dropdown and select one of the 11 `DT_Tags_*` tables
4. **Click the refresh icon** next to "Import Tags from Config" to force tag load
5. Verify: Type `Framework.Player.State.Alive` in the search bar at the bottom → it should appear as a valid tag

> **⚠️ Without this step**, no gameplay tags work. Framework tags will be invalid.

---

## 4. Foundation Blueprint Assets

### 4.1 Create DA_GameTagRegistry Data Asset

1. `Content Browser → Framework/Core/`
2. Right-click → **Miscellaneous → Data Asset**
3. Class: `DA_GameTagRegistry`
4. Name: `DA_GameTagRegistry`
5. Open it → assign the `Tag Data Tables` array:
   - Click `+` 11 times
   - Add each of the 11 `DT_Tags_*` Data Tables
6. Save

### 4.2 Create BP_GameFramework (GameInstance)

1. `Content Browser → Framework/Core/`
2. Right-click → **Blueprint Class**
3. Parent: `GI_GameFramework`
4. Name: `BP_GameFramework`
5. Open it → **Class Defaults**:
   - `Tag Registry` → `DA_GameTagRegistry`
   - `bValidateTagsOnInit` → `true`
   - `bLogTagsOnInit` → `true` (useful for debugging first boot)
6. Compile → Save

### 4.3 Create PC_CoreController and PS_CorePlayerState

1. Create Blueprint Class → Parent: `APC_CoreController` → name: `PC_CoreController`
2. Create Blueprint Class → Parent: `APS_CorePlayerState` → name: `PS_CorePlayerState`
3. Save both to `Content/Framework/Player/`

These are C++ stubs. For the prototype, they can be empty — expand later with input routing and replicated state.

### 4.4 Create BP_CoreGameState

1. Create Blueprint Class → Parent: `AGS_CoreGameState` → name: `BP_CoreGameState`
2. Save to `Content/Framework/Core/`
3. No extra config — all state is replicated automatically.

### 4.5 Create BP_CoreGameMode

1. Create Blueprint Class → Parent: `AGM_CoreGameMode` → name: `BP_CoreGameMode`
2. Save to `Content/Framework/Core/`
3. Open → **Class Defaults**:
   - `Game State Class` → `BP_CoreGameState`
   - `Player Controller Class` → `PC_CoreController`
   - `Player State Class` → `PS_CorePlayerState`
   - `Default Pawn Class` → (leave empty for now — we'll set it after creating the player pawn)
4. Compile → Save

### 4.6 Set Project Defaults

`Edit → Project Settings → Maps & Modes`:

| Setting | Value |
|---------|-------|
| Default GameMode | `BP_CoreGameMode` |
| Game Instance Class | `BP_GameFramework` |
| Editor Startup Map | Your test level (create later) |
| Game Default Map | Your test level |

---

## 5. Player Pawn Assembly

### 5.1 Create Player Pawn Blueprint

1. `Content Browser → Framework/Player/`
2. Right-click → **Blueprint Class**
3. Parent: `Character`
4. Name: `BP_PlayerCharacter`
5. Open the Blueprint

### 5.2 Attach Required Components

In the Components panel of `BP_PlayerCharacter`, add these in order:

**Tier 1 — State & Core (must load first):**
| Order | Component Class | Variable Name |
|-------|----------------|---------------|
| 1 | **BPC_StateManager** | `StateManager` |
| 2 | **BPC_HealthSystem** | `HealthSystem` |
| 3 | **BPC_StaminaSystem** | `StaminaSystem` |
| 4 | **BPC_StressSystem** | `StressSystem` |
| 5 | **BPC_MovementStateSystem** | `MovementStateSystem` |
| 6 | **BPC_InventorySystem** | `InventorySystem` |

**Tier 2 — Combat:**
| 7 | **BPC_DamageReceptionSystem** | `DamageReceptionSystem` |
| 8 | **BPC_ShieldDefenseSystem** | `ShieldDefenseSystem` |
| 9 | **BPC_HitReactionSystem** | `HitReactionSystem` |

**Tier 3 — Interaction (add as needed):**
| 10 | **BPC_InteractionDetector** | (create BP child from spec #16 later) |
| 11 | **BPC_HidingSystem** | (create BP child from spec #12 later) |

### 5.3 Configure Component Defaults

Select each component in the Components panel and set its defaults:

**State Manager:**
- `Gating Table` → (will assign DA_StateGatingTable — create it in Step 7 first)
- `Default Action State` → `Framework.State.Action.Idle`
- `Default Overlay State` → (leave empty)
- `Heart Rate Smooth Speed` → `2.0`

**Health System:**
- `Max Health` → `100.0`

**Stamina System:**
- `Max Stamina` → `100.0`

**Stress System:**
- `Stress Tier` → `Calm`

**Inventory System:**
- `Grid Width` → `8`
- `Grid Height` → `5`
- `Max Weight` → `50.0`

**Damage Reception System:**
- `Base Resistance` → `0.0`
- `Stagger Threshold` → `20.0`
- `Knockdown Threshold` → `50.0`

### 5.4 Create Player Pawn Blueprint (GASP-Free Baseline)

For the prototype you can use the default UE5 `CharacterMovementComponent` — no GASP needed:

1. Compile `BP_PlayerCharacter`
2. The default CharacterMovement settings are fine for testing

### 5.5 Assign Pawn to GameMode

1. Open `BP_CoreGameMode` → Class Defaults
2. `Default Pawn Class` → `BP_PlayerCharacter`
3. Save

---

## 6. Input System Setup

### 6.1 Create Input Action Assets

`Content Browser → Framework/Input/Actions/` (create folders)

Right-click → **Input → Input Action**, create these minimum actions for the prototype:

| Input Action | Value Type | Purpose |
|-------------|-----------|---------|
| `IA_Move` | Axis2D (Vector2D) | WASD movement |
| `IA_Look` | Axis2D (Vector2D) | Mouse look |
| `IA_Jump` | Digital (bool) | Jump |
| `IA_Sprint` | Digital (bool) | Sprint (stamina drain) |
| `IA_Interact` | Digital (bool) | Interaction (E key) |
| `IA_Fire` | Digital (bool) | Weapon fire (testing damage) |
| `IA_Inventory` | Digital (bool) | Inventory toggle |
| `IA_Pause` | Digital (bool) | Pause menu |

### 6.2 Create Input Mapping Context

`Content Browser → Framework/Input/Contexts/`

Right-click → **Input → Input Mapping Context**, name: `IMC_Default`

Add mappings:

| Input Action | Key Binding | Triggers |
|-------------|-------------|----------|
| `IA_Move` | W, A, S, D (2D axis: W=Y+, S=Y-, D=X+, A=X-) | Down trigger |
| `IA_Look` | Mouse XY 2D Axis | Down trigger |
| `IA_Jump` | Space Bar | Pressed trigger |
| `IA_Sprint` | Left Shift | Pressed + Released triggers |
| `IA_Interact` | E | Pressed trigger |
| `IA_Fire` | Left Mouse Button | Pressed trigger |
| `IA_Inventory` | Tab | Pressed trigger |
| `IA_Pause` | Escape | Pressed trigger |

### 6.3 Wire Input in PC_CoreController

Open `PC_CoreController` Blueprint → **Event Graph**:

```
Event BeginPlay
  → Get Game Instance → Cast To BP_GameFramework
  → Get Subsystem (Class: SS_EnhancedInputManager) [if not auto-created, use GetSubsystemSafe]
  → Push Context (IMC_Default, Priority: 0, Tag: Framework.Input.Context.Default)
```

> **Note:** `SS_EnhancedInputManager` is auto-created by UE. At `BeginPlay`, call `GetSubsystem<USS_EnhancedInputManager>()` from the GameInstance and push `IMC_Default`.

### 6.4 Wire Movement in PlayerCharacter

Open `BP_PlayerCharacter` → **Event Graph**:

```
Event Setup Player Input Component
  → Get Enhanced Input Local Player Subsystem (from PlayerController)
  → Bind Action (IA_Move, Triggered → call "Add Movement Input" using ActionValue)
  → Bind Action (IA_Look, Triggered → call "Add Controller Yaw/Pitch Input")
  → Bind Action (IA_Jump, Started → call "Jump")
  → Bind Action (IA_Jump, Completed → call "Stop Jumping")
```

Basic movement setup — see the Enhanced Input documentation for details.

---

## 7. State Management Wiring

### 7.1 Create DA_StateGatingTable

1. `Content Browser → Framework/State/`
2. Right-click → **Miscellaneous → Data Asset**
3. Class: `DA_StateGatingTable`
4. Name: `DA_StateGatingTable`
5. Open → populate `Gating Rules` array with rules.

**Minimum rules for prototype:**

| # | Action Tag | Blocked By State | Is Blocked? |
|---|-----------|-----------------|-------------|
| 1 | `Framework.Action.Sprint` | `Framework.State.Action.Dead` | ✅ true |
| 2 | `Framework.Action.Sprint` | `Framework.State.Action.Hiding` | ✅ true |
| 3 | `Framework.Action.Jump` | `Framework.State.Action.Dead` | ✅ true |
| 4 | `Framework.Action.Interact` | `Framework.State.Action.Dead` | ✅ true |
| 5 | `Framework.Action.FireWeapon` | `Framework.State.Action.Dead` | ✅ true |
| 6 | `Framework.Action.FireWeapon` | `Framework.State.Action.Hiding` | ✅ true |
| 7 | `Framework.Action.Reload` | `Framework.State.Action.Dead` | ✅ true |
| 8 | `Framework.Action.UseItem` | `Framework.State.Action.Dead` | ✅ true |

> Full 37-rule table: see `docs/architecture/bpc-statemanager.md` Section 9.

### 7.2 Assign Gating Table

1. Open `BP_PlayerCharacter`
2. Select `StateManager` component
3. `Gating Table` → `DA_StateGatingTable`
4. Compile → Save

### 7.3 Create State Manager Enums & Structs

In `Content/Framework/State/`:

**Enum: E_PlayerActionState** (42 values)
```
Idle, Moving, Sprinting, Crouching, Prone, Jumping, Falling, Landing,
Swimming, Climbing, Vaulting, Mantling, Sliding, Squeezing,
Interacting, Inspecting, UsingItem, Equipping, PickingUp,
Hiding, Peeking, HoldingBreath,
Attacking, Aiming, Firing, Reloading, Blocking, Throwing,
Staggered, KnockedDown, Dead, Respawning,
InCutscene, InDialogue, InMenu,
Pushing, Pulling, Dragging,
Stunned, Frozen, Trapped, Carrying
```

**Enum: E_OverlayState** (18 values)
```
None, AimingDownSights, Reloading, Inspecting, UsingItem,
Flashlight, Wristwatch, Map, Radio, Compass,
HoldingWeapon, HoldingTool, HoldingThrowable,
CarryingObject, InjuredLeftArm, InjuredRightArm,
TalkingOnRadio, ReadingDocument
```

**Enum: E_ActionRequestResult** (8 values)
```
Granted, Denied, BlockedByForce, AlreadyActive,
InvalidState, RequesterNotFound, CooldownActive, VitalThreshold
```

**Struct: S_StateGatingRule**
```
ActionTag : GameplayTag
BlockedByState : GameplayTag
bIsBlocked : Boolean
```

### 7.4 Verify StateManager at Runtime

Add this to `BP_PlayerCharacter` BeginPlay:

```
Event BeginPlay
  → Get StateManager component
  → Print String (concat "StateManager Ready. Default: " + Current Action State → ToString)
  → Bind OnActionStateChanged → Print String ("Action state changed: " + NewState)
```

---

## 8. Test Level Setup

### 8.1 Create Test Level

1. `File → New Level → Empty Level`
2. Save as `Content/Maps/L_PrototypeTest`

### 8.2 Place Required Actors

| Actor | Type | Notes |
|-------|------|-------|
| **Player Start** | `PlayerStart` | Drag from Place Actors panel |
| **Directional Light** | `DirectionalLight` | Default one is fine |
| **Sky Light** | `SkyLight` | Default one is fine |
| **Sky Atmosphere** | `SkyAtmosphere` | For realistic sky |
| **Exponential Height Fog** | `ExponentialHeightFog` | Atmosphere depth |
| **Floor** | `StaticMesh` → Cube | Scale to X=50, Y=50, Z=0.1 for a ground plane |
| **Volumetric Clouds** | `VolumetricCloud` | Optional — visual polish |

### 8.3 Add Test Objects

For testing interaction, place a simple cube or a `BP_DoorActor` (create from spec #19):

1. Place a Static Mesh (Cube) in the level
2. Scale to represent a door: X=0.2, Y=3, Z=4
3. For the prototype, just test that interaction raycasts hit it

### 8.4 Set as Startup Map

1. `Edit → Project Settings → Maps & Modes`
2. `Editor Startup Map` → `L_PrototypeTest`
3. `Game Default Map` → `L_PrototypeTest`

---

## 9. Data Asset Content

### 9.1 Create Test Items

In `Content/Framework/DataAssets/Items/`:

1. Right-click → **Miscellaneous → Data Asset**
2. Class: `DA_ItemData`
3. Name: `DA_Item_TestMedKit`

Set properties:

| Property | Value |
|----------|-------|
| Item Tag | `Framework.Item.Consumable.MedKit` |
| Display Name | "MedKit" |
| Description | "A standard medical kit. Restores 25 health." |
| Weight | 1.0 |
| Stack Limit | 5 |
| Item Type | Consumable |
| Consumable Data → Health Restore | 25.0 |
| Consumable Data → Use Duration | 2.0 |
| Consumable Data → Consumed on Use | true |

Create a second item for testing inventory:

| Property | Value |
|----------|-------|
| Item Tag | `Framework.Item.Key.RustyKey` |
| Display Name | "Rusty Key" |
| Description | "An old rusted key. Might open something nearby." |
| Weight | 0.5 |
| Stack Limit | 1 |
| Item Type | Key Item |
| bIsKeyItem | true |

### 9.2 Create DA_EquipmentConfig (for armor testing)

1. Right-click → **Miscellaneous → Data Asset**
2. Class: `DA_EquipmentConfig`
3. Name: `DA_Equipment_DefaultArmor`

Set:

| Property | Value |
|----------|-------|
| Durability | 100.0 |
| Weight | 5.0 |
| Damage Type Resistances | Array[0] → Damage Type: `Framework.Combat.Damage.Physical`, Resistance: 0.2 |

### 9.3 Place Item Pickup in Level

1. Create Blueprint Class → Parent: `BP_ItemPickup` (per spec #25)
2. Or for quick test: place a simple `StaticMeshActor` with a Cube mesh, add `I_Interactable` interface later

---

## 10. Verification Checklist

Run **Play In Editor (PIE)** and verify:

### Core Systems
- [ ] Editor opens without asset-loading errors
- [ ] `Output Log` shows: "GI_GameFramework: Framework initialized. X tags validated."
- [ ] `Output Log` shows: "StateManager: Loaded gating table with N rules."
- [ ] No `GetSubsystem()` null pointer errors in log

### Player Movement
- [ ] WASD moves the character
- [ ] Mouse rotates the camera
- [ ] Space bar makes the character jump
- [ ] Left Shift enables sprint (movement speed increases)

### State Manager
- [ ] Print String shows "StateManager Ready. Default: Framework.State.Action.Idle"
- [ ] `Is Action Permitted(Framework.Action.Sprint)` returns true when idle
- [ ] Force a state change → verify dispatcher fires

### Health / Damage
- [ ] `BPC_HealthSystem` component is valid (not null)
- [ ] Call `Apply Damage` from a cheat / debug key → health decreases
- [ ] OnHealthChanged dispatcher fires
- [ ] Health reaches 0 → OnDeath fires (if wired)

### Inventory
- [ ] `BPC_InventorySystem` component is valid
- [ ] Call `Add Item(DA_Item_TestMedKit, 3)` → success
- [ ] `Get Item Count` returns 3
- [ ] `Get All Items` returns array with MedKit
- [ ] `Get Remaining Weight` decreases by 3.0

### Save/Load
- [ ] `Get Subsystem(SS_SaveManager)` returns a valid reference
- [ ] `Quick Save` → completes without error
- [ ] `Get Slot Manifest` shows slot 0 as non-empty
- [ ] `Quick Load` → restores game state

### Input Manager
- [ ] `SS_EnhancedInputManager` is valid
- [ ] `Is Context Active(Framework.Input.Context.Default)` returns true
- [ ] `Get Top Context` returns Default context tag

### Gameplay Tags
- [ ] `DA_GameTagRegistry.Validate Tag(Framework.Player.State.Alive)` returns true
- [ ] `Get All Registered Tags` returns non-empty array
- [ ] Tag `Framework.Player.State.Alive` is in the returned array

### State Gating
- [ ] `StateManager.Is Action Permitted(Framework.Action.FireWeapon)` returns true (when idle)
- [ ] After death: `Is Action Permitted(Framework.Action.FireWeapon)` returns false
- [ ] After respawn: permissions restore

---

## 11. Next Steps — Expanding the Prototype

Once the core loop works, build these additional systems in priority order:

### Priority 1 — Make It Playable
1. Build `BPC_InteractionDetector` (spec #16) — raycast to interactables, show prompts
2. Build `BP_ItemPickup` (spec #25) — place items in world, pick them up
3. Build `WBP_HUDController` (spec #47) — health/stamina/stress bars on screen
4. Wire health damage to screen effects (red vignette on low health)

### Priority 2 — Combat Loop
5. Build `BP_WeaponBase` (spec #69) — basic weapon with fire animation
6. Build `BPC_FirearmSystem` (spec #74) — hitscan fire, damage application
7. Wire `BPC_DamageReceptionSystem.ApplyDamage()` to weapon fire events
8. Build `BPC_HitReactionSystem` (spec #75) — add stagger/ragdoll animations

### Priority 3 — Save/Death Loop
9. Build `BPC_DeathHandlingSystem` (spec #39) — death screen, respawn timer
10. Build `BP_Checkpoint` (spec #37) — save on touch, respawn point
11. Build `BPC_PlayerRespawnSystem` (spec #42) — checkpoint loading

### Priority 4 — Inventory UI
12. Build `WBP_InventoryMenu` (spec #49) — grid display, item drag-drop
13. Build `BPC_EquipmentSlotSystem` (spec #30) — weapon/armor slots
14. Build `BPC_ConsumableSystem` (spec #28) — use medkits from inventory

### Priority 5 — Full Systems
15. Build remaining Player systems (12-15)
16. Build Interaction systems (17-23)
17. Build Narrative systems (58-68)
18. Build AI systems (80-88)
19. Build Adaptive systems (89-101)
20. Build UI, Meta, Settings, Polish (44-57, 102-114)

> See [`docs/checklists/remaining-blueprint-build-order.md`](../checklists/remaining-blueprint-build-order.md) for the complete build order across all 135 systems.

---

## 12. Troubleshooting

### "GameplayTag is not valid" / Tags show as "Invalid"

**Fix:** Add all 11 `DT_Tags_*` Data Tables to `Project Settings → Gameplay Tags → Gameplay Tag Table List`. Restart editor. Verify tags are in `.ini` cache: check `Saved/Config/WindowsEditor/GameplayTags.ini` for entries.

### "SS_SaveManager not found" / Subsystem is null

**Fix:** Ensure `BP_GameFramework` is set as the Default Game Instance in Project Settings. `UGameInstanceSubsystem` lifecycles only trigger under the assigned GameInstance.

### "Enhanced Input not working" — character doesn't move

**Fix:** 
1. Ensure `Enhanced Input` plugin is enabled in Plugins
2. Ensure `IMC_Default` is pushed in `PC_CoreController.BeginPlay`
3. Ensure Input Actions are bound in player character's `Setup Player Input Component`

### "BPC_StateManager.GatingTable is null"

**Fix:** Create `DA_StateGatingTable` Data Asset (class: `DA_StateGatingTable`), populate at least 1 rule, then assign it to the `StateManager` component's `Gating Table` property in `BP_PlayerCharacter`.

### "Cannot find class DA_GameTagRegistry" in Content Browser

**Fix:** The C++ class must be compiled before it appears. Ensure `PG_Framework` module is in `PG_Prototype.Build.cs` and the project compiled successfully. Check `Window → Developer Tools → Modules` for `PG_Framework`.

### Compile error: "EnhancedInputModule not found"

**Fix:** Add `"EnhancedInput"` to `PublicDependencyModuleNames` in `PG_Prototype.Build.cs`.

### "Inventory Add Item returns 0"

**Fix:** Check `InventorySystem.MaxWeight` — if too low, items can't be added. Check `DA_ItemData.StackLimit` — must be >= 1. Check `GridWidth` and `GridHeight` — must be > 0.

### "Force State Change doesn't block actions"

**Fix:** The `DA_StateGatingTable` must have gating rules that block the action when the force state is active. Example: rule `Framework.Action.FireWeapon` blocked by `Framework.State.Action.Cutscene` marked `IsBlocked = true`.

---

## Reference Files

| Document | Path |
|----------|------|
| Complete BP build order | `docs/checklists/remaining-blueprint-build-order.md` |
| C++ per-class setup guide | `docs/developer/cpp-integration-guide.md` |
| Full project migration guide | `docs/developer/project-setup-migration.md` |
| C++/BP status grid | `docs/checklists/cpp-blueprint-status.md` |
| State Manager architecture | `docs/architecture/bpc-statemanager.md` |
| Blueprint spec INDEX | `docs/blueprints/INDEX.md` |
| Developer docs INDEX | `docs/developer/INDEX.md` |

---

*Project Prototype Guide v1.0 — Build a working PG_Framework prototype in under 4 hours.*
