Bukkit

The basic format of recipes is very simple. You have a type, the input, and then the result. The result is the same for all recipe types, but the input varies. The format is not case-sensitive, and underscores are generally interchangeable with hyphens. Anything after a \ (backslash) is ignored as a comment. (Prior to version 1.2, the comment character was #, but that has been changed due to the same character being used to represent hex colours.)

NOTE: The examples on this page are /not/ guaranteed to work exactly as shown. They are certainly formatted correctly, but there is a possibility that incorrect item names have been used.

Splitting the recipe file up

If your recipes file starts to get very large, you might find it useful to split it into several smaller files. Cookbook can handle this! In your main recipe file, just add an include directive like so:

@Include more-recipes.cb

When Cookbook sees that, it'll load up the more-recipes.cb file in the same directory and apply any recipes it finds in that file! You can add include directives in any file, not just the main recipe file. Cookbook is smart enough to notice if you accidentally create a loop.

Shaped Recipes

This is your standard Minecraft type of recipe, where the relative placement of the ingredients is important. Note that Minecraft allows you to flip the recipe horizontally, so keep this in mind when creating asymmetric recipes.

A shaped recipe starts with the "@Shaped" directive, which can be followed by a name for the recipe. This name is not use at the moment, but will eventually allow you to set permissions for the recipe.

After the @Shaped directive, you can have one to three lines of ingredients, each line containing one to three ingredients. The ingredients on a line are separated by whitespace; spaces and tabs are both fine. For the format of the individual ingredients, see the Ingredients section below.

After the ingredients, you specify the result; see the Result section for more info on how to do this.

Example:

@Shaped
dirt dirt
0 3
-> 2x IRON_INGOT

Shapeless Recipes

This is a mixing recipe, where you can put the ingredients in any order on the crafting grid.

A shapeless recipe begins with the "@Shapeless" directive, which can be followed by a name for the recipe. This name is not use at the moment, but will eventually allow you to set permissions for the recipe.

After the @Shapeless directive, you can have up to nine ingredients separated by commas. Whitespace is ignored. For the format of the individual ingredients, see the Ingredients section below.

After the ingredients, you specify the result; see the Result section for more info on how to do this.

Example:

@Shapeless
Apple, Bowl
-> 1x Water-bucket

Smelting Recipes

This is a recipe for something that can be cooked in the furnace. You cannot specify the fuel. In addition, furnace input cannot depend on data values, and furnace output strips all metadata (except the simple data values like dye colour). Both of these are Bukkit/Minecraft limitations that I can't do much about.

A smelting recipe begins with the "@Smelt" directive, which can be followed by a name for the recipe. This name is not use at the moment, but will eventually allow you to set permissions for the recipe.

The input is a single ingredient. For the format of the ingredient, see the Ingredients section below.

After the ingredients, you specify the result; see the Result section for more info on how to do this. For furnace recipes, the result goes on the same line as the input.

Example:

@Smelt
Dirt -> 3x Wheat

Ingredients

The format of an ingredient is very simple. Simply use the item ID or the Bukkit name of the item. If you need to specify a durability or data value, add a slash followed by the appropriate number. Named data values (for example, the names of colours) are not supported. If you specify a data value of -1, then the data value will be ignored and the recipe will work for any data value. If you don't specify a data value, it's assumed to be zero.

A list of Bukkit's item names can be found here. It's recommended to start searching from the bottom of the list, as some items may seem to appear twice, and in most cases you want the last of them.

For the data values of potions, look here. Using these data values will ensure that brewed potions will work in your recipe. Although other data values may give the same potion, they will not match any brewed potions.

Starting in version 1.2, you can use named datavalues to make the recipe files more readable. See Item Variants for a list of currently supported names. I'll do my best to keep this list updated.

Result

The result of a recipe is introduced by the "->" indicator, followed by the stack size and the item name, using the same format as used for ingredients. The stack size may be followed by the letter 'x'; including this is just a matter of preference. If you're getting errors on the result line, the first thing you should check for is whether you forgot the stack size; a stack size of 1 is /not/ implicitly assumed.

After the item name, various metadata keys may be specified. Some metadata is instead specified on separate lines following the main result line. Unless otherwise specified, all metadata information described below must appear on the same line as the item name, separated from it and from each other by whitespace.

Enchantments

An enchantment key is of the form <enchantment-name>=<level>. For the names of enchantments, see here.

Example:

@Shapeless
iron-spade, nether_wart
-> 1x iron-spade loot-bonus-blocks=7

Custom Potions

A custom potion effect key is of the form <effect-name>=<level>, or <effect-name>=<level>,<duration>. The duration is specified in seconds and defaults to 80. For the names of potion effects, see here.

Example:

@Shapeless
potion/0, nether-wart
-> 1x potion/8198 water-breathing=3,120

Armour Colour

You can specify the colour of leather armour using a key of the form colour=<named-colour> or colour=#<six-digit hexadecimal colour>. (If you prefer America spellings, you can use color= instead of colour=.) For a list of named colours, see here. There is also a second set of named colours available using the names here with the suffix "_DYE" (or "-dye"). These name the colours of in-game dyes.

If you specify this for an item that is not leather armour (ie, one of LEATHER_CHESTPLATE, LEATHER_HELMET, LEATHER_LEGGINGS, or LEATHER_BOOTS), it is ignored without warning.

Example:

@Shapeless
leather-boots, nether-wart
-> 1x leather-boots color=#ff8c00

Books

For WRITTEN_BOOK, you can specify the title and author of the book using the keys title=<title> and author=<author>. Both the title and author accept chat formatting codes using either the section character (§) or the ampersand (&). Furthermore, underscores are translated to spaces. For info on the chat formatting codes, see here.

You can also specify the contents of a book for WRITTEN_BOOK and also for BOOK_AND_QUILL. This is done on lines following the main result line. There are three types of lines used to specify the contents of a book:

• A line beginning with % begins a new page in a book.
• A line beginning with | begins a new line on the current page. You should not specify this before starting a first page, but if you do, Cookbook will handle it intelligently and automatically start the new page for you.
• A line beginning with ~ continues the current line on the current page. It automatically inserts a space for you. You should not specify this before starting a first page, but if you do, Cookbook will handle it intelligently and automatically start the new page for you.

Keep in mind that Minecraft cannot handle pages longer than 256 characters total. The chat formatting codes work in book pages as well, in the same way as for title and author. However, underscores are not translated.

Example:

@Shapeless
book, nether-wart
-> 1x written-book title=About_Magical_Herbs author=Some_guy
%Nether wart is useful!
~It can be used for brewing potions!
|For example, it is used for Regeneration Potion.

Player Heads

You can specify player heads for SKULL_ITEM using a key of the form owner=<player-name>. The player name is case sensitive.

Example:

@Shapeless
skull-item, cookie
-> 1x skull-item owner=Celmin

Fireworks

Both FIREWORK (the actual rocket) and FIREWORK_CHARGE (the firework star) can accept keys of the form <effect-type>=<colour-list>;<fade-colour-list>. This is quite a complex key. FIREWORK_CHARGE can only have one instance of it, but FIREWORK can have several.

The effect type is a comma-separated list of one to three items, where the first item is one of the main effect names (see here for a list), and additional items are one of TWINKLE or TRAIL, representing secondary effects.

The two lists of colours are both comma separated, and in every other way work exactly the same as armour colours, above. You can have any number of primary colours and any number of fade colours. However, if you use colours other than the <colour>_DYE format, they will simply be displayed by Minecraft as "Custom".

On FIREWORK items, you can also add a power=<flight-power> key to specify how high the rocket will fly.

Example:

@Shapeless
gunpower, nether-wart
-> 1x firework power=3 star,twinkle=red,green;blue,teal creeper,trail=green;yellow

Lore

You can specify a custom item name using a key of the form name=<new-name>. This supports chat formatting codes using either the section character (§) or the ampersand (&), and also translates underscores to spaces. For info on the chat formatting codes, see here.

You can specify arbitrary additional lore for the item on lines following the main result line. Any line beginning with $ is added to the item's lore. The chat formatting codes work in lore as well, in the same way as for names. However, underscores are not translated.

Example:

@Shapeless
leather-helmet, nether-wart
-> 1x leather-helmet
$Something seems strange about this helmet!