docs: Update BP_ItemPickup setup instructions and correct C++ references

docs/blueprints/01-core/07_DA_ItemData.md

@@ -3,9 +3,102 @@
 ## Purpose
 The single source of truth for every item in the game. Each item is represented by one `DA_ItemData` Primary Data Asset. No item data lives in Blueprint logic; all item definitions are data-driven from these assets.
 
+**C++ Status:** ✅ Full — `Source/PG_Framework/Public/Inventory/DA_ItemData.h` + `.cpp`. All enums, structs, variables, and editor validation are implemented in C++ with `UPROPERTY` metadata (EditCondition, EditConditionHides, ClampMin/Max) for designer-friendly editor UX.
+
+> **Critical distinction:** `DA_ItemData` is a **Data Asset** — it lives in the Content Browser, NOT in the level. It defines *what* an item is (name, weight, icon, effects, type). To place an item in the world, create a `BP_ItemPickup` actor (spec #25) and assign the `DA_ItemData` to it. The Data Asset is the item's *identity card*; `BP_ItemPickup` is its *physical body* in the world. See [How to Set Up](#how-to-set-up) below.
+
+---
+
+## How to Set Up
+
+### Step 1 — Create the Data Asset
+
+```
+Content Browser → Framework/DataAssets/Items/
+  Right-click → Miscellaneous → Data Asset
+  Class: DA_ItemData
+  Name: DA_Item_[ShortName]  (e.g., DA_Item_MedKit, DA_Item_RustyKey, DA_Item_Pistol)
+```
+
+### Step 2 — Fill in Core Properties
+
+Open the Data Asset and fill in:
+
+| Property | Purpose | Example |
+|----------|---------|---------|
+| `Item Tag` | **Unique identifier** — registered in `DA_GameTagRegistry` | `Framework.Item.Consumable.MedKit` |
+| `Display Name` | Player-visible name | "MedKit" |
+| `Description` | Flavor text / gameplay hint | "A standard medical kit. Restores 25 health." |
+| `Icon` | Inventory thumbnail texture | `T_MedKit_Icon` |
+| `World Mesh` | 3D mesh when dropped in world | `SM_MedKit` |
+| `Weight` | Weight units for carry limit | `1.0` |
+| `Stack Limit` | Max per slot (weapons = 1, ammo = 999, consumables = 5) | `5` |
+| `Item Type` | Category enum — controls which sub-data to fill | `Consumable` |
+
+### Step 3 — Fill Type-Specific Sub-Data
+
+Based on `Item Type`, fill the relevant sub-struct (other sub-panels auto-hide via `EditCondition`):
+
+| Item Type | Sub-Struct to Fill | Example Values |
+|-----------|-------------------|-----------------|
+| `Weapon` / `Tool` | `Equipment Data` | Damage=0, FireRate=0, MagazineSize=0, Slot=PrimaryWeapon |
+| `Consumable` | `Consumable Data` | HealthRestore=25, UseDuration=2.0, bConsumedOnUse=true |
+| `Ammo` | `AmmoData` (legacy) | AmmoTypeTag, PerPickupCount |
+| `KeyItem`, `Document`, `Collectible`, `Resource`, `Misc` | None — core properties only | |
+
+### Step 4 — Place a Pickup in the World
+
+The Data Asset does **not** appear in the world. To spawn it:
+
+1. Create a `BP_ItemPickup` actor (see spec #25: [`../../04-inventory/25_BP_ItemPickup.md`](../04-inventory/25_BP_ItemPickup.md))
+2. In the `BP_ItemPickup` actor instance, set `Config → Item Data` → your `DA_Item_MedKit`
+3. Drag `BP_ItemPickup` into the level
+4. The pickup reads the mesh from the Data Asset, handles overlap, and calls `BPC_InventorySystem.AddItem(ItemData)` on interact
+
+```
+DA_Item_MedKit (Content Browser)        ← defines WHAT the item is
+        ↑ referenced by
+BP_ItemPickup (Actor in level)          ← physical body in the world
+        ↑ interacts via
+BPC_InteractionDetector → BPC_InventorySystem.AddItem()
+```
+
+---
+
+## Single Identity Tag — Why One Tag Is Enough
+
+Each item has exactly one `ItemTag` GameplayTag. This is intentional — the tag is the item's **unique identifier**, not a categorization bucket.
+
+Categorization and behavioral flags are handled by separate, purpose-built properties:
+
+| Concern | Mechanism | Example |
+|---------|-----------|---------|
+| **Identity** | `ItemTag` (single GameplayTag) | `Framework.Item.Consumable.MedKit` |
+| **Category** | `ItemType` (enum) | Consumable, Weapon, KeyItem, Document, etc. |
+| **Is non-droppable?** | `bIsKeyItem` (bool) | Key items are auto-protected from drop/clear |
+| **Can be dropped?** | `bCanBeDropped` (bool) | Ammo/documents can be dropped; key items cannot |
+| **Has 3D inspection?** | `bHasInspectMode` (bool) | Enables rotate-examine on pickup |
+| **Crafting relationships** | `CombinesWith` (array of GameplayTag) | `MedKit` + `Bandage` → `SuperMedKit` |
+| **Project-specific data** | `CustomProperties` (TMap<FName, FString>) | Key=`"QuestRewardID"`, Value=`"Q12"` |
+| **Tag-based queries** | Hierarchical tag structure | `ItemTag.MatchesTag(Framework.Item.Consumable)` returns true for all consumables |
+
+**Why not multiple ItemTags?**
+- A single unique ID prevents ambiguity: inventory lookups, save/load references, and crafting recipes all need one canonical name for each item.
+- Hierarchical GameplayTags support partial matching: `Framework.Item.Consumable.MedKit` matches `Framework.Item.Consumable` for category-wide queries.
+- Adding a `FGameplayTagContainer ItemTags` would create confusion — which tag is the "real" ID? Do you check all of them? Do you sort by the first one?
+- The `ItemType` enum + boolean flags + `CombinesWith` array already cover every use case without tag collision risks.
+
+**If you truly need multiple filtering tags**, the `CustomProperties` map can store them (e.g., `"FilterTags"` → `"Flammable,Magnetic,QuestItem"`), and your BP can parse the comma-separated string at runtime. But in practice, this is rarely needed because:
+- `ItemType` already categorizes items
+- `bIsKeyItem` / `bCanBeDropped` already handle behavioral flags
+- `CombinesWith` already handles cross-item relationships
+- Hierarchical tag matching handles category queries (e.g., `MatchesTag(Framework.Item.Weapon)`)
+
+---
+
 ## Dependencies
 - **Requires:** `GameplayTag` system (`DA_GameTagRegistry`), `UPrimaryDataAsset` (engine base)
-- **Required By:** `BPC_InventorySystem`, `BPC_EquipmentSlotSystem`, `BPC_ConsumableSystem`, `BPC_AmmoResourceSystem`, `BPC_ItemCombineSystem`, `BPC_KeyItemSystem`, `BPC_ActiveItemSystem`, `DA_ItemDatabase` (collection)
+- **Required By:** `BPC_InventorySystem`, `BPC_EquipmentSlotSystem`, `BPC_ConsumableSystem`, `BPC_AmmoComponent` (70), `BPC_ItemCombineSystem`, `BPC_KeyItemSystem`, `BPC_ActiveItemSystem`
 - **Engine/Plugin Requirements:** `GameplayTags`, `AssetManager` (Primary Data Asset registration)
 - **Parent Class:** `UPrimaryDataAsset`
 
@@ -13,9 +106,10 @@ The single source of truth for every item in the game. Each item is represented
 | Property | Value |
 |----------|-------|
 | **Parent Class** | `UPrimaryDataAsset` |
-| **Class Type** | Blueprint Function Library (Data Asset) |
+| **C++ Class** | `UDA_ItemData` (in `Source/PG_Framework/Public/Inventory/DA_ItemData.h`) |
-| **Asset Path** | `Content/Data/Items/DA_Item_[Name]` |
+| **Class Type** | Primary Data Asset |
-| **Implements Interfaces** | None |
+| **Asset Path** | `Content/Framework/DataAssets/Items/DA_Item_[Name]` |
+| **Implements Interfaces** | None (passive data container) | |
 
 ---
 
@@ -87,19 +181,28 @@ No custom structs defined in this Data Asset class. Consumed structs from other
 
 ## 4. Functions
 
-No runtime functions. This is a pure data container. The only accessible operations are direct variable reads from Blueprints that hold a reference to the asset.
+`DA_ItemData` is a pure data container. All properties are read directly from Blueprints that hold a reference to the asset. The following functions exist in the C++ class (`Source/PG_Framework/Public/Inventory/DA_ItemData.h`):
+
+### Runtime (All BlueprintCallable / BlueprintPure)
+
+| Function | Returns | Description |
+|----------|---------|-------------|
+| `GetResistance(DamageType)` (on `DA_EquipmentConfig`) | `float` | Returns resistance value for a damage type (armor/equipment) |
+| *(All UPROPERTY reads)* | — | `ItemTag`, `DisplayName`, `ItemType`, `Weight`, `StackLimit`, etc. are read directly — no function call needed |
 
 ### Editor-Only Functions (for content team validation)
 
 #### `ValidateItemData` → `Bool` (BlueprintCallable, Editor only)
+- **C++ Implementation:** Full — `Source/PG_Framework/Private/Inventory/DA_ItemData.cpp`
 - **Description:** Runs editor validation checks (tag uniqueness, required fields filled).
-- **Parameters:** None
+- **Parameters:** `OutErrors` (FString, out) — human-readable error messages
 - **Flow:**
-  1. Check `ItemTag != None` — if None, log warning
+  1. Check `ItemTag != None` — if None, append error
-  2. Check `DisplayName != ""` — if empty, log warning
+  2. Check `DisplayName != ""` — if empty, append error
-  3. If `StackLimit < 1`, reset to 1
+  3. If `StackLimit < 1`, append error
-  4. If `bIsKeyItem` then `bCanBeDropped = false` (forced)
+  4. If `bIsKeyItem` then warn if `bCanBeDropped == true`
-  5. Return true if all validations pass
+  5. If Consumable, check at least one effect value > 0
+  6. Return true if all validations pass; false if any failed
 
 ---
 
@@ -115,21 +218,40 @@ No event overrides. Data Assets do not tick or have BeginPlay.
 
 ---
 
-## 7. Blueprint Graph Logic Flow
+## 7. Content Creation Flow
 
-No blueprint graph. This asset is created and edited in the Content Browser via "Create Advanced Asset -> Blueprint -> Data Asset -> DA_ItemData".
+`DA_ItemData` has **no blueprint graph**. It is created and edited in the Content Browser as a Data Asset instance.
 
 ```mermaid
 flowchart LR
-    A[Content Browser] --> B[Right-click > Data Asset > DA_ItemData]
+    A[Content Browser] --> B[Right-click > Miscellaneous > Data Asset]
-    B --> C[Name: DA_Item_MedKit]
+    B --> C[Select Class: DA_ItemData]
-    C --> D[Fill ItemTag: Item.MedKit]
+    C --> D[Name: DA_Item_MedKit]
-    D --> E[Fill DisplayName: Med Kit]
+    D --> E[Open Asset > Fill Properties]
-    E --> F[Assign Icon, Mesh]
+    E --> F[ItemTag: Framework.Item.Consumable.MedKit]
-    F --> G[Set ItemType: Consumable]
+    F --> G[DisplayName: Med Kit]
-    G --> H[Fill ConsumableData]
+    G --> H[Set Icon, WorldMesh]
-    H --> I[Save Asset]
+    H --> I[ItemType: Consumable]
-    I --> J[Registered in Asset Manager]
+    I --> J[Fill ConsumableData: HealthRestore=25]
+    J --> K[Save Asset]
+    K --> L[Ready — referenced by BP_ItemPickup actors]
+```
+
+### How Systems Use the Data Asset (Read-Only)
+
+```mermaid
+flowchart TD
+    DA[DA_Item_MedKit<br/>Data Asset] -->|referenced by| PICKUP[BP_ItemPickup<br/>Actor in world]
+    PICKUP -->|OnInteract| INV[BPC_InventorySystem.AddItem(DA, 1)]
+    INV -->|stores reference| SLOT[FInventorySlot.Item = DA]
+    
+    DA -->|reads EquipmentData| EQUIP[BPC_EquipmentSlotSystem]
+    DA -->|reads ConsumableData| CONSUM[BPC_ConsumableSystem]
+    DA -->|reads CombinesWith| COMBINE[BPC_ItemCombineSystem]
+    DA -->|reads bIsKeyItem| KEY[BPC_KeyItemSystem]
+    DA -->|reads ItemType| ACTIVE[BPC_ActiveItemSystem<br/>routes to correct handler]
+    
+    INV -->|dispatches OnItemAdded| UI[WBP_InventoryMenu<br/>reads DisplayName, Icon, Description]
 ```
 
 ---
@@ -170,15 +292,18 @@ flowchart LR
 
 ## 10. Reuse Notes
 
-- Create one `DA_ItemData` per item. Name convention: `DA_Item_[ShortName]` (e.g. `DA_Item_MedKit`, `DA_Item_Flashlight`, `DA_Item_KeyCard_Omega`).
+- **Create one `DA_ItemData` per item.** Naming convention: `DA_Item_[ShortName]` (e.g., `DA_Item_MedKit`, `DA_Item_Flashlight`, `DA_Item_KeyCard_Omega`).
-- All `ItemTag` values must be registered in `DA_GameTagRegistry` before use.
+- **Data Assets are not world actors.** They cannot be dragged into a level. To place an item in the world, create a `BP_ItemPickup` actor (spec #25) and assign the `DA_ItemData` to its `Config.ItemData` property.
-- The `CustomProperties` map future-proofs any per-project additions without modifying the base asset class.
+- All `ItemTag` values must be registered in `DA_GameTagRegistry` before use. Use the hierarchical tag structure: `Framework.Item.[Type].[Name]`.
+- The `CustomProperties` map future-proofs any per-project additions without modifying the base C++ class.
 - For non-stackable items (weapons, key items, tools), set `StackLimit = 1`.
-- For stacks, choose a sensible `StackLimit` (e.g. ammo = 999, consumables = 5).
+- For stacks, choose a sensible `StackLimit` (e.g., ammo = 999, consumables = 5, resources = 99).
 - The `AssetManager` should be configured with `PrimaryAssetType = Item` and `PrimaryAssetLabel = Item` for async loading support.
 - Document items (`E_ItemType.Document`) additionally populate `BPC_DocumentArchiveSystem` with their content; the `Description` field serves as document body text.
-- To add a new item property across all items, add a new variable to `DA_ItemData`. Do not create a separate asset class per item type — use the `ItemType` enum for branching logic.
+- To add a new item property across all items, add a new `UPROPERTY` to `DA_ItemData` in C++. Do not create a separate asset class per item type — use the `ItemType` enum + `EditCondition` metadata for branching display.
 - The `ValidateItemData` editor function can be exposed as a Python command for batch validation on check-in.
+- **C++ EditCondition metadata** auto-hides irrelevant panels based on `ItemType` (e.g., `ConsumableData` only shows when `ItemType == Consumable`). Designers never see irrelevant fields.
+- **Inventory systems interact with `DA_ItemData` through C++ `TObjectPtr<UDA_ItemData>`** references — the Data Asset is never copied, only referenced by pointer. All inventory operations pass the `DA_ItemData*` pointer.
 
 ---
 

docs/blueprints/04-inventory/25_BP_ItemPickup.md

@@ -3,15 +3,65 @@
 **Parent Class:** `Actor`
 **Category:** Inventory
 **Target UE Version:** 5.5–5.7
-**Build Phase:** 3 — Inventory
+**Build Phase:** 4 — Inventory
+**C++ Status:** 🔵 BP-Only
+
+---
+
+## 0. Quick Setup — How to Place an Item in the World
+
+This is the most common question: "I created a `DA_ItemData` but I can't drag it into the level." Here's the correct workflow:
+
+### Step A — Create the Data Asset (one-time per item type)
+
+```
+Content Browser → Framework/DataAssets/Items/
+  Right-click → Miscellaneous → Data Asset
+  Class: DA_ItemData
+  Name: DA_Item_MedKit
+  Fill in: ItemTag, DisplayName, Icon, WorldMesh, Weight, StackLimit, ItemType
+  If ItemType=Consumable → fill ConsumableData (HealthRestore=25, UseDuration=2.0)
+  Save
+```
+
+### Step B — Create the BP_ItemPickup Blueprint (one-time)
+
+```
+Content Browser → Framework/Inventory/
+  Right-click → Blueprint Class → Actor
+  Name: BP_ItemPickup
+  Implement I_Interactable interface
+  Add: StaticMeshComponent (named "Mesh"), SphereComponent (named "InteractionCollision")
+  Add: Config variable of type S_PickupConfig
+  In Construction Script: read Config.ItemData → set Mesh to ItemData.WorldMesh
+```
+
+### Step C — Place Items in Your 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 it where you want it in the world
+```
+
+The `BP_ItemPickup` reads the mesh, name, icon, and interaction prompt from the `DA_ItemData`. You never drag the Data Asset itself into the level — only the actor that references it.
+
+```
+DA_Item_MedKit (Content Browser)        ← defines WHAT
+        ↑ referenced by
+BP_ItemPickup (Actor in level)          ← physical body in world
+        ↑ interacts via
+Player → BPC_InteractionDetector → I_Interactable → BPC_InventorySystem.AddItem()
+```
 
 ---
 
 ## 1. Overview
 
-`BP_ItemPickup` is a world-placed or runtime-spawned `Actor` representing an item the player can pick up. It implements [`I_Interactable`](docs/blueprints/01-core/03_I_InterfaceLibrary.md) and optionally [`I_Persistable`](docs/blueprints/01-core/03_I_InterfaceLibrary.md).
+`BP_ItemPickup` is a world-placed or runtime-spawned `Actor` representing an item the player can pick up. It implements [`I_Interactable`](../01-core/03_I_InterfaceLibrary.md) and optionally [`I_Persistable`](../01-core/03_I_InterfaceLibrary.md).
 
-When the player interacts (via [`BPC_InteractionDetector`](docs/blueprints/03-interaction/16_BPC_InteractionDetector.md)), the pickup calls `BPC_InventoryComponent.AddItem` with the associated item data, plays feedback, and either destroys itself or depletes a stack count.
+When the player interacts (via [`BPC_InteractionDetector`](../03-interaction/16_BPC_InteractionDetector.md)), the pickup calls `BPC_InventorySystem.AddItem` with the associated item data, plays feedback, and either destroys itself or depletes a stack count.
 
 ---
 
@@ -99,7 +149,7 @@ When the player interacts (via [`BPC_InteractionDetector`](docs/blueprints/03-in
 | Variable | Type | Description |
 |----------|------|-------------|
 | `WorldState` | `S_PickupWorldState` | Tracks pickup history. |
-| `OwningInventory` | `BPC_InventoryComponent*` | Cached when player overlaps interaction trigger. |
+| `OwningInventory` | `UBPC_InventorySystem*` | Cached when player overlaps interaction trigger. |
 | `RespawnTimerHandle` | `FTimerHandle` | Handle for respawn delay. |
 
 ---
@@ -110,7 +160,8 @@ When the player interacts (via [`BPC_InteractionDetector`](docs/blueprints/03-in
 
 | Function | Description |
 |----------|-------------|
-| `Interact_Implementation` | Implements `I_Interactable`: adds item to player inventory, plays feedback, destroys or depletes. |
+| `Public Functions` | Description |
+| `Interact_Implementation` | Implements `I_Interactable`: calls `BPC_InventorySystem.AddItem()`, plays feedback, destroys or depletes. |
 | `OnDroppedFromInventory` | Called by inventory drop system: sets transform, velocity, and respawn behaviour. |
 | `BeginPlay` | Caches references, sets up bobbing/rotation timeline, configures collision. |
 | `SetPickupEnabled` | Toggles visibility and collision. |
@@ -151,7 +202,7 @@ Event BeginPlay
 OnOverlapBegin (Player overlaps InteractionCollision)
     → Set VisualState = Highlighted
     → Show pickup prompt widget (if assigned)
-    → Cache player's BPC_InventoryComponent
+    → Cache player's BPC_InventorySystem
 
 OnOverlapEnd (Player leaves InteractionCollision)
     → Set VisualState = Idle
@@ -163,7 +214,7 @@ Interact_Implementation (Called from BPC_InteractionDetector)
     → Validate player inventory has space → if full, show "Inventory Full" feedback → return
     → Set VisualState = BeingPickedUp
     → Play pickup sound + particle effect
-    → Call BPC_InventoryComponent.AddItem(Config.ItemData, Config.Quantity)
+    → Call BPC_InventorySystem.AddItem(Config.ItemData, Config.Quantity)
     → If AddItem succeeded:
         → Broadcast OnPickupCollected(InteractingPlayer)
         → If bIsInfinite → do not destroy
@@ -214,12 +265,12 @@ OnRespawnComplete
 |--------|--------------|
 | `I_Interactable` | Implements the interface for interaction detection. |
 | `BPC_InteractionDetector` | Sends overlap events and routes interaction call. |
-| `BPC_InventoryComponent` | Target for item addition. |
+| `BPC_InventorySystem` (31) | **Target for item addition.** C++ component — call `AddItem(ItemData, Quantity)`. |
-| `DA_ItemData` | Supplies mesh, name, icon, stack limits. |
+| `DA_ItemData` (07) | Supplies mesh, name, icon, stack limits, weight. |
-| `BPC_PlayerMetricsTracker` | Logs pickup event (item type, quantity, location). |
+| `BPC_PlayerMetricsTracker` (15) | Logs pickup event (item type, quantity, location). |
 | `I_Persistable` | Optional: saves pickup state (available, transform, quantity). |
-| `BPC_InventoryWeightSystem` | Checks weight capacity before allowing pickup. |
+| `BPC_KeyItemSystem` (34) | Checks `bIsKeyItem` — key items auto-protect from drop/clear. |
-| `BPC_AdaptiveDifficulty` | May adjust item availability based on difficulty. |
+| `SS_AchievementSystem` (103) | Notified on collectible pickups for completion tracking. |
 
 ---
 
@@ -248,7 +299,7 @@ Player approaches world item → Overlap event
 Player presses Interact key
     → BPC_InteractionDetector.InteractTarget → BP_ItemPickup.Interact_Implementation
     → Validate availability + inventory space
-    → BPC_InventoryComponent.AddItem (ItemData, Quantity)
+    → BPC_InventorySystem.AddItem (ItemData, Quantity)
     → Play pickup sound + particle
     → Broadcast OnPickupCollected
     → If bRespawns → StartRespawn (hide, wait, reappear)