# 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`](https://github.com/Pumpkin-MC/Pumpkin/tree/master/crates/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`](/developer/codegen).
2. **Dynamic Behavior Layer ([`pumpkin::item`](https://github.com/Pumpkin-MC/Pumpkin/tree/master/crates/pumpkin/src/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`](https://github.com/Pumpkin-MC/Pumpkin/blob/master/crates/pumpkin-data/src/item.rs) 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).

```rust
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`](https://github.com/Pumpkin-MC/Pumpkin/blob/master/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](/developer/items/adding-items)**: Step-by-step instructions for implementing `ItemMetadata`, `ItemBehaviour`, managing cooldowns, and registering items.