Item pockets¶
Responsibility¶
item_pocket enforces storage constraints for one compartment: type, volume, weight, length,
liquid/gas sealing, ammo compatibility, flags, priorities, whitelists, and nested contents.
Entry points¶
Start with src/item_pocket.h and src/item_pocket.cpp; parent orchestration is in
item_contents.cpp, save code is in savegame_json.cpp, and insertion behavior is exercised
by tests/item_pocket_test.cpp.
Data ownership¶
A pocket owns the items placed in it plus favorite settings and pocket runtime state. Static capacity/configuration comes from pocket data on the parent item's type.
Dependencies¶
It depends on item dimensions and phases, units, ammo types, item locations, parent contents, characters performing moves, and JSON pocket definitions.
Lifecycle¶
Pockets are built from item type data, receive and remove items, seal or unseal, update favorite settings, and serialize with the parent item. Parent conversion can migrate or spill contents.
Invariants¶
Insertion must return a meaningful contain_code; capacity and phase constraints hold after
every mutation; an item has one owner; recursive containment cannot create a cycle; sealed
state agrees with pocket capability.
Extension points¶
Add a constraint to the centralized containment checks and expose a diagnostic reason. New
preference behavior belongs in favorite_settings; do not special-case it in inventory UI.
Serialization¶
item_pocket, favorite settings, and pocket data deserialize in savegame_json.cpp. Missing
fields need stable defaults, and migrations must preserve or explicitly reject contents.
Tests¶
Cover each new success and failure code, nested pockets, liquids, weight/volume limits, whitelist precedence, sealing, and a serialization round trip.
Performance¶
Autopickup and inventory organization evaluate many pockets. Keep acceptance checks allocation free where practical and avoid repeatedly walking nested contents.
CCB divergence¶
Pocket rules are a save- and mod-facing contract. Treat upstream pocket changes as migrations, and verify CCB JSON definitions and tests rather than assuming the same constraints.
Technical debt¶
Containment, preference policy, and serialization meet in one broad type. New code should keep pure feasibility checks separate from mutations and UI decisions.