Creating Items - RockinChaos/ItemJoin GitHub Wiki

If you feel like something is missing and needs to be added or clarified please send me a message on spigot or join our discord server and I will add it.​

Index:

• Creating an Item
• Defining an Items Slot
• Defining an Items Enabled Worlds
• Defining an Items ItemFlags
• Defining an Items Triggers
• Defining an Items Attributes
• Defining Gamemode Limitations
• Defining an Items Enchants
• Establishing ItemPermissions (Required!)
• Establishing ItemCommands
• Creating Toggle Commands
• Custom Placeholders
• Creating a Custom Book
• Creating a Custom Firework
• Creating a Custom Map (Images)
• Adding a Map ID
• Creating a Custom Skull (Player Heads)
• Creating a Custom Skull (Skull Textures)
• Creating a Custom Arrow
• Creating a Custom Potion
• Creating a Custom Firework Charge
• Creating a Custom Golden Apple (Effects)
• Creating a Custom Food (Effects)
• Creating a Custom Banner (Patterns)
• Creating Custom Dyed Armor
• Creating a Teleport Arrow
• Dynamic Item Explanation
• Animated Item Explanation
• Setting up Mob Drops
• Setting up Block Drops
• Setting up Custom Recipes
• ShulkerBox Nesting
• Setting up NBTProperties
• Setting up Conditions

An Item is fairly simple to create, to create an item you must first list the world identifier. This is the name of the world that you want to receive these items in. The next identifier you must add is the item's identifier, to signify the creation of the items. Now you can simply list the name of the items you wish to create.

The items must have an ID to receive the item while in-game. You can also list the enabled-worlds and add a slot you want each item in, or if you don't list the enabled worlds it will be given to all worlds by default. If you do not list a slot it will be given in the first available slot by default. All of the features are optional and simply for greater configuration. Shown below is an example of creating three items.

Please Note: Item-ID's (data-values) will continue to function on Minecraft v1.13 and above, however, they are longer be supported in versions above this as Item-ID's do not exist in Minecraft v1.13+. It is recommended to move away from the use of Item-ID's as soon as possible.

Also, Material (ID)'s are able to be animated (change material types upon a given interval) see the Animation Section at the bottom of this page.

The diamond-item listed below is entirely valid, this will give the item in all worlds the player joins, and will be given in the first available slot.

Here is an example of some items:

items:
  any-text:
    id: 284
    slot: 0
    enabled-worlds: world_name_here, another_world_name
  another-item:
    id: SEEDS
    slot: 2
  wheat-item:
    id: WHEAT
    slot: 4
    enabled-worlds: world, world_nether, world_the_end
  diamond-item:
    id: DIAMOND

Now I as I said you can add more options to your items to make them so much more custom. You can set a custom name, add lines of lore, enchantments, define custom permission nodes to receive the items, as well as the count/amount of each item you get.

Pretty much every definable option that can be displayed to the player about the item will take a color-code input such as &6 for a GOLD colored text. However something to note, as of Minecraft 1.16+ there is now support for hex-colors in any visible text. This can be done by adding &# before the hex-color string. An example string; &#184d47I am a hex color!.

There is also an option to use the data-value of an item, this is useful to get items such as wool. If you are wanting to include the data-value to the item which is specific to certain items such as coloring wool, you will want to include this in the id of the item. The id and data-value should be included in either quotations or apostrophes because this is a limitation of YAML files. It should look like such '160:15' or "160:15". The id of the item supports numerical as well as a string version along with the data-value so it can also look like this; 'STAINED_GLASS_PANE:15'.

We also have durability, you set this to the amount of durability you want the item to have taken, such as if the item has 32 durability and you set the durability to 5 it will have 27 durability when you receive the item.

Along with durability, one can define the durability data for custom textures. This can be done simply by defining data: 12 for example where 12 is the damage you wish the item to take. If the max damage value is 150, and you set the custom texture to be applied for the damage value at 140 you would put 10 as your data for the item.

In (1.14+) there is now official Custom Model Data support so each item has its own individual texture regardless of durability taken. This can be done by adding model-data: 10001 to the item for example. Do note, this is the numerical value you assigned in the .json file.

If the item is a consumable item or a type of interactable such as an eye of ender, you can put an item use-cooldown on it. In the example, the player has to wait 10 seconds each time they want to use an eye of ender. This prevents any and all special uses of the specified item while the item is on cooldown, this option is not limited to any certain items.

Example:

items:
  special-item:
    id: 381
    slot: 0
    use-cooldown: 10
    enabled-worlds: world_name_here

Lastly, you can also define certain items with a probability to be put into a lottery, then the item that won will be given to the player. Items that do not have probabilities defined will be automatically given to the player and If the item has a probability, only one of those items can be given. Items probability are based on weight rather than a percentage, so you can use any number as long as it is a positive integer. If you define any item(s) without a probability, the item(s) will be given along with the item that wins the probability roll. This also works for adding additional slots, so if the item that was chosen has multiple slots those multiple slots will be given if its a multi-slot item.

Example of random items to be given (as shown in the example image);

items:
  sword-of-a-god:
    id: DIAMOND_SWORD
    slot: 0
    name: '&eYou have been chosen..'
    probability: 15
    triggers: join, world-switch
    enabled-worlds: world, world_nether, world_the_end
  herobrine-apple:
    id: GOLDEN_APPLE
    slot: 0
    name: '&cHerobrine Apple'
    probability: 55
    enabled-worlds: world, world_nether, world_the_end
  filler-pane-item-four:
    id: DIAMOND_PICKAXE
    slot: 0
    name: '&fUseless Pickaxe'
    probability: 110
    triggers: join, world-switch
    enabled-worlds: world, world_nether, world_the_end

As said all options are optional and can be removed if you do not want to use them in your item, you just must have the defining characteristics of an item, ID and Slot.

Here is a list of all available options;

items:
  ultra-item:
    id: DIAMOND_SWORD
    slot: 0
    name: '&bBlazefury'
    count: 1
    durability: 5
    lore:
      - '&7A god sword..'
      - '&7This is generations old!'
    interact:
      - 'message: &eYou can send yourself custom messages!'
      - 'console: say You can even execute more than one command!'
      - 'player: say This is item slot 1'
      - 'say Hello world!'
    interact-right:
      - 'console: gamemode 1 %player%'
      - 'message: &eYou have been set to creative mode.'
    interact-left:
      - 'console: gamemode 3 %player%'
      - 'message: &eYou have been set to spectator mode.'
    interact-air:
      - 'message: &eThis will prevent commands from being executed when you click on blocks such as a sign.'
    interact-air-right:
      - 'message: &eThis will prevent commands from being executed when you click on blocks such as a sign.'
    interact-air-left:
      - 'message: &eThis will prevent commands from being executed when you click on blocks such as a sign.'
    inventory:
      - 'console: gamemode 2 %player%'
      - 'message: &eYou have been set to adventure mode.'
    enchantment: FIRE_ASPECT:3, DAMAGE_ALL:5, DAMAGE_UNDEAD:5, KNOCKBACK:8
    commands-sequence: SEQUENTIAL
    commands-sound: BLOCK_NOTE_PLING
    commands-particle: FIREWORK:BLACK:RED:BURST:3
    commands-warmup: 5
    commands-cost: 25
    commands-cooldown: 5
    cooldown-message: '&7[&eItemJoin&7] &a[%item%&a] &cis on cooldown for &a%timeleft% &cseconds..'
    probability: 25
    use-cooldown: 10
    itemflags: inventory-modify, death-drops, unbreakable, disposable, count-lock, cancel-events, placement, hide-durability, hide-attributes, self-drops, first-join, CreativeBypass, AllowOpBypass
    triggers: join, respawn, world-switch
    permission-node: 'itemjoin.ultra'
    enabled-regions: region1, region2
    enabled-worlds: world, world_nether, world_the_end

Note: You can define extra parameters to commands-sound: for further customization. It is possible to add volume and pitch, which would look like that in your config: commands-sound: 'BLOCK_NOTE_PLING:10:1'. The first value stands for the volume, while the second one stands for the pitch. You can use decimals like 0.75 too, but make sure that you add the two '' in the example one line above when working with special characters or else you risk your configuration breaking.

The slot system consists of 35 Numerical slots and 6 Custom Name slots, and 5 Custom Crafting Name Slots, 0 to 8 are the first 9 slots in your hot bar. Normally when you count you would not start with zero then count up from there, you would start with one. CraftBukkit / Spigot does not do this, they start out with zero first. So the first slot in your hot bar would really be slot zero.

As for the physical inventory, the slot numbers start at the top left and increase to the right, as shown in the image below. Those slots are 9 to 35.

To set an item in your armor slots you would simply type the name of the slot you would want it to be in. Helmet, Chestplate, Leggings, or Boots, If you want an item in your offhand you would do the same for this. Just put the slot as Offhand.

