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

Element	Description
`<item>`	A single item stack.

Sub-Elements

Element	Description
`<enchantment> </enchantment>` `<stored-enchantment> </stored-enchantment>`	Enchantment
`<effect> </effect>`	Potion Effects (only works on potion items)
`<attribute> </attribute>`	Attribute Modifier
`<can-destroy> </can-destroy>`	Materials that can be mined with the item
`<can-place-on> </can-place-on>`	Materials that the item can be placed on

Item Attributes

Attribute	Description	Value	Default
`material`	RequiredThe item's material name.	Material Name
`slot`	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
`amount`	The amount of items. Blocks can be given an infinite amount by using `oo`.	Number	1
`damage`	The item's damage value, used for items such as birch logs, red wool, potion types, etc.	Number	0
`unbreakable`	Specify if this item is unbreakable and hides the durability bar in Minecraft.	true/false	false
`name`	The item's display name that appears when it is selected.	Formatted Text
`lore`	Custom text that appears when a player hovers over the item in their inventory.	Formatted Text
`color`	Leather armor color as a hexadecimal color. `RRGGBB` Only applies to leather armor items.	Hex Color
`team-color`	Automatically applies the team's Dye Color to colored blocks (wool, stained glass, banner, etc).	true/false	false
`grenade`	Projectile explodes on impact. Works with ender pearls, snowballs, eggs, and arrows.	true/false	false
`grenade-power`	The power of the grenade explosion on impact.	Decimal	1.0
`grenade-fire`	Toggle if grenade explosion creates fire.	true/false	false
`grenade-destroy`	Toggle if grenade explosion destroys blocks.	true/false	true
`prevent-sharing`	Prevent this item from being moved from the player's inventory.	true/false	false
`projectile`	Make this item shoot a custom projectile.	Projectile ID
`show-enchantments`	Show enchantments in the item tooltip.	true/false	true
`show-attributes`	Show attribute modifiers in the item tooltip.	true/false	true
`show-unbreakable`	Show the unbreakable property in the item tooltip.	true/false	true
`show-can-destroy`	Show the breakable block list in the item tooltip.	true/false	true
`show-can-place-on`	Show the blocks the item can be placed on in the item tooltip.	true/false	true
`show-other`	Show various other things in the item tooltip.	true/false	true

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

Attribute	Description	Value
`name`	The head's display name.	String
`uuid`	PropertyRequiredThe UUID used to identify the player this head belongs to.	String
`skin`	PropertyRequiredThe skin data used for this head.	Base64

Head Sub-elements

Element	Description	Value
`<uuid>`	PropertyRequiredThe UUID used to identify the player this head belongs to.	String
`<skin>`	PropertyRequiredThe skin data used for this head.	Base64

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

Attribute	Description	Value	Default
`locked`	Prevent this armor item from being removed from the armor slot in any way.	true/false	false

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.

info

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 add color to leather armor automatically. Armor color is based on the team's Chat Color rather than their Dye Color, so using the dye-color attribute on Teams is not required. This helps simplfy kits so a seperate team kit for colored armor and items is not required.

<kits>
    <kit id="spawn-kit">
        <!-- automatically applies blue stained clay to blue team, red stained clay to red team, etc -->
        <item slot="0" amount="64" team-color="true" material="stained clay"/>
        <!-- automatically applies blue 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 player's inventory. This behavior can be disabled with the <keep-potion-bottles/> tag.

For more details on the <effect> element, visit Potion Effects. Additionally, you can visit Potions & Effects for references on potion effects available in Minecraft.

Potion Item Sub-elements

Element	Description	Value
`<effect>`	A custom effect.	Potion 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 title, 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

Element	Description	Value
`<book>`	The element containing the books `<title>`, `<author>`, and `<pages>`.	Formatted Text

Book Sub-elements

Element	Description	Value
`<title>`	RequiredThe title of the book.	Formatted Text
`<author>`	RequiredThe author of the book.	Formatted Text
`<pages>`	The pages in the book.	`<page>`
`<page>`	A newline separated string. Used inside `<pages>`.	Formatted 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>

Firework

You can define custom explosion designs when creating and giving a firework rocket item.

Element	Description
`<firework> </firework>`	A firework design containing one or more explosion effect.

Sub-element
`<firework> </firework>`	Define an explosion effect design.

Firework Attributes

Attribute	Description	Value	Default
`power`	Defines the power of the firework. This also determines how high it will travel.	Number	1

Explosion Attributes

Attribute	Description	Value	Default
`type`	Defines the power of the firework. This also determines how high it will travel.	`ball`, `ball large`, `burst`, `creeper`, `star`	`burst`
`flicker`	Whether the effect should flicker.	true/false	false
`trail`	Whether the effect should have a trail.	true/false	false

Explosion Sub-elements

Element	Description	Value
`<color>`	RequiredDefine a color of the firework.	Hex Firework Color
`<fade>`	Define a fade color of the firework. Multiple fade colors can be defined for each explosion. If no fade colors are defined, the explosion will not fade.	Hex Firework Color

<firework power="1">
    <!-- Defines an explosion -->
    <explosion type="creeper" flicker="true" trail="true">
        <!-- One or more colors can be defined as hex values -->
        <color>193bcf</color>
        <color>edea18</color>
        <!-- Defines a fade color as a hex value (optional) -->
        <fade>e2a31a</fade>
    </explosion>
    <!-- Another explosion with different attributes -->
    <explosion type="burst" trail="true">
        <color>b319af</color>
        <!-- Multiple fade colors can be defined -->
        <fade>e2a31a</fade>
        <fade>e2a31a</fade>
    </explosion>
</firework>

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

Element	Description	Value
`<enchantment> <enchantment>`	An item enchantment.	Enchantment Name
`<stored-enchantment> </stored-enchantment>`	An enchantment stored in an enchanted book.	Enchantment Name

Enchantment Attributes

Element	Description	Value	Default
`level`	The specified enchantment's level.	Number	1

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, they sometimes do not 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.

Elements	Description
`<can-destroy> </can-destroy>`	A node containing the materials this item can destroy.
`<can-place-on> </can-place-on>`	A node containing materials this item can be placed on.

Sub-elements		Value/Children
`<material> </material`	An individual material to match. Does not accept a damage/data value.	Material Name
`<all-blocks/>`	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>

Item Element​

Sub-Elements​

Item Attributes​

Custom Heads​

Head Attributes​

Head Sub-elements​

Armor​

Armor Attributes​

Team Color Attribute​

Potions​

Potion Item Sub-elements​

Auto Potion Bottle Remover​

Books​

Book Element​

Book Sub-elements​

Firework​

Firework Attributes​

Explosion Attributes​

Explosion Sub-elements​

Enchantments​

Enchantment Element​

Enchantment Attributes​

Attribute Modifiers​

Grenades​

Can-Destroy / Can-Place-On​