docs: Update item pickup setup instructions and add game examples for Blueprint walkthroughs

docs/checklists/remaining-blueprint-build-order.md

@@ -1,6 +1,6 @@
 # Remaining Blueprint Build Order — All 135 Systems
 
-**Version:** 1.0 | **Generated:** 2026-05-21 | **C++ Status:** 22 header files (12 full, 10 stubs)
+**Version:** 1.1 | **Generated:** 2026-05-21 | **C++ Status:** 22 header files (12 full, 10 stubs)
 
 This document is the authoritative "what's left to build" reference. It cross-references the 22 C++ classes in `Source/PG_Framework/` against all 135 Blueprint spec files to show exactly what Blueprint assets remain to be created, in dependency-safe build order.
 
@@ -67,8 +67,19 @@ These 8 systems are the bedrock. Without them, nothing else runs.
 |--------|--------|
 | **C++ Status** | ✅ Full — `Source/PG_Framework/Public/Core/DA_GameTagRegistry.h` + `.cpp` |
 | **BP Spec** | ✅ `docs/blueprints/01-core/01_DA_GameTagRegistry.md` |
-| **What to Build** | ⬜ **Data Asset instance:** `Content/Framework/Core/DA_GameTagRegistry` → assign `TagDataTables` (11 entries) |
-| **Manual Steps** | 11 Data Tables must be created from CSV and registered in Project Settings first. |
+| **What to Build** | ⬜ **Data Asset instance** (not a Blueprint child — a Data Asset instance created from the C++ class) |
+
+**Setup Steps:**
+1. **Prerequisite:** All 11 Data Tables must already exist (imported from CSV) and registered in `Project Settings → Gameplay Tags → Gameplay Tag Table List`. If not done, go back to the Data Tables section below.
+2. In Content Browser, navigate to `Content/Framework/Core/` (create folder if needed)
+3. **Right-click → Miscellaneous → Data Asset**
+4. In the "Pick Data Asset Class" dialog, type `DA_GameTagRegistry` and select it
+5. Name it `DA_GameTagRegistry`
+6. **Open the Data Asset** → find the `Tag Data Tables` array property
+7. Click `+` eleven times → assign each of the 11 `DT_Tags_*` Data Tables in order
+8. Save
+
+**Verification:** Open `DA_GameTagRegistry` → call `GetAllRegisteredTags()` (right-click the asset → "Test Data Asset" or via Blueprint). Should return 300+ tags. If empty, the Data Tables are not registered in Project Settings.
 
 ### 02 — FL_GameUtilities
 | Aspect | Detail |
@@ -90,30 +101,88 @@ These 8 systems are the bedrock. Without them, nothing else runs.
 |--------|--------|
 | **C++ Status** | ✅ Full — `Source/PG_Framework/Public/Core/GI_GameFramework.h` + `.cpp` |
 | **BP Spec** | ✅ `docs/blueprints/01-core/04_GI_GameFramework.md` |
-| **What to Build** | 🔵 **BP child:** `Content/Framework/Core/BP_GameFramework` (parent: `GI_GameFramework`). In Class Defaults: set `TagRegistry` → `DA_GameTagRegistry`, `bValidateTagsOnInit` → `true`. |
-| **Project Settings** | Set as **Default Game Instance** in Maps & Modes. |
+| **What to Build** | 🔵 **BP child:** `Content/Framework/Core/BP_GameFramework` (parent: `GI_GameFramework`) |
+| **Project Settings** | Set as **Default Game Instance** in Maps & Modes |
+
+**Setup Steps:**
+1. In Content Browser, navigate to `Content/Framework/Core/` (create folder if needed)
+2. **Right-click → Blueprint Class**
+3. In the "Pick Parent Class" dialog, scroll to the bottom and click **"All Classes"**
+4. In the search box that appears, type `GI_GameFramework` and select it
+5. Name it `BP_GameFramework`
+6. **Double-click to open** the Blueprint → click **Class Defaults** (toolbar button at top)
+7. In the Details panel, find the **Framework\|Config** category:
+   - `Tag Registry` → click the dropdown → select `DA_GameTagRegistry`
+   - `b Validate Tags On Init` → check the box (set to `true`)
+   - `b Log Tags On Init` → optional — check to see all tags in Output Log on startup
+8. **Compile → Save**
+9. **Edit → Project Settings → Maps & Modes → Game Instance Class** → select `BP_GameFramework`
+
+**Why a BP child?** `GI_GameFramework` is `UCLASS(Blueprintable)` — you can't use the C++ class directly as Game Instance. UE5 requires a concrete class. The BP child inherits all C++ logic (game phases, session flags, service resolution, tag validation) and lets you override Blueprint events like `Init` or `Shutdown` for project-specific startup logic.
 
 ### 05 — GM_CoreGameMode
 | Aspect | Detail |
 |--------|--------|
 | **C++ Status** | ✅ Full — `Source/PG_Framework/Public/Core/GM_CoreGameMode.h` + `.cpp` |
 | **BP Spec** | ✅ `docs/blueprints/01-core/05_GM_CoreGameMode.md` |
