UE5-Modular-Game-Framework/docs/game/item-medkit.md

Item Example — MedKit (Consumable)

Item Type: Consumable Complexity: Low Systems Used: DA_ItemData, BP_ItemPickup, BPC_InventorySystem, BPC_ConsumableSystem, BPC_HealthSystem What You Learn: Consumable Data Asset, pickup actor, health restore, stackable item, quick-slot use

---

1. Create the DA_ItemData

1.1 — Create the Data Asset

Content Browser → Game/Items/
  Right-click → Miscellaneous → Data Asset
  Class: DA_ItemData
  Name: DA_Item_MedKit

1.2 — Fill Core Properties

Property	Value	Notes
Item Tag	Framework.Item.Consumable.MedKit	Unique identity
Display Name	"MedKit"	Player sees this
Description	"A standard medical kit. Restores 25 health."	Shown in inventory
Icon	T_MedKit_Icon	Any red/white cross texture for prototype
World Mesh	SM_MedKit	Soft reference — Construction Script resolves it
Weight	1.0	Light carry weight
Stack Limit	5	Can carry up to 5 in one stack
Item Type	Consumable	Triggers Consumable Data panel

1.3 — Fill Consumable Data

When ItemType == Consumable, the Consumable Data panel appears:

Field	Value	Notes
Health Restore	25.0	How much HP to restore (0-100 clamp)
Stress Reduce	0.0	Optional stress relief
Use Duration	2.0	Seconds to consume (animation time)
bConsumedOnUse	✓ (true)	Item is removed from inventory after use

1.4 — Save

The Data Asset is ready. No other config needed for a simple consumable.

---

2. Create the BP_Pickup_MedKit

Follow the same pattern as the flashlight pickup, but simpler — no active-use actor needed.

2.1 — Create Blueprint

Content Browser → Game/Pickups/
  Right-click → Blueprint Class → Actor
  Name: BP_Pickup_MedKit

2.2 — Add Components

#	Component	Name	Purpose
1	StaticMeshComponent	Mesh	Renders the medkit model
2	SphereComponent	PickupTrigger	Interaction radius (Sphere Radius → 150)

Select PickupTrigger → Details → Collision Presets → OverlapOnlyPawn

2.3 — Create ItemData Variable

+ Variable → Name: ItemData → Type: DA_ItemData → Object Reference

Select the variable → Details:

• Instance Editable → ✓
• Category → Pickup

2.4 — Wire Construction Script

[Construction Script]
  │
  ├─ ItemData → Is Valid? → Branch
  │    ├─ True:
  │    │    ├─ ItemData → Get World Mesh → Load Synchronous → Set Static Mesh (Mesh)
  │    │    └─ ItemData → Get Display Name → Set Actor Label
  │    └─ False:
  │         └─ Print String ("No ItemData assigned to BP_Pickup_MedKit")

2.5 — Add I_Interactable and Wire

Same pattern as flashlight. The key difference for consumables is stacking: the pickup can hold multiple units.

Event Interact
  │ Interactor: AActor*
  │
  ├─ Interactor → Get Component by Class (UBPC_InventorySystem) → Is Valid?
  │    │
  │    └─ True → [Inventory]
  │         │
  │         ├─ Can Add Item(ItemData, Quantity=1)
  │         │    │
  │         │    ├─ True → Add Item(ItemData, Quantity=1) → Destroy Actor → Return True
  │         │    │
  │         │    └─ False:
  │         │         ├─ Print "Inventory Full"
  │         │         └─ Return False

For multi-pickup stacks (e.g., picking up 3 medkits at once), set a Quantity variable (Integer, Instance Editable) and pass it to Add Item. The inventory auto-stacks identical items.

2.6 — Add Bobbing (optional)

Add a Timeline to Event BeginPlay with a sine wave for Z offset — same as flashlight example.

---

3. Wire Consumable Use (On Player Pawn)

When the player uses a consumable from their inventory or quick-slot:

3.1 — In BPC_ConsumableSystem (BP child on pawn)

Event Use Consumable (custom event)
  │ ItemData: DA_ItemData*
  │
  ├─ ItemData → Get Consumable Data (Break FItemConsumableData)
  │    │
  │    ├─ Health Restore > 0?
  │    │    └─ True:
  │    │         ├─ Get Owner → Get Component by Class (UBPC_HealthSystem)
  │    │         │    │
  │    │         │    └─ Is Valid? → True:
  │    │         │         └─ Apply Healing (HealthRestore, Healer=self)
  │    │         │              │
  │    │         │              └─ Print String: "Restored {HealthRestore} HP"
  │    │         │
  │    │         └─ False: Print "No HealthSystem found"
  │    │
  │    ├─ Stress Reduce > 0?
  │    │    └─ True:
  │    │         └─ Get BPC_StressSystem → Remove Stress (StressReduce)
  │    │
  │    ├─ bConsumedOnUse?
  │    │    └─ True:
  │    │         └─ Get BPC_InventorySystem → Remove Item (ItemData, 1)
  │    │
  │    └─ (Optional) Play sound, screen effect, widget animation

3.2 — Quick Test Without Full Integration

Bind a test key (e.g., IA_UseItem) in your player character:

Event InputAction (IA_UseItem, Pressed)
  │
  ├─ Get Component by Class (UBPC_InventorySystem)
  ├─ Get All Items → For Each Loop
  │    │
  │    ├─ Break FInventorySlot → Item
  │    ├─ Item → Get Item Type == Consumable?
  │    │    └─ True:
  │    │         ├─ Item → Get Consumable Data → Health Restore
  │    │         ├─ Get BPC_HealthSystem → Apply Healing (HealthRestore)
  │    │         ├─ Inventory → Remove Item (Item, 1)
  │    │         └─ Break (exit loop — only use one)
  │    │
  │    └─ Continue loop

---

4. Verification Checklist

• Data Asset: DA_Item_MedKit has ItemType = Consumable, HealthRestore = 25, StackLimit = 5
• Pickup in level: Mesh appears, bobs, interaction prompt shows "Pick up MedKit"
• Inventory: Pick up medkit → appears in inventory slot. Pick up 4 more → they stack (quantity = 5). Pick up 6th → fails (stack limit).
• Use: Press use item key → health increases by 25, stack count decreases by 1
• Weight: Each medkit adds 1.0 to carry weight. Get Remaining Weight decreases by 1.0 per pickup.
• Full inventory: Pick up medkit when no slots left → "Inventory Full" feedback, pickup remains in world

---

5. Key Concepts

Concept	How It Works
Stacking	StackLimit = 5 on the Data Asset. BPC_InventorySystem.AddItem() auto-finds existing stacks and adds to them instead of creating new slots.
Consumed on use	bConsumedOnUse = true → BPC_ConsumableSystem calls RemoveItem() after applying effects. Set to false for reusable items (e.g., a reusable syringe with cooldown).
Soft references	WorldMesh is a TSoftObjectPtr<UStaticMesh> — it doesn't load into memory until Construction Script resolves it. This keeps memory low when assets aren't in use.
Inventory weight	BPC_InventorySystem.CurrentWeight auto-updates when items are added/removed. CanAddItem() checks weight capacity before pickup.