add blueprints
This commit is contained in:
Lefteris Notas
255
docs/blueprints/04-inventory/25_BP_ItemPickup.md
Normal file
255
docs/blueprints/04-inventory/25_BP_ItemPickup.md
Normal file
@@ -0,0 +1,255 @@
|
||||
# `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
|
||||
Reference in New Issue
Block a user