Items and item stacks

An Item describes a reusable item type; an ItemStack is a mutable quantity of that type with durability and per-stack data. Item actions belong on item subclasses or the gameplay system that owns the interaction. Registries provide shared item identities, while inventory containers own stack placement and counts.

Type versus stack

Layer	Stores or decides
Item	Stable ID/name, stack and damage limits, rarity, and overridable item behavior.
Items / item registries	Shared item definitions used by recipes, entities, blocks, and UI.
ItemStack	Item reference, count, damage, and item-specific data carried by that stack.
IItemContainer	Where stacks are stored and how slots change.
ItemEntity	A dropped stack represented in the world.

Two stacks can merge only when their item, damage, and component-like data agree. Use ItemStack.IsSameItemSameComponents and its paired merge operations rather than comparing only item identity; otherwise combining named, enchanted, or variant-bearing stacks can discard state.

Use and interaction

The player routes a use action through the held stack and the owning item/block interaction path. Item exposes overridable behavior for item use, air use, attack attributes, and use timing; subclasses implement the details for food, tools, buckets, weapons, and other families. Item use may also change world state, consume a stack, damage a tool, or return a different stack. Keep those outcomes together so input, UI, and inventory do not duplicate item rules.

When adding an item, trace its registration, icon/mesh lookup, use caller, recipe references, drop or pickup path, and save path. Reuse existing item textures and import settings.

Save data and fidelity

Binary player and chunk serializers persist stacks through versioned formats. StoredStackExtras now covers custom names, anvil repair cost, enchantments, potion contents, map IDs, banner patterns, writable and written book data, stew effects, bucket entity data, Sulfur Cube contents, lodestone tracking, and firework data. The current format is version 7; earlier versions remain readable with defaults for fields they did not store. When adding stack state, update both write and read paths and decide how older saves should initialize it.

• Definitions and use behavior: src/Item/Item.cs, src/Item/Items.cs, and specialized item subclasses
• Stack state and compatibility: src/Item/ItemStack.cs
• Save encoding: src/Storage/StoredStackExtras.cs, PlayerDataStorage.cs, and ChunkSerializer.cs
• World drops: src/Entity/ItemEntity.cs