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:

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.
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:

Registration: At server startup, all ItemBehaviour implementations are registered along with their target numeric item IDs.
Interaction Routing: When a client sends use packets (CUseItem, CUseItemOn), Pumpkin evaluates cooldowns and routes execution to the registered ItemBehaviour.
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.

4.3 KiB Raw Blame History