diff --git a/docs/blueprints/01-core/07_DA_ItemData.md b/docs/blueprints/01-core/07_DA_ItemData.md index 2350068..f1289f7 100644 --- a/docs/blueprints/01-core/07_DA_ItemData.md +++ b/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) | 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) | -| **Asset Path** | `Content/Data/Items/DA_Item_[Name]` | -| **Implements Interfaces** | None | +| **C++ Class** | `UDA_ItemData` (in `Source/PG_Framework/Public/Inventory/DA_ItemData.h`) | +| **Class Type** | Primary Data Asset | +| **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 - 2. Check `DisplayName != ""` — if empty, log warning - 3. If `StackLimit < 1`, reset to 1 - 4. If `bIsKeyItem` then `bCanBeDropped = false` (forced) - 5. Return true if all validations pass + 1. Check `ItemTag != None` — if None, append error + 2. Check `DisplayName != ""` — if empty, append error + 3. If `StackLimit < 1`, append error + 4. If `bIsKeyItem` then warn if `bCanBeDropped == true` + 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] - B --> C[Name: DA_Item_MedKit] - C --> D[Fill ItemTag: Item.MedKit] - D --> E[Fill DisplayName: Med Kit] - E --> F[Assign Icon, Mesh] - F --> G[Set ItemType: Consumable] - G --> H[Fill ConsumableData] - H --> I[Save Asset] - I --> J[Registered in Asset Manager] + A[Content Browser] --> B[Right-click > Miscellaneous > Data Asset] + B --> C[Select Class: DA_ItemData] + C --> D[Name: DA_Item_MedKit] + D --> E[Open Asset > Fill Properties] + E --> F[ItemTag: Framework.Item.Consumable.MedKit] + F --> G[DisplayName: Med Kit] + G --> H[Set Icon, WorldMesh] + H --> I[ItemType: Consumable] + 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
Data Asset] -->|referenced by| PICKUP[BP_ItemPickup
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
routes to correct handler] + + INV -->|dispatches OnItemAdded| UI[WBP_InventoryMenu
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`). -- All `ItemTag` values must be registered in `DA_GameTagRegistry` before use. -- The `CustomProperties` map future-proofs any per-project additions without modifying the base asset class. +- **Create one `DA_ItemData` per item.** Naming convention: `DA_Item_[ShortName]` (e.g., `DA_Item_MedKit`, `DA_Item_Flashlight`, `DA_Item_KeyCard_Omega`). +- **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. +- 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`** references — the Data Asset is never copied, only referenced by pointer. All inventory operations pass the `DA_ItemData*` pointer. --- diff --git a/docs/blueprints/04-inventory/25_BP_ItemPickup.md b/docs/blueprints/04-inventory/25_BP_ItemPickup.md index f67e570..336b07d 100644 --- a/docs/blueprints/04-inventory/25_BP_ItemPickup.md +++ b/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. | -| `DA_ItemData` | Supplies mesh, name, icon, stack limits. | -| `BPC_PlayerMetricsTracker` | Logs pickup event (item type, quantity, location). | +| `BPC_InventorySystem` (31) | **Target for item addition.** C++ component — call `AddItem(ItemData, Quantity)`. | +| `DA_ItemData` (07) | Supplies mesh, name, icon, stack limits, weight. | +| `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_AdaptiveDifficulty` | May adjust item availability based on difficulty. | +| `BPC_KeyItemSystem` (34) | Checks `bIsKeyItem` — key items auto-protect from drop/clear. | +| `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)