Items & Armor

The item elements are used to place items into a player's inventory or armor slots. Items have many different attributes, and some may only apply to certain item types; such as the leather armor color attribute.

Item names can be found with the material finder or on the bukkit docs - Material

Item Element
ElementDescription
A single item stack.
Sub-Elements
ElementDescription
Enchantment
Stored Enchantment (for enchanted books)
Potion Effect (only works on potion items)
Attribute Modifier
Materials that can be mined with the item
Materials that the item can be placed on
Item Attributes
AttributeDescriptionValueDefault
RequiredThe item's material name.Material Name
Slot where the item will be placed in the player's inventory.
If no slot is specified the item will be merged into the player's inventory.
Inventory Slot
The amount of items. Blocks can be given an infinite amount by using "oo".Number1
The item's damage, used for items such as birch logs, red wool, potion types, etc.Number0
Specify if this item is unbreakable, hides the durability bar in minecraft.true/falsefalse
The item's display name.String
Custom lore string.String
Leather armor color as a hexadecimal color.
Only applies to leather armor items.
Hex Color
Projectile explodes on impact.
Works with ender pearls, snowballs, eggs, and arrows.
true/falsefalse
The power of the grenade explosion on impact.Decimal1.0
Explosion creates fire.true/falsefalse
Explosion destroys blocks.true/falsetrue
Prevent this item from being moved from the player's inventory.true/falsefalse
Make this item shoot a custom projectile.Projectile ID
Show enchantments in the item tooltip.true/falsetrue
Show attribute modifiers in the item tooltip.true/falsetrue
Show the unbreakable property in the item tooltip.true/falsetrue
Show the breakable block list in the item tooltip.true/falsetrue
Show the blocks the item can be placed on in the item tooltip.true/falsetrue
Show various other things in the item tooltip.true/falsetrue

Items can be give custom names and lore with the name and lore attributes. Colors and fancy text in item names or lore can be specified with the grave symbol ` and then the formatting code. You can specify multiple lines of lore using a pipe symbol | for line breaks.

<item name="`6Golden Sword" material="gold sword"/> <!-- Gold sword with a gold/yellow name. -->
<item lore="`4The One and Only" material="stick"/> <!-- A stick with the lore colored red. -->
<item lore="`eWarning!|`5Does damage!" material="iron sword"/> <!-- A sword with 2 lines of lore. -->

Custom Heads

Player heads can be given to players by using the heads element.

A player's skin data can be found by using https://sessionserver.mojang.com/session/minecraft/profile/(UUID).

<head name="Cubist" uuid="3fbec7dd-0a5f-40bf-9d11-885a54507112" slot="slot.armor.head">
<skin>eyJ0aW1lc3RhbXAiOjE0NDY0MDgwOTExNzQsInByb2ZpbGVJZCI6IjNmYmVjN2RkMGE1ZjQwYmY5ZDExODg1YTU0NTA3MTEyIiwicHJvZmlsZU5hbWUiOiJDdWJpc3QiLCJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvOTRlZGExMjg4NWIzYmE2ZGY2ODMyZGZkMTIzNGEyNjc5MmQwNDI2ZDkyMDM2ZWVlYzc1M2ZiZmM2NmRiIn19fQ==</skin>
</head>
Head Attributes
AttributeDescriptionValueDefault
The heads display name.String
PropertyRequiredUUID used to identify the player this head belongs to.String
PropertyRequiredThe skin data used for this head.String
Head Sub-elements
ElementDescriptionValue
PropertyRequiredUUID used to identify the player this head belongs to.String
PropertyRequiredThe skin data used for this head.String

Armor

Armor slots have predefined tags to make it easier to give them to a player. They accept all of the properties of normal items, and may have their own special attributes.

<helmet material="iron helmet"/>
<chestplate material="diamond chestplate"/>
<leggings material="gold leggings"/>
<boots material="leather boots"/>
Armor Attributes
AttributeDescriptionValueDefault
Prevent this armor item from being removed from the armor slot in any way.true/falsefalse

Enchanting, naming or giving armor lore works the same way as with items.

<boots material="iron boots" lore="The Winged Boots of Hermes">
<enchantment level="1">feather_falling</enchantment>
</boots>

Items like leather armor can be colored with the color attribute. The color is represented in hexadecimal, see dye colors for a list of hex colors for the different dyes.

NOTE: The hex color value is specified without the hash # symbol.

<helmet color="cd0000" material="leather helmet"/>
Team Color Attribute

The team-color attribute can be used to attribute color to leather armor automatically. This helps to simplfy kits so a seperate team kit for only colored armor is not required.

<kits>
<kit id="spawn" force="true">
<!-- automatically applies blue colored armor to blue team, red armor to red team, etc -->
<helmet team-color="true" unbreakable="true" material="leather helmet"/>
<chestplate team-color="true" unbreakable="true" material="leather chestplate"/>
</kit>
</kits>

Potions

Potion items (including lingering and splash potions) can specify their potion type, and any number of custom effects. The potion type determines the name and color of the item. It also determines the default effects of the potion. However, if any custom effects are present, they will completely replace the default effects.

