Skip to main content

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
<item>A single item stack.

Sub-Elements

ElementDescription
<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

AttributeDescriptionValueDefault
materialRequiredThe item's material name.Material Name
slotSlot 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
amountThe amount of items. Blocks can be given an infinite amount by using oo.Number1
damageThe item's damage value, used for items such as birch logs, red wool, potion types, etc.Number0
unbreakableSpecify if this item is unbreakable and hides the durability bar in Minecraft.true/falsefalse
nameThe item's display name that appears when it is selected.Formatted Text
loreCustom text that appears when a player hovers over the item in their inventory.Formatted Text
colorLeather armor color as a hexadecimal color. RRGGBB
Only applies to leather armor items.
Hex Color
team-colorAutomatically applies the team's Dye Color to colored blocks (wool, stained glass, banner, etc).true/falsefalse
grenadeProjectile explodes on impact.
Works with ender pearls, snowballs, eggs, and arrows.
true/falsefalse
grenade-powerThe power of the grenade explosion on impact.Decimal1.0
grenade-fireToggle if grenade explosion creates fire.true/falsefalse
grenade-destroyToggle if grenade explosion destroys blocks.true/falsetrue
prevent-sharingPrevent this item from being moved from the player's inventory.true/falsefalse
projectileMake this item shoot a custom projectile.Projectile ID
show-enchantmentsShow enchantments in the item tooltip.true/falsetrue
show-attributesShow attribute modifiers in the item tooltip.true/falsetrue
show-unbreakableShow the unbreakable property in the item tooltip.true/falsetrue
show-can-destroyShow the breakable block list in the item tooltip.true/falsetrue
show-can-place-onShow the blocks the item can be placed on in the item tooltip.true/falsetrue
show-otherShow 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
AttributeDescriptionValue
nameThe head's display name.String
uuidPropertyRequiredThe UUID used to identify the player this head belongs to.String
skinPropertyRequiredThe skin data used for this head.Base64
Head Sub-elements
ElementDescriptionValue
<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
AttributeDescriptionValueDefault
lockedPrevent 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.

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
ElementDescriptionValue
<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
ElementDescriptionValue
<book>The element containing the books <title>, <author>, and <pages>.Formatted Text
Book Sub-elements
ElementDescriptionValue
<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.

ElementDescription
<firework> </firework>A firework design containing one or more explosion effect.
Sub-element
<firework> </firework>Define an explosion effect design.
Firework Attributes
AttributeDescriptionValueDefault
powerDefines the power of the firework. This also determines how high it will travel.Number1
Explosion Attributes
AttributeDescriptionValueDefault
typeDefines the power of the firework. This also determines how high it will travel.ball, ball large, burst, creeper, starburst
flickerWhether the effect should flicker.true/falsefalse
trailWhether the effect should have a trail.true/falsefalse
Explosion Sub-elements
ElementDescriptionValue
<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
ElementDescriptionValue
<enchantment> <enchantment>An item enchantment.Enchantment Name
<stored-enchantment> </stored-enchantment>An enchantment stored in an enchanted book.Enchantment Name
Enchantment Attributes
ElementDescriptionValueDefault
levelThe 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, 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.

ElementsDescription
<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-elementsValue/Children
<material> </materialAn 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>