Items
On this page, we will be discussing how you can create all different kinds of custom items with the AdditionsPlus plugin. For all features to work correctly, please make sure that you are running the latest version of AdditionsPlus. Please know that some features may not be available on all versions of Bukkit/Minecraft.
Within AdditionsPlus, we work with custom items that each have unique identifiers. This identifier is used to identify the item in an inventory, but also to give the item to players and is case-sensitive.
As you probably know, all items in Minecraft have basic information like the material type, amount, display name, lore, enchantments, durability, item flags, and custom model data. Newer servers also support unbreakable. Below is an example configuration of all these basics combined into one item.
All strings (messages) in the AdditionsPlus plugin allow the usage of (player-specific) placeholders, with PAPI support. You can also add HEX colors and gradients on 1.16+ servers.
customItem: # the unique identifier
material: DIAMOND_SWORD
amount: 1
displayName: "&6Magic Sword"
lore:
- "&7This is a &bmagic sword &7that"
- "&7should be kept safe at all times."
- ""
- "&eWatch it, &d%player%&e!"
- "&eBecause it can only be used 5 times."
# format for enchantments are: 'ENCHANTMENT:LEVEL', eg 'DAMAGE_ALL:2'
# these need to follow Bukkit names, which can differ from Minecraft names.
# https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/enchantments/Enchantment.html
enchantments:
- DAMAGE_ALL:5
- KNOCKBACK:1
durability: 5 # the durability that's left of the item.
# item flags also need to follow Bukkit names, which can be found here:
# https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/inventory/ItemFlag.html
itemFlags:
- HIDE_ENCHANTS
custom_model_data: 412 # custom number that can be used in resource packs to customize the item's appearance.
unbreakable: true # (1.9+) whether the item should not lose durability/gain damage.AdditionsPlus offers a broad variety of actions that can be used to execute certain actions within your server, often tied to players. For items, you can add these actions for left- and right-click interactions. Add the following to your item configuration:
You can find a list of actions here: https://www.gcnt.net/additionsplus/actions.
left_click_actions:
- "[msg]&aYou left-clicked this cool item!"
- "[command]help"
right_click_actions:
- "[msg]&aYou right-clicked this cool item!"
- "[title]&d&lHEY!\n&eCool, right?"Items can require specific permission to be used. You can add this by adding the option permission to the item. When a player does not have the right permission, a message will be sent to the player. You can override this default message by adding permissionMessage or noPermission to the item.
permission: vip.only
permissionMessage: '&f&l[&e&l!&f&l] &cOnly &6VIP &cranks can use this item!'Items can have cooldowns. This is the time that the player has to wait before they can interact with the item again. This time is measured in ticks (1 second = 20 ticks). If the item is on cooldown for the player that is interacting with it, then a message will be sent to the player. You can override this message by adding the option cooldownMessage to the item. This message additionally supports the placeholder %time% which represents the cooldown left for the item, displayed in format 1h 5m 40s.
cooldown: 300 # 300 ticks / 20 = 15 seconds cooldown.
cooldownMessage: '&cSlow down! &7You have to wait another &e%time% &7to use this item.'You can have the item set to be put in a specific slot in the player's inventory. You can do this by adding the slot option to the item.
material: DIAMOND_HELMET
slot: 103 # sets the item to the helmet slot.We also offer an option to have players pay for an interaction (left/right-click) with the item. This will withdraw the given number of items from their inventory when they interact with the item. You can do this by adding the option item_interaction_cost to your item. This will check if the player has the given amount of this item in their inventory, and will send a message to the player (and cancel the interaction) when they do not have enough of the right item.
You can override the default message by adding item_interaction_cost_fail_message to the item. This message supports, besides the normal placeholders, two additional placeholders: %cost% for the cost of the interaction, and %found% for the number of items found in the player's inventory.
This option is a replacement for the [take] action, which could get duped because it was not taken instantly due to asynchronization.
item_interaction_cost: 5 # the player will need to turn in 5 of these items to use it.
item_interaction_cost_fail_message: "&cYou do not have enough items in your inventory. You need at least %cost% items but we only found %found%."AdditionsPlus allows you to create a skull with the skin of a player by setting the material to HEAD-<playerNameHere>. Replace with the name of the player that you want to be displayed if you know the name. It is also possible to create dynamic heads, with the owner of the viewer/owner of the item/menu by using %player% as the player name: HEAD-%player%.
material: "HEAD-%player%" # Skull of the viewer/owner of the item or menu.
material: HEAD-bob # Skull of the player bob.We allow you to use HeadDatabase skulls as base items by setting the material to HDB-<skullId>. Here, you replace with the name of the skull. You can find the ids in the lore of the skull item (in-game), or on the Minecraft Heads website.
material: "HDB-51897" # Displays a Snail headWe allow you to display your ItemsAdder creations as base items by setting the material to IA-<itemId>. Here, you replace with the complete identifier of the ItemsAdder item.
material: "IA-example_item"You can customize potions by changing the base potion and additionally the color. Potions include the materials SPLASH_POTION, POTION, and LINGERING_POTION. Potions hold a couple of extra properties besides the default ones: the potion type, whether it's upgraded (higher level), whether it's extended (longer duration), and an additional color that overrides the default.
[!] Currently it is not yet possible to add custom potion effects to the potions.
material: SPLASH_POTION
# the base type of the potion.
# this needs to follow Bukkit names, which can be found here:
# https://hub.spigotmc.org/javadocs/spigot/org/bukkit/potion/PotionType.html
potion_type: POISON
potion_extended: true # whether the potion is extended (longer duration).
potion_upgraded: false # whether the potion is upgraded (higher level).
# the HEX color of the potion.
# please know that using this will set the base potion to "WATER" since they can't all have colors.
potion_color: "#118c44"In Minecraft, leather armor supports the use of custom RGB colors. This includes LEATHER_HELMET, LEATHER_CHESTPLATE, LEATHER_LEGGINGS, and LEATHER_BOOTS. Colors should be in HEX format.
material: LEATHER_CHESTPLATE
armor_color: "#5ed6b0" # light blue-colored armor| Option | Default | Description |
|---|---|---|
material |
STONE | material of the item |
amount |
1 | amount of the item |
lore |
lore (hover description) of the item | |
slot |
the inventory slot the item should be put in | |
cooldown |
0 | the cooldown in ticks |
cooldownMessage |
&cYou can't use this item for another %time%. | message shown when the item is on cooldown |
permission |
permission node of the item | |
permissionMessage |
&cYou are not allowed to use this item. | message shown when the player has no permission |
left_click_actions |
actions to be executed on left-click interactions | |
right_click_actions |
actions to be executed on right-click interactions | |
actions |
actions to be executed on any interaction that's not left- or right-click | |
itemOptions |
list of custom additional options | |
displayName |
display name of the item | |
data |
0 | (1.8 - 1.12) material data type (such as color number for wool) |
durability |
the durability that's left of the item | |
itemFlags |
list of item flags | |
enchantments |
list of enchantments to be applied | |
unbreakable |
false | (1.9+) whether the item should be unbreakable |
custom_model_data |
0 | custom model data used in resource packs |
armor_color |
HEX color code of leather armor | |
potion_type |
the type of potion | |
potion_color |
HEX color code of the potion | |
potion_extended |
false | whether the potion has extended duration |
potion_upgraded |
false | whether the potion is upgraded (higher level) |
item_interaction_cost |
0 | items that it will cost to use the item |
item_interaction_cost_fail_message |
&cYou must have at least %cost% items to do this. You only have %found%. | message sent when the player does not have enough items |
