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

# Item Example — Flashlight (Tool)

**Item Type:** `Tool`
**Complexity:** Medium
**Systems Used:** `DA_ItemData`, `BP_ItemPickup`, `I_UsableItem`, `I_Toggleable`, `BPC_InventorySystem`, `BPC_EquipmentSlotSystem`
**What You Learn:** Data Asset setup, pickup actor with soft reference mesh, Construction Script wiring, toggleable active-use item, inventory integration

---

## 1. Create the DA_ItemData

### 1.1 — Create the Data Asset

```
Content Browser → Game/Items/
  (create folder "Items" if needed)
  Right-click → Miscellaneous → Data Asset
  Class: DA_ItemData
  Name: DA_Item_Flashlight
```

### 1.2 — Fill Core Properties

Open `DA_Item_Flashlight`:

| Property | Value | Notes |
|----------|-------|-------|
| `Item Tag` | `Framework.Item.Tool.Flashlight` | Must be registered in `DA_GameTagRegistry`. Tag hierarchy: Framework → Item → Tool → Flashlight |
| `Display Name` | "Flashlight" | Player sees this in inventory UI |
| `Description` | "A heavy-duty tactical flashlight. Click to toggle on/off." | Shown in inventory |
| `Icon` | `T_Flashlight_Icon` | Assign any texture; for prototype, use a white square |
| `World Mesh` | `SM_Flashlight` | **Soft reference** — doesn't need to be loaded at startup; Construction Script resolves it |
| `Weight` | `1.5` | Carried weight in your carry limit |
| `Stack Limit` | `1` | Cannot stack multiple flashlights |
| `Item Type` | `Tool` | Determines that `Equipment Data` panel shows |

### 1.3 — Fill Equipment Data

Scroll down — the `Equipment Data` panel appears because `ItemType == Tool`:

| Field | Value | Notes |
|-------|-------|-------|
| `Slot` | `Framework.Equipment.Slot.Tool` | Which equipment slot it goes into |
| `Damage` | `0` | Not a weapon |
| `Fire Rate` | `0` | Not a weapon |
| `Range` | `0` | N/A |
| `Magazine Size` | `0` | N/A |
| `Reload Time` | `0` | N/A |

### 1.4 — Save

File → Save (or Ctrl+S). The Data Asset is ready.

---

## 2. Create the BP_Pickup_Flashlight (World Pickup Actor)

This is the actor the player sees in the level. It reads the Data Asset and represents it in the world.

### 2.1 — Create Blueprint

```
Content Browser → Game/Pickups/
  (create folder "Pickups" if needed)
  Right-click → Blueprint Class → Actor
  Name: BP_Pickup_Flashlight
```

### 2.2 — Add Components

Open `BP_Pickup_Flashlight` → **Viewport** tab.

**Add Component** button (top-left of the Components panel):

| Order | Component Class | Name | Purpose |
|-------|----------------|------|---------|
| 1 | `StaticMeshComponent` | `Mesh` | Renders the flashlight 3D model in the world |
| 2 | `SphereComponent` | `PickupTrigger` | Detects when player is close enough to interact |
| 3 | *(Optional)* `PointLightComponent` | `BatteryIndicator` | Small glow showing the pickup has charge |

**Select `PickupTrigger` → Details:**
- `Sphere Radius` → `200.0`
- **Collision → Collision Presets** → `OverlapOnlyPawn`

**Select `Mesh` → Details:**
- **Collision → Collision Enabled** → `No Collision` (the sphere handles interaction; mesh collision is unnecessary)

Your Components panel should look like:

```
BP_Pickup_Flashlight (self)
  ├── DefaultSceneRoot
  ├── Mesh                  ← StaticMeshComponent
  ├── PickupTrigger         ← SphereComponent (radius 200)
  └── BatteryIndicator      ← PointLightComponent (optional)
```

### 2.3 — Create the ItemData Variable

In the **My Blueprint** panel (left side):