To set an item in your crafting slots you would simply have to type CRAFTING then the number of the slot as [#]. See the chart below for the exact slot numbers for crafting. You can define a crafting slot as either CRAFTING[#], C[#], or C(#). The # is the input 0, 1, 2, 3, or 4 for the slot number.

You can also set a slot as a placeholder from PlaceholderAPI, usually used in the instance of hooking into another plugin that uses PlaceholderAPI to create its own placeholders.

Placeholder example;

  placeholder-item:
    id: EMERALD
    slot: %player_health%

Example of crafting slot items;

  diamond-item:
    id: DIAMOND
    slot: CRAFTING[1]
    itemflags: death-drops, self-drops
    triggers: join
    enabled-worlds: world, world_nether, world_the_end
  iron-item:
    id: IRON_INGOT
    slot: CRAFTING[2]
    itemflags: death-drops, self-drops
    triggers: join
    enabled-worlds: world, world_nether, world_the_end
  gold-item:
    id: GOLD_INGOT
    slot: CRAFTING[3]
    itemflags: death-drops, self-drops
    triggers: join
    enabled-worlds: world, world_nether, world_the_end
  redstone-item:
    id: REDSTONE
    slot: CRAFTING[4]
    itemflags: death-drops, self-drops
    triggers: join
    enabled-worlds: world, world_nether, world_the_end

There is also a slot option called Arbitrary, If an item is set to this, the item will be put in the FIRST available slot in the player's inventory, it will not remove any of the player's items in their inventory to place itself in that spot.

You can also set multiple slots per item, just separate the slots by commas such as 1, 12, 13, Arbitrary, 3.

Here is an example of the slots being used for various items;

items:
 first-item:
   d: SKULL_ITEM
   slot: 0 #// This can be any number between 0 and 35, depending on the location you want it in the players inventory.
 second-item:
   id: DIAMOND_SWORD
   slot: Arbitrary
 helmet-item:
   id: DIAMOND_HELMET
   slot: Helmet
 chestplate-item:
   id: 299
   slot: Chestplate
 leggings-item:
   id: DIAMOND_LEGGINGS
   slot: Leggings
 boots-item:
   id: LEATHER_BOOTS
   slot: Boots
 offhand-item:
   id: SHIELD
   slot: Offhand
  redstone-item:
    id: REDSTONE
    slot: CRAFTING[4]
    itemflags: death-drops, self-drops
    triggers: join
    enabled-worlds: world, world_nether, world_the_end

This is fairly simple to up set up, just add the enabled-worlds identifier to the item and define the world or world(s) separated by commas that you want to receive the item(s). If you do not want any restrictions between worlds simply do not define any enabled worlds for the item(s).

Here is an example;

items:
  any-text:
    id: 284
    slot: 0
    enabled-worlds: world_name_here, another_world_name
  wheat-item:
    id: WHEAT
    slot: 4
    enabled-worlds: world, world_nether, world_the_end

If you want to get the item in every world, simply add either All or Global to the enabled-worlds identifier, then the items will be given in every world.

Here is an example of global items;

items:
  any-text:
    id: 284
    slot: 0
    enabled-worlds: Global
  wheat-item:
    id: WHEAT
    slot: 4
    enabled-worlds: All

However, what if you actually need a way to disable items in certain worlds, because for example you have a plugin that lets your players claim their own worlds? Well, ItemJoin got you covered. disabled-worlds will disable ItemJoin items in all worlds that are defined.

Here is an example;

items:
  any-text:
    id: 284
    slot: 0
    disabled-worlds: world_name_here, another_world_name
  wheat-item:
    id: WHEAT
    slot: 4
    disabled-worlds: world, world_nether, world_the_end

Itemflags allow HUGE modifications to the items. All you have to do to add itemflags to an item is adding the itemflags identifier to the item as shown below.

These are custom itemflags, all itemflags with description are listed below, Itemflags are always being updated and added onto so check back here for updates!

• vanilla - Allows the giving of default unmodified no-name items. Please note if you choose to use commands or itemflags, etc. They will not function since all this does is allow ItemJoin to give a vanilla type item that can have a modified name or lore if defined.
• vanilla-status - Applying this itemflag to an item will allow any item with the vanilla itemflag retain its functionality to ItemJoin without applying any NBTTags to the item. This is useful for trying to implement items being used by other plugins so they can retain their functionality while also (not being given on every join).
• vanilla-control - Allows the item to be given as a vanilla item although, commands, itemflags, and other ItemJoin features will still continue to function. There will be no DataTags or ItemJoin item identifiers on the item, so the item can be given by another plugin (created by another plugin and given) and ItemJoin will still see it as an ItemJoin item. The downside is that if players have access to color codes and lore modification plugins they can rename a regular item to an ItemJoin item and it will function as such. Use with caution.
• ip-limit - This will only give the item after checking the IP of a player, so if someone has already joined and then joins with an alt the alt will not get the item, preventing players from loading up on free items. This will limit the item to the player's IP address.
• unbreakable - Set the item as INDESTRUCTIBLE!
• hide-attributes - only hides attribute tags such as armor points and attack speed.
• hide-flags - Hides ALL ALTERNATE attributes, such as firework color, damage the item does, and enchantments. (Hides everything from lore except the custom lore and the armor/attack speed).
• hide-enchants - Hides the list of enchantments from the item's lore.
• hide-durability - Hides the durability bar from the item by setting the item as Unbreakable.
• glowing - Gives the item the "enchanted" glowing effect.
• stackable - Allows items that are not stackable to be stacked up to x64. This is done automatically on pickup, click-drag, and shift+click.
• selectable - Any item with this itemflag will not be allowed to be selected. If the item is selected the player has about a half-second to move past the item or it will automatically jump to the next available item in the direction the player was originally scrolling.
• no-hat - Prevents the ItemJoin item from being used as a helmet via Essential's /hat command.
• placement - Prevents this item from being placed if it is a BLOCK, or if the item is being placed in an item-frame.
• inventory-modify - Prevents this item from being moved, placed in an item frame, or switched to offhand in the player's inventory.
• dynamic - This will allow the item to dynamically update every 100 ticks by default, changing any previous placeholder values to the now up-to-date values. See how to set up dynamic items below.
• animate - This will allow the item to animate between the different name and lore iterations every 100 ticks by default, you can make the name of the item and/or the lore to anything you could want, between a different name entirely or just changing the color codes to create a cool effect. See how to set up animated items below.
• item-store - Prevents the storage of the item in a trapped chest, chest, enderchest, hopper, anvil, crafting table, shulker box, furnace, item frame, minecart with chest, droppers, dispensers, item-stands, brewing-stands, llama chests, and donkey chests.
• cancel-events - Prevents the player from opening a chest while this item is in hand or any open-able items. Useful for canceling the event of opening a book to set custom book items.
• cancel-equip - Prevents the Player from moving/placing the custom item into armor slots. This allows the item to move freely excluding armor slots.
• count-lock - Prevents the player from using all of the items. If the item is set to count: 32 then each time the player places the block item the stack will be refreshed back to 32. This also works for bows, crossbows, arrows, and other consumable items.
• death-drops - Clears this item if it is dropped on the ground when the player dies. This itemflag will respect the /gamerule keepInventory value, so if it's set to true then the death-drops itemflag will be disabled.
• self-drops - Prevents the player from dropping this item, either clicking it out of inventory or using the drop key, usually (q).
• disposable - If a command is run from the item it will remove x1 of the item from the player's inventory.
• inventory-close - If an inventory is open while the player interacts with the item, it will close this inventory.
• item-repairable - This will block the usage of the specified ItemJoin item in an anvil repair recipe. If this itemflag is also used on a consumable recipe item such as a diamond the itemflag will still prevent the repair of an item.
• item-craftable - This will block the usage of the specified ItemJoin item in a crafting recipe via the crafting table or the player's own personal crafting menu. If an item using this itemflag is placed in either of those following locations the item will be automatically moved back to the first available slot of the player's inventory.
• item-modifiable - This will prevent the specified item from being modified via an ANVIL, ENCHANTING or a GRINDSTONE.
• always-give - This will always give the specified ItemJoin item when a player acts upon one of the defined triggers such as on join. This itemflag also has multiple functions, allowing the hasItem restriction bypass on the regular /itemjoin get <item> and /itemjoin get <item> <player> with no amount being specified.
• auto-remove - Upon performing one of the defined triggers for the item, if the custom item is found in the player's inventory and is in a world which is not defined under the enabled-worlds it will be automatically removed. This best works with the world-switch trigger that way when players switch to a world that is not enabled for the item, it will simply be removed.
• give-next - This will function similar to the Arbitrary slot idea, any item with a dedicated number slot from 0 to 35 with this itemflag will function as normal if the dedicated slot is empty. However, if it is full, it will give the item in the next available slot AFTER the preceding dedicated slot. The Arbitrary would simply give the item to the first available slot rather than the slot after the dedicated slot.
• move-next - If an item with this flag is set to be given, and the slot where the item should be set in is already full, it will move the old item to another slot to make room for the custom item.
• drop-full - This simply gives the item the ability to drop itself onto the ground when attempting to give the item to the player. The item will drop if the player's inventory is full. This functionality works with any slot type including custom and arbitrary slots.
• death-keep - Retains the custom item on-death so it will exist in the player's inventory upon respawn. Note: This will add the respawn trigger to your item.
• teleport - Teleport Arrows, adding this itemflag will make it so the player is teleported to the arrows' landing location when fired by a BOW or CROSSBOW.
• allow-modifications - Allows the item to still function as a normal ItemJoin item if the ENCHANTMENTS, BOOK PAGES, NAME, LORE, and item COUNT are modified by the player or a plugin.
• overwrite - This will perform exactly the same as the items-Overwrite boolean in the items.yml except it is item-specific. Applying this itemflag to the item will allow it to overwrite any other items in its designated slot. This itemflag will take priority over the items-Overwrite boolean.
• AllowOpBypass - This would allow the user IF THEIR OP to bypass most of these itemflags. It will work on ALL non-item modifying flags. This would NOT work on unbreakable, hide-attributes, stuff like that.
• CreativeBypass - This would allow the user IF THEY'RE IN CREATIVE MODE to bypass most of these itemflags. It will work on ALL non-item modifying flags. This would NOT work on unbreakable, hide-attributes, stuff like that.

Here is an example of an item with all itemflags;

items:
  ultra-item:
    id: DIAMOND_SWORD
    slot: 0
    itemflags: first-join, unbreakable, hide-attributes, hide-durability, placement, inventory-modify, cancel-events, count-lock, death-drops, self-drops, disposable, AllowOpBypass, CreativeBypass
    enabled-worlds: world

Triggers allow you to receive the items under certain conditions. All you have to do to add a trigger to an item is to add the triggers identifier to the item as shown below. If a trigger is not defined, the item will be given upon joining the server by default.

These are custom triggers, all triggers with description are listed below.

• join - This will give the item when the player logs into the server.
• first-join - This will only give the item when joining the server for the first time, to get the item every time you join just remove this itemflag. If you want to give the item once per-world entrance, use the first-world trigger. Note: This is the exact same as the first-join itemflag, however, this will automatically apply the join trigger. If you want any other triggers you will need to manually add them.
• first-world - This will only give the specified item once per world for each player. Note: This is the exact same as the first-join itemflag, however, this will automatically apply the join and world-switch trigger. If you want any other triggers you will need to manually add them.
• first-life - This will only give the specified item once upon joining the server, however upon respawning the item will always be given--for each player.
• respawn - This item will be given on respawn if a player dies.
• world-switch - This item will be given when the player switches worlds. When you enter the world this item is allowed in it will be given.
• gamemode-switch - This works well with the limit-modes identifier, however, it will work without it. If the player switches to a gamemode that is not defined in the limit-mode this trigger will remove the item from the player's inventory. If the player is missing an item that is defined by the limit-modes it will be given if they are switching to the correct gamemode.
• region-enter - This will give the item upon entering a region and will NOT remove this when exiting, you must have WorldGuard set to true and have enabled-regions listed for the item.
• region-access - This will give the item upon entering a region and WILL remove it upon exiting, you must have WorldGuard set to true and have enabled-regions listed for the item.
• region-leave - This will give the item upon leaving an enabled-region, you must have WorldGuard set to true and have enabled-regions listed for the item.
• region-egress - This will remove the item upon entering a region and WILL add it back upon exiting, you must have WorldGuard set to true and have enabled-regions listed for the item.
• teleport - This will give the item whenever a player teleports from one location to another.
• disabled - This will prevent the item from being given on join, respawn, world-switch, and region-enter. This is helpful if you only wish to get the item using /itemjoin get .

Here is an example of an item with all triggers;

items:
  ultra-item:
    id: DIAMOND_SWORD
    slot: 0
    triggers: join, respawn, world-switch, region-enter, gamemode-switch
    enabled-regions: region1
    enabled-worlds: world
  second-item:
    id: PAPER
    slot: 1
    triggers: disabled, region-leave
    enabled-regions: region2
    enabled-worlds: world

Gamemode-Switch example;

  arrow-item-example:
    id: ARROW
    slot: 0
    name: '&fArrow'
    limit-modes: CREATIVE
    triggers: JOIN, GAMEMODE-SWITCH
    enabled-worlds: world, world_nether, world_the_end

• You can now define any available attributes on an item that accepts attributes such as a Diamond Sword.
• This is set up by defining attributes followed by {ATTRIBUTE:VALUE}, you can define multiple attributes separated by a comma.
• Example usage; attributes: '{GENERIC_ATTACK_DAMAGE:15.2}, {GENERIC_ATTACK_SPEED:19.0}'
• These attributes work on Minecraft versions as early as 1.8 to the latest 1.16.2. They do change names so it's best to use the /itemjoin menu for this.
• For current 1.16.2 attributes see; Spigot Link.
• Legacy JavaDocs can be found here; CG Link.

Setting up an item to be limited to a specific gamemode is fairly easy, any item that is defined under limit-modes will be allowed to have the specified item. If a limit-mode is set to a specific item, the player will only be given the items if they are in the defined gamemode upon an action defined by the triggers. If you wish to actively give and remove the item based on a player gamemode rather than upon join/world-switch/respawn/region you can add the Gamemode-Switch TRIGGER which will active make sure you have the correct items for your defined limit-modes.

Simply ass the limit-modes identifier as shown; An example item that you can only get in SURVIVAL and ADVENTURE mode;

  arrow-item-example1:
    id: ARROW
    slot: 0
    name: '&fArrow'
    count: 32
    limit-modes: SURVIVAL, ADVENTURE
    triggers: join, respawn, world-switch
    enabled-worlds: world, world_nether, world_the_end

ItemJoin allows you to add Minecraft enchantments to your custom item. For this you need to add the enchantments: identifier and an enchantment level as shown in the example below:

  enchanted-item:
    id: DIAMOND_SWORD
    slot: 0
    triggers: JOIN
    enchantments: PROTECTION_ENVIRONMENTAL:3

The number with the collon defines the level of the enchantment. Without this, the enchantment level will default to 1. Of course, you can add multiple enchantments to your item by seperating each new enchant with a comma. A full list of valid names can be found here. Note: If you are using Minecraft 1.8 or below and these do not work for you, you may need to use the values found here in the collumn named "Field".

These are the permission(s) required for players who are not a server administrator to receive the item(s). Please note; permissions are case sensitive, including the world names! Sometimes certain permissions plugins fix this but in reality, it depends on the permissions plugin you use.

itemjoin.Your_Specified_World_Name_Here.Item_Name:
description: Gives permission to get a specific item in a specific world. Replace Item_Name with the name of the specified item (in the items.yml) and Your_Specified_World_Name_Here with the name of the world to receive that item.
default: false

itemjoin.Your_Specified_World_Name_Here.*:
description: Gives permission to get all items from the specified world. Replace Your_Specified_World_Name_Here with the name of the world to receive that item.
default: false

(I recommend itemjoin.Your_Specified_World_Name_Here.* as it would be easier unless you are trying to create permission group specific items)

Remember to replace Your_Specified_World_Name_Here with your world's name. If you need to see what world you want the items in, simply stand in the world and type /itemjoin world this will tell you the world name you are in that you want to put in the permission node.

The other option is to add a permission node for each specific item you have created. You can use these interchangeably such as adding a custom permission node to one item and using the default permission nodes listed above for items without a dedicated permission node.

Simply add the following to your item and replace specialty with your desired text. You can change the permission node to whatever you want such as 'example.fish'. I simply chose to use ItemJoin as the beginning word of the custom permission node. Make sure to add the custom permissions you create to a permissions plugin afterward.

You can use all these item permissions interchangeably such as adding a custom permission node to one item and using the default permission nodes for items without a dedicated permission node.

Add this to your item;

    permission-node: 'itemjoin.specialty'

Here is an example of an item utilizing the custom permission node utility;

items:
  example-item:
    id: DIAMOND_SWORD
    slot: 0
    permission-node: 'itemjoin.specialty'

First off, we have to start by setting up the command actions. These will be the actions the player has to do to activate the commands.

• Interact - Actions performed with the player's inventory closed, usually with the item in their hand.
• Inventory - Actions performed with the player's inventory open, usually clicking the item with their cursor.

These are the different types of commands actions:

• interact - Executes the commands when the player is left or right clicking a block or the air with the item in their hand.
• interact-air - Executes the commands when the player is left or right clicking the air with the item in their hand.
• interact-block - Executes the commands when the player is left or right clicking a block with the item in their hand.
• interact-left - Executes the commands when the player is left clicking a block or the air with the item in their hand.
• interact-air-left - Executes the commands when the player is left clicking the air with the item in their hand.
• interact-block-left - Executes the commands when the player is left clicking a block with the item in their hand.
• interact-right - Executes the commands when the player is right clicking a block or the air with the item in their hand.
• interact-air-right - Executes the commands when the player is right clicking the air with the item in their hand.
• interact-block-right - Executes the commands when the player is right clicking a block with the item in their hand.
• inventory - Executes the command when the player is middle-mouse, left, right, shift-left, shift-right clicking the item in their inventory.
• inventory-middle - Executes the command when the player is middle-mouse clicking the item in their inventory. NOTE: No longer supported in Minecraft versions 1.21+ (blame Microsoft).
• inventory-creative - Executes the command when the player is in creative mode and clicks the item in their inventory, any click action will trigger this event.
• inventory-left - Executes the command when the player is left clicking the item in their inventory.
• inventory-right - Executes the command when the player is right clicking the item in their inventory.
• inventory-shift-left - Executes the command when the player is shift-left clicking the item in their inventory.
• inventory-shift-right - Executes the command when the player is shift-right clicking the item in their inventory.
• inventory-swap-cursor - Executes the command when the player is swapping the item on their cursor with the item in their inventory.
• on-damage - Executes the command when the player has the custom item in their inventory if the player damages an entity or the entity damages the player the command will be executed.
• on-hit - Executes the command when the player is holding the custom item and hits an entity or another player. This also supports projectiles such as ENDER_PEARL, EGG, FISHING_ROD.
• on-fire - Executes the command when the player fires an arrow from the bow/cross-bow item. In 1.16+ you can add this to an arrow that if fired from a bow item will execute a command as well.
• on-consume - Executes the command when the player is able to "eat" / "consume" / or "use" the item aka consumed.
• on-receive - Executes the commands when the player receives the item for every x second(s) for every x number of times.
  • Every x second(s) is defined by setting the wait value as the commands-cooldown.
  • The every x number of times is defined by adding commands-receive to the item and setting a numerical value.
• on-hold - Executes the commands every x second(s) while the player is holding the item.
  • Every x second(s) is defined by setting the wait value as the commands-cooldown.
• on-equip - Executes the commands when equipping the item into an armor slot.
• un-equip - Executes the commands when unequipping the item from an armor slot.
• on-death - Executes the command when the player holding the item in their inventory dies.
• physical - Executes the command if a player steps on a pressure plate, hits a mob, opens a chest, or any other physical actions with that item in the player's hand.

You can set it up as such to use all of the commands triggers or you can remove the ones you don't want to use. See the example below for how the triggers should be set up.

As for the commands cooldowns, it is as simple as it gets! It sets the time in seconds that the items command will be on cooldown. If the commands are on cooldown then it will send a cooldown message, sends the player the cooldown message when the item is on cooldown.

You can also set a warmup delay to execute the command by adding commands-warmup to the item, this is the delay in seconds it will take before the command is executed. Certain interactions or swapping items will cancel this action.

Commands can be defined with a commands-cost that will be charged from your Vault statistics. The other option is to define a commands-item which is the name of the material that will be removed when trying to execute the command. The number of them to be removed can be defined by the commands-cost and the commands will not execute if the player does not have the required number of items. Not defining a commands-cost will only remove one of the commands-item from the players inventory. An example is to have the player charged 3 emeralds to use a command by setting the following; commands-cost: 3 commands-item: EMERALD

You are able to setup commands-particle for the item as well. There are two formats for this, the main one is commands-particle: PARTICLE:LIFETIME where the particle is the name of the particle and the lifetime is the time in seconds which the effect is alive for. The second way is custom particles and you can request your own to be added, currently there is only one which is a firework; commands-particle: PROJECTILETYPE:STARTCOLOR:ENDCOLOR:PATTERN:LIFETIME Example; commands-particle: FIREWORK:BLACK:RED:BURST:3

There are also commands-sequence identifiers SEQUENTIAL - Executes the commands in order. REMAIN - Item will be required to exist in the player inventory for DELAYED commands to be executed. If the item is removed from the player inventory before the commands finish executing the remaining commands will fail to execute. RANDOM - Executes ALL of the commands in random order. RANDOM_SINGLE - Executes a single command that is randomly chosen. RANDOM_LIST - Executes a random list of commands, remember multi-list commands will only be executed if this is defined as your command-sequence.

In this example of RANDOM_LIST, there are two commands lists defined for the interact-right action. Since there are only two lists it has a 50% chance to be a winner or 50% chance to be a loser.

    interact-right:
        winner:
        - 'message: &aYou have won the dice role!'
        - 'console: give %player% diamond 64'
        loser:
        - 'message: &cYou have lost the dice role..'
        - 'console: kill %player%'

Note; you do not have to add commands-sequence if no sequence is defined they will simply just execute sequentially.

Example of an item with RANDOM commands (as shown in the example image);

random-item:
    id: EMERALD
    slot: 0
    name: '&aRandomizer'
    interact:
      - 'message: &eCOMMAND 1'
      - 'message: &eCOMMAND 2'
      - 'message: &eCOMMAND 3'
      - 'message: &eCOMMAND 4'
      - 'message: &eCOMMAND 5'
    commands-sound: BLOCK_NOTE_PLING
    commands-sequence: RANDOM_SINGLE
    commands-cooldown: 5
    cooldown-message: '&7[&eItemJoin&7] &a[%item%&a] &cis on cooldown for &a%timeleft% &cseconds..'
    triggers: join, respawn, world-switch, region-enter
    permission-node: 'itemjoin.ultra'
    enabled-worlds: world, world_nether, world_the_end

Finally, we have command instances. Commands can be executed by 4 instances; console, player, server, serverswitch, and message. If no instance is specified in the commands string, then by default it will be executed by the player. If you still do not understand what each does;

• console, executes the set command by the console.
• op, executes the command as if the player executed it themselves, but ignoring all the permissions (as if they were Oped.
• player, executes the command as if the player executed it as themselves.
• server, sends the player to that directed server name. (Intended for use on switching server that is using BungeeCord).
• bungee, executes a BungeeCord command, it is required for you to have the CloudSync plugin in order to execute these commands. This plugin acts as a bridge to pass through the commands to the Bungee server. You will not be able to execute any commands from Bungee plugins without this plugin!
• delay, executes the commands after this identifier, delayed by the specified amount of ticks.
• message, sends the player a custom message of your choosing.
• swap-item, changes the item in the player's hand to another existing ItemJoin item. This will replace the existing item in their hand to another custom item, however, it will ignore the defined slot and place it in the exact slot the previous item existed in.

Along with these command instances come a few optional command identifiers that can perform some interesting actions. Closing a player's inventory - You can specify [close] for all player, console, op, and default commands to close the player's inventory once the command is executed. This specifically closes the executing player's inventory, so despite it being executed by the console, it will close the player's inventory since obviously, the console does not have an inventory. Example, 'player: [close]'

Here is an example of an item with a command;

items:
  ultra-item:
    id: DIAMOND_SWORD
    slot: 0
    interact:
      - 'message: &eYou can send yourself custom messages!'
      - 'console: say You can even execute more than one command!'
      - 'player: say I am executed by player'
      - 'op: say I am executed by player but I have all the permissions!'
      - 'delay: 100'
      - 'server: survival'
      - 'say I am executed by player since I dont have a executor...'
      - 'swap-item: ultra-item'
    interact-right:
      - 'console: gamemode 1 %player%'
      - 'message: &eYou have been set to creative mode.'
    interact-left:
      - 'console: gamemode 3 %player%'
      - 'message: &eYou have been set to spectator mode.'
    inventory:
      - 'console: gamemode 2 %player%'
      - 'message: &eYou have been set to adventure mode.'
    commands-sequence: SEQUENTIAL
    commands-sound: BLOCK_NOTE_PLING
    commands-particle: HEART:3
    commands-warmup: 5
    commands-cost: 25
    commands-cooldown: 5
    cooldown-message: '&7[&eItemJoin&7] &a[%item%&a] &cis on cooldown for &a%timeleft% &cseconds..'
    enabled-worlds: world

You can allow players to execute one of a list of command(s) to enable and disable a specific custom item for themselves. The command action toggle: must be defined followed by a command or list of commands.

You can also specify a toggle-permission so only certain players can toggle on/off the command, this does not apply to OP players. This can be anything, such as fish.toggle, in the example I simply use itemjoin.compass.toggle.

You can also specify a custom toggle-message that is sent to the player when they execute the toggle command.

In this example, if the user has itemjoin.compass.toggle and executes either the compass or toggle compass command then the item will be removed from their inventory and disabled. If they execute one of those two commands again it will be re-enabled and given to the player;

items:
  toggle-item:
    id: COMPASS
    toggle:
      - 'compass'
      - 'toggle compass'
    toggle-permission: 'itemjoin.compass.toggle'
    toggle-message: '&7You have toggled your navigation compass!'
    enabled-worlds: world

These placeholders can be used in anything to do with ItemJoin, whether it is an item name/lore/command/etc. These are independent and added by ItemJoin if you wish to have additional placeholders you will need to install PlaceholderAPI and download desired Expansions with the command /papi ecloud download <ExpansionName>.

These placeholders I have added I call internal placeholders as they are only accessible by ItemJoin;

• %player% - Displays the player's current display name.
• %argsplayer% - Displays the other player's current display name for specific lang.yml messages.
• %argsplayer_world% - Displays the other player's current world for specific lang.yml messages.
• %player_kills% - Displays the player's current player vs player kill count.
• %mob_kills% - Displays the player's current mob kill count.
• %player_deaths% - Displays the player's current death count.
• %player_location% - Displays the player's current location (x, y, z).
• %player_health% - Displays the player's current health.
• %player_food% - Displays the player's current food level.
• %player_hit% - Currently limited to ItemCommands, this is the player damaged such as on-hit.
• %player_interact% - Currently limited to ItemCommands, replaces with the name of the player which you have left-clicked or right-clicked. Example; /duel %player_interact%

Custom books can get a bit complicated and tricky so bear with me. To begin creating your custom book you must set the ID to WRITTEN_BOOK. It must be that and it cannot be anything else. You have the option of adding an author if you would like by adding the author's identifier.

The way books are created has been completely rewritten, so now it is a lot easier. It is super simple, just like defining commands, however, you will need to create an identifier for each page, below I used numbers to show that. Then you just have to list the page lines as you want.

Custom books also support JSON events, along with support for all PlaceholderAPI placeholders, as well as default ItemJoin internal placeholders. NOTE; JSON events such as hover/open_url/run_command/etc will not work on MC 1.7 and below as Minecraft does not support it for books. (Text Components)

Creating a JSON event is easy, they are simply defined via <TYPE:VALUE> The type is the JSON event which currently are open_url, run_command, show_text, text, and change_page. The value is the desired value aka, text, command, or page number for example. What is also great about this system is you can link multiple JSON events as shown in the example below.

Example of a JSON event;

<text:I am a clickable hover text component><show_text:Visit the website! \nAnyone is welcome.><open_url:https://www.craftationgaming.com>

Creating open_url and run_command events are very similar to the hover event, take the example event below and fill in the value to be executed when the player clicks on the text, then after that replace the text "Click to view ItemJoin." or "Click to run a Command." with the custom text you wish to appear on the page. This line of text will be the one you have to hover on to show the value text.

Example of an open_url JSON event;

<open_url:https://www.spigotmc.org/resources/itemjoin.12661/>

This still needs a text so that it is clickable which is where linking multiple JSON events comes into play;

<text:&aView the resource><open_url:https://www.spigotmc.org/resources/itemjoin.12661/>

You can also link in regular text (non-JSON event text) with JSON events.

&aView the resource<open_url:https://www.spigotmc.org/resources/itemjoin.12661/>

Example of a run_command JSON event;

<run_command:/say ItemJoin is so AMAZING!>

This as well still needs a text so that we can have a clickable command action;

<text:&aWhat is ItemJoin?><run_command:/say ItemJoin is so AMAZING!>

Example of a change_page JSON event;

Switch Pages<change_page:2>

This as well still needs a text so that we can have a clickable change page button;

<text:&aPage Two!><change_page:2>

If there is something that is currently not set up for ItemJoin JSON books, you can actually input your own RAW JSON data for each book-line. If you have raw JSON data you can now put that as a page line to appear, for example, this would be useful for clickable hover text as shown in the example below. Simply add the "raw: " identifier and paste the raw JSON data, this can include the ["" or exclude it. Please note that this only works for each separate line on each book page.

  book-item-example:
    id: WRITTEN_BOOK
    slot: 0
    name: '&c&nCreating a Book'
    author: '&bItemJoin'
    lore:
      - '&7'
      - '&7This magical book is given on join!'
    pages:
      1:
      - 'raw: ["",{"text":"I am a hidden text!","color":"yellow","clickEvent":{"action":"open_url","value":"https://www.spigotmc.org/resources/itemjoin.12661/"},"hoverEvent":{"action":"show_text","value":{"text":"","extra":[{"text":"Click to visit the spigot page.","color":"blue"}]}}}]'
      - '&eThis is Line Number TWO of page ONE.'

Here is an example of a custom book item;

  book-item:
    id: WRITTEN_BOOK
    author: '&bRockinChaos'
    slot: 6
    name: '&c&nCreating a Book'
    lore:
    - '&7'
    - '&7Useful for server rules'
    - '&7and other server information.'
    pages:
      '1':
      - '&aThanks for checking'
      - '&aout &bItemJoin &aby'
      - '<text:&b@RockinChaos#6746><open_url:https://discord.gg/D5FnJ7C><show_text:Click to visit the discord.>'
      - ''
      - '&0This is an example of'
      - '    a &9custom book&0.'
      - '&0-=-=-=-=-=-=-=-=-=-'
      - ''
      - '&0You can set an &cauthor&r'
      - '&0and you can add text'
      - '&0components using the'
      - '&0format <<text:TYPE><show_text:Replace TYPE with the component type. \nExample: run_command, show_text, open_url.>:<text:VALUE><show_text:Replace VALUE with the text, url or command.>>.'
      '2':
      - '&cHow do you specify a'
      - '&cnew page number?'
      - ''
      - '&0As displayed to the'
      - '&0left in the items.yml.'
      - '&0Create a number to'
      - '&0specify the new page.'
      - '&cMakesure you put'
      - '&ceach number in order.'
      - ''
      - '&aNote:&0 that you can'
      - '&0only have &b14&0 lines '
      - '&0per page.'
      '3':
      - '&0I still &nneed&r help&r!'
      - ''
      - '&0RockinChaos is always'
      - '&0happy to help so feel'
      - '&0free to reach out'
      - '&0on <text:&adiscord.><open_url:https://discord.gg/D5FnJ7C><show_text:Click to visit the discord.>'
      - ''
      - '&0You can also visit'
      - '&0the <text:&9wiki page><open_url:https://github.com/RockinChaos/ItemJoin/wiki><show_text:Click to view the wiki.> &rfor'
      - '&0additional help on'
      - '&0the plugin including'
      - '<text:&9custom books.><open_url:https://github.com/RockinChaos/ItemJoin/wiki/Creating-Items#creating-a-custom-book><show_text:Click for additional \nhelp with creating books.>'
      - ''
      - 'raw: ["",{"text":"Visit Plugin Page!","color":"gold","clickEvent":{"action":"open_url","value":"https://www.spigotmc.org/resources/itemjoin.12661/"},"hoverEvent":{"action":"show_text","value":{"text":"","extra":[{"text":"Click to visit the spigot page.","color":"green"}]}}}]'

Your custom firework item's ID must be FIREWORK, if you are using Minecraft v1.13 or above it must be set to FIREWORK_ROCKET. If it is not set to either of those it will not work. Each firework must have the firework identifier as shown below. You must specify what firework type you would like your firework to be. The available firework types are; BALL, BALL_LARGE, BURST, CREEPER, STAR.

You also have the option of enabling / disabling flicker and trail from your firework. Flicker is if you want the particles after the explosion to sparkle and fade out. The trail is if you want your firework to leave a trail of misty smoke behind the fireworks path of trajectory.

Next, you must specify the power, the power represents the distance the firework will travel before it will explode. For example, 1 is fairly close to the ground, 2 is fairly high in the sky. It is recommended that you keep the power BELOW 2, as it will get really high up into the sky if it is set any higher than 2.

Finally, you must set the color identifier. Within the color identifier, you can add as many colors as you want! These colors must be Dye colors. The available dye colors are; BLACK, BLUE, BROWN, CYAN, GRAY, GREEN, LIGHT_BLUE, LIME, MAGENTA, ORANGE, PINK, PURPLE, RED, SILVER, WHITE, YELLOW. You can see the list of dye colors here.

Here is an example of a custom firework item;

items:
  firework-item:
    id: FIREWORK
    slot: 0
    firework:
      type: CREEPER
      flicker: true
      trail: true
      power: 1
      colors: GRAY, WHITE, PURPLE, SILVER, GREEN

Custom maps are really simple and easy to set up! All you need to do is set the ID to MAP and add the custom-map-image identifier as shown below.

Just put the image you want to be displayed on your map in the local ItemJoin folder, where the config files are located, and replace the default.png with the name of the png file.

NOTE: The map image must be NO LARGER than 128x128 pixels, this is a perfect fit for the map size. The image file you use can be any format such as PNG or JPG. There is also support for animated GIF's as long as the file ends in (.gif).

Here is an example of a custom map item;

items:
  map-item:
    id: FILLED_MAP
    slot: 0
    custom-map-image: 'default.png'

• Custom Map Images on a specific Map ID.

  • You can specify a map id for a custom map but leaving this undefined will allow ItemJoin to select a map id to use by itself.
  • Only define this if you know what you are doing or experience conflicts with another plugin.

• Vanilla Map ID's

  • If you do not define a custom-map-image the map-id defined will now select the defined VANILLA map (or canvas rendered by another plugin).

Example;

items:
  map-item:
    id: FILLED_MAP
    slot: 0
    map-id: 17

Custom Player Heads are super simple to set up. Set the ID to SKULL_ITEM, or PLAYER_HEAD if you are using Minecraft v1.13 or above, and set the data value to 3 at the end of the item's id. The data-value being 3 means it is a player head.

Finally, just add the skull-owner identifier as shown below and put the name of the player you want to be displayed on the skull. In the example, a placeholder %player% is shown. This means the player that gets the skull in their inventory will show their own skin! So everyone gets their own skull, with their own skin!

Also, note; Skull Owners are able to be animated (change textures upon a given interval) see the Animation Section at the bottom of this page.

Here is an example of a custom skull item;

items:
  skull-item:
    id: 'SKULL_ITEM:3'
    slot: 0
    name: '&b%player%'
    skull-owner: '%player%'

Custom Skull Textures are super simple to set up, they work almost identically to Custom Player Skulls. Set the ID to SKULL_ITEM, or PLAYER_HEAD if you are using Minecraft v1.13 or above, and set the data value to 3 at the end of the item's id. The data-value being 3 means it is a player head.

Finally, just add the skull-texture identifier as shown below and put the texture code (encoded in Base64) that you want to be displayed on the skull.

My system mainly works off of http://minecraft-heads.com, however, it will work for any URL as long as its encoded in Base64, as shown in the screenshots minecraft-heads.com already supplies the needed texture for you so not many people will have to worry about it. If you are using a skull-texture do not define a skull-owner, otherwise, the item will not be given.

If you experience issues or would rather use a players UUID to generate the skull-texture--specifying skull-texture: '%player_uuid%' will attempt to fetch the player's skin directly from Mojang. Useful if you are unable to have the spigot API fetch the skull-owner directly.

In addition to supporting the UUID placeholder, you can also add a url- specification for skull-texture. You can specify a DIRECT URL to the skull-texture map. Typically this would be something resembling url-http://textures.minecraft.net/texture/955d611a878e821231749b2965708cad942650672db09e26847a88e2fac2946 If you use specifically textures.minecraft.net you can specify the ending texture bytes instead of the full URL resembling url-955d611a878e821231749b2965708cad942650672db09e26847a88e2fac2946 The URL can be either HTTP or HTTPS. Example skull items;

  skull1:
    id: PLAYER_HEAD
    skull-texture: 'url-13e8bbc8d174aecd6b46888fa63f9bade14b042e5e17063139d67f8e0163a38'
  skull2:
    id: PLAYER_HEAD
    skull-texture: 'url-http://textures.minecraft.net/texture/955d611a878e821231749b2965708cad942650672db09e26847a88e2fac2946'

Also, note; Skull Textures are able to be animated (change textures upon a given interval) see the Animation Section at the bottom of this page.

Here is a random head I found at; minecraft-heads.com, copy the code supplied from them.

This is the code I copied all spaced out so you can see what everything is.

This is what you need from the code highlighted in red. Make sure you copy this.

Paste the code as shown below into the skull-texture identifier.

Shown working with the Cauldron as well as another random skull texture I found.

Here is an example of a custom skull item using skull textures;

items:
  skull-item:
    id: 'SKULL_ITEM:3'
    slot: 0
    skull-texture: 'eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvMGZlMzFlYWE4YThhZDhkZDhkN2FiOTZhODQyMzI5MDUzOWQzODdkODJkNDI2ODcwMWVjNjlkNDFhMWZjIn19fQ=='
    enabled-worlds: world, world_nether, world_the_end

Custom Arrows are meant for making Tipped Arrows, these are the new 1.9 arrows with potion effects. All you have to do is set the id to TIPPED_ARROW, and add the potion-effects identifier, which is the effect given off by the arrow, the power; strength of the arrows potion effect, the default is 1 and there is no limit that I have found, Lastly would be the time; this is the time in seconds that the effect of the arrow will have on the target it is on in seconds, the default is set to 20 seconds. So formatting would look like this; Effect:LevelOfEffect:DurationInSeconds you can see below I did Wither 1 with 20 seconds of duration.

Here is an example of a custom arrow item;

items:
  arrow-item:
    id: TIPPED_ARROW
    slot: 0
    count: 16
    potion-effects: WITHER:1:20

NOTE: Any potion effect duration longer than 1800 seconds (30 minutes) will result in an infinite duration!

Custom Potions can be LINGERING, SPLASH, and simply a regular potion bottle. The setup is very similar to custom tipped arrows, simply specify the id of the potion, this can be the default (blank) potion or you can specify a specific potion type such as a blindness splash potion (so it looks like an actual blindness potion) and modify its effect(s) by specifying the potion effects, which will overwrite any default potion effects.

So formatting would look like this; Effect:LevelOfEffect:DurationInSeconds you can see below I did BLINDNESS 1 with 20 seconds of duration.

Here is an example of a custom arrow item;

items:
  splash-blindness:
    id: POTION:16392
    slot: 0
    count: 16
    potion-effects: BLINDNESS:1:20

NOTE: Any potion effect duration longer than 1800 seconds (30 minutes) will result in an infinite duration!

This is a very simple feature but you can easily change the color of a firework charge using ItemJoin! Simply set the id to FIREWORK_CHARGE, or FIREWORK_STAR if you are using Minecraft v1.13 or above and add charge-color: ColorName and the firework charge will spawn in with that color.

Here is an example of a custom firework charge item;

items:
  charge-item:
    id: FIREWORK_CHARGE
    charge-color: BLUE
    slot: 0

Custom golden apples are apples that have custom potion effects. These work with both golden apples and notch apples. Just add the potion-effects identifier like the custom potions. Formatting goes as such Effect:LevelOfEffect:DurationInSeconds as you can see below I did Jump level 2 with 120 seconds of time applied to you upon drinking it.

Here is an example of a custom golden apple item;

items:
  golden-apple-item:
    id: GOLDEN_APPLE
    slot: 0
    potion-effects: JUMP:2:120, NIGHT_VISION:2:400, GLOWING:1:410, REGENERATION:1:160

NOTE: Any potion effect duration longer than 1800 seconds (30 minutes) will result in an infinite duration!

Custom food is very similar to custom apples or tipped arrows, you can create custom foods using potion-effects including skull items with food skins, this can typically be any consumable item. Formatting goes as such Effect:LevelOfEffect:DurationInSeconds as you can see below I did Jump level 2 with 120 seconds of time applied to you upon drinking it.

Here is an example of a custom golden apple item;

items:
  beef-item:
    id: COOKED_BEEF
    slot: 0
    potion-effects: NIGHT_VISION:2:400
  skull-item:
    id: PLAYER_HEAD
    slot: 1
    potion-effects: GLOWING:1:410
    skull-texture: 'eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvOWI3NGNmMDA4ZGNmNDM3NDc0MGU1ODdlM2FkOGE5ZjBhNWY1NDI3ZGUyZDY5ZmZhZjA2MjA2NjNmMjEyYmNkZSJ9fX0='

NOTE: Any potion effect duration longer than 1800 seconds (30 minutes) will result in an infinite duration!

To create custom banners, all you have to do is set your item's id to BANNER, or WHITE_BANNER if you are using Minecraft v1.13 and above, and add the banner-meta identifier as shown below.

The format for the banner meta works as such, COLOR:PATTERN. You can add multiple Colors and Patterns to create some amazing effects, just separate them by commas. You can create almost anything if you set them in the right order.

Here is the Banner Meta used to create the banner in the images;

    banner-meta: RED:HALF_HORIZONTAL, BLACK:RHOMBUS_MIDDLE, RED:STRIPE_TOP, WHITE:STRIPE_BOTTOM, BLACK:STRIPE_MIDDLE, WHITE:CIRCLE_MIDDLE

Here is an example of a custom banner item;

items:
  banner-item:
    id: BANNER
    slot: 0
    banner-meta: BLUE:BASE, WHITE:CREEPER
    enabled-worlds: world, world_nether, world_the_end

Coloring leather armor is as simple as setting the id to leather helmet/chest/leggings/boots. Then just add the leather-color identifier as shown below. The format for changing leather color is leather-color: COLOR. The list of available colors is located here. You also have the option to use hex color codes for a leather's color. You can use the hex color tool here. Example of hexcolor;

    leather-color: f4d0ec

Here is an example of a custom dyed leather armor item;

items:
  leather-helmet:
    id: LEATHER_HELMET
    leather-color: BLUE
    slot: 0

Teleport arrows will teleport the player to the arrows' landing location when fired by a BOW or CROSSBOW. This arrow can display an effect at its landing location as well as a sound. A teleport arrow functions similar to teleport bow plugins used in lobby servers. Upon teleporting the player will retain their facing direction.

To create a teleport arrow you will need to add the teleport itemflag for the arrow to function, sounds and effects are completely optional. If you want to add an effect you can add teleport-effect: ENDER_SIGNAL to the arrow item and it will be displayed when the arrow lands at its landing location. If you want to add a sound you can add teleport-sound: ENTITY_ENDERMAN_TELEPORT to the arrow item and it will be played when the arrow lands at its landing location. Example, (this works with ARROW and TIPPED_ARROW);

  example-item:
    id: ARROW
    slot: 0
    itemflags: teleport
    teleport-sound: ENTITY_ENDERMAN_TELEPORT
    teleport-effect: ENDER_SIGNAL

Dynamic items are items that update periodically when there is a change to the item(s) name or lore, that being mostly to do with placeholders, these could also be interpreted as "live" items.

Creating an updating item is a little complex but becomes easier once you learn how to do the proper formatting. First off you will need to add the itemflag dynamic to the item. Once you do this you must specify a delay. If no delay is specified then the default delay will be 100 ticks which is every 5 seconds. If you want the name to update simply add delay:TimeInTicks to the beginning of the name you specified for the item. If you want to update the lore as well you will need to place delay:TimeInTicks in the first line of lore only, not in the additional lines. The name and lore can update at different ticks being completely independent of each other. Keep in mind that 20 ticks are equal to 1 second(s).

Say I want to update the number of players that are online every 120 ticks which is every 6 seconds. I would add delay:120 at the beginning of the name shown in the example below. As you can see the delay:120 does not actually appear in the items name.

Next, I want to update the current server up-time and players online every 20 ticks which is every 1 second(s), I would add delay:20 to only the first line of the item's lore. As you can see shown in the GIF below it seamlessly updates the item's lore counting the server's update up every second as if it was a clock.

A nice option is for skull-owners as well, these if given the dynamic itemflag can update the player's skin if they happen to change it.

Note: If you have to update the item any faster (less than) 20 ticks and you are running Spigot, you will need to edit your spigot.yml in your server folder and set item-dirty-ticks to 1, this limitation does not exist in CraftBukkit so you will not have to worry about it. Also the lower you set the ticks the harsher it could be on your server performance, this has not been proven but logically it will depend on your server specs, if you have a computer with decent specs then you will be fine. It is not recommended to set your ticks any lower than 3 ticks otherwise there could be a decrease in server performance.

Here is an example of a custom dynamically updated item;

items:
  dynamic-item:
    id: WATCH
    slot: 0
    name: '<delay:120>&a%server_online% Player(s) Online'
    lore:
      - '<delay:20>&7Current Server Uptime Is; %server_uptime%'
      - '&7%server_online% player(s) online.' #// This line does not need a delay, as the delay is uses it the first line of the lore (above).
    itemflags: dynamic, inventory-modify, hide-attributes
    enabled-worlds: world, world_nether, world_the_end

Animated items are items that update periodically when there is a change to the item(s) name or lore, the name and lore can change to anything you desire after each delay!

Animated items are based off a similar structure as dynamic items, however, these items can switch between the different name and lore iterations. First, you are going to want to add the itemflag animate or animated to your item. Next, you will want to create at least two lines in the name to iterate through, as shown below I had done 12 lines. I used numbers as an example since they are cleaner but you can call the line whatever you want just like the item's identifier structure. In each line specify a delay, if no delay is specified it will default to 100 ticks which is every 5 seconds. Simply add delay:TimeInTicks to the beginning of the name you specified for the item. If you want to animate the lore as well you will need to place delay:TimeInTicks in the first line of lore only for each iteration, not in the additional lines. The name and lore can animate at different ticks/speeds being completely independent of each other. Keep in mind that 20 ticks are equal to 1 second(s).

Below you can see the new structure for changing the name and lore. Each line has a delay of 3 ticks, this delay takes effect after the first delay/name change. So say you are going from name 1: to name 2:, the delay would be the original delay + the 2nd delay, making it so the 2nd name change will take effect 3 ticks after the first name change is applied.

Skull-Owners, Material-ID's, and Skull-Textures all support animation as shown in the examples below.

Note: If you have to animate the item any faster (less than) 20 ticks and you are running Spigot, you will need to edit your spigot.yml in your server folder and set item-dirty-ticks to 1, this limitation does not exist in CraftBukkit so you will not have to worry about it. Also the lower you set the ticks the harsher it could be on your server performance, this has not been proven but logically it will depend on your server specs, if you have a computer with decent specs then you will be fine. It is not recommended to set your ticks any lower than 3 ticks otherwise there could be a decrease in server performance.

Here is an example of a custom dyed leather armor item;

items:
  animated-item:
    id: COMPASS
    slot: 0
    name:
      1: '<delay:3>&f&lSearch'
      2: '<delay:3>&b&lS&f&learch'
      3: '<delay:3>&b&lSe&f&larch'
      4: '<delay:3>&b&lSea&f&lrch'
      5: '<delay:3>&b&lSear&f&lch'
      6: '<delay:3>&b&lSearc&f&lh'
      7: '<delay:3>&b&lSearch'
      8: '<delay:3>&f&lS&b&learch'
      9: '<delay:3>&f&lSe&b&larch'
      10: '<delay:3>&f&lSea&b&lrch'
      11: '<delay:3>&f&lSear&b&lch'
      12: '<delay:3>&f&lSearc&b&lh'
    lore:
      1:
      - '<delay:3>&f&lColors!!!'
      2:
      - '<delay:3>&c&lC&f&lolors!!!'
      3:
      - '<delay:3>&c&lC&a&lo&f&llors!!!'
      4:
      - '<delay:3>&c&lC&a&lo&5&ll&f&lors!!!'
      5:
      - '<delay:3>&c&lC&a&lo&5&ll&3&lo&f&lrs!!!'
      6:
      - '<delay:3>&c&lC&a&lo&5&ll&3&lo&1&lr&f&ls!!!'
      7:
      - '<delay:3>&c&lC&a&lo&5&ll&3&lo&1&lr&e&ls&f&l!!!'
      8:
      - '<delay:3>&c&lC&a&lo&5&ll&3&lo&1&lr&e&ls&d&l!&f&l!!'
      9:
      - '<delay:3>&c&lC&a&lo&5&ll&3&lo&1&lr&e&ls&d&l!&a&l!&f&l!'
      10:
      - '<delay:3>&c&lC&a&lo&5&ll&3&lo&1&lr&e&ls&d&l!&a&l!&2&l!'
      11:
      - '<delay:3>&f&lC&a&lo&5&ll&3&lo&1&lr&e&ls&d&l!&a&l!&2&l!'
      12:
      - '<delay:3>&f&lCo&5&ll&3&lo&1&lr&e&ls&d&l!&a&l!&2&l!'
      13:
      - '<delay:3>&f&lCol&3&lo&1&lr&e&ls&d&l!&a&l!&2&l!'
      14:
      - '<delay:3>&f&lColo&1&lr&e&ls&d&l!&a&l!&2&l!'
      15:
      - '<delay:3>&f&lColor&e&ls&d&l!&a&l!&2&l!'
      16:
      - '<delay:3>&f&lColors&d&l!&a&l!&2&l!'
      17:
      - '<delay:3>&f&lColors!&a&l!&2&l!'
      18:
      - '<delay:3>&f&lColors!!&2&l!'
      19:
      - '<delay:3>&f&lColors!!!'
    itemflags: animate, death-drops
    triggers: join
    enabled-worlds: world

Example of an item with Animated Skull-Texture;

  skulldb-item-example:
    id: PLAYER_HEAD
    slot: 0
    name: '&fCyclone'
    skull-texture:
      1: '<delay:100>eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvMGZlMzFlYWE4YThhZDhkZDhkN2FiOTZhODQyMzI5MDUzOWQzODdkODJkNDI2ODcwMWVjNjlkNDFhMWZjIn19fQ=='
      2: '<delay:100>eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvOTYxZGZkZGE3MTAyMmJmYWQ3OWVhYmJmYTU2YTE1MTE2NDdiMjAyYWQxMTM2ZmY5N2UzMWEwNmRiYWMxMGVjYiJ9fX0='
      3: '<delay:100>eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvZGFmNjJkNjJkMGE5MzZmMDdmZGZjMWM2MDcyMTY4NzVjOTkzZTViZWViY2U5NTNlOWM4NzI0YTI1ZmNiYTBiYyJ9fX0='
    lore:
      - '&7This is a custom textured skull.'
      - '&7'
      - '&7You can create your own skull texture'
      - '&7and apply it to a skull item!'
    itemflags: inventory-modify, death-drops, self-drops, animate
    triggers: join, respawn, world-switch
    enabled-worlds: world, world_nether, world_the_end

Example of an item with Animated Skull-Owner;

  skull-item-example1:
    id: PLAYER_HEAD
    slot: 0
    skull-texture:
      1: '%player%'
      2: 'RockinChaos'
      3: 'Notch'
    itemflags: animate
    triggers: join, respawn, world-switch
    enabled-worlds: world, world_nether, world_the_end

Example of an item with Animated Material;

  filler-pane-item-example:
    id:
      1: '<delay:40>BLACK_STAINED_GLASS_PANE'
      2: '<delay:20>BLUE_STAINED_GLASS_PANE'
      3: '<delay:20>GREEN_STAINED_GLASS_PANE'
      4: '<delay:20>MAGENTA_STAINED_GLASS_PANE'
      5: '<delay:20>ORANGE_STAINED_GLASS_PANE'
      6: '<delay:20>RED_STAINED_GLASS_PANE'
    slot: Arbitrary, Arbitrary, Arbitrary, Arbitrary
    name: '&f'
    itemflags: inventory-modify, placement, animate
    triggers: join, world-switch
    enabled-worlds: world, world_nether, world_the_end

Better example item;

  animated-item:
    id: SIGN
    slot: 0
    name:
      1: '<delay:20>&f&lStatistics'
      2: '<delay:40>&e&lS&f&lt&e&la&f&lt&e&li&f&ls&e&lt&f&li&e&lc&f&ls'
      3: '<delay:20>&b&lS&f&lt&b&la&f&lt&b&li&f&ls&b&lt&f&li&b&lc&f&ls'
      4: '<delay:40>&a&lS&f&lt&a&la&f&lt&a&li&f&ls&a&lt&f&li&a&lc&f&ls'
      5: '<delay:20>&d&lS&f&lt&d&la&f&lt&d&li&f&ls&d&lt&f&li&d&lc&f&ls'
      6: '<delay:40>&e&lS&f&lt&e&la&f&lt&e&li&f&ls&e&lt&f&li&e&lc&f&ls'
    lore:
      1:
      - '<delay:60>&cMob Kills: %mob_kills%'
      - '&cPlayer Kills: %player_kills%'
      2:
      - '<delay:60>&cDeaths: %player_deaths%'
      - '&cYour Location: %player_location%'
      3:
      - '<delay:60>&cHealth: %player_health%'
      - '&cFood Level: %player_food%'
    itemflags: death-drops, animate
    triggers: join, respawn, world-switch
    enabled-worlds: world, world_nether, world_the_end

• You can specify a list of mobs and their probability of dropping the custom item.
• A probability of 1.0 is the max probability and is considered to be 100%.
• Formatting is ENTITY:PROBABILITY.
• The Entity expects an entity type input, obviously all entities will not work such as an ender pearl. The entity input should be a physical mob. List of entities here: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/entity/EntityType.html
• Recommendations (not required): Set triggers to DISABLED to prevent players from getting the items on join. Set the slot to ARBITRARY--there is no real reason for this but it can help with compatibility in the future.

Example Mob Drops item that could potentially be dropped from a Zombie or more likely a Pig;

  mobs-item:
    id: IRON_SWORD
    slot: ARBITRARY
    name: '&cStolen Sword'
    lore:
    - '&7Pulled from the ashes of chaos.'
    mobs-drop:
    - 'ZOMBIE:0.001'
    - 'PIG:0.3'
    triggers: DISABLED
    enabled-worlds: world, world_the_end

• You can specify a list of mobs and their probability of dropping the custom item.
• A probability of 1.0 is the max probability and is considered to be 100%.
• Formatting is MATERIAL:PROBABILITY.
• The Material expects a block type input, obviously all materials will not work such as a COOKED_STEAK. The block input should be a physical block. List of materials here: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Material.html
• Recommendations (not required): Set triggers to DISABLED to prevent players from getting the items on join. Set the slot of ARBITRARY--there is no real reason for this but it can help with compatibility in the future.

Example Block Drops item that could potentially be dropped from a GOLD_ORE or more likely a DIAMOND_ORE;

  blocks-item:
    id: DIAMOND_BLOCK
    slot: ARBITRARY
    name: '&aSurprise!'
    blocks-drop:
    - 'DIAMOND_ORE:0.5'
    - 'GOLD_ORE:0.19'
    triggers: DISABLED
    enabled-worlds: All

• You can specify a recipe for a custom item.
• To define a recipe, you must specify the shape with the ingredient characters, as well as the ingredients with their characters. The ingredients expect a single character followed by the material input. See the example item below.
• Recipe shapes are quite diverse and can be defined in unique shapes as shown.
• You may require a player to put more then one item in a single slot to craft an item. This would look like this: - 'I:IRON_INGOT:#3'
• X Stands for Air, do NOT include X in the 'ingredients' below.

Examples of Recipe usages, these are ways to allow the user to craft the item, you can only choose one, you can restrict an item to a 3x3 bench or keep it a 2x2 size for crafting in a player inventory:

    recipe:
    - 'XGX'
    - 'IDI'
    - 'XGX'
    recipe:
    - 'XG'
    - 'XD'
    recipe:
    - 'XGX'
    - 'IDI'
    recipe:
    - 'G'
    - 'D'
    - 'G'

Example Recipe item that is crafted using a 3x3 crafting bench, and GOLD_INGOT, IRON_INGOT, and DIAMOND as materials;

  recipe-item:
    id: BEDROCK
    slot: ARBITRARY
    name: '&6Essence'
    lore:
    - '&7Shhhh don''t tell anyone...'
    recipe:
    # X Stands for Air, do NOT include X in the 'ingredients' below.
    - 'XGX' # First row in the crafting table
    - 'IDI' # Second row in the crafting table
    - 'XGX' # Third row in the crafting table
    ingredients:
    # Format: LETTER:ITEMID
    - 'G:GOLD_INGOT' # G Stands for Gold Ingot.
    - 'I:IRON_INGOT' # I Stands for Iron Ingot.
    - 'D:DIAMOND' # D Stands for Diamond, you can use any letter here and the ITEMID can be numerical.
    triggers: DISABLED

You can also define the ingredients as a custom item node. So if you have a custom item you wish to have as an ingredient in the current custom items recipe you can define it by using the item node such as ultra-item.

Example;

    ingredients:
    - 'G:GOLD_INGOT' # G Stands for Gold Ingot.
    - 'U:ultra-item' # U Stands for the custom ultra-item.
    - 'B:bungee-item' # B Stands for the custom bungee-item.

Furthermore, you may also define multiple recipes for a single item. To do this, simply assign a unique number to each recipe.

Here is an example;

  recipe-item:
    id: BEDROCK
    slot: ARBITRARY
    name: '&6Essence'
    lore:
    - '&7Shhhh don''t tell anyone...'
    recipe:
      '1':
      - 'XAX'
      - 'DXB'
      - 'XCX'
      '2':
      - 'XAX'
      - 'EXE'
      - 'XFX'
    ingredients:
      - 'A:COAL'
      - 'B:IRON_INGOT'
      - 'C:DIAMOND'
      - 'D:EMERALD'
      - 'E:GOLD_INGOT'
      - 'F:NETHER_STAR'
    triggers: DISABLED

• You can now define EXISTING custom items inside a Shulkerbox.
• Start by creating items as normal to be set as an ItemJoin item, except set the triggers to DISABLED. The only limits for these items are they need to be slots from 0 to 26, any smaller or larger will not work as shulker boxes are smaller than a player inventory. You can also use slot ARBITRARY any other custom slots will not work since there is no crafting inventory or armor slots.
• These contents are the CONFIG NAME of the ItemJoin item you want to be set. The config names are what define the items, in the example, the shulker box is called shulker-item which is the config name, (not the item name).

Example using default items from the items.yml;

  shulker-item:
    id: BLACK_SHULKER_BOX
    slot: 0
    contents:
    - ultra-item
    - map-item
    - animated-panes
    triggers: join, respawn, world-switch
    enabled-worlds: ALL

• You can now define properties for each of your custom items.
• You can define a single property or a list of properties separated by a comma.
• Format is Identifier:Value and for clarification, these are called NBTTags.
• Example; properties: 'TranslatableDisplayName:&aUltra &cItem, Slot:33'
• This will add TranslatableDisplayName with the String value &aUltra &cItem and add Slot with the Integer value 33`.
• This is mainly useful for implementing features from other plugins.

Example;

  nbt-item:
    id: COMPASS
    slot: 33
    properties: 'TranslatableDisplayName:&aUltra &cItem, Slot:33, Plugin:Waystones'
    triggers: join, respawn, world-switch
    enabled-worlds: ALL

• Disposable Conditions
  • The item will only be removed from the player if the condition is MET, commands will execute regardless.
  • You can specify a fail message if the condition was not met, this is optional.
  • You can specify a single condition or a list of conditions, however in the list only ONE of the conditions needs to be MET.
  • Current conditional operands are EQUAL, NOTEQUAL, OVER, and UNDER--Over and Under is specifically INTEGER ONLY conditions.
  • Remember to add the disposable itemflag for this to function.
  • Example;

disposable-conditions:
- '%mypet_has_pet_treat%:equal:true'
- '%other_placeholder%:notequal:VALUE'
- '%other_placeholder%:over:300'
- '%other_placeholder%:under:700'
disposable-fail-message: '&cYou get to keep your item, lucky!'

• Command Conditions
  • The item command will only be executed if the condition is MET.
  • You can specify a fail message if the condition was not met, this is optional.
  • You can specify a single condition or a list of conditions, however in the list only ONE of the conditions needs to be MET.
  • Current conditional operands are EQUAL, NOTEQUAL, OVER, and UNDER--Over and Under is specifically INTEGER ONLY conditions.
  • Command conditions are defined as their action-condition as an example, the action being inventory-left would be inventory-left-condition.
  • Example;

inventory-left-conditions:
- '%mypet_ishungry%:equal:true'
- '%other_placeholder%:notequal:VALUE'
- '%other_placeholder%:over:600'
- '%other_placeholder%:under:500'
inventory-left-fail-message: '&cYou cannot execute that command until you feed your pet more.'

• Trigger Conditions
  • The item will only be given to the player upon performing the trigger and the condition is MET.
  • The /itemjoin get command(s) respect this condition and will not be given if they are not met.
  • You can specify a fail message if the condition was not met, this is optional.
  • You can specify a single condition or a list of conditions, however in the list only ONE of the conditions needs to be MET.
  • Current conditional operands are EQUAL, NOTEQUAL, OVER, and UNDER--Over and Under is specifically INTEGER ONLY conditions.
  • Example;

trigger-conditions:
- '%mypet_has_pet%:equal:true'
- '%other_placeholder%:notequal:VALUE'
- '%other_placeholder%:over:100'
- '%other_placeholder%:under:200'
trigger-fail-message: '&cYou need to summon your pet.'