Item For Server Admins

This section is dedicated to server admins. If you are looking for the developers' page, click here

Many of the fields referenced on this page might be or require platform-specific values. Check the glossary

The item module is a specific module that allows serialization and creation of custom items in Minecraft.

Its main focus is to ease and uniform the developers work with server admins configurations, to allow a seamless integration for custom plugins. Developers can use this library to introduce new customized items, and server admins will have all the advantages that this project provides.

Table of contents
Items
Recipes for items

Items

An Item can be created by specifying its values with their Minecraft names. The only one required for the actual creation of the item is material:

item:
  material: "bow"
  amount: 1
  durability: 15
  display-name: "&dCupid&e's bow"
  lore:
    - "&7This bow was used by Cupid during"
    - "&7the Trojan War."
    - " "
    - "&cBe careful with it:"
    - "&4It possesses immense power"
  enchantments:
    - "power:10"
    - "flame:3"
    - "unbreaking:5"
    - "infinity"
    - "mending:3" # Conflicting enchantments can be added
  item-flags:
    - "hide_attributes"
    - "hide_unbreakable"
  unbreakable: true
  custom-model-data: 1337

Here are a few notes for the fields:

• material: this is the type of the item, basically its Minecraft id.

  WARNING: in Minecraft obsolete versions like 1.8.8, not all items were identified by their name. For example, dyes were identified by the dye material and the durability set to a certain value based on the color.

  item:
    material: "dye"
    durability: 4
    display-name: "&9Custom Lapis Lazuli"

• display-name and lore: on versions higher than Minecraft 1.16, HEX colors can be used;

• enchantments: these can be specified using the format described in the relative wrappers section;

Item recipes

By default, every item supports multiple recipes to be added. However, it is up to the developer to register them: if they explicitly stated that the recipes should be ignored, adding or modifying the recipes section will not cause errors, but rather, the whole configuration will be discarded.

An item can have multiple recipes, which are identified by some common values:

• type: the type of the recipe (see below for all the available types);
• id: a unique identifier (name) for the recipe that has to be unique across the whole server.

item:
  material: "diamond_sword"
  display-name: "&e&lSuper Sword"
  recipes:
    - id: "super-sword-shaped-recipe"
      type: "SHAPED"
      # ...
    - id: "super-sword-shapeless-recipe"
      type: "SHAPELESS"
      # ...
    - id: "super-sword-furnace-recipe"
      type: "FURNACE"
      # ...

Shaped recipe

The SHAPED type recipe allows creating a recipe that requires an order for which the ingredients are put in. If the ingredients are not put in the correct order, the item will not be crafted. The available fields are:

• shape: the shape of the recipe in the crafting table. It can be specified in the format <rows>x<columns> where the values cannot be lower than 1 and higher than 3;
• ingredients: a list of valid items specified in sections. The name of the sections should be a numerical index that counts from 0, and it will impact the order in which they are put. They should also not exceed the product between rows and columns specified in the shape field. So, for example, specifying three items in a 3x1 shape, will put the first ingredient on top, the second in the middle and the third on the bottom.

item:
  material: "diamond_sword"
  custom-model-data: 7
  display-name: "Gem Sword"
  recipes:
    - id: "gem-sword-shaped-recipe"
      type: "SHAPED"
      shape: "3x1"
      ingredients:
        '0':
          material: "redstone"
          custom-model-data: 7
          display-name: "Gem"
        '1':
          material: "redstone"
          custom-model-data: 7
          display-name: "Gem"
        '2':
          material: "stick"

Shapeless recipe

The SHAPELESS type recipe defines a recipe that does not require an order for the ingredients. They can be put in any position in the crafting table, and the result will always be the same. The available fields are:

• ingredients: a list of valid items specified in sections. The name of the sections should be a numerical index that counts from 0.

item:
  material: "redstone"
  custom-model-data: 7
  display-name: "Gem"
  recipes:
    - id: "gem-block-shapeless-recipe"
      type: "SHAPELESS"
      ingredients:
        '0':
          material: "redstone_block"
          custom-model-data: 7
          display-name: "Gem Block"

Furnace recipe

The FURNACE type recipe allows setting the current item as the result of smelting in the furnace. The available fields are:

• ingredient: the item that should be smelted. Has to be a valid item;
• experience: the resulting experience of the smelting;
• cooking-time: how many seconds the smelting should take;

item:
  material: "redstone"
  custom-model-data: 7
  display-name: "Gem"
  recipes:
    - id: "gem-ore-furnace-recipe"
      type: "FURNACE"
      experience: 50.0
      cooking-time: 5.0
      ingredient:
        material: "redstone_ore"
        custom-model-data: 7
        display-name: "Gem Ore"