# `BP_ItemPickup` — World Item Pickup Actor

**Parent Class:** `Actor`
**Category:** Inventory
**Target UE Version:** 5.5–5.7
**Build Phase:** 3 — Inventory

---

## 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).

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.

---

## 2. Enums

### `E_PickupSpawnReason`

| Value | Description |
|-------|-------------|
| `PlacedInLevel` | Designer-placed in the map. |
| `DroppedFromInventory` | Player dropped from inventory. |
| `LootDrop` | Spawned as loot from a creature/container. |
| `QuestReward` | Spawned as a quest completion reward. |

### `E_PickupVisualState`

| Value | Description |
|-------|-------------|
| `Idle` | Default floating/rotating state. |
| `Highlighted` | Within interaction range; glowing outline. |
| `BeingPickedUp` | Playing pickup animation before destruction. |
| `Respawning` | Hidden while respawn timer counts down. |

---

## 3. Structs

### `S_PickupConfig`

| Field | Type | Description |
|-------|------|-------------|
| `ItemData` | `DA_ItemData*` | Primary item data asset reference. |
| `Quantity` | `int32` | Stack quantity (1 for non-stackable). |
| `SpawnReason` | `E_PickupSpawnReason` | Initial spawn reason. |
| `bIsInfinite` | `bool` | If true, item is never consumed on pickup. |
| `bRespawns` | `bool` | If true, re-appears after a timer. |
| `RespawnTimeSeconds` | `float` | Seconds before respawning (in-game or real-time based on config). |
| `bUsePhysicsOnDrop` | `bool` | If true, dropped items have physics simulation. |
| `DropVelocity` | `FVector` | Initial velocity when dropped from inventory. |
| `bAutoRotate` | `bool` | Whether the pickup rotates slowly while idle. |
| `RotationRate` | `FRotator` | Rotation speed when auto-rotate is enabled. |
| `bBobUpDown` | `bool` | Whether the pickup bobs up and down. |
| `BobAmplitude` | `float` | Bobbing height offset. |
| `BobFrequency` | `float` | Bobbing speed. |

### `S_PickupWorldState`

| Field | Type | Description |
|-------|------|-------------|
| `SpawnTransform` | `FTransform` | Transform at spawn time (for respawn reference). |
| `SpawnTime` | `float` | Game time at spawn. |
| `bHasBeenPickedUp` | `bool` | Whether pickup has ever been collected. |
| `PickedUpBy` | `AActor*` | Last player to pick up this item. |

---

## 4. Variables

### Configuration (Instance Editable)

| Variable | Type | Description |
|----------|------|-------------|
| `Config` | `S_PickupConfig` | Primary configuration. |
| `bAutoSetup` | `bool` | If true, auto-configures mesh and collision at `BeginPlay`. |
| `PickupWidgetClass` | `TSubclassOf<UUserWidget>` | Optional widget class for pickup prompt. |

### Scene Components (Create & Attach at Construction)

| Variable | Type | Description |
|----------|------|-------------|
| `RootScene` | `USceneComponent*` | Root component. |
| `MeshComponent` | `UStaticMeshComponent*` | Visual representation of item. |
| `InteractionCollision` | `USphereComponent*` | Overlap sphere for interaction detection. |
| `FloatCurveComponent` | `UFloatingPawnMovement*` | Optional floating/bobbing behaviour component. |

### State (Blueprint Read Only, Replicated)

| Variable | Type | Description |
|----------|------|-------------|
| `VisualState` | `E_PickupVisualState` | Current visual state. |
| `bIsAvailable` | `bool` | Whether the pickup can be collected. |

### Internal (Blueprint Read Only)

| Variable | Type | Description |
|----------|------|-------------|
| `WorldState` | `S_PickupWorldState` | Tracks pickup history. |
| `OwningInventory` | `BPC_InventoryComponent*` | Cached when player overlaps interaction trigger. |
| `RespawnTimerHandle` | `FTimerHandle` | Handle for respawn delay. |

---

## 5. Functions & Events

### Public Functions

| Function | Description |
|----------|-------------|
| `Interact_Implementation` | Implements `I_Interactable`: adds item to player inventory, 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. |
| `StartRespawn` | Hides pickup and starts countdown timer. |
| `OnRespawnComplete` | Restores pickup to world (visual + collision). |
| `GetPickupDisplayInfo` | Returns `FText` name and `UTexture2D*` icon for UI prompt. |

### Protected Functions