1. Click **+ Variable** → name: `ItemData` → type: **DA_ItemData → Object Reference**
2. Select the variable → Details:
   - **Instance Editable** → ✓
   - **Category** → `Pickup`
   - **Tooltip** → "The item Data Asset this pickup represents"

This is simpler than using a struct for a single item — you can expand to a struct later if you need more fields.

### 2.4 — Wire the Construction Script

Switch to the **Construction Script** tab (or open the graph). This runs when the blueprint is compiled or when you change `ItemData` in the editor.

```
[Construction Script]
  │
  ├─ ItemData (drag from My Blueprint → Get ItemData)
  │
  ├─ Is Valid? (ItemData)
  │    │
  │    ├─ Branch (Condition = IsValid result)
  │    │
  │    ├─ True:
  │    │    │
  │    │    ├─ ItemData → Get World Mesh
  │    │    │     This returns a TSoftObjectPtr<UStaticMesh>
  │    │    │     │
  │    │    │     └─ To Soft Object Reference (conversion node, or just drag from pin)
  │    │    │          └─ Resolve Soft Reference (or "Async Load Asset")
  │    │    │               │
  │    │    │               ├─ On Complete (if async) → Set Static Mesh (Mesh component, New Mesh = loaded asset)
  │    │    │               │
  │    │    │               └─ For Construction Script, use "Load Synchronous" to see it in editor immediately:
  │    │    │                    └─ Sync Load Asset (from soft ref) → Set Static Mesh (Mesh)
  │    │    │
  │    │    ├─ ItemData → Get Display Name → Set Actor Label
  │    │    │     (This renames the actor in the world to "Flashlight" so it's easy to find in the World Outliner)
  │    │    │
  │    │    └─ ItemData → Get Weight → (optional: store for physics if dropped)
  │    │
  │    └─ False:
  │         └─ Print String ("No ItemData assigned to BP_Pickup_Flashlight")
  │              └─ Only if Editor (not PIE/standalone)
```

**Exact node sequence:**

| Step | Right-click / Drag | Search | Connect |
|------|-------------------|--------|---------|
| 1 | Drag `ItemData` variable → Get | — | — |
| 2 | Drag from ItemData pin | `Is Valid` | Branch Condition |
| 3 | True branch → drag from ItemData | `Get World Mesh` | — |
| 4 | Drag from World Mesh pin | `Load Synchronous` | — |
| 5 | Drag `Mesh` component from Components → Get | — | Target of Set Static Mesh |
| 6 | Drag from Load Synchronous Return Value | `Set Static Mesh` (New Mesh) | — |
| 7 | Drag from ItemData → `Get Display Name` | — | To String (Auto) |
| 8 | Drag from string result | `Set Actor Label` → New Actor Label | — |

### 2.5 — Add I_Interactable Interface

1. **Class Settings** (toolbar button)
2. **Implemented Interfaces** → **Add** → search and select `UInteractable`
3. **Compile** (blue checkmark). Now these events appear:

#### Event Interact

```
Event Interact (Interface -> UInteractable)
  │ Interactor: AActor*
  │ Return Node expects a Boolean
  │
  ├─ Interactor → Get Component by Class → Class: UBPC_InventorySystem
  │    │
  │    └─ Is Valid?
  │         ├─ False → Return False (no inventory on this actor)
  │         │
  │         └─ True → [InventorySystem ref]
  │              │
  │              ├─ ItemData → Is Valid?
  │              │    └─ False → Return False
  │              │
  │              ├─ [InventorySystem] → Can Add Item
  │              │    ├─ Item: ItemData
  │              │    ├─ Quantity: 1
  │              │    └─ Result → Branch
  │              │         ├─ True:
  │              │         │    ├─ [InventorySystem] → Add Item (Item=ItemData, Quantity=1)
  │              │         │    │    → Result (int32, ignore)
  │              │         │    ├─ Destroy Actor
  │              │         │    └─ Return True
  │              │         └─ False:
  │              │              ├─ Print String ("Inventory full or cannot carry")
  │              │              └─ Return False
```

#### Event Can Interact

