Item Architecture & Data Components

Items represent portable game objects held in player inventories, hotbars, armor slots, and world containers. In Pumpkin, item handling is divided into two primary subsystems:

1. Static Data Layer (pumpkin-data): Compile-time generated metadata including item IDs, max stack sizes, max durability, tool tier properties, food nutrition, and data components generated by pumpkin-codegen.
2. Dynamic Behavior Layer (pumpkin::item): Interactive right-click actions, projectile launching, eating durations, bow charging, and block interactions handled via the ItemBehaviour trait.

---

Static Items vs. Actionable Items

Item Type	Description	Examples	Runtime Behavior Struct Needed?
Passive Items	Items without active right-click effects	diamond, stick, iron_ingot, feather	No — Stacking, moving, crafting, and dropping are handled automatically by pumpkin-inventory.
Standard Block Items	Items corresponding directly to placeable blocks	stone, oak_planks, glass	No — Placement logic queries the target block's data.
Projectiles & Throwables	Items spawned into physical entities when thrown	snowball, egg, ender_pearl, splash_potion	Yes — Implements ItemBehaviour::normal_use.
Channeled / Charged Items	Items with use durations or charging animations	bow, crossbow, spyglass, trident	Yes — Implements get_use_duration, on_use_tick, on_stopped_using.
Tools with Block Interactions	Items modifying existing blocks in the world	hoe (tilling), axe (stripping), shovel (pathmaking)	Yes — Implements ItemBehaviour::use_on_block.

---

The ItemStack Structure

An ItemStack represents an instance of an item in an inventory container. It encapsulates:

• item: Reference to the static Item definition.
• item_count: Current stack size ($1 \le \text{count} \le \text{max_stack_size}$).
• Data Components: Dynamic properties attached to the item stack (custom names, lore, damage values, enchantments, potion effects).

use pumpkin_data::item::Item;
use pumpkin_data::item_stack::ItemStack;

// Create a new item stack
let mut stack = ItemStack::new(1, Item::DIAMOND_SWORD);

// Safely decrement stack count, respecting creative mode
stack.decrement_unless_creative(player.gamemode.load(), 1);

---

Data Components System

Modern Minecraft represents item properties via modular Data Components:

Component	Responsibility	Description
FoodImpl	Nutrition & Saturation	Controls hunger points restored and saturation ratio.
ConsumableImpl	Consumption Mechanics	Controls eating duration, sound effects, and animation types.
Damageable	Durability	Tracks current damage points and breaks when max durability is reached.
UseCooldown	Cooldown Group	Prevents item re-use for a specified duration in game ticks.
Enchantments	Enchantment Levels	Key-value mapping of applied enchantments and levels.

---

The Item Registry & Dispatch Architecture

Item interactions are managed by the ItemRegistry in crates/pumpkin/src/item/registry.rs:

1. Registration: At server startup, all ItemBehaviour implementations are registered along with their target numeric item IDs.
2. Interaction Routing: When a client sends use packets (CUseItem, CUseItemOn), Pumpkin evaluates cooldowns and routes execution to the registered ItemBehaviour.
3. Cooldown System: Players track active cooldowns keyed by cooldown group strings. If an item is on cooldown, interactions are canceled before calling the behavior.

---

Next Steps

To implement interactive mechanics for a new item, proceed to the practical guide:

• Adding an Item: Step-by-step instructions for implementing ItemMetadata, ItemBehaviour, managing cooldowns, and registering items.