add blueprints
This commit is contained in:
Lefteris Notas
264
docs/blueprints/04-inventory/24_BPC_ContainerInventory.md
Normal file
264
docs/blueprints/04-inventory/24_BPC_ContainerInventory.md
Normal file
@@ -0,0 +1,264 @@
|
||||
# `BPC_ContainerInventory` — Container / Loot Storage
|
||||
|
||||
**Parent Class:** `ActorComponent`
|
||||
**Category:** Inventory
|
||||
**Target UE Version:** 5.5–5.7
|
||||
**Build Phase:** 3 — Inventory
|
||||
|
||||
---
|
||||
|
||||
## 1. Overview
|
||||
|
||||
`BPC_ContainerInventory` provides an inventory for world actors like loot crates, drawers, cabinets, corpses, and safe storage. It shares the same `S_InventorySlot`/`S_InventoryEntry` structs as [`BPC_InventoryComponent`](docs/blueprints/04-inventory/22_BPC_InventoryComponent.md) but operates as a standalone container with no player controller — it is interacted with via [`BPC_InteractionDetector`](docs/blueprints/03-interaction/16_BPC_InteractionDetector.md) and transfers items to/from the player's inventory.
|
||||
|
||||
It supports lock state, loot tables (random fill from `DA_LootTable`), respawning, decay, and implements `I_Interactable` and `I_Persistable`.
|
||||
|
||||
---
|
||||
|
||||
## 2. Enums
|
||||
|
||||
### `E_ContainerLockState`
|
||||
|
||||
| Value | Description |
|
||||
|-------|-------------|
|
||||
| `Unlocked` | Anyone can open and loot. |
|
||||
| `Locked` | Requires key or lockpick to open. |
|
||||
| `Jammed` | Lock is broken; cannot be opened (visual only). |
|
||||
| `KeyRequired` | Requires specific key item from inventory. |
|
||||
| `PuzzleRequired` | Requires external puzzle completion. |
|
||||
|
||||
### `E_ContainerFillMethod`
|
||||
|
||||
| Value | Description |
|
||||
|-------|-------------|
|
||||
| `Fixed` | Contents defined in a `DA_FixedContainerContents` data asset. |
|
||||
| `LootTable` | Contents generated from a `DA_LootTable`. |
|
||||
| `Empty` | Starts empty; items placed manually by designer. |
|
||||
| `PlayerStored` | Items stored by the player (drop-off box, cupboard). |
|
||||
|
||||
### `E_ContainerLootRarity`
|
||||
|
||||
| Value | Description |
|
||||
|-------|-------------|
|
||||
| `Trash` | Junk items, low-value resources. |
|
||||
| `Common` | Standard consumables, basic resources. |
|
||||
| `Uncommon` | Better gear, moderate resources. |
|
||||
| `Rare` | Good weapons, valuable items. |
|
||||
| `Legendary` | Unique story items, top-tier gear. |
|
||||
|
||||
---
|
||||
|
||||
## 3. Structs
|
||||
|
||||
### `S_ContainerConfig`
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `ContainerName` | `FText` | Display name shown in UI ("Wooden Crate", "File Cabinet"). |
|
||||
| `MaxSlots` | `int32` | Number of inventory slots. |
|
||||
| `FillMethod` | `E_ContainerFillMethod` | How contents are generated. |
|
||||
| `LootTable` | `TArray<FName>` | Loot table IDs to roll on fill. |
|
||||
| `LockState` | `E_ContainerLockState` | Starting lock state. |
|
||||
| `RequiredKeyTag` | `FGameplayTag` | Required item tag if KeyRequired. |
|
||||
| `bCanRespawnLoot` | `bool` | If true, loot respawns after a timer. |
|
||||
| `RespawnTimeHours` | `float` | In-game hours before loot respawns. |
|
||||
| `bDecayEnabled` | `bool` | If true, items decay and disappear over time. |
|
||||
| `DecayTimeHours` | `float` | In-game hours before items decay entirely. |
|
||||
| `bIsPlayerStorage` | `bool` | If true, items persist and are safe (player stash). |
|
||||
| `bReplicates` | `bool` | Whether container state is replicated. |
|
||||
|
||||
### `S_ContainerLootEntry`
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `ItemData` | `DA_ItemData*` | Possible item to spawn. |
|
||||
| `Weight` | `float` | Relative spawn weight for random selection. |
|
||||
| `MinCount` | `int32` | Minimum stack count. |
|
||||
| `MaxCount` | `int32` | Maximum stack count. |
|
||||
| `Rarity` | `E_ContainerLootRarity` | Rarity tier for filtering. |
|
||||
| `bGuaranteed` | `bool` | If true, guaranteed to spawn (bypassed weighted chance). |
|
||||
|
||||
---
|
||||
|
||||
## 4. Variables
|
||||
|
||||
### Configuration (Instance Editable)
|
||||
|
||||
| Variable | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `ContainerConfig` | `S_ContainerConfig` | Primary container configuration. |
|
||||
| `FixedContents` | `TArray<FStartingItemEntry>` | Fixed items to place at BeginPlay. |
|
||||
|
||||
### State (Blueprint Read Only, Replicated)
|
||||
|
||||
| Variable | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `Slots` | `TArray<S_InventorySlot>` | Container inventory slots. |
|
||||
| `LockState` | `E_ContainerLockState` | Current lock state. |
|
||||
| `bIsLooted` | `bool` | True after initial loot has been taken. |
|
||||
| `bIsOpen` | `bool` | Whether the container UI is open. |
|
||||
|
||||
### Internal (Not Replicated)
|
||||
|
||||
| Variable | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `OwningInventoryComponent` | `BPC_InventoryComponent*` | Cached reference to interacting player's inventory (set when opened). |
|
||||
| `OwningActor` | `AActor*` | Cached owning actor (the container mesh). |
|
||||
| `RespawnTimerHandle` | `FTimerHandle` | Handle for loot respawn timer. |
|
||||
|
||||
---
|
||||
|
||||
## 5. Functions & Events
|
||||
|
||||
### Public Functions
|
||||
|
||||
| Function | Description |
|
||||
|----------|-------------|
|
||||
| `Interact_Implementation` | Implements `I_Interactable`: opens container UI if conditions met. |
|
||||
| `OpenContainer` | Called on interaction: sends `Slots` data to player's UI. |
|
||||
| `CloseContainer` | Closes container UI, clears interacting player reference. |
|
||||
| `AddItemToContainer` | Adds item to container slots (transfer from player). |
|
||||
| `RemoveItemFromContainer` | Removes item from container (transfer to player). |
|
||||
| `TryUnlock` | Attempts to unlock container with key/lockpick. |
|
||||
| `GenerateLoot` | Generates container contents from loot table or fixed data. |
|
||||
| `ClearContainer` | Empties all slots. |
|
||||
| `IsContainerEmpty` | Returns true if all slots are empty. |
|
||||
| `HasPlayerTransferTarget` | Returns true if a player is actively interacting with this container. |
|
||||
|
||||
### Protected Functions
|
||||
|
||||
| Function | Description |
|
||||
|----------|-------------|
|
||||
| `BeginPlay` | Caches references, calls `GenerateLoot` if fill method is `Fixed` or `LootTable`. |
|
||||
| `ValidatePlayerInteraction` | Checks distance, lock state, player alive state. |
|
||||
| `RollLootTable` | Performs weighted random selection from loot table. |
|
||||
| `StartRespawnTimer` | Starts timer for loot respawn. |
|
||||
| `OnRespawnTimer` | Calls `GenerateLoot` and refills slots. |
|
||||
| `StartDecayTimer` | Starts timer for item decay. |
|
||||
| `OnDecayTimer` | Removes all items, sets `bIsLooted = false`. |
|
||||
| `OnRep_Slots` | RepNotify: updates UI on remote client. |
|
||||
|
||||
### Event Dispatchers
|
||||
|
||||
| Dispatcher | Payload | Description |
|
||||
|------------|---------|-------------|
|
||||
| `OnContainerOpened` | `AActor* InteractingPlayer` | Fired when container is opened. |
|
||||
| `OnContainerClosed` | — | Fired when container UI is closed. |
|
||||
| `OnContainerItemAdded` | `S_InventoryEntry Item` | Fired on item transfer into container. |
|
||||
| `OnContainerItemRemoved` | `S_InventoryEntry Item` | Fired on item transfer out of container. |
|
||||
| `OnContainerUnlocked` | `AActor* Instigator` | Fired when container is unlocked. |
|
||||
| `OnContainerLootGenerated` | — | Fired after loot generation. |
|
||||
|
||||
---
|
||||
|
||||
## 6. Blueprint Graph Flow
|
||||
|
||||
```
|
||||
Event BeginPlay
|
||||
→ Cache OwningActor
|
||||
→ Create empty Slots array (MaxSlots)
|
||||
→ If FillMethod == Fixed → Add FixedContents
|
||||
→ If FillMethod == LootTable → Call GenerateLoot
|
||||
→ If LockState != Unlocked → Set bIsLocked as appropriate
|
||||
|
||||
OpenContainer
|
||||
→ ValidatePlayerInteraction → If fail → return
|
||||
→ Set bIsOpen = true
|
||||
→ Cache interacting player's inventory component
|
||||
→ Broadcast OnContainerOpened
|
||||
→ (BP implementation) Open UI widget showing container slots
|
||||
|
||||
CloseContainer
|
||||
→ Set bIsOpen = false
|
||||
→ Clear cached player inventory reference
|
||||
→ Broadcast OnContainerClosed
|
||||
→ If All slots empty → Set bIsLooted = true
|
||||
→ If bIsLooted and bCanRespawnLoot → StartRespawnTimer
|
||||
→ If bDecayEnabled and container has items → StartDecayTimer
|
||||
|
||||
GenerateLoot
|
||||
→ Clear all slots
|
||||
→ For each category in LootTable:
|
||||
→ For each S_ContainerLootEntry:
|
||||
→ If bGuaranteed → Add item to slot
|
||||
→ Else → Random roll against Weight
|
||||
→ If success → Random quantity between MinCount and MaxCount
|
||||
→ Add to slot
|
||||
→ Broadcast OnContainerLootGenerated
|
||||
|
||||
TryUnlock (ItemTag)
|
||||
→ If LockState == KeyRequired and ItemTag == RequiredKeyTag:
|
||||
→ Set LockState = Unlocked
|
||||
→ Broadcast OnContainerUnlocked
|
||||
→ Return true
|
||||
→ Else → Return false
|
||||
|
||||
AddItemToContainer (ItemData, Quantity)
|
||||
→ Find free slot → If none → return (container full)
|
||||
→ Find existing stack → If found and not full → increment
|
||||
→ Else → new slot
|
||||
→ If bReplicates → Mark slots dirty
|
||||
→ Broadcast OnContainerItemAdded
|
||||
|
||||
RemoveItemFromContainer (SlotIndex, Quantity)
|
||||
→ Decrement stack, clear slot if zero
|
||||
→ Broadcast OnContainerItemRemoved
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Replication
|
||||
|
||||
| Variable | Replication | Callback |
|
||||
|----------|-------------|----------|
|
||||
| `Slots` | `RepNotify` | `OnRep_Slots` — refreshes UI on remote clients |
|
||||
| `LockState` | `Replicated` | — |
|
||||
| `bIsOpen` | `Replicated` | — |
|
||||
| `bIsLooted` | `Replicated` | — |
|
||||
|
||||
---
|
||||
|
||||
## 8. Dependencies & Communication
|
||||
|
||||
| System | Relationship |
|
||||
|--------|--------------|
|
||||
| `BPC_InteractionDetector` | Detects container and routes interaction to `OpenContainer`. |
|
||||
| `BPC_InventoryComponent` | Target for item transfers when player loots the container. |
|
||||
| `DA_LootTable` | Data asset containing weighted loot entries. |
|
||||
| `BPC_InventoryUIManager` | Receives container slot data for display. |
|
||||
| `I_Persistable` | Container saves its inventory state for persistence. |
|
||||
| `BPC_LeverPuzzleComponent` | May unlock container when puzzle is solved (`PuzzleRequired` lock state). |
|
||||
| `BPC_PlayerMetricsTracker` | Logs loot acquisition events. |
|
||||
| `BPC_AdaptiveDifficulty` | May adjust loot table weights based on difficulty. |
|
||||
|
||||
---
|
||||
|
||||
## 9. Success Criteria
|
||||
|
||||
1. Player interacts with container → UI opens showing contents.
|
||||
2. Items can be transferred from container to player inventory.
|
||||
3. Items can be transferred from player inventory to container.
|
||||
4. Locked container plays feedback; unlocked with correct key.
|
||||
5. Fixed containers spawn designer-defined items.
|
||||
6. Loot-table containers generate random items with correct weighting.
|
||||
7. Empty containers show empty slots correctly.
|
||||
8. Respawn timer refills container after all loot is taken.
|
||||
9. Decay timer clears items after configured time.
|
||||
10. Multiplayer: container state syncs to all clients.
|
||||
11. Save/load restores container inventory and lock state.
|
||||
|
||||
---
|
||||
|
||||
## 10. Data Flow Summary
|
||||
|
||||
```
|
||||
Player approaches loot crate and presses Interact
|
||||
→ BPC_InteractionDetector → BP_LootCrate.Interact_Implementation
|
||||
→ BPC_ContainerInventory.OpenContainer
|
||||
→ Validate distance, lock state, player alive
|
||||
→ Send Slots array to UI
|
||||
→ Player clicks item in container UI
|
||||
→ BPC_ContainerInventory.RemoveItemFromContainer
|
||||
→ BPC_InventoryComponent.AddItem (transfer)
|
||||
→ Broadcast OnContainerItemRemoved
|
||||
→ UI updates both panels
|
||||
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
|
||||
86
docs/blueprints/04-inventory/26_BPC_ActiveItemSystem.md
Normal file
86
docs/blueprints/04-inventory/26_BPC_ActiveItemSystem.md
Normal file
@@ -0,0 +1,86 @@
|
||||
# BPC_ActiveItemSystem — Active Item System
|
||||
|
||||
**Parent Class:** `ActorComponent`
|
||||
**Category:** Inventory
|
||||
**Target UE Version:** 5.5–5.7
|
||||
**Build Phase:** 3 — Inventory
|
||||
|
||||
---
|
||||
|
||||
## 1. Overview
|
||||
|
||||
`BPC_ActiveItemSystem` manages the player's currently selected/active item and quick slot assignments. It reads from [`BPC_InventorySystem`](BPC_InventorySystem.md) and maps up to 8 quick slots to inventory items, handling hotkey input, item switching, and active item context (usable, throwable, consumable).
|
||||
|
||||
---
|
||||
|
||||
## 2. Enums
|
||||
|
||||
### `E_QuickSlot`
|
||||
|
||||
| Value | Description |
|
||||
|-------|-------------|
|
||||
| `Slot_1` | Hotkey 1 |
|
||||
| `Slot_2` | Hotkey 2 |
|
||||
| `Slot_3` | Hotkey 3 |
|
||||
| `Slot_4` | Hotkey 4 |
|
||||
| `Slot_5` | Hotkey 5 |
|
||||
| `Slot_6` | Hotkey 6 |
|
||||
| `Slot_7` | Hotkey 7 |
|
||||
| `Slot_8` | Hotkey 8 |
|
||||
|
||||
---
|
||||
|
||||
## 3. Variables
|
||||
|
||||
| Variable | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `QuickSlots` | `TMap<E_QuickSlot, FGuid>` | Hotkey → Inventory Item ID mapping |
|
||||
| `ActiveSlot` | `E_QuickSlot` | Currently selected quick slot |
|
||||
| `ActiveItem` | `S_InventoryEntry` | Currently active item data |
|
||||
| `bHasActiveItem` | `bool` | An item is currently selected |
|
||||
| `bCanSwitchItems` | `bool` | Item switching allowed (not during anim) |
|
||||
| `SwitchCooldown` | `float` | Min time between item switches |
|
||||
|
||||
---
|
||||
|
||||
## 4. Functions
|
||||
|
||||
| Function | Description |
|
||||
|----------|-------------|
|
||||
| `SetQuickSlot` | Assigns an inventory item to a quick slot |
|
||||
| `ClearQuickSlot` | Clears a quick slot assignment |
|
||||
| `SelectSlot` | Sets the active quick slot by key press |
|
||||
| `GetActiveItem` | Returns current `S_InventoryEntry` |
|
||||
| `UseActiveItem` | Uses/consumes the active item |
|
||||
| `CycleNextItem` | Selects the next populated quick slot |
|
||||
| `CyclePreviousItem` | Selects the previous populated quick slot |
|
||||
| `IsQuickSlotEmpty` | Returns true if quick slot has no item |
|
||||
| `GetQuickSlotItem` | Returns item in a specific quick slot |
|
||||
|
||||
---
|
||||
|
||||
## 5. Event Dispatchers
|
||||
|
||||
| Dispatcher | Payload | Description |
|
||||
|------------|---------|-------------|
|
||||
| `OnActiveItemChanged` | `S_InventoryEntry NewItem`, `E_QuickSlot Slot` | Active item switched |
|
||||
| `OnQuickSlotAssigned` | `E_QuickSlot Slot`, `FGuid ItemID` | Item assigned to quick slot |
|
||||
| `OnQuickSlotCleared` | `E_QuickSlot Slot` | Quick slot cleared |
|
||||
| `OnActiveItemUsed` | `S_InventoryEntry Item` | Active item consumed |
|
||||
|
||||
---
|
||||
|
||||
## 6. Dependencies & Communication
|
||||
|
||||
| System | Relationship |
|
||||
|--------|--------------|
|
||||
| `BPC_InventorySystem` | Reads inventory slots; source of truth for items |
|
||||
| `BPC_EquipmentSlotSystem` | Automatically updates quick slots on equipment change |
|
||||
| `WBP_HUDController` | Displays active item in HUD |
|
||||
| `BPC_HealthSystem` | Consumed health items trigger healing |
|
||||
|
||||
---
|
||||
|
||||
## 7. Reuse Notes
|
||||
- Quick slots are configurable per project (4-8 slots)
|
||||
- Active item system is the bridge between inventory data and gameplay input
|
||||
49
docs/blueprints/04-inventory/27_BPC_CollectibleTracker.md
Normal file
49
docs/blueprints/04-inventory/27_BPC_CollectibleTracker.md
Normal file
@@ -0,0 +1,49 @@
|
||||
# BPC_CollectibleTracker — Collectible Tracker
|
||||
|
||||
**Parent Class:** `ActorComponent`
|
||||
**Category:** Inventory
|
||||
**Target UE Version:** 5.5–5.7
|
||||
**Build Phase:** 3 — Inventory
|
||||
|
||||
## 1. Overview
|
||||
|
||||
`BPC_CollectibleTracker` tracks player collection of rare/optional items — figurines, hidden artifacts, secret tapes. Supports per-collection progress, completion rewards, and UI indicators for collectible hunters.
|
||||
|
||||
## 2. Variables
|
||||
|
||||
| Variable | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `CollectionProgress` | `TMap<FGameplayTag, int32>` | Collected count per collection type |
|
||||
| `CollectionTargets` | `TMap<FGameplayTag, int32>` | Total items per collection |
|
||||
| `bShowCollectibleNotifications` | `bool` | Toast on collectible pickup |
|
||||
| `CompletionRewards` | `TMap<FGameplayTag, TArray<FPrimaryAssetId>>` | Items granted on collection completion |
|
||||
|
||||
## 3. Functions
|
||||
|
||||
| Function | Description |
|
||||
|----------|-------------|
|
||||
| `OnCollectiblePickedUp` | Records collectible acquisition |
|
||||
| `GetProgress` | Returns progress (current/total) for a collection |
|
||||
| `IsCollectionComplete` | Checks if collection is fully completed |
|
||||
| `GetAllCollections` | Returns all tracked collections with progress |
|
||||
| `GetTotalCompletion` | Returns overall completion percentage |
|
||||
|
||||
## 4. Event Dispatchers
|
||||
|
||||
| Dispatcher | Payload | Description |
|
||||
|------------|---------|-------------|
|
||||
| `OnCollectibleFound` | `FGameplayTag CollectionTag`, `int32 NewCount` | New collectible acquired |
|
||||
| `OnCollectionComplete` | `FGameplayTag CollectionTag` | Collection fully completed |
|
||||
| `OnAllCollectionsComplete` | — | All collections complete |
|
||||
|
||||
## 5. Dependencies
|
||||
|
||||
| System | Relationship |
|
||||
|--------|--------------|
|
||||
| `BPC_InventorySystem` | Collectibles as inventory items |
|
||||
| `BPC_AchievementManager` | Achievement triggers for completions |
|
||||
| `WBP_HUDController` | Toast notification display |
|
||||
|
||||
## 6. Reuse Notes
|
||||
- Data-driven collection definitions via gameplay tags
|
||||
- Rewards are granted as inventory items on collection completion
|
||||
62
docs/blueprints/04-inventory/28_BPC_ConsumableSystem.md
Normal file
62
docs/blueprints/04-inventory/28_BPC_ConsumableSystem.md
Normal file
@@ -0,0 +1,62 @@
|
||||
# BPC_ConsumableSystem — Consumable System
|
||||
|
||||
**Parent Class:** `ActorComponent`
|
||||
**Category:** Inventory
|
||||
**Target UE Version:** 5.5–5.7
|
||||
**Build Phase:** 3 — Inventory
|
||||
|
||||
## 1. Overview
|
||||
|
||||
`BPC_ConsumableSystem` manages consumable item usage — health packs, stamina boosters, temporary buff items, and one-time-use consumables. Reads from [`BPC_InventorySystem`](BPC_InventorySystem.md) and applies effects through the relevant player systems.
|
||||
|
||||
## 2. Variables
|
||||
|
||||
| Variable | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `ConsumableCooldown` | `float` | Global cooldown between consumable uses |
|
||||
| `ActiveBuffs` | `TArray<S_ActiveBuff>` | Currently active temporary buffs |
|
||||
| `bCanUseConsumables` | `bool` | Master toggle (blocked during certain states) |
|
||||
|
||||
## 3. Structs
|
||||
|
||||
### `S_ActiveBuff`
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `BuffTag` | `FGameplayTag` | Buff identifier |
|
||||
| `RemainingDuration` | `float` | Time remaining |
|
||||
| `BuffData` | `DA_ItemData*` | Source item data |
|
||||
| `AffectedStat` | `E_PlayerStat` | Health, Stamina, Speed, Stress, Damage |
|
||||
|
||||
## 4. Functions
|
||||
|
||||
| Function | Description |
|
||||
|----------|-------------|
|
||||
| `UseConsumable` | Uses a consumable item from inventory slot |
|
||||
| `ApplyBuff` | Applies a temporary buff to the player |
|
||||
| `RemoveBuff` | Removes a buff by tag |
|
||||
| `GetActiveBuffs` | Returns all active buffs |
|
||||
| `HasBuff` | Checks if a specific buff is active |
|
||||
| `TickBuffs` | Decrements buff durations, removes expired |
|
||||
|
||||
## 5. Event Dispatchers
|
||||
|
||||
| Dispatcher | Payload | Description |
|
||||
|------------|---------|-------------|
|
||||
| `OnConsumableUsed` | `S_InventoryEntry Item` | Consumable item used |
|
||||
| `OnBuffApplied` | `FGameplayTag BuffTag`, `float Duration` | Buff activated |
|
||||
| `OnBuffExpired` | `FGameplayTag BuffTag` | Buff ended |
|
||||
|
||||
## 6. Dependencies
|
||||
|
||||
| System | Relationship |
|
||||
|--------|--------------|
|
||||
| `BPC_InventorySystem` | Reads and modifies consumable items |
|
||||
| `BPC_HealthSystem` | Health restoration via consumables |
|
||||
| `BPC_StaminaSystem` | Stamina restoration |
|
||||
| `BPC_StressSystem` | Stress reduction items |
|
||||
| `BPC_MovementStateSystem` | Speed buffs |
|
||||
|
||||
## 7. Reuse Notes
|
||||
- All consumable effects are data-driven via DA_ItemData
|
||||
- Buffs support stacking (multiple buffs active simultaneously)
|
||||
49
docs/blueprints/04-inventory/29_BPC_DocumentArchiveSystem.md
Normal file
49
docs/blueprints/04-inventory/29_BPC_DocumentArchiveSystem.md
Normal file
@@ -0,0 +1,49 @@
|
||||
# BPC_DocumentArchiveSystem — Document Archive System
|
||||
|
||||
**Parent Class:** `ActorComponent`
|
||||
**Category:** Inventory
|
||||
**Target UE Version:** 5.5–5.7
|
||||
**Build Phase:** 3 — Inventory
|
||||
|
||||
## 1. Overview
|
||||
|
||||
`BPC_DocumentArchiveSystem` manages collected documents — notes, letters, audio logs, data files. Tracks read/unread status, organizes by category, and provides query functions for UI and narrative systems.
|
||||
|
||||
## 2. Variables
|
||||
|
||||
| Variable | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `CollectedDocuments` | `TArray<S_DocumentEntry>` | All collected documents |
|
||||
| `DocumentCategories` | `TArray<E_DocumentCategory>` | Notes, Letters, Audio, Data, Photos |
|
||||
| `bShowUnreadBadge` | `bool` | Highlight unread documents |
|
||||
| `UnreadCount` | `int32` | Total unread documents |
|
||||
|
||||
## 3. Functions
|
||||
|
||||
| Function | Description |
|
||||
|----------|-------------|
|
||||
| `AddDocument` | Adds a document to the archive |
|
||||
| `MarkAsRead` | Marks a document as read |
|
||||
| `MarkAllAsRead` | Marks all as read |
|
||||
| `GetDocumentsByCategory` | Returns filtered list |
|
||||
| `GetUnreadCount` | Returns unread count |
|
||||
| `HasDocument` | Checks if document is collected |
|
||||
|
||||
## 4. Event Dispatchers
|
||||
|
||||
| Dispatcher | Payload | Description |
|
||||
|------------|---------|-------------|
|
||||
| `OnDocumentCollected` | `S_DocumentEntry Document` | New document added |
|
||||
| `OnDocumentRead` | `FGuid DocumentID` | Document marked read |
|
||||
| `OnAllDocumentsRead` | — | All documents read |
|
||||
|
||||
## 5. Dependencies
|
||||
|
||||
| System | Relationship |
|
||||
|--------|--------------|
|
||||
| `BPC_InventorySystem` | Documents as inventory items |
|
||||
| `WBP_JournalDocumentViewer` | UI for viewing documents |
|
||||
| `BPC_LoreUnlockSystem` | Lore document triggers |
|
||||
|
||||
## 6. Reuse Notes
|
||||
- Documents are inventory items with `E_ItemCategory = Document`
|
||||
305
docs/blueprints/04-inventory/30_BPC_EquipmentSlotSystem.md
Normal file
305
docs/blueprints/04-inventory/30_BPC_EquipmentSlotSystem.md
Normal file
@@ -0,0 +1,305 @@
|
||||
# `BPC_EquipmentSlotSystem` — Equipment & Gear Slots
|
||||
|
||||
**Parent Class:** `ActorComponent`
|
||||
**Category:** Inventory
|
||||
**Target UE Version:** 5.5–5.7
|
||||
**Build Phase:** 3 — Inventory
|
||||
|
||||
---
|
||||
|
||||
## 1. Overview
|
||||
|
||||
`BPC_EquipmentSlotSystem` manages wearable gear slots on the player — head, torso, hands, legs, feet, backpack, eyewear, and accessory. It reads from the linked [`BPC_InventorySystem`](docs/blueprints/04-inventory/BPC_InventorySystem.md) and marks items as equipped/unequipped via the inventory's `S_InventoryEntry.bIsEquipped` flag.
|
||||
|
||||
Equipping moves stat modifiers (defense, move speed, carry capacity, sensory range) into a live `S_EquipmentModifiers` struct that other systems query. Unequipping removes them. Equipment also attaches skeletal meshes to character socket points for visual representation.
|
||||
|
||||
---
|
||||
|
||||
## 2. Mermaid — Equipment Flow
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[Player selects Equip Action] --> B{BPC_EquipmentSlotSystem.EquipItem}
|
||||
B --> C{Slot Occupied?}
|
||||
C -->|Yes| D[Unequip current item]
|
||||
C -->|No| E[Set Item.bIsEquipped = true]
|
||||
|
||||
D --> F[Remove modifiers from active pool]
|
||||
E --> G[Add modifiers to active pool]
|
||||
F --> H[Detach skeletal mesh from socket]
|
||||
G --> I[Attach skeletal mesh to socket]
|
||||
|
||||
H --> J[Broadcast OnEquipmentChanged]
|
||||
I --> J
|
||||
|
||||
J --> K[Systems Query Modifiers]
|
||||
K --> L[BPC_MovementStateSystem]
|
||||
K --> M[BPC_InventorySystem Weight]
|
||||
K --> N[BPC_HealthSystem Defense]
|
||||
K --> O[InteractionDetector Range]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Enums
|
||||
|
||||
### `E_EquipmentSlot`
|
||||
|
||||
| Value | Description |
|
||||
|-------|-------------|
|
||||
| `Head` | Helmets, masks, headgear. |
|
||||
| `Torso` | Chest armor, vests, jackets. |
|
||||
| `Hands` | Gloves, wrist devices. |
|
||||
| `Legs` | Pants, leg armor. |
|
||||
| `Feet` | Boots, shoes. |
|
||||
| `Backpack` | Back slot — increases carry capacity. |
|
||||
| `Eyewear` | Night vision, goggles, glasses. |
|
||||
| `Accessory_1` | Ring, necklace, badge (slot 1). |
|
||||
| `Accessory_2` | Ring, necklace, badge (slot 2). |
|
||||
| `Weapon_Primary` | Main weapon (slot shared with quick slots). |
|
||||
| `Weapon_Secondary` | Sidearm / backup weapon. |
|
||||
| `Tool` | Equipped tool (lockpick, scanner, flashlight). |
|
||||
|
||||
### `E_EquipResult`
|
||||
|
||||
| Value | Description |
|
||||
|-------|-------------|
|
||||
| `Success` | Item was equipped. |
|
||||
| `SlotOccupied` | Slot is full; unequip first. |
|
||||
| `NotEquippable` | Item's category does not match any slot. |
|
||||
| `ItemNotFound` | Item is not in inventory. |
|
||||
| `BlockedByState` | Cannot equip in current state (e.g., hiding). |
|
||||
| `BlockedByCondition` | Player condition blocks equip (e.g., injured arm). |
|
||||
|
||||
### `E_EquipAnimationType`
|
||||
|
||||
| Value | Description |
|
||||
|-------|-------------|
|
||||
| `Instant` | No animation — immediate attach. |
|
||||
| `Holster` | Holster/draw weapon animation. |
|
||||
| `Equip` | Generic equip animation (armor, backpack). |
|
||||
| `Unequip` | Generic unequip animation. |
|
||||
|
||||
---
|
||||
|
||||
## 4. Structs
|
||||
|
||||
### `S_EquipmentSlotDef`
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `Slot` | `E_EquipmentSlot` | Which slot this definition is for. |
|
||||
| `SocketName` | `FName` | Skeletal mesh socket to attach equipment visuals to. |
|
||||
| `AllowedCategories` | `TArray<E_ItemCategory>` | Item categories that can be equipped in this slot. |
|
||||
| `bMustBeEmptyToEquip` | `bool` | If true, slot must be empty before equipping. |
|
||||
| `bAutoEquipOnPickup` | `bool` | If true, items matching categories auto-equip. |
|
||||
|
||||
### `S_EquipmentModifiers`
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `DefenseBonus` | `float` | Flat damage reduction applied by HealthSystem (0.0 = none). |
|
||||
| `MoveSpeedModifier` | `float` | Multiplier for character max walk speed (1.0 = normal). |
|
||||
| `CarryCapacityBonus` | `float` | Additional kg the inventory can hold. |
|
||||
| `StaminaDrainModifier` | `float` | Multiplier for stamina drain rate (1.0 = normal). |
|
||||
| `SensoryRangeModifier` | `float` | Multiplier for detection range (1.0 = normal). |
|
||||
| `StressResistanceModifier` | `float` | Multiplier for stress gain (1.0 = normal, 0.5 = half). |
|
||||
| `HealthRegenPerSecond` | `float` | Passive health regen when equipped. |
|
||||
|
||||
### `S_EquipmentState`
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `EquippedItems` | `TMap<E_EquipmentSlot, FGuid>` | Map of slot → ItemID of equipped item. |
|
||||
| `ActiveModifiers` | `S_EquipmentModifiers` | Current summed modifiers from all equipped items. |
|
||||
| `VisualAttachments` | `TMap<E_EquipmentSlot, UChildActorComponent*>` | Map of slot → attached mesh component. |
|
||||
|
||||
---
|
||||
|
||||
## 5. Variables
|
||||
|
||||
### Configuration (Instance Editable)
|
||||
|
||||
| Variable | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `SlotDefinitions` | `TArray<S_EquipmentSlotDef>` | Definitions for each equipment slot. |
|
||||
| `bAllowUnequipInCombat` | `bool` | If false, cannot unequip during combat. |
|
||||
| `bAutoEquipStartingItems` | `bool` | If true, starting items with matching categories auto-equip. |
|
||||
| `bReplicates` | `bool` | Whether equipment state is replicated. |
|
||||
|
||||
### State (Blueprint Read Only, Replicated)
|
||||
|
||||
| Variable | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `EquippedItems` | `TMap<E_EquipmentSlot, FGuid>` | Currently equipped items by slot. |
|
||||
| `ActiveModifiers` | `S_EquipmentModifiers` | Summed modifier values from all equipped gear. |
|
||||
|
||||
### Internal (Not Replicated)
|
||||
|
||||
| Variable | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `OwningInventory` | `BPC_InventorySystem*` | Cached inventory reference. |
|
||||
| `OwningCharacter` | `ACharacter*` | Cached character for skeletal mesh attachment. |
|
||||
| `VisualAttachments` | `TMap<E_EquipmentSlot, AActor*>` | Spawned attachment actors/meshes. |
|
||||
|
||||
---
|
||||
|
||||
## 6. Functions & Events
|
||||
|
||||
### Public Functions
|
||||
|
||||
| Function | Description |
|
||||
|----------|-------------|
|
||||
| `EquipItem` | Equips an item from inventory to its matching slot. Returns `E_EquipResult`. Handles slot swap if occupied. |
|
||||
| `UnequipItem` | Unequips item from a slot. Returns result. Item stays in inventory. |
|
||||
| `UnequipAll` | Unequips all slots. Broadcasts final state. |
|
||||
| `GetEquippedItemInSlot` | Returns `S_InventoryEntry` for the item in a given slot. |
|
||||
| `GetSlotForItemCategory` | Returns the best `E_EquipmentSlot` for an item category. |
|
||||
| `IsSlotOccupied` | Returns true if a slot has an equipped item. |
|
||||
| `GetActiveModifiers` | Returns the current `S_EquipmentModifiers` struct. |
|
||||
| `GetEquippedItems` | Returns `TMap<E_EquipmentSlot, FGuid>` of all equipped items. |
|
||||
| `CanEquipItem` | Pre-checks if an item can be equipped (category, slot, state). Returns `E_EquipResult`. |
|
||||
| `CanUnequipSlot` | Pre-checks if a slot can be unequipped (not locked by state). |
|
||||
|
||||
### Protected Functions
|
||||
|
||||
| Function | Description |
|
||||
|----------|-------------|
|
||||
| `BeginPlay` | Caches inventory and character references, auto-equips starting items. |
|
||||
| `FindMatchingSlot` | Finds an `E_EquipmentSlot` whose allowed categories include the item's category. |
|
||||
| `ApplyEquipmentVisual` | Attaches a skeletal or static mesh to the character's socket. |
|
||||
| `RemoveEquipmentVisual` | Detaches and destroys the visual for a slot. |
|
||||
| `RecalculateModifiers` | Iterates all equipped items, sums modifier values into `ActiveModifiers`. |
|
||||
| `SetItemEquippedFlag` | Sets `bIsEquipped` on the inventory entry to true/false. |
|
||||
| `ValidateEquipState` | Called periodically or on save: verifies equipped items still exist in inventory. |
|
||||
| `OnRep_EquippedItems` | RepNotify: rebuilds visual attachments on remote clients. |
|
||||
|
||||
### Event Dispatchers
|
||||
|
||||
| Dispatcher | Payload | Description |
|
||||
|------------|---------|-------------|
|
||||
| `OnItemEquipped` | `E_EquipmentSlot Slot`, `S_InventoryEntry Item` | Fired after successful equip. |
|
||||
| `OnItemUnequipped` | `E_EquipmentSlot Slot`, `S_InventoryEntry Item` | Fired after successful unequip. |
|
||||
| `OnEquipmentChanged` | `S_EquipmentModifiers NewModifiers`, `S_EquipmentModifiers OldModifiers` | Fired when any modifier value changes. |
|
||||
| `OnEquipFailed` | `E_EquipResult Reason`, `E_EquipmentSlot Slot` | Fired when equip is rejected. |
|
||||
|
||||
---
|
||||
|
||||
## 7. Blueprint Graph Flow
|
||||
|
||||
```
|
||||
Event BeginPlay
|
||||
→ GetOwner → FindComponentByClass BPC_InventorySystem → Cache
|
||||
→ GetOwner → Cast to ACharacter → Cache
|
||||
→ If bAutoEquipStartingItems:
|
||||
→ Inventory has starting items → For each with matching slot → Call EquipItem
|
||||
|
||||
EquipItem (ItemID, Slot)
|
||||
→ CanEquipItem → If fail → return NotEquippable
|
||||
→ Get item from inventory by ItemID
|
||||
→ FindMatchingSlot (item's category)
|
||||
→ If slot is occupied → Call UnequipItem (current slot)
|
||||
→ SetItemEquippedFlag (true)
|
||||
→ Add to EquippedItems map
|
||||
→ ApplyEquipmentVisual (slot, item)
|
||||
→ RecalculateModifiers
|
||||
→ Broadcast OnItemEquipped
|
||||
→ Broadcast OnEquipmentChanged
|
||||
→ Return Success
|
||||
|
||||
UnequipItem (Slot)
|
||||
→ CanUnequipSlot → If fail → return BlockedByState
|
||||
→ Get ItemID from EquippedItems (Slot)
|
||||
→ Get item from inventory by ItemID
|
||||
→ SetItemEquippedFlag (false)
|
||||
→ Remove from EquippedItems map
|
||||
→ RemoveEquipmentVisual (Slot)
|
||||
→ RecalculateModifiers
|
||||
→ Broadcast OnItemUnequipped
|
||||
→ Broadcast OnEquipmentChanged
|
||||
→ Return Success
|
||||
|
||||
ApplyEquipmentVisual (Slot, Item)
|
||||
→ Get SocketName from SlotDefinitions for this slot
|
||||
→ If item has skeletal mesh → SpawnAttached SkeletalMeshComponent to socket
|
||||
→ If item has static mesh → SpawnAttached StaticMeshComponent to socket
|
||||
→ Store reference in VisualAttachments
|
||||
|
||||
RemoveEquipmentVisual (Slot)
|
||||
→ If VisualAttachments contains slot → Destroy attached component
|
||||
→ Remove from VisualAttachments map
|
||||
|
||||
RecalculateModifiers
|
||||
→ Zero out all modifier fields
|
||||
→ For each equipped item:
|
||||
→ Read modifiers from DA_ItemData.EquipmentModifiers
|
||||
→ Sum each field into ActiveModifiers
|
||||
→ Broadcast OnEquipmentChanged
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Replication
|
||||
|
||||
| Variable | Replication | Callback |
|
||||
|----------|-------------|----------|
|
||||
| `EquippedItems` | `RepNotify` | `OnRep_EquippedItems` — rebuilds visuals on remote |
|
||||
| `ActiveModifiers` | `Replicated` | — |
|
||||
|
||||
**Authority:** Server validates all equip/unequip operations. Client predicts input; server broadcasts authoritative state.
|
||||
|
||||
---
|
||||
|
||||
## 9. Dependencies & Communication
|
||||
|
||||
| System | Relationship |
|
||||
|--------|--------------|
|
||||
| `BPC_InventorySystem` | Source of item data; sets/reads `bIsEquipped` flag. |
|
||||
| `BPC_ActiveItemSystem` | Automatically updates quick slots when equipment changes. |
|
||||
| `BPC_HealthSystem` | Reads `ActiveModifiers.DefenseBonus` for damage calculations. |
|
||||
| `BPC_StaminaSystem` | Reads `ActiveModifiers.StaminaDrainModifier`. |
|
||||
| `BPC_MovementStateSystem` | Reads `ActiveModifiers.MoveSpeedModifier`. |
|
||||
| `BPC_StressSystem` | Reads `ActiveModifiers.StressResistanceModifier`. |
|
||||
| `BPC_CameraStateLayer` | May adjust camera based on head equipment (e.g., night vision overlay). |
|
||||
| `BPC_InteractionDetector` | Reads `ActiveModifiers.SensoryRangeModifier` for detection range. |
|
||||
| `BP_PlayerCharacter` (Skeletal Mesh) | Provides sockets for equipment visual attachment. |
|
||||
| `Save/Load System` | Serializes `EquippedItems` for restore. |
|
||||
| `UI (WBP_InventoryMenu)` | Subscribes to all dispatchers for visual updates. |
|
||||
|
||||
---
|
||||
|
||||
## 10. Success Criteria
|
||||
|
||||
1. Item equip swaps into slot; old item is unequipped automatically.
|
||||
2. Unequipped item stays in inventory, not lost.
|
||||
3. Modifiers are correctly summed from all equipped items.
|
||||
4. Visual meshes attach to the correct character sockets.
|
||||
5. Equipping a helmet with night vision applies the camera overlay.
|
||||
6. Carrying a backpack increases max carry weight.
|
||||
7. Equipping armor reduces incoming damage.
|
||||
8. Multiplayer: visual equipment and modifiers sync to remote clients.
|
||||
9. Save/load restores equipped state.
|
||||
10. Auto-equip on pickup works for configured item categories.
|
||||
|
||||
---
|
||||
|
||||
## 11. Data Flow Summary
|
||||
|
||||
```
|
||||
Player equips armor vest from inventory
|
||||
→ BPC_EquipmentSlotSystem.EquipItem (item ID, Torso slot)
|
||||
→ Validate (not occupied? category matches?)
|
||||
→ Set inventory entry bIsEquipped = true
|
||||
→ Add to EquippedItems map
|
||||
→ Attach vest skeletal mesh to Torso socket
|
||||
→ RecalculateModifiers → DefenseBonus, MoveSpeed, etc.
|
||||
→ Broadcast OnItemEquipped, OnEquipmentChanged
|
||||
→ BPC_HealthSystem reads new DefenseBonus
|
||||
→ BPC_MovementStateSystem reads new MoveSpeed
|
||||
→ UI updates equipment panel
|
||||
```
|
||||
|
||||
## 12. Reuse Notes
|
||||
|
||||
- Renamed from `BPC_EquipmentSystem` to `BPC_EquipmentSlotSystem` per Master naming convention.
|
||||
- Cross-references updated: `BPC_InventoryComponent` → `BPC_InventorySystem`, `BPC_InventoryQuickSlot` → `BPC_ActiveItemSystem`, `BPC_InventoryWeightSystem` → `BPC_ActiveItemSystem`.
|
||||
393
docs/blueprints/04-inventory/31_BPC_InventorySystem.md
Normal file
393
docs/blueprints/04-inventory/31_BPC_InventorySystem.md
Normal file
@@ -0,0 +1,393 @@
|
||||
# `BPC_InventorySystem` — Core Inventory System
|
||||
|
||||
**Parent Class:** `ActorComponent`
|
||||
**Category:** Inventory
|
||||
**Target UE Version:** 5.5–5.7
|
||||
**Build Phase:** 3 — Inventory
|
||||
|
||||
---
|
||||
|
||||
## 1. Overview
|
||||
|
||||
`BPC_InventorySystem` is the central inventory authority on the player. It manages an array of item instances (stackable, tagged, data-driven), handles add/remove/use/transfer operations, enforces capacity limits, and communicates state changes via Event Dispatchers. All other inventory subsystems (weight, quick slots, UI, equipment) read from this component as their single source of truth.
|
||||
|
||||
Items are stored as `S_InventoryEntry` structs referencing a `DA_ItemData` primary data asset plus runtime state (stack count, durability, custom metadata). Operations are validated by category, stack limits, and capacity before execution.
|
||||
|
||||
---
|
||||
|
||||
## 2. Mermaid — Inventory Architecture
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[External Request] --> B{BPC_InventorySystem}
|
||||
B --> C{Operation Type}
|
||||
C -->|AddItem| D[Validate: Has Space?]
|
||||
C -->|RemoveItem| E[Validate: Has Item?]
|
||||
C -->|UseItem| F[Validate: Usable?]
|
||||
C -->|TransferItem| G[Validate: Target Has Space?]
|
||||
C -->|DropItem| H[Spawn BP_ItemPickup in World]
|
||||
|
||||
D -->|Pass| I[Add to Array / Stack]
|
||||
D -->|Fail| J[Return Failure Reason]
|
||||
E -->|Pass| K[Remove from Array / Unstack]
|
||||
E -->|Fail| L[Return Failure Reason]
|
||||
F -->|Pass| M[Dispatch OnItemUsed]
|
||||
F -->|Fail| N[Return Failure Reason]
|
||||
|
||||
I --> O[Broadcast OnInventoryChanged]
|
||||
K --> O
|
||||
M --> O
|
||||
G --> P[Remove from Source / Add to Target]
|
||||
P --> O
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Enums
|
||||
|
||||
### `E_InventoryOperationResult`
|
||||
|
||||
| Value | Description |
|
||||
|-------|-------------|
|
||||
| `Success` | Operation completed successfully. |
|
||||
| `InventoryFull` | No free slots available. |
|
||||
| `ItemNotFound` | Specified item not in inventory. |
|
||||
| `StackLimitReached` | Item exists but stack is at maximum. |
|
||||
| `InsufficientQuantity` | Not enough of the item to remove. |
|
||||
| `ItemNotUsable` | Item cannot be used from inventory. |
|
||||
| `CategoryRestricted` | Item category not allowed in this inventory. |
|
||||
| `WeightCapacityExceeded` | Adding would exceed max weight. |
|
||||
|
||||
### `E_ItemCategory`
|
||||
|
||||
| Value | Description |
|
||||
|-------|-------------|
|
||||
| `Consumable` | Health items, food, drink, batteries. |
|
||||
| `KeyItem` | Story keys, access cards, puzzle tokens. |
|
||||
| `Weapon` | Firearms, melee weapons, tools. |
|
||||
| `Ammo` | Bullets, shells, energy cells. |
|
||||
| `Resource` | Crafting materials, scrap, components. |
|
||||
| `Document` | Notes, letters, audio logs, data files. |
|
||||
| `Equipment` | Wearable gear (armor, backpack, goggles). |
|
||||
| `QuestItem` | Mission-specific objects. |
|
||||
|
||||
### `E_SortMode`
|
||||
|
||||
| Value | Description |
|
||||
|-------|-------------|
|
||||
| `ByName` | Alphabetical by item name. |
|
||||
| `ByCategory` | Grouped by item category. |
|
||||
| `ByRarity` | Sorted by item rarity value. |
|
||||
| `ByWeight` | Sorted by weight ascending. |
|
||||
| `ByQuantity` | Sorted by stack count descending. |
|
||||
| `ByRecent` | Most recently acquired first. |
|
||||
|
||||
---
|
||||
|
||||
## 4. Structs
|
||||
|
||||
### `S_InventoryEntry`
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `ItemData` | `DA_ItemData*` | Reference to the item's data asset. |
|
||||
| `ItemID` | `FGuid` | Unique runtime ID for this item instance. |
|
||||
| `StackCount` | `int32` | Current number of this item in the stack. |
|
||||
| `MaxStackSize` | `int32` | Max per slot (from DA, overrideable). |
|
||||
| `Durability` | `float` | Current durability (0–1). |
|
||||
| `CustomTags` | `FGameplayTagContainer` | Runtime-added tags for quest tracking. |
|
||||
| `CustomData` | `TMap<FName, FString>` | Generic key-value store for per-instance data. |
|
||||
| `SlotIndex` | `int32` | The slot this entry occupies. |
|
||||
| `bIsEquipped` | `bool` | Whether this item is currently equipped. |
|
||||
|
||||
### `S_InventorySlot`
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `SlotIndex` | `int32` | Unique slot number within the inventory. |
|
||||
| `Entry` | `S_InventoryEntry` | The item occupying this slot (empty = null ItemData). |
|
||||
| `bIsLocked` | `bool` | If true, this slot cannot be modified. |
|
||||
| `bIsQuickSlot` | `bool` | If true, this slot is mapped to a hotkey. |
|
||||
| `CategoryRestriction` | `E_ItemCategory` | Only items of this category can occupy this slot. |
|
||||
|
||||
### `S_InventorySnapshot`
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `Slots` | `TArray<S_InventorySlot>` | Copy of all inventory slots at snapshot time. |
|
||||
| `TotalWeight` | `float` | Weight at snapshot time. |
|
||||
| `TotalItems` | `int32` | Count of non-empty slots. |
|
||||
| `SnapshotTimestamp` | `float` | Game time when snapshot was taken. |
|
||||
|
||||
### `S_ItemQuery`
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `CategoryFilter` | `E_ItemCategory` | Only return items of this category. |
|
||||
| `TagFilter` | `FGameplayTag` | Only return items with this tag. |
|
||||
| `NameFilter` | `FString` | Partial name match (case-insensitive). |
|
||||
| `bIncludeEquipped` | `bool` | If false, exclude equipped items. |
|
||||
| `bSortResult` | `bool` | If true, sort results by name. |
|
||||
|
||||
---
|
||||
|
||||
## 5. Variables
|
||||
|
||||
### Configuration (Instance Editable, Expose On Spawn)
|
||||
|
||||
| Variable | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `MaxSlots` | `int32` | Total number of inventory slots (default 24). |
|
||||
| `MaxWeightCapacity` | `float` | Maximum carry weight in kg. |
|
||||
| `bUseWeightSystem` | `bool` | If true, weight limits are enforced. |
|
||||
| `AllowedCategories` | `TArray<E_ItemCategory>` | Categories permitted in this inventory. Empty = all. |
|
||||
| `StartingItems` | `TArray<FStartingItemEntry>` | Items to add at BeginPlay. |
|
||||
| `bReplicates` | `bool` | Whether inventory state is replicated. |
|
||||
|
||||
### `FStartingItemEntry`
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `ItemData` | `DA_ItemData*` | Item data asset to add. |
|
||||
| `StackCount` | `int32` | Quantity to add. |
|
||||
| `AutoEquip` | `bool` | If true, equip immediately if possible. |
|
||||
|
||||
### State (Blueprint Read Only)
|
||||
|
||||
| Variable | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `Slots` | `TArray<S_InventorySlot>` | The actual inventory array. Replicated. |
|
||||
| `TotalWeight` | `float` | Current total weight of all items. |
|
||||
| `TotalItems` | `int32` | Current count of non-empty slots. |
|
||||
| `bIsOverEncumbered` | `bool` | True when TotalWeight exceeds MaxWeightCapacity. |
|
||||
|
||||
### Internal (Not Replicated)
|
||||
|
||||
| Variable | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `OwningPawn` | `APawn*` | Cached owning pawn reference. |
|
||||
| `OnItemCooldowns` | `TMap<FGuid, float>` | Map of ItemID → remaining cooldown seconds. |
|
||||
|
||||
---
|
||||
|
||||
## 6. Functions & Events
|
||||
|
||||
### Public Functions — Core Operations
|
||||
|
||||
| Function | Description |
|
||||
|----------|-------------|
|
||||
| `AddItem` | Adds an item instance. Returns `E_InventoryOperationResult` and the slot index. Handles stacking if item already exists and stack not full. |
|
||||
| `RemoveItem` | Removes `Quantity` of an item by `ItemID` or `SlotIndex`. Returns result and how many were actually removed. |
|
||||
| `RemoveItemByTag` | Removes first matching item by `FGameplayTag`. Returns result. |
|
||||
| `UseItem` | Uses/consumes item at slot. Returns result. Dispatches `OnItemUsed`. If consumable with limited uses, reduces stack. |
|
||||
| `DropItem` | Drops `Quantity` of item at slot. Creates `BP_ItemPickup` in world. Returns result and spawned actor. |
|
||||
| `TransferItem` | Moves item from this inventory to a target `BPC_InventorySystem`. Validates target capacity. |
|
||||
| `MoveItemToSlot` | Moves item from one slot to another (rearrange). Handles swapping if target slot is occupied. |
|
||||
| `SplitStack` | Splits a stack into two slots. Returns new slot index. |
|
||||
| `CombineStack` | Combines two stacks of the same item into one (if max allows). |
|
||||
|
||||
### Public Functions — Query
|
||||
|
||||
| Function | Description |
|
||||
|----------|-------------|
|
||||
| `HasItem` | Returns true if inventory contains an item with the given `ItemID` or matching `FGameplayTag`. |
|
||||
| `HasItemQuantity` | Returns total count of items matching a tag or data asset. |
|
||||
| `FindItemByTag` | Returns first `S_InventoryEntry` matching a gameplay tag. |
|
||||
| `FindAllItemsByCategory` | Returns `TArray<S_InventoryEntry>` filtered by category. |
|
||||
| `FindAllItemsByTag` | Returns `TArray<S_InventoryEntry>` filtered by gameplay tag. |
|
||||
| `GetItemAtSlot` | Returns `S_InventoryEntry` at the given slot index (or empty if slot is free). |
|
||||
| `GetSlotCount` | Returns total number of slots (empty + filled). |
|
||||
| `GetFreeSlotCount` | Returns number of empty slots. |
|
||||
| `IsInventoryFull` | Returns true if no free slots. |
|
||||
| `SortInventory` | Reorders slots by the given `E_SortMode`. |
|
||||
| `GetTotalWeight` | Returns current `TotalWeight`. |
|
||||
| `IsOverEncumbered` | Returns `bIsOverEncumbered`. |
|
||||
| `GetItemCooldownRemaining` | Returns seconds remaining for a given ItemID cooldown. |
|
||||
|
||||
### Protected Functions
|
||||
|
||||
| Function | Description |
|
||||
|----------|-------------|
|
||||
| `BeginPlay` | Caches owner, adds starting items, initialises empty slots array. |
|
||||
| `FindFreeSlot` | Returns the index of the first empty slot. Returns -1 if full. |
|
||||
| `FindExistingStack` | Finds slot index with same ItemData that is below MaxStackSize. |
|
||||
| `RecalculateWeight` | Iterates all slots and sums item weight. Updates `TotalWeight` and `bIsOverEncumbered`. |
|
||||
| `ValidateAddItem` | Pre-checks slot availability, weight capacity, category restrictions. Returns result. |
|
||||
| `ValidateRemoveItem` | Pre-checks item exists and has sufficient quantity. |
|
||||
| `SetSlot` | Internal: writes an entry to a specific slot index. |
|
||||
| `ClearSlot` | Internal: empties a slot. |
|
||||
| `OnRep_Slots` | RepNotify: recalculates weight and broadcasts `OnInventoryChanged`. |
|
||||
|
||||
### Event Dispatchers
|
||||
|
||||
| Dispatcher | Payload | Description |
|
||||
|------------|---------|-------------|
|
||||
| `OnInventoryChanged` | — | Fired on any add/remove/transfer/sort operation. |
|
||||
| `OnItemAdded` | `S_InventoryEntry Item`, `int32 SlotIndex` | Fired after an item is successfully added. |
|
||||
| `OnItemRemoved` | `S_InventoryEntry Item`, `int32 SlotIndex`, `int32 Quantity` | Fired after an item is removed. |
|
||||
| `OnItemUsed` | `S_InventoryEntry Item`, `AActor* Instigator` | Fired when UseItem successfully executes. |
|
||||
| `OnItemDropped` | `S_InventoryEntry Item`, `BP_ItemPickup* DroppedActor` | Fired when an item is dropped into the world. |
|
||||
| `OnItemTransferred` | `S_InventoryEntry Item`, `BPC_InventorySystem* TargetInventory` | Fired after transfer to another inventory. |
|
||||
| `OnStackSplit` | `S_InventoryEntry Original`, `S_InventoryEntry NewStack` | Fired when a stack is split into two. |
|
||||
| `OnStackCombined` | `S_InventoryEntry CombinedStack` | Fired when two stacks are merged. |
|
||||
| `OnOverEncumberedStateChanged` | `bool bIsOverEncumbered` | Fired when weight crosses the threshold. |
|
||||
| `OnItemCooldownStarted` | `FGuid ItemID`, `float Duration` | Fired when an item cooldown begins. |
|
||||
| `OnInventoryFull` | — | Fired when all slots are filled. |
|
||||
|
||||
---
|
||||
|
||||
## 7. Blueprint Graph Flow
|
||||
|
||||
```
|
||||
Event BeginPlay
|
||||
→ Set MaxSlots (from config)
|
||||
→ Create empty Slots array (Size = MaxSlots)
|
||||
→ For each StartingItem:
|
||||
→ Call AddItem (StartingItem.ItemData, StartingItem.StackCount)
|
||||
→ If StartingItem.AutoEquip → Call EquipItem on slot (via EquipmentSlotSystem)
|
||||
|
||||
AddItem (ItemData, Quantity)
|
||||
→ Call ValidateAddItem → If Fail → return result
|
||||
→ FindExistingStack (same ItemData, not full)
|
||||
→ Branch: Found?
|
||||
→ Yes → Increment stack by Quantity (clamped to MaxStackSize)
|
||||
→ If Quantity > remaining → FindFreeSlot for overflow
|
||||
→ No → FindFreeSlot
|
||||
→ If no free slot → return InventoryFull
|
||||
→ Create new S_InventoryEntry → Assign SlotIndex
|
||||
→ RecalculateWeight
|
||||
→ If bReplicates → Mark slots array dirty
|
||||
→ Broadcast OnItemAdded, OnInventoryChanged
|
||||
→ Return Success
|
||||
|
||||
RemoveItem (SlotIndex, Quantity)
|
||||
→ Call ValidateRemoveItem → If Fail → return result
|
||||
→ Decrement stack count by Quantity
|
||||
→ If stack count <= 0 → ClearSlot
|
||||
→ RecalculateWeight
|
||||
→ Broadcast OnItemRemoved, OnInventoryChanged
|
||||
→ Return Success
|
||||
|
||||
UseItem (SlotIndex)
|
||||
→ GetItemAtSlot → If empty → return ItemNotFound
|
||||
→ Check cooldown → If on cooldown → return failure
|
||||
→ Check bIsUsable from DA_ItemData → If not → return ItemNotUsable
|
||||
→ If item has cooldown → Add to OnItemCooldowns map
|
||||
→ Broadcast OnItemUsed
|
||||
→ If item is consumable (bConsumeOnUse from DA):
|
||||
→ Reduce stack by 1
|
||||
→ If stack = 0 → ClearSlot
|
||||
→ Broadcast OnInventoryChanged
|
||||
→ Return Success
|
||||
|
||||
DropItem (SlotIndex, Quantity, SpawnLocation, SpawnRotation)
|
||||
→ RemoveItem (SlotIndex, Quantity) → If fail → return
|
||||
→ SpawnActor BP_ItemPickup at location/rotation
|
||||
→ Set pickup's ItemData and StackCount
|
||||
→ Broadcast OnItemDropped
|
||||
→ Return Success + spawned actor
|
||||
|
||||
TransferItem (SlotIndex, TargetInventory, Quantity)
|
||||
→ Validate item exists and quantity sufficient
|
||||
→ Call TargetInventory.ValidateAddItem → If fail → return
|
||||
→ RemoveItem (SlotIndex, Quantity)
|
||||
→ TargetInventory.AddItem (ItemData, Quantity)
|
||||
→ Broadcast OnItemTransferred
|
||||
→ Return Success
|
||||
|
||||
SortInventory (SortMode)
|
||||
→ Build TMap of slot index → entry for non-empty slots
|
||||
→ Sort entries by SortMode rules
|
||||
→ Clear all slots
|
||||
→ Write sorted entries back into sequential slots
|
||||
→ Broadcast OnInventoryChanged
|
||||
|
||||
RecalculateWeight
|
||||
→ Sum = 0
|
||||
→ For each slot with non-null ItemData:
|
||||
→ Sum += ItemData.Weight * StackCount
|
||||
→ TotalWeight = Sum
|
||||
→ OldEncumbered = bIsOverEncumbered
|
||||
→ bIsOverEncumbered = Sum > MaxWeightCapacity
|
||||
→ If OldEncumbered != bIsOverEncumbered
|
||||
→ Broadcast OnOverEncumberedStateChanged
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Replication
|
||||
|
||||
| Variable | Replication | Callback |
|
||||
|----------|-------------|----------|
|
||||
| `Slots` | `RepNotify` | `OnRep_Slots` — refreshes UI, recalculates weight |
|
||||
| `TotalWeight` | `Replicated` | — |
|
||||
| `bIsOverEncumbered` | `Replicated` | — |
|
||||
| `TotalItems` | `Replicated` | — |
|
||||
|
||||
**Authority:** Server is authoritative for all add/remove/use operations. Clients predict UI updates but server validates and corrects.
|
||||
|
||||
**Cooldowns:** Managed locally (not replicated) but validated on server for authoritative actions.
|
||||
|
||||
---
|
||||
|
||||
## 9. Dependencies & Communication
|
||||
|
||||
| System | Relationship |
|
||||
|--------|--------------|
|
||||
| `DA_ItemData` | Each slot references a Data Asset for item properties. |
|
||||
| `BPC_ActiveItemSystem` | Listens to `OnInventoryChanged` and `OnOverEncumberedStateChanged`. |
|
||||
| `WBP_InventoryMenu` | Subscribes to all event dispatchers to update UI. |
|
||||
| `BPC_EquipmentSlotSystem` | Reads `bIsEquipped` flag; equips/unequips items via slot. |
|
||||
| `BP_ItemPickup` | Receives dropped items; sends pickup requests to `AddItem`. |
|
||||
| `BPC_InteractionDetector` | Routes pickup interaction to `AddItem`. |
|
||||
| `BPC_HealthSystem` | Consumed health items via `UseItem` trigger healing. |
|
||||
| `BPC_StaminaSystem` | Consumed stamina items via `UseItem` trigger stamina restore. |
|
||||
| `Save/Load System` | Serializes `Slots` array for save/restore. |
|
||||
| `BPC_PlayerMetricsTracker` | Logs item acquisition events. |
|
||||
| `BPC_DifficultyManager` | May adjust `MaxSlots` or `MaxWeightCapacity` based on difficulty. |
|
||||
|
||||
---
|
||||
|
||||
## 10. Success Criteria
|
||||
|
||||
1. Items can be added to inventory; duplicates stack up to `MaxStackSize`.
|
||||
2. Adding beyond slot capacity returns `InventoryFull`.
|
||||
3. Adding beyond weight capacity returns `WeightCapacityExceeded`.
|
||||
4. Items can be removed by slot index or gameplay tag; stacks decrement correctly.
|
||||
5. Using a consumable item reduces stack; item is removed at 0.
|
||||
6. Dropping an item spawns `BP_ItemPickup` in the world with correct data.
|
||||
7. Items can be transferred between inventories (player ↔ container).
|
||||
8. Inventory can be sorted by all sort modes.
|
||||
9. Stack splitting creates a new slot; combining merges stacks.
|
||||
10. Event dispatchers fire correctly for all operations.
|
||||
11. Multiplayer: inventory state is server-authoritative and syncs to clients.
|
||||
12. Save/load restores exact inventory state including custom data.
|
||||
|
||||
---
|
||||
|
||||
## 11. Data Flow Summary
|
||||
|
||||
```
|
||||
Player picks up item
|
||||
→ BPC_InteractionDetector detects BP_ItemPickup
|
||||
→ Player presses Interact
|
||||
→ BP_ItemPickup.ExecuteInteraction → BPC_InventorySystem.AddItem
|
||||
→ Validate (space, weight, category)
|
||||
→ Add to array / increment stack
|
||||
→ RecalculateWeight
|
||||
→ Broadcast OnItemAdded / OnInventoryChanged
|
||||
→ UI updates / Weight system reacts / Metrics logs
|
||||
|
||||
Player uses health item from inventory
|
||||
→ UI calls BPC_InventorySystem.UseItem (SlotIndex)
|
||||
→ Validate (exists, usable, cooldown)
|
||||
→ Broadcast OnItemUsed
|
||||
→ BPC_HealthSystem.OnItemUsed → ApplyHealing
|
||||
→ If consumable → reduce stack
|
||||
→ Broadcast OnInventoryChanged
|
||||
```
|
||||
|
||||
## 12. Reuse Notes
|
||||
|
||||
- Renamed from `BPC_InventoryComponent` to `BPC_InventorySystem` per Master naming convention.
|
||||
- Cross-references updated: `BPC_InventoryWeightSystem` → `BPC_ActiveItemSystem`, `BPC_InventoryQuickSlot` → `BPC_ActiveItemSystem`, `BPC_InventoryUIManager` → `WBP_InventoryMenu`, `BPC_EquipmentSystem` → `BPC_EquipmentSlotSystem`.
|
||||
56
docs/blueprints/04-inventory/32_BPC_ItemCombineSystem.md
Normal file
56
docs/blueprints/04-inventory/32_BPC_ItemCombineSystem.md
Normal file
@@ -0,0 +1,56 @@
|
||||
# BPC_ItemCombineSystem — Item Combine System
|
||||
|
||||
**Parent Class:** `ActorComponent`
|
||||
**Category:** Inventory
|
||||
**Target UE Version:** 5.5–5.7
|
||||
**Build Phase:** 3 — Inventory
|
||||
|
||||
## 1. Overview
|
||||
|
||||
`BPC_ItemCombineSystem` handles item combination and crafting — combining two or more inventory items to create new items. Supports recipe-based combinations, ingredient validation, and result generation.
|
||||
|
||||
## 2. Enums
|
||||
|
||||
### `E_CombineResult`
|
||||
| Value | Description |
|
||||
|-------|-------------|
|
||||
| `Success` | Items combined successfully |
|
||||
| `MissingIngredients` | Not all required items present |
|
||||
| `IncompatibleItems` | Items cannot be combined |
|
||||
| `InventoryFull` | No space for result item |
|
||||
| `RecipeNotFound` | No recipe matches combination |
|
||||
|
||||
## 3. Variables
|
||||
|
||||
| Variable | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `Recipes` | `TArray<DA_RecipeData*>` | Loaded recipe data assets |
|
||||
| `CombineCooldown` | `float` | Time between combine operations |
|
||||
| `bConsumeIngredients` | `bool` | Remove ingredients on combine |
|
||||
|
||||
## 4. Functions
|
||||
|
||||
| Function | Description |
|
||||
|----------|-------------|
|
||||
| `CombineItems` | Attempts to combine two items by slot index |
|
||||
| `GetValidRecipes` | Returns all recipes matching current inventory items |
|
||||
| `PreviewResult` | Shows result item without consuming ingredients |
|
||||
| `CanCombine` | Checks if two items have a valid recipe |
|
||||
|
||||
## 5. Event Dispatchers
|
||||
|
||||
| Dispatcher | Payload | Description |
|
||||
|------------|---------|-------------|
|
||||
| `OnCombineSuccess` | `S_InventoryEntry Result` | Items combined |
|
||||
| `OnCombineFailed` | `E_CombineResult Reason` | Combination failed |
|
||||
| `OnRecipeDiscovered` | `DA_RecipeData Recipe` | New recipe found |
|
||||
|
||||
## 6. Dependencies
|
||||
|
||||
| System | Relationship |
|
||||
|--------|--------------|
|
||||
| `BPC_InventorySystem` | Reads and modifies inventory items |
|
||||
| `DA_RecipeData` | Recipe definitions |
|
||||
|
||||
## 7. Reuse Notes
|
||||
- Data-driven recipe system; designers add recipes via data assets
|
||||
46
docs/blueprints/04-inventory/33_BPC_JournalSystem.md
Normal file
46
docs/blueprints/04-inventory/33_BPC_JournalSystem.md
Normal file
@@ -0,0 +1,46 @@
|
||||
# BPC_JournalSystem — Journal System
|
||||
|
||||
**Parent Class:** `ActorComponent`
|
||||
**Category:** Inventory
|
||||
**Target UE Version:** 5.5–5.7
|
||||
**Build Phase:** 3 — Inventory
|
||||
|
||||
## 1. Overview
|
||||
|
||||
`BPC_JournalSystem` manages the player journal — tracking discovered entries, quest notes, character bios, and lore entries. Provides query functions for UI display and narrative progression tracking.
|
||||
|
||||
## 2. Variables
|
||||
|
||||
| Variable | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `JournalEntries` | `TArray<S_JournalEntry>` | All journal entries |
|
||||
| `EntryCategories` | `TArray<E_JournalCategory>` | Quest, Character, Lore, Notes, Tips |
|
||||
| `UnreadCount` | `int32` | Total unread entries |
|
||||
| `bAutoAddOnDiscovery` | `bool` | Auto-add entries on narrative flag |
|
||||
|
||||
## 3. Functions
|
||||
|
||||
| Function | Description |
|
||||
|----------|-------------|
|
||||
| `AddJournalEntry` | Adds new entry |
|
||||
| `MarkAsRead` | Marks entry read |
|
||||
| `GetEntriesByCategory` | Returns filtered entries |
|
||||
| `HasEntry` | Checks if entry exists |
|
||||
| `GetUnreadCount` | Returns unread count |
|
||||
|
||||
## 4. Event Dispatchers
|
||||
|
||||
| Dispatcher | Payload | Description |
|
||||
|------------|---------|-------------|
|
||||
| `OnJournalEntryAdded` | `S_JournalEntry Entry` | New entry discovered |
|
||||
| `OnJournalEntryRead` | `FGuid EntryID` | Entry marked read |
|
||||
|
||||
## 5. Dependencies
|
||||
|
||||
| System | Relationship |
|
||||
|--------|--------------|
|
||||
| `BPC_NarrativeStateSystem` | Narrative-driven journal entries |
|
||||
| `WBP_JournalDocumentViewer` | UI display |
|
||||
|
||||
## 6. Reuse Notes
|
||||
- Journal entries are narrative-gated via gameplay tags
|
||||
49
docs/blueprints/04-inventory/34_BPC_KeyItemSystem.md
Normal file
49
docs/blueprints/04-inventory/34_BPC_KeyItemSystem.md
Normal file
@@ -0,0 +1,49 @@
|
||||
# BPC_KeyItemSystem — Key Item System
|
||||
|
||||
**Parent Class:** `ActorComponent`
|
||||
**Category:** Inventory
|
||||
**Target UE Version:** 5.5–5.7
|
||||
**Build Phase:** 3 — Inventory
|
||||
|
||||
## 1. Overview
|
||||
|
||||
`BPC_KeyItemSystem` manages key items — story-critical objects that unlock doors, trigger narrative events, or are required for puzzle completion. Tracks acquired keys, provides query for door/puzzle unlock checks, and supports key usage notifications.
|
||||
|
||||
## 2. Variables
|
||||
|
||||
| Variable | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `AcquiredKeys` | `TArray<FGameplayTag>` | Tags of all acquired key items |
|
||||
| `bShowKeyNotifications` | `bool` | Toast on key pickup |
|
||||
| `KeyItemCategory` | `E_ItemCategory` | KeyItem category filter |
|
||||
|
||||
## 3. Functions
|
||||
|
||||
| Function | Description |
|
||||
|----------|-------------|
|
||||
| `HasKey` | Checks if player has a specific key by tag |
|
||||
| `AddKey` | Registers a key item acquisition |
|
||||
| `RemoveKey` | Removes a key (if consumed) |
|
||||
| `GetAllKeys` | Returns all acquired key tags |
|
||||
| `CanUnlock` | Checks if player meets unlock requirements for a target |
|
||||
|
||||
## 4. Event Dispatchers
|
||||
|
||||
| Dispatcher | Payload | Description |
|
||||
|------------|---------|-------------|
|
||||
| `OnKeyAcquired` | `FGameplayTag KeyTag` | New key picked up |
|
||||
| `OnKeyUsed` | `FGameplayTag KeyTag`, `AActor* Target` | Key used on target |
|
||||
| `OnKeyRemoved` | `FGameplayTag KeyTag` | Key consumed/removed |
|
||||
|
||||
## 5. Dependencies
|
||||
|
||||
| System | Relationship |
|
||||
|--------|--------------|
|
||||
| `BPC_InventorySystem` | Keys as inventory items |
|
||||
| `BP_DoorActor` | Door unlock queries |
|
||||
| `BP_PuzzleDeviceActor` | Puzzle unlock gates |
|
||||
| `BPC_NarrativeStateSystem` | Key-based narrative flags |
|
||||
|
||||
## 6. Reuse Notes
|
||||
- Keys use gameplay tags for generic matching (any key with same tag works)
|
||||
- Supports consumable keys (removed after single use) and persistent keys
|
||||
Reference in New Issue
Block a user