72 lines
4.3 KiB
Markdown
72 lines
4.3 KiB
Markdown
# 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.
|