Items¶
Responsibility¶
item represents one runtime item instance: type identity, charges, damage, flags, variables,
active state, craft state, unique ID, and nested item_contents. Static itype definitions
are created by item_factory; they are not copied into each instance.
Entry points¶
Begin with class item in src/item.h. Use the focused item_*.cpp file for naming, armor,
gun/tool/ammo, activation, degradation, or transformation behavior; creation enters through
item_factory and persistence through src/savegame_json.cpp.
Data ownership¶
An item owns its instance fields and contents. Containers own child items through pockets;
item_location is a relocatable reference, not ownership. itype_id resolves immutable
definition data in the factory.
Dependencies¶
Items depend on type registries, pockets, units, flags, use actors, recipes, effects, and the map/character/vehicle container that currently holds them.
Lifecycle¶
Items are spawned from a type, may activate, transform, split, stack, move between owners, and
eventually be consumed or destroyed. safe_reference and persistent item_uid cover distinct
identity needs and must not be conflated.
Invariants¶
Type pointers and IDs agree; nested contents satisfy pocket constraints; stacking compares all state that affects equivalence; charge-counted items follow their quantity rules; and moves do not leave stale locations or duplicate UIDs.
Extension points¶
Add content through item JSON and existing use actors where possible. Native behavior belongs in the focused item component, with loader, formatter, save compatibility, and tests updated together.
Serialization¶
item::serialize / deserialize and item_contents persistence live in
src/savegame_json.cpp. New fields need defaults for old saves; derived caches and safe
references are not durable state.
Tests¶
Select item, contents, pocket, stacking, name, spawn, location, or activation tests according to the invariant changed. Round-trip any durable instance field.
Performance¶
Item visits and name/info generation multiply across large inventories. Avoid recursive scans, string formatting, or factory lookup in hot predicates when a scoped cached value exists.
CCB divergence¶
CCB item JSON and runtime state may intentionally lag, port, or extend upstream contracts. Compare loaders, save fields, and tests before importing an upstream item change.
Technical debt¶
item remains a broad type split across many translation units. Keep new features in existing
components and resist adding another cross-cutting flag or unversioned variable convention.