From 977f656e09c4b542e09ec210b202ba46eb45ac5e Mon Sep 17 00:00:00 2001 From: Wuzzy Date: Sat, 1 Oct 2022 21:20:28 +0200 Subject: [PATCH] Improve crafting recipe documentation (#12806) --- doc/lua_api.txt | 273 +++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 247 insertions(+), 26 deletions(-) diff --git a/doc/lua_api.txt b/doc/lua_api.txt index e253af30e..201f4d123 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -1831,7 +1831,24 @@ are effective towards. Groups in crafting recipes -------------------------- -An example: Make meat soup from any meat, any water and any bowl: +In crafting recipes, you can specify a group as an input item. +This means that any item in that group will be accepted as input. + +The basic syntax is: + + "group:" + +For example, `"group:meat"` will accept any item in the `meat` group. + +It is also possible to require an input item to be in +multiple groups at once. The syntax for that is: + + "group:,,(...)," + +For example, `"group:leaves,birch,trimmed"` accepts any item which is member +of *all* the groups `leaves` *and* `birch` *and* `trimmed`. + +An example recipe: Craft a raw meat soup from any meat, any water and any bowl: { output = "food:meat_soup_raw", @@ -1842,7 +1859,9 @@ An example: Make meat soup from any meat, any water and any bowl: }, } -Another example: Make red wool from white wool and red dye: +Another example: Craft red wool from white wool and red dye +(here, "red dye" is defined as any item which is member of +*both* the groups `dye` and `basecolor_red`). { type = "shapeless", @@ -8495,44 +8514,188 @@ Used by `minetest.register_node`. Crafting recipes ---------------- -Used by `minetest.register_craft`. +Crafting converts one or more inputs to one output itemstack of arbitrary +count (except for fuels, which don't have an output). The conversion reduces +each input ItemStack by 1. + +Craft recipes are registered by `minetest.register_craft` and use a +table format. The accepted parameters are listed below. + +Recipe input items can either be specified by item name (item count = 1) +or by group (see "Groups in crafting recipes" for details). + +The following sections describe the types and syntaxes of recipes. ### Shaped +This is the default recipe type (when no `type` is specified). + +A shaped recipe takes one or multiple items as input and has +a single item stack as output. The input items must be specified +in a 2-dimensional matrix (see parameters below) to specify the +exact arrangement (the "shape") in which the player must place them +in the crafting grid. + +For example, for a 3x3 recipe, the `recipes` table must have +3 rows and 3 columns. + +In order to craft the recipe, the players' crafting grid must +have equal or larger dimensions (both width and height). + +Parameters: + +* `type = "shaped"`: (optional) specifies recipe type as shaped +* `output`: Itemstring of output itemstack (item counts >= 1 are allowed) +* `recipe`: A 2-dimensional matrix of items, with a width *w* and height *h*. + * *w* and *h* are chosen by you, they don't have to be equal but must be at least 1 + * The matrix is specified as a table containing tables containing itemnames + * The inner tables are the rows. There must be *h* tables, specified from the top to the bottom row + * Values inside of the inner table are the columns. + Each inner table must contain a list of *w* items, specified from left to right + * Empty slots *must* be filled with the empty string +* `replacements`: (optional) Allows you to replace input items with some other items + when something is crafted + * Provided as a list of item pairs of the form `{ old_item, new_item }` where + `old_item` is the input item to replace (same syntax as for a regular input + slot; groups are allowed) and `new_item` is an itemstring for the item stack + it will become + * When the output is crafted, Minetest iterates through the list + of input items if the crafting grid. For each input item stack, it checks if + it matches with an `old_item` in the item pair list. + * If it matches, the item will be replaced. Also, this item pair + will *not* be applied again for the remaining items + * If it does not match, the item is consumed (reduced by 1) normally + * The `new_item` will appear in one of 3 places: + * Crafting grid, if the input stack size was exactly 1 + * Player inventory, if input stack size was larger + * Drops as item entity, if it fits neither in craft grid or inventory + +#### Examples + +A typical shaped recipe: + + -- Stone pickaxe { - output = "default:pick_stone", + output = "example:stone_pickaxe", + -- A 3x3 recipe which needs 3 stone in the 1st row, + -- and 1 stick in the horizontal middle in each of the 2nd and 3nd row. + -- The 4 remaining slots have to be empty. recipe = { - {"default:cobble", "default:cobble", "default:cobble"}, - {"", "default:stick", ""}, - {"", "default:stick", ""}, -- Also groups; e.g. "group:crumbly" + {"example:stone", "example:stone", "example:stone"}, -- row 1 + {"", "example:stick", "" }, -- row 2 + {"", "example:stick", "" }, -- row 3 + -- ^ column 1 ^ column 2 ^ column 3 + }, + -- There is no replacements table, so every input item + -- will be consumed. + } + +Simple replacement example: + + -- Wet sponge + { + output = "example:wet_sponge", + -- 1x2 recipe with a water bucket above a dry sponge + recipe = { + {"example:water_bucket"}, + {"example:dry_sponge"}, + }, + -- When the wet sponge is crafted, the water bucket + -- in the input slot is replaced with an empty + -- bucket + replacements = { + {"example:water_bucket", "example:empty_bucket"}, + }, + } + +Complex replacement example 1: + + -- Very wet sponge + { + output = "example:very_wet_sponge", + -- 3x3 recipe with a wet sponge in the center + -- and 4 water buckets around it + recipe = { + {"","example:water_bucket",""}, + {"example:water_bucket","example:wet_sponge","example:water_bucket"}, + {"","example:water_bucket",""}, + }, + -- When the wet sponge is crafted, all water buckets + -- in the input slot become empty + replacements = { + -- Without these repetitions, only the first + -- water bucket would be replaced. + {"example:water_bucket", "example:empty_bucket"}, + {"example:water_bucket", "example:empty_bucket"}, + {"example:water_bucket", "example:empty_bucket"}, + {"example:water_bucket", "example:empty_bucket"}, + }, + } + +Complex replacement example 2: + + -- Magic book: + -- 3 magic orbs + 1 book crafts a magic book, + -- and the orbs will be replaced with 3 different runes. + { + output = "example:magic_book", + -- 3x2 recipe + recipe = { + -- 3 items in the group `magic_orb` on top of a book in the middle + {"group:magic_orb", "group:magic_orb", "group:magic_orb"}, + {"", "example:book", ""}, + }, + -- When the book is crafted, the 3 magic orbs will be turned into + -- 3 runes: ice rune, earth rune and fire rune (from left to right) + replacements = { + {"group:magic_orb", "example:ice_rune"}, + {"group:magic_orb", "example:earth_rune"}, + {"group:magic_orb", "example:fire_rune"}, }, - replacements = , - -- replacements: replace one input item with another item on crafting - -- (optional). } ### Shapeless +Takes a list of input items (at least 1). The order or arrangement +of input items does not matter. + +In order to craft the recipe, the players' crafting grid must have matching or +larger *count* of slots. The grid dimensions do not matter. + +Parameters: + +* `type = "shapeless"`: Mandatory +* `output`: Same as for shaped recipe +* `recipe`: List of item names +* `replacements`: Same as for shaped recipe + +#### Example + { + -- Craft a mushroom stew from a bowl, a brown mushroom and a red mushroom + -- (no matter where in the input grid the items are placed) type = "shapeless", - output = "mushrooms:mushroom_stew", + output = "example:mushroom_stew", recipe = { - "mushrooms:bowl", - "mushrooms:mushroom_brown", - "mushrooms:mushroom_red", + "example:bowl", + "example:mushroom_brown", + "example:mushroom_red", }, - replacements = , } ### Tool repair +Syntax: + { type = "toolrepair", additional_wear = -0.02, -- multiplier of 65536 } Adds a shapeless recipe for *every* tool that doesn't have the `disable_repair=1` -group. Player can put 2 equal tools in the craft grid to get one "repaired" tool +group. If this recipe is used, repairing is possible with any crafting grid +with at least 2 slots. +The player can put 2 equal tools in the craft grid to get one "repaired" tool back. The wear of the output is determined by the wear of both tools, plus a 'repair bonus' given by `additional_wear`. To reduce the wear (i.e. 'repair'), @@ -8547,25 +8710,83 @@ no crafting is possible. ### Cooking +A cooking recipe has a single input item, a single output item stack +and a cooking time. It represents cooking/baking/smelting/etc. items in +an oven, furnace, or something similar; the exact meaning is up for games +to decide, if they choose to use cooking at all. + +The engine does not implement anything specific to cooking recipes, but +the recipes can be retrieved later using `minetest.get_craft_result` to +have a consistent interface across different games/mods. + +Parameters: + +* `type = "cooking"`: Mandatory +* `output`: Same as for shaped recipe +* `recipe`: An itemname of the single input item +* `cooktime`: (optional) Time it takes to cook this item, in seconds. + A floating-point number. (default: 3.0) +* `replacements`: Same meaning as for shaped recipes, but the mods + that utilize cooking recipes (e.g. for adding a furnace + node) need to implement replacements on their own + +Note: Games and mods are free to re-interpret the cooktime in special +cases, e.g. for a super furnace that cooks items twice as fast. + +#### Example + +Cooking sand to glass in 3 seconds: + { type = "cooking", - output = "default:glass", - recipe = "default:sand", - cooktime = 3, + output = "example:glass", + recipe = "example:sand", + cooktime = 3.0, } -### Furnace fuel +### Fuel + +A fuel recipe is an item associated with a "burning time" and an optional +item replacement. There is no output. This is usually used as fuel for +furnaces, ovens, stoves, etc. + +Like with cooking recipes, the engine does not do anything specific with +fuel recipes and it's up to games and mods to use them by retrieving +them via `minetest.get_craft_result`. + +Parameters: + +* `type = "fuel"`: Mandatory +* `recipe`: Itemname of the item to be used as fuel +* `burntime`: (optional) Burning time this item provides, in seconds. + A floating-point number. (default: 1.0) +* `replacements`: Same meaning as for shaped recipes, but the mods + that utilize fuels need to implement replacements + on their own + +Note: Games and mods are free to re-interpret the burntime in special +cases, e.g. for an efficient furnace in which fuels burn twice as +long. + +#### Examples + +Coal lump with a burntime of 20 seconds. Will be consumed when used. { type = "fuel", - recipe = "bucket:bucket_lava", - burntime = 60, - replacements = {{"bucket:bucket_lava", "bucket:bucket_empty"}}, + recipe = "example:coal_lump", + burntime = 20.0, } -The engine does not implement anything specific to cooking or fuels, but the -recpies can be retrieved later using `minetest.get_craft_result` to have a -consistent interface across different games/mods. +Lava bucket with a burn time of 60 seconds. Will become an empty bucket +if used: + + { + type = "fuel", + recipe = "example:lava_bucket", + burntime = 60.0, + replacements = {{"example:lava_bucket", "example:empty_bucket"}}, + } Ore definition --------------