admin/UE5-Modular-Game-Framework
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Lefteris Notas
2026-05-21 20:08:40 +03:00
parent ccd1872e59
commit 7e876e4f0c
2 changed files with 216 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

179
docs/blueprints/01-core/07_DA_ItemData.md
View File

@@ -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) |
| **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<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`).
- 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<UDA_ItemData>`** references — the Data Asset is never copied, only referenced by pointer. All inventory operations pass the `DA_ItemData*` pointer.
---

77
docs/blueprints/04-inventory/25_BP_ItemPickup.md
View File

@@ -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)