~fgaz/minetest-lls-definitions

8213c6e4f144c22060a5198374e1ad00e187b843 — Francesco Gazzetta 5 months ago 3d6c48e 
lua_api.txt -> lua_api.md

Update it to d197ff0f9dc55c165cfd7e84a41e2c0891c85111, which reformats
the file.
patch browse .tar.gz 
3 files changed, 2387 insertions(+), 2224 deletions(-)

M README.md
M gen.tcl
R lua_api.txt => lua_api.md

M README.md => README.md +3 -3
@@ 7,20 7,20 @@ https://github.com/LuaLS/lua-language-server/wiki/Addons
## Contributing

1. Edit files in `templates/`. Write only types, not documentation strings.
2. Regenerate `library/` with `./gen.tcl`. This will add documentation strings from `lua_api.txt`.
2. Regenerate `library/` with `./gen.tcl`. This will add documentation strings from `lua_api.md`.
3. Check for errors with `lua-language-server --check library`.
4. [Send a patch](https://git-send-email.io) to [this mailing list](https://lists.sr.ht/~fgaz/public-inbox) or a [pull request](https://docs.codeberg.org/collaborating/pull-requests-and-git-flow/) to [the Codeberg mirror](https://codeberg.org/fgaz/minetest-lls-definitions).

A few rules:

* When adding a new function, class, or table definition, please specify it fully. No `any`.
* Follow the order and sections from `lua_api.txt`.
* Follow the order and sections from `lua_api.md`.
* Everything should be namespaced, including classes and table definitions.
* Use `@nodiscard` where applicable.

### Targeting a new API version

1. Download the new `lua_api.txt`.
1. Download the new `lua_api.md`.
2. Check for new functions and updated signatures with `git diff` and apply the changes to `templates`.
   Ignore updated docs, those will be regenerated in the next step.
3. Regenerate `library` with `./gen.tcl`.


M gen.tcl => gen.tcl +4 -4
@@ 3,11 3,11 @@
# function name => doc comments string
set fun_dict [dict create]

# Collect documentation strings from lua_api.txt
# Collect documentation strings from lua_api.md
set is_fun 0
set fun_name ""
set txt [open "lua_api.txt"]
while {[gets $txt line] >= 0} {
set md [open "lua_api.md"]
while {[gets $md line] >= 0} {
  if {[regexp {^    (.*)} $line _ docline]} then {
    if {$is_fun} then {dict append fun_dict $fun_name "\n--- $docline"}
  } else {


@@ 15,7 15,7 @@ while {[gets $txt line] >= 0} {
    if {$is_fun} then {dict set fun_dict $fun_name [list]}
  }
}
close $txt
close $md

# Generate documented library/*.lua from templates/*.lua
foreach file [glob "templates/*.lua"] {


R lua_api.txt => lua_api.md +2380 -2217
@@ 794,32 794,36 @@ To transfer the color to a special drop, you need a drop table.

Example:

    minetest.register_node("mod:stone", {
        description = "Stone",
        tiles = {"default_stone.png"},
        paramtype2 = "color",
        palette = "palette.png",
        drop = {
            items = {
                -- assume that mod:cobblestone also has the same palette
                {items = {"mod:cobblestone"}, inherit_color = true },
            }
```lua
minetest.register_node("mod:stone", {
    description = "Stone",
    tiles = {"default_stone.png"},
    paramtype2 = "color",
    palette = "palette.png",
    drop = {
        items = {
            -- assume that mod:cobblestone also has the same palette
            {items = {"mod:cobblestone"}, inherit_color = true },
        }
    })
    }
})
```

### Colored items in craft recipes

Craft recipes only support item strings, but fortunately item strings
can also contain metadata. Example craft recipe registration:

    minetest.register_craft({
        output = minetest.itemstring_with_palette("wool:block", 3),
        type = "shapeless",
        recipe = {
            "wool:block",
            "dye:red",
        },
    })
```lua
minetest.register_craft({
    output = minetest.itemstring_with_palette("wool:block", 3),
    type = "shapeless",
    recipe = {
        "wool:block",
        "dye:red",
    },
})
```

To set the `color` field, you can use `minetest.itemstring_with_color`.



@@ 852,23 856,24 @@ To skip one face, set that overlay tile to an empty string.

Example (colored grass block):

    minetest.register_node("default:dirt_with_grass", {
        description = "Dirt with Grass",
        -- Regular tiles, as usual
        -- The dirt tile disables palette coloring
        tiles = {{name = "default_grass.png"},
            {name = "default_dirt.png", color = "white"}},
        -- Overlay tiles: define them in the same style
        -- The top and bottom tile does not have overlay
        overlay_tiles = {"", "",
            {name = "default_grass_side.png"}},
        -- Global color, used in inventory
        color = "green",
        -- Palette in the world
        paramtype2 = "color",
        palette = "default_foilage.png",
    })

```lua
minetest.register_node("default:dirt_with_grass", {
    description = "Dirt with Grass",
    -- Regular tiles, as usual
    -- The dirt tile disables palette coloring
    tiles = {{name = "default_grass.png"},
        {name = "default_dirt.png", color = "white"}},
    -- Overlay tiles: define them in the same style
    -- The top and bottom tile does not have overlay
    overlay_tiles = {"", "",
        {name = "default_grass_side.png"}},
    -- Global color, used in inventory
    color = "green",
    -- Palette in the world
    paramtype2 = "color",
    palette = "default_foilage.png",
})
```





@@ 900,44 905,46 @@ from the available ones of the following files:

Examples of sound parameter tables:

    -- Play locationless on all clients
    {
        gain = 1.0,   -- default
        fade = 0.0,   -- default, change to a value > 0 to fade the sound in
        pitch = 1.0,  -- default
    }
    -- Play locationless to one player
    {
        to_player = name,
        gain = 1.0,   -- default
        fade = 0.0,   -- default, change to a value > 0 to fade the sound in
        pitch = 1.0,  -- default
    }
    -- Play locationless to one player, looped
    {
        to_player = name,
        gain = 1.0,  -- default
        loop = true,
    }
    -- Play at a location
    {
        pos = {x = 1, y = 2, z = 3},
        gain = 1.0,  -- default
        max_hear_distance = 32,  -- default, uses a Euclidean metric
    }
    -- Play connected to an object, looped
    {
        object = <an ObjectRef>,
        gain = 1.0,  -- default
        max_hear_distance = 32,  -- default, uses a Euclidean metric
        loop = true,
    }
    -- Play at a location, heard by anyone *but* the given player
    {
        pos = {x = 32, y = 0, z = 100},
        max_hear_distance = 40,
        exclude_player = name,
    }
```lua
-- Play locationless on all clients
{
    gain = 1.0,   -- default
    fade = 0.0,   -- default, change to a value > 0 to fade the sound in
    pitch = 1.0,  -- default
}
-- Play locationless to one player
{
    to_player = name,
    gain = 1.0,   -- default
    fade = 0.0,   -- default, change to a value > 0 to fade the sound in
    pitch = 1.0,  -- default
}
-- Play locationless to one player, looped
{
    to_player = name,
    gain = 1.0,  -- default
    loop = true,
}
-- Play at a location
{
    pos = {x = 1, y = 2, z = 3},
    gain = 1.0,  -- default
    max_hear_distance = 32,  -- default, uses a Euclidean metric
}
-- Play connected to an object, looped
{
    object = <an ObjectRef>,
    gain = 1.0,  -- default
    max_hear_distance = 32,  -- default, uses a Euclidean metric
    loop = true,
}
-- Play at a location, heard by anyone *but* the given player
{
    pos = {x = 32, y = 0, z = 100},
    max_hear_distance = 40,
    exclude_player = name,
}
```

Looped sounds must either be connected to an object or played locationless to
one player using `to_player = name`.


@@ 1003,9 1010,10 @@ All nodes registered with `minetest.register_node` get added to the table

If you want to check the drawtype of a node, you could do it like this:

    local def = minetest.registered_nodes[nodename]
    local drawtype = def and def.drawtype

```lua
local def = minetest.registered_nodes[nodename]
local drawtype = def and def.drawtype
```





@@ 1018,14 1026,18 @@ are quite static.

The definition of a node is stored and can be accessed by using

    minetest.registered_nodes[node.name]
```lua
minetest.registered_nodes[node.name]
```

See [Registered definitions].

Nodes are passed by value between Lua and the engine.
They are represented by a table:

    {name="name", param1=num, param2=num}
```lua
{name="name", param1=num, param2=num}
```

`param1` and `param2` are 8-bit integers ranging from 0 to 255. The engine uses
them for certain automated functions. If you don't use these functions, you can


@@ 1301,63 1313,69 @@ Node selection boxes are defined using "node boxes".

A nodebox is defined as any of:

    {
        -- A normal cube; the default in most things
        type = "regular"
    }
    {
        -- A fixed box (or boxes) (facedir param2 is used, if applicable)
        type = "fixed",
        fixed = box OR {box1, box2, ...}
    }
    {
        -- A variable height box (or boxes) with the top face position defined
        -- by the node parameter 'leveled = ', or if 'paramtype2 == "leveled"'
        -- by param2.
        -- Other faces are defined by 'fixed = {}' as with 'type = "fixed"'.
        type = "leveled",
        fixed = box OR {box1, box2, ...}
    }
    {
        -- A box like the selection box for torches
        -- (wallmounted param2 is used, if applicable)
        type = "wallmounted",
        wall_top = box,
        wall_bottom = box,
        wall_side = box
    }
    {
        -- A node that has optional boxes depending on neighboring nodes'
        -- presence and type. See also `connects_to`.
        type = "connected",
        fixed = box OR {box1, box2, ...}
        connect_top = box OR {box1, box2, ...}
        connect_bottom = box OR {box1, box2, ...}
        connect_front = box OR {box1, box2, ...}
        connect_left = box OR {box1, box2, ...}
        connect_back = box OR {box1, box2, ...}
        connect_right = box OR {box1, box2, ...}
        -- The following `disconnected_*` boxes are the opposites of the
        -- `connect_*` ones above, i.e. when a node has no suitable neighbor
        -- on the respective side, the corresponding disconnected box is drawn.
        disconnected_top = box OR {box1, box2, ...}
        disconnected_bottom = box OR {box1, box2, ...}
        disconnected_front = box OR {box1, box2, ...}
        disconnected_left = box OR {box1, box2, ...}
        disconnected_back = box OR {box1, box2, ...}
        disconnected_right = box OR {box1, box2, ...}
        disconnected = box OR {box1, box2, ...} -- when there is *no* neighbor
        disconnected_sides = box OR {box1, box2, ...} -- when there are *no*
                                                      -- neighbors to the sides
    }
```lua
{
    -- A normal cube; the default in most things
    type = "regular"
}
{
    -- A fixed box (or boxes) (facedir param2 is used, if applicable)
    type = "fixed",
    fixed = box OR {box1, box2, ...}
}
{
    -- A variable height box (or boxes) with the top face position defined
    -- by the node parameter 'leveled = ', or if 'paramtype2 == "leveled"'
    -- by param2.
    -- Other faces are defined by 'fixed = {}' as with 'type = "fixed"'.
    type = "leveled",
    fixed = box OR {box1, box2, ...}
}
{
    -- A box like the selection box for torches
    -- (wallmounted param2 is used, if applicable)
    type = "wallmounted",
    wall_top = box,
    wall_bottom = box,
    wall_side = box
}
{
    -- A node that has optional boxes depending on neighboring nodes'
    -- presence and type. See also `connects_to`.
    type = "connected",
    fixed = box OR {box1, box2, ...}
    connect_top = box OR {box1, box2, ...}
    connect_bottom = box OR {box1, box2, ...}
    connect_front = box OR {box1, box2, ...}
    connect_left = box OR {box1, box2, ...}
    connect_back = box OR {box1, box2, ...}
    connect_right = box OR {box1, box2, ...}
    -- The following `disconnected_*` boxes are the opposites of the
    -- `connect_*` ones above, i.e. when a node has no suitable neighbor
    -- on the respective side, the corresponding disconnected box is drawn.
    disconnected_top = box OR {box1, box2, ...}
    disconnected_bottom = box OR {box1, box2, ...}
    disconnected_front = box OR {box1, box2, ...}
    disconnected_left = box OR {box1, box2, ...}
    disconnected_back = box OR {box1, box2, ...}
    disconnected_right = box OR {box1, box2, ...}
    disconnected = box OR {box1, box2, ...} -- when there is *no* neighbor
    disconnected_sides = box OR {box1, box2, ...} -- when there are *no*
                                                  -- neighbors to the sides
}
```

A `box` is defined as:

    {x1, y1, z1, x2, y2, z2}
```lua
{x1, y1, z1, x2, y2, z2}
```

A box of a regular node would look like:

    {-0.5, -0.5, -0.5, 0.5, 0.5, 0.5},
```lua
{-0.5, -0.5, -0.5, 0.5, 0.5, 0.5},
```

To avoid collision issues, keep each value within the range of +/- 1.45.
This also applies to leveled nodeboxes, where the final height shall not


@@ 1589,7 1607,9 @@ Representations of simple things
Vector (ie. a position)
-----------------------

    vector.new(x, y, z)
```lua
vector.new(x, y, z)
```

See [Spatial Vectors] for details.



@@ 1637,19 1657,27 @@ is present, mapped to a boolean of any value, the specified flag is unset.

E.g. A flag field of value

    {place_center_x = true, place_center_y=false, place_center_z=true}
```lua
{place_center_x = true, place_center_y=false, place_center_z=true}
```

is equivalent to

    {place_center_x = true, noplace_center_y=true, place_center_z=true}
```lua
{place_center_x = true, noplace_center_y=true, place_center_z=true}
```

which is equivalent to

    "place_center_x, noplace_center_y, place_center_z"
```lua
"place_center_x, noplace_center_y, place_center_z"
```

or even

    "place_center_x, place_center_z"
```lua
"place_center_x, place_center_z"
```

since, by default, no schematic attributes are set.



@@ 1760,15 1788,21 @@ Examples:

5 dirt nodes:

    {name="default:dirt", count=5, wear=0, metadata=""}
```lua
{name="default:dirt", count=5, wear=0, metadata=""}
```

A wooden pick about 1/3 worn out:

    {name="default:pick_wood", count=1, wear=21323, metadata=""}
```lua
{name="default:pick_wood", count=1, wear=21323, metadata=""}
```

An apple:

    {name="default:apple", count=1, wear=0, metadata=""}
```lua
{name="default:apple", count=1, wear=0, metadata=""}
```

### `ItemStack`



@@ 1793,11 1827,13 @@ Groups are stored in a table, having the group names with keys and the
group ratings as values. Group ratings are integer values within the
range [-32767, 32767]. For example:

    -- Default dirt
    groups = {crumbly=3, soil=1}
```lua
-- Default dirt
groups = {crumbly=3, soil=1}

    -- A more special dirt-kind of thing
    groups = {crumbly=2, soil=1, level=2, outerspace=1}
-- A more special dirt-kind of thing
groups = {crumbly=2, soil=1, level=2, outerspace=1}
```

Groups always have a rating associated with them. If there is no
useful meaning for a rating for an enabled group, it shall be `1`.


@@ 1807,7 1843,9 @@ read groups, you must interpret `nil` and `0` as the same value, `0`.

You can read the rating of a group for an item or a node by using

    minetest.get_item_group(itemname, groupname)
```lua
minetest.get_item_group(itemname, groupname)
```

Groups of items
---------------


@@ 1827,8 1865,10 @@ For entities, groups are, as of now, used only for calculating damage.
The rating is the percentage of damage caused by items with this damage group.
See [Entity damage mechanism].

    object:get_armor_groups() --> a group-rating table (e.g. {fleshy=100})
    object:set_armor_groups({fleshy=30, cracky=80})
```lua
object:get_armor_groups() --> a group-rating table (e.g. {fleshy=100})
object:set_armor_groups({fleshy=30, cracky=80})
```

Groups of tool capabilities
---------------------------


@@ 1844,38 1884,46 @@ This means that any item in that group will be accepted as input.

The basic syntax is:

    "group:<group_name>"
```lua
"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>"
```lua
"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",
        recipe = {
            {"group:meat"},
            {"group:water"},
            {"group:bowl"},
        },
    }
```lua
{
    output = "food:meat_soup_raw",
    recipe = {
        {"group:meat"},
        {"group:water"},
        {"group:bowl"},
    },
}
```

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",
        output = "wool:red",
        recipe = {"wool:white", "group:dye,basecolor_red"},
    }
```lua
{
    type = "shapeless",
    output = "wool:red",
    recipe = {"wool:white", "group:dye,basecolor_red"},
}
```

Special groups
--------------


@@ 2103,11 2151,13 @@ For non-tools, this has no effect.
Example definition of the capabilities of an item
-------------------------------------------------

    tool_capabilities = {
        groupcaps={
            crumbly={maxlevel=2, uses=20, times={[1]=1.60, [2]=1.20, [3]=0.80}}
        },
    }
```lua
tool_capabilities = {
    groupcaps={
        crumbly={maxlevel=2, uses=20, times={[1]=1.60, [2]=1.20, [3]=0.80}}
    },
}
```

This makes the item capable of digging nodes that fulfill both of these:



@@ 2168,8 2218,10 @@ a non-tool item, so that it can do something else than take damage.

On the Lua side, every punch calls:

    entity:on_punch(puncher, time_from_last_punch, tool_capabilities, direction,
                    damage)
```lua
entity:on_punch(puncher, time_from_last_punch, tool_capabilities, direction,
                damage)
```

This should never be called directly, because damage is usually not handled by
the entity itself.


@@ 2186,7 2238,9 @@ Return value of this function will determine if damage is done by this function

To punch an entity/object in Lua, call:

  object:punch(puncher, time_from_last_punch, tool_capabilities, direction)
```lua
object:punch(puncher, time_from_last_punch, tool_capabilities, direction)
```

* Return value is tool wear.
* Parameters are equal to the above callback.


@@ 2222,41 2276,43 @@ Some of the values in the key-value store are handled specially:

Example:

    local meta = minetest.get_meta(pos)

    -- Set node formspec and infotext
    meta:set_string("formspec",
            "size[8,9]"..
            "list[context;main;0,0;8,4;]"..
            "list[current_player;main;0,5;8,4;]")
    meta:set_string("infotext", "Chest");

    -- Set inventory list size of `"main"` list to 32
    local inv = meta:get_inventory()
    inv:set_size("main", 32)

    -- Dump node metadata
    print(dump(meta:to_table()))

    -- Set node metadata from a metadata table
    meta:from_table({
        inventory = {
            -- Set items of inventory in all 32 slots of the `"main"` list
            main = {[1] = "default:dirt", [2] = "", [3] = "", [4] = "",
                    [5] = "", [6] = "", [7] = "", [8] = "", [9] = "",
                    [10] = "", [11] = "", [12] = "", [13] = "",
                    [14] = "default:cobble", [15] = "", [16] = "", [17] = "",
                    [18] = "", [19] = "", [20] = "default:cobble", [21] = "",
                    [22] = "", [23] = "", [24] = "", [25] = "", [26] = "",
                    [27] = "", [28] = "", [29] = "", [30] = "", [31] = "",
                    [32] = ""}
        },
        -- metadata fields
        fields = {
            formspec = "size[8,9]list[context;main;0,0;8,4;]list[current_player;main;0,5;8,4;]",
            infotext = "Chest"
        }
    })
```lua
local meta = minetest.get_meta(pos)

-- Set node formspec and infotext
meta:set_string("formspec",
        "size[8,9]"..
        "list[context;main;0,0;8,4;]"..
        "list[current_player;main;0,5;8,4;]")
meta:set_string("infotext", "Chest");

-- Set inventory list size of `"main"` list to 32
local inv = meta:get_inventory()
inv:set_size("main", 32)

-- Dump node metadata
print(dump(meta:to_table()))

-- Set node metadata from a metadata table
meta:from_table({
    inventory = {
        -- Set items of inventory in all 32 slots of the `"main"` list
        main = {[1] = "default:dirt", [2] = "", [3] = "", [4] = "",
                [5] = "", [6] = "", [7] = "", [8] = "", [9] = "",
                [10] = "", [11] = "", [12] = "", [13] = "",
                [14] = "default:cobble", [15] = "", [16] = "", [17] = "",
                [18] = "", [19] = "", [20] = "default:cobble", [21] = "",
                [22] = "", [23] = "", [24] = "", [25] = "", [26] = "",
                [27] = "", [28] = "", [29] = "", [30] = "", [31] = "",
                [32] = ""}
    },
    -- metadata fields
    fields = {
        formspec = "size[8,9]list[context;main;0,0;8,4;]list[current_player;main;0,5;8,4;]",
        infotext = "Chest"
    }
})
```

Item Metadata
-------------


@@ 2271,6 2327,11 @@ Some of the values in the key-value store are handled specially:
  See also: `get_description` in [`ItemStack`]
* `short_description`: Set the item stack's short description.
  See also: `get_short_description` in [`ItemStack`]
* `inventory_image`: Override inventory_image
* `inventory_overlay`: Override inventory_overlay
* `wield_image`: Override wield_image
* `wield_overlay`: Override wield_overlay
* `wield_scale`: Override wield_scale, use vector.to_string
* `color`: A `ColorString`, which sets the stack's color.
* `palette_index`: If the item has a palette, this is used to get the
  current color from the palette.


@@ 2284,26 2345,29 @@ Some of the values in the key-value store are handled specially:

Example:

    local meta = stack:get_meta()
    meta:set_string("key", "value")
    print(dump(meta:to_table()))
```lua
local meta = stack:get_meta()
meta:set_string("key", "value")
print(dump(meta:to_table()))
```

Example manipulations of "description" and expected output behaviors:

    print(ItemStack("default:pick_steel"):get_description()) --> Steel Pickaxe
    print(ItemStack("foobar"):get_description()) --> Unknown Item
```lua
print(ItemStack("default:pick_steel"):get_description()) --> Steel Pickaxe
print(ItemStack("foobar"):get_description()) --> Unknown Item

    local stack = ItemStack("default:stone")
    stack:get_meta():set_string("description", "Custom description\nAnother line")
    print(stack:get_description()) --> Custom description\nAnother line
    print(stack:get_short_description()) --> Custom description
local stack = ItemStack("default:stone")
stack:get_meta():set_string("description", "Custom description\nAnother line")
print(stack:get_description()) --> Custom description\nAnother line
print(stack:get_short_description()) --> Custom description

    stack:get_meta():set_string("short_description", "Short")
    print(stack:get_description()) --> Custom description\nAnother line
    print(stack:get_short_description()) --> Short

    print(ItemStack("mod:item_with_no_desc"):get_description()) --> mod:item_with_no_desc
stack:get_meta():set_string("short_description", "Short")
print(stack:get_description()) --> Custom description\nAnother line
print(stack:get_short_description()) --> Short

print(ItemStack("mod:item_with_no_desc"):get_description()) --> mod:item_with_no_desc
```


Formspec


@@ 3760,8 3824,10 @@ Two functions are provided to translate strings: `minetest.translate` and
  It is intended to be used in the following way, so that it avoids verbose
  repetitions of `minetest.translate`:

      local S = minetest.get_translator(textdomain)
      S(str, ...)
  ```lua
  local S = minetest.get_translator(textdomain)
  S(str, ...)
  ```

  As an extra commodity, if `textdomain` is nil, it is assumed to be "" instead.



@@ 3780,8 3846,10 @@ Two functions are provided to translate strings: `minetest.translate` and
  For instance, suppose we want to translate "@1 Wool" with "@1" being replaced
  by the translation of "Red". We can do the following:

      local S = minetest.get_translator()
      S("@1 Wool", S("Red"))
  ```lua
  local S = minetest.get_translator()
  S("@1 Wool", S("Red"))
  ```

  This will be displayed as "Red Wool" on old clients and on clients that do
  not have localization enabled. However, if we have for instance a translation


@@ 4006,16 4074,18 @@ noise = offset + scale * (abs(octave1) +

For 2D or 3D perlin noise or perlin noise maps:

    np_terrain = {
        offset = 0,
        scale = 1,
        spread = {x = 500, y = 500, z = 500},
        seed = 571347,
        octaves = 5,
        persistence = 0.63,
        lacunarity = 2.0,
        flags = "defaults, absvalue",
    }
```lua
np_terrain = {
    offset = 0,
    scale = 1,
    spread = {x = 500, y = 500, z = 500},
    seed = 571347,
    octaves = 5,
    persistence = 0.63,
    lacunarity = 2.0,
    flags = "defaults, absvalue",
}
```

For 2D noise the Z component of `spread` is still defined but is ignored.
A single noise parameter table can be used for 2D or 3D noise.


@@ 4096,17 4166,19 @@ by this ore type.
This ore type is difficult to control since it is sensitive to small changes.
The following is a decent set of parameters to work from:

    noise_params = {
        offset  = 0,
        scale   = 3,
        spread  = {x=200, y=200, z=200},
        seed    = 5390,
        octaves = 4,
        persistence = 0.5,
        lacunarity = 2.0,
        flags = "eased",
    },
    noise_threshold = 1.6
```lua
noise_params = {
    offset  = 0,
    scale   = 3,
    spread  = {x=200, y=200, z=200},
    seed    = 5390,
    octaves = 4,
    persistence = 0.5,
    lacunarity = 2.0,
    flags = "eased",
},
noise_threshold = 1.6
```

**WARNING**: Use this ore type *very* sparingly since it is ~200x more
computationally expensive than any other ore.


@@ 4694,28 4766,30 @@ Callbacks:

Collision info passed to `on_step` (`moveresult` argument):

    {
        touching_ground = boolean,
        -- Note that touching_ground is only true if the entity was moving and
        -- collided with ground.
```lua
{
    touching_ground = boolean,
    -- Note that touching_ground is only true if the entity was moving and
    -- collided with ground.

        collides = boolean,
        standing_on_object = boolean,
    collides = boolean,
    standing_on_object = boolean,

        collisions = {
            {
                type = string, -- "node" or "object",
                axis = string, -- "x", "y" or "z"
                node_pos = vector, -- if type is "node"
                object = ObjectRef, -- if type is "object"
                old_velocity = vector,
                new_velocity = vector,
            },
            ...
        }
        -- `collisions` does not contain data of unloaded mapblock collisions
        -- or when the velocity changes are negligibly small
    collisions = {
        {
            type = string, -- "node" or "object",
            axis = string, -- "x", "y" or "z"
            node_pos = vector, -- if type is "node"
            object = ObjectRef, -- if type is "object"
            old_velocity = vector,
            new_velocity = vector,
        },
        ...
    }
    -- `collisions` does not contain data of unloaded mapblock collisions
    -- or when the velocity changes are negligibly small
}
```





@@ 4725,27 4799,28 @@ L-system trees
Tree definition
---------------

    treedef={
        axiom,         --string  initial tree axiom
        rules_a,       --string  rules set A
        rules_b,       --string  rules set B
        rules_c,       --string  rules set C
        rules_d,       --string  rules set D
        trunk,         --string  trunk node name
        leaves,        --string  leaves node name
        leaves2,       --string  secondary leaves node name
        leaves2_chance,--num     chance (0-100) to replace leaves with leaves2
        angle,         --num     angle in deg
        iterations,    --num     max # of iterations, usually 2 -5
        random_level,  --num     factor to lower number of iterations, usually 0 - 3
        trunk_type,    --string  single/double/crossed) type of trunk: 1 node,
                       --        2x2 nodes or 3x3 in cross shape
        thin_branches, --boolean true -> use thin (1 node) branches
        fruit,         --string  fruit node name
        fruit_chance,  --num     chance (0-100) to replace leaves with fruit node
        seed,          --num     random seed, if no seed is provided, the engine
                                 will create one.
    }
```lua
treedef={
    axiom,         --string  initial tree axiom
    rules_a,       --string  rules set A
    rules_b,       --string  rules set B
    rules_c,       --string  rules set C
    rules_d,       --string  rules set D
    trunk,         --string  trunk node name
    leaves,        --string  leaves node name
    leaves2,       --string  secondary leaves node name
    leaves2_chance,--num     chance (0-100) to replace leaves with leaves2
    angle,         --num     angle in deg
    iterations,    --num     max # of iterations, usually 2 -5
    random_level,  --num     factor to lower number of iterations, usually 0 - 3
    trunk_type,    --string  single/double/crossed) type of trunk: 1 node,
                    --        2x2 nodes or 3x3 in cross shape
    thin_branches, --boolean true -> use thin (1 node) branches
    fruit,         --string  fruit node name
    fruit_chance,  --num     chance (0-100) to replace leaves with fruit node
    seed,          --num     random seed, if no seed is provided, the engine will create one.
}
```

Key for special L-System symbols used in axioms
-----------------------------------------------


@@ 4777,23 4852,24 @@ Example

Spawn a small apple tree:

    pos = {x=230,y=20,z=4}
    apple_tree={
        axiom="FFFFFAFFBF",
        rules_a="[&&&FFFFF&&FFFF][&&&++++FFFFF&&FFFF][&&&----FFFFF&&FFFF]",
        rules_b="[&&&++FFFFF&&FFFF][&&&--FFFFF&&FFFF][&&&------FFFFF&&FFFF]",
        trunk="default:tree",
        leaves="default:leaves",
        angle=30,
        iterations=2,
        random_level=0,
        trunk_type="single",
        thin_branches=true,
        fruit_chance=10,
        fruit="default:apple"
    }
    minetest.spawn_tree(pos,apple_tree)

```lua
pos = {x=230,y=20,z=4}
apple_tree={
    axiom="FFFFFAFFBF",
    rules_a="[&&&FFFFF&&FFFF][&&&++++FFFFF&&FFFF][&&&----FFFFF&&FFFF]",
    rules_b="[&&&++FFFFF&&FFFF][&&&--FFFFF&&FFFF][&&&------FFFFF&&FFFF]",
    trunk="default:tree",
    leaves="default:leaves",
    angle=30,
    iterations=2,
    random_level=0,
    trunk_type="single",
    thin_branches=true,
    fruit_chance=10,
    fruit="default:apple"
}
minetest.spawn_tree(pos,apple_tree)
```

Privileges
==========


@@ 4902,81 4978,85 @@ Utilities
  current game. Note that other meta information (e.g. version/release number)
  can be manually read from `game.conf` in the game's root directory.

      {
          id = string,
          title = string,
          author = string,
          -- The root directory of the game
          path = string,
      }
  ```lua
  {
      id = string,
      title = string,
      author = string,
      -- The root directory of the game
      path = string,
  }
  ```

* `minetest.get_worldpath()`: returns e.g. `"/home/user/.minetest/world"`
    * Useful for storing custom data
* `minetest.is_singleplayer()`
* `minetest.features`: Table containing API feature flags

      {
          glasslike_framed = true,  -- 0.4.7
          nodebox_as_selectionbox = true,  -- 0.4.7
          get_all_craft_recipes_works = true,  -- 0.4.7
          -- The transparency channel of textures can optionally be used on
          -- nodes (0.4.7)
          use_texture_alpha = true,
          -- Tree and grass ABMs are no longer done from C++ (0.4.8)
          no_legacy_abms = true,
          -- Texture grouping is possible using parentheses (0.4.11)
          texture_names_parens = true,
          -- Unique Area ID for AreaStore:insert_area (0.4.14)
          area_store_custom_ids = true,
          -- add_entity supports passing initial staticdata to on_activate
          -- (0.4.16)
          add_entity_with_staticdata = true,
          -- Chat messages are no longer predicted (0.4.16)
          no_chat_message_prediction = true,
          -- The transparency channel of textures can optionally be used on
          -- objects (ie: players and lua entities) (5.0.0)
          object_use_texture_alpha = true,
          -- Object selectionbox is settable independently from collisionbox
          -- (5.0.0)
          object_independent_selectionbox = true,
          -- Specifies whether binary data can be uploaded or downloaded using
          -- the HTTP API (5.1.0)
          httpfetch_binary_data = true,
          -- Whether formspec_version[<version>] may be used (5.1.0)
          formspec_version_element = true,
          -- Whether AreaStore's IDs are kept on save/load (5.1.0)
          area_store_persistent_ids = true,
          -- Whether minetest.find_path is functional (5.2.0)
          pathfinder_works = true,
          -- Whether Collision info is available to an objects' on_step (5.3.0)
          object_step_has_moveresult = true,
          -- Whether get_velocity() and add_velocity() can be used on players (5.4.0)
          direct_velocity_on_players = true,
          -- nodedef's use_texture_alpha accepts new string modes (5.4.0)
          use_texture_alpha_string_modes = true,
          -- degrotate param2 rotates in units of 1.5° instead of 2°
          -- thus changing the range of values from 0-179 to 0-240 (5.5.0)
          degrotate_240_steps = true,
          -- ABM supports min_y and max_y fields in definition (5.5.0)
          abm_min_max_y = true,
          -- dynamic_add_media supports passing a table with options (5.5.0)
          dynamic_add_media_table = true,
          -- particlespawners support texpools and animation of properties,
          -- particle textures support smooth fade and scale animations, and
          -- sprite-sheet particle animations can by synced to the lifetime
          -- of individual particles (5.6.0)
          particlespawner_tweenable = true,
          -- allows get_sky to return a table instead of separate values (5.6.0)
          get_sky_as_table = true,
          -- VoxelManip:get_light_data accepts an optional buffer argument (5.7.0)
          get_light_data_buffer = true,
          -- When using a mod storage backend that is not "files" or "dummy",
          -- the amount of data in mod storage is not constrained by
          -- the amount of RAM available. (5.7.0)
          mod_storage_on_disk = true,
          -- "zstd" method for compress/decompress (5.7.0)
          compress_zstd = true,
      }
  ```lua
  {
      glasslike_framed = true,  -- 0.4.7
      nodebox_as_selectionbox = true,  -- 0.4.7
      get_all_craft_recipes_works = true,  -- 0.4.7
      -- The transparency channel of textures can optionally be used on
      -- nodes (0.4.7)
      use_texture_alpha = true,
      -- Tree and grass ABMs are no longer done from C++ (0.4.8)
      no_legacy_abms = true,
      -- Texture grouping is possible using parentheses (0.4.11)
      texture_names_parens = true,
      -- Unique Area ID for AreaStore:insert_area (0.4.14)
      area_store_custom_ids = true,
      -- add_entity supports passing initial staticdata to on_activate
      -- (0.4.16)
      add_entity_with_staticdata = true,
      -- Chat messages are no longer predicted (0.4.16)
      no_chat_message_prediction = true,
      -- The transparency channel of textures can optionally be used on
      -- objects (ie: players and lua entities) (5.0.0)
      object_use_texture_alpha = true,
      -- Object selectionbox is settable independently from collisionbox
      -- (5.0.0)
      object_independent_selectionbox = true,
      -- Specifies whether binary data can be uploaded or downloaded using
      -- the HTTP API (5.1.0)
      httpfetch_binary_data = true,
      -- Whether formspec_version[<version>] may be used (5.1.0)
      formspec_version_element = true,
      -- Whether AreaStore's IDs are kept on save/load (5.1.0)
      area_store_persistent_ids = true,
      -- Whether minetest.find_path is functional (5.2.0)
      pathfinder_works = true,
      -- Whether Collision info is available to an objects' on_step (5.3.0)
      object_step_has_moveresult = true,
      -- Whether get_velocity() and add_velocity() can be used on players (5.4.0)
      direct_velocity_on_players = true,
      -- nodedef's use_texture_alpha accepts new string modes (5.4.0)
      use_texture_alpha_string_modes = true,
      -- degrotate param2 rotates in units of 1.5° instead of 2°
      -- thus changing the range of values from 0-179 to 0-240 (5.5.0)
      degrotate_240_steps = true,
      -- ABM supports min_y and max_y fields in definition (5.5.0)
      abm_min_max_y = true,
      -- dynamic_add_media supports passing a table with options (5.5.0)
      dynamic_add_media_table = true,
      -- particlespawners support texpools and animation of properties,
      -- particle textures support smooth fade and scale animations, and
      -- sprite-sheet particle animations can by synced to the lifetime
      -- of individual particles (5.6.0)
      particlespawner_tweenable = true,
      -- allows get_sky to return a table instead of separate values (5.6.0)
      get_sky_as_table = true,
      -- VoxelManip:get_light_data accepts an optional buffer argument (5.7.0)
      get_light_data_buffer = true,
      -- When using a mod storage backend that is not "files" or "dummy",
      -- the amount of data in mod storage is not constrained by
      -- the amount of RAM available. (5.7.0)
      mod_storage_on_disk = true,
      -- "zstd" method for compress/decompress (5.7.0)
      compress_zstd = true,
  }
  ```

* `minetest.has_feature(arg)`: returns `boolean, missing_features`
    * `arg`: string or table in format `{foo=true, bar=true}`


@@ 4984,66 5064,71 @@ Utilities
* `minetest.get_player_information(player_name)`: Table containing information
  about a player. Example return value:

      {
          address = "127.0.0.1",     -- IP address of client
          ip_version = 4,            -- IPv4 / IPv6
          connection_uptime = 200,   -- seconds since client connected
          protocol_version = 32,     -- protocol version used by client
          formspec_version = 2,      -- supported formspec version
          lang_code = "fr",          -- Language code used for translation

          -- the following keys can be missing if no stats have been collected yet
          min_rtt = 0.01,            -- minimum round trip time
          max_rtt = 0.2,             -- maximum round trip time
          avg_rtt = 0.02,            -- average round trip time
          min_jitter = 0.01,         -- minimum packet time jitter
          max_jitter = 0.5,          -- maximum packet time jitter
          avg_jitter = 0.03,         -- average packet time jitter
          -- the following information is available in a debug build only!!!
          -- DO NOT USE IN MODS
          --ser_vers = 26,             -- serialization version used by client
          --major = 0,                 -- major version number
          --minor = 4,                 -- minor version number
          --patch = 10,                -- patch version number
          --vers_string = "0.4.9-git", -- full version string
          --state = "Active"           -- current client state
      }
  ```lua
  {
      address = "127.0.0.1",     -- IP address of client
      ip_version = 4,            -- IPv4 / IPv6
      connection_uptime = 200,   -- seconds since client connected
      protocol_version = 32,     -- protocol version used by client
      formspec_version = 2,      -- supported formspec version
      lang_code = "fr",          -- Language code used for translation

      -- the following keys can be missing if no stats have been collected yet
      min_rtt = 0.01,            -- minimum round trip time
      max_rtt = 0.2,             -- maximum round trip time
      avg_rtt = 0.02,            -- average round trip time
      min_jitter = 0.01,         -- minimum packet time jitter
      max_jitter = 0.5,          -- maximum packet time jitter
      avg_jitter = 0.03,         -- average packet time jitter
      -- the following information is available in a debug build only!!!
      -- DO NOT USE IN MODS
      --ser_vers = 26,             -- serialization version used by client
      --major = 0,                 -- major version number
      --minor = 4,                 -- minor version number
      --patch = 10,                -- patch version number
      --vers_string = "0.4.9-git", -- full version string
      --state = "Active"           -- current client state
  }
  ```

* `minetest.get_player_window_information(player_name)`:

      -- Will only be present if the client sent this information (requires v5.7+)
      --
      -- Note that none of these things are constant, they are likely to change during a client
      -- connection as the player resizes the window and moves it between monitors
  ```lua
  -- Will only be present if the client sent this information (requires v5.7+)
  --
  -- Note that none of these things are constant, they are likely to change during a client
  -- connection as the player resizes the window and moves it between monitors
  --
  -- real_gui_scaling and real_hud_scaling can be used instead of DPI.
  -- OSes don't necessarily give the physical DPI, as they may allow user configuration.
  -- real_*_scaling is just OS DPI / 96 but with another level of user configuration.
  {
      -- Current size of the in-game render target (pixels).
      --
      -- real_gui_scaling and real_hud_scaling can be used instead of DPI.
      -- OSes don't necessarily give the physical DPI, as they may allow user configuration.
      -- real_*_scaling is just OS DPI / 96 but with another level of user configuration.
      {
          -- Current size of the in-game render target (pixels).
          --
          -- This is usually the window size, but may be smaller in certain situations,
          -- such as side-by-side mode.
          size = {
              x = 1308,
              y = 577,
          },

          -- Estimated maximum formspec size before Minetest will start shrinking the
          -- formspec to fit. For a fullscreen formspec, use a size 10-20% larger than
          -- this and `padding[-0.01,-0.01]`.
          max_formspec_size = {
              x = 20,
              y = 11.25
          },

          -- GUI Scaling multiplier
          -- Equal to the setting `gui_scaling` multiplied by `dpi / 96`
          real_gui_scaling = 1,

          -- HUD Scaling multiplier
          -- Equal to the setting `hud_scaling` multiplied by `dpi / 96`
          real_hud_scaling = 1,
      }
      -- This is usually the window size, but may be smaller in certain situations,
      -- such as side-by-side mode.
      size = {
          x = 1308,
          y = 577,
      },

      -- Estimated maximum formspec size before Minetest will start shrinking the
      -- formspec to fit. For a fullscreen formspec, use a size 10-20% larger than
      -- this and `padding[-0.01,-0.01]`.
      max_formspec_size = {
          x = 20,
          y = 11.25
      },

      -- GUI Scaling multiplier
      -- Equal to the setting `gui_scaling` multiplied by `dpi / 96`
      real_gui_scaling = 1,

      -- HUD Scaling multiplier
      -- Equal to the setting `hud_scaling` multiplied by `dpi / 96`
      real_hud_scaling = 1,
  }
  ```

* `minetest.mkdir(path)`: returns success.
    * Creates a directory specified by `path`, creating parent directories


@@ 6009,17 6094,18 @@ Item handling
        * `items`: indexed [1-9] table with recipe items
        * `output`: string with item name and quantity
    * Example result for `"default:gold_ingot"` with two recipes:

      ```lua
      {
          {
              {
                  method = "cooking", width = 3,
                  output = "default:gold_ingot", items = {"default:gold_lump"}
              },
              {
                  method = "normal", width = 1,
                  output = "default:gold_ingot 9", items = {"default:goldblock"}
              }
              method = "cooking", width = 3,
              output = "default:gold_ingot", items = {"default:gold_lump"}
          },
          {
              method = "normal", width = 1,
              output = "default:gold_ingot 9", items = {"default:goldblock"}
          }
      }
      ```

* `minetest.handle_node_drops(pos, drops, digger)`
    * `drops`: list of itemstrings


@@ 6540,14 6626,15 @@ Misc.
    * Cache and call the old version of this function if the position is
      not protected by the mod. This will allow using multiple protection mods.
    * Example:

          local old_is_protected = minetest.is_protected
          function minetest.is_protected(pos, name)
              if mymod:position_protected_from(pos, name) then
                  return true
              end
              return old_is_protected(pos, name)
      ```lua
      local old_is_protected = minetest.is_protected
      function minetest.is_protected(pos, name)
          if mymod:position_protected_from(pos, name) then
              return true
          end
          return old_is_protected(pos, name)
      end
      ```
* `minetest.record_protection_violation(pos, name)`
    * This function calls functions registered with
      `minetest.register_on_protection_violation`.


@@ 6740,13 6827,14 @@ use the provided load and write functions for this.
* `get_area(id, include_corners, include_data)`
    * Returns the area information about the specified ID.
    * Returned values are either of these:

            nil  -- Area not found
            true -- Without `include_corners` and `include_data`
            {
                min = pos, max = pos -- `include_corners == true`
                data = string        -- `include_data == true`
            }
      ```lua
      nil  -- Area not found
      true -- Without `include_corners` and `include_data`
      {
          min = pos, max = pos -- `include_corners == true`
          data = string        -- `include_data == true`
      }
      ```

* `get_areas_for_pos(pos, include_corners, include_data)`
    * Returns all areas as table, indexed by the area ID.


@@ 6774,12 6862,15 @@ use the provided load and write functions for this.
  Calling invalidates the cache, so that its elements have to be newly
  generated.
    * `params` is a table with the following fields:

      ```lua
      {
          enabled = boolean,   -- Whether to enable, default true
          block_radius = int,  -- The radius (in nodes) of the areas the cache
                               -- generates prefiltered lists for, minimum 16,
                               -- default 64
          limit = int,         -- The cache size, minimum 20, default 1000
      }
      ```
* `to_string()`: Experimental. Returns area store serialized as a (binary)
  string.
* `to_file(filename)`: Experimental. Like `to_string()`, but writes the data to


@@ 7004,29 7095,31 @@ A metadata table is a table that has the following keys:

Example:

    metadata_table = {
        -- metadata fields (key/value store)
        fields = {
            infotext = "Container",
            anoter_key = "Another Value",
        },
```lua
metadata_table = {
    -- metadata fields (key/value store)
    fields = {
        infotext = "Container",
        anoter_key = "Another Value",
    },

        -- inventory data (for nodes)
        inventory = {
            -- inventory list "main" with 4 slots
            main = {
                -- list of all item slots
                [1] = "example:dirt",
                [2] = "example:stone 25",
                [3] = "", -- empty slot
                [4] = "example:pickaxe",
            },
            -- inventory list "hidden" with 1 slot
            hidden = {
                [1] = "example:diamond",
            },
    -- inventory data (for nodes)
    inventory = {
        -- inventory list "main" with 4 slots
        main = {
            -- list of all item slots
            [1] = "example:dirt",
            [2] = "example:stone 25",
            [3] = "", -- empty slot
            [4] = "example:pickaxe",
        },
    }
        -- inventory list "hidden" with 1 slot
        hidden = {
            [1] = "example:diamond",
        },
    },
}
```

`ModChannel`
------------


@@ 7200,23 7293,27 @@ child will follow movement and rotation of that bone.
* `is_player()`: returns true for players, false otherwise
* `get_nametag_attributes()`
    * returns a table with the attributes of the nametag of an object
    * {
        text = "",
        color = {a=0..255, r=0..255, g=0..255, b=0..255},
        bgcolor = {a=0..255, r=0..255, g=0..255, b=0..255},
    * ```lua
      {
          text = "",
          color = {a=0..255, r=0..255, g=0..255, b=0..255},
          bgcolor = {a=0..255, r=0..255, g=0..255, b=0..255},
      }
      ```
* `set_nametag_attributes(attributes)`
    * sets the attributes of the nametag of an object
    * `attributes`:
      ```lua
      {
        text = "My Nametag",
        color = ColorSpec,
        -- ^ Text color
        bgcolor = ColorSpec or false,
        -- ^ Sets background color of nametag
        -- `false` will cause the background to be set automatically based on user settings
        -- Default: false
          text = "My Nametag",
          color = ColorSpec,
          -- ^ Text color
          bgcolor = ColorSpec or false,
          -- ^ Sets background color of nametag
          -- `false` will cause the background to be set automatically based on user settings
          -- Default: false
      }
      ```

#### Lua entity only (no-op for other objects)



@@ 7716,10 7813,12 @@ It can be created via `PseudoRandom(seed)`.
A raycast on the map. It works with selection boxes.
Can be used as an iterator in a for loop as:

    local ray = Raycast(...)
    for pointed_thing in ray do
        ...
    end
```lua
local ray = Raycast(...)
for pointed_thing in ray do
    ...
end
```

The map is loaded as the ray advances. If the map is modified after the
`Raycast` is created, the changes may or may not have an effect on the object.


@@ 7839,201 7938,205 @@ These properties are not persistent, but are applied automatically to the
corresponding Lua entity using the given registration fields.
Player properties need to be saved manually.

    {
        hp_max = 10,
        -- Defines the maximum and default HP of the entity
        -- For Lua entities the maximum is not enforced.
        -- For players this defaults to `minetest.PLAYER_MAX_HP_DEFAULT`.

        breath_max = 0,
        -- For players only. Defaults to `minetest.PLAYER_MAX_BREATH_DEFAULT`.

        zoom_fov = 0.0,
        -- For players only. Zoom FOV in degrees.
        -- Note that zoom loads and/or generates world beyond the server's
        -- maximum send and generate distances, so acts like a telescope.
        -- Smaller zoom_fov values increase the distance loaded/generated.
        -- Defaults to 15 in creative mode, 0 in survival mode.
        -- zoom_fov = 0 disables zooming for the player.

        eye_height = 1.625,
        -- For players only. Camera height above feet position in nodes.

        physical = false,
        -- Collide with `walkable` nodes.

        collide_with_objects = true,
        -- Collide with other objects if physical = true

        collisionbox = { -0.5, -0.5, -0.5, 0.5, 0.5, 0.5 },  -- default
        selectionbox = { -0.5, -0.5, -0.5, 0.5, 0.5, 0.5, rotate = false },
		-- { xmin, ymin, zmin, xmax, ymax, zmax } in nodes from object position.
        -- Collision boxes cannot rotate, setting `rotate = true` on it has no effect.
        -- If not set, the selection box copies the collision box, and will also not rotate.
        -- If `rotate = false`, the selection box will not rotate with the object itself, remaining fixed to the axes.
        -- If `rotate = true`, it will match the object's rotation and any attachment rotations.
        -- Raycasts use the selection box and object's rotation, but do *not* obey attachment rotations.


        pointable = true,
        -- Whether the object can be pointed at

        visual = "cube" / "sprite" / "upright_sprite" / "mesh" / "wielditem" / "item",
        -- "cube" is a node-sized cube.
        -- "sprite" is a flat texture always facing the player.
        -- "upright_sprite" is a vertical flat texture.
        -- "mesh" uses the defined mesh model.
        -- "wielditem" is used for dropped items.
        --   (see builtin/game/item_entity.lua).
        --   For this use 'wield_item = itemname' (Deprecated: 'textures = {itemname}').
        --   If the item has a 'wield_image' the object will be an extrusion of
        --   that, otherwise:
        --   If 'itemname' is a cubic node or nodebox the object will appear
        --   identical to 'itemname'.
        --   If 'itemname' is a plantlike node the object will be an extrusion
        --   of its texture.
        --   Otherwise for non-node items, the object will be an extrusion of
        --   'inventory_image'.
        --   If 'itemname' contains a ColorString or palette index (e.g. from
        --   `minetest.itemstring_with_palette()`), the entity will inherit the color.
        --   Wielditems are scaled a bit. If you want a wielditem to appear
        --   to be as large as a node, use `0.667` in `visual_size`
        -- "item" is similar to "wielditem" but ignores the 'wield_image' parameter.

        visual_size = {x = 1, y = 1, z = 1},
        -- Multipliers for the visual size. If `z` is not specified, `x` will be used
        -- to scale the entity along both horizontal axes.

        mesh = "model.obj",
        -- File name of mesh when using "mesh" visual

        textures = {},
        -- Number of required textures depends on visual.
        -- "cube" uses 6 textures just like a node, but all 6 must be defined.
        -- "sprite" uses 1 texture.
        -- "upright_sprite" uses 2 textures: {front, back}.
        -- "wielditem" expects 'textures = {itemname}' (see 'visual' above).
        -- "mesh" requires one texture for each mesh buffer/material (in order)

        colors = {},
        -- Number of required colors depends on visual

        use_texture_alpha = false,
        -- Use texture's alpha channel.
        -- Excludes "upright_sprite" and "wielditem".
        -- Note: currently causes visual issues when viewed through other
        -- semi-transparent materials such as water.

        spritediv = {x = 1, y = 1},
        -- Used with spritesheet textures for animation and/or frame selection
        -- according to position relative to player.
        -- Defines the number of columns and rows in the spritesheet:
        -- {columns, rows}.

        initial_sprite_basepos = {x = 0, y = 0},
        -- Used with spritesheet textures.
        -- Defines the {column, row} position of the initially used frame in the
        -- spritesheet.

        is_visible = true,
        -- If false, object is invisible and can't be pointed.

        makes_footstep_sound = false,
        -- If true, is able to make footstep sounds of nodes
        -- (see node sound definition for details).

        automatic_rotate = 0,
        -- Set constant rotation in radians per second, positive or negative.
        -- Object rotates along the local Y-axis, and works with set_rotation.
        -- Set to 0 to disable constant rotation.

        stepheight = 0,
        -- If positive number, object will climb upwards when it moves
        -- horizontally against a `walkable` node, if the height difference
        -- is within `stepheight`.

        automatic_face_movement_dir = 0.0,
        -- Automatically set yaw to movement direction, offset in degrees.
        -- 'false' to disable.

        automatic_face_movement_max_rotation_per_sec = -1,
        -- Limit automatic rotation to this value in degrees per second.
        -- No limit if value <= 0.

        backface_culling = true,
        -- Set to false to disable backface_culling for model

        glow = 0,
        -- Add this much extra lighting when calculating texture color.
        -- Value < 0 disables light's effect on texture color.
        -- For faking self-lighting, UI style entities, or programmatic coloring
        -- in mods.

        nametag = "",
        -- The name to display on the head of the object. By default empty.
        -- If the object is a player, a nil or empty nametag is replaced by the player's name.
        -- For all other objects, a nil or empty string removes the nametag.
        -- To hide a nametag, set its color alpha to zero. That will disable it entirely.

        nametag_color = <ColorSpec>,
        -- Sets text color of nametag

        nametag_bgcolor = <ColorSpec>,
        -- Sets background color of nametag
        -- `false` will cause the background to be set automatically based on user settings.
        -- Default: false

        infotext = "",
        -- Same as infotext for nodes. Empty by default

        static_save = true,
        -- If false, never save this object statically. It will simply be
        -- deleted when the block gets unloaded.
        -- The get_staticdata() callback is never called then.
        -- Defaults to 'true'.

        damage_texture_modifier = "^[brighten",
        -- Texture modifier to be applied for a short duration when object is hit

        shaded = true,
        -- Setting this to 'false' disables diffuse lighting of entity

        show_on_minimap = false,
        -- Defaults to true for players, false for other entities.
        -- If set to true the entity will show as a marker on the minimap.
    }
```lua
{
    hp_max = 10,
    -- Defines the maximum and default HP of the entity
    -- For Lua entities the maximum is not enforced.
    -- For players this defaults to `minetest.PLAYER_MAX_HP_DEFAULT`.

    breath_max = 0,
    -- For players only. Defaults to `minetest.PLAYER_MAX_BREATH_DEFAULT`.

    zoom_fov = 0.0,
    -- For players only. Zoom FOV in degrees.
    -- Note that zoom loads and/or generates world beyond the server's
    -- maximum send and generate distances, so acts like a telescope.
    -- Smaller zoom_fov values increase the distance loaded/generated.
    -- Defaults to 15 in creative mode, 0 in survival mode.
    -- zoom_fov = 0 disables zooming for the player.

    eye_height = 1.625,
    -- For players only. Camera height above feet position in nodes.

    physical = false,
    -- Collide with `walkable` nodes.

    collide_with_objects = true,
    -- Collide with other objects if physical = true

    collisionbox = { -0.5, -0.5, -0.5, 0.5, 0.5, 0.5 },  -- default
    selectionbox = { -0.5, -0.5, -0.5, 0.5, 0.5, 0.5, rotate = false },
    -- { xmin, ymin, zmin, xmax, ymax, zmax } in nodes from object position.
    -- Collision boxes cannot rotate, setting `rotate = true` on it has no effect.
    -- If not set, the selection box copies the collision box, and will also not rotate.
    -- If `rotate = false`, the selection box will not rotate with the object itself, remaining fixed to the axes.
    -- If `rotate = true`, it will match the object's rotation and any attachment rotations.
    -- Raycasts use the selection box and object's rotation, but do *not* obey attachment rotations.


    pointable = true,
    -- Whether the object can be pointed at

    visual = "cube" / "sprite" / "upright_sprite" / "mesh" / "wielditem" / "item",
    -- "cube" is a node-sized cube.
    -- "sprite" is a flat texture always facing the player.
    -- "upright_sprite" is a vertical flat texture.
    -- "mesh" uses the defined mesh model.
    -- "wielditem" is used for dropped items.
    --   (see builtin/game/item_entity.lua).
    --   For this use 'wield_item = itemname' (Deprecated: 'textures = {itemname}').
    --   If the item has a 'wield_image' the object will be an extrusion of
    --   that, otherwise:
    --   If 'itemname' is a cubic node or nodebox the object will appear
    --   identical to 'itemname'.
    --   If 'itemname' is a plantlike node the object will be an extrusion
    --   of its texture.
    --   Otherwise for non-node items, the object will be an extrusion of
    --   'inventory_image'.
    --   If 'itemname' contains a ColorString or palette index (e.g. from
    --   `minetest.itemstring_with_palette()`), the entity will inherit the color.
    --   Wielditems are scaled a bit. If you want a wielditem to appear
    --   to be as large as a node, use `0.667` in `visual_size`
    -- "item" is similar to "wielditem" but ignores the 'wield_image' parameter.

    visual_size = {x = 1, y = 1, z = 1},
    -- Multipliers for the visual size. If `z` is not specified, `x` will be used
    -- to scale the entity along both horizontal axes.

    mesh = "model.obj",
    -- File name of mesh when using "mesh" visual

    textures = {},
    -- Number of required textures depends on visual.
    -- "cube" uses 6 textures just like a node, but all 6 must be defined.
    -- "sprite" uses 1 texture.
    -- "upright_sprite" uses 2 textures: {front, back}.
    -- "wielditem" expects 'textures = {itemname}' (see 'visual' above).
    -- "mesh" requires one texture for each mesh buffer/material (in order)

    colors = {},
    -- Number of required colors depends on visual

    use_texture_alpha = false,
    -- Use texture's alpha channel.
    -- Excludes "upright_sprite" and "wielditem".
    -- Note: currently causes visual issues when viewed through other
    -- semi-transparent materials such as water.

    spritediv = {x = 1, y = 1},
    -- Used with spritesheet textures for animation and/or frame selection
    -- according to position relative to player.
    -- Defines the number of columns and rows in the spritesheet:
    -- {columns, rows}.

    initial_sprite_basepos = {x = 0, y = 0},
    -- Used with spritesheet textures.
    -- Defines the {column, row} position of the initially used frame in the
    -- spritesheet.

    is_visible = true,
    -- If false, object is invisible and can't be pointed.

    makes_footstep_sound = false,
    -- If true, is able to make footstep sounds of nodes
    -- (see node sound definition for details).

    automatic_rotate = 0,
    -- Set constant rotation in radians per second, positive or negative.
    -- Object rotates along the local Y-axis, and works with set_rotation.
    -- Set to 0 to disable constant rotation.

    stepheight = 0,
    -- If positive number, object will climb upwards when it moves
    -- horizontally against a `walkable` node, if the height difference
    -- is within `stepheight`.

    automatic_face_movement_dir = 0.0,
    -- Automatically set yaw to movement direction, offset in degrees.
    -- 'false' to disable.

    automatic_face_movement_max_rotation_per_sec = -1,
    -- Limit automatic rotation to this value in degrees per second.
    -- No limit if value <= 0.

    backface_culling = true,
    -- Set to false to disable backface_culling for model

    glow = 0,
    -- Add this much extra lighting when calculating texture color.
    -- Value < 0 disables light's effect on texture color.
    -- For faking self-lighting, UI style entities, or programmatic coloring
    -- in mods.

    nametag = "",
    -- The name to display on the head of the object. By default empty.
    -- If the object is a player, a nil or empty nametag is replaced by the player's name.
    -- For all other objects, a nil or empty string removes the nametag.
    -- To hide a nametag, set its color alpha to zero. That will disable it entirely.

    nametag_color = <ColorSpec>,
    -- Sets text color of nametag

    nametag_bgcolor = <ColorSpec>,
    -- Sets background color of nametag
    -- `false` will cause the background to be set automatically based on user settings.
    -- Default: false

    infotext = "",
    -- Same as infotext for nodes. Empty by default

    static_save = true,
    -- If false, never save this object statically. It will simply be
    -- deleted when the block gets unloaded.
    -- The get_staticdata() callback is never called then.
    -- Defaults to 'true'.

    damage_texture_modifier = "^[brighten",
    -- Texture modifier to be applied for a short duration when object is hit

    shaded = true,
    -- Setting this to 'false' disables diffuse lighting of entity

    show_on_minimap = false,
    -- Defaults to true for players, false for other entities.
    -- If set to true the entity will show as a marker on the minimap.
}
```

Entity definition
-----------------

Used by `minetest.register_entity`.

    {
        initial_properties = {
            visual = "mesh",
            mesh = "boats_boat.obj",
            ...,
        },
        -- A table of object properties, see the `Object properties` section.
        -- The properties in this table are applied to the object
        -- once when it is spawned.

        -- Refer to the "Registered entities" section for explanations
        on_activate = function(self, staticdata, dtime_s),
        on_deactivate = function(self, removal),
        on_step = function(self, dtime, moveresult),
        on_punch = function(self, puncher, time_from_last_punch, tool_capabilities, dir, damage),
        on_death = function(self, killer),
        on_rightclick = function(self, clicker),
        on_attach_child = function(self, child),
        on_detach_child = function(self, child),
        on_detach = function(self, parent),
        get_staticdata = function(self),

        _custom_field = whatever,
        -- You can define arbitrary member variables here (see Item definition
        -- for more info) by using a '_' prefix
    }
```lua
{
    initial_properties = {
        visual = "mesh",
        mesh = "boats_boat.obj",
        ...,
    },
    -- A table of object properties, see the `Object properties` section.
    -- The properties in this table are applied to the object
    -- once when it is spawned.

    -- Refer to the "Registered entities" section for explanations
    on_activate = function(self, staticdata, dtime_s) end,
    on_deactivate = function(self, removal) end,
    on_step = function(self, dtime, moveresult) end,
    on_punch = function(self, puncher, time_from_last_punch, tool_capabilities, dir, damage) end,
    on_death = function(self, killer) end,
    on_rightclick = function(self, clicker) end,
    on_attach_child = function(self, child) end,
    on_detach_child = function(self, child) end,
    on_detach = function(self, parent) end,
    get_staticdata = function(self) end,

    _custom_field = whatever,
    -- You can define arbitrary member variables here (see Item definition
    -- for more info) by using a '_' prefix
}
```


ABM (ActiveBlockModifier) definition


@@ 8041,47 8144,49 @@ ABM (ActiveBlockModifier) definition

Used by `minetest.register_abm`.

    {
        label = "Lava cooling",
        -- Descriptive label for profiling purposes (optional).
        -- Definitions with identical labels will be listed as one.

        nodenames = {"default:lava_source"},
        -- Apply `action` function to these nodes.
        -- `group:groupname` can also be used here.

        neighbors = {"default:water_source", "default:water_flowing"},
        -- Only apply `action` to nodes that have one of, or any
        -- combination of, these neighbors.
        -- If left out or empty, any neighbor will do.
        -- `group:groupname` can also be used here.

        interval = 10.0,
        -- Operation interval in seconds

        chance = 50,
        -- Chance of triggering `action` per-node per-interval is 1.0 / chance

        min_y = -32768,
        max_y = 32767,
        -- min and max height levels where ABM will be processed (inclusive)
        -- can be used to reduce CPU usage

        catch_up = true,
        -- If true, catch-up behavior is enabled: The `chance` value is
        -- temporarily reduced when returning to an area to simulate time lost
        -- by the area being unattended. Note that the `chance` value can often
        -- be reduced to 1.

        action = function(pos, node, active_object_count, active_object_count_wider),
        -- Function triggered for each qualifying node.
        -- `active_object_count` is number of active objects in the node's
        -- mapblock.
        -- `active_object_count_wider` is number of active objects in the node's
        -- mapblock plus all 26 neighboring mapblocks. If any neighboring
        -- mapblocks are unloaded an estimate is calculated for them based on
        -- loaded mapblocks.
    }
```lua
{
    label = "Lava cooling",
    -- Descriptive label for profiling purposes (optional).
    -- Definitions with identical labels will be listed as one.

    nodenames = {"default:lava_source"},
    -- Apply `action` function to these nodes.
    -- `group:groupname` can also be used here.

    neighbors = {"default:water_source", "default:water_flowing"},
    -- Only apply `action` to nodes that have one of, or any
    -- combination of, these neighbors.
    -- If left out or empty, any neighbor will do.
    -- `group:groupname` can also be used here.

    interval = 10.0,
    -- Operation interval in seconds

    chance = 50,
    -- Chance of triggering `action` per-node per-interval is 1.0 / chance

    min_y = -32768,
    max_y = 32767,
    -- min and max height levels where ABM will be processed (inclusive)
    -- can be used to reduce CPU usage

    catch_up = true,
    -- If true, catch-up behavior is enabled: The `chance` value is
    -- temporarily reduced when returning to an area to simulate time lost
    -- by the area being unattended. Note that the `chance` value can often
    -- be reduced to 1.

    action = function(pos, node, active_object_count, active_object_count_wider),
    -- Function triggered for each qualifying node.
    -- `active_object_count` is number of active objects in the node's
    -- mapblock.
    -- `active_object_count_wider` is number of active objects in the node's
    -- mapblock plus all 26 neighboring mapblocks. If any neighboring
    -- mapblocks are unloaded an estimate is calculated for them based on
    -- loaded mapblocks.
}
```

LBM (LoadingBlockModifier) definition
-------------------------------------


@@ 8092,29 8197,31 @@ A loading block modifier (LBM) is used to define a function that is called for
specific nodes (defined by `nodenames`) when a mapblock which contains such nodes
gets activated (not loaded!)

    {
        label = "Upgrade legacy doors",
        -- Descriptive label for profiling purposes (optional).
        -- Definitions with identical labels will be listed as one.

        name = "modname:replace_legacy_door",
        -- Identifier of the LBM, should follow the modname:<whatever> convention

        nodenames = {"default:lava_source"},
        -- List of node names to trigger the LBM on.
        -- Names of non-registered nodes and groups (as group:groupname)
        -- will work as well.

        run_at_every_load = false,
        -- Whether to run the LBM's action every time a block gets activated,
        -- and not only the first time the block gets activated after the LBM
        -- was introduced.

        action = function(pos, node, dtime_s),
        -- Function triggered for each qualifying node.
        -- `dtime_s` is the in-game time (in seconds) elapsed since the block
        -- was last active
    }
```lua
{
    label = "Upgrade legacy doors",
    -- Descriptive label for profiling purposes (optional).
    -- Definitions with identical labels will be listed as one.

    name = "modname:replace_legacy_door",
    -- Identifier of the LBM, should follow the modname:<whatever> convention

    nodenames = {"default:lava_source"},
    -- List of node names to trigger the LBM on.
    -- Names of non-registered nodes and groups (as group:groupname)
    -- will work as well.

    run_at_every_load = false,
    -- Whether to run the LBM's action every time a block gets activated,
    -- and not only the first time the block gets activated after the LBM
    -- was introduced.

    action = function(pos, node, dtime_s) end,
    -- Function triggered for each qualifying node.
    -- `dtime_s` is the in-game time (in seconds) elapsed since the block
    -- was last active
}
```

Tile definition
---------------


@@ 8141,31 8248,33 @@ Tile definition
Tile animation definition
-------------------------

    {
        type = "vertical_frames",
```lua
{
    type = "vertical_frames",

        aspect_w = 16,
        -- Width of a frame in pixels
    aspect_w = 16,
    -- Width of a frame in pixels

        aspect_h = 16,
        -- Height of a frame in pixels
    aspect_h = 16,
    -- Height of a frame in pixels

        length = 3.0,
        -- Full loop length
    }
    length = 3.0,
    -- Full loop length
}

    {
        type = "sheet_2d",
{
    type = "sheet_2d",

        frames_w = 5,
        -- Width in number of frames
    frames_w = 5,
    -- Width in number of frames

        frames_h = 3,
        -- Height in number of frames
    frames_h = 3,
    -- Height in number of frames

        frame_length = 0.5,
        -- Length of a single frame
    }
    frame_length = 0.5,
    -- Length of a single frame
}
```

Item definition
---------------


@@ 8173,616 8282,620 @@ Item definition
Used by `minetest.register_node`, `minetest.register_craftitem`, and
`minetest.register_tool`.

    {
        description = "",
        -- Can contain new lines. "\n" has to be used as new line character.
        -- See also: `get_description` in [`ItemStack`]

        short_description = "",
        -- Must not contain new lines.
        -- Defaults to nil.
        -- Use an [`ItemStack`] to get the short description, e.g.:
        --   ItemStack(itemname):get_short_description()

        groups = {},
        -- key = name, value = rating; rating = <number>.
        -- If rating not applicable, use 1.
        -- e.g. {wool = 1, fluffy = 3}
        --      {soil = 2, outerspace = 1, crumbly = 1}
        --      {bendy = 2, snappy = 1},
        --      {hard = 1, metal = 1, spikes = 1}

        inventory_image = "",
        -- Texture shown in the inventory GUI
        -- Defaults to a 3D rendering of the node if left empty.

        inventory_overlay = "",
        -- An overlay texture which is not affected by colorization

        wield_image = "",
        -- Texture shown when item is held in hand
        -- Defaults to a 3D rendering of the node if left empty.

        wield_overlay = "",
        -- Like inventory_overlay but only used in the same situation as wield_image

        wield_scale = {x = 1, y = 1, z = 1},
        -- Scale for the item when held in hand

        palette = "",
        -- An image file containing the palette of a node.
        -- You can set the currently used color as the "palette_index" field of
        -- the item stack metadata.
        -- The palette is always stretched to fit indices between 0 and 255, to
        -- ensure compatibility with "colorfacedir" (and similar) nodes.

        color = "#ffffffff",
        -- Color the item is colorized with. The palette overrides this.

        stack_max = 99,
        -- Maximum amount of items that can be in a single stack.
        -- The default can be changed by the setting `default_stack_max`

        range = 4.0,
        -- Range of node and object pointing that is possible with this item held

        liquids_pointable = false,
        -- If true, item can point to all liquid nodes (`liquidtype ~= "none"`),
        -- even those for which `pointable = false`

        light_source = 0,
        -- When used for nodes: Defines amount of light emitted by node.
        -- Otherwise: Defines texture glow when viewed as a dropped item
        -- To set the maximum (14), use the value 'minetest.LIGHT_MAX'.
        -- A value outside the range 0 to minetest.LIGHT_MAX causes undefined
        -- behavior.

        -- See "Tool Capabilities" section for an example including explanation
        tool_capabilities = {
            full_punch_interval = 1.0,
            max_drop_level = 0,
            groupcaps = {
                -- For example:
                choppy = {times = {2.50, 1.40, 1.00}, uses = 20, maxlevel = 2},
            },
            damage_groups = {groupname = damage},
            -- Damage values must be between -32768 and 32767 (2^15)

            punch_attack_uses = nil,
            -- Amount of uses this tool has for attacking players and entities
            -- by punching them (0 = infinite uses).
            -- For compatibility, this is automatically set from the first
            -- suitable groupcap using the formula "uses * 3^(maxlevel - 1)".
            -- It is recommend to set this explicitly instead of relying on the
            -- fallback behavior.
```lua
{
    description = "",
    -- Can contain new lines. "\n" has to be used as new line character.
    -- See also: `get_description` in [`ItemStack`]

    short_description = "",
    -- Must not contain new lines.
    -- Defaults to nil.
    -- Use an [`ItemStack`] to get the short description, e.g.:
    --   ItemStack(itemname):get_short_description()

    groups = {},
    -- key = name, value = rating; rating = <number>.
    -- If rating not applicable, use 1.
    -- e.g. {wool = 1, fluffy = 3}
    --      {soil = 2, outerspace = 1, crumbly = 1}
    --      {bendy = 2, snappy = 1},
    --      {hard = 1, metal = 1, spikes = 1}

    inventory_image = "",
    -- Texture shown in the inventory GUI
    -- Defaults to a 3D rendering of the node if left empty.

    inventory_overlay = "",
    -- An overlay texture which is not affected by colorization

    wield_image = "",
    -- Texture shown when item is held in hand
    -- Defaults to a 3D rendering of the node if left empty.

    wield_overlay = "",
    -- Like inventory_overlay but only used in the same situation as wield_image

    wield_scale = {x = 1, y = 1, z = 1},
    -- Scale for the item when held in hand

    palette = "",
    -- An image file containing the palette of a node.
    -- You can set the currently used color as the "palette_index" field of
    -- the item stack metadata.
    -- The palette is always stretched to fit indices between 0 and 255, to
    -- ensure compatibility with "colorfacedir" (and similar) nodes.

    color = "#ffffffff",
    -- Color the item is colorized with. The palette overrides this.

    stack_max = 99,
    -- Maximum amount of items that can be in a single stack.
    -- The default can be changed by the setting `default_stack_max`

    range = 4.0,
    -- Range of node and object pointing that is possible with this item held

    liquids_pointable = false,
    -- If true, item can point to all liquid nodes (`liquidtype ~= "none"`),
    -- even those for which `pointable = false`

    light_source = 0,
    -- When used for nodes: Defines amount of light emitted by node.
    -- Otherwise: Defines texture glow when viewed as a dropped item
    -- To set the maximum (14), use the value 'minetest.LIGHT_MAX'.
    -- A value outside the range 0 to minetest.LIGHT_MAX causes undefined
    -- behavior.

    -- See "Tool Capabilities" section for an example including explanation
    tool_capabilities = {
        full_punch_interval = 1.0,
        max_drop_level = 0,
        groupcaps = {
            -- For example:
            choppy = {times = {2.50, 1.40, 1.00}, uses = 20, maxlevel = 2},
        },
        damage_groups = {groupname = damage},
        -- Damage values must be between -32768 and 32767 (2^15)

        punch_attack_uses = nil,
        -- Amount of uses this tool has for attacking players and entities
        -- by punching them (0 = infinite uses).
        -- For compatibility, this is automatically set from the first
        -- suitable groupcap using the formula "uses * 3^(maxlevel - 1)".
        -- It is recommend to set this explicitly instead of relying on the
        -- fallback behavior.
    },

        node_placement_prediction = nil,
        -- If nil and item is node, prediction is made automatically.
        -- If nil and item is not a node, no prediction is made.
        -- If "" and item is anything, no prediction is made.
        -- Otherwise should be name of node which the client immediately places
        -- on ground when the player places the item. Server will always update
        -- with actual result shortly.
    node_placement_prediction = nil,
    -- If nil and item is node, prediction is made automatically.
    -- If nil and item is not a node, no prediction is made.
    -- If "" and item is anything, no prediction is made.
    -- Otherwise should be name of node which the client immediately places
    -- on ground when the player places the item. Server will always update
    -- with actual result shortly.

        node_dig_prediction = "air",
        -- if "", no prediction is made.
        -- if "air", node is removed.
        -- Otherwise should be name of node which the client immediately places
        -- upon digging. Server will always update with actual result shortly.
    node_dig_prediction = "air",
    -- if "", no prediction is made.
    -- if "air", node is removed.
    -- Otherwise should be name of node which the client immediately places
    -- upon digging. Server will always update with actual result shortly.

        sound = {
            -- Definition of item sounds to be played at various events.
            -- All fields in this table are optional.
    sound = {
        -- Definition of item sounds to be played at various events.
        -- All fields in this table are optional.

            breaks = <SimpleSoundSpec>,
            -- When tool breaks due to wear. Ignored for non-tools
        breaks = <SimpleSoundSpec>,
        -- When tool breaks due to wear. Ignored for non-tools

            eat = <SimpleSoundSpec>,
            -- When item is eaten with `minetest.do_item_eat`
        eat = <SimpleSoundSpec>,
        -- When item is eaten with `minetest.do_item_eat`

            punch_use = <SimpleSoundSpec>,
            -- When item is used with the 'punch/mine' key pointing at a node or entity
        punch_use = <SimpleSoundSpec>,
        -- When item is used with the 'punch/mine' key pointing at a node or entity

            punch_use_air = <SimpleSoundSpec>,
            -- When item is used with the 'punch/mine' key pointing at nothing (air)
        },
        punch_use_air = <SimpleSoundSpec>,
        -- When item is used with the 'punch/mine' key pointing at nothing (air)
    },

        on_place = function(itemstack, placer, pointed_thing),
        -- When the 'place' key was pressed with the item in hand
        -- and a node was pointed at.
        -- Shall place item and return the leftover itemstack
        -- or nil to not modify the inventory.
        -- The placer may be any ObjectRef or nil.
        -- default: minetest.item_place

        on_secondary_use = function(itemstack, user, pointed_thing),
        -- Same as on_place but called when not pointing at a node.
        -- Function must return either nil if inventory shall not be modified,
        -- or an itemstack to replace the original itemstack.
        -- The user may be any ObjectRef or nil.
        -- default: nil

        on_drop = function(itemstack, dropper, pos),
        -- Shall drop item and return the leftover itemstack.
        -- The dropper may be any ObjectRef or nil.
        -- default: minetest.item_drop

        on_pickup = function(itemstack, picker, pointed_thing, time_from_last_punch, ...),
        -- Called when a dropped item is punched by a player.
        -- Shall pick-up the item and return the leftover itemstack or nil to not
        -- modify the dropped item.
        -- Parameters:
        -- * `itemstack`: The `ItemStack` to be picked up.
        -- * `picker`: Any `ObjectRef` or `nil`.
        -- * `pointed_thing` (optional): The dropped item (a `"__builtin:item"`
        --   luaentity) as `type="object"` `pointed_thing`.
        -- * `time_from_last_punch, ...` (optional): Other parameters from
        --   `luaentity:on_punch`.
        -- default: `minetest.item_pickup`

        on_use = function(itemstack, user, pointed_thing),
        -- default: nil
        -- When user pressed the 'punch/mine' key with the item in hand.
        -- Function must return either nil if inventory shall not be modified,
        -- or an itemstack to replace the original itemstack.
        -- e.g. itemstack:take_item(); return itemstack
        -- Otherwise, the function is free to do what it wants.
        -- The user may be any ObjectRef or nil.
        -- The default functions handle regular use cases.

        after_use = function(itemstack, user, node, digparams),
        -- default: nil
        -- If defined, should return an itemstack and will be called instead of
        -- wearing out the item (if tool). If returns nil, does nothing.
        -- If after_use doesn't exist, it is the same as:
        --   function(itemstack, user, node, digparams)
        --     itemstack:add_wear(digparams.wear)
        --     return itemstack
        --   end
        -- The user may be any ObjectRef or nil.

        _custom_field = whatever,
        -- Add your own custom fields. By convention, all custom field names
        -- should start with `_` to avoid naming collisions with future engine
        -- usage.
    }
    on_place = function(itemstack, placer, pointed_thing),
    -- When the 'place' key was pressed with the item in hand
    -- and a node was pointed at.
    -- Shall place item and return the leftover itemstack
    -- or nil to not modify the inventory.
    -- The placer may be any ObjectRef or nil.
    -- default: minetest.item_place

    on_secondary_use = function(itemstack, user, pointed_thing),
    -- Same as on_place but called when not pointing at a node.
    -- Function must return either nil if inventory shall not be modified,
    -- or an itemstack to replace the original itemstack.
    -- The user may be any ObjectRef or nil.
    -- default: nil

    on_drop = function(itemstack, dropper, pos),
    -- Shall drop item and return the leftover itemstack.
    -- The dropper may be any ObjectRef or nil.
    -- default: minetest.item_drop

    on_pickup = function(itemstack, picker, pointed_thing, time_from_last_punch, ...),
    -- Called when a dropped item is punched by a player.
    -- Shall pick-up the item and return the leftover itemstack or nil to not
    -- modify the dropped item.
    -- Parameters:
    -- * `itemstack`: The `ItemStack` to be picked up.
    -- * `picker`: Any `ObjectRef` or `nil`.
    -- * `pointed_thing` (optional): The dropped item (a `"__builtin:item"`
    --   luaentity) as `type="object"` `pointed_thing`.
    -- * `time_from_last_punch, ...` (optional): Other parameters from
    --   `luaentity:on_punch`.
    -- default: `minetest.item_pickup`

    on_use = function(itemstack, user, pointed_thing),
    -- default: nil
    -- When user pressed the 'punch/mine' key with the item in hand.
    -- Function must return either nil if inventory shall not be modified,
    -- or an itemstack to replace the original itemstack.
    -- e.g. itemstack:take_item(); return itemstack
    -- Otherwise, the function is free to do what it wants.
    -- The user may be any ObjectRef or nil.
    -- The default functions handle regular use cases.

    after_use = function(itemstack, user, node, digparams),
    -- default: nil
    -- If defined, should return an itemstack and will be called instead of
    -- wearing out the item (if tool). If returns nil, does nothing.
    -- If after_use doesn't exist, it is the same as:
    --   function(itemstack, user, node, digparams)
    --     itemstack:add_wear(digparams.wear)
    --     return itemstack
    --   end
    -- The user may be any ObjectRef or nil.

    _custom_field = whatever,
    -- Add your own custom fields. By convention, all custom field names
    -- should start with `_` to avoid naming collisions with future engine
    -- usage.
}
```

Node definition
---------------

Used by `minetest.register_node`.

    {
        -- <all fields allowed in item definitions>

        drawtype = "normal",  -- See "Node drawtypes"

        visual_scale = 1.0,
        -- Supported for drawtypes "plantlike", "signlike", "torchlike",
        -- "firelike", "mesh", "nodebox", "allfaces".
        -- For plantlike and firelike, the image will start at the bottom of the
        -- node. For torchlike, the image will start at the surface to which the
        -- node "attaches". For the other drawtypes the image will be centered
        -- on the node.

        tiles = {tile definition 1, def2, def3, def4, def5, def6},
        -- Textures of node; +Y, -Y, +X, -X, +Z, -Z
        -- List can be shortened to needed length.

        overlay_tiles = {tile definition 1, def2, def3, def4, def5, def6},
        -- Same as `tiles`, but these textures are drawn on top of the base
        -- tiles. You can use this to colorize only specific parts of your
        -- texture. If the texture name is an empty string, that overlay is not
        -- drawn. Since such tiles are drawn twice, it is not recommended to use
        -- overlays on very common nodes.

        special_tiles = {tile definition 1, Tile definition 2},
        -- Special textures of node; used rarely.
        -- List can be shortened to needed length.

        color = ColorSpec,
        -- The node's original color will be multiplied with this color.
        -- If the node has a palette, then this setting only has an effect in
        -- the inventory and on the wield item.

        use_texture_alpha = ...,
        -- Specifies how the texture's alpha channel will be used for rendering.
        -- possible values:
        -- * "opaque": Node is rendered opaque regardless of alpha channel
        -- * "clip": A given pixel is either fully see-through or opaque
        --           depending on the alpha channel being below/above 50% in value
        -- * "blend": The alpha channel specifies how transparent a given pixel
        --            of the rendered node is
        -- The default is "opaque" for drawtypes normal, liquid and flowingliquid;
        -- "clip" otherwise.
        -- If set to a boolean value (deprecated): true either sets it to blend
        -- or clip, false sets it to clip or opaque mode depending on the drawtype.

        palette = "",
        -- The node's `param2` is used to select a pixel from the image.
        -- Pixels are arranged from left to right and from top to bottom.
        -- The node's color will be multiplied with the selected pixel's color.
        -- Tiles can override this behavior.
        -- Only when `paramtype2` supports palettes.

        post_effect_color = "#00000000",
        -- Screen tint if player is inside node, see "ColorSpec"

        paramtype = "none",  -- See "Nodes"

        paramtype2 = "none",  -- See "Nodes"

        place_param2 = 0,
        -- Value for param2 that is set when player places node

        is_ground_content = true,
        -- If false, the cave generator and dungeon generator will not carve
        -- through this node.
        -- Specifically, this stops mod-added nodes being removed by caves and
        -- dungeons when those generate in a neighbor mapchunk and extend out
        -- beyond the edge of that mapchunk.

        sunlight_propagates = false,
        -- If true, sunlight will go infinitely through this node

        walkable = true,  -- If true, objects collide with node

        pointable = true,  -- If true, can be pointed at

        diggable = true,  -- If false, can never be dug

        climbable = false,  -- If true, can be climbed on like a ladder

        move_resistance = 0,
        -- Slows down movement of players through this node (max. 7).
        -- If this is nil, it will be equal to liquid_viscosity.
        -- Note: If liquid movement physics apply to the node
        -- (see `liquid_move_physics`), the movement speed will also be
        -- affected by the `movement_liquid_*` settings.

        buildable_to = false,  -- If true, placed nodes can replace this node

        floodable = false,
        -- If true, liquids flow into and replace this node.
        -- Warning: making a liquid node 'floodable' will cause problems.

        liquidtype = "none",  -- specifies liquid flowing physics
        -- * "none":    no liquid flowing physics
        -- * "source":  spawns flowing liquid nodes at all 4 sides and below;
        --              recommended drawtype: "liquid".
        -- * "flowing": spawned from source, spawns more flowing liquid nodes
        --              around it until `liquid_range` is reached;
        --              will drain out without a source;
        --              recommended drawtype: "flowingliquid".
        -- If it's "source" or "flowing", then the
        -- `liquid_alternative_*` fields _must_ be specified

        liquid_alternative_flowing = "",
        liquid_alternative_source = "",
        -- These fields may contain node names that represent the
        -- flowing version (`liquid_alternative_flowing`) and
        -- source version (`liquid_alternative_source`) of a liquid.
        --
        -- Specifically, these fields are required if any of these is true:
        -- * `liquidtype ~= "none" or
        -- * `drawtype == "liquid" or
        -- * `drawtype == "flowingliquid"
        --
        -- Liquids consist of up to two nodes: source and flowing.
        --
        -- There are two ways to define a liquid:
        -- 1) Source node and flowing node. This requires both fields to be
        --    specified for both nodes.
        -- 2) Standalone source node (cannot flow). `liquid_alternative_source`
        --    must be specified and `liquid_range` must be set to 0.
        --
        -- Example:
        --     liquid_alternative_flowing = "example:water_flowing",
        --     liquid_alternative_source = "example:water_source",

        liquid_viscosity = 0,
        -- Controls speed at which the liquid spreads/flows (max. 7).
        -- 0 is fastest, 7 is slowest.
        -- By default, this also slows down movement of players inside the node
        -- (can be overridden using `move_resistance`)

        liquid_renewable = true,
        -- If true, a new liquid source can be created by placing two or more
        -- sources nearby

        liquid_move_physics = nil, -- specifies movement physics if inside node
        -- * false: No liquid movement physics apply.
        -- * true: Enables liquid movement physics. Enables things like
        --   ability to "swim" up/down, sinking slowly if not moving,
        --   smoother speed change when falling into, etc. The `movement_liquid_*`
        --   settings apply.
        -- * nil: Will be treated as true if `liquidtype ~= "none"`
        --   and as false otherwise.

        leveled = 0,
        -- Only valid for "nodebox" drawtype with 'type = "leveled"'.
        -- Allows defining the nodebox height without using param2.
        -- The nodebox height is 'leveled' / 64 nodes.
        -- The maximum value of 'leveled' is `leveled_max`.

        leveled_max = 127,
        -- Maximum value for `leveled` (0-127), enforced in
        -- `minetest.set_node_level` and `minetest.add_node_level`.
        -- Values above 124 might causes collision detection issues.

        liquid_range = 8,
        -- Maximum distance that flowing liquid nodes can spread around
        -- source on flat land;
        -- maximum = 8; set to 0 to disable liquid flow

        drowning = 0,
        -- Player will take this amount of damage if no bubbles are left

        damage_per_second = 0,
        -- If player is inside node, this damage is caused

        node_box = {type = "regular"},  -- See "Node boxes"

        connects_to = {},
        -- Used for nodebox nodes with the type == "connected".
        -- Specifies to what neighboring nodes connections will be drawn.
        -- e.g. `{"group:fence", "default:wood"}` or `"default:stone"`

        connect_sides = {},
        -- Tells connected nodebox nodes to connect only to these sides of this
        -- node. possible: "top", "bottom", "front", "left", "back", "right"

        mesh = "",
        -- File name of mesh when using "mesh" drawtype

        selection_box = {
            -- see [Node boxes] for possibilities
        },
        -- Custom selection box definition. Multiple boxes can be defined.
        -- If "nodebox" drawtype is used and selection_box is nil, then node_box
        -- definition is used for the selection box.
```lua
{
    -- <all fields allowed in item definitions>

    drawtype = "normal",  -- See "Node drawtypes"

    visual_scale = 1.0,
    -- Supported for drawtypes "plantlike", "signlike", "torchlike",
    -- "firelike", "mesh", "nodebox", "allfaces".
    -- For plantlike and firelike, the image will start at the bottom of the
    -- node. For torchlike, the image will start at the surface to which the
    -- node "attaches". For the other drawtypes the image will be centered
    -- on the node.

    tiles = {tile definition 1, def2, def3, def4, def5, def6},
    -- Textures of node; +Y, -Y, +X, -X, +Z, -Z
    -- List can be shortened to needed length.

    overlay_tiles = {tile definition 1, def2, def3, def4, def5, def6},
    -- Same as `tiles`, but these textures are drawn on top of the base
    -- tiles. You can use this to colorize only specific parts of your
    -- texture. If the texture name is an empty string, that overlay is not
    -- drawn. Since such tiles are drawn twice, it is not recommended to use
    -- overlays on very common nodes.

    special_tiles = {tile definition 1, Tile definition 2},
    -- Special textures of node; used rarely.
    -- List can be shortened to needed length.

    color = ColorSpec,
    -- The node's original color will be multiplied with this color.
    -- If the node has a palette, then this setting only has an effect in
    -- the inventory and on the wield item.

    use_texture_alpha = ...,
    -- Specifies how the texture's alpha channel will be used for rendering.
    -- possible values:
    -- * "opaque": Node is rendered opaque regardless of alpha channel
    -- * "clip": A given pixel is either fully see-through or opaque
    --           depending on the alpha channel being below/above 50% in value
    -- * "blend": The alpha channel specifies how transparent a given pixel
    --            of the rendered node is
    -- The default is "opaque" for drawtypes normal, liquid and flowingliquid;
    -- "clip" otherwise.
    -- If set to a boolean value (deprecated): true either sets it to blend
    -- or clip, false sets it to clip or opaque mode depending on the drawtype.

    palette = "",
    -- The node's `param2` is used to select a pixel from the image.
    -- Pixels are arranged from left to right and from top to bottom.
    -- The node's color will be multiplied with the selected pixel's color.
    -- Tiles can override this behavior.
    -- Only when `paramtype2` supports palettes.

    post_effect_color = "#00000000",
    -- Screen tint if player is inside node, see "ColorSpec"

    paramtype = "none",  -- See "Nodes"

    paramtype2 = "none",  -- See "Nodes"

    place_param2 = 0,
    -- Value for param2 that is set when player places node

    is_ground_content = true,
    -- If false, the cave generator and dungeon generator will not carve
    -- through this node.
    -- Specifically, this stops mod-added nodes being removed by caves and
    -- dungeons when those generate in a neighbor mapchunk and extend out
    -- beyond the edge of that mapchunk.

    sunlight_propagates = false,
    -- If true, sunlight will go infinitely through this node

    walkable = true,  -- If true, objects collide with node

    pointable = true,  -- If true, can be pointed at

    diggable = true,  -- If false, can never be dug

    climbable = false,  -- If true, can be climbed on like a ladder

    move_resistance = 0,
    -- Slows down movement of players through this node (max. 7).
    -- If this is nil, it will be equal to liquid_viscosity.
    -- Note: If liquid movement physics apply to the node
    -- (see `liquid_move_physics`), the movement speed will also be
    -- affected by the `movement_liquid_*` settings.

    buildable_to = false,  -- If true, placed nodes can replace this node

    floodable = false,
    -- If true, liquids flow into and replace this node.
    -- Warning: making a liquid node 'floodable' will cause problems.

    liquidtype = "none",  -- specifies liquid flowing physics
    -- * "none":    no liquid flowing physics
    -- * "source":  spawns flowing liquid nodes at all 4 sides and below;
    --              recommended drawtype: "liquid".
    -- * "flowing": spawned from source, spawns more flowing liquid nodes
    --              around it until `liquid_range` is reached;
    --              will drain out without a source;
    --              recommended drawtype: "flowingliquid".
    -- If it's "source" or "flowing", then the
    -- `liquid_alternative_*` fields _must_ be specified

    liquid_alternative_flowing = "",
    liquid_alternative_source = "",
    -- These fields may contain node names that represent the
    -- flowing version (`liquid_alternative_flowing`) and
    -- source version (`liquid_alternative_source`) of a liquid.
    --
    -- Specifically, these fields are required if any of these is true:
    -- * `liquidtype ~= "none" or
    -- * `drawtype == "liquid" or
    -- * `drawtype == "flowingliquid"
    --
    -- Liquids consist of up to two nodes: source and flowing.
    --
    -- There are two ways to define a liquid:
    -- 1) Source node and flowing node. This requires both fields to be
    --    specified for both nodes.
    -- 2) Standalone source node (cannot flow). `liquid_alternative_source`
    --    must be specified and `liquid_range` must be set to 0.
    --
    -- Example:
    --     liquid_alternative_flowing = "example:water_flowing",
    --     liquid_alternative_source = "example:water_source",

    liquid_viscosity = 0,
    -- Controls speed at which the liquid spreads/flows (max. 7).
    -- 0 is fastest, 7 is slowest.
    -- By default, this also slows down movement of players inside the node
    -- (can be overridden using `move_resistance`)

    liquid_renewable = true,
    -- If true, a new liquid source can be created by placing two or more
    -- sources nearby

    liquid_move_physics = nil, -- specifies movement physics if inside node
    -- * false: No liquid movement physics apply.
    -- * true: Enables liquid movement physics. Enables things like
    --   ability to "swim" up/down, sinking slowly if not moving,
    --   smoother speed change when falling into, etc. The `movement_liquid_*`
    --   settings apply.
    -- * nil: Will be treated as true if `liquidtype ~= "none"`
    --   and as false otherwise.

    leveled = 0,
    -- Only valid for "nodebox" drawtype with 'type = "leveled"'.
    -- Allows defining the nodebox height without using param2.
    -- The nodebox height is 'leveled' / 64 nodes.
    -- The maximum value of 'leveled' is `leveled_max`.

    leveled_max = 127,
    -- Maximum value for `leveled` (0-127), enforced in
    -- `minetest.set_node_level` and `minetest.add_node_level`.
    -- Values above 124 might causes collision detection issues.

    liquid_range = 8,
    -- Maximum distance that flowing liquid nodes can spread around
    -- source on flat land;
    -- maximum = 8; set to 0 to disable liquid flow

    drowning = 0,
    -- Player will take this amount of damage if no bubbles are left

    damage_per_second = 0,
    -- If player is inside node, this damage is caused

    node_box = {type = "regular"},  -- See "Node boxes"

    connects_to = {},
    -- Used for nodebox nodes with the type == "connected".
    -- Specifies to what neighboring nodes connections will be drawn.
    -- e.g. `{"group:fence", "default:wood"}` or `"default:stone"`

    connect_sides = {},
    -- Tells connected nodebox nodes to connect only to these sides of this
    -- node. possible: "top", "bottom", "front", "left", "back", "right"

    mesh = "",
    -- File name of mesh when using "mesh" drawtype

    selection_box = {
        -- see [Node boxes] for possibilities
    },
    -- Custom selection box definition. Multiple boxes can be defined.
    -- If "nodebox" drawtype is used and selection_box is nil, then node_box
    -- definition is used for the selection box.

        collision_box = {
            -- see [Node boxes] for possibilities
        },
        -- Custom collision box definition. Multiple boxes can be defined.
        -- If "nodebox" drawtype is used and collision_box is nil, then node_box
        -- definition is used for the collision box.

        -- Support maps made in and before January 2012
        legacy_facedir_simple = false,
        legacy_wallmounted = false,

        waving = 0,
        -- Valid for drawtypes:
        -- mesh, nodebox, plantlike, allfaces_optional, liquid, flowingliquid.
        -- 1 - wave node like plants (node top moves side-to-side, bottom is fixed)
        -- 2 - wave node like leaves (whole node moves side-to-side)
        -- 3 - wave node like liquids (whole node moves up and down)
        -- Not all models will properly wave.
        -- plantlike drawtype can only wave like plants.
        -- allfaces_optional drawtype can only wave like leaves.
        -- liquid, flowingliquid drawtypes can only wave like liquids.

        sounds = {
            -- Definition of node sounds to be played at various events.
            -- All fields in this table are optional.

            footstep = <SimpleSoundSpec>,
            -- If walkable, played when object walks on it. If node is
            -- climbable or a liquid, played when object moves through it

            dig = <SimpleSoundSpec> or "__group",
            -- While digging node.
            -- If `"__group"`, then the sound will be
            -- `{name = "default_dig_<groupname>", gain = 0.5}` , where `<groupname>` is the
            -- name of the item's digging group with the fastest digging time.
            -- In case of a tie, one of the sounds will be played (but we
            -- cannot predict which one)
            -- Default value: `"__group"`

            dug = <SimpleSoundSpec>,
            -- Node was dug

            place = <SimpleSoundSpec>,
            -- Node was placed. Also played after falling

            place_failed = <SimpleSoundSpec>,
            -- When node placement failed.
            -- Note: This happens if the _built-in_ node placement failed.
            -- This sound will still be played if the node is placed in the
            -- `on_place` callback manually.

            fall = <SimpleSoundSpec>,
            -- When node starts to fall or is detached
        },
    collision_box = {
        -- see [Node boxes] for possibilities
    },
    -- Custom collision box definition. Multiple boxes can be defined.
    -- If "nodebox" drawtype is used and collision_box is nil, then node_box
    -- definition is used for the collision box.

    -- Support maps made in and before January 2012
    legacy_facedir_simple = false,
    legacy_wallmounted = false,

    waving = 0,
    -- Valid for drawtypes:
    -- mesh, nodebox, plantlike, allfaces_optional, liquid, flowingliquid.
    -- 1 - wave node like plants (node top moves side-to-side, bottom is fixed)
    -- 2 - wave node like leaves (whole node moves side-to-side)
    -- 3 - wave node like liquids (whole node moves up and down)
    -- Not all models will properly wave.
    -- plantlike drawtype can only wave like plants.
    -- allfaces_optional drawtype can only wave like leaves.
    -- liquid, flowingliquid drawtypes can only wave like liquids.

    sounds = {
        -- Definition of node sounds to be played at various events.
        -- All fields in this table are optional.

        footstep = <SimpleSoundSpec>,
        -- If walkable, played when object walks on it. If node is
        -- climbable or a liquid, played when object moves through it

        dig = <SimpleSoundSpec> or "__group",
        -- While digging node.
        -- If `"__group"`, then the sound will be
        -- `{name = "default_dig_<groupname>", gain = 0.5}` , where `<groupname>` is the
        -- name of the item's digging group with the fastest digging time.
        -- In case of a tie, one of the sounds will be played (but we
        -- cannot predict which one)
        -- Default value: `"__group"`

        dug = <SimpleSoundSpec>,
        -- Node was dug

        place = <SimpleSoundSpec>,
        -- Node was placed. Also played after falling

        place_failed = <SimpleSoundSpec>,
        -- When node placement failed.
        -- Note: This happens if the _built-in_ node placement failed.
        -- This sound will still be played if the node is placed in the
        -- `on_place` callback manually.

        fall = <SimpleSoundSpec>,
        -- When node starts to fall or is detached
    },

        drop = "",
        -- Name of dropped item when dug.
        -- Default dropped item is the node itself.

        -- Using a table allows multiple items, drop chances and item filtering:
        drop = {
            max_items = 1,
            -- Maximum number of item lists to drop.
            -- The entries in 'items' are processed in order. For each:
            -- Item filtering is applied, chance of drop is applied, if both are
            -- successful the entire item list is dropped.
            -- Entry processing continues until the number of dropped item lists
            -- equals 'max_items'.
            -- Therefore, entries should progress from low to high drop chance.
            items = {
                -- Examples:
                {
                    -- 1 in 1000 chance of dropping a diamond.
                    -- Default rarity is '1'.
                    rarity = 1000,
                    items = {"default:diamond"},
                },
                {
                    -- Only drop if using an item whose name is identical to one
                    -- of these.
                    tools = {"default:shovel_mese", "default:shovel_diamond"},
                    rarity = 5,
                    items = {"default:dirt"},
                    -- Whether all items in the dropped item list inherit the
                    -- hardware coloring palette color from the dug node.
                    -- Default is 'false'.
                    inherit_color = true,
                },
                {
                    -- Only drop if using an item whose name contains
                    -- "default:shovel_" (this item filtering by string matching
                    -- is deprecated, use tool_groups instead).
                    tools = {"~default:shovel_"},
                    rarity = 2,
                    -- The item list dropped.
                    items = {"default:sand", "default:desert_sand"},
                },
                {
                    -- Only drop if using an item in the "magicwand" group, or
                    -- an item that is in both the "pickaxe" and the "lucky"
                    -- groups.
                    tool_groups = {
                        "magicwand",
                        {"pickaxe", "lucky"}
                    },
                    items = {"default:coal_lump"},
    drop = "",
    -- Name of dropped item when dug.
    -- Default dropped item is the node itself.

    -- Using a table allows multiple items, drop chances and item filtering:
    drop = {
        max_items = 1,
        -- Maximum number of item lists to drop.
        -- The entries in 'items' are processed in order. For each:
        -- Item filtering is applied, chance of drop is applied, if both are
        -- successful the entire item list is dropped.
        -- Entry processing continues until the number of dropped item lists
        -- equals 'max_items'.
        -- Therefore, entries should progress from low to high drop chance.
        items = {
            -- Examples:
            {
                -- 1 in 1000 chance of dropping a diamond.
                -- Default rarity is '1'.
                rarity = 1000,
                items = {"default:diamond"},
            },
            {
                -- Only drop if using an item whose name is identical to one
                -- of these.
                tools = {"default:shovel_mese", "default:shovel_diamond"},
                rarity = 5,
                items = {"default:dirt"},
                -- Whether all items in the dropped item list inherit the
                -- hardware coloring palette color from the dug node.
                -- Default is 'false'.
                inherit_color = true,
            },
            {
                -- Only drop if using an item whose name contains
                -- "default:shovel_" (this item filtering by string matching
                -- is deprecated, use tool_groups instead).
                tools = {"~default:shovel_"},
                rarity = 2,
                -- The item list dropped.
                items = {"default:sand", "default:desert_sand"},
            },
            {
                -- Only drop if using an item in the "magicwand" group, or
                -- an item that is in both the "pickaxe" and the "lucky"
                -- groups.
                tool_groups = {
                    "magicwand",
                    {"pickaxe", "lucky"}
                },
                items = {"default:coal_lump"},
            },
        },
    },

        on_construct = function(pos),
        -- Node constructor; called after adding node.
        -- Can set up metadata and stuff like that.
        -- Not called for bulk node placement (i.e. schematics and VoxelManip).
        -- Note: Within an on_construct callback, minetest.set_node can cause an
        -- infinite loop if it invokes the same callback.
        --  Consider using minetest.swap_node instead.
        -- default: nil

        on_destruct = function(pos),
        -- Node destructor; called before removing node.
        -- Not called for bulk node placement.
        -- default: nil

        after_destruct = function(pos, oldnode),
        -- Node destructor; called after removing node.
        -- Not called for bulk node placement.
        -- default: nil

        on_flood = function(pos, oldnode, newnode),
        -- Called when a liquid (newnode) is about to flood oldnode, if it has
        -- `floodable = true` in the nodedef. Not called for bulk node placement
        -- (i.e. schematics and VoxelManip) or air nodes. If return true the
        -- node is not flooded, but on_flood callback will most likely be called
        -- over and over again every liquid update interval.
        -- Default: nil
        -- Warning: making a liquid node 'floodable' will cause problems.

        preserve_metadata = function(pos, oldnode, oldmeta, drops),
        -- Called when `oldnode` is about be converted to an item, but before the
        -- node is deleted from the world or the drops are added. This is
        -- generally the result of either the node being dug or an attached node
        -- becoming detached.
        -- * `pos`: node position
        -- * `oldnode`: node table of node before it was deleted
        -- * `oldmeta`: metadata of node before it was deleted, as a metadata table
        -- * `drops`: a table of `ItemStack`s, so any metadata to be preserved can
        --   be added directly to one or more of the dropped items. See
        --   "ItemStackMetaRef".
        -- default: `nil`

        after_place_node = function(pos, placer, itemstack, pointed_thing),
        -- Called after constructing node when node was placed using
        -- minetest.item_place_node / minetest.place_node.
        -- If return true no item is taken from itemstack.
        -- `placer` may be any valid ObjectRef or nil.
        -- default: nil

        after_dig_node = function(pos, oldnode, oldmetadata, digger),
        -- Called after destructing the node when node was dug using
        -- `minetest.node_dig` / `minetest.dig_node`.
        -- * `pos`: node position
        -- * `oldnode`: node table of node before it was dug
        -- * `oldmetadata`: metadata of node before it was dug,
        --                  as a metadata table
        -- * `digger`: ObjectRef of digger
        -- default: nil

        can_dig = function(pos, [player]),
        -- Returns true if node can be dug, or false if not.
        -- default: nil

        on_punch = function(pos, node, puncher, pointed_thing),
        -- default: minetest.node_punch
        -- Called when puncher (an ObjectRef) punches the node at pos.
        -- By default calls minetest.register_on_punchnode callbacks.

        on_rightclick = function(pos, node, clicker, itemstack, pointed_thing),
        -- default: nil
        -- Called when clicker (an ObjectRef) used the 'place/build' key
        -- (not necessarily an actual rightclick)
        -- while pointing at the node at pos with 'node' being the node table.
        -- itemstack will hold clicker's wielded item.
        -- Shall return the leftover itemstack.
        -- Note: pointed_thing can be nil, if a mod calls this function.
        -- This function does not get triggered by clients <=0.4.16 if the
        -- "formspec" node metadata field is set.

        on_dig = function(pos, node, digger),
        -- default: minetest.node_dig
        -- By default checks privileges, wears out item (if tool) and removes node.
        -- return true if the node was dug successfully, false otherwise.
        -- Deprecated: returning nil is the same as returning true.

        on_timer = function(pos, elapsed),
        -- default: nil
        -- called by NodeTimers, see minetest.get_node_timer and NodeTimerRef.
        -- elapsed is the total time passed since the timer was started.
        -- return true to run the timer for another cycle with the same timeout
        -- value.

        on_receive_fields = function(pos, formname, fields, sender),
        -- fields = {name1 = value1, name2 = value2, ...}
        -- Called when an UI form (e.g. sign text input) returns data.
        -- See minetest.register_on_player_receive_fields for more info.
        -- default: nil

        allow_metadata_inventory_move = function(pos, from_list, from_index, to_list, to_index, count, player),
        -- Called when a player wants to move items inside the inventory.
        -- Return value: number of items allowed to move.

        allow_metadata_inventory_put = function(pos, listname, index, stack, player),
        -- Called when a player wants to put something into the inventory.
        -- Return value: number of items allowed to put.
        -- Return value -1: Allow and don't modify item count in inventory.

        allow_metadata_inventory_take = function(pos, listname, index, stack, player),
        -- Called when a player wants to take something out of the inventory.
        -- Return value: number of items allowed to take.
        -- Return value -1: Allow and don't modify item count in inventory.

        on_metadata_inventory_move = function(pos, from_list, from_index, to_list, to_index, count, player),
        on_metadata_inventory_put = function(pos, listname, index, stack, player),
        on_metadata_inventory_take = function(pos, listname, index, stack, player),
        -- Called after the actual action has happened, according to what was
        -- allowed.
        -- No return value.

        on_blast = function(pos, intensity),
        -- intensity: 1.0 = mid range of regular TNT.
        -- If defined, called when an explosion touches the node, instead of
        -- removing the node.

        mod_origin = "modname",
        -- stores which mod actually registered a node
        -- If the source could not be determined it contains "??"
        -- Useful for getting which mod truly registered something
        -- example: if a node is registered as ":othermodname:nodename",
        -- nodename will show "othermodname", but mod_origin will say "modname"
    }
    on_construct = function(pos),
    -- Node constructor; called after adding node.
    -- Can set up metadata and stuff like that.
    -- Not called for bulk node placement (i.e. schematics and VoxelManip).
    -- Note: Within an on_construct callback, minetest.set_node can cause an
    -- infinite loop if it invokes the same callback.
    --  Consider using minetest.swap_node instead.
    -- default: nil

    on_destruct = function(pos),
    -- Node destructor; called before removing node.
    -- Not called for bulk node placement.
    -- default: nil

    after_destruct = function(pos, oldnode),
    -- Node destructor; called after removing node.
    -- Not called for bulk node placement.
    -- default: nil

    on_flood = function(pos, oldnode, newnode),
    -- Called when a liquid (newnode) is about to flood oldnode, if it has
    -- `floodable = true` in the nodedef. Not called for bulk node placement
    -- (i.e. schematics and VoxelManip) or air nodes. If return true the
    -- node is not flooded, but on_flood callback will most likely be called
    -- over and over again every liquid update interval.
    -- Default: nil
    -- Warning: making a liquid node 'floodable' will cause problems.

    preserve_metadata = function(pos, oldnode, oldmeta, drops),
    -- Called when `oldnode` is about be converted to an item, but before the
    -- node is deleted from the world or the drops are added. This is
    -- generally the result of either the node being dug or an attached node
    -- becoming detached.
    -- * `pos`: node position
    -- * `oldnode`: node table of node before it was deleted
    -- * `oldmeta`: metadata of node before it was deleted, as a metadata table
    -- * `drops`: a table of `ItemStack`s, so any metadata to be preserved can
    --   be added directly to one or more of the dropped items. See
    --   "ItemStackMetaRef".
    -- default: `nil`

    after_place_node = function(pos, placer, itemstack, pointed_thing),
    -- Called after constructing node when node was placed using
    -- minetest.item_place_node / minetest.place_node.
    -- If return true no item is taken from itemstack.
    -- `placer` may be any valid ObjectRef or nil.
    -- default: nil

    after_dig_node = function(pos, oldnode, oldmetadata, digger),
    -- Called after destructing the node when node was dug using
    -- `minetest.node_dig` / `minetest.dig_node`.
    -- * `pos`: node position
    -- * `oldnode`: node table of node before it was dug
    -- * `oldmetadata`: metadata of node before it was dug,
    --                  as a metadata table
    -- * `digger`: ObjectRef of digger
    -- default: nil

    can_dig = function(pos, [player]),
    -- Returns true if node can be dug, or false if not.
    -- default: nil

    on_punch = function(pos, node, puncher, pointed_thing),
    -- default: minetest.node_punch
    -- Called when puncher (an ObjectRef) punches the node at pos.
    -- By default calls minetest.register_on_punchnode callbacks.

    on_rightclick = function(pos, node, clicker, itemstack, pointed_thing),
    -- default: nil
    -- Called when clicker (an ObjectRef) used the 'place/build' key
    -- (not necessarily an actual rightclick)
    -- while pointing at the node at pos with 'node' being the node table.
    -- itemstack will hold clicker's wielded item.
    -- Shall return the leftover itemstack.
    -- Note: pointed_thing can be nil, if a mod calls this function.
    -- This function does not get triggered by clients <=0.4.16 if the
    -- "formspec" node metadata field is set.

    on_dig = function(pos, node, digger),
    -- default: minetest.node_dig
    -- By default checks privileges, wears out item (if tool) and removes node.
    -- return true if the node was dug successfully, false otherwise.
    -- Deprecated: returning nil is the same as returning true.

    on_timer = function(pos, elapsed),
    -- default: nil
    -- called by NodeTimers, see minetest.get_node_timer and NodeTimerRef.
    -- elapsed is the total time passed since the timer was started.
    -- return true to run the timer for another cycle with the same timeout
    -- value.

    on_receive_fields = function(pos, formname, fields, sender),
    -- fields = {name1 = value1, name2 = value2, ...}
    -- Called when an UI form (e.g. sign text input) returns data.
    -- See minetest.register_on_player_receive_fields for more info.
    -- default: nil

    allow_metadata_inventory_move = function(pos, from_list, from_index, to_list, to_index, count, player),
    -- Called when a player wants to move items inside the inventory.
    -- Return value: number of items allowed to move.

    allow_metadata_inventory_put = function(pos, listname, index, stack, player),
    -- Called when a player wants to put something into the inventory.
    -- Return value: number of items allowed to put.
    -- Return value -1: Allow and don't modify item count in inventory.

    allow_metadata_inventory_take = function(pos, listname, index, stack, player),
    -- Called when a player wants to take something out of the inventory.
    -- Return value: number of items allowed to take.
    -- Return value -1: Allow and don't modify item count in inventory.

    on_metadata_inventory_move = function(pos, from_list, from_index, to_list, to_index, count, player),
    on_metadata_inventory_put = function(pos, listname, index, stack, player),
    on_metadata_inventory_take = function(pos, listname, index, stack, player),
    -- Called after the actual action has happened, according to what was
    -- allowed.
    -- No return value.

    on_blast = function(pos, intensity),
    -- intensity: 1.0 = mid range of regular TNT.
    -- If defined, called when an explosion touches the node, instead of
    -- removing the node.

    mod_origin = "modname",
    -- stores which mod actually registered a node
    -- If the source could not be determined it contains "??"
    -- Useful for getting which mod truly registered something
    -- example: if a node is registered as ":othermodname:nodename",
    -- nodename will show "othermodname", but mod_origin will say "modname"
}
```

Crafting recipes
----------------


@@ 8847,85 8960,93 @@ Parameters:

A typical shaped recipe:

    -- Stone pickaxe
    {
        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 = {
            {"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.
    }
```lua
-- Stone pickaxe
{
    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 = {
        {"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"},
        },
    }
```lua
-- 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"},
        },
    }
```lua
-- 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"},
        },
    }
```lua
-- 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"},
    },
}
```

### Shapeless



@@ 8944,17 9065,19 @@ Parameters:

#### 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 = "example:mushroom_stew",
        recipe = {
            "example:bowl",
            "example:mushroom_brown",
            "example:mushroom_red",
        },
    }
```lua
{
    -- 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 = "example:mushroom_stew",
    recipe = {
        "example:bowl",
        "example:mushroom_brown",
        "example:mushroom_red",
    },
}
```

### Tool repair



@@ 9010,12 9133,14 @@ cases, e.g. for a super furnace that cooks items twice as fast.

Cooking sand to glass in 3 seconds:

    {
        type = "cooking",
        output = "example:glass",
        recipe = "example:sand",
        cooktime = 3.0,
    }
```lua
{
    type = "cooking",
    output = "example:glass",
    recipe = "example:sand",
    cooktime = 3.0,
}
```

### Fuel



@@ 9045,21 9170,25 @@ long.

Coal lump with a burntime of 20 seconds. Will be consumed when used.

    {
        type = "fuel",
        recipe = "example:coal_lump",
        burntime = 20.0,
    }
```lua
{
    type = "fuel",
    recipe = "example:coal_lump",
    burntime = 20.0,
}
```

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"}},
    }
```lua
{
    type = "fuel",
    recipe = "example:lava_bucket",
    burntime = 60.0,
    replacements = {{"example:lava_bucket", "example:empty_bucket"}},
}
```

Ore definition
--------------


@@ 9068,103 9197,105 @@ Used by `minetest.register_ore`.

See [Ores] section above for essential information.

    {
        ore_type = "",
        -- Supported: "scatter", "sheet", "puff", "blob", "vein", "stratum"
```lua
{
    ore_type = "",
    -- Supported: "scatter", "sheet", "puff", "blob", "vein", "stratum"

        ore = "",
        -- Ore node to place
    ore = "",
    -- Ore node to place

        ore_param2 = 0,
        -- Param2 to set for ore (e.g. facedir rotation)
    ore_param2 = 0,
    -- Param2 to set for ore (e.g. facedir rotation)

        wherein = "",
        -- Node to place ore in. Multiple are possible by passing a list.
    wherein = "",
    -- Node to place ore in. Multiple are possible by passing a list.

        clust_scarcity = 8 * 8 * 8,
        -- Ore has a 1 out of clust_scarcity chance of spawning in a node.
        -- If the desired average distance between ores is 'd', set this to
        -- d * d * d.
    clust_scarcity = 8 * 8 * 8,
    -- Ore has a 1 out of clust_scarcity chance of spawning in a node.
    -- If the desired average distance between ores is 'd', set this to
    -- d * d * d.

        clust_num_ores = 8,
        -- Number of ores in a cluster
    clust_num_ores = 8,
    -- Number of ores in a cluster

        clust_size = 3,
        -- Size of the bounding box of the cluster.
        -- In this example, there is a 3 * 3 * 3 cluster where 8 out of the 27
        -- nodes are coal ore.
    clust_size = 3,
    -- Size of the bounding box of the cluster.
    -- In this example, there is a 3 * 3 * 3 cluster where 8 out of the 27
    -- nodes are coal ore.

        y_min = -31000,
        y_max = 31000,
        -- Lower and upper limits for ore (inclusive)
    y_min = -31000,
    y_max = 31000,
    -- Lower and upper limits for ore (inclusive)

        flags = "",
        -- Attributes for the ore generation, see 'Ore attributes' section above
    flags = "",
    -- Attributes for the ore generation, see 'Ore attributes' section above

        noise_threshold = 0,
        -- If noise is above this threshold, ore is placed. Not needed for a
        -- uniform distribution.
    noise_threshold = 0,
    -- If noise is above this threshold, ore is placed. Not needed for a
    -- uniform distribution.

        noise_params = {
            offset = 0,
            scale = 1,
            spread = {x = 100, y = 100, z = 100},
            seed = 23,
            octaves = 3,
            persistence = 0.7
        },
        -- NoiseParams structure describing one of the perlin noises used for
        -- ore distribution.
        -- Needed by "sheet", "puff", "blob" and "vein" ores.
        -- Omit from "scatter" ore for a uniform ore distribution.
        -- Omit from "stratum" ore for a simple horizontal strata from y_min to
        -- y_max.

        biomes = {"desert", "rainforest"},
        -- List of biomes in which this ore occurs.
        -- Occurs in all biomes if this is omitted, and ignored if the Mapgen
        -- being used does not support biomes.
        -- Can be a list of (or a single) biome names, IDs, or definitions.

        -- Type-specific parameters

        -- "sheet"
        column_height_min = 1,
        column_height_max = 16,
        column_midpoint_factor = 0.5,

        -- "puff"
        np_puff_top = {
            offset = 4,
            scale = 2,
            spread = {x = 100, y = 100, z = 100},
            seed = 47,
            octaves = 3,
            persistence = 0.7
        },
        np_puff_bottom = {
            offset = 4,
            scale = 2,
            spread = {x = 100, y = 100, z = 100},
            seed = 11,
            octaves = 3,
            persistence = 0.7
        },
    noise_params = {
        offset = 0,
        scale = 1,
        spread = {x = 100, y = 100, z = 100},
        seed = 23,
        octaves = 3,
        persistence = 0.7
    },
    -- NoiseParams structure describing one of the perlin noises used for
    -- ore distribution.
    -- Needed by "sheet", "puff", "blob" and "vein" ores.
    -- Omit from "scatter" ore for a uniform ore distribution.
    -- Omit from "stratum" ore for a simple horizontal strata from y_min to
    -- y_max.

    biomes = {"desert", "rainforest"},
    -- List of biomes in which this ore occurs.
    -- Occurs in all biomes if this is omitted, and ignored if the Mapgen
    -- being used does not support biomes.
    -- Can be a list of (or a single) biome names, IDs, or definitions.

    -- Type-specific parameters

    -- "sheet"
    column_height_min = 1,
    column_height_max = 16,
    column_midpoint_factor = 0.5,

    -- "puff"
    np_puff_top = {
        offset = 4,
        scale = 2,
        spread = {x = 100, y = 100, z = 100},
        seed = 47,
        octaves = 3,
        persistence = 0.7
    },
    np_puff_bottom = {
        offset = 4,
        scale = 2,
        spread = {x = 100, y = 100, z = 100},
        seed = 11,
        octaves = 3,
        persistence = 0.7
    },

        -- "vein"
        random_factor = 1.0,

        -- "stratum"
        np_stratum_thickness = {
            offset = 8,
            scale = 4,
            spread = {x = 100, y = 100, z = 100},
            seed = 17,
            octaves = 3,
            persistence = 0.7
        },
        stratum_thickness = 8, -- only used if no noise defined
    }
    -- "vein"
    random_factor = 1.0,

    -- "stratum"
    np_stratum_thickness = {
        offset = 8,
        scale = 4,
        spread = {x = 100, y = 100, z = 100},
        seed = 17,
        octaves = 3,
        persistence = 0.7
    },
    stratum_thickness = 8, -- only used if no noise defined
}
```

Biome definition
----------------


@@ 9175,245 9306,249 @@ The maximum number of biomes that can be used is 65535. However, using an
excessive number of biomes will slow down map generation. Depending on desired
performance and computing power the practical limit is much lower.

    {
        name = "tundra",

        node_dust = "default:snow",
        -- Node dropped onto upper surface after all else is generated

        node_top = "default:dirt_with_snow",
        depth_top = 1,
        -- Node forming surface layer of biome and thickness of this layer

        node_filler = "default:permafrost",
        depth_filler = 3,
        -- Node forming lower layer of biome and thickness of this layer

        node_stone = "default:bluestone",
        -- Node that replaces all stone nodes between roughly y_min and y_max.

        node_water_top = "default:ice",
        depth_water_top = 10,
        -- Node forming a surface layer in seawater with the defined thickness

        node_water = "",
        -- Node that replaces all seawater nodes not in the surface layer

        node_river_water = "default:ice",
        -- Node that replaces river water in mapgens that use
        -- default:river_water

        node_riverbed = "default:gravel",
        depth_riverbed = 2,
        -- Node placed under river water and thickness of this layer

        node_cave_liquid = "default:lava_source",
        node_cave_liquid = {"default:water_source", "default:lava_source"},
        -- Nodes placed inside 50% of the medium size caves.
        -- Multiple nodes can be specified, each cave will use a randomly
        -- chosen node from the list.
        -- If this field is left out or 'nil', cave liquids fall back to
        -- classic behavior of lava and water distributed using 3D noise.
        -- For no cave liquid, specify "air".

        node_dungeon = "default:cobble",
        -- Node used for primary dungeon structure.
        -- If absent, dungeon nodes fall back to the 'mapgen_cobble' mapgen
        -- alias, if that is also absent, dungeon nodes fall back to the biome
        -- 'node_stone'.
        -- If present, the following two nodes are also used.

        node_dungeon_alt = "default:mossycobble",
        -- Node used for randomly-distributed alternative structure nodes.
        -- If alternative structure nodes are not wanted leave this absent.

        node_dungeon_stair = "stairs:stair_cobble",
        -- Node used for dungeon stairs.
        -- If absent, stairs fall back to 'node_dungeon'.

        y_max = 31000,
        y_min = 1,
        -- Upper and lower limits for biome.
        -- Alternatively you can use xyz limits as shown below.

        max_pos = {x = 31000, y = 128, z = 31000},
        min_pos = {x = -31000, y = 9, z = -31000},
        -- xyz limits for biome, an alternative to using 'y_min' and 'y_max'.
        -- Biome is limited to a cuboid defined by these positions.
        -- Any x, y or z field left undefined defaults to -31000 in 'min_pos' or
        -- 31000 in 'max_pos'.

        vertical_blend = 8,
        -- Vertical distance in nodes above 'y_max' over which the biome will
        -- blend with the biome above.
        -- Set to 0 for no vertical blend. Defaults to 0.

        heat_point = 0,
        humidity_point = 50,
        -- Characteristic temperature and humidity for the biome.
        -- These values create 'biome points' on a voronoi diagram with heat and
        -- humidity as axes. The resulting voronoi cells determine the
        -- distribution of the biomes.
        -- Heat and humidity have average values of 50, vary mostly between
        -- 0 and 100 but can exceed these values.
    }
```lua
{
    name = "tundra",

    node_dust = "default:snow",
    -- Node dropped onto upper surface after all else is generated

    node_top = "default:dirt_with_snow",
    depth_top = 1,
    -- Node forming surface layer of biome and thickness of this layer

    node_filler = "default:permafrost",
    depth_filler = 3,
    -- Node forming lower layer of biome and thickness of this layer

    node_stone = "default:bluestone",
    -- Node that replaces all stone nodes between roughly y_min and y_max.

    node_water_top = "default:ice",
    depth_water_top = 10,
    -- Node forming a surface layer in seawater with the defined thickness

    node_water = "",
    -- Node that replaces all seawater nodes not in the surface layer

    node_river_water = "default:ice",
    -- Node that replaces river water in mapgens that use
    -- default:river_water

    node_riverbed = "default:gravel",
    depth_riverbed = 2,
    -- Node placed under river water and thickness of this layer

    node_cave_liquid = "default:lava_source",
    node_cave_liquid = {"default:water_source", "default:lava_source"},
    -- Nodes placed inside 50% of the medium size caves.
    -- Multiple nodes can be specified, each cave will use a randomly
    -- chosen node from the list.
    -- If this field is left out or 'nil', cave liquids fall back to
    -- classic behavior of lava and water distributed using 3D noise.
    -- For no cave liquid, specify "air".

    node_dungeon = "default:cobble",
    -- Node used for primary dungeon structure.
    -- If absent, dungeon nodes fall back to the 'mapgen_cobble' mapgen
    -- alias, if that is also absent, dungeon nodes fall back to the biome
    -- 'node_stone'.
    -- If present, the following two nodes are also used.

    node_dungeon_alt = "default:mossycobble",
    -- Node used for randomly-distributed alternative structure nodes.
    -- If alternative structure nodes are not wanted leave this absent.

    node_dungeon_stair = "stairs:stair_cobble",
    -- Node used for dungeon stairs.
    -- If absent, stairs fall back to 'node_dungeon'.

    y_max = 31000,
    y_min = 1,
    -- Upper and lower limits for biome.
    -- Alternatively you can use xyz limits as shown below.

    max_pos = {x = 31000, y = 128, z = 31000},
    min_pos = {x = -31000, y = 9, z = -31000},
    -- xyz limits for biome, an alternative to using 'y_min' and 'y_max'.
    -- Biome is limited to a cuboid defined by these positions.
    -- Any x, y or z field left undefined defaults to -31000 in 'min_pos' or
    -- 31000 in 'max_pos'.

    vertical_blend = 8,
    -- Vertical distance in nodes above 'y_max' over which the biome will
    -- blend with the biome above.
    -- Set to 0 for no vertical blend. Defaults to 0.

    heat_point = 0,
    humidity_point = 50,
    -- Characteristic temperature and humidity for the biome.
    -- These values create 'biome points' on a voronoi diagram with heat and
    -- humidity as axes. The resulting voronoi cells determine the
    -- distribution of the biomes.
    -- Heat and humidity have average values of 50, vary mostly between
    -- 0 and 100 but can exceed these values.
}
```

Decoration definition
---------------------

See [Decoration types]. Used by `minetest.register_decoration`.

    {
        deco_type = "simple",
        -- Type. "simple" or "schematic" supported

        place_on = "default:dirt_with_grass",
        -- Node (or list of nodes) that the decoration can be placed on

        sidelen = 8,
        -- Size of the square (X / Z) divisions of the mapchunk being generated.
        -- Determines the resolution of noise variation if used.
        -- If the chunk size is not evenly divisible by sidelen, sidelen is made
        -- equal to the chunk size.

        fill_ratio = 0.02,
        -- The value determines 'decorations per surface node'.
        -- Used only if noise_params is not specified.
        -- If >= 10.0 complete coverage is enabled and decoration placement uses
        -- a different and much faster method.

        noise_params = {
            offset = 0,
            scale = 0.45,
            spread = {x = 100, y = 100, z = 100},
            seed = 354,
            octaves = 3,
            persistence = 0.7,
            lacunarity = 2.0,
            flags = "absvalue"
```lua
{
    deco_type = "simple",
    -- Type. "simple" or "schematic" supported

    place_on = "default:dirt_with_grass",
    -- Node (or list of nodes) that the decoration can be placed on

    sidelen = 8,
    -- Size of the square (X / Z) divisions of the mapchunk being generated.
    -- Determines the resolution of noise variation if used.
    -- If the chunk size is not evenly divisible by sidelen, sidelen is made
    -- equal to the chunk size.

    fill_ratio = 0.02,
    -- The value determines 'decorations per surface node'.
    -- Used only if noise_params is not specified.
    -- If >= 10.0 complete coverage is enabled and decoration placement uses
    -- a different and much faster method.

    noise_params = {
        offset = 0,
        scale = 0.45,
        spread = {x = 100, y = 100, z = 100},
        seed = 354,
        octaves = 3,
        persistence = 0.7,
        lacunarity = 2.0,
        flags = "absvalue"
    },
    -- NoiseParams structure describing the perlin noise used for decoration
    -- distribution.
    -- A noise value is calculated for each square division and determines
    -- 'decorations per surface node' within each division.
    -- If the noise value >= 10.0 complete coverage is enabled and
    -- decoration placement uses a different and much faster method.

    biomes = {"Oceanside", "Hills", "Plains"},
    -- List of biomes in which this decoration occurs. Occurs in all biomes
    -- if this is omitted, and ignored if the Mapgen being used does not
    -- support biomes.
    -- Can be a list of (or a single) biome names, IDs, or definitions.

    y_min = -31000,
    y_max = 31000,
    -- Lower and upper limits for decoration (inclusive).
    -- These parameters refer to the Y co-ordinate of the 'place_on' node.

    spawn_by = "default:water",
    -- Node (or list of nodes) that the decoration only spawns next to.
    -- Checks the 8 neighboring nodes on the same Y, and also the ones
    -- at Y+1, excluding both center nodes.

    num_spawn_by = 1,
    -- Number of spawn_by nodes that must be surrounding the decoration
    -- position to occur.
    -- If absent or -1, decorations occur next to any nodes.

    flags = "liquid_surface, force_placement, all_floors, all_ceilings",
    -- Flags for all decoration types.
    -- "liquid_surface": Instead of placement on the highest solid surface
    --   in a mapchunk column, placement is on the highest liquid surface.
    --   Placement is disabled if solid nodes are found above the liquid
    --   surface.
    -- "force_placement": Nodes other than "air" and "ignore" are replaced
    --   by the decoration.
    -- "all_floors", "all_ceilings": Instead of placement on the highest
    --   surface in a mapchunk the decoration is placed on all floor and/or
    --   ceiling surfaces, for example in caves and dungeons.
    --   Ceiling decorations act as an inversion of floor decorations so the
    --   effect of 'place_offset_y' is inverted.
    --   Y-slice probabilities do not function correctly for ceiling
    --   schematic decorations as the behavior is unchanged.
    --   If a single decoration registration has both flags the floor and
    --   ceiling decorations will be aligned vertically.

    ----- Simple-type parameters

    decoration = "default:grass",
    -- The node name used as the decoration.
    -- If instead a list of strings, a randomly selected node from the list
    -- is placed as the decoration.

    height = 1,
    -- Decoration height in nodes.
    -- If height_max is not 0, this is the lower limit of a randomly
    -- selected height.

    height_max = 0,
    -- Upper limit of the randomly selected height.
    -- If absent, the parameter 'height' is used as a constant.

    param2 = 0,
    -- Param2 value of decoration nodes.
    -- If param2_max is not 0, this is the lower limit of a randomly
    -- selected param2.

    param2_max = 0,
    -- Upper limit of the randomly selected param2.
    -- If absent, the parameter 'param2' is used as a constant.

    place_offset_y = 0,
    -- Y offset of the decoration base node relative to the standard base
    -- node position.
    -- Can be positive or negative. Default is 0.
    -- Effect is inverted for "all_ceilings" decorations.
    -- Ignored by 'y_min', 'y_max' and 'spawn_by' checks, which always refer
    -- to the 'place_on' node.

    ----- Schematic-type parameters

    schematic = "foobar.mts",
    -- If schematic is a string, it is the filepath relative to the current
    -- working directory of the specified Minetest schematic file.
    -- Could also be the ID of a previously registered schematic.

    schematic = {
        size = {x = 4, y = 6, z = 4},
        data = {
            {name = "default:cobble", param1 = 255, param2 = 0},
            {name = "default:dirt_with_grass", param1 = 255, param2 = 0},
            {name = "air", param1 = 255, param2 = 0},
              ...
        },
        -- NoiseParams structure describing the perlin noise used for decoration
        -- distribution.
        -- A noise value is calculated for each square division and determines
        -- 'decorations per surface node' within each division.
        -- If the noise value >= 10.0 complete coverage is enabled and
        -- decoration placement uses a different and much faster method.

        biomes = {"Oceanside", "Hills", "Plains"},
        -- List of biomes in which this decoration occurs. Occurs in all biomes
        -- if this is omitted, and ignored if the Mapgen being used does not
        -- support biomes.
        -- Can be a list of (or a single) biome names, IDs, or definitions.

        y_min = -31000,
        y_max = 31000,
        -- Lower and upper limits for decoration (inclusive).
        -- These parameters refer to the Y co-ordinate of the 'place_on' node.

        spawn_by = "default:water",
        -- Node (or list of nodes) that the decoration only spawns next to.
        -- Checks the 8 neighboring nodes on the same Y, and also the ones
        -- at Y+1, excluding both center nodes.

        num_spawn_by = 1,
        -- Number of spawn_by nodes that must be surrounding the decoration
        -- position to occur.
        -- If absent or -1, decorations occur next to any nodes.

        flags = "liquid_surface, force_placement, all_floors, all_ceilings",
        -- Flags for all decoration types.
        -- "liquid_surface": Instead of placement on the highest solid surface
        --   in a mapchunk column, placement is on the highest liquid surface.
        --   Placement is disabled if solid nodes are found above the liquid
        --   surface.
        -- "force_placement": Nodes other than "air" and "ignore" are replaced
        --   by the decoration.
        -- "all_floors", "all_ceilings": Instead of placement on the highest
        --   surface in a mapchunk the decoration is placed on all floor and/or
        --   ceiling surfaces, for example in caves and dungeons.
        --   Ceiling decorations act as an inversion of floor decorations so the
        --   effect of 'place_offset_y' is inverted.
        --   Y-slice probabilities do not function correctly for ceiling
        --   schematic decorations as the behavior is unchanged.
        --   If a single decoration registration has both flags the floor and
        --   ceiling decorations will be aligned vertically.

        ----- Simple-type parameters

        decoration = "default:grass",
        -- The node name used as the decoration.
        -- If instead a list of strings, a randomly selected node from the list
        -- is placed as the decoration.

        height = 1,
        -- Decoration height in nodes.
        -- If height_max is not 0, this is the lower limit of a randomly
        -- selected height.

        height_max = 0,
        -- Upper limit of the randomly selected height.
        -- If absent, the parameter 'height' is used as a constant.

        param2 = 0,
        -- Param2 value of decoration nodes.
        -- If param2_max is not 0, this is the lower limit of a randomly
        -- selected param2.

        param2_max = 0,
        -- Upper limit of the randomly selected param2.
        -- If absent, the parameter 'param2' is used as a constant.

        place_offset_y = 0,
        -- Y offset of the decoration base node relative to the standard base
        -- node position.
        -- Can be positive or negative. Default is 0.
        -- Effect is inverted for "all_ceilings" decorations.
        -- Ignored by 'y_min', 'y_max' and 'spawn_by' checks, which always refer
        -- to the 'place_on' node.

        ----- Schematic-type parameters

        schematic = "foobar.mts",
        -- If schematic is a string, it is the filepath relative to the current
        -- working directory of the specified Minetest schematic file.
        -- Could also be the ID of a previously registered schematic.

        schematic = {
            size = {x = 4, y = 6, z = 4},
            data = {
                {name = "default:cobble", param1 = 255, param2 = 0},
                {name = "default:dirt_with_grass", param1 = 255, param2 = 0},
                {name = "air", param1 = 255, param2 = 0},
                 ...
            },
            yslice_prob = {
                {ypos = 2, prob = 128},
                {ypos = 5, prob = 64},
                 ...
            },
        yslice_prob = {
            {ypos = 2, prob = 128},
            {ypos = 5, prob = 64},
              ...
        },
        -- Alternative schematic specification by supplying a table. The fields
        -- size and data are mandatory whereas yslice_prob is optional.
        -- See 'Schematic specifier' for details.

        replacements = {["oldname"] = "convert_to", ...},
        -- Map of node names to replace in the schematic after reading it.

        flags = "place_center_x, place_center_y, place_center_z",
        -- Flags for schematic decorations. See 'Schematic attributes'.

        rotation = "90",
        -- Rotation can be "0", "90", "180", "270", or "random"

        place_offset_y = 0,
        -- If the flag 'place_center_y' is set this parameter is ignored.
        -- Y offset of the schematic base node layer relative to the 'place_on'
        -- node.
        -- Can be positive or negative. Default is 0.
        -- Effect is inverted for "all_ceilings" decorations.
        -- Ignored by 'y_min', 'y_max' and 'spawn_by' checks, which always refer
        -- to the 'place_on' node.
    }
    },
    -- Alternative schematic specification by supplying a table. The fields
    -- size and data are mandatory whereas yslice_prob is optional.
    -- See 'Schematic specifier' for details.

    replacements = {["oldname"] = "convert_to", ...},
    -- Map of node names to replace in the schematic after reading it.

    flags = "place_center_x, place_center_y, place_center_z",
    -- Flags for schematic decorations. See 'Schematic attributes'.

    rotation = "90",
    -- Rotation can be "0", "90", "180", "270", or "random"

    place_offset_y = 0,
    -- If the flag 'place_center_y' is set this parameter is ignored.
    -- Y offset of the schematic base node layer relative to the 'place_on'
    -- node.
    -- Can be positive or negative. Default is 0.
    -- Effect is inverted for "all_ceilings" decorations.
    -- Ignored by 'y_min', 'y_max' and 'spawn_by' checks, which always refer
    -- to the 'place_on' node.
}
```

Chat command definition
-----------------------


@@ 9424,25 9559,27 @@ Specifies the function to be called and the privileges required when a player
issues the command.  A help message that is the concatenation of the params and
description fields is shown when the "/help" chatcommand is issued.

    {
        params = "",
        -- Short parameter description.  See the below note.

        description = "",
        -- General description of the command's purpose.

        privs = {},
        -- Required privileges to run. See `minetest.check_player_privs()` for
        -- the format and see [Privileges] for an overview of privileges.

        func = function(name, param),
        -- Called when command is run.
        -- * `name` is the name of the player who issued the command.
        -- * `param` is a string with the full arguments to the command.
        -- Returns a boolean for success and a string value.
        -- The string is shown to the issuing player upon exit of `func` or,
        -- if `func` returns `false` and no string, the help message is shown.
    }
```lua
{
    params = "",
    -- Short parameter description.  See the below note.

    description = "",
    -- General description of the command's purpose.

    privs = {},
    -- Required privileges to run. See `minetest.check_player_privs()` for
    -- the format and see [Privileges] for an overview of privileges.

    func = function(name, param),
    -- Called when command is run.
    -- * `name` is the name of the player who issued the command.
    -- * `param` is a string with the full arguments to the command.
    -- Returns a boolean for success and a string value.
    -- The string is shown to the issuing player upon exit of `func` or,
    -- if `func` returns `false` and no string, the help message is shown.
}
```

Note that in params, the conventional use of symbols is as follows:



@@ 9458,74 9595,80 @@ Note that in params, the conventional use of symbols is as follows:

Example:

    {
        params = "<name> <privilege>",
```lua
{
    params = "<name> <privilege>",

        description = "Remove privilege from player",
    description = "Remove privilege from player",

        privs = {privs=true},  -- Require the "privs" privilege to run
    privs = {privs=true},  -- Require the "privs" privilege to run

        func = function(name, param),
    }
    func = function(name, param),
}
```

Privilege definition
--------------------

Used by `minetest.register_privilege`.

    {
        description = "",
        -- Privilege description
```lua
{
    description = "",
    -- Privilege description

        give_to_singleplayer = true,
        -- Whether to grant the privilege to singleplayer.
    give_to_singleplayer = true,
    -- Whether to grant the privilege to singleplayer.

        give_to_admin = true,
        -- Whether to grant the privilege to the server admin.
        -- Uses value of 'give_to_singleplayer' by default.
    give_to_admin = true,
    -- Whether to grant the privilege to the server admin.
    -- Uses value of 'give_to_singleplayer' by default.

        on_grant = function(name, granter_name),
        -- Called when given to player 'name' by 'granter_name'.
        -- 'granter_name' will be nil if the priv was granted by a mod.
    on_grant = function(name, granter_name),
    -- Called when given to player 'name' by 'granter_name'.
    -- 'granter_name' will be nil if the priv was granted by a mod.

        on_revoke = function(name, revoker_name),
        -- Called when taken from player 'name' by 'revoker_name'.
        -- 'revoker_name' will be nil if the priv was revoked by a mod.
    on_revoke = function(name, revoker_name),
    -- Called when taken from player 'name' by 'revoker_name'.
    -- 'revoker_name' will be nil if the priv was revoked by a mod.

        -- Note that the above two callbacks will be called twice if a player is
        -- responsible, once with the player name, and then with a nil player
        -- name.
        -- Return true in the above callbacks to stop register_on_priv_grant or
        -- revoke being called.
    }
    -- Note that the above two callbacks will be called twice if a player is
    -- responsible, once with the player name, and then with a nil player
    -- name.
    -- Return true in the above callbacks to stop register_on_priv_grant or
    -- revoke being called.
}
```

Detached inventory callbacks
----------------------------

Used by `minetest.create_detached_inventory`.

    {
        allow_move = function(inv, from_list, from_index, to_list, to_index, count, player),
        -- Called when a player wants to move items inside the inventory.
        -- Return value: number of items allowed to move.

        allow_put = function(inv, listname, index, stack, player),
        -- Called when a player wants to put something into the inventory.
        -- Return value: number of items allowed to put.
        -- Return value -1: Allow and don't modify item count in inventory.

        allow_take = function(inv, listname, index, stack, player),
        -- Called when a player wants to take something out of the inventory.
        -- Return value: number of items allowed to take.
        -- Return value -1: Allow and don't modify item count in inventory.

        on_move = function(inv, from_list, from_index, to_list, to_index, count, player),
        on_put = function(inv, listname, index, stack, player),
        on_take = function(inv, listname, index, stack, player),
        -- Called after the actual action has happened, according to what was
        -- allowed.
        -- No return value.
    }
```lua
{
    allow_move = function(inv, from_list, from_index, to_list, to_index, count, player),
    -- Called when a player wants to move items inside the inventory.
    -- Return value: number of items allowed to move.

    allow_put = function(inv, listname, index, stack, player),
    -- Called when a player wants to put something into the inventory.
    -- Return value: number of items allowed to put.
    -- Return value -1: Allow and don't modify item count in inventory.

    allow_take = function(inv, listname, index, stack, player),
    -- Called when a player wants to take something out of the inventory.
    -- Return value: number of items allowed to take.
    -- Return value -1: Allow and don't modify item count in inventory.

    on_move = function(inv, from_list, from_index, to_list, to_index, count, player),
    on_put = function(inv, listname, index, stack, player),
    on_take = function(inv, listname, index, stack, player),
    -- Called after the actual action has happened, according to what was
    -- allowed.
    -- No return value.
}
```

HUD Definition
--------------


@@ 9535,110 9678,114 @@ documentation in [HUD] section.

Used by `ObjectRef:hud_add`. Returned by `ObjectRef:hud_get`.

    {
        hud_elem_type = "image",
        -- Type of element, can be "image", "text", "statbar", "inventory",
        -- "waypoint", "image_waypoint", "compass" or "minimap"
```lua
{
    hud_elem_type = "image",
    -- Type of element, can be "image", "text", "statbar", "inventory",
    -- "waypoint", "image_waypoint", "compass" or "minimap"

        position = {x=0.5, y=0.5},
        -- Top left corner position of element
    position = {x=0.5, y=0.5},
    -- Top left corner position of element

        name = "<name>",
    name = "<name>",

        scale = {x = 1, y = 1},
    scale = {x = 1, y = 1},

        text = "<text>",
    text = "<text>",

        text2 = "<text>",
    text2 = "<text>",

        number = 0,
    number = 0,

        item = 0,
    item = 0,

        direction = 0,
        -- Direction: 0: left-right, 1: right-left, 2: top-bottom, 3: bottom-top
    direction = 0,
    -- Direction: 0: left-right, 1: right-left, 2: top-bottom, 3: bottom-top

        alignment = {x=0, y=0},
    alignment = {x=0, y=0},

        offset = {x=0, y=0},
    offset = {x=0, y=0},

        world_pos = {x=0, y=0, z=0},
    world_pos = {x=0, y=0, z=0},

        size = {x=0, y=0},
    size = {x=0, y=0},

        z_index = 0,
        -- Z index: lower z-index HUDs are displayed behind higher z-index HUDs
    z_index = 0,
    -- Z index: lower z-index HUDs are displayed behind higher z-index HUDs

        style = 0,
    }
    style = 0,
}
```

Particle definition
-------------------

Used by `minetest.add_particle`.

    {
        pos = {x=0, y=0, z=0},
        velocity = {x=0, y=0, z=0},
        acceleration = {x=0, y=0, z=0},
        -- Spawn particle at pos with velocity and acceleration

        expirationtime = 1,
        -- Disappears after expirationtime seconds

        size = 1,
        -- Scales the visual size of the particle texture.
        -- If `node` is set, size can be set to 0 to spawn a randomly-sized
        -- particle (just like actual node dig particles).

        collisiondetection = false,
        -- If true collides with `walkable` nodes and, depending on the
        -- `object_collision` field, objects too.

        collision_removal = false,
        -- If true particle is removed when it collides.
        -- Requires collisiondetection = true to have any effect.

        object_collision = false,
        -- If true particle collides with objects that are defined as
        -- `physical = true,` and `collide_with_objects = true,`.
        -- Requires collisiondetection = true to have any effect.

        vertical = false,
        -- If true faces player using y axis only

        texture = "image.png",
        -- The texture of the particle
        -- v5.6.0 and later: also supports the table format described in the
        -- following section

        playername = "singleplayer",
        -- Optional, if specified spawns particle only on the player's client

        animation = {Tile Animation definition},
        -- Optional, specifies how to animate the particle texture

        glow = 0
        -- Optional, specify particle self-luminescence in darkness.
        -- Values 0-14.

        node = {name = "ignore", param2 = 0},
        -- Optional, if specified the particle will have the same appearance as
        -- node dig particles for the given node.
        -- `texture` and `animation` will be ignored if this is set.

        node_tile = 0,
        -- Optional, only valid in combination with `node`
        -- If set to a valid number 1-6, specifies the tile from which the
        -- particle texture is picked.
        -- Otherwise, the default behavior is used. (currently: any random tile)

        drag = {x=0, y=0, z=0},
        -- v5.6.0 and later: Optional drag value, consult the following section

        bounce = {min = ..., max = ..., bias = 0},
        -- v5.6.0 and later: Optional bounce range, consult the following section
    }
```lua
{
    pos = {x=0, y=0, z=0},
    velocity = {x=0, y=0, z=0},
    acceleration = {x=0, y=0, z=0},
    -- Spawn particle at pos with velocity and acceleration

    expirationtime = 1,
    -- Disappears after expirationtime seconds

    size = 1,
    -- Scales the visual size of the particle texture.
    -- If `node` is set, size can be set to 0 to spawn a randomly-sized
    -- particle (just like actual node dig particles).

    collisiondetection = false,
    -- If true collides with `walkable` nodes and, depending on the
    -- `object_collision` field, objects too.

    collision_removal = false,
    -- If true particle is removed when it collides.
    -- Requires collisiondetection = true to have any effect.

    object_collision = false,
    -- If true particle collides with objects that are defined as
    -- `physical = true,` and `collide_with_objects = true,`.
    -- Requires collisiondetection = true to have any effect.

    vertical = false,
    -- If true faces player using y axis only

    texture = "image.png",
    -- The texture of the particle
    -- v5.6.0 and later: also supports the table format described in the
    -- following section

    playername = "singleplayer",
    -- Optional, if specified spawns particle only on the player's client

    animation = {Tile Animation definition},
    -- Optional, specifies how to animate the particle texture

    glow = 0
    -- Optional, specify particle self-luminescence in darkness.
    -- Values 0-14.

    node = {name = "ignore", param2 = 0},
    -- Optional, if specified the particle will have the same appearance as
    -- node dig particles for the given node.
    -- `texture` and `animation` will be ignored if this is set.

    node_tile = 0,
    -- Optional, only valid in combination with `node`
    -- If set to a valid number 1-6, specifies the tile from which the
    -- particle texture is picked.
    -- Otherwise, the default behavior is used. (currently: any random tile)

    drag = {x=0, y=0, z=0},
    -- v5.6.0 and later: Optional drag value, consult the following section

    bounce = {min = ..., max = ..., bias = 0},
    -- v5.6.0 and later: Optional bounce range, consult the following section
}
```


`ParticleSpawner` definition


@@ 9657,82 9804,84 @@ The older syntax can be used in combination with the newer syntax (e.g. having
the new syntax will override the older syntax; on older servers, the newer syntax
will be ignored.

    {
        -- Common fields (same name and meaning in both new and legacy syntax)

        amount = 1,
        -- Number of particles spawned over the time period `time`.

        time = 1,
        -- Lifespan of spawner in seconds.
        -- If time is 0 spawner has infinite lifespan and spawns the `amount` on
        -- a per-second basis.

        collisiondetection = false,
        -- If true collide with `walkable` nodes and, depending on the
        -- `object_collision` field, objects too.

        collision_removal = false,
        -- If true particles are removed when they collide.
        -- Requires collisiondetection = true to have any effect.

        object_collision = false,
        -- If true particles collide with objects that are defined as
        -- `physical = true,` and `collide_with_objects = true,`.
        -- Requires collisiondetection = true to have any effect.

        attached = ObjectRef,
        -- If defined, particle positions, velocities and accelerations are
        -- relative to this object's position and yaw

        vertical = false,
        -- If true face player using y axis only

        texture = "image.png",
        -- The texture of the particle

        playername = "singleplayer",
        -- Optional, if specified spawns particles only on the player's client

        animation = {Tile Animation definition},
        -- Optional, specifies how to animate the particles' texture
        -- v5.6.0 and later: set length to -1 to synchronize the length
        -- of the animation with the expiration time of individual particles.
        -- (-2 causes the animation to be played twice, and so on)

        glow = 0,
        -- Optional, specify particle self-luminescence in darkness.
        -- Values 0-14.

        node = {name = "ignore", param2 = 0},
        -- Optional, if specified the particles will have the same appearance as
        -- node dig particles for the given node.
        -- `texture` and `animation` will be ignored if this is set.

        node_tile = 0,
        -- Optional, only valid in combination with `node`
        -- If set to a valid number 1-6, specifies the tile from which the
        -- particle texture is picked.
        -- Otherwise, the default behavior is used. (currently: any random tile)

        -- Legacy definition fields

        minpos = {x=0, y=0, z=0},
        maxpos = {x=0, y=0, z=0},
        minvel = {x=0, y=0, z=0},
        maxvel = {x=0, y=0, z=0},
        minacc = {x=0, y=0, z=0},
        maxacc = {x=0, y=0, z=0},
        minexptime = 1,
        maxexptime = 1,
        minsize = 1,
        maxsize = 1,
        -- The particles' properties are random values between the min and max
        -- values.
        -- applies to: pos, velocity, acceleration, expirationtime, size
        -- If `node` is set, min and maxsize can be set to 0 to spawn
        -- randomly-sized particles (just like actual node dig particles).
    }
```lua
{
    -- Common fields (same name and meaning in both new and legacy syntax)

    amount = 1,
    -- Number of particles spawned over the time period `time`.

    time = 1,
    -- Lifespan of spawner in seconds.
    -- If time is 0 spawner has infinite lifespan and spawns the `amount` on
    -- a per-second basis.

    collisiondetection = false,
    -- If true collide with `walkable` nodes and, depending on the
    -- `object_collision` field, objects too.

    collision_removal = false,
    -- If true particles are removed when they collide.
    -- Requires collisiondetection = true to have any effect.

    object_collision = false,
    -- If true particles collide with objects that are defined as
    -- `physical = true,` and `collide_with_objects = true,`.
    -- Requires collisiondetection = true to have any effect.

    attached = ObjectRef,
    -- If defined, particle positions, velocities and accelerations are
    -- relative to this object's position and yaw

    vertical = false,
    -- If true face player using y axis only

    texture = "image.png",
    -- The texture of the particle

    playername = "singleplayer",
    -- Optional, if specified spawns particles only on the player's client

    animation = {Tile Animation definition},
    -- Optional, specifies how to animate the particles' texture
    -- v5.6.0 and later: set length to -1 to synchronize the length
    -- of the animation with the expiration time of individual particles.
    -- (-2 causes the animation to be played twice, and so on)

    glow = 0,
    -- Optional, specify particle self-luminescence in darkness.
    -- Values 0-14.

    node = {name = "ignore", param2 = 0},
    -- Optional, if specified the particles will have the same appearance as
    -- node dig particles for the given node.
    -- `texture` and `animation` will be ignored if this is set.

    node_tile = 0,
    -- Optional, only valid in combination with `node`
    -- If set to a valid number 1-6, specifies the tile from which the
    -- particle texture is picked.
    -- Otherwise, the default behavior is used. (currently: any random tile)

    -- Legacy definition fields

    minpos = {x=0, y=0, z=0},
    maxpos = {x=0, y=0, z=0},
    minvel = {x=0, y=0, z=0},
    maxvel = {x=0, y=0, z=0},
    minacc = {x=0, y=0, z=0},
    maxacc = {x=0, y=0, z=0},
    minexptime = 1,
    maxexptime = 1,
    minsize = 1,
    maxsize = 1,
    -- The particles' properties are random values between the min and max
    -- values.
    -- applies to: pos, velocity, acceleration, expirationtime, size
    -- If `node` is set, min and maxsize can be set to 0 to spawn
    -- randomly-sized particles (just like actual node dig particles).
}
```

### Modern definition fields



@@ 9750,91 9899,93 @@ property definition are present, the highest-precedence form will be selected
and all lower-precedence fields will be ignored, allowing for graceful
degradation in older clients).

    {
      -- old syntax
      maxpos = {x = 0, y = 0, z = 0},
      minpos = {x = 0, y = 0, z = 0},

      -- absolute value
      pos = 0,
      -- all components of every particle's position vector will be set to this
      -- value

      -- vec3
      pos = vector.new(0,0,0),
      -- all particles will appear at this exact position throughout the lifetime
      -- of the particlespawner

      -- vec3 range
      pos = {
            -- the particle will appear at a position that is picked at random from
            -- within a cubic range

            min = vector.new(0,0,0),
            -- `min` is the minimum value this property will be set to in particles
            -- spawned by the generator

            max = vector.new(0,0,0),
            -- `max` is the minimum value this property will be set to in particles
            -- spawned by the generator

            bias = 0,
            -- when `bias` is 0, all random values are exactly as likely as any
            -- other. when it is positive, the higher it is, the more likely values
            -- will appear towards the minimum end of the allowed spectrum. when
            -- it is negative, the lower it is, the more likely values will appear
            -- towards the maximum end of the allowed spectrum. the curve is
            -- exponential and there is no particular maximum or minimum value
        },
```lua
{
  -- old syntax
  maxpos = {x = 0, y = 0, z = 0},
  minpos = {x = 0, y = 0, z = 0},

  -- absolute value
  pos = 0,
  -- all components of every particle's position vector will be set to this
  -- value

  -- vec3
  pos = vector.new(0,0,0),
  -- all particles will appear at this exact position throughout the lifetime
  -- of the particlespawner

  -- vec3 range
  pos = {
        -- the particle will appear at a position that is picked at random from
        -- within a cubic range

        min = vector.new(0,0,0),
        -- `min` is the minimum value this property will be set to in particles
        -- spawned by the generator

        max = vector.new(0,0,0),
        -- `max` is the minimum value this property will be set to in particles
        -- spawned by the generator

        bias = 0,
        -- when `bias` is 0, all random values are exactly as likely as any
        -- other. when it is positive, the higher it is, the more likely values
        -- will appear towards the minimum end of the allowed spectrum. when
        -- it is negative, the lower it is, the more likely values will appear
        -- towards the maximum end of the allowed spectrum. the curve is
        -- exponential and there is no particular maximum or minimum value
    },

        -- tween table
        pos_tween = {...},
        -- a tween table should consist of a list of frames in the same form as the
        -- untweened pos property above, which the engine will interpolate between,
        -- and optionally a number of properties that control how the interpolation
        -- takes place. currently **only two frames**, the first and the last, are
        -- used, but extra frames are accepted for the sake of forward compatibility.
        -- any of the above definition styles can be used here as well in any combination
        -- supported by the property type

        pos_tween = {
            style = "fwd",
            -- linear animation from first to last frame (default)
            style = "rev",
            -- linear animation from last to first frame
            style = "pulse",
            -- linear animation from first to last then back to first again
            style = "flicker",
            -- like "pulse", but slightly randomized to add a bit of stutter

            reps = 1,
            -- number of times the animation is played over the particle's lifespan

            start = 0.0,
            -- point in the spawner's lifespan at which the animation begins. 0 is
            -- the very beginning, 1 is the very end

            -- frames can be defined in a number of different ways, depending on the
            -- underlying type of the property. for now, all but the first and last
            -- frame are ignored

            -- frames

                -- floats
                0, 0,

                -- vec3s
                vector.new(0,0,0),
                vector.new(0,0,0),

                -- vec3 ranges
                { min = vector.new(0,0,0), max = vector.new(0,0,0), bias = 0 },
                { min = vector.new(0,0,0), max = vector.new(0,0,0), bias = 0 },

                -- mixed
                0, { min = vector.new(0,0,0), max = vector.new(0,0,0), bias = 0 },
        },
    }
    -- tween table
    pos_tween = {...},
    -- a tween table should consist of a list of frames in the same form as the
    -- untweened pos property above, which the engine will interpolate between,
    -- and optionally a number of properties that control how the interpolation
    -- takes place. currently **only two frames**, the first and the last, are
    -- used, but extra frames are accepted for the sake of forward compatibility.
    -- any of the above definition styles can be used here as well in any combination
    -- supported by the property type

    pos_tween = {
        style = "fwd",
        -- linear animation from first to last frame (default)
        style = "rev",
        -- linear animation from last to first frame
        style = "pulse",
        -- linear animation from first to last then back to first again
        style = "flicker",
        -- like "pulse", but slightly randomized to add a bit of stutter

        reps = 1,
        -- number of times the animation is played over the particle's lifespan

        start = 0.0,
        -- point in the spawner's lifespan at which the animation begins. 0 is
        -- the very beginning, 1 is the very end

        -- frames can be defined in a number of different ways, depending on the
        -- underlying type of the property. for now, all but the first and last
        -- frame are ignored

        -- frames

            -- floats
            0, 0,

            -- vec3s
            vector.new(0,0,0),
            vector.new(0,0,0),

            -- vec3 ranges
            { min = vector.new(0,0,0), max = vector.new(0,0,0), bias = 0 },
            { min = vector.new(0,0,0), max = vector.new(0,0,0), bias = 0 },

            -- mixed
            0, { min = vector.new(0,0,0), max = vector.new(0,0,0), bias = 0 },
    },
}
```

All of the properties that can be defined in this way are listed in the next
section, along with the datatypes they accept.


@@ 9919,56 10070,58 @@ In versions before v5.6.0, particlespawner textures could only be specified as a
texture string. After v5.6.0, textures can now be specified as a table as well. This
table contains options that allow simple animations to be applied to the texture.

    texture = {
        name = "mymod_particle_texture.png",
        -- the texture specification string

        alpha = 1.0,
        -- controls how visible the particle is; at 1.0 the particle is fully
        -- visible, at 0, it is completely invisible.

        alpha_tween = {1, 0},
        -- can be used instead of `alpha` to animate the alpha value over the
        -- particle's lifetime. these tween tables work identically to the tween
        -- tables used in particlespawner properties, except that time references
        -- are understood with respect to the particle's lifetime, not the
        -- spawner's. {1,0} fades the particle out over its lifetime.

        scale = 1,
        scale = {x = 1, y = 1},
        -- scales the texture onscreen

        scale_tween = {
            {x = 1, y = 1},
            {x = 0, y = 1},
        },
        -- animates the scale over the particle's lifetime. works like the
        -- alpha_tween table, but can accept two-dimensional vectors as well as
        -- integer values. the example value would cause the particle to shrink
        -- in one dimension over the course of its life until it disappears

        blend = "alpha",
        -- (default) blends transparent pixels with those they are drawn atop
        -- according to the alpha channel of the source texture. useful for
        -- e.g. material objects like rocks, dirt, smoke, or node chunks
        blend = "add",
        -- adds the value of pixels to those underneath them, modulo the sources
        -- alpha channel. useful for e.g. bright light effects like sparks or fire
        blend = "screen",
        -- like "add" but less bright. useful for subtler light effects. note that
        -- this is NOT formally equivalent to the "screen" effect used in image
        -- editors and compositors, as it does not respect the alpha channel of
        -- of the image being blended
        blend = "sub",
        -- the inverse of "add"; the value of the source pixel is subtracted from
        -- the pixel underneath it. a white pixel will turn whatever is underneath
        -- it black; a black pixel will be "transparent". useful for creating
        -- darkening effects

        animation = {Tile Animation definition},
        -- overrides the particlespawner's global animation property for a single
        -- specific texture
    }
```lua
texture = {
    name = "mymod_particle_texture.png",
    -- the texture specification string

    alpha = 1.0,
    -- controls how visible the particle is; at 1.0 the particle is fully
    -- visible, at 0, it is completely invisible.

    alpha_tween = {1, 0},
    -- can be used instead of `alpha` to animate the alpha value over the
    -- particle's lifetime. these tween tables work identically to the tween