-| **What to Build** | 🔵 **BP child:** `Content/Framework/Core/BP_CoreGameMode` (parent: `GM_CoreGameMode`). In Class Defaults: set `PlayerControllerClass` → `PC_CoreController`, `PlayerStateClass` → `PS_CorePlayerState`, `GameStateClass` → `BP_CoreGameState`, `DefaultPawnClass` → your player pawn. |
-| **Project Settings** | Set as **Default GameMode** in Maps & Modes. |
+| **What to Build** | 🔵 **BP child:** `Content/Framework/Core/BP_CoreGameMode` (parent: `GM_CoreGameMode`) |
+| **Project Settings** | Set as **Default GameMode** in Maps & Modes |
+
+**Setup Steps:**
+1. In Content Browser, navigate to `Content/Framework/Core/`
+2. **Right-click → Blueprint Class → All Classes** → search `GM_CoreGameMode`
+3. Name it `BP_CoreGameMode`
+4. **Double-click to open** → click **Class Defaults** (toolbar button at top)
+5. The `PlayerControllerClass`, `PlayerStateClass`, `GameStateClass`, and `DefaultPawnClass` are **inherited from `AGameModeBase`** — they appear in the Details panel under the **"Classes"** section (not under Framework). Fill them in:
+
+   | Property | Value | Notes |
+   |----------|-------|-------|
+   | `Player Controller Class` | `PC_CoreController` | Your BP child of `APC_CoreController` (C++ stub — create it first) |
+   | `Player State Class` | `PS_CorePlayerState` | Your BP child of `APS_CorePlayerState` (C++ stub — create it first) |
+   | `Game State Class` | `BP_CoreGameState` | Your BP child of `AGS_CoreGameState` |
+   | `Default Pawn Class` | Your player pawn BP | The Character BP with all BPC_ components attached |
+   | `HUD Class` | `WBP_HUDController` | Your root HUD widget (create later in Phase 6) |
+
+6. **Compile → Save**
+7. **Edit → Project Settings → Maps & Modes → Default GameMode** → select `BP_CoreGameMode`
+
+> **Important:** The C++ header explicitly states: *"PlayerControllerClass, PlayerStateClass, and GameStateClass are inherited from AGameModeBase — do not redeclare (UHT forbids shadowing). Set them in your BP child's Class Defaults."* These properties are in the inherited "Classes" category, not in custom Framework categories. If you can't find them, make sure you're looking at Class Defaults (not the Event Graph) and scroll through all categories.
 
 ### 06 — GS_CoreGameState
 | Aspect | Detail |
 |--------|--------|
 | **C++ Status** | ✅ Full — `Source/PG_Framework/Public/Core/GS_CoreGameState.h` + `.cpp` |
 | **BP Spec** | ✅ `docs/blueprints/01-core/06_GS_CoreGameState.md` |
