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

Item Example — Keycard (Key Item)

Item Type: KeyItem Complexity: Low Systems Used: DA_ItemData, BP_ItemPickup, BPC_InventorySystem, BPC_KeyItemSystem, I_Lockable, BP_DoorActor What You Learn: Key item Data Asset, auto-protection from drop/clear, used-once pattern, door unlocking via I_Lockable

---

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_Keycard_Omega

1.2 — Fill Properties

Property	Value	Notes
Item Tag	Framework.Item.KeyItem.KeycardOmega	Unique — registered in DA_GameTagRegistry
Display Name	"Omega Keycard"	Player sees this
Description	"A high-security keycard labeled 'Omega Wing.'"	Shown in journal/inventory
Icon	T_Keycard_Icon	Card-shaped texture
World Mesh	SM_Keycard	Flat card mesh
Weight	0.1	Very light
Stack Limit	1	One per slot — cannot stack keycards
Item Type	KeyItem	Key items are auto-protected
b Is Key Item	✓ (checked)	This property also appears — it's a boolean flag
b Can Be Dropped	✗ (unchecked)	Key items should NOT be droppable (auto-forced by bIsKeyItem)

1.3 — Save

No sub-data needed. Key items don't have Equipment or Consumable data.

---

2. Create the BP_Pickup_KeycardOmega

Same pattern as other pickups:

2.1 — Create Blueprint

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

2.2 — Components

#	Component	Name	Purpose
1	StaticMeshComponent	Mesh	Card model
2	SphereComponent	PickupTrigger	Radius 150, OverlapOnlyPawn

2.3 — Variable

ItemData → Type: DA_ItemData → Object Reference → Instance Editable ✓

2.4 — Construction Script (same pattern)

ItemData → Get World Mesh → Load Synchronous → Set Static Mesh (Mesh)
ItemData → Get Display Name → Set Actor Label

2.5 — I_Interactable Wiring (same pattern)

Interactor → Get BPC_InventorySystem → CanAddItem(ItemData, 1)
  True → AddItem → Destroy Actor → Return True
  False → Print "Inventory Full" → Return False

---

3. Create the Lockable Door

3.1 — Create Door Blueprint

Content Browser → Game/Actors/
  Right-click → Blueprint Class → Actor (or BP_DoorActor from framework)
  Name: BP_Door_OmegaWing

3.2 — Add Components

#	Component	Name	Purpose
1	StaticMeshComponent	DoorFrame	The door frame (static)
2	StaticMeshComponent	DoorPanel	The moving door part
3	BoxComponent	InteractionTrigger	Door interaction range

3.3 — Add Interfaces

Class Settings → Interfaces → Add:

• UInteractable
• ULockable

3.4 — Variables

Variable	Type	Default	Purpose
bIsLocked	Boolean	true	Door starts locked
bIsOpen	Boolean	false	Door starts closed
RequiredKeyTag	GameplayTag	Framework.Item.KeyItem.KeycardOmega	Which key unlocks this

3.5 — Wire I_Lockable

Event Try Unlock (Interface -> ULockable)
  │ Unlocker: AActor*, KeyTag: FGameplayTag
  │ Return Boolean
  │
  ├─ bIsLocked? → Branch
  │    ├─ True:
  │    │    ├─ KeyTag == RequiredKeyTag? → Branch
  │    │    │    ├─ True:
  │    │    │    │    ├─ Set bIsLocked = false
  │    │    │    │    ├─ Unlocker → Get BPC_KeyItemSystem
  │    │    │    │    │    └─ Consume Key (KeyTag) ← removes key from inventory
  │    │    │    │    ├─ Print "Door unlocked with Omega Keycard"
  │    │    │    │    └─ Return True
  │    │    │    │
  │    │    │    └─ False:
  │    │    │         ├─ Print "Wrong key — requires Omega Keycard"
  │    │    │         └─ Return False
  │    │    │
  │    │    └─ False: (already unlocked)
  │    │         └─ Return True

Event Is Locked
  │ Return Boolean
  └─ Return bIsLocked

Event Get Required Key Tag
  │ Return FGameplayTag
  └─ Return RequiredKeyTag

Event Try Lock
  │ Locker: AActor*
  │ Return Boolean
  └─ Set bIsLocked = true → Return True  (re-lockable for puzzle purposes)

3.6 — Wire I_Interactable (on door)

Event Interact (Interface -> UInteractable)
  │ Interactor: AActor*
  │ Return Boolean
  │
  ├─ bIsLocked? → Branch
  │    ├─ True:
  │    │    ├─ Interactor → Get BPC_KeyItemSystem
  │    │    │    └─ Has Key(RequiredKeyTag)?
  │    │    │         ├─ True:
  │    │    │         │    ├─ Call Try Unlock (self, Interactor, RequiredKeyTag)
  │    │    │         │    └─ (If unlocked) → Open Door (see below)
  │    │    │         │
  │    │    │         └─ False:
  │    │    │              ├─ Print "Door is locked. Find Omega Keycard."
  │    │    │              └─ Return False
  │    │    │
  │    │    └─ Return False
  │    │
  │    └─ False: (door is unlocked)
  │         ├─ bIsOpen? → Branch
  │         │    ├─ True → Close Door → Return True
  │         │    └─ False → Open Door → Return True

Function: Open Door
  │
  ├─ Timeline (Rotation track, 0 → OpenAngle over OpenDuration)
  │    └─ Update: DoorPanel → Set Relative Rotation
  ├─ Set bIsOpen = true
  └─ (Optional) Play door creak sound

Function: Close Door
  │
  ├─ Timeline (Rotation track, OpenAngle → 0 over CloseDuration)
  │    └─ Update: DoorPanel → Set Relative Rotation
  ├─ Set bIsOpen = false
  └─ (Optional) Play door close sound

---

4. Wire BPC_KeyItemSystem (On Player Pawn)

The BPC_KeyItemSystem tracks which key items the player holds. It automates:

• Protecting key items from being dropped/cleared
• Validating key item requirements on door/lock interactions
• Removing consumed key items after use

In your BP child of BPC_KeyItemSystem:

Function: Has Key (KeyTag: GameplayTag) → Boolean
  │
  ├─ Get Owner → Get BPC_InventorySystem
  ├─ Get All Items → For Each Loop
  │    ├─ Item → Get bIsKeyItem → Branch
  │    │    ├─ True: Item → Get ItemTag == KeyTag? → Return True
  │    │    └─ False: Continue
  │    │
  │    └─ Loop end → Return False

Function: Consume Key (KeyTag: GameplayTag)
  │
  ├─ Get Owner → Get BPC_InventorySystem
  ├─ Has Key(KeyTag)? → Branch
  │    ├─ True: Inventory → Remove Item (by KeyTag, Quantity=1)
  │    └─ False: Print "No such key in inventory"

In the full framework, BPC_KeyItemSystem also prevents Clear Inventory and Drop operations from affecting key items by checking bIsKeyItem on the Data Asset.

---

5. Verification Checklist

Step 1 — Pickup:

• BP_Pickup_KeycardOmega placed in level, mesh visible
• Walk up → prompt "Pick up Omega Keycard" → press Interact → card goes to inventory

Step 2 — Inventory Protection:

• Keycard appears in inventory with "KEY" badge/indicator
• Try to drop keycard → blocked (cannot drop key items)
• Try "Clear Inventory" → keycard remains (protected)

Step 3 — Door Interaction:

• Walk up to BP_Door_OmegaWing while locked → prompt "Door is locked"
• Interact → door stays closed, shows "Requires Omega Keycard"
• Pick up keycard → walk to door → interact → door unlocks, keycard consumed from inventory
• Interact again → door opens

Step 4 — Wrong Key:

• Create a DA_Item_Keycard_Beta with a different tag
• Pick it up, try on Omega door → "Wrong key — requires Omega Keycard"
• Keycard_Beta stays in inventory (not consumed on wrong door)

---

6. KeyItem vs Regular Item — What's Different

Behavior	Regular Item	Key Item (bIsKeyItem = true)
Can be dropped?	Yes (if bCanBeDropped)	No (auto-protected)
Can be cleared (death/new game)?	Yes	No (preserved across death)
Stacks	Yes (up to StackLimit)	Usually StackLimit=1
Appears in inventory?	Yes	Yes, with KEY indicator
Consumed on use?	Depends on type	Yes (used once, then removed)
Sells to vendor?	Yes	No (protected from sale)

Key items exist specifically to gate progression. They're a player's permanent proof of having solved a puzzle, explored an area, or defeated a boss. The framework ensures they can't be accidentally lost.