Add developer documentation for systems 11-16, including architecture overview and implementation patterns
- Created detailed documentation for systems 102-135 covering achievements, settings, polish, data assets, input management, and state management. - Added INDEX.md for easy navigation of developer reference materials. - Introduced architecture-overview.md to provide a high-level understanding of the framework's structure and communication methods. - Compiled implementation-patterns.md to outline common UE5 Blueprint patterns for consistent development practices.
This commit is contained in:
Lefteris Notas
243
docs/developer/04-inventory-systems.md
Normal file
243
docs/developer/04-inventory-systems.md
Normal file
@@ -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.*
|
||||
Reference in New Issue
Block a user