minetest
/
minetest
mirror of https://github.com/minetest/minetest.git
1
0
Fork 0
Code Issues Releases Wiki Activity

Improve crafting recipe documentation (#12806)

This commit is contained in:
Wuzzy 2022-10-01 21:20:28 +02:00 committed by GitHub
parent 525fc3833c
commit 977f656e09
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 247 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

273
doc/lua_api.txt
View File

@ -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:<group_name>"
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:<group_name_1>,<group_name_2>,(...),<group_name_n>"
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 = <list of item pairs>,
-- 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 = <list of item pairs>,
}
### 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
--------------