From 19b97772f8f7bb812d3a31c48170c7476347007e Mon Sep 17 00:00:00 2001 From: admin Date: Tue, 19 May 2026 11:10:20 +0000 Subject: [PATCH] Add Inventory, Items & Collectibles Systems --- ...ntory%2C-Items-%26-Collectibles-Systems.md | 243 ++++++++++++++++++ 1 file changed, 243 insertions(+) create mode 100644 Inventory%2C-Items-%26-Collectibles-Systems.md diff --git a/Inventory%2C-Items-%26-Collectibles-Systems.md b/Inventory%2C-Items-%26-Collectibles-Systems.md new file mode 100644 index 0000000..dab5051 --- /dev/null +++ b/Inventory%2C-Items-%26-Collectibles-Systems.md @@ -0,0 +1,243 @@ +# 04 — Inventory, Items & Collectibles Systems (Systems 24-34) + +**Category Purpose:** These 11 systems form the complete inventory management layer — core item storage grid, world containers, item pickups, consumable usage, equipment slots, item combination/crafting, key item tracking, document archiving, quick slots, journal tracking, and collectible progression. The `BPC_InventorySystem` is the single source of truth for all item data; every other inventory subsystem reads from and writes through it. + +--- + +## System Index + +| # | System | Asset Type | Role | +|---|--------|-----------|------| +| 24 | `BPC_ContainerInventory` | Component | World container inventory (chests, drawers, safes) | +| 25 | `BP_ItemPickup` | Actor | Physical item pickup in world with bob/rotate effects | +| 26 | `BPC_ActiveItemSystem` | Component | Quick-slot item management; contextual item use | +| 27 | `BPC_CollectibleTracker` | Component | Collectible tracking, found count, set bonuses | +| 28 | `BPC_ConsumableSystem` | Component | Consumable use (health packs, syringes, buffs) | +| 29 | `BPC_DocumentArchiveSystem` | Component | Document/journal archive; read, categorize, flag | +| 30 | `BPC_EquipmentSlotSystem` | Component | Equipment slots (weapon, armor, tool); equip/unequip | +| 31 | `BPC_InventorySystem` | Component | **Core inventory grid** — add/remove/sort/stack/weight | +| 32 | `BPC_ItemCombineSystem` | Component | Item combination crafting; recipe validation | +| 33 | `BPC_JournalSystem` | Component | Quest/objective journal; active, completed, failed | +| 34 | `BPC_KeyItemSystem` | Component | Key item tracking; use-on-target, consumed-on-use | + +--- + +## Category Data Flow + +``` +┌──────────────────────────────────────────────────────────────────────┐ +│ INVENTORY ECOSYSTEM │ +│ │ +│ BPC_InventorySystem (CENTRAL AUTHORITY) │ +│ │ Array of S_InventorySlot → each holds S_InventoryEntry │ +│ │ Operations: AddItem, RemoveItem, UseItem, DropItem, │ +│ │ TransferItem, MoveItem, SplitStack, SortInventory │ +│ │ │ +│ ├─► OnInventoryChanged → ALL other inventory systems react │ +│ │ │ +│ ├─► BPC_ActiveItemSystem (quick slots) │ +│ │ └─► Routes equip/use to EquipmentSlotSystem or Consumable │ +│ │ │ +│ ├─► BPC_EquipmentSlotSystem (equip/unequip) │ +│ │ └─► Validates slot type, notifies BP_WeaponBase │ +│ │ │ +│ ├─► BPC_ConsumableSystem (use health/stamina/stress items) │ +│ │ └─► Calls BPC_HealthSystem.ApplyHealing() etc. │ +│ │ │ +│ ├─► BPC_ItemCombineSystem (crafting) │ +│ │ └─► Reads DA_ItemData.CombinesWith/CombineResult │ +│ │ │ +│ ├─► BPC_KeyItemSystem (key item use-on-target) │ +│ │ └─► Checks I_Lockable on target, consumes key if matching │ +│ │ │ +│ ├─► BPC_DocumentArchiveSystem (reading documents) │ +│ ├─► BPC_JournalSystem (quest tracking) │ +│ ├─► BPC_CollectibleTracker (completion tracking) │ +│ │ │ +│ External interactions: │ +│ BP_ItemPickup ←── player picks up → BPC_InventorySystem.AddItem │ +│ BPC_ContainerInventory ←── looting → transfer between inventories │ +│ BPC_InventorySystem.DropItem → spawns BP_ItemPickup in world │ +└──────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 31 — BPC_InventorySystem: Core Inventory Grid + +**What It Does:** The central inventory authority on the player. Stores all items as an array of `S_InventorySlot` structs, each potentially containing an `S_InventoryEntry` with a reference to `DA_ItemData` plus runtime state (stack count, durability, custom metadata). All other inventory subsystems read from this component as their single source of truth. + +**How It Works Internally:** + +**Core Data Structures:** +- `S_InventorySlot`: SlotIndex, Entry (S_InventoryEntry), bIsLocked, bIsQuickSlot, CategoryRestriction +- `S_InventoryEntry`: ItemData (DA_ItemData*), ItemID (FGuid unique), StackCount, MaxStackSize, Durability, CustomTags, CustomData, SlotIndex, bIsEquipped +- Slots array is the authoritative item list + +**Operation Validation (every add/remove is validated):** +- `ValidateAddItem`: checks free slots, weight capacity (`TotalWeight + new weight <= MaxWeightCapacity`), category restrictions +- `ValidateRemoveItem`: checks item exists, sufficient quantity +- Returns `E_InventoryOperationResult`: Success, InventoryFull, ItemNotFound, StackLimitReached, InsufficientQuantity, ItemNotUsable, CategoryRestricted, WeightCapacityExceeded + +**Add Item Flow:** +1. `FindExistingStack()` — same ItemData, below MaxStackSize → increment stack +2. If overflow: `FindFreeSlot()` for remainder +3. If no existing stack: `FindFreeSlot()`, create new `S_InventoryEntry` +4. `RecalculateWeight()`, fire `OnItemAdded` + `OnInventoryChanged` + +**Remove Item Flow:** +1. Decrement stack count by Quantity +2. If stack <= 0: `ClearSlot()` +3. `RecalculateWeight()`, fire `OnItemRemoved` + `OnInventoryChanged` + +**Use Item Flow:** +1. Check cooldown (per-item cooldown map) +2. Check `bIsUsable` from DA_ItemData +3. Fire `OnItemUsed` → consumer systems react (health pack → heal, etc.) +4. If consumable: reduce stack, clear slot if 0 + +**Drop Item Flow:** +1. Remove item from inventory +2. Spawn `BP_ItemPickup` at world location with correct ItemData and StackCount +3. Fire `OnItemDropped` + +**Transfer Item Flow (between inventories):** +1. Validate source has item, target has space +2. Remove from source, add to target +3. Fire `OnItemTransferred` + +**Sort Modes:** ByName, ByCategory, ByRarity, ByWeight, ByQuantity, ByRecent + +**Weight System:** +- `RecalculateWeight()` iterates all slots, sums `ItemData.Weight * StackCount` +- `bIsOverEncumbered = TotalWeight > MaxWeightCapacity` +- `OnOverEncumberedStateChanged` fires on threshold crossing + +**Replication:** Slots array replicated with `RepNotify` → `OnRep_Slots` refreshes UI and recalculates weight + +**Implementation Patterns:** +- Stack split: creates new slot from partial stack +- Stack combine: merges two same-item slots into one (capped at MaxStackSize) +- `HasItemQuantity(Tag)` returns total count matching a tag across all slots +- `FindAllItemsByCategory/Tag` for filtered queries +- Cooldowns managed locally (not replicated), validated server-side + +**Integration Points:** +- **Broadcasts:** `OnInventoryChanged`, `OnItemAdded/Removed/Used/Dropped/Transferred`, `OnOverEncumberedStateChanged`, `OnInventoryFull` +- **Read by:** Every other inventory subsystem, `WBP_InventoryMenu`, `BPC_InteractionDetector` (pickup routing), Save System + +--- + +## 24 — BPC_ContainerInventory: World Container Storage + +**What It Does:** Provides inventory storage for world actors (crates, cabinets, corpses, safes). Uses the same `S_InventorySlot` structs as `BPC_InventorySystem` but operates standalone — interacted with via `BPC_InteractionDetector`, transfers items to/from the player's inventory. + +**Fill Methods:** +- `Fixed`: designer-defined contents via Data Asset +- `LootTable`: randomly generated from weighted loot table +- `Empty`: starts empty, filled by designer or player +- `PlayerStored`: safe storage that persists + +**Key Features:** +- Lock states: Unlocked, Locked, Jammed, KeyRequired, PuzzleRequired +- Loot rarity tiers: Trash, Common, Uncommon, Rare, Legendary +- `GenerateLoot()`: rolls weighted random selection, respects rarity filters +- Respawn timer: refills after `RespawnTimeHours` +- Decay timer: clears items after `DecayTimeHours` +- Implements `I_Interactable` and `I_Persistable` + +**Interaction Flow:** +1. Player interacts → `OpenContainer()`, validates distance/lock/alive +2. UI opens showing container slots +3. Player clicks: `RemoveItemFromContainer()` transfers to player inventory +4. Player places: `AddItemToContainer()` transfers from player inventory +5. `CloseContainer()` → if empty, mark `bIsLooted`, start respawn/decay timers + +--- + +## 25 — BP_ItemPickup: World Item Pickup Actor + +**What It Does:** A world-placed or runtime-spawned actor representing an item to pick up. Implements `I_Interactable` and optionally `I_Persistable`. Handles visual effects (bobbing, rotating), pickup animation, inventory transfer, and respawn. + +**Visual States:** Idle (floating/rotating) → Highlighted (within range, glowing outline) → BeingPickedUp (pickup animation) → Respawning (hidden during cooldown) + +**Spawn Reasons:** PlacedInLevel, DroppedFromInventory, LootDrop, QuestReward + +**Pickup Flow:** +1. Player overlaps interaction sphere → highlight, show prompt widget +2. Player leaves → unhighlight, hide prompt +3. Player interacts → validate availability + inventory space +4. Call `BPC_InventorySystem.AddItem(ItemData, Quantity)` +5. Play pickup sound + particle +6. If succeeded: broadcast `OnPickupCollected` +7. If infinite: don't destroy; if respawns: start timer; else: destroy + +**Drop from Inventory:** +- Called by `BPC_InventorySystem.DropItem` +- Sets transform, optionally applies physics velocity +- Configures respawn behavior + +--- + +## 28 — BPC_ConsumableSystem: Consumable Usage + +**What It Does:** Handles consumable item usage — health packs, stamina boosters, temporary buffs. Reads from `BPC_InventorySystem` when `OnItemUsed` fires for consumable items, applies effects through relevant player systems. + +**Key Features:** +- Global cooldown between consumable uses +- `ActiveBuffs` array tracks temporary buffs with durations +- `TickBuffs()` decrements durations, removes expired, fires `OnBuffExpired` +- Buff types affect: Health, Stamina, Speed, Stress, Damage +- All effects data-driven via `DA_ItemData.ConsumableData` + +**Integration:** Calls `BPC_HealthSystem.ApplyHealing()`, `BPC_StaminaSystem.RestoreStamina()`, `BPC_StressSystem.RemoveStress()` based on item data. + +--- + +## 30 — BPC_EquipmentSlotSystem: Equipment Slots + +**What It Does:** Manages equipment slots (primary weapon, secondary weapon, flashlight, shield, armor, tool). Validates equip/unequip operations against slot type restrictions and coordinates with `BP_WeaponBase` for visual attachment. + +**Key Features:** +- Slot types mapped to body sockets (equip socket, holster socket) +- Validation: slot type must match item's EquipmentData.SlotType +- Unequip returns item to inventory; equip removes from inventory slot +- `bIsEquipped` flag on inventory entry tracked +- Notifies animation system for equip/holster montages + +--- + +## 32 — BPC_ItemCombineSystem: Item Crafting + +**What It Does:** Handles item combination/crafting. Two items can be combined if one's `CombinesWith` array contains the other's ItemTag, producing the item specified in `CombineResult`. + +**Flow:** +1. Player selects two items in inventory UI +2. System checks: does ItemA.CombinesWith contain ItemB.ItemTag? (or vice versa) +3. If valid: remove both source items, add CombineResult item +4. Fire `OnItemsCombined` dispatcher + +--- + +## 26, 27, 29, 33, 34 — Supporting Subsystems + +- **26 BPC_ActiveItemSystem:** Quick-slot hotbar mapping. Manages which items are on quick slots (1-4), routes quick-use to correct system (equip weapon, use consumable). +- **27 BPC_CollectibleTracker:** Tracks found collectibles, fires dispatchers on set completion, unlocks rewards at milestones. +- **29 BPC_DocumentArchiveSystem:** Stores read documents, categorizes them, allows flagging as important, supports re-reading. +- **33 BPC_JournalSystem:** Quest/objective journal separate from inventory. Tracks active, completed, and failed objectives independently. +- **34 BPC_KeyItemSystem:** Key items that can be used on locked targets. Checks `I_Lockable` on target, consumes key if matching `RequiredKeyTag`. + +--- + +## Common Implementation Patterns in This Category + +1. **Central Authority Pattern:** `BPC_InventorySystem` is the single source of truth. All additions, removals, and modifications go through it. Subsystems read and react to its dispatchers. +2. **Data-Driven Items:** All item properties live in `DA_ItemData` Data Assets. Changing an item's behavior never requires Blueprint edits. +3. **Stack Management:** Duplicate items automatically stack to `MaxStackSize`; overflow creates new slots. +4. **Validation Before Action:** Every operation validates capacity, weight, stack limits, and category restrictions before executing. +5. **Dispatcher Cascade:** `OnInventoryChanged` fires on any modification → UI updates, weight recalculates, metrics log, save system marks dirty. +6. **Weight as Soft Limit:** Over-encumbered is a state flag, not a hard block — systems can choose to penalize movement or block sprinting. + +--- + +*Developer Reference v1.0 — 04 Inventory Systems. Companion to docs/blueprints/04-inventory/ specs.*