Creating a Custom Item

This page is for advanced users. If you're just getting started, we recommend that you use the in-game GUI to create your item! Just type /cui create <item name> to get started!

Your first item

Let's get started making your first CustomItem!

To make a new CustomItem, create a new .yml file in the items directory of the plugin folder (in plugins/CustomItems/items). This is where we'll be creating the item!

The file's name will be the item's CustomItem ID. For example, purpleSword.yml is the CustomItem with the ID "purpleSword". Remember, these CustomItem IDs have to be unique and can't be the same as Minecraft material ID.

The CustomItem ID is what you use to give the CustomItem to players using the /cui give command, and is also how you reference the CustomItem as an ingredient or something else for other CustomItems (more on that later).

Pssst... You can also add custom recipes and other custom things to native Minecraft items! You can find more info about that below

Note: Any file prefixed with two underscores, like _ _ignore.yml, will be ignored.

Inside the File

Now, let's open up the .yml file you created and get going! For this example, we're gonna be sticking with purpleSword.yml, but you can feel free to change this as little or as much as you want!

First, add the name key. This is the friendly name of the plugin, and is what CustomItems calls it in messages sent to players. Keep in mind that this ISN'T the item's display name — we'll be setting that later. name should almost always just be the CustomItem's ID, just formatted nicely

# This is all inside of purpleSword.yml
name: "Purple Sword"

The next key to add is item! This is where you say what you want your CustomItem to look like. A good rule of thumb is that everything under item will be things you could do with Vanilla Minecraft (like setting the display name, the lore, etc.). Things outside of the item key are special

name: "Purple Sword"
item:
  # ...

Under item, add the following things:

(Side note: the word "string" just means "text" (which is a bunch of characters strung together). So, if something should be a "string", that just means that it should be "text in quotation marks like this" rather than a number or something else)

material

string — REQUIRED
The Minecraft material of the item. A list of materials is available here: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Material.html

displayName

string — REQUIRED
The display name of the item. You can add color codes to this string with &, like "&aThis is green!"

lore

string list — OPTIONAL
A list of strings, each line corresponding to a line of lore on the item. You can add color codes to these strings with & as well, and by default, each line is displayed gray.

enchantments

map — OPTIONAL
The enchantments that should be added to this item. For each enchantment you want to add, provide the enchantment name as a new key under the enchantments key, and set it to the level of the enchantment. This also works for enchantments from other plugins. Check out below to see how this is formatted.

Here's an example of what using these keys might look like

name: "Purple Sword"
item:
  material: DIAMOND_SWORD
  displayName: "&dPurple &7Sword"
  lore:
    - "&fThis is a"
    - "&d&lPurple &7Sword"
  enchantments:
    "minecraft:SHARPNESS": 2
    "minecraft:FIRE_ASPECT": 1

Remember: the item and name keys are the only two keys that are absolutely required in a CustomItem file. Everything else is optional!

For a full list of things you can put in your CustomItem's .yml file, check out the Custom Item Reference. But keep in mind: that page has little to no explanation of what everything does

info

Next, let's add some information about the item, shall we? This is what players will see if they open up the item's information GUI by running /cui info or /cui inspect with the item in their hand. All of these are optional, and you can use & color codes in them!

name: "Purple Sword"
item:
  # ...
  # make sure to indent correctly!
info:
  description: "This is a description of a &dPurple Sword"
  usage: "You use a &dPurple Sword &7just like any other sword"
  obtaining: "It's impossible to get a &dPurple Sword&7."

  # crafting is automatically generated by the plugin.
  # Only set it if you want to override the default GUI information
  # about how to craft the item.
  crafting: "I really shouldn't be setting this to anything, but I'm a rebel"

  # A list of the items that are related to this one.
  # They will all show up as clickable in the item information GUI.
  #
  # You can use either Minecraft items or CustomItem IDs here!
  relatedItems:
    - "minecraft:DIAMOND_SWORD"
    - "minecraft:IRON_SWORD"
    - "myOtherCustomItemID"
    # make sure everything is indented correctly!

recipes

Next, lets add some recipes for our CustomItem! More info will be coming about this later, but for now you can look at the SpigotMC page under "Quick-Start guide to adding Custom Items", and check out the CustomItem recipe reference page

name: "Purple Sword"
item:
  # ...
info:
  # ...
recipe:
  # ...

handlers

Handlers are one of the main features of CustomItems — they let you configure your item to do essentially whatever you want it to do! More info will be coming about this later, but for now you can look at the SpigotMC page under "Quick-Start guide to adding Custom Items", and check out the CustomItem handlers and actions page

name: "Purple Sword"
item:
  # ...
info:
  # ...
recipe:
  # ...
handlers:
  rightClickAir: # when a player right-clicks air with this item
    actions: # run these actions 
      - # make sure you have all of the indenting correct!
        action: teleportPlayer

        world: "world"
        x: 0
        y: 10
        z: 0
        
        method: "add"
        bringToTop: true
      -
        action: # you can put a second action here, if you like
      -
        action: # you can put a third action here, and so on...

  leftClickAir: # When a player hits the air with this item
    actions:
      - # Again, make sure you indent everything correctly
        action: sendMessage
        message: "Hey {player.name}, You hit the air with a &dPurple Sword"
      -
        action: # another action, and so on...