By default when a player drinks a potion bottle the empty bottle is automatically removed from the players inventory. This behavior can be disabled with the <keep-potion-bottles/> tag.

See Potion Effects for details on the <effect> element.

Also see the Potions & Effects reference page.

Potion Item Sub-elements
ElementDescriptionValue
Custom effectPotion Effect
<item slot="1" material="potion" damage="3">
<effect duration="15m">fire_resistance</effect>
</item>
<!-- A Jump Boost Splash Potion -->
<item slot="0" material="potion" damage="16395">
<effect duration="3m" amplifier="2">jump_boost</effect>
</item>

Auto Potion Bottle Remover

Empty potion bottles are removed automatically when a player drinks a potion.
This feature is enabled by default, but can be disabled with this tag.

<keep-potion-bottles/>

Books

Written books can be created using the book element, the tile, author and individual pages can be formatted with formatting codes. All normal item attributes can also be applied to books.

Each page in a book can contain a maximum of 13 lines, with approximately 19 characters per line. Preferably books should be written in-game to ensure proper formatting, and then translated into the books element.

Book Element
ElementDescriptionValue
The element containing the books&Formatted Text
Book Sub-elements
ElementDescriptionValue
RequiredThe title of the book.Formatted Text
RequiredThe author of the book.Formatted Text
The pages in the book.
A newline separated string. Used insideFormatted Text
<book slot="1">
<title>`6Example`r</title>
<author>`4BB-8`r</author>
<pages>
<page>
`lPage `1I`r
This is an example
</page>
<page>
`lPage `1II`r
Nothing to see here, move along...
</page>
<!-- More pages -->
</pages>
</book>

Enchantments

Any enchantment can be applied to any item and an item can have one or multiple enchantments. The enchantment type can be specified by its Minecraft name or Bukkit name.

To store an enchantment in an enchanted book (instead of enchanting the book itself), simply replace the tag enchantment with stored-enchantment.

Enchantment Element
ElementDescriptionValue
An item enchantment.Enchantment Name
An enchantment stored in an enchanted book.Enchantment Name
Enchantment Attributes
AttributeDescriptionValueDefault
The specified enchantment's level.Number1

Examples

<!-- A sharpness II iron sword -->
<item material="iron sword">
<enchantment level="2">sharpness</enchantment>
</item>
<!-- A knockback IV stick -->
<item material="stick">
<enchantment level="4">knockback</enchantment>
</item>
<!-- Feather falling 2 boots -->
<boots material="gold boots">
<enchantment level="2">feather_falling</enchantment>
</boots>
<!-- Enchanted book of Luck -->
<item material="enchanted_book">
<stored-enchantment level="1">luck</stored-enchantment>
</item>

Attribute Modifiers

Attribute modifiers can be applied to items in the same way they are applied to kits. See Attribute Kits for details.

Additionally, a slot can be specified, in which case the modifier will only be applied when the item is in that slot. This must be an armor or hand slot.

Examples

<chestplate material="chainmail chestplate">
<attribute amount="1">generic.knockbackResistance</attribute>
</chestplate>
<item material="diamond spade">
<attribute slot="weapon.mainhand" operation="multiply" amount="2">generic.movementSpeed</attribute>
</item>

NOTE: Negative attribute values are allowed; however sometimes they don't work as expected.

Grenades

The grenade="true" attribute will make the item explode on impact, just like a grenade. This option only works on items that can turn into projectiles. For example, ender pearls, snowballs, eggs, and arrows all work.

The grenade-power="1.0" attribute sets the explosion power. The default value of 1.0 will not destroy blocks, but it will damage players and set off TNT.

The attributes grenade-fire="true" and grenade-destroy="true" determine if the explosion creates fire and/or destroys blocks.

NOTE: If an ender pearl is used as a grenade, the player will teleport to the location and the explosion will occur.

<item slot="1" amount="12" name="`4Grenade" grenade="true" grenade-power="1.2" material="snow ball"/>
<item name="`a`lRocket Ammo" amount="3" enchantment="thorns" grenade="true" grenade-power="4" grenade-fire="true" material="arrow"/>

Can-Destroy / Can-Place-On

In adventure mode, no blocks can be placed or mined by default. The <can-destroy> element allows an item to mine a specified list of blocks. The <can-place-on> element allows a block item to be placed against a specified list of blocks. In each case, the blocks are listed inside the element, each wrapped in a <material> sub-element. These blocks cannot have damage/data values (this is a limitation of Minecraft that we are unable to work around).

Instead of a list of blocks, you can use the <all-blocks/> element, which is equivalent to listing literally every block in the game. In this case, you will probably want to specify show-can-place-on="false" or show-can-destroy="false" on the item to prevent a massive tooltip being displayed to the player.

ElementsDescriptionValue/Children
A node containing the materials this item can destroy.
A node containing materials this item can be placed on.
Sub-elements
An individual material to match.
Does not accept a damage/data value.
Material Name
Match all block type materials.
<item material="iron shovel">
<can-destroy>
<material>dirt</material>
<material>grass</material>
<material>sand</material>
</can-destroy>
</item>
<item material="lever">
<can-place-on>
<all-blocks/>
</can-place-on>
</item>