| Function | Description |
|----------|-------------|
| `OnOverlapBegin` | When player enters overlap: highlight, show pickup prompt. |
| `OnOverlapEnd` | When player leaves overlap: unhighlight, hide pickup prompt. |
| `OnPickupAnimationComplete` | Called after pickup animation ends (destroys actor or hides). |
| `PlayPickupFeedback` | Plays sound, particle, and/or widget animation. |

### Event Dispatchers

| Dispatcher | Payload | Description |
|------------|---------|-------------|
| `OnPickupAvailableChanged` | `bool bIsAvailable` | Broadcast when pickup becomes available/unavailable. |
| `OnPickupCollected` | `AActor* Collector` | Broadcast when item is successfully collected. |
| `OnPickupRespawnStarted` | `float RespawnTime` | Broadcast when respawn timer begins. |
| `OnPickupRespawned` | — | Broadcast when pickup reappears. |

---

## 6. Blueprint Graph Flow

```
Event BeginPlay
    → Cache WorldState.SpawnTransform = ActorTransform
    → If bAutoSetup → Set MeshComponent from ItemData
    → Configure collision presets (OverlapOnlyPawn)
    → Attach Timeline for bobbing / rotation
    → Start idle loop

OnOverlapBegin (Player overlaps InteractionCollision)
    → Set VisualState = Highlighted
    → Show pickup prompt widget (if assigned)
    → Cache player's BPC_InventoryComponent

OnOverlapEnd (Player leaves InteractionCollision)
    → Set VisualState = Idle
    → Hide pickup prompt widget
    → Clear cached inventory component reference

Interact_Implementation (Called from BPC_InteractionDetector)
    → If !bIsAvailable → return (no interaction)
    → 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)
    → If AddItem succeeded:
        → Broadcast OnPickupCollected(InteractingPlayer)
        → If bIsInfinite → do not destroy
        → Else → Deplete stack or destroy
        → If bRespawns → StartRespawn
        → Else → DestroyActor
    → Else:
        → Set VisualState = Idle
        → Show error feedback

OnDroppedFromInventory (ItemData, Quantity, DropLocation, DropVelocity)
    → Set Config with ItemData and Quantity
    → Set Config.SpawnReason = DroppedFromInventory
    → Set ActorTransform = DropLocation
    → If bUsePhysicsOnDrop → Enable physics on MeshComponent, apply velocity
    → Enable collision and visibility
    → Set bIsAvailable = true

StartRespawn
    → Set bIsAvailable = false
    → Hide MeshComponent, disable collision
    → Broadcast OnPickupRespawnStarted(RespawnTimeSeconds)
    → Start timer (RespawnTimerHandle, OnRespawnComplete, RespawnTimeSeconds)

OnRespawnComplete
    → Show MeshComponent, enable collision
    → Set bIsAvailable = true
    → Set VisualState = Idle
    → Broadcast OnPickupRespawned
```

---

## 7. Replication

| Variable | Replication | Callback |
|----------|-------------|----------|
| `bIsAvailable` | `Replicated` | — |
| `VisualState` | `Replicated Using` | `OnRep_VisualState` |
| `Config.Quantity` | `Replicated` | — |
| `WorldState.SpawnTransform` | `Replicated` | — |

---

## 8. Dependencies & Communication

| System | Relationship |
|--------|--------------|
| `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). |
| `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. |

---

## 9. Success Criteria

1. World-placed pickup shows mesh and collision at game start.
2. Player overlaps pickup → highlight activates + prompt widget shows.
3. Player leaves overlap → highlight deactivates + prompt hides.
4. Player interacts → item added to inventory, feedback plays, pickup destroyed.
5. Dropped from inventory → pickup spawns at correct transform with physics velocity.
6. Infinite pickups never deplete on collection.
7. Respawn pickups re-appear after configured timer.
8. Respawning pickups hide collision and mesh during cooldown.
9. Multiplayer: pickups replicate state to all clients.
10. Pickup prompt displays correct item name and icon.
11. No interaction if player inventory is full (feedback shown).

---

## 10. Data Flow Summary

```
Player approaches world item → Overlap event
    → BPC_InteractionDetector → BP_ItemPickup sets VisualState = Highlighted
    → Show pickup prompt widget
Player presses Interact key
    → BPC_InteractionDetector.InteractTarget → BP_ItemPickup.Interact_Implementation
    → Validate availability + inventory space
    → BPC_InventoryComponent.AddItem (ItemData, Quantity)
    → Play pickup sound + particle
    → Broadcast OnPickupCollected
    → If bRespawns → StartRespawn (hide, wait, reappear)
    → Else → DestroyActor