Custom Item Data
KitMaster contains support for custom item data and metadata. Things like item names and lore, compound potions, written books, and fireworks all require additional data to be stored and loaded to be used in kits. In KitMaster, this data is defined in plugins/KitMaster/custom-data.yml.
Overview
When you first load a version of KitMaster at or above v1.3 (or if you delete the existing file), plugins/KitMaster/custom-data.yml will be automatically generated for you with a set of sample entries so that you can see how things are set up. A comment block at the top of the generated file contains some basic instructions and tips about configuring your data. I highly recommend that you do not remove this comment block. Leave it for reference. Custom data configuration can be finicky at times.
Book data, compound potion data, custom item data, and the separately stored firework effect data and firework data each have their own configuration sections: books, items, potions, bursts, and fireworks.
Within every configuration section, data sets are stored within subsections. The names of these subsections are what you use to access the item's data when loading it in an item within a kit. For custom items, the name of this section replaces the name of the item - i.e. to use the sample custom item "Personalized_Sword", you should use Personalized_Sword:1 as an item in a kit. For all other custom data sets, the configuration section's name is used as the tag - i.e. to use the sample compound potion "vodka", you should use Potion:Vodka:1 as an item in a kit.
Books
To load custom book data in an item in a kit, use the configuration section's name as the tag for either a Written_Book or a Book_and_Quill. Book data consists of three fields:
| title | The title of the book. It will have no effect if loaded on a Book and Quill. | |
|---|---|---|
| author | The author of the book (doesn't actually have to be the author). It will have no effect if loaded on a Book and Quill. | |
| pages | This is a list of lines, prefixed by a dash and space. Each line is the text for a single page of the book. To insert line breaks, enter a vertical slash followed by the lowercase letter 'n'. |
Because editing books in this manner can be cumbersome, and it is difficult to know how long to make each line/page, it can be preferable to use the commands /itemmeta savebook and /itemmeta loadbook to save and load written books to and from this file. The command /itemmeta editbook can be used as well, and works exactly the same as loadbook, except it will give you a book and quill which can be edited.
Items
To load custom items in an item in a kit, use the configuration section's name as the name of the item. Item data consists of three fields:
| item | The actual item that this custom item builds on, written exactly as it would be in the kit configuration. For example, if you were creating a customized diamond sword, this would be the string for the diamond sword: Diamond_Sword:1. | |
|---|---|---|
| name | The custom name that will be given to this item. If you don't want to apply a custom name, remove this field entirely. | |
| lore | The lore that will be given to this item. Each line corresponds to one line of lore in the item's tooltip. |
Item names and lore can both include color codes prefixed by an ampersand (&), and can also include the %player% macro, which will be replaced automatically with the name of whoever is being given the kit.
In addition to editing in the configurations, the /itemmeta command has several subcommands for editing names and lore. Use /itemmeta setname to set the name of the item. Use /itemmeta addlore and /itemmeta removelore to add and remove lore. Finally, use /itemmeta saveitem and /itemmeta loaditem to save and load custom items to and from this file.
Potions
To load custom potions in an item in a kit, use the configuration section's name as a tag for a Potion. Potion data consists of a collection of sub-units, which define the individual effects that this potion will produce. Each effect's section contains three fields:
| type | The type of potion effect that will be imparted (regeneration, slowness, fire_resistance, etc.). | |
|---|---|---|
| duration | How long this effect will last, in game ticks. One second is equal to 20 game ticks. | |
| amplifier | How powerful this effect will be. |
Any number of these effects can be put on a single custom potion, and the names of the configuration sections do not matter so long as they are different.
Bursts
Bursts are the individual elements of fireworks that carry information about color, effects, and shape. They are not applied to individual items in kits, but are used in the definition of fireworks. Burst data consists of 5 fields:
| type | This is the shape of the burst, and can be either ball, ball_large, burst, star, or creeper. | |
|---|---|---|
| flicker | True or false whether this burst should have a flicker/crackle effect. | |
| trail | True or false whether the "sparks" from this burst should leave a trail as they fly outwards. | |
| primary-colors | This is a list of the initial colors of the burst, in hexadecimal notation (prefixed by 0x) in RRGGBB format. | |
| secondary-colors | This is a list of the colors this burst will fade to, in the same form as the primary colors. |
Because bursts are complicated to configure what with the hexadecimal colors and such, it is usually preferable to create fireworks in-game, and save their custom data to this file by using the command /itemmeta savefirework, which will save both the firework's data and each of its bursts individually. You can also load fireworks back up from this file manually by using /itemmeta loadfirework.
Fireworks
Fireworks are the actual items that can be used, and incorporate multiple bursts to give them their colors. To load fireworks as items in a kit, use the configuration section's name as a tag for a Firework. Firework data consists of only two fields:
| fuse | The fuse length of the firework, which directly corresponds to the altitude at which it will explode. Values over 5 are not recommended. | |
|---|---|---|
| bursts | The names of all the bursts that will be contained in this firework, as they were defined in the bursts section. Any number of these can be included, and multiple different fireworks can use the same burst. |