-| **What to Build** | 🔵 **BP child:** `Content/Framework/Core/BP_CoreGameState` (parent: `GS_CoreGameState`). No extra config needed — replicated state works out of the box. |
+| **What to Build** | 🔵 **BP child:** `Content/Framework/Core/BP_CoreGameState` (parent: `GS_CoreGameState`) |
+
+**Setup Steps:**
+1. In Content Browser, navigate to `Content/Framework/Core/`
+2. **Right-click → Blueprint Class → All Classes** → search `GS_CoreGameState`
+3. Name it `BP_CoreGameState`
+4. **Compile → Save** (no extra config needed — all 5 replicated state variables with `OnRep_` handlers work out of the box)
+5. Assign it in `BP_CoreGameMode` → Class Defaults → Classes → `Game State Class` → `BP_CoreGameState`
+
+**What you get for free:** Chapter tracking, narrative phase, encounter state, objective tags, play time accumulation — all replicated with dispatchers that fire identically for local and remote clients.
 
 ### 07 — DA_ItemData
 | Aspect | Detail |
 |--------|--------|
 | **C++ Status** | ✅ Full — `Source/PG_Framework/Public/Inventory/DA_ItemData.h` + `.cpp` |
 | **BP Spec** | ✅ `docs/blueprints/01-core/07_DA_ItemData.md` |
-| **What to Build** | ⬜ **Data Asset instances:** `DA_Item_*` per game item (weapons, consumables, key items, documents, collectibles, tools, resources, misc). |
+| **What to Build** | ⬜ **Data Asset instances** (NOT world actors — see note below) |
+
+**How to create each item:**
+1. `Content/Framework/DataAssets/Items/` → **Right-click → Miscellaneous → Data Asset**
+2. Class: `DA_ItemData` → Name: `DA_Item_[Name]` (e.g., `DA_Item_MedKit`)
+3. Open → fill core properties: ItemTag, DisplayName, Description, Icon, WorldMesh, Weight, StackLimit, ItemType
+4. Based on ItemType, fill the relevant sub-struct:
+   - Weapon/Tool → fill `Equipment Data` (slot, damage, fire rate, magazine size)
+   - Consumable → fill `Consumable Data` (health restore, use duration)
+   - KeyItem → set `b Is Key Item` = true (auto-protects from drop/clear)
+5. Save
+6. **To place in world:** Create a `BP_ItemPickup` actor (spec #25), set its `Config.ItemData` to this asset, drag into level.
+
+> **Data Assets are NOT actors.** `DA_ItemData` defines *what* the item is (identity card). `BP_ItemPickup` is the *physical body* in the world. See `docs/blueprints/01-core/07_DA_ItemData.md` for the full explanation with diagrams.
 
 ### 128 — SS_EnhancedInputManager
 | Aspect | Detail |
@@ -128,14 +197,40 @@ These 8 systems are the bedrock. Without them, nothing else runs.
 |--------|--------|
 | **C++ Status** | 🟡 **Stub** — `Source/PG_Framework/Public/Player/PC_CoreController.h` + `.cpp` |
 | **BP Spec** | Covered in 02-player integration docs |
-| **What to Build** | 🔵 **BP child:** `Content/Framework/Player/PC_CoreController` (parent: `APC_CoreController`). Add logic: input routing, BeginPlay (push IMC_Default), phase handling. |
+| **What to Build** | 🔵 **BP child:** `Content/Framework/Player/PC_CoreController` (parent: `APC_CoreController`) |
+
+**Setup Steps:**
+1. In Content Browser, navigate to `Content/Framework/Player/`
+2. **Right-click → Blueprint Class → All Classes** → search `PC_CoreController` (or `APC_CoreController`)
+3. Name it `PC_CoreController`
+4. **Open → Event Graph → Event BeginPlay:**
+   - Get Game Instance → Cast To `BP_GameFramework`
+   - Get Subsystem (Class: `SS_EnhancedInputManager`) — auto-created, no need to spawn
+   - Call `Push Context` on the subsystem: Context=`IMC_Default`, Priority=0, ContextTag=`Framework.Input.Context.Default`
+5. Add input routing logic for game phase transitions (bind to `GI_GameFramework.OnGamePhaseChanged` → show/hide cursor, switch input mode)
+6. **Compile → Save**
+7. Assign in `BP_CoreGameMode` → Class Defaults → Classes → `Player Controller Class` → `PC_CoreController`
+
+> **C++ stub means:** The C++ class exists solely so UHT can compile forward-declarations from `GM_CoreGameMode`. It has a constructor but no logic. All gameplay behavior (input routing, phase handling, BeginPlay) goes in your BP child.
 
 ### — PS_CorePlayerState
 | Aspect | Detail |
 |--------|--------|
 | **C++ Status** | 🟡 **Stub** — `Source/PG_Framework/Public/Player/PS_CorePlayerState.h` + `.cpp` |
 | **BP Spec** | Covered in 02-player integration docs |
-| **What to Build** | 🔵 **BP child:** `Content/Framework/Player/PS_CorePlayerState` (parent: `APS_CorePlayerState`). Add player-specific replicated state: inventory slots, equipped items, narrative flags. |
+| **What to Build** | 🔵 **BP child:** `Content/Framework/Player/PS_CorePlayerState` (parent: `APS_CorePlayerState`) |
+
+**Setup Steps:**
+1. In Content Browser, navigate to `Content/Framework/Player/`
+2. **Right-click → Blueprint Class → All Classes** → search `PS_CorePlayerState` (or `APS_CorePlayerState`)
+3. Name it `PS_CorePlayerState`
+4. **Open → Class Defaults** (or add replicated variables in Event Graph):
+   - Add player-specific replicated state: inventory slot data, equipped items array, narrative flags map
+   - Use `Replicated` or `Replicated Using` with `OnRep_` handlers to fire dispatchers
+5. **Compile → Save**
+6. Assign in `BP_CoreGameMode` → Class Defaults → Classes → `Player State Class` → `PS_CorePlayerState`
+
+> **Why empty?** The C++ stub inherits from `APlayerState` which already has `PlayerName`, `Score`, `Ping`. Add your project's player data (loadout, stats, progression) to this BP child. For multiplayer, mark variables `Replicated` and add `GetLifetimeReplicatedProps` override.
 
 ### Data Tables (Phase 0 Root)
 | Asset | Status |
@@ -152,6 +247,20 @@ These 8 systems are the bedrock. Without them, nothing else runs.
 | `DT_Tags_Audio.csv` | ⬜ Import, register |
 | `DT_Tags_Achievement.csv` | ⬜ Import, register |
 
+**How to create each Data Table:**
+1. In Content Browser, navigate to `Content/Framework/DataTables/` (create folder if needed)
+2. **Right-click → Miscellaneous → Data Table**
+3. In the "Pick Row Structure" dialog, search and select `GameplayTagTableRow`
+4. Name it exactly: `DT_Tags_[Category]` (e.g., `DT_Tags_Player`)
+5. **Double-click** the Data Table to open it → click **Import** (toolbar button)
+6. Select the corresponding CSV file from the framework source
+7. After importing all 11, go to **Edit → Project Settings → Gameplay Tags → Gameplay Tag Table List**
+8. Click `+` eleven times → assign each `DT_Tags_*` Data Table
+9. **Click the refresh icon** next to "Import Tags from Config" to force tag load
+10. Restart the editor to ensure all tags are cached
+
+> **⚠️ Critical:** Without Step 8-9, NO framework gameplay tags will be recognized. `Is Gameplay Tag Valid` returns false for all tags. `DA_GameTagRegistry.ValidateTag()` fails. The CSV files alone are not enough — UE must be told which Data Tables to scan for tags.
+
 ### Starter GameInstance (00-project-setup)
 | Aspect | Detail |
 |--------|--------|
@@ -321,7 +430,29 @@ These 2 systems are the central nervous system. `BPC_StateManager` must be on th
 | Aspect | Detail |
 |--------|--------|
 | **C++ Status** | 🔵 **BP-Only** |
-| **What to Build** | 🔵 **BP actor child** — physical item in world: bob/rotate animation, `I_Interactable`, auto-pickup or manual pickup. Set `DA_ItemData` per instance. |
+| **What to Build** | 🔵 **BP actor child** — physical item in world: bob/rotate animation, `I_Interactable`, auto-pickup or manual pickup |
+
+**Setup Steps (3-part workflow):**
+
+**Part A — Create the Data Asset (one-time per item type):**
+1. `Content/Framework/DataAssets/Items/` → Right-click → Miscellaneous → Data Asset → Class: `DA_ItemData`
+2. Name: `DA_Item_MedKit` → Open → fill: ItemTag, DisplayName, Icon, WorldMesh, Weight, StackLimit, ItemType
+3. If ItemType=Consumable → fill ConsumableData (HealthRestore=25, UseDuration=2.0)
+
+**Part B — Create the BP_ItemPickup Blueprint (one-time):**
+1. `Content/Framework/Inventory/` → Right-click → Blueprint Class → Actor → name: `BP_ItemPickup`
+2. Implement `I_Interactable` interface (Class Settings → Interfaces → Add `UInteractable`)
+3. Add Components: `StaticMeshComponent` (named "Mesh"), `SphereComponent` (named "InteractionCollision")
+4. Add Variable: `Config` of type `S_PickupConfig`
+5. In Construction Script: read `Config.ItemData` → set Mesh to `ItemData.WorldMesh`
+
+**Part C — Place Items in Level (repeat per item instance):**
+1. Drag `BP_ItemPickup` into the level
+2. Select it → Details panel → Config → Item Data → `DA_Item_MedKit`
+3. Set Quantity → 1 (or more for stacked items)
+4. Position the actor where you want it
+
+> `DA_ItemData` is NOT an actor — you cannot drag it into the level. It lives in the Content Browser as a Data Asset. `BP_ItemPickup` is the physical body that references the Data Asset. See `docs/blueprints/01-core/07_DA_ItemData.md` for the full explanation.
 
 ### 26 — BPC_ActiveItemSystem
 | Aspect | Detail |
@@ -357,8 +488,26 @@ These 2 systems are the central nervous system. `BPC_StateManager` must be on th
 | Aspect | Detail |
 |--------|--------|
 | **C++ Status** | ✅ Full — `Source/PG_Framework/Public/Inventory/BPC_InventorySystem.h` + `.cpp` |
-| **What to Build** | ➖ **None.** Attach C++ component directly to player pawn. Set `GridWidth`, `GridHeight`, `MaxWeight` in Details panel. |
-| **Attach To** | Player pawn |
+| **What to Build** | ➖ **None.** Attach C++ component directly to player pawn. |
+
+**Setup Steps:**
+1. Open your `BP_PlayerCharacter` Blueprint
+2. In the Components panel, click **Add Component** → search `BPC_InventorySystem`
+3. Select the component → in Details panel:
+   - `Grid Width` → `8` (columns)
+   - `Grid Height` → `5` (rows — gives 40 total slots)
+   - `Max Weight` → `50.0` (set to `0` to disable weight limit)
+4. **Compile → Save**
+
+**Usage from Blueprint:**
+- Get component: `Get Component by Class (BPC_InventorySystem)`
+- `Add Item(ItemData, Quantity)` → returns `int32` (actual quantity added — may be less if full)
+- `Can Add Item(ItemData, Quantity)` → returns `bool` (check before showing pickup prompt)
+- `Get Item Count(ItemData)` → returns total quantity across all stacks
+- `Sort Inventory` — native-speed C++ TArray sort with lambda
+- Bind to `On Inventory Changed` dispatcher → UI widgets refresh
+
+**Attach To** | Player pawn (alongside HealthSystem, StaminaSystem, etc. — order doesn't matter for inventory)
 
 ### 32 — BPC_ItemCombineSystem
 | Aspect | Detail |
@@ -670,4 +819,4 @@ Every system has a complete spec in `docs/blueprints/` with node-by-node Manual
 
 ---
 
-*Remaining Blueprint Build Order v1.0 — Companion to `cpp-blueprint-status.md` and `cpp-integration-guide.md`.*
+*Remaining Blueprint Build Order v1.1 — Companion to `cpp-blueprint-status.md` and `cpp-integration-guide.md`.*