🗡️ Item

Overview

An item is a single entry under items: in your configuration. Each one is keyed by its id — namespace:path, e.g. default:topaz_sword — and assembled from a handful of independent sections. material defaults to nether_brick (configurable in config.yml) and is ignored for vanilla item IDs — everything else is added when needed.

Anatomy

Every item follows the same skeleton. Each top-level key answers one question about the item:

items:
  default:my_item:            # the item id — referenced everywhere as default:my_item
    material: paper           # optional  → the vanilla item it's built on (default: config.yml)
    data:                     # optional  → what data components it has (name, lore, enchants…)
      ...
    model:                    # optional  → what it looks like         
      ...
    behavior:                 # optional  → what it can do on interaction (place a block, place furniture…)
      ...
    settings:                 # optional  → plugin-driven features (fuel, tags, repairable, enchantable…)
      ...
    events:                   # optional  → reactions to events
      ...

In addition to the sections above, a handful of root-level fields live directly on the item: custom_model_data, item_model, hand_animation_on_swap, oversized_in_gui, and swap_animation_scale. See Item Models → Root Fields for details.

Sections to Configure

🔢 Item DataName, lore, enchantments, attributes, food, durability — what data components the item has

🟰 Item ModelsModel type tree, simplified textures, tints, legacy overrides — what the item looks like

🕹️ Item BehaviorsWhat the item does — place a block, place furniture, mine in range, compost…

🔧 Item SettingsFuel time, tags, repairable, enchantable, dyeable — plugin-driven item properties

🪇 EventsReact to clicks, consumption, attacks & more with functions, gated by conditions

🔄 Item UpdaterVersioned item migration — update existing items when config changes

Quick Start

1. The smallest possible item

A texture alone is enough — material falls back to config.yml's default:

items:
  default:ruby:
    material: paper
    texture: minecraft:item/custom/ruby

2. Give it a name and a handheld model

Add data for the display name and switch to a tool base so it renders in 3D:

items:
  default:ruby_sword:
    material: golden_sword
    texture: minecraft:item/custom/ruby_sword
    data:
      item_name: "<!i><#FF8C00>Ruby Sword"
      lore:
        - "Forged in the depths"

3. Make it place a block

Add a behavior so right-clicking the item places a custom block:

items:
  default:ruby_sword:
    material: golden_sword
    texture: minecraft:item/custom/ruby_sword
    data:
      item_name: "<!i><#FF8C00>Ruby Sword"
    behavior:
      type: block_item
      block: default:ruby_block

4. Full control: explicit model, attributes, settings

Drop the simplified texture and use the full model definition. Add combat attributes and a tool tag:

items:
  default:ruby_sword:
    material: golden_sword
    custom_model_data: 10001
    data:
      item_name: "<!i><#FF8C00>Ruby Sword"
      attribute_modifiers:
        - type: attack_damage
          amount: 7
          operation: add_value
          slot: mainhand
    model:
      type: minecraft:model
      path: minecraft:item/custom/ruby_sword
      generation:
        parent: minecraft:item/handheld
        textures:
          layer0: minecraft:item/custom/ruby_sword
    settings:
      tags:
        - minecraft:swords
    behavior:
      type: block_item
      block: default:ruby_block

Where to Look

You want to…	Go to
Set the item's name, lore, or enchantments	Item Data
Make it a food item	Item Data → food
Give it a simple 2D or handheld model	Item Models → Simplified Models
Make a bow, crossbow, or fishing rod model	Item Models → Simplified Models
Build a complex model definition	Item Models → Model Types
Add tints (dyed armor, grass color, potion…)	Model → Tints
Make it place a block	Block Item
Make it place furniture	Furniture Item
Give it durability (max_damage)	Item Data → max_damage
React to eating, attacking, or clicking	Events
Update existing items after config changes	Item Updater
Keep display data client-side (premium)	Item Data → Client Bound Data