Item Meta
From Essentials
Some newer items have additional attributes that cannot be described by the item id alone. For example, the enchantment on a sword, the colour of wool and fireworks effects/colours. These are stored in an additional field known as 'meta data'.
Currently items with meta data can only be acquired via the /give, /i or /enchant commands, or by using kits, with the exception being 'name' which can be achieved using an Anvil.
Contents
Global Meta Data
ALL items can have a Name and Lore (or description) applied to them. You can use an underscore '_' to create a space and a pipe '|' within lore to create a new line. You can also use the Essentials colour syntax to colour this meta information as seen below.
Name
Provide a name for the item which is shown in inventory tooltips and hotbar descriptions.
You can use normal Essentials colour codes.
name:<item name>
/i dsword 1 name:&fThe_&4Monster&f_mash
Lore
Otherwise known as a description, sets text for the item which is shown in inventory tooltips and hotbar descriptions.
You can use normal Essentials colour codes, and | for new lines.
lore:<Item description>
/i daxe 1 lore:KHobbits'_ban_hammer /i bow 1 name:Mighty_twang lore:Through|the|ages
Permissions
- essentials.itemspawn.meta-title
- essentials.itemspawn.meta-lore
Usage in Kits
Below is an example of how item meta can be utelised in kits. These are defined in the Essentials config.yml file, which ships with a number of default examples.
It's also worth noting that kits can use any of the token substitutions avaliable in Manual files. Of particular note is the {PLAYER} token, which can be used to further personalise kit items. Take care with which tokens you use however, as many aren't suitable for item meta given its character length restrictions.
mychoicekit:
delay: 600
items:
- 278 1 efficiency:1 durability:1 fortune:1 name:&4Gigadrill lore:The_drill_that_&npierces|the_heavens
- ironsword 1 knockback:1 name:{PLAYER}&c'_chopper lore:Chops_them_good!
- 277 1 digspeed:3 name:Dwarf lore:Diggy|Diggy|Hole
- 298 1 color:255,255,255 name:Top_Hat lore:Good_day,_Good_day
- 279:780 1
Enchanting
Items spawned with /i or /give can also have enchantments added to them. Unless you have enabled 'unsafe-enchantments' in the Essentials configuration file, you will be limited to the Bukkit defaults for particular enchantment types. 'Knockback' for example, has a maximum level of Knockback II (2) so attempting anything higher will simply result in that maximum.If however, you choose to enable 'unsafe-enchantments' you will be able to ignore these limits. Warning: Mixing and overleveling some enchantments can cause issues with clients, servers and plugins.
Command syntax: /<command> <item|numeric> [amount [enchantment name:value...]] - amount is required.
For a list of available enchants equip the desired item in-hand and issue /enchant. It will present you with the available 'safe' options for that item.
Note: Multiple enchantments can be provided by separating the name:value with a space.
Examples
/i diamondpickaxe 1 efficiency:1 durability:1 fortune:1 /give Evonuts woodensword 1 fireaspect:2 /i ironsword 1 efficiency:1 looting:1 silktouch:1
Permissions
- essentials.enchantments.[enchantmentname]
Fireworks
| Colors | |
|---|---|
| white | |
| orange | |
| magenta | |
| light_blue | |
| yellow | |
| lime | |
| pink | |
| gray | |
| silver | |
| cyan | |
| purple | |
| blue | |
| brown | |
| green | |
| red | |
| black | |
|
| |
| Shapes | |
| large | |
| creeper | |
| star | |
| burst | |
|
| |
| Effects | |
| trail | |
| twinkle | |
Command syntax: /<command> <item|numeric> [amount [attribute:value...]] - amount is required.
Note: multiple, comma separated values, can be given for 'color' and 'effect' only.
Colour
The initial colour of the explosion. Multiple values can be separated with a comma.
color:<color>
color:white color:black,white,yellow
Shape
The resulting shape of the explosion, if not defined the default is 'small ball' which rarely produces an effect.
shape:large|creeper|star|burst
shape:star
Fade
Color(s) that the firework will change to shortly after the explosion.
fade:<color>
fade:red fade:red,white,lime
Effects
Effects to be applied to the explosion. Multiple values can be separated with a comma.
effect:trail|twinkle
effect:trail effect:trail,twinkle
Power
The flight duration of the rocket, this can also be set on held fireworks with /firework power [1-4]
power:<1-4>
power:4
Examples
/i firework 1 name:Angry_Creeper color:red fade:green type:creeper power:1 /i firework 1 name:StarryNight color:yellow,orange fade:blue type:star effect:trail,twinkle power:1
Console give playerName firework 2 name:SolarWind color:yellow,orange fade:red shape:large effect:twinkle color:yellow,orange fade:red shape:ball effect:trail color:red,purple fade:pink shape:star effect:trail power:1
Note: There is a limit of 100 characters for in-game chat.
Permissions
- essentials.itemspawn.meta-firework
- essentials.itemspawn.meta-firework-multiple
Books
Title
The book title, supports colour code formatting. If 'name:' is used here instead of 'title:' the book title will be italicised.
title:<title>
Author
The author of the book, supports colour code formatting.
author:<author>
Lore
A description for the book.
lore:<description>
Book
Creating custom books is possible by using the book.txt file in the Essentials plugin root folder. In this file you can create a named section or chapter which starts with #. These can then be used in item meta using book:<name of section>
Essentials comes with a example book, in /kit color, but can also be spawned using the example command below. In the example book.txt, the chapter 'Colors' can be spawned by using book:Colors.
See book example here.
book:<section name>
Examples
/i writtenbook 1 title:&4Book_&9o_&6Colors author:KHobbits lore:Ingame_color_codes book:Colors
Permissions
- essentials.itemspawn.meta-title
- essentials.itemspawn.meta-author
- essentials.itemspawn.meta-lore
- essentials.itemspawn.meta-book
- essentials.itemspawn.meta-chapter-[chapter]
Potions
Potion meta data takes 3 parameters, 'effect', 'power' and 'duration' or shorthands of 'e', 'p' and 'd' respectively. All 3 parameters are required and need to be in this order. For multiple potion effects repeat the series (see below for exmaples).
| Effect | |
|---|---|
| speed | |
| slowness | |
| haste | |
| fatigue | |
| strength | |
| heal | |
| harm | |
| jump | |
| nausea | |
| regeneration | |
| resistance | |
| fireresist | |
| waterbreath | |
| invisibility | |
| blindness | |
| nightvision | |
| hunger | |
| weakness | |
| poison | |
| wither | |
| healthboost | |
| absorption | |
| saturation | |
Effect
Any number of different potion effects can be simultaneously active on a player, even in the case of opposite potion effects such as Strength and Weakness. It is not possible to apply the same potion effect multiple times, however, even if the effects are of different levels (e.g. Strength and Strength II cannot both be active at the same time). In the event of using a potion that applies an effect already active on the player, the new version of the effect overwrites the old effect, giving a new level and full duration if the new effect is of equal or greater level. An attempt to use a potion that applies a weaker version of an already-active effect consumes the potion but does not apply the new effect.
effect:<potion effect>
effect:speed
Power
The power or level for the potion effect. This can also be a negative value which essentially inverts the effect. Jump becomes lower in height, heal actually causes damage, etc etc.
power:-127 to 128
power:2
Duration
Provided as seconds.
duration:<duration amount>
duration:120
Examples
/i potion 1 effect:speed power:2 duration:60 /i potion 3 effect:heal power:1 duration:240 effect:jump power:50 duration:30
Permissions
- essentials.potions.[potionname]
- essentials.potions.multiple
Leather Armor
Leather armor can be coloured by crafting dyes in with a piece of leather armor, alternatively they can be acquired using /give, /i commands or in Kits. Note, the syntax for colours varies slightly from that of Fireworks above as it is provided in comma separated RGB format (0-255).
color:<red>,<green>,<blue>
You can test out your colors by using http://www.colorschemer.com/online.html
color:226,29,34
Examples
/i leatherhelmet 1 name:A_Raspberry_Beret color:199,44,72 lore:The_kind_u_find|in_a_second_hand_store
Mob Heads
There are five variants of mob heads: Skeleton, Wither Skeleton, zombie, human and Creeper.
Head types
Provided as either an id with an integer 0-4 (eg. 397:2) or with the values below.
397:0-4 or skeletonhead|witherhead|zombiehead|humanhead|creeperhead
Player heads
For 397:3 or 'humanhead' above, an extra argument is provided for player/owner.
397:3 1 player:Notch
Examples
/i 397:1 1 /i witherhead 1 /i 397:3 1 player:Khobbits
Tool durability
It is also possible to spawn tools with a pre-defined durability level, that is to say how 'worn' the item in question is. Refer to the table below.
<itemid>:<durability level>
| Gold | 33 uses |
| Wood | 60 uses |
| Stone | 132 uses |
| Iron | 251 uses |
| Diamond | 1562 uses |
Examples
/i 279:780 1 /i goldpickaxe:32 1
