Inventory¶
Responsibility¶
inventory organizes item stacks for a character or temporary crafting view. It handles
insertion, removal, stacking, inventory letters, pseudo-tools, searches, and cache-backed
queries; it is distinct from pockets and from the inventory UI.
Entry points¶
Read src/inventory.h and src/inventory.cpp; character integration is in
src/character_inventory.cpp, temporary crafting views use form_from_map/form_from_zone,
and presentation belongs to inventory_ui.cpp.
Data ownership¶
The container owns its std::list<item> stacks. A character owns its durable inventory;
temporary inventories may copy or synthesize views, including pseudo-items, and therefore are
not authoritative owners of map or vehicle items.
Dependencies¶
Inventory depends on item stacking, visitable traversal, map zones, crafting requirements, character invlets, and item-location rules.
Lifecycle¶
Items are added, restacked, queried, consumed, or removed. Mutators mark ordering and query caches dirty; temporary crafting inventories are rebuilt from their source scope.
Invariants¶
Every item is in exactly one owning container; stack members are actually stackable; invlets respect assignment policy; and mutators invalidate cached amounts, charges, qualities, and sorted state.
Extension points¶
Add a focused query or mutation only when visitable/item-location APIs cannot express it. Presentation filters belong in inventory UI; pocket selection policy belongs in pockets.
Serialization¶
Inventory is persisted as part of its owning character rather than as an independent global object. Pseudo-items and query caches are reconstructed and must not become save authority.
Tests¶
Use advanced-inventory, temporary crafting inventory, item inventory-color, pickup, and item location tests. Cache-sensitive changes need a mutation followed by a repeated query.
Performance¶
form_from_map, restacking, and recursive visits can dominate crafting and UI latency. Use the
bulk-add path only with its documented invlet combinations and preserve source order.
CCB divergence¶
CCB contains a bulk insertion path with explicit ordering and invlet constraints. Do not port inventory optimizations without checking those constraints and CCB performance tests.
Technical debt¶
The same type serves durable inventories and synthesized crafting views. Code must keep that ownership distinction explicit until the roles can be separated safely.