Add Project Prototype Guide for PG_Framework Testing Setup

- Introduced a comprehensive guide for creating a minimal playable prototype in UE5. - Detailed steps for project creation, C++ module integration, gameplay tags setup, and player pawn assembly. - Included instructions for input system setup, state management wiring, and test level setup. - Provided a verification checklist and troubleshooting section to assist developers. - Documented next steps for expanding the prototype with additional systems.
2026-05-21 18:03:15 +03:00
parent cd0ebf2233
commit 8bb162eda2
5 changed files with 1515 additions and 53 deletions
--- a/docs/developer/INDEX.md
+++ b/docs/developer/INDEX.md
@@ -1,6 +1,6 @@
 # Developer Reference — UE5 Modular Game Framework

-**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
+**Version:** 1.5 | **Generated:** 2026-05-21 | **Files:** 18 (1 index + 2 overview + 1 migration + 1 integration + 1 prototype + 1 starter + 10 category docs + 1 combined) | **C++:** 12 full + 10 stubs = 22 systems

 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,11 @@ docs/developer/
 ├── INDEX.md                              ← THIS FILE
 ├── architecture-overview.md              ← Framework-wide architecture walkthrough
 ├── implementation-patterns.md            ← Common UE5 Blueprint patterns used
-├── cpp-integration-guide.md              ← C++ per-system integration & setup (NEW — 12 systems)
+├── cpp-integration-guide.md              ← C++ per-system integration & setup (22 systems)
 ├── project-setup-migration.md            ← Project setup & migration guide
+├── project-prototype-guide.md            ← Step-by-step prototype build guide (NEW)
 ├── 00-starter-gameinstance.md            ← Starter GameInstance: GI_StarterGameInstance setup guide
+├── 01-core-foundation.md                 ← Foundation systems explained
 ├── 02-player-systems.md                  ← Player state & embodiment (systems 08-15)
 ├── 03-interaction-systems.md             ← Interaction & world manipulation (systems 16-23)
 ├── 04-inventory-systems.md               ← Inventory, items & collectibles (systems 24-34)
@@ -178,12 +180,14 @@ docs/developer/

 1. **New to the framework?** Start with [`architecture-overview.md`](architecture-overview.md) to understand the big picture.
 2. **Setting up a new project?** Read [`00-starter-gameinstance.md`](00-starter-gameinstance.md) first — create `GI_StarterGameInstance` to validate your GameplayTags immediately. Then follow [`project-setup-migration.md`](project-setup-migration.md) for full Project Settings, plugins, Data Tables, and init sequence.
-3. **Using the C++ classes?** Read [`cpp-integration-guide.md`](cpp-integration-guide.md) — per-system setup steps, Blueprint children to create, usage patterns, and build order. See [`../checklists/cpp-blueprint-status.md`](../checklists/cpp-blueprint-status.md) for the full 135-system status grid.
-4. **Implementing a system?** Read the Blueprint Spec in `docs/blueprints/` — every file has a Manual Implementation Guide with node-by-node logic.
-5. **Need to understand internals?** Read the corresponding Developer Reference doc in this directory.
-6. **Debugging?** Each category doc includes a data flow section showing how data moves between systems.
-7. **Need UE5 Blueprint patterns?** See [`implementation-patterns.md`](implementation-patterns.md).
-8. **Multiplayer networking?** See [`../architecture/multiplayer-networking.md`](../architecture/multiplayer-networking.md). Every doc has a Multiplayer Networking section.
+3. **Building a prototype?** Follow [`project-prototype-guide.md`](project-prototype-guide.md) — step-by-step instructions from blank project to working test character with verification checklist.
+4. **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.
+5. **Need the prioritized BP build list?** See [`../checklists/remaining-blueprint-build-order.md`](../checklists/remaining-blueprint-build-order.md) — every system with C++ status, what BP to build, and dependency-safe order.
+6. **Implementing a system?** Read the Blueprint Spec in `docs/blueprints/` — every file has a Manual Implementation Guide with node-by-node logic.
+7. **Need to understand internals?** Read the corresponding Developer Reference doc in this directory.
+8. **Debugging?** Each category doc includes a data flow section showing how data moves between systems.
+9. **Need UE5 Blueprint patterns?** See [`implementation-patterns.md`](implementation-patterns.md).
+10. **Multiplayer networking?** See [`../architecture/multiplayer-networking.md`](../architecture/multiplayer-networking.md). Every doc has a Multiplayer Networking section.

 ## Relationship to Spec Files

--- a/docs/developer/project-prototype-guide.md
+++ b/docs/developer/project-prototype-guide.md
@@ -0,0 +1,713 @@
+# 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.*