```
Event Can Interact (Interface -> UInteractable)
  │ Interactor: AActor*
  │ OutBlockReason: FText& (by reference)
  │ Return Node expects Boolean
  │
  ├─ ItemData → Is Valid?
  │    ├─ False → OutBlockReason = "No item data configured" → Return False
  │    └─ True → Return True
```

#### Event Get Interaction Prompt

```
Event Get Interaction Prompt (Interface -> UInteractable)
  │ Return Node expects FText
  │
  ├─ ItemData → Get Display Name
  ├─ Format Text: "Pick up {0}" (format with DisplayName)
  └─ Return the formatted text
```

### 2.6 — Optional: Bobbing & Rotation

In **Event Graph → Event BeginPlay**:

```
Event BeginPlay
  │
  ├─ Mesh → Set Collision Enabled → No Collision
  ├─ PickupTrigger → Set Collision Enabled → Query Only
  │
  ├─ [Create a Timeline named "FloatAnim"]
  │    │
  │    ├─ Float Track: 0.0 to 1.0, length 2.0 seconds, Looping ✓
  │    │
  │    └─ Timeline → Update pin:
  │         │
  │         ├─ Mesh → Add World Rotation
  │         │    ├─ Delta Rotation: (0, 0, TimelineOutput * 90.0)
  │         │    └─ Sweep: false, Teleport: false
  │         │
  │         └─ Mesh → Set World Location (interpolation)
  │              └─ Z = ActorLocation.Z + sin(TimelineOutput * 2π) * 5.0
  │                   (Use "Make Vector" → Break Actor Location → modify Z → "Lerp" or direct set)
  │
  └─ Play Timeline from Start
```

> For the bobbing math: `sin(TimelineOutput * 6.28318) * 5.0` gives a smooth ±5 unit bounce.

---

## 3. Create the BP_Flashlight (Active-Use Actor — Toggleable)

This is a separate Blueprint for the *held* flashlight — what the player actually uses after picking it up. It implements `I_UsableItem` and `I_Toggleable`.

### 3.1 — Create Blueprint

```
Content Browser → Game/Actors/
  Right-click → Blueprint Class → Actor
  Name: BP_Flashlight
```

### 3.2 — Add Components

| # | Component | Name | Purpose |
|---|-----------|------|---------|
| 1 | `StaticMeshComponent` | `BodyMesh` | Flashlight body |
| 2 | `SpotLightComponent` | `LightBeam` | The actual light cone |
| 3 | `AudioComponent` | `ClickSound` | Plays the toggle click sound |

Select `LightBeam` → Details:
- `Intensity` → `5000.0` (bright)
- `Inner Cone Angle` → `15.0`
- `Outer Cone Angle` → `30.0`
- **Visible** → false (starts off — player toggles it on)

### 3.3 — Add Toggle State Variable

**+ Variable** → Name: `bIsOn` → Type: `Boolean` → Default: `false`
- **Replication** → `Replicated` (if multiplayer)

### 3.4 — Add Interfaces

Class Settings → Interfaces → Add:
- `UUsableItem` — so the player can select and use it from inventory
- `UToggleable` — so the player can toggle it on/off

### 3.5 — Wire I_Toggleable

```
Event Toggle (Interface -> UToggleable)
  │ Toggler: AActor*
  │
  ├─ bIsOn = NOT bIsOn  (FlipFlop or Boolean NOT)
  │
  ├─ Branch (bIsOn)
  │    ├─ True:
  │    │    ├─ LightBeam → Set Visibility (true)
  │    │    ├─ ClickSound → Play
  │    │    └─ (Optional) Play toggle-on animation montage
  │    │
  │    └─ False:
  │         ├─ LightBeam → Set Visibility (false)
  │         └─ ClickSound → Play

Event Set State (Interface -> UToggleable)
  │ bNewState: Boolean, Setter: AActor*
  │
  ├─ Set bIsOn = bNewState
  ├─ LightBeam → Set Visibility (bNewState)
  └─ (Don't play click sound — this is programmatic, not player toggle)

Event Get Current State
  │ Return Boolean
  └─ Return bIsOn

Event Get State Label
  │ Return FText
  └─ Format Text: "Flashlight is {0}" → format with (bIsOn ? "ON" : "OFF")
```

### 3.6 — Wire I_UsableItem

```
Event Use Item (Interface -> UUsableItem)
  │ User: AActor*, Target: AActor*
  │ Return Boolean
  │
  ├─ Call Toggle (self, User)   ← reuses the I_Toggleable logic
  └─ Return True

Event Can Use Item
  │ User, Target
  │ Return Boolean
  └─ Return True  (can always toggle flashlight)

Event Get Use Duration
  │ Return Float
  └─ Return 0.0  (instant toggle)

Event On Item Used
  │ User: AActor*
  │
  └─ (Optional) Play a small haptic pulse on controller
```

### 3.7 — Compile & Save

The held flashlight is ready. When a player picks up `BP_Pickup_Flashlight` and the inventory's `BPC_ActiveItemSystem` routes the item to use, it calls `I_UsableItem.UseItem()` on this actor, which toggles the light.

---

## 4. Wire Inventory Integration

### 4.1 — In Your Player Pawn BP

When `BPC_ActiveItemSystem` detects that an item of type `Tool` is used:
1. Get the equipped item from `BPC_EquipmentSlotSystem`
2. Spawn `BP_Flashlight` actor (if not already spawned)
3. Call `I_UsableItem.UseItem()`
4. The flashlight actor handles its own toggle state

### 4.2 — Quick Test Without Full Integration

For a rapid prototype, add this to your **PlayerCharacter's Event Graph**:

```
Event InputAction (IA_UseItem, Pressed)
  │
  ├─ Branch (bFlashlightEquipped)   ← set this bool when flashlight is picked up
  │    ├─ True:
  │    │    ├─ Get All Actors of Class (BP_Flashlight)
  │    │    ├─ For Each → Call I_Toggleable.Toggle
  │    │    └─ (In production, use BPC_ActiveItemSystem instead of this crude search)
  │    └─ False: do nothing
```

---

## 5. Verification Checklist

**Step 1 — Data Asset:** Open `DA_Item_Flashlight` → all fields filled, no blank properties.

**Step 2 — Pickup in Editor:** Drag `BP_Pickup_Flashlight` into level → set `ItemData` → the mesh appears in viewport immediately (Construction Script).

**Step 3 — Pickup Interaction (PIE):**
- [ ] Walk up to flashlight pickup → interaction prompt appears ("Pick up Flashlight")
- [ ] Press Interact → flashlight disappears from world
- [ ] Check log/print: `BPC_InventorySystem.AddItem` was called
- [ ] In debug: `Get All Items` on inventory → flashlight is in a slot

**Step 4 — Held Use:**
- [ ] Toggle via IA_UseItem → light turns on (visible in world)
- [ ] Toggle again → light turns off
- [ ] Click sound plays on each toggle

**Step 5 — Equipment Slot:**
- [ ] Flashlight occupies `Framework.Equipment.Slot.Tool` slot
- [ ] Cannot equip another tool while flashlight is in slot (slot type validation)

---

## 6. Common Issues

| Issue | Cause | Fix |
|-------|-------|-----|
| Mesh doesn't appear in Construction Script | Soft reference not loaded | Use `Load Synchronous` instead of `Async Load Asset` in Construction Script |
| Pickup doesn't respond to interaction | `UInteractable` interface not added | Class Settings → Interfaces → Add `UInteractable` → Compile |
| "Can Add Item" always returns false | `BPC_InventorySystem.MaxWeight` too low or `GridWidth/Height = 0` | Set MaxWeight to 0 (unlimited) for testing, or increase it |
| Light doesn't toggle | `bIsOn` variable not replicated or `I_Toggleable` not wired | Verify `Toggle` event is called; check `Set Visibility` target is the correct light component |
| "No ItemData configured" error | Forgot to set `ItemData` on the pickup instance in the level | Select the pickup → Details → set ItemData → recompile |