:`
+#### Crack
+* `[crack::`
+* `[cracko::`
+* `[crack:::`
+* `[cracko:::`
+
+Parameters:
+* `` = tile count (in each direction)
* `` = animation frame count
* `` = current animation frame
Draw a step of the crack animation on the texture.
+`crack` draws it normally, while `cracko` lays it over, keeping transparent
+pixels intact.
Example:
@@ -333,7 +413,7 @@ Only the channels that are mentioned in the mode string will be inverted.
Example:
- default_apple.png^[invert:rgb
+ default_apple.png^[invert:rgb
#### `[brighten`
Brightens the texture.
@@ -378,7 +458,8 @@ Example:
default_stone.png^[transformFXR90
#### `[inventorycube{{{`
-Escaping does not apply here and `^` is replaced by `&` in texture names instead.
+Escaping does not apply here and `^` is replaced by `&` in texture names
+instead.
Create an inventory cube texture using the side textures.
@@ -431,8 +512,8 @@ texture pixel.
Multiplies texture colors with the given color.
`` is specified as a `ColorString`.
Result is more like what you'd expect if you put a color on top of another
-color. Meaning white surfaces get a lot of your new color while black parts don't
-change very much.
+color. Meaning white surfaces get a lot of your new color while black parts
+don't change very much.
Hardware coloring
-----------------
@@ -475,6 +556,7 @@ stretched to contain exactly 256 pixels (after arranging the pixels
to one line). The indexing starts from 0.
Examples:
+
* 16x16 palette, index = 0: the top left corner
* 16x16 palette, index = 4: the fifth pixel in the first row
* 16x16 palette, index = 16: the pixel below the top left corner
@@ -498,35 +580,36 @@ index of the pixel to use.
When registering a node, set the item definition's `palette` field to
a texture. You can also use texture modifiers.
The node's color depends on its `param2`, so you also must set an
-appropriate `drawtype`:
-* `drawtype = "color"` for nodes which use their full `param2` for
+appropriate `paramtype2`:
+
+* `paramtype2 = "color"` for nodes which use their full `param2` for
palette indexing. These nodes can have 256 different colors.
The palette should contain 256 pixels.
-* `drawtype = "colorwallmounted"` for nodes which use the first
+* `paramtype2 = "colorwallmounted"` for nodes which use the first
five bits (most significant) of `param2` for palette indexing.
The remaining three bits are describing rotation, as in `wallmounted`
- draw type. Division by 8 yields the palette index (without stretching the
+ paramtype2. Division by 8 yields the palette index (without stretching the
palette). These nodes can have 32 different colors, and the palette
should contain 32 pixels.
Examples:
- * `param2 = 17` is 2 * 8 + 1, so the rotation is 1 and the third (= 2 + 1)
- pixel will be picked from the palette.
- * `param2 = 35` is 4 * 8 + 3, so the rotation is 3 and the fifth (= 4 + 1)
- pixel will be picked from the palette.
-* `drawtype = "colorfacedir"` for nodes which use the first
+ * `param2 = 17` is 2 * 8 + 1, so the rotation is 1 and the third (= 2 + 1)
+ pixel will be picked from the palette.
+ * `param2 = 35` is 4 * 8 + 3, so the rotation is 3 and the fifth (= 4 + 1)
+ pixel will be picked from the palette.
+* `paramtype2 = "colorfacedir"` for nodes which use the first
three bits of `param2` for palette indexing. The remaining
- five bits are describing rotation, as in `facedir` draw type.
+ five bits are describing rotation, as in `facedir` paramtype2.
Division by 32 yields the palette index (without stretching the
palette). These nodes can have 8 different colors, and the
palette should contain 8 pixels.
Examples:
- * `param2 = 17` is 0 * 32 + 17, so the rotation is 17 and the
- first (= 0 + 1) pixel will be picked from the palette.
- * `param2 = 35` is 1 * 32 + 3, so the rotation is 3 and the
- second (= 1 + 1) pixel will be picked from the palette.
+ * `param2 = 17` is 0 * 32 + 17, so the rotation is 17 and the
+ first (= 0 + 1) pixel will be picked from the palette.
+ * `param2 = 35` is 1 * 32 + 3, so the rotation is 3 and the
+ second (= 1 + 1) pixel will be picked from the palette.
To colorize a node on the map, set its `param2` value (according
-to the node's draw type).
+to the node's paramtype2).
### Conversion between nodes in the inventory and the on the map
Static coloring is the same for both cases, there is no need
@@ -541,6 +624,7 @@ when a player digs or places a colored node.
You can disable this feature by setting the `drop` field of the node
to itself (without metadata).
To transfer the color to a special drop, you need a drop table.
+
Example:
minetest.register_node("mod:stone", {
@@ -715,6 +799,10 @@ the global `minetest.registered_*` tables.
* added to `minetest.registered_biome` with the key of `biome.name`
* if `biome.name` is nil, the key is the returned ID
+* `minetest.unregister_biome(name)`
+ * Unregisters the biome name from engine, and deletes the entry with key
+ * `name` from `minetest.registered_biome`
+
* `minetest.register_ore(ore definition)`
* returns an integer uniquely identifying the registered ore
* added to `minetest.registered_ores` with the key of `ore.name`
@@ -722,16 +810,19 @@ the global `minetest.registered_*` tables.
* `minetest.register_decoration(decoration definition)`
* returns an integer uniquely identifying the registered decoration
- * added to `minetest.registered_decorations` with the key of `decoration.name`
+ * added to `minetest.registered_decorations` with the key of
+ `decoration.name`.
* if `decoration.name` is nil, the key is the returned ID
* `minetest.register_schematic(schematic definition)`
* returns an integer uniquely identifying the registered schematic
* added to `minetest.registered_schematic` with the key of `schematic.name`
* if `schematic.name` is nil, the key is the returned ID
- * if the schematic is loaded from a file, schematic.name is set to the filename
- * if the function is called when loading the mod, and schematic.name is a relative
- path, then the current mod path will be prepended to the schematic filename
+ * if the schematic is loaded from a file, schematic.name is set to the
+ filename.
+ * if the function is called when loading the mod, and schematic.name is a
+ relative path, then the current mod path will be prepended to the
+ schematic filename.
* `minetest.clear_registered_biomes()`
* clears all biomes currently registered
@@ -820,14 +911,25 @@ node definition:
0 = y+ 1 = z+ 2 = z- 3 = x+ 4 = x- 5 = y-
facedir modulo 4 = rotation around that axis
paramtype2 == "leveled"
+ ^ Only valid for "nodebox" with 'type = "leveled"', and "plantlike_rooted".
+ Leveled nodebox:
+ The level of the top face of the nodebox is stored in param2.
+ The other faces are defined by 'fixed = {}' like 'type = "fixed"'
+ nodeboxes.
+ The nodebox height is (param2 / 64) nodes.
+ The maximum accepted value of param2 is 127.
+ Rooted plantlike:
+ The height of the 'plantlike' section is stored in param2.
+ The height is (param2 / 16) nodes.
paramtype2 == "degrotate"
- ^ The rotation of this node is stored in param2. Plants are rotated this way.
+ ^ Only valid for "plantlike". The rotation of the node is stored in param2.
Values range 0 - 179. The value stored in param2 is multiplied by two to
- get the actual rotation of the node.
+ get the actual rotation in degrees of the node.
paramtype2 == "meshoptions"
- ^ Only valid for "plantlike". The value of param2 becomes a bitfield which can
- be used to change how the client draws plantlike nodes. Bits 0, 1 and 2 form
- a mesh selector. Currently the following meshes are choosable:
+ ^ Only valid for "plantlike". The value of param2 becomes a bitfield which
+ can be used to change how the client draws plantlike nodes.
+ Bits 0, 1 and 2 form a mesh selector.
+ Currently the following meshes are choosable:
0 = a "x" shaped plant (ordinary plant)
1 = a "+" shaped plant (just rotated 45 degrees)
2 = a "*" shaped plant with 3 faces instead of 2
@@ -854,49 +956,107 @@ node definition:
is picked from the palette.
The palette should have 32 pixels.
paramtype2 == "glasslikeliquidlevel"
- ^ Only valid for "glasslike_framed" or "glasslike_framed_optional" drawtypes.
- param2 defines 64 levels of internal liquid.
+ ^ Only valid for "glasslike_framed" or "glasslike_framed_optional"
+ drawtypes.
+ param2 values 0-63 define 64 levels of internal liquid, 0 being empty and
+ 63 being full.
Liquid texture is defined using `special_tiles = {"modname_tilename.png"},`
Nodes can also contain extra data. See "Node Metadata".
Node drawtypes
----------------
+--------------
There are a bunch of different looking node types.
Look for examples in `games/minimal` or `games/minetest_game`.
* `normal`
+ * A node-sized cube.
* `airlike`
+ * Invisible, uses no texture.
* `liquid`
+ * The cubic source node for a liquid.
* `flowingliquid`
+ * The flowing version of a liquid, appears with various heights and slopes.
* `glasslike`
+ * Often used for partially-transparent nodes.
+ * Only external sides of textures are visible.
* `glasslike_framed`
+ * All face-connected nodes are drawn as one volume within a surrounding
+ frame.
+ * The frame appearence is generated from the edges of the first texture
+ specified in `tiles`. The width of the edges used are 1/16th of texture
+ size: 1 pixel for 16x16, 2 pixels for 32x32 etc.
+ * The glass 'shine' (or other desired detail) on each node face is supplied
+ by the second texture specified in `tiles`.
* `glasslike_framed_optional`
+ * This switches between the above 2 drawtypes according to the menu setting
+ 'Connected Glass'.
* `allfaces`
+ * Often used for partially-transparent nodes.
+ * External and internal sides of textures are visible.
* `allfaces_optional`
+ * Often used for leaves nodes.
+ * This switches between `normal`, `glasslike` and `allfaces` according to
+ the menu setting: Opaque Leaves / Simple Leaves / Fancy Leaves.
+ * With 'Simple Leaves' selected, the texture specified in `special_tiles`
+ is used instead, if present. This allows a visually thicker texture to be
+ used to compensate for how `glasslike` reduces visual thickness.
* `torchlike`
+ * A single vertical texture.
+ * If placed on top of a node, uses the first texture specified in `tiles`.
+ * If placed against the underside of a node, uses the second texture
+ specified in `tiles`.
+ * If placed on the side of a node, uses the third texture specified in
+ `tiles` and is perpendicular to that node.
* `signlike`
+ * A single texture parallel to, and mounted against, the top, underside or
+ side of a node.
* `plantlike`
+ * Two vertical and diagonal textures at right-angles to each other.
+ * See `paramtype2 == "meshoptions"` above for other options.
* `firelike`
+ * When above a flat surface, appears as 6 textures, the central 2 as
+ `plantlike` plus 4 more surrounding those.
+ * If not above a surface the central 2 do not appear, but the texture
+ appears against the faces of surrounding nodes if they are present.
* `fencelike`
+ * A 3D model suitable for a wooden fence.
+ * One placed node appears as a single vertical post.
+ * Adjacently-placed nodes cause horizontal bars to appear between them.
* `raillike`
-* `nodebox` -- See below. (**Experimental!**)
-* `mesh` -- use models for nodes
+ * Often used for tracks for mining carts.
+ * Requires 4 textures to be specified in `tiles`, in order: Straight,
+ curved, t-junction, crossing.
+ * Each placed node automatically switches to a suitable rotated texture
+ determined by the adjacent `raillike` nodes, in order to create a
+ continuous track network.
+ * Becomes a sloping node if placed against stepped nodes.
+* `nodebox`
+ * Often used for stairs and slabs.
+ * Allows defining nodes consisting of an arbitrary number of boxes.
+ * See 'Node boxes' below for more information.
+* `mesh`
+ * Uses models for nodes.
+ * Tiles should hold model materials textures.
+ * Only static meshes are implemented.
+ * For supported model formats see Irrlicht engine documentation.
* `plantlike_rooted`
-
-`*_optional` drawtypes need less rendering time if deactivated (always client side).
+ * Enables underwater `plantlike` without air bubbles around the nodes.
+ * Consists of a base cube at the co-ordinates of the node plus a
+ `plantlike` extension above with a height of `param2 / 16` nodes.
+ * The `plantlike` extension visually passes through any nodes above the
+ base cube without affecting them.
+ * The base cube texture tiles are defined as normal, the `plantlike`
+ extension uses the defined special tile, for example:
+ `special_tiles = {{name = "default_papyrus.png", tileable_vertical = true}},`
+
+`*_optional` drawtypes need less rendering time if deactivated
+(always client-side).
Node boxes
------------
-Node selection boxes are defined using "node boxes"
-
-The `nodebox` node drawtype allows defining visual of nodes consisting of
-arbitrary number of boxes. It allows defining stuff like stairs. Only the
-`fixed` and `leveled` box type is supported for these.
-
-Please note that this is still experimental, and may be incompatibly
-changed in the future.
+----------
+Node selection boxes are defined using "node boxes".
A nodebox is defined as any of:
@@ -905,10 +1065,18 @@ A nodebox is defined as any of:
type = "regular"
}
{
- -- A fixed box (facedir param2 is used, if applicable)
+ -- 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)
@@ -928,6 +1096,18 @@ A nodebox is defined as any of:
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 neighbour
+ -- 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* neighbour
+ disconnected_sides = box OR {box1, box2, ...} -- when there are *no*
+ neighbours to the sides
}
A `box` is defined as:
@@ -938,17 +1118,6 @@ A box of a regular node would look like:
{-0.5, -0.5, -0.5, 0.5, 0.5, 0.5},
-`type = "leveled"` is same as `type = "fixed"`, but `y2` will be automatically
-set to level from `param2`.
-
-
-Meshes
-------
-If drawtype `mesh` is used, tiles should hold model materials textures.
-Only static meshes are implemented.
-For supported model formats see Irrlicht engine documentation.
-
-
Noise Parameters
----------------
Noise Parameters, or commonly called "`NoiseParams`", define the properties of
@@ -961,14 +1130,16 @@ Offset that the noise is translated by (i.e. added) after calculation.
Factor that the noise is scaled by (i.e. multiplied) after calculation.
### `spread`
-Vector containing values by which each coordinate is divided by before calculation.
+Vector containing values by which each coordinate is divided by before
+calculation.
Higher spread values result in larger noise features.
A value of `{x=250, y=250, z=250}` is common.
### `seed`
-Random seed for the noise. Add the world seed to a seed offset for world-unique noise.
-In the case of `minetest.get_perlin()`, this value has the world seed automatically added.
+Random seed for the noise. Add the world seed to a seed offset for world-unique
+noise. In the case of `minetest.get_perlin()`, this value has the world seed
+automatically added.
### `octaves`
Number of times the noise gradient is accumulated into the noise.
@@ -978,10 +1149,11 @@ Increase this number to increase the amount of detail in the resulting noise.
A value of `6` is common.
### `persistence`
-Factor by which the effect of the noise gradient function changes with each successive octave.
+Factor by which the effect of the noise gradient function changes with each
+successive octave.
-Values less than `1` make the details of successive octaves' noise diminish, while values
-greater than `1` make successive octaves stronger.
+Values less than `1` make the details of successive octaves' noise diminish,
+while values greater than `1` make successive octaves stronger.
A value of `0.6` is common.
@@ -996,13 +1168,15 @@ Leave this field unset for no special handling.
Currently supported are `defaults`, `eased` and `absvalue`.
#### `defaults`
-Specify this if you would like to keep auto-selection of eased/not-eased while specifying
-some other flags.
+Specify this if you would like to keep auto-selection of eased/not-eased while
+specifying some other flags.
#### `eased`
-Maps noise gradient values onto a quintic S-curve before performing interpolation.
-This results in smooth, rolling noise. Disable this (`noeased`) for sharp-looking noise.
-If no flags are specified (or defaults is), 2D noise is eased and 3D noise is not eased.
+Maps noise gradient values onto a quintic S-curve before performing
+interpolation. This results in smooth, rolling noise.
+Disable this (`noeased`) for sharp-looking noise.
+If no flags are specified (or defaults is), 2D noise is eased and 3D noise is
+not eased.
#### `absvalue`
Accumulates the absolute value of each noise gradient result.
@@ -1032,9 +1206,9 @@ All default ores are of the uniformly-distributed scatter type.
### `scatter`
Randomly chooses a location and generates a cluster of ore.
-If `noise_params` is specified, the ore will be placed if the 3D perlin noise at
-that point is greater than the `noise_threshold`, giving the ability to create
-a non-equal distribution of ore.
+If `noise_params` is specified, the ore will be placed if the 3D perlin noise
+at that point is greater than the `noise_threshold`, giving the ability to
+create a non-equal distribution of ore.
### `sheet`
Creates a sheet of ore in a blob shape according to the 2D perlin noise
@@ -1045,56 +1219,91 @@ This sheet consists of vertical columns of uniform randomly distributed height,
varying between the inclusive range `column_height_min` and `column_height_max`.
If `column_height_min` is not specified, this parameter defaults to 1.
If `column_height_max` is not specified, this parameter defaults to `clust_size`
-for reverse compatibility. New code should prefer `column_height_max`.
+for reverse compatibility. New code should prefer `column_height_max`.
-The `column_midpoint_factor` parameter controls the position of the column at which
-ore eminates from. If 1, columns grow upward. If 0, columns grow downward. If 0.5,
-columns grow equally starting from each direction. `column_midpoint_factor` is a
-decimal number ranging in value from 0 to 1. If this parameter is not specified,
-the default is 0.5.
+The `column_midpoint_factor` parameter controls the position of the column at
+which ore emanates from.
+If 1, columns grow upward. If 0, columns grow downward. If 0.5, columns grow
+equally starting from each direction.
+`column_midpoint_factor` is a decimal number ranging in value from 0 to 1. If
+this parameter is not specified, the default is 0.5.
-The ore parameters `clust_scarcity` and `clust_num_ores` are ignored for this ore type.
+The ore parameters `clust_scarcity` and `clust_num_ores` are ignored for this
+ore type.
### `puff`
Creates a sheet of ore in a cloud-like puff shape.
As with the `sheet` ore type, the size and shape of puffs are described by
-`noise_params` and `noise_threshold` and are placed at random vertical positions
-within the currently generated chunk.
-
-The vertical top and bottom displacement of each puff are determined by the noise
-parameters `np_puff_top` and `np_puff_bottom`, respectively.
+`noise_params` and `noise_threshold` and are placed at random vertical
+positions within the currently generated chunk.
+The vertical top and bottom displacement of each puff are determined by the
+noise parameters `np_puff_top` and `np_puff_bottom`, respectively.
### `blob`
Creates a deformed sphere of ore according to 3d perlin noise described by
-`noise_params`. The maximum size of the blob is `clust_size`, and
+`noise_params`. The maximum size of the blob is `clust_size`, and
`clust_scarcity` has the same meaning as with the `scatter` type.
### `vein`
Creates veins of ore varying in density by according to the intersection of two
-instances of 3d perlin noise with diffferent seeds, both described by
-`noise_params`. `random_factor` varies the influence random chance has on
-placement of an ore inside the vein, which is `1` by default. Note that
-modifying this parameter may require adjusting `noise_threshold`.
+instances of 3d perlin noise with different seeds, both described by
+`noise_params`.
+
+`random_factor` varies the influence random chance has on placement of an ore
+inside the vein, which is `1` by default. Note that modifying this parameter
+may require adjusting `noise_threshold`.
+
The parameters `clust_scarcity`, `clust_num_ores`, and `clust_size` are ignored
-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,
- persist = 0.5,
- flags = "eased",
- },
- noise_threshold = 1.6
+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,
+ persist = 0.5,
+ flags = "eased",
+ },
+ noise_threshold = 1.6
**WARNING**: Use this ore type *very* sparingly since it is ~200x more
computationally expensive than any other ore.
+### `stratum`
+Creates a single undulating ore stratum that is continuous across mapchunk
+borders and horizontally spans the world.
+
+The 2D perlin noise described by `noise_params` defines the Y co-ordinate of
+the stratum midpoint. The 2D perlin noise described by `np_stratum_thickness`
+defines the stratum's vertical thickness (in units of nodes). Due to being
+continuous across mapchunk borders the stratum's vertical thickness is
+unlimited.
+
+If the noise parameter `noise_params` is omitted the ore will occur from y_min
+to y_max in a simple horizontal stratum.
+
+A parameter `stratum_thickness` can be provided instead of the noise parameter
+`np_stratum_thickness`, to create a constant thickness.
+
+Leaving out one or both noise parameters makes the ore generation less
+intensive, useful when adding multiple strata.
+
+`y_min` and `y_max` define the limits of the ore generation and for performance
+reasons should be set as close together as possible but without clipping the
+stratum's Y variation.
+
+Each node in the stratum has a 1-in-`clust_scarcity` chance of being ore, so a
+solid-ore stratum would require a `clust_scarcity` of 1.
+
+The parameters `clust_num_ores`, `clust_size`, `noise_threshold` and
+`random_factor` are ignored by this ore type.
+
Ore attributes
--------------
See section "Flag Specifier Format".
@@ -1103,15 +1312,16 @@ Currently supported flags:
`puff_cliffs`, `puff_additive_composition`.
### `puff_cliffs`
-If set, puff ore generation will not taper down large differences in displacement
-when approaching the edge of a puff. This flag has no effect for ore types other
-than `puff`.
+If set, puff ore generation will not taper down large differences in
+displacement when approaching the edge of a puff. This flag has no effect for
+ore types other than `puff`.
### `puff_additive_composition`
-By default, when noise described by `np_puff_top` or `np_puff_bottom` results in a
-negative displacement, the sub-column at that point is not generated. With this
-attribute set, puff ore generation will instead generate the absolute difference in
-noise displacement values. This flag has no effect for ore types other than `puff`.
+By default, when noise described by `np_puff_top` or `np_puff_bottom` results
+in a negative displacement, the sub-column at that point is not generated. With
+this attribute set, puff ore generation will instead generate the absolute
+difference in noise displacement values. This flag has no effect for ore types
+other than `puff`.
Decoration types
----------------
@@ -1138,22 +1348,28 @@ A schematic specifier identifies a schematic by either a filename to a
Minetest Schematic file (`.mts`) or through raw data supplied through Lua,
in the form of a table. This table specifies the following fields:
-* The `size` field is a 3D vector containing the dimensions of the provided schematic. (required)
-* The `yslice_prob` field is a table of {ypos, prob} which sets the `ypos`th vertical slice
- of the schematic to have a `prob / 256 * 100` chance of occuring. (default: 255)
+* The `size` field is a 3D vector containing the dimensions of the provided
+ schematic. (required)
+* The `yslice_prob` field is a table of {ypos, prob} which sets the `ypos`th
+ vertical slice of the schematic to have a `prob / 256 * 100` chance of
+ occurring. (default: 255)
* The `data` field is a flat table of MapNode tables making up the schematic,
in the order of `[z [y [x]]]`. (required)
Each MapNode table contains:
- * `name`: the name of the map node to place (required)
- * `prob` (alias `param1`): the probability of this node being placed (default: 255)
- * `param2`: the raw param2 value of the node being placed onto the map (default: 0)
- * `force_place`: boolean representing if the node should forcibly overwrite any
- previous contents (default: false)
+ * `name`: the name of the map node to place (required)
+ * `prob` (alias `param1`): the probability of this node being placed
+ (default: 255)
+ * `param2`: the raw param2 value of the node being placed onto the map
+ (default: 0)
+ * `force_place`: boolean representing if the node should forcibly overwrite
+ any previous contents (default: false)
About probability values:
-* A probability value of `0` or `1` means that node will never appear (0% chance).
-* A probability value of `254` or `255` means the node will always appear (100% chance).
+* A probability value of `0` or `1` means that node will never appear
+ (0% chance).
+* A probability value of `254` or `255` means the node will always appear
+ (100% chance).
* If the probability value `p` is greater than `1`, then there is a
`(p / 256 * 100)` percent chance that node will appear when the schematic is
placed on the map.
@@ -1169,15 +1385,16 @@ Currently supported flags: `place_center_x`, `place_center_y`, `place_center_z`,
* `place_center_x`: Placement of this decoration is centered along the X axis.
* `place_center_y`: Placement of this decoration is centered along the Y axis.
* `place_center_z`: Placement of this decoration is centered along the Z axis.
-* `force_placement`: Schematic nodes other than "ignore" will replace existing nodes.
+* `force_placement`: Schematic nodes other than "ignore" will replace existing
+ nodes.
HUD element types
-----------------
The position field is used for all element types.
-To account for differing resolutions, the position coordinates are the percentage
-of the screen, ranging in value from `0` to `1`.
+To account for differing resolutions, the position coordinates are the
+percentage of the screen, ranging in value from `0` to `1`.
The name field is not yet used, but should contain a description of what the
HUD element represents. The direction field is the direction in which something
@@ -1186,20 +1403,22 @@ is drawn.
`0` draws from left to right, `1` draws from right to left, `2` draws from
top to bottom, and `3` draws from bottom to top.
-The `alignment` field specifies how the item will be aligned. It ranges from `-1` to `1`,
-with `0` being the center, `-1` is moved to the left/up, and `1` is to the right/down.
-Fractional values can be used.
+The `alignment` field specifies how the item will be aligned. It ranges from
+`-1` to `1`, with `0` being the center. `-1` is moved to the left/up, and `1`
+is to the right/down. Fractional values can be used.
-The `offset` field specifies a pixel offset from the position. Contrary to position,
-the offset is not scaled to screen size. This allows for some precisely-positioned
-items in the HUD.
+The `offset` field specifies a pixel offset from the position. Contrary to
+position, the offset is not scaled to screen size. This allows for some
+precisely positioned items in the HUD.
-**Note**: `offset` _will_ adapt to screen DPI as well as user defined scaling factor!
+**Note**: `offset` _will_ adapt to screen DPI as well as user defined scaling
+factor!
-Below are the specific uses for fields in each type; fields not listed for that type are ignored.
+Below are the specific uses for fields in each type; fields not listed for that
+type are ignored.
-**Note**: Future revisions to the HUD API may be incompatible; the HUD API is still
-in the experimental stages.
+**Note**: Future revisions to the HUD API may be incompatible; the HUD API is
+still in the experimental stages.
### `image`
Displays an image on the HUD.
@@ -1218,8 +1437,8 @@ Displays text on the HUD.
* `scale`: Defines the bounding rectangle of the text.
A value such as `{x=100, y=100}` should work.
* `text`: The text to be displayed in the HUD element.
-* `number`: An integer containing the RGB value of the color used to draw the text.
- Specify `0xFFFFFF` for white text, `0xFF0000` for red, and so on.
+* `number`: An integer containing the RGB value of the color used to draw the
+ text. Specify `0xFFFFFF` for white text, `0xFF0000` for red, and so on.
* `alignment`: The alignment of the text.
* `offset`: offset in pixels from position.
@@ -1231,7 +1450,8 @@ Displays a horizontal bar made up of half-images.
If odd, will end with a vertically center-split texture.
* `direction`
* `offset`: offset in pixels from position.
-* `size`: If used, will force full-image size to this value (override texture pack image size)
+* `size`: If used, will force full-image size to this value (override texture
+ pack image size)
### `inventory`
* `text`: The name of the inventory list to be displayed.
@@ -1245,7 +1465,8 @@ Displays distance to selected world position.
* `name`: The name of the waypoint.
* `text`: Distance suffix. Can be blank.
-* `number:` An integer containing the RGB value of the color used to draw the text.
+* `number:` An integer containing the RGB value of the color used to draw the
+ text.
* `world_pos`: World position of the waypoint.
Representations of simple things
@@ -1264,8 +1485,8 @@ For helper functions see "Vector helpers".
Flag Specifier Format
---------------------
-Flags using the standardized flag specifier format can be specified in either of
-two ways, by string or table.
+Flags using the standardized flag specifier format can be specified in either
+of two ways, by string or table.
The string format is a comma-delimited set of flag names; whitespace and
unrecognized flag fields are ignored. Specifying a flag in the string sets the
@@ -1448,7 +1669,7 @@ Another example: Make red wool from white wool and red dye:
* `connect_to_raillike`: makes nodes of raillike drawtype with same group value
connect to each other
* `slippery`: Players and items will slide on the node.
- Only use `slippery = 3` for now to ensure forwards compatibility.
+ Slipperiness rises steadily with `slippery` value, starting at 1.
### Known damage and digging time defining groups
@@ -1614,7 +1835,7 @@ 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)
+ 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.
@@ -1626,17 +1847,17 @@ the entity itself.
* `direction` is a unit vector, pointing from the source of the punch to
the punched object.
* `damage` damage that will be done to entity
-Return value of this function will determin if damage is done by this function
+Return value of this function will determine if damage is done by this function
(retval true) or shall be done by engine (retval false)
To punch an entity/object in Lua, call:
- object:punch(puncher, time_from_last_punch, tool_capabilities, direction)
+ object:punch(puncher, time_from_last_punch, tool_capabilities, direction)
* Return value is tool wear.
* Parameters are equal to the above callback.
-* If `direction` equals `nil` and `puncher` does not equal `nil`,
- `direction` will be automatically filled in based on the location of `puncher`.
+* If `direction` equals `nil` and `puncher` does not equal `nil`, `direction`
+ will be automatically filled in based on the location of `puncher`.
Node Metadata
-------------
@@ -1690,10 +1911,11 @@ Item metadata only contains a key-value store.
Some of the values in the key-value store are handled specially:
-* `description`: Set the item stack's description. Defaults to `idef.description`
+* `description`: Set the item stack's description. Defaults to
+ `idef.description`.
* `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.
+ current color from the palette.
Example stuff:
@@ -1741,23 +1963,36 @@ examples.
* deprecated: `invsize[,;]`
#### `position[,]`
-* Define the position of the formspec
-* A value between 0.0 and 1.0 represents a position inside the screen
-* The default value is the center of the screen (0.5, 0.5)
+* Must be used after `size` element.
+* Defines the position on the game window of the formspec's `anchor` point.
+* For X and Y, 0.0 and 1.0 represent opposite edges of the game window,
+ for example:
+ * [0.0, 0.0] sets the position to the top left corner of the game window.
+ * [1.0, 1.0] sets the position to the bottom right of the game window.
+* Defaults to the center of the game window [0.5, 0.5].
#### `anchor[,]`
-* Define the anchor of the formspec
-* A value between 0.0 and 1.0 represents an anchor inside the formspec
-* The default value is the center of the formspec (0.5, 0.5)
+* Must be used after both `size` and `position` (if present) elements.
+* Defines the location of the anchor point within the formspec.
+* For X and Y, 0.0 and 1.0 represent opposite edges of the formspec,
+ for example:
+ * [0.0, 1.0] sets the anchor to the bottom left corner of the formspec.
+ * [1.0, 0.0] sets the anchor to the top right of the formspec.
+* Defaults to the center of the formspec [0.5, 0.5].
+
+* `position` and `anchor` elements need suitable values to avoid a formspec
+ extending off the game window due to particular game window sizes.
#### `container[,]`
-* Start of a container block, moves all physical elements in the container by (X, Y)
+* Start of a container block, moves all physical elements in the container by
+ (X, Y).
* Must have matching `container_end`
* Containers can be nested, in which case the offsets are added
(child containers are relative to parent containers)
#### `container_end[]`
-* End of a container, following elements are no longer relative to this container
+* End of a container, following elements are no longer relative to this
+ container.
#### `list[;;,;,;]`
* Show an inventory list
@@ -1807,7 +2042,8 @@ examples.
#### `bgcolor[;]`
* Sets background color of formspec as `ColorString`
-* If `true`, the background color is drawn fullscreen (does not effect the size of the formspec)
+* If `true`, the background color is drawn fullscreen (does not effect the size
+ of the formspec).
#### `background[,;,;]`
* Use a background. Inventory rectangles are not drawn then.
@@ -1825,8 +2061,8 @@ examples.
#### `pwdfield[,;,;;]`
* Textual password style field; will be sent to server when a button is clicked
-* When enter is pressed in field, fields.key_enter_field will be sent with the name
- of this field.
+* When enter is pressed in field, fields.key_enter_field will be sent with the
+ name of this field.
* `x` and `y` position the field relative to the top left of the menu
* `w` and `h` are the size of the field
* Fields are a set height, but will be vertically centred on `h`
@@ -1837,8 +2073,8 @@ examples.
#### `field[,;,;;;]`
* Textual field; will be sent to server when a button is clicked
-* When enter is pressed in field, `fields.key_enter_field` will be sent with the name
- of this field.
+* When enter is pressed in field, `fields.key_enter_field` will be sent with
+ the name of this field.
* `x` and `y` position the field relative to the top left of the menu
* `w` and `h` are the size of the field
* Fields are a set height, but will be vertically centred on `h`
@@ -1853,8 +2089,8 @@ examples.
#### `field[;;]`
* As above, but without position/size units
-* When enter is pressed in field, `fields.key_enter_field` will be sent with the name
- of this field.
+* When enter is pressed in field, `fields.key_enter_field` will be sent with
+ the name of this field.
* Special field for creating simple forms, such as sign text input
* Must be used without a `size[]` element
* A "Proceed" button will be added automatically
@@ -1862,11 +2098,14 @@ examples.
#### `field_close_on_enter[;]`
* is the name of the field
-* if is false, pressing enter in the field will submit the form but not close it
+* if is false, pressing enter in the field will submit the
+ form but not close it.
* defaults to true when not specified (ie: no tag for a field)
#### `textarea[,;,;;;]`
* Same as fields above, but with multi-line input
+* if the text overflows a vertical scrollbar is added
+* if the name is empty the textarea is readonly, the label is not displayed.
#### `label[,;]`
* `x` and `y` work as per field
@@ -1896,15 +2135,16 @@ examples.
* `x`, `y`, `w`, `h`, and `name` work as per button
* `texture name` is the filename of an image
* Position and size units are inventory slots
-* `noclip=true` means the image button doesn't need to be within specified formsize
+* `noclip=true` means the image button doesn't need to be within specified
+ formsize.
* `drawborder`: draw button border or not
* `pressed texture name` is the filename of an image on pressed state
#### `item_image_button[,;,;- ;
;]`
* `x`, `y`, `w`, `h`, `name` and `label` work as per button
* `item name` is the registered name of an item/node,
- tooltip will be made out of its description
- to override it use tooltip element
+ tooltip will be made out of its description
+ to override it use tooltip element
* Position and size units are inventory slots
#### `button_exit[,;,;;]`
@@ -1917,20 +2157,24 @@ examples.
* Scrollable item list showing arbitrary text elements
* `x` and `y` position the itemlist relative to the top left of the menu
* `w` and `h` are the size of the itemlist
-* `name` fieldname sent to server on doubleclick value is current selected element
-* `listelements` can be prepended by #color in hexadecimal format RRGGBB (only),
- * if you want a listelement to start with "#" write "##".
+* `name` fieldname sent to server on doubleclick value is current selected
+ element.
+* `listelements` can be prepended by #color in hexadecimal format RRGGBB
+ (only).
+ * if you want a listelement to start with "#" write "##".
#### `textlist[,;,;;,,...,;;]`
* Scrollable itemlist showing arbitrary text elements
* `x` and `y` position the item list relative to the top left of the menu
* `w` and `h` are the size of the item list
-* `name` fieldname sent to server on doubleclick value is current selected element
+* `name` fieldname sent to server on doubleclick value is current selected
+ element.
* `listelements` can be prepended by #RRGGBB (only) in hexadecimal format
- * if you want a listelement to start with "#" write "##"
+ * if you want a listelement to start with "#" write "##"
* Index to be selected within textlist
* `true`/`false`: draw transparent background
-* See also `minetest.explode_textlist_event` (main menu: `engine.explode_textlist_event`)
+* See also `minetest.explode_textlist_event`
+ (main menu: `engine.explode_textlist_event`).
#### `tabheader[,;;,,...,;;;]`
* Show a tab**header** at specific position (ignores formsize)
@@ -1950,8 +2194,8 @@ examples.
#### `dropdown[,;;;- ,
- , ...,
- ;
]`
* Show a dropdown field
* **Important note**: There are two different operation modes:
- 1. handle directly on change (only changed dropdown is submitted)
- 2. read the value on pressing a button (all dropdown values are available)
+ 1. handle directly on change (only changed dropdown is submitted)
+ 2. read the value on pressing a button (all dropdown values are available)
* `x` and `y` position of dropdown
* Width of dropdown
* Fieldname data is transferred to Lua
@@ -1968,14 +2212,15 @@ examples.
#### `scrollbar[,;,;;;]`
* Show a scrollbar
* There are two ways to use it:
- 1. handle the changed event (only changed scrollbar is available)
- 2. read the value on pressing a button (all scrollbars are available)
+ 1. handle the changed event (only changed scrollbar is available)
+ 2. read the value on pressing a button (all scrollbars are available)
* `x` and `y`: position of trackbar
* `w` and `h`: width and height
* `orientation`: `vertical`/`horizontal`
* Fieldname data is transferred to Lua
* Value this trackbar is set to (`0`-`1000`)
-* See also `minetest.explode_scrollbar_event` (main menu: `engine.explode_scrollbar_event`)
+* See also `minetest.explode_scrollbar_event`
+ (main menu: `engine.explode_scrollbar_event`).
#### `table[,;,;;,,...,;]`
* Show scrollable table using options defined by the previous `tableoptions[]`
@@ -1985,32 +2230,37 @@ examples.
* `name`: fieldname sent to server on row select or doubleclick
* `cell 1`...`cell n`: cell contents given in row-major order
* `selected idx`: index of row to be selected within table (first row = `1`)
-* See also `minetest.explode_table_event` (main menu: `engine.explode_table_event`)
+* See also `minetest.explode_table_event`
+ (main menu: `engine.explode_table_event`).
#### `tableoptions[;;...]`
* Sets options for `table[]`
* `color=#RRGGBB`
- * default text color (`ColorString`), defaults to `#FFFFFF`
+ * default text color (`ColorString`), defaults to `#FFFFFF`
* `background=#RRGGBB`
- * table background color (`ColorString`), defaults to `#000000`
+ * table background color (`ColorString`), defaults to `#000000`
* `border=`
- * should the table be drawn with a border? (default: `true`)
+ * should the table be drawn with a border? (default: `true`)
* `highlight=#RRGGBB`
- * highlight background color (`ColorString`), defaults to `#466432`
+ * highlight background color (`ColorString`), defaults to `#466432`
* `highlight_text=#RRGGBB`
- * highlight text color (`ColorString`), defaults to `#FFFFFF`
+ * highlight text color (`ColorString`), defaults to `#FFFFFF`
* `opendepth=`
- * all subtrees up to `depth < value` are open (default value = `0`)
- * only useful when there is a column of type "tree"
+ * all subtrees up to `depth < value` are open (default value = `0`)
+ * only useful when there is a column of type "tree"
#### `tablecolumns[,,,...;,,;...]`
* Sets columns for `table[]`
* Types: `text`, `image`, `color`, `indent`, `tree`
* `text`: show cell contents as text
- * `image`: cell contents are an image index, use column options to define images
- * `color`: cell contents are a ColorString and define color of following cell
- * `indent`: cell contents are a number and define indentation of following cell
- * `tree`: same as indent, but user can open and close subtrees (treeview-like)
+ * `image`: cell contents are an image index, use column options to define
+ images.
+ * `color`: cell contents are a ColorString and define color of following
+ cell.
+ * `indent`: cell contents are a number and define indentation of following
+ cell.
+ * `tree`: same as indent, but user can open and close subtrees
+ (treeview-like).
* Column options:
* `align=`
* for `text` and `image`: content alignment within cells.
@@ -2028,10 +2278,11 @@ examples.
* and so on; defined indices need not be contiguous empty or
non-numeric cells are treated as `0`.
* `color` column options:
- * `span=`: number of following columns to affect (default: infinite)
+ * `span=`: number of following columns to affect
+ (default: infinite).
-**Note**: do _not_ use a element name starting with `key_`; those names are reserved to
-pass key press events to formspec!
+**Note**: do _not_ use a element name starting with `key_`; those names are
+reserved to pass key press events to formspec!
Inventory locations
-------------------
@@ -2060,9 +2311,9 @@ Player Inventory lists
Named colors are also supported and are equivalent to
[CSS Color Module Level 4](http://dev.w3.org/csswg/css-color/#named-colors).
-To specify the value of the alpha channel, append `#AA` to the end of the color name
-(e.g. `colorname#08`). For named colors the hexadecimal string representing the alpha
-value must (always) be two hexadecimal digits.
+To specify the value of the alpha channel, append `#AA` to the end of the color
+name (e.g. `colorname#08`). For named colors the hexadecimal string
+representing the alpha value must (always) be two hexadecimal digits.
`ColorSpec`
-----------
@@ -2086,8 +2337,8 @@ The following functions provide escape sequences:
* `minetest.colorize(color, message)`:
* Equivalent to:
`minetest.get_color_escape_sequence(color) ..
- message ..
- minetest.get_color_escape_sequence("#ffffff")`
+ message ..
+ minetest.get_color_escape_sequence("#ffffff")`
* `minetest.get_background_escape_sequence(color)`
* `color` is a ColorString
* The escape sequence sets the background of the whole text element to
@@ -2101,98 +2352,147 @@ The following functions provide escape sequences:
Spatial Vectors
---------------
-* `vector.new(a[, b, c])`: returns a vector:
+For the following functions, `v`, `v1`, `v2` are vectors,
+`p1`, `p2` are positions:
+
+* `vector.new(a[, b, c])`:
+ * Returns a vector.
* A copy of `a` if `a` is a vector.
- * `{x = a, y = b, z = c}`, if all `a, b, c` are defined
-* `vector.direction(p1, p2)`: returns a vector
-* `vector.distance(p1, p2)`: returns a number
-* `vector.length(v)`: returns a number
-* `vector.normalize(v)`: returns a vector
-* `vector.floor(v)`: returns a vector, each dimension rounded down
-* `vector.round(v)`: returns a vector, each dimension rounded to nearest int
-* `vector.apply(v, func)`: returns a vector
-* `vector.equals(v1, v2)`: returns a boolean
-* `vector.sort(v1, v2)`: returns minp, maxp vectors of the cuboid defined by v1 and v2
+ * `{x = a, y = b, z = c}`, if all of `a`, `b`, `c` are defined numbers.
+* `vector.direction(p1, p2)`:
+ * Returns a vector of length 1 with direction `p1` to `p2`.
+ * If `p1` and `p2` are identical, returns `{x = 0, y = 0, z = 0}`.
+* `vector.distance(p1, p2)`:
+ * Returns zero or a positive number, the distance between `p1` and `p2`.
+* `vector.length(v)`:
+ * Returns zero or a positive number, the length of vector `v`.
+* `vector.normalize(v)`:
+ * Returns a vector of length 1 with direction of vector `v`.
+ * If `v` has zero length, returns `{x = 0, y = 0, z = 0}`.
+* `vector.floor(v)`:
+ * Returns a vector, each dimension rounded down.
+* `vector.round(v)`:
+ * Returns a vector, each dimension rounded to nearest integer.
+* `vector.apply(v, func)`:
+ * Returns a vector where the function `func` has been applied to each
+ component.
+* `vector.equals(v1, v2)`:
+ * Returns a boolean, `true` if the vectors are identical.
+* `vector.sort(v1, v2)`:
+ * Returns in order minp, maxp vectors of the cuboid defined by `v1`, `v2`.
For the following functions `x` can be either a vector or a number:
-* `vector.add(v, x)`: returns a vector
-* `vector.subtract(v, x)`: returns a vector
-* `vector.multiply(v, x)`: returns a scaled vector or Schur product
-* `vector.divide(v, x)`: returns a scaled vector or Schur quotient
+* `vector.add(v, x)`:
+ * Returns a vector.
+* `vector.subtract(v, x)`:
+ * Returns a vector.
+* `vector.multiply(v, x)`:
+ * Returns a scaled vector or Schur product.
+* `vector.divide(v, x)`:
+ * Returns a scaled vector or Schur quotient.
Helper functions
----------------
-* `dump2(obj, name="_", dumped={})`
- * Return object serialized as a string, handles reference loops
-* `dump(obj, dumped={})`
- * Return object serialized as a string
+* `dump2(obj, name, dumped)`: returns a string which makes `obj`
+ human-readable, handles reference loops.
+ * `obj`: arbitrary variable
+ * `name`: string, default: `"_"`
+ * `dumped`: table, default: `{}`
+* `dump(obj, dumped)`: returns a string which makes `obj` human-readable
+ * `obj`: arbitrary variable
+ * `dumped`: table, default: `{}`
* `math.hypot(x, y)`
* Get the hypotenuse of a triangle with legs x and y.
Useful for distance calculation.
-* `math.sign(x, tolerance)`
+* `math.sign(x, tolerance)`: returns `-1`, `0` or `1`
* Get the sign of a number.
- Optional: Also returns `0` when the absolute value is within the tolerance (default: `0`)
-* `string.split(str, separator=",", include_empty=false, max_splits=-1, sep_is_pattern=false)`
- * If `max_splits` is negative, do not limit splits.
- * `sep_is_pattern` specifies if separator is a plain string or a pattern (regex).
- * e.g. `string:split("a,b", ",") == {"a","b"}`
-* `string:trim()`
- * e.g. `string.trim("\n \t\tfoo bar\t ") == "foo bar"`
-* `minetest.wrap_text(str, limit)`: returns a string
- * Adds new lines to the string to keep it within the specified character limit
- * limit: Maximal amount of characters in one line
-* `minetest.pos_to_string({x=X,y=Y,z=Z}, decimal_places))`: returns string `"(X,Y,Z)"`
- * Convert position to a printable string
- Optional: 'decimal_places' will round the x, y and z of the pos to the given decimal place.
-* `minetest.string_to_pos(string)`: returns a position
- * Same but in reverse. Returns `nil` if the string can't be parsed to a position.
+ * tolerance: number, default: `0.0`
+ * If the absolute value of `x` is within the `tolerance` or `x` is NaN,
+ `0` is returned.
+* `string.split(str, separator, include_empty, max_splits, sep_is_pattern)`
+ * `separator`: string, default: `","`
+ * `include_empty`: boolean, default: `false`
+ * `max_splits`: number, if it's positive, splits aren't limited,
+ default: `-1`
+ * `sep_is_pattern`: boolean, it specifies whether separator is a plain
+ string or a pattern (regex), default: `false`
+ * e.g. `"a,b":split","` returns `{"a","b"}`
+* `string:trim()`: returns the string without whitespace pre- and suffixes
+ * e.g. `"\n \t\tfoo bar\t ":trim()` returns `"foo bar"`
+* `minetest.wrap_text(str, limit, as_table)`: returns a string or table
+ * Adds newlines to the string to keep it within the specified character
+ limit
+ * Note that the returned lines may be longer than the limit since it only
+ splits at word borders.
+ * `limit`: number, maximal amount of characters in one line
+ * `as_table`: boolean, if set to true, a table of lines instead of a string
+ is returned, default: `false`
+* `minetest.pos_to_string(pos, decimal_places)`: returns string `"(X,Y,Z)"`
+ * `pos`: table {x=X, y=Y, z=Z}
+ * Converts the position `pos` to a human-readable, printable string
+ * `decimal_places`: number, if specified, the x, y and z values of
+ the position are rounded to the given decimal place.
+* `minetest.string_to_pos(string)`: returns a position or `nil`
+ * Same but in reverse.
+ * If the string can't be parsed to a position, nothing is returned.
* `minetest.string_to_area("(X1, Y1, Z1) (X2, Y2, Z2)")`: returns two positions
* Converts a string representing an area box into two positions
* `minetest.formspec_escape(string)`: returns a string
- * escapes the characters "[", "]", "\", "," and ";", which can not be used in formspecs
+ * escapes the characters "[", "]", "\", "," and ";", which can not be used
+ in formspecs.
* `minetest.is_yes(arg)`
* returns true if passed 'y', 'yes', 'true' or a number that isn't zero.
* `minetest.get_us_time()`
* returns time with microsecond precision. May not return wall time.
* `table.copy(table)`: returns a table
* returns a deep copy of `table`
-* `minetest.pointed_thing_to_face_pos(placer, pointed_thing)`: returns a position
+* `minetest.pointed_thing_to_face_pos(placer, pointed_thing)`: returns a
+ position.
* returns the exact position on the surface of a pointed node
Translations
------------
-Texts can be translated client-side with the help of `minetest.translate` and translation files.
+Texts can be translated client-side with the help of `minetest.translate` and
+translation files.
### Translating a string
-Two functions are provided to translate strings: `minetest.translate` and `minetest.get_translator`.
+Two functions are provided to translate strings: `minetest.translate` and
+`minetest.get_translator`.
-* `minetest.get_translator(textdomain)` is a simple wrapper around `minetest.translate`, and
- `minetest.get_translator(textdomain)(str, ...)` is equivalent to `minetest.translate(textdomain, str, ...)`.
- It is intended to be used in the following way, so that it avoids verbose repetitions of `minetest.translate`:
+* `minetest.get_translator(textdomain)` is a simple wrapper around
+ `minetest.translate`, and `minetest.get_translator(textdomain)(str, ...)` is
+ equivalent to `minetest.translate(textdomain, str, ...)`.
+ 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, ...)
As an extra commodity, if `textdomain` is nil, it is assumed to be "" instead.
-* `minetest.translate(textdomain, str, ...)` translates the string `str` with the given `textdomain`
- for disambiguation. The textdomain must match the textdomain specified in the translation file in order
- to get the string translated. This can be used so that a string is translated differently in different contexts.
- It is advised to use the name of the mod as textdomain whenever possible, to avoid clashes with other mods.
- This function must be given a number of arguments equal to the number of arguments the translated string expects.
- Arguments are literal strings -- they will not be translated, so if you want them to be, they need to come as
- outputs of `minetest.translate` as well.
-
- For instance, suppose we want to translate "@1 Wool" with "@1" being replaced by the translation of "Red".
- We can do the following:
+* `minetest.translate(textdomain, str, ...)` translates the string `str` with
+ the given `textdomain` for disambiguation. The textdomain must match the
+ textdomain specified in the translation file in order to get the string
+ translated. This can be used so that a string is translated differently in
+ different contexts.
+ It is advised to use the name of the mod as textdomain whenever possible, to
+ avoid clashes with other mods.
+ This function must be given a number of arguments equal to the number of
+ arguments the translated string expects.
+ Arguments are literal strings -- they will not be translated, so if you want
+ them to be, they need to come as outputs of `minetest.translate` as well.
+
+ 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"))
- 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 file named `wool.fr.tr` containing the following:
+ 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
+ file named `wool.fr.tr` containing the following:
@1 Wool=Laine @1
Red=Rouge
@@ -2201,35 +2501,43 @@ Two functions are provided to translate strings: `minetest.translate` and `minet
### Operations on translated strings
-The output of `minetest.translate` is a string, with escape sequences adding additional information to that string
-so that it can be translated on the different clients. In particular, you can't expect operations like string.length
-to work on them like you would expect them to, or string.gsub to work in the expected manner. However, string
-concatenation will still work as expected (note that you should only use this for things like formspecs; do not
-translate sentences by breaking them into parts; arguments should be used instead), and operations such as
-`minetest.colorize` which are only concatenation under the hood as well.
+The output of `minetest.translate` is a string, with escape sequences adding
+additional information to that string so that it can be translated on the
+different clients. In particular, you can't expect operations like string.length
+to work on them like you would expect them to, or string.gsub to work in the
+expected manner. However, string concatenation will still work as expected
+(note that you should only use this for things like formspecs; do not translate
+sentences by breaking them into parts; arguments should be used instead), and
+operations such as `minetest.colorize` which are also concatenation.
### Translation file format
-A translation file has the suffix `.[lang].tr`, where `[lang]` is the language it corresponds to.
+A translation file has the suffix `.[lang].tr`, where `[lang]` is the language
+it corresponds to.
The file should be a text file, with the following format:
-* Lines beginning with `# textdomain:` (the space is significant) can be used to specify the text
- domain of all following translations in the file.
+* Lines beginning with `# textdomain:` (the space is significant) can be used
+ to specify the text domain of all following translations in the file.
* All other empty lines or lines beginning with `#` are ignored.
-* Other lines should be in the format `original=translated`. Both `original` and `translated` can
- contain escape sequences beginning with `@` to insert arguments, literal `@`, `=` or newline
- (See ### Escapes below). There must be no extraneous whitespace around the `=` or at the beginning
- or the end of the line.
+* Other lines should be in the format `original=translated`. Both `original`
+ and `translated` can contain escape sequences beginning with `@` to insert
+ arguments, literal `@`, `=` or newline (See ### Escapes below).
+ There must be no extraneous whitespace around the `=` or at the beginning or
+ the end of the line.
### Escapes
Strings that need to be translated can contain several escapes, preceded by `@`.
+
* `@@` acts as a literal `@`.
-* `@n`, where `n` is a digit between 1 and 9, is an argument for the translated string that will be inlined
- when translation. Due to how translations are implemented, the original translation string **must** have
- its arguments in increasing order, without gaps or repetitions, starting from 1.
-* `@=` acts as a literal `=`. It is not required in strings given to `minetest.translate`, but is in translation
- files to avoid begin confused with the `=` separating the original from the translation.
-* `@\n` (where the `\n` is a literal newline) acts as a literal newline. As with `@=`, this escape is not required
- in strings given to `minetest.translate`, but is in translation files.
+* `@n`, where `n` is a digit between 1 and 9, is an argument for the translated
+ string that will be inlined when translation. Due to how translations are
+ implemented, the original translation string **must** have its arguments in
+ increasing order, without gaps or repetitions, starting from 1.
+* `@=` acts as a literal `=`. It is not required in strings given to
+ `minetest.translate`, but is in translation files to avoid being confused
+ with the `=` separating the original from the translation.
+* `@\n` (where the `\n` is a literal newline) acts as a literal newline.
+ As with `@=`, this escape is not required in strings given to
+ `minetest.translate`, but is in translation files.
* `@n` acts as a literal newline as well.
`minetest` namespace reference
@@ -2237,8 +2545,10 @@ Strings that need to be translated can contain several escapes, preceded by `@`.
### Utilities
-* `minetest.get_current_modname()`: returns the currently loading mod's name, when we are loading a mod
-* `minetest.get_modpath(modname)`: returns e.g. `"/home/user/.minetest/usermods/modname"`
+* `minetest.get_current_modname()`: returns the currently loading mod's name,
+ when loading a mod.
+* `minetest.get_modpath(modname)`: returns e.g.
+ `"/home/user/.minetest/usermods/modname"`.
* Useful for loading additional `.lua` modules or static data from mod
* `minetest.get_modnames()`: returns a list of installed mods
* Return a list of installed mods, sorted alphabetically
@@ -2269,7 +2579,8 @@ Strings that need to be translated can contain several escapes, preceded by `@`.
* `arg`: string or table in format `{foo=true, bar=true}`
* `missing_features`: `{foo=true, bar=true}`
* `minetest.get_player_information(player_name)`:
- * Returns a table containing information about a player. Example return value:
+ * Returns a table containing information about a player.
+ Example return value:
{
address = "127.0.0.1", -- IP address of client
@@ -2281,7 +2592,7 @@ Strings that need to be translated can contain several escapes, preceded by `@`.
max_jitter = 0.5, -- maximum packet time jitter
avg_jitter = 0.03, -- average packet time jitter
connection_uptime = 200, -- seconds since client connected
- prot_vers = 31, -- protocol version used by client
+ protocol_version = 32, -- protocol version used by client
-- following information is available on debug build only!!!
-- DO NOT USE IN MODS
--ser_vers = 26, -- serialization version used by client
@@ -2296,20 +2607,28 @@ Strings that need to be translated can contain several escapes, preceded by `@`.
if they don't exist.
* `minetest.get_dir_list(path, [is_dir])`: returns list of entry names
* is_dir is one of:
- * nil: return all entries,
- * true: return only subdirectory names, or
- * false: return only file names.
+ * nil: return all entries,
+ * true: return only subdirectory names, or
+ * false: return only file names.
+* `minetest.safe_file_write(path, content)`: returns boolean indicating success
+ * Replaces contents of file at path with new contents in a safe (atomic)
+ way. Use this instead of below code when writing e.g. database files:
+ `local f = io.open(path, "wb"); f:write(content); f:close()`
* `minetest.get_version()`: returns a table containing components of the
engine version. Components:
* `project`: Name of the project, eg, "Minetest"
* `string`: Simple version, eg, "1.2.3-dev"
- * `hash`: Full git version (only set if available), eg, "1.2.3-dev-01234567-dirty"
+ * `hash`: Full git version (only set if available),
+ eg, "1.2.3-dev-01234567-dirty".
Use this for informational purposes only. The information in the returned
table does not represent the capabilities of the engine, nor is it
- reliable or verifyable. Compatible forks will have a different name and
+ reliable or verifiable. Compatible forks will have a different name and
version entirely. To check for the presence of engine features, test
whether the functions exported by the wanted features exist. For example:
- `if minetest.nodeupdate then ... end`.
+ `if minetest.check_for_falling then ... end`.
+* `minetest.sha1(data, [raw])`: returns the sha1 hash of data
+ * `data`: string of data to hash
+ * `raw`: return raw bytes instead of hex digits, default: false
### Logging
* `minetest.debug(...)`
@@ -2329,16 +2648,21 @@ Call these functions only at load time!
* `minetest.register_craftitem(name, item definition)`
* `minetest.unregister_item(name)`
* `minetest.register_alias(name, convert_to)`
+ * Also use this to set the 'mapgen aliases' needed in a game for the core
+ * mapgens. See 'Mapgen aliases' section above.
* `minetest.register_alias_force(name, convert_to)`
* `minetest.register_craft(recipe)`
* Check recipe table syntax for different types below.
* `minetest.clear_craft(recipe)`
* Will erase existing craft based either on output item or on input recipe.
- * Specify either output or input only. If you specify both, input will be ignored. For input use the same recipe table
- syntax as for `minetest.register_craft(recipe)`. For output specify only the item, without a quantity.
+ * Specify either output or input only. If you specify both, input will be
+ ignored. For input use the same recipe table syntax as for
+ `minetest.register_craft(recipe)`. For output specify only the item,
+ without a quantity.
* If no erase candidate could be found, Lua exception will be thrown.
- * **Warning**! The type field ("shaped","cooking" or any other) will be ignored if the recipe
- contains output. Erasing is then done independently from the crafting method.
+ * **Warning**! The type field ("shaped","cooking" or any other) will be
+ ignored if the recipe contains output. Erasing is then done independently
+ from the crafting method.
* `minetest.register_ore(ore definition)`
* `minetest.register_biome(biome definition)`
* `minetest.register_decoration(decoration definition)`
@@ -2357,57 +2681,66 @@ Call these functions only at load time!
* Called every server step, usually interval of 0.1s
* `minetest.register_on_shutdown(func())`
* Called before server shutdown
- * **Warning**: If the server terminates abnormally (i.e. crashes), the registered
- callbacks **will likely not be run**. Data should be saved at
+ * **Warning**: If the server terminates abnormally (i.e. crashes), the
+ registered callbacks **will likely not be run**. Data should be saved at
semi-frequent intervals as well as on server shutdown.
* `minetest.register_on_placenode(func(pos, newnode, placer, oldnode, itemstack, pointed_thing))`
* Called when a node has been placed
* If return `true` no item is taken from `itemstack`
- * **Not recommended**; use `on_construct` or `after_place_node` in node definition
- whenever possible
+ * `placer` may be any valid ObjectRef or nil.
+ * **Not recommended**; use `on_construct` or `after_place_node` in node
+ definition whenever possible.
* `minetest.register_on_dignode(func(pos, oldnode, digger))`
* Called when a node has been dug.
- * **Not recommended**; Use `on_destruct` or `after_dig_node` in node definition
- whenever possible
+ * **Not recommended**; Use `on_destruct` or `after_dig_node` in node
+ definition whenever possible.
* `minetest.register_on_punchnode(func(pos, node, puncher, pointed_thing))`
- * Called when a node is punched
+ * Called when a node is punched
* `minetest.register_on_generated(func(minp, maxp, blockseed))`
- * Called after generating a piece of world. Modifying nodes inside the area
- is a bit faster than usually.
+ * Called after generating a piece of world. Modifying nodes inside the area
+ is a bit faster than usually.
* `minetest.register_on_newplayer(func(ObjectRef))`
- * Called after a new player has been created
+ * Called after a new player has been created
* `minetest.register_on_dieplayer(func(ObjectRef))`
- * Called when a player dies
+ * Called when a player dies
* `minetest.register_on_punchplayer(func(player, hitter, time_from_last_punch, tool_capabilities, dir, damage))`
- * Called when a player is punched
- * `player` - ObjectRef - Player that was punched
- * `hitter` - ObjectRef - Player that hit
- * `time_from_last_punch`: Meant for disallowing spamming of clicks (can be nil)
- * `tool_capabilities`: capability table of used tool (can be nil)
- * `dir`: unit vector of direction of punch. Always defined. Points from
- the puncher to the punched.
- * `damage` - number that represents the damage calculated by the engine
- * should return `true` to prevent the default damage mechanism
+ * Called when a player is punched
+ * `player` - ObjectRef - Player that was punched
+ * `hitter` - ObjectRef - Player that hit
+ * `time_from_last_punch`: Meant for disallowing spamming of clicks
+ (can be nil).
+ * `tool_capabilities`: capability table of used tool (can be nil)
+ * `dir`: unit vector of direction of punch. Always defined. Points from
+ the puncher to the punched.
+ * `damage` - number that represents the damage calculated by the engine
+ * should return `true` to prevent the default damage mechanism
* `minetest.register_on_player_hpchange(func(player, hp_change), modifier)`
* Called when the player gets damaged or healed
* `player`: ObjectRef of the player
* `hp_change`: the amount of change. Negative when it is damage.
* `modifier`: when true, the function should return the actual `hp_change`.
- Note: modifiers only get a temporary hp_change that can be modified by later modifiers.
- modifiers can return true as a second argument to stop the execution of further functions.
- Non-modifiers receive the final hp change calculated by the modifiers.
+ Note: modifiers only get a temporary hp_change that can be modified by
+ later modifiers. modifiers can return true as a second argument to stop
+ the execution of further functions. Non-modifiers receive the final hp
+ change calculated by the modifiers.
* `minetest.register_on_respawnplayer(func(ObjectRef))`
- * Called when player is to be respawned
- * Called _before_ repositioning of player occurs
- * return true in func to disable regular player placement
+ * Called when player is to be respawned
+ * Called _before_ repositioning of player occurs
+ * return true in func to disable regular player placement
* `minetest.register_on_prejoinplayer(func(name, ip))`
- * Called before a player joins the game
- * If it returns a string, the player is disconnected with that string as reason
+ * Called before a player joins the game
+ * If it returns a string, the player is disconnected with that string as
+ reason.
* `minetest.register_on_joinplayer(func(ObjectRef))`
* Called when a player joins the game
* `minetest.register_on_leaveplayer(func(ObjectRef, timed_out))`
* Called when a player leaves the game
* `timed_out`: True for timeout, false for other reasons.
+* `minetest.register_on_auth_fail(func(name, ip))`
+ * Called when a client attempts to log into an account but supplies the
+ wrong password.
+ * `ip`: The IP address of the client.
+ * `name`: The account the client attempted to log into.
* `minetest.register_on_cheat(func(ObjectRef, cheat))`
* Called when a player cheats
* `cheat`: `{type=}`, where `` is one of:
@@ -2419,7 +2752,8 @@ Call these functions only at load time!
* `dug_too_fast`
* `minetest.register_on_chat_message(func(name, message))`
* Called always when a player says something
- * Return `true` to mark the message as handled, which means that it will not be sent to other players
+ * Return `true` to mark the message as handled, which means that it will
+ not be sent to other players.
* `minetest.register_on_player_receive_fields(func(player, formname, fields))`
* Called when a button is pressed in player's inventory form
* Newest functions are called first
@@ -2427,22 +2761,41 @@ Call these functions only at load time!
* `minetest.register_on_craft(func(itemstack, player, old_craft_grid, craft_inv))`
* Called when `player` crafts something
* `itemstack` is the output
- * `old_craft_grid` contains the recipe (Note: the one in the inventory is cleared)
+ * `old_craft_grid` contains the recipe (Note: the one in the inventory is
+ cleared).
* `craft_inv` is the inventory with the crafting grid
- * Return either an `ItemStack`, to replace the output, or `nil`, to not modify it
+ * Return either an `ItemStack`, to replace the output, or `nil`, to not
+ modify it.
* `minetest.register_craft_predict(func(itemstack, player, old_craft_grid, craft_inv))`
- * The same as before, except that it is called before the player crafts, to make
- craft prediction, and it should not change anything.
+ * The same as before, except that it is called before the player crafts, to
+ make craft prediction, and it should not change anything.
* `minetest.register_on_protection_violation(func(pos, name))`
- * Called by `builtin` and mods when a player violates protection at a position
- (eg, digs a node or punches a protected entity).
- * The registered functions can be called using `minetest.record_protection_violation`
- * The provided function should check that the position is protected by the mod
- calling this function before it prints a message, if it does, to allow for
- multiple protection mods.
+ * Called by `builtin` and mods when a player violates protection at a
+ position (eg, digs a node or punches a protected entity).
+ * The registered functions can be called using
+ `minetest.record_protection_violation`.
+ * The provided function should check that the position is protected by the
+ mod calling this function before it prints a message, if it does, to
+ allow for multiple protection mods.
* `minetest.register_on_item_eat(func(hp_change, replace_with_item, itemstack, user, pointed_thing))`
* Called when an item is eaten, by `minetest.item_eat`
- * Return `true` or `itemstack` to cancel the default item eat response (i.e.: hp increase)
+ * Return `true` or `itemstack` to cancel the default item eat response
+ (i.e.: hp increase).
+* `minetest.register_on_priv_grant(function(name, granter, priv))`
+ * Called when `granter` grants the priv `priv` to `name`.
+ * Note that the callback will be called twice if it's done by a player,
+ once with granter being the player name, and again with granter being nil.
+* `minetest.register_on_priv_revoke(function(name, revoker, priv))`
+ * Called when `revoker` revokes the priv `priv` from `name`.
+ * Note that the callback will be called twice if it's done by a player,
+ once with revoker being the player name, and again with revoker being nil.
+* `minetest.register_can_bypass_userlimit(function(name, ip))`
+ * Called when `name` user connects with `ip`.
+ * Return `true` to by pass the player limit
+* `minetest.register_on_modchannel_message(func(channel_name, sender, message))`
+ * Called when an incoming mod channel message is received
+ * You should have joined some channels to receive events.
+ * If message comes from a server mod, `sender` field is an empty string.
### Other registration functions
* `minetest.register_chatcommand(cmd, chatcommand definition)`
@@ -2453,17 +2806,24 @@ Call these functions only at load time!
* Unregisters a chatcommands registered with `register_chatcommand`.
* `minetest.register_privilege(name, definition)`
* `definition`: `"description text"`
- * `definition`: `{ description = "description text", give_to_singleplayer = boolean}`
- the default of `give_to_singleplayer` is true
- * To allow players with `basic_privs` to grant, see `basic_privs` minetest.conf setting.
- * `on_grant(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(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.
-* `minetest.register_authentication_handler(handler)`
- * See `minetest.builtin_auth_handler` in `builtin.lua` for reference
+ * `definition`:
+ `{description = "description text", give_to_singleplayer = boolean}`
+ the default of `give_to_singleplayer` is true.
+ * To allow players with `basic_privs` to grant, see `basic_privs`
+ minetest.conf setting.
+ * `on_grant(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(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.
+* `minetest.register_authentication_handler(authentication handler definition)`
+ * Registers an auth handler that overrides the builtin one
+ * This function can be called by a single mod once only.
### Setting-related
* `minetest.settings`: Settings object containing all of the settings from the
@@ -2472,40 +2832,52 @@ Call these functions only at load time!
parses it as a position (in the format `(1,2,3)`). Returns a position or nil.
### Authentication
-* `minetest.notify_authentication_modified(name)`
- * Should be called by the authentication handler if privileges changes.
- * To report everybody, set `name=nil`.
+* `minetest.string_to_privs(str)`: returns `{priv1=true,...}`
+* `minetest.privs_to_string(privs)`: returns `"priv1,priv2,..."`
+ * Convert between two privilege representations
+* `minetest.get_player_privs(name) -> {priv1=true,...}`
+* `minetest.check_player_privs(player_or_name, ...)`:
+ returns `bool, missing_privs`
+ * A quickhand for checking privileges.
+ * `player_or_name`: Either a Player object or the name of a player.
+ * `...` is either a list of strings, e.g. `"priva", "privb"` or
+ a table, e.g. `{ priva = true, privb = true }`.
+
* `minetest.check_password_entry(name, entry, password)`
- * Returns true if the "db entry" for a player with name matches given
- * password, false otherwise.
- * The "db entry" is the usually player-individual value that is derived
- * from the player's chosen password and stored on the server in order to allow
- * authentication whenever the player desires to log in.
- * Only use this function for making it possible to log in via the password from
- * via protocols like IRC, other uses for inside the game are frowned upon.
+ * Returns true if the "password entry" for a player with name matches given
+ password, false otherwise.
+ * The "password entry" is the password representation generated by the
+ engine as returned as part of a `get_auth()` call on the auth handler.
+ * Only use this function for making it possible to log in via password from
+ external protocols such as IRC, other uses are frowned upon.
* `minetest.get_password_hash(name, raw_password)`
* Convert a name-password pair to a password hash that Minetest can use.
* The returned value alone is not a good basis for password checks based
- * on comparing the password hash in the database with the password hash
- * from the function, with an externally provided password, as the hash
- * in the db might use the new SRP verifier format.
+ on comparing the password hash in the database with the password hash
+ from the function, with an externally provided password, as the hash
+ in the db might use the new SRP verifier format.
* For this purpose, use `minetest.check_password_entry` instead.
-* `minetest.string_to_privs(str)`: returns `{priv1=true,...}`
-* `minetest.privs_to_string(privs)`: returns `"priv1,priv2,..."`
- * Convert between two privilege representations
-* `minetest.set_player_password(name, password_hash)`
-* `minetest.set_player_privs(name, {priv1=true,...})`
-* `minetest.get_player_privs(name) -> {priv1=true,...}`
+* `minetest.get_player_ip(name)`: returns an IP address string for the player
+ `name`.
+ * The player needs to be online for this to be successful.
+
+* `minetest.get_auth_handler()`: Return the currently active auth handler
+ * See the `Authentication handler definition`
+ * Use this to e.g. get the authentication data for a player:
+ `local auth_data = minetest.get_auth_handler().get_auth(playername)`
+* `minetest.notify_authentication_modified(name)`
+ * Must be called by the authentication handler for privilege changes.
+ * `name`: string; if omitted, all auth data should be considered modified
+* `minetest.set_player_password(name, password_hash)`: Set password hash of
+ player `name`.
+* `minetest.set_player_privs(name, {priv1=true,...})`: Set privileges of player
+ `name`.
* `minetest.auth_reload()`
-* `minetest.check_player_privs(player_or_name, ...)`: returns `bool, missing_privs`
- * A quickhand for checking privileges.
- * `player_or_name`: Either a Player object or the name of a player.
- * `...` is either a list of strings, e.g. `"priva", "privb"` or
- a table, e.g. `{ priva = true, privb = true }`.
-* `minetest.get_player_ip(name)`: returns an IP address string
+ * See `reload()` in authentication handler definition
-`minetest.set_player_password`, `minetest_set_player_privs`, `minetest_get_player_privs`
-and `minetest.auth_reload` call the authetification handler.
+`minetest.set_player_password`, `minetest_set_player_privs`,
+`minetest_get_player_privs` and `minetest.auth_reload` call the authentication
+handler.
### Chat
* `minetest.chat_send_all(text)`
@@ -2513,16 +2885,29 @@ and `minetest.auth_reload` call the authetification handler.
### Environment access
* `minetest.set_node(pos, node)`
-* `minetest.add_node(pos, node): alias set_node(pos, node)`
- * Set node at position (`node = {name="foo", param1=0, param2=0}`)
+* `minetest.add_node(pos, node): alias to `minetest.set_node`
+ * Set node at position `pos`
+ * `node`: table `{name=string, param1=number, param2=number}`
+ * If param1 or param2 is omitted, it's set to `0`.
+ * e.g. `minetest.set_node({x=0, y=10, z=0}, {name="default:wood"})`
+* `minetest.bulk_set_node({pos1, pos2, pos3, ...}, node)`
+ * Set node on all positions set in the first argument.
+ * e.g. `minetest.bulk_set_node({{x=0, y=1, z=1}, {x=1, y=2, z=2}}, {name="default:stone"})`
+ * For node specification or position syntax see `minetest.set_node` call
+ * Faster than set_node due to single call, but still considerably slower
+ than Lua Voxel Manipulators (LVM) for large numbers of nodes.
+ Unlike LVMs, this will call node callbacks. It also allows setting nodes
+ in spread out positions which would cause LVMs to waste memory.
+ For setting a cube, this is 1.3x faster than set_node whereas LVM is 20
+ times faster.
* `minetest.swap_node(pos, node)`
* Set node at position, but don't remove metadata
* `minetest.remove_node(pos)`
- * Equivalent to `set_node(pos, "air")`
+ * By default it does the same as `minetest.set_node(pos, {name="air"})`
* `minetest.get_node(pos)`
* Returns the node at the given position as table in the format
- `{name="node_name", param1=0, param2=0}`, returns `{name="ignore", param1=0, param2=0}`
- for unloaded areas.
+ `{name="node_name", param1=0, param2=0}`,
+ returns `{name="ignore", param1=0, param2=0}` for unloaded areas.
* `minetest.get_node_or_nil(pos)`
* Same as `get_node` but returns `nil` for unloaded areas.
* `minetest.get_node_light(pos, timeofday)`
@@ -2544,37 +2929,48 @@ and `minetest.auth_reload` call the authetification handler.
* Returns `true` if successful, `false` on failure
* `minetest.find_nodes_with_meta(pos1, pos2)`
- * Get a table of positions of nodes that have metadata within a region {pos1, pos2}
+ * Get a table of positions of nodes that have metadata within a region
+ {pos1, pos2}.
* `minetest.get_meta(pos)`
* Get a `NodeMetaRef` at that position
* `minetest.get_node_timer(pos)`
* Get `NodeTimerRef`
-* `minetest.add_entity(pos, name, [staticdata])`: Spawn Lua-defined entity at position
+* `minetest.add_entity(pos, name, [staticdata])`: Spawn Lua-defined entity at
+ position.
* Returns `ObjectRef`, or `nil` if failed
* `minetest.add_item(pos, item)`: Spawn item
* Returns `ObjectRef`, or `nil` if failed
* `minetest.get_player_by_name(name)`: Get an `ObjectRef` to a player
-* `minetest.get_objects_inside_radius(pos, radius)`
+* `minetest.get_objects_inside_radius(pos, radius)`: returns a list of
+ ObjectRefs.
* `radius`: using an euclidean metric
* `minetest.set_timeofday(val)`
* `val` is between `0` and `1`; `0` for midnight, `0.5` for midday
* `minetest.get_timeofday()`
-* `minetest.get_gametime()`: returns the time, in seconds, since the world was created
-* `minetest.get_day_count()`: returns number days elapsed since world was created,
- * accounting for time changes.
-* `minetest.find_node_near(pos, radius, nodenames, [search_center])`: returns pos or `nil`
+* `minetest.get_gametime()`: returns the time, in seconds, since the world was
+ created.
+* `minetest.get_day_count()`: returns number days elapsed since world was
+ created.
+ * accounts for time changes.
+* `minetest.find_node_near(pos, radius, nodenames, [search_center])`: returns
+ pos or `nil`.
* `radius`: using a maximum metric
* `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
* `search_center` is an optional boolean (default: `false`)
If true `pos` is also checked for the nodes
-* `minetest.find_nodes_in_area(pos1, pos2, nodenames)`: returns a list of positions
+* `minetest.find_nodes_in_area(pos1, pos2, nodenames)`: returns a list of
+ positions.
* `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
* First return value: Table with all node positions
- * Second return value: Table with the count of each node with the node name as index
-* `minetest.find_nodes_in_area_under_air(pos1, pos2, nodenames)`: returns a list of positions
+ * Second return value: Table with the count of each node with the node name
+ as index.
+ * Area volume is limited to 4,096,000 nodes
+* `minetest.find_nodes_in_area_under_air(pos1, pos2, nodenames)`: returns a
+ list of positions.
* `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
* Return value: Table with all node positions with a node air above
+ * Area volume is limited to 4,096,000 nodes
* `minetest.get_perlin(noiseparams)`
* `minetest.get_perlin(seeddiff, octaves, persistence, scale)`
* Return world-specific perlin noise (`int(worldseed)+seeddiff`)
@@ -2582,87 +2978,138 @@ and `minetest.auth_reload` call the authetification handler.
* Return voxel manipulator object.
* Loads the manipulator from the map if positions are passed.
* `minetest.set_gen_notify(flags, {deco_ids})`
- * Set the types of on-generate notifications that should be collected
- * `flags` is a flag field with the available flags: `dungeon`, `temple`, `cave_begin`,
- `cave_end`, `large_cave_begin`, `large_cave_end`, `decoration`
- * The second parameter is a list of IDS of decorations which notification is requested for
-* `get_gen_notify()`: returns a flagstring and a table with the `deco_id`s
+ * Set the types of on-generate notifications that should be collected.
+ * `flags` is a flag field with the available flags:
+ * dungeon
+ * temple
+ * cave_begin
+ * cave_end
+ * large_cave_begin
+ * large_cave_end
+ * decoration
+ * The second parameter is a list of IDS of decorations which notification
+ is requested for.
+* `minetest.get_gen_notify()`
+ * Returns a flagstring and a table with the `deco_id`s.
+* `minetest.get_decoration_id(decoration_name)
+ * Returns the decoration ID number for the provided decoration name string,
+ or `nil` on failure.
* `minetest.get_mapgen_object(objectname)`
* Return requested mapgen object if available (see "Mapgen objects")
+* `minetest.get_heat(pos)`
+ * Returns the heat at the position, or `nil` on failure.
+* `minetest.get_humidity(pos)`
+ * Returns the humidity at the position, or `nil` on failure.
+* `minetest.get_biome_data(pos)`
+ * Returns a table containing:
+ * `biome` the biome id of the biome at that position
+ * `heat` the heat at the position
+ * `humidity` the humidity at the position
+ * Or returns `nil` on failure.
* `minetest.get_biome_id(biome_name)`
- * Returns the biome id, as used in the biomemap Mapgen object, for a
- given biome_name string.
-* `minetest.get_mapgen_params()` Returns mapgen parameters, a table containing
- `mgname`, `seed`, `chunksize`, `water_level`, and `flags`.
- * Deprecated: use `minetest.get_mapgen_setting(name)` instead
+ * Returns the biome id, as used in the biomemap Mapgen object and returned
+ by `minetest.get_biome_data(pos)`, for a given biome_name string.
+* `minetest.get_biome_name(biome_id)`
+ * Returns the biome name string for the provided biome id, or `nil` on
+ failure.
+ * If no biomes have been registered, such as in mgv6, returns `default`.
+* `minetest.get_mapgen_params()`
+ * Deprecated: use `minetest.get_mapgen_setting(name)` instead.
+ * Returns a table containing:
+ * `mgname`
+ * `seed`
+ * `chunksize`
+ * `water_level`
+ * `flags`
* `minetest.set_mapgen_params(MapgenParams)`
- * Deprecated: use `minetest.set_mapgen_setting(name, value, override)` instead
- * Set map generation parameters
- * Function cannot be called after the registration period; only initialization
- and `on_mapgen_init`
- * Takes a table as an argument with the fields `mgname`, `seed`, `water_level`,
- and `flags`.
- * Leave field unset to leave that parameter unchanged
- * `flags` contains a comma-delimited string of flags to set,
- or if the prefix `"no"` is attached, clears instead.
- * `flags` is in the same format and has the same options as `mg_flags` in `minetest.conf`
+ * Deprecated: use `minetest.set_mapgen_setting(name, value, override)`
+ instead.
+ * Set map generation parameters.
+ * Function cannot be called after the registration period; only
+ initialization and `on_mapgen_init`.
+ * Takes a table as an argument with the fields:
+ * `mgname`
+ * `seed`
+ * `chunksize`
+ * `water_level`
+ * `flags`
+ * Leave field unset to leave that parameter unchanged.
+ * `flags` contains a comma-delimited string of flags to set, or if the
+ prefix `"no"` is attached, clears instead.
+ * `flags` is in the same format and has the same options as `mg_flags` in
+ `minetest.conf`.
* `minetest.get_mapgen_setting(name)`
- * Gets the *active* mapgen setting (or nil if none exists) in string format with the following
- order of precedence:
- 1) Settings loaded from map_meta.txt or overrides set during mod execution
+ * Gets the *active* mapgen setting (or nil if none exists) in string
+ format with the following order of precedence:
+ 1) Settings loaded from map_meta.txt or overrides set during mod
+ execution.
2) Settings set by mods without a metafile override
3) Settings explicitly set in the user config file, minetest.conf
4) Settings set as the user config default
* `minetest.get_mapgen_setting_noiseparams(name)`
- * Same as above, but returns the value as a NoiseParams table if the setting `name` exists
- and is a valid NoiseParams
+ * Same as above, but returns the value as a NoiseParams table if the
+ setting `name` exists and is a valid NoiseParams.
* `minetest.set_mapgen_setting(name, value, [override_meta])`
- * Sets a mapgen param to `value`, and will take effect if the corresponding mapgen setting
- is not already present in map_meta.txt.
- * `override_meta` is an optional boolean (default: `false`). If this is set to true,
- the setting will become the active setting regardless of the map metafile contents.
- * Note: to set the seed, use `"seed"`, not `"fixed_map_seed"`
+ * Sets a mapgen param to `value`, and will take effect if the corresponding
+ mapgen setting is not already present in map_meta.txt.
+ * `override_meta` is an optional boolean (default: `false`). If this is set
+ to true, the setting will become the active setting regardless of the map
+ metafile contents.
+ * Note: to set the seed, use `"seed"`, not `"fixed_map_seed"`.
* `minetest.set_mapgen_setting_noiseparams(name, value, [override_meta])`
- * Same as above, except value is a NoiseParams table.
+ * Same as above, except value is a NoiseParams table.
* `minetest.set_noiseparams(name, noiseparams, set_default)`
- * Sets the noiseparams setting of `name` to the noiseparams table specified in `noiseparams`.
- * `set_default` is an optional boolean (default: `true`) that specifies whether the setting
- should be applied to the default config or current active config
-* `minetest.get_noiseparams(name)`: returns a table of the noiseparams for name
+ * Sets the noiseparams setting of `name` to the noiseparams table specified
+ in `noiseparams`.
+ * `set_default` is an optional boolean (default: `true`) that specifies
+ whether the setting should be applied to the default config or current
+ active config.
+* `minetest.get_noiseparams(name)`
+ * Returns a table of the noiseparams for name.
* `minetest.generate_ores(vm, pos1, pos2)`
- * Generate all registered ores within the VoxelManip `vm` and in the area from `pos1` to `pos2`.
+ * Generate all registered ores within the VoxelManip `vm` and in the area
+ from `pos1` to `pos2`.
* `pos1` and `pos2` are optional and default to mapchunk minp and maxp.
* `minetest.generate_decorations(vm, pos1, pos2)`
- * Generate all registered decorations within the VoxelManip `vm` and in the area from `pos1` to `pos2`.
+ * Generate all registered decorations within the VoxelManip `vm` and in the
+ area from `pos1` to `pos2`.
* `pos1` and `pos2` are optional and default to mapchunk minp and maxp.
* `minetest.clear_objects([options])`
* Clear all objects in the environment
* Takes an optional table as an argument with the field `mode`.
- * mode = `"full"`: Load and go through every mapblock, clearing objects (default).
- * mode = `"quick"`: Clear objects immediately in loaded mapblocks;
- clear objects in unloaded mapblocks only when the mapblocks are next activated.
+ * mode = `"full"` : Load and go through every mapblock, clearing
+ objects (default).
+ * mode = `"quick"`: Clear objects immediately in loaded mapblocks,
+ clear objects in unloaded mapblocks only when the
+ mapblocks are next activated.
* `minetest.emerge_area(pos1, pos2, [callback], [param])`
- * Queue all blocks in the area from `pos1` to `pos2`, inclusive, to be asynchronously
- * fetched from memory, loaded from disk, or if inexistent, generates them.
- * If `callback` is a valid Lua function, this will be called for each block emerged.
+ * Queue all blocks in the area from `pos1` to `pos2`, inclusive, to be
+ asynchronously fetched from memory, loaded from disk, or if inexistent,
+ generates them.
+ * If `callback` is a valid Lua function, this will be called for each block
+ emerged.
* The function signature of callback is:
- * `function EmergeAreaCallback(blockpos, action, calls_remaining, param)`
- * - `blockpos` is the *block* coordinates of the block that had been emerged
- * - `action` could be one of the following constant values:
- * `minetest.EMERGE_CANCELLED`, `minetest.EMERGE_ERRORED`, `minetest.EMERGE_FROM_MEMORY`,
- * `minetest.EMERGE_FROM_DISK`, `minetest.EMERGE_GENERATED`
- * - `calls_remaining` is the number of callbacks to be expected after this one
- * - `param` is the user-defined parameter passed to emerge_area (or nil if the
- * parameter was absent)
+ * `function EmergeAreaCallback(blockpos, action, calls_remaining, param)`
+ * `blockpos` is the *block* coordinates of the block that had been
+ emerged.
+ * `action` could be one of the following constant values:
+ * `minetest.EMERGE_CANCELLED`
+ * `minetest.EMERGE_ERRORED`
+ * `minetest.EMERGE_FROM_MEMORY`
+ * `minetest.EMERGE_FROM_DISK`
+ * `minetest.EMERGE_GENERATED`
+ * `calls_remaining` is the number of callbacks to be expected after
+ this one.
+ * `param` is the user-defined parameter passed to emerge_area (or
+ nil if the parameter was absent).
* `minetest.delete_area(pos1, pos2)`
* delete all mapblocks in the area from pos1 to pos2, inclusive
-* `minetest.line_of_sight(pos1, pos2, stepsize)`: returns `boolean, pos`
- * Check if there is a direct line of sight between `pos1` and `pos2`
+* `minetest.line_of_sight(pos1, pos2)`: returns `boolean, pos`
+ * Checks if there is anything other than air between pos1 and pos2.
+ * Returns false if something is blocking the sight.
* Returns the position of the blocking node when `false`
* `pos1`: First position
* `pos2`: Second position
- * `stepsize`: smaller gives more accurate results but requires more computing
- time. Default is `1`.
* `minetest.raycast(pos1, pos2, objects, liquids)`: returns `Raycast`
* Creates a `Raycast` object.
* `pos1`: start of the ray
@@ -2671,10 +3118,12 @@ and `minetest.auth_reload` call the authetification handler.
* `liquids' : if false, liquid nodes won't be returned. Default is `false`.
* `minetest.find_path(pos1,pos2,searchdistance,max_jump,max_drop,algorithm)`
* returns table containing path
- * returns a table of 3D points representing a path from `pos1` to `pos2` or `nil`
+ * returns a table of 3D points representing a path from `pos1` to `pos2` or
+ `nil`.
* `pos1`: start position
* `pos2`: end position
- * `searchdistance`: number of blocks to search in each direction using a maximum metric
+ * `searchdistance`: number of blocks to search in each direction using a
+ maximum metric.
* `max_jump`: maximum height difference to consider walkable
* `max_drop`: maximum height difference to consider droppable
* `algorithm`: One of `"A*_noprefetch"` (default), `"A*"`, `"Dijkstra"`
@@ -2718,6 +3167,24 @@ and `minetest.auth_reload` call the authetification handler.
unattached `group:attached_node` node to fall.
* spread these updates to neighbours and can cause a cascade
of nodes to fall.
+* `minetest.get_spawn_level(x, z)`
+ * Returns a player spawn y co-ordinate for the provided (x, z)
+ co-ordinates, or `nil` for an unsuitable spawn point.
+ * For most mapgens a 'suitable spawn point' is one with y between
+ `water_level` and `water_level + 16`, and in mgv7 well away from rivers,
+ so `nil` will be returned for many (x, z) co-ordinates.
+ * The spawn level returned is for a player spawn in unmodified terrain.
+ * The spawn level is intentionally above terrain level to cope with
+ full-node biome 'dust' nodes.
+
+### Mod channels
+You can find mod channels communication scheme in `docs/mod_channels.png`.
+
+* `minetest.mod_channel_join(channel_name)`
+ * Server joins channel `channel_name`, and creates it if necessary. You
+ should listen from incoming messages with
+ `minetest.register_on_modchannel_message` call to receive incoming
+ messages.
### Inventory
`minetest.get_inventory(location)`: returns an `InvRef`
@@ -2726,14 +3193,17 @@ and `minetest.auth_reload` call the authetification handler.
* `{type="player", name="celeron55"}`
* `{type="node", pos={x=, y=, z=}}`
* `{type="detached", name="creative"}`
-* `minetest.create_detached_inventory(name, callbacks, [player_name])`: returns an `InvRef`
+* `minetest.create_detached_inventory(name, callbacks, [player_name])`: returns
+ an `InvRef`.
* callbacks: See "Detached inventory callbacks"
- * `player_name`: Make detached inventory available to one player exclusively,
- by default they will be sent to every player (even if not used).
- Note that this parameter is mostly just a workaround and will be removed in future releases.
+ * `player_name`: Make detached inventory available to one player
+ exclusively, by default they will be sent to every player (even if not
+ used).
+ Note that this parameter is mostly just a workaround and will be removed
+ in future releases.
* Creates a detached inventory. If it already exists, it is cleared.
* `minetest.do_item_eat(hp_change, replace_with_item, itemstack, user, pointed_thing)`:
- returns left over ItemStack
+ returns left over ItemStack.
* See `minetest.item_eat` and `minetest.register_on_item_eat`
### Formspec
@@ -2744,13 +3214,16 @@ and `minetest.auth_reload` call the authetification handler.
* `formspec`: formspec to display
* `minetest.close_formspec(playername, formname)`
* `playername`: name of player to close formspec
- * `formname`: has to exactly match the one given in `show_formspec`, or the formspec will
- not close.
- * calling `show_formspec(playername, formname, "")` is equal to this expression
+ * `formname`: has to exactly match the one given in `show_formspec`, or the
+ formspec will not close.
+ * calling `show_formspec(playername, formname, "")` is equal to this
+ expression.
* to close a formspec regardless of the formname, call
- `minetest.close_formspec(playername, "")`. **USE THIS ONLY WHEN ABSOLUTELY NECESSARY!**
+ `minetest.close_formspec(playername, "")`.
+ **USE THIS ONLY WHEN ABSOLUTELY NECESSARY!**
* `minetest.formspec_escape(string)`: returns a string
- * escapes the characters "[", "]", "\", "," and ";", which can not be used in formspecs
+ * escapes the characters "[", "]", "\", "," and ";", which can not be used
+ in formspecs.
* `minetest.explode_table_event(string)`: returns a table
* returns e.g. `{type="CHG", row=1, column=2}`
* `type` is one of:
@@ -2776,26 +3249,31 @@ and `minetest.auth_reload` call the authetification handler.
* `minetest.get_pointed_thing_position(pointed_thing, above)`
* Get position of a `pointed_thing` (that you can get from somewhere)
* `minetest.dir_to_facedir(dir, is6d)`
- * Convert a vector to a facedir value, used in `param2` for `paramtype2="facedir"`;
- * passing something non-`nil`/`false` for the optional second parameter causes it to
- take the y component into account
+ * Convert a vector to a facedir value, used in `param2` for
+ `paramtype2="facedir"`.
+ * passing something non-`nil`/`false` for the optional second parameter
+ causes it to take the y component into account.
* `minetest.facedir_to_dir(facedir)`
- * Convert a facedir back into a vector aimed directly out the "back" of a node
+ * Convert a facedir back into a vector aimed directly out the "back" of a
+ node.
* `minetest.dir_to_wallmounted(dir)`
- * Convert a vector to a wallmounted value, used for `paramtype2="wallmounted"`
+ * Convert a vector to a wallmounted value, used for
+ `paramtype2="wallmounted"`.
* `minetest.wallmounted_to_dir(wallmounted)`
- * Convert a wallmounted value back into a vector aimed directly out the "back" of a node
+ * Convert a wallmounted value back into a vector aimed directly out the
+ "back" of a node.
* `minetest.dir_to_yaw(dir)`
* Convert a vector into a yaw (angle)
* `minetest.yaw_to_dir(yaw)`
* Convert yaw (angle) to a vector
* `minetest.is_colored_paramtype(ptype)`
- * Returns a boolean. Returns `true` if the given `paramtype2` contains color
- information (`color`, `colorwallmounted` or `colorfacedir`).
+ * Returns a boolean. Returns `true` if the given `paramtype2` contains
+ color information (`color`, `colorwallmounted` or `colorfacedir`).
* `minetest.strip_param2_color(param2, paramtype2)`
* Removes everything but the color information from the
given `param2` value.
- * Returns `nil` if the given `paramtype2` does not contain color information
+ * Returns `nil` if the given `paramtype2` does not contain color
+ information.
* `minetest.get_node_drops(nodename, toolname)`
* Returns list of item names.
* **Note**: This will be removed or modified in a future version.
@@ -2803,7 +3281,7 @@ and `minetest.auth_reload` call the authetification handler.
* `input.method` = `"normal"` or `"cooking"` or `"fuel"`
* `input.width` = for example `3`
* `input.items` = for example
- `{ stack1, stack2, stack3, stack4, stack 5, stack 6, stack 7, stack 8, stack 9 }`
+ `{stack1, stack2, stack3, stack4, stack 5, stack 6, stack 7, stack 8, stack 9}`
* `output.item` = `ItemStack`, if unsuccessful: empty `ItemStack`
* `output.time` = a number, if unsuccessful: `0`
* `output.replacements` = list of `ItemStack`s that couldn't be placed in
@@ -2815,34 +3293,35 @@ and `minetest.auth_reload` call the authetification handler.
* `input.method` = `"normal"` or `"cooking"` or `"fuel"`
* `input.width` = for example `3`
* `input.items` = for example
- `{ stack1, stack2, stack3, stack4, stack 5, stack 6, stack 7, stack 8, stack 9 }`
- * `input.items` = `nil` if no recipe found
+ `{stack1, stack2, stack3, stack4, stack 5, stack 6, stack 7, stack 8, stack 9}`
+ * `input.items` = `nil` if no recipe found
* `minetest.get_all_craft_recipes(query item)`: returns a table or `nil`
* returns indexed table with all registered recipes for query item (node)
- or `nil` if no recipe was found
+ or `nil` if no recipe was found.
* recipe entry table:
- {
- method = 'normal' or 'cooking' or 'fuel'
- width = 0-3, 0 means shapeless recipe
- items = indexed [1-9] table with recipe items
- output = string with item name and quantity
- }
+ {
+ method = 'normal' or 'cooking' or 'fuel'
+ width = 0-3, 0 means shapeless recipe
+ items = indexed [1-9] table with recipe items
+ output = string with item name and quantity
+ }
* Example query for `"default:gold_ingot"` will return table:
- {
- [1]={method = "cooking", width = 3, output = "default:gold_ingot",
- items = {1 = "default:gold_lump"}},
- [2]={method = "normal", width = 1, output = "default:gold_ingot 9",
- items = {1 = "default:goldblock"}}
- }
+ {
+ [1]={method = "cooking", width = 3, output = "default:gold_ingot",
+ items = {1 = "default:gold_lump"}},
+ [2]={method = "normal", width = 1, output = "default:gold_ingot 9",
+ items = {1 = "default:goldblock"}}
+ }
* `minetest.handle_node_drops(pos, drops, digger)`
* `drops`: list of itemstrings
- * Handles drops from nodes after digging: Default action is to put them into
- digger's inventory
+ * Handles drops from nodes after digging: Default action is to put them
+ into digger's inventory.
* Can be overridden to get different functionality (e.g. dropping items on
ground)
-* `minetest.itemstring_with_palette(item, palette_index)`: returns an item string
+* `minetest.itemstring_with_palette(item, palette_index)`: returns an item
+ string.
* Creates an item string which contains palette index information
for hardware colorization. You can use the returned string
as an output in a craft recipe.
@@ -2863,7 +3342,8 @@ and `minetest.auth_reload` call the authetification handler.
returns `{{actor, pos, time, oldnode, newnode}, ...}`
* Find who has done something to a node, or near a node
* `actor`: `"player:"`, also `"liquid"`.
-* `minetest.rollback_revert_actions_by(actor, seconds)`: returns `boolean, log_messages`
+* `minetest.rollback_revert_actions_by(actor, seconds)`: returns
+ `boolean, log_messages`.
* Revert latest actions of someone
* `actor`: `"player:"`, also `"liquid"`.
@@ -2906,7 +3386,8 @@ These functions return the leftover itemstack.
* `minetest.sound_fade(handle, step, gain)`
* `handle` is a handle returned by `minetest.sound_play`
* `step` determines how fast a sound will fade.
- Negative step will lower the sound volume, positive step will increase the sound volume
+ Negative step will lower the sound volume, positive step will increase
+ the sound volume.
* `gain` the target gain for the fade.
### Timing
@@ -2915,32 +3396,41 @@ These functions return the leftover itemstack.
* Optional: Variable number of arguments that are passed to `func`
### Server
-* `minetest.request_shutdown([message],[reconnect],[delay])`: request for server shutdown. Will display `message` to clients,
- `reconnect` == true displays a reconnect button,
- `delay` adds an optional delay (in seconds) before shutdown
- negative delay cancels the current active shutdown
- zero delay triggers an immediate shutdown.
+* `minetest.request_shutdown([message],[reconnect],[delay])`: request for
+ server shutdown. Will display `message` to clients.
+ * `reconnect` == true displays a reconnect button
+ * `delay` adds an optional delay (in seconds) before shutdown.
+ Negative delay cancels the current active shutdown.
+ Zero delay triggers an immediate shutdown.
* `minetest.cancel_shutdown_requests()`: cancel current delayed shutdown
* `minetest.get_server_status()`: returns server status string
* `minetest.get_server_uptime()`: returns the server uptime in seconds
-* `minetest.remove_player(name)`: remove player from database (if he is not connected).
- * Does not remove player authentication data, minetest.player_exists will continue to return true.
+* `minetest.remove_player(name)`: remove player from database (if they are not
+ connected).
+ * As auth data is not removed, minetest.player_exists will continue to
+ return true. Call the below method as well if you want to remove auth
+ data too.
* Returns a code (0: successful, 1: no such player, 2: player is connected)
+* `minetest.remove_player_auth(name)`: remove player authentication data
+ * Returns boolean indicating success (false if player nonexistant)
### Bans
-* `minetest.get_ban_list()`: returns the ban list (same as `minetest.get_ban_description("")`)
+* `minetest.get_ban_list()`: returns the ban list
+ (same as `minetest.get_ban_description("")`).
* `minetest.get_ban_description(ip_or_name)`: returns ban description (string)
* `minetest.ban_player(name)`: ban a player
* `minetest.unban_player_or_ip(name)`: unban player or IP address
-* `minetest.kick_player(name, [reason])`: disconnect a player with a optional reason
+* `minetest.kick_player(name, [reason])`: disconnect a player with a optional
+ reason.
### Particles
* `minetest.add_particle(particle definition)`
- * Deprecated: `minetest.add_particle(pos, velocity, acceleration, expirationtime,
- size, collisiondetection, texture, playername)`
+ * Deprecated: `minetest.add_particle(pos, velocity, acceleration,
+ expirationtime, size, collisiondetection, texture, playername)`
* `minetest.add_particlespawner(particlespawner definition)`
- * Add a `ParticleSpawner`, an object that spawns an amount of particles over `time` seconds
+ * Add a `ParticleSpawner`, an object that spawns an amount of particles
+ over `time` seconds.
* Returns an `id`, and -1 if adding didn't succeed
* `Deprecated: minetest.add_particlespawner(amount, time,
minpos, maxpos,
@@ -2951,80 +3441,110 @@ These functions return the leftover itemstack.
collisiondetection, texture, playername)`
* `minetest.delete_particlespawner(id, player)`
- * Delete `ParticleSpawner` with `id` (return value from `minetest.add_particlespawner`)
+ * Delete `ParticleSpawner` with `id` (return value from
+ `minetest.add_particlespawner`).
* If playername is specified, only deletes on the player's client,
- * otherwise on all clients
+ otherwise on all clients.
### Schematics
* `minetest.create_schematic(p1, p2, probability_list, filename, slice_prob_list)`
- * Create a schematic from the volume of map specified by the box formed by p1 and p2.
- * Apply the specified probability and per-node force-place to the specified nodes
- according to the `probability_list`.
- * `probability_list` is an array of tables containing two fields, `pos` and `prob`.
+ * Create a schematic from the volume of map specified by the box formed by
+ p1 and p2.
+ * Apply the specified probability and per-node force-place to the specified
+ nodes according to the `probability_list`.
+ * `probability_list` is an array of tables containing two fields, `pos`
+ and `prob`.
* `pos` is the 3D vector specifying the absolute coordinates of the
node being modified,
- * `prob` is an integer value from `0` to `255` that encodes probability and
- per-node force-place. Probability has levels 0-127, then 128 is added to
- encode per-node force-place.
- For probability stated as 0-255, divide by 2 and round down to get values
- 0-127, then add 128 to apply per-node force-place.
+ * `prob` is an integer value from `0` to `255` that encodes
+ probability and per-node force-place. Probability has levels
+ 0-127, then 128 may be added to encode per-node force-place.
+ For probability stated as 0-255, divide by 2 and round down to
+ get values 0-127, then add 128 to apply per-node force-place.
* If there are two or more entries with the same pos value, the
last entry is used.
- * If `pos` is not inside the box formed by `p1` and `p2`, it is ignored.
+ * If `pos` is not inside the box formed by `p1` and `p2`, it is
+ ignored.
* If `probability_list` equals `nil`, no probabilities are applied.
- * Apply the specified probability to the specified horizontal slices according to the
- `slice_prob_list`.
- * `slice_prob_list` is an array of tables containing two fields, `ypos` and `prob`.
- * `ypos` indicates the y position of the slice with a probability applied,
- the lowest slice being `ypos = 0`.
- * If slice probability list equals `nil`, no slice probabilities are applied.
+ * Apply the specified probability to the specified horizontal slices
+ according to the `slice_prob_list`.
+ * `slice_prob_list` is an array of tables containing two fields, `ypos`
+ and `prob`.
+ * `ypos` indicates the y position of the slice with a probability
+ applied, the lowest slice being `ypos = 0`.
+ * If slice probability list equals `nil`, no slice probabilities
+ are applied.
* Saves schematic in the Minetest Schematic format to filename.
-* `minetest.place_schematic(pos, schematic, rotation, replacements, force_placement)`
- * Place the schematic specified by schematic (see: Schematic specifier) at `pos`.
+* `minetest.place_schematic(pos, schematic, rotation, replacements, force_placement, flags)`
+ * Place the schematic specified by schematic (see: Schematic specifier) at
+ `pos`.
* `rotation` can equal `"0"`, `"90"`, `"180"`, `"270"`, or `"random"`.
* If the `rotation` parameter is omitted, the schematic is not rotated.
* `replacements` = `{["old_name"] = "convert_to", ...}`
- * `force_placement` is a boolean indicating whether nodes other than `air` and
- `ignore` are replaced by the schematic
+ * `force_placement` is a boolean indicating whether nodes other than `air`
+ and `ignore` are replaced by the schematic.
* Returns nil if the schematic could not be loaded.
-
-* `minetest.place_schematic_on_vmanip(vmanip, pos, schematic, rotation, replacement, force_placement)`:
- * This function is analagous to minetest.place_schematic, but places a schematic onto the
- specified VoxelManip object `vmanip` instead of the whole map.
- * Returns false if any part of the schematic was cut-off due to the VoxelManip not
- containing the full area required, and true if the whole schematic was able to fit.
+ * **Warning**: Once you have loaded a schematic from a file, it will be
+ cached. Future calls will always use the cached version and the
+ replacement list defined for it, regardless of whether the file or the
+ replacement list parameter have changed. The only way to load the file
+ anew is to restart the server.
+ * `flags` is a flag field with the available flags:
+ * place_center_x
+ * place_center_y
+ * place_center_z
+
+* `minetest.place_schematic_on_vmanip(vmanip, pos, schematic, rotation, replacement, force_placement, flags)`:
+ * This function is analogous to minetest.place_schematic, but places a
+ schematic onto the specified VoxelManip object `vmanip` instead of the
+ map.
+ * Returns false if any part of the schematic was cut-off due to the
+ VoxelManip not containing the full area required, and true if the whole
+ schematic was able to fit.
* Returns nil if the schematic could not be loaded.
- * After execution, any external copies of the VoxelManip contents are invalidated.
+ * After execution, any external copies of the VoxelManip contents are
+ invalidated.
+ * `flags` is a flag field with the available flags:
+ * place_center_x
+ * place_center_y
+ * place_center_z
* `minetest.serialize_schematic(schematic, format, options)`
- * Return the serialized schematic specified by schematic (see: Schematic specifier)
+ * Return the serialized schematic specified by schematic
+ (see: Schematic specifier)
* in the `format` of either "mts" or "lua".
- * "mts" - a string containing the binary MTS data used in the MTS file format
- * "lua" - a string containing Lua code representing the schematic in table format
+ * "mts" - a string containing the binary MTS data used in the MTS file
+ format.
+ * "lua" - a string containing Lua code representing the schematic in table
+ format.
* `options` is a table containing the following optional parameters:
- * If `lua_use_comments` is true and `format` is "lua", the Lua code generated will have (X, Z)
- * position comments for every X row generated in the schematic data for easier reading.
- * If `lua_num_indent_spaces` is a nonzero number and `format` is "lua", the Lua code generated
- * will use that number of spaces as indentation instead of a tab character.
+ * If `lua_use_comments` is true and `format` is "lua", the Lua code
+ generated will have (X, Z) position comments for every X row
+ generated in the schematic data for easier reading.
+ * If `lua_num_indent_spaces` is a nonzero number and `format` is "lua",
+ the Lua code generated will use that number of spaces as indentation
+ instead of a tab character.
### HTTP Requests:
* `minetest.request_http_api()`:
- * returns `HTTPApiTable` containing http functions if the calling mod has been granted
- access by being listed in the `secure.http_mods` or `secure.trusted_mods` setting,
- otherwise returns `nil`.
- * The returned table contains the functions `fetch`, `fetch_async` and `fetch_async_get`
- described below.
- * Only works at init time and must be called from the mod's main scope (not from a function).
+ * returns `HTTPApiTable` containing http functions if the calling mod has
+ been granted access by being listed in the `secure.http_mods` or
+ `secure.trusted_mods` setting, otherwise returns `nil`.
+ * The returned table contains the functions `fetch`, `fetch_async` and
+ `fetch_async_get` described below.
+ * Only works at init time and must be called from the mod's main scope
+ (not from a function).
* Function only exists if minetest server was built with cURL support.
* **DO NOT ALLOW ANY OTHER MODS TO ACCESS THE RETURNED TABLE, STORE IT IN
A LOCAL VARIABLE!**
* `HTTPApiTable.fetch(HTTPRequest req, callback)`
* Performs given request asynchronously and calls callback upon completion
* callback: `function(HTTPRequestResult res)`
- * Use this HTTP function if you are unsure, the others are for advanced use.
+ * Use this HTTP function if you are unsure, the others are for advanced use
* `HTTPApiTable.fetch_async(HTTPRequest req)`: returns handle
- * Performs given request asynchronously and returns handle for `HTTPApiTable.fetch_async_get`
+ * Performs given request asynchronously and returns handle for
+ `HTTPApiTable.fetch_async_get`
* `HTTPApiTable.fetch_async_get(handle)`: returns HTTPRequestResult
* Return response data for given asynchronous HTTP request
@@ -3035,12 +3555,19 @@ These functions return the leftover itemstack.
### Misc.
* `minetest.get_connected_players()`: returns list of `ObjectRefs`
-* `minetest.player_exists(name)`: boolean, whether player exists (regardless of online status)
+* `minetest.is_player(o)`: boolean, whether `o` is a player
+* `minetest.player_exists(name)`: boolean, whether player exists
+ (regardless of online status)
* `minetest.hud_replace_builtin(name, hud_definition)`
* Replaces definition of a builtin hud element
* `name`: `"breath"` or `"health"`
* `hud_definition`: definition to replace builtin definition
-* `minetest.hash_node_position({x=,y=,z=})`: returns an 48-bit integer
+* `minetest.send_join_message(player_name)`
+ * This function can be overridden by mods to change the join message.
+* `minetest.send_leave_message(player_name, timed_out)`
+ * This function can be overridden by mods to change the leave message.
+* `minetest.hash_node_position(pos)`: returns an 48-bit integer
+ * `pos`: table {x=number, y=number, z=number},
* Gives a unique hash number for a node position (16+16+16=48bit)
* `minetest.get_position_from_hash(hash)`: returns a position
* Inverse transform of `minetest.hash_node_position`
@@ -3050,8 +3577,8 @@ These functions return the leftover itemstack.
* Deprecated: An alias for the former.
* `minetest.raillike_group(name)`: returns a rating
* Returns rating of the connect_to_raillike group corresponding to name
- * If name is not yet the name of a connect_to_raillike group, a new group id
- * is created, with that name
+ * If name is not yet the name of a connect_to_raillike group, a new group
+ id is created, with that name.
* `minetest.get_content_id(name)`: returns an integer
* Gets the internal content ID of `name`
* `minetest.get_name_from_content_id(content_id)`: returns a string
@@ -3062,15 +3589,20 @@ These functions return the leftover itemstack.
* On success returns a table, a string, a number, a boolean or `nullvalue`
* On failure outputs an error message and returns `nil`
* Example: `parse_json("[10, {\"a\":false}]")`, returns `{10, {a = false}}`
-* `minetest.write_json(data[, styled])`: returns a string or `nil` and an error message
+* `minetest.write_json(data[, styled])`: returns a string or `nil` and an error
+ message.
* Convert a Lua table into a JSON string
- * styled: Outputs in a human-readable format if this is set, defaults to false
+ * styled: Outputs in a human-readable format if this is set, defaults to
+ false.
* Unserializable things like functions and userdata will cause an error.
* **Warning**: JSON is more strict than the Lua table format.
- 1. You can only use strings and positive integers of at least one as keys.
+ 1. You can only use strings and positive integers of at least one as
+ keys.
2. You can not mix string and integer keys.
- This is due to the fact that JSON has two distinct array and object values.
- * Example: `write_json({10, {a = false}})`, returns `"[10, {\"a\": false}]"`
+ This is due to the fact that JSON has two distinct array and object
+ values.
+ * Example: `write_json({10, {a = false}})`,
+ returns `"[10, {\"a\": false}]"`
* `minetest.serialize(table)`: returns a string
* Convert a table containing tables, strings, numbers, booleans and `nil`s
into string form readable by `minetest.deserialize`
@@ -3079,21 +3611,24 @@ These functions return the leftover itemstack.
* Convert a string returned by `minetest.deserialize` into a table
* `string` is loaded in an empty sandbox environment.
* Will load functions, but they cannot access the global environment.
- * Example: `deserialize('return { ["foo"] = "bar" }')`, returns `{foo='bar'}`
- * Example: `deserialize('print("foo")')`, returns `nil` (function call fails)
- * `error:[string "print("foo")"]:1: attempt to call global 'print' (a nil value)`
+ * Example: `deserialize('return { ["foo"] = "bar" }')`,
+ returns `{foo='bar'}`
+ * Example: `deserialize('print("foo")')`, returns `nil`
+ (function call fails), returns
+ `error:[string "print("foo")"]:1: attempt to call global 'print' (a nil value)`
* `minetest.compress(data, method, ...)`: returns `compressed_data`
* Compress a string of data.
* `method` is a string identifying the compression method to be used.
* Supported compression methods:
- * Deflate (zlib): `"deflate"`
- * `...` indicates method-specific arguments. Currently defined arguments are:
- * Deflate: `level` - Compression level, `0`-`9` or `nil`.
+ * Deflate (zlib): `"deflate"`
+ * `...` indicates method-specific arguments. Currently defined arguments
+ are:
+ * Deflate: `level` - Compression level, `0`-`9` or `nil`.
* `minetest.decompress(compressed_data, method, ...)`: returns data
* Decompress a string of data (using ZLib).
- * See documentation on `minetest.compress()` for supported compression methods.
- * currently supported.
- * `...` indicates method-specific arguments. Currently, no methods use this.
+ * See documentation on `minetest.compress()` for supported compression
+ methods.
+ * `...` indicates method-specific arguments. Currently, no methods use this
* `minetest.rgba(red, green, blue[, alpha])`: returns a string
* Each argument is a 8 Bit unsigned integer
* Returns the ColorString from rgb or rgba values
@@ -3103,13 +3638,15 @@ These functions return the leftover itemstack.
* `minetest.decode_base64(string)`: returns string
* Decodes a string encoded in base64.
* `minetest.is_protected(pos, name)`: returns boolean
- * Returns true, if player `name` shouldn't be abled to dig at `pos` or do other
- actions, defineable by mods, due to some mod-defined ownership-like concept.
- Returns false or nil, if the player is allowed to do such actions.
- * This function should be overridden by protection mods and should be used to
- check if a player can interact at a position.
- * This function should call the old version of itself if the position is not
- protected by the mod.
+ * Returns true, if player `name` shouldn't be able to dig at `pos` or do
+ other actions, definable by mods, due to some mod-defined ownership-like
+ concept.
+ * Returns false or nil, if the player is allowed to do such actions.
+ * `name` will be "" for non-players or unknown players.
+ * This function should be overridden by protection mods and should be used
+ to check if a player can interact at a position.
+ * This function should call the old version of itself if the position is
+ not protected by the mod.
* Example:
local old_is_protected = minetest.is_protected
@@ -3120,27 +3657,42 @@ These functions return the leftover itemstack.
return old_is_protected(pos, name)
end
* `minetest.record_protection_violation(pos, name)`
- * This function calls functions registered with
- `minetest.register_on_protection_violation`.
+ * This function calls functions registered with
+ `minetest.register_on_protection_violation`.
+* `minetest.is_area_protected(pos1, pos2, player_name, interval)
+ * Returns the position of the first node that `player_name` may not modify
+ in the specified cuboid between `pos1` and `pos2`.
+ * Returns `false` if no protections were found.
+ * Applies `is_protected()` to a 3D lattice of points in the defined volume.
+ The points are spaced evenly throughout the volume and have a spacing
+ similar to, but no larger than, `interval`.
+ * All corners and edges of the defined volume are checked.
+ * `interval` defaults to 4.
+ * `interval` should be carefully chosen and maximised to avoid an excessive
+ number of points being checked.
+ * Like `minetest.is_protected`, this function may be extended or
+ overwritten by mods to provide a faster implementation to check the
+ cuboid for intersections.
* `minetest.rotate_and_place(itemstack, placer, pointed_thing, infinitestacks, orient_flags)`
* Attempt to predict the desired orientation of the facedir-capable node
- defined by `itemstack`, and place it accordingly (on-wall, on the floor, or
- hanging from the ceiling). Stacks are handled normally if the `infinitestacks`
- field is false or omitted (else, the itemstack is not changed). `orient_flags`
- is an optional table containing extra tweaks to the placement code:
- * `invert_wall`: if `true`, place wall-orientation on the ground and ground-
- orientation on the wall.
+ defined by `itemstack`, and place it accordingly (on-wall, on the floor,
+ or hanging from the ceiling). Stacks are handled normally if the
+ `infinitestacks` field is false or omitted (else, the itemstack is not
+ changed). `orient_flags` is an optional table containing extra tweaks to
+ the placement code:
+ * `invert_wall`: if `true`, place wall-orientation on the ground and
+ ground-orientation on the wall.
* `force_wall` : if `true`, always place the node in wall orientation.
* `force_ceiling`: if `true`, always place on the ceiling.
* `force_floor`: if `true`, always place the node on the floor.
- * `force_facedir`: if `true`, forcefully reset the facedir to north when placing on
- the floor or ceiling
- * The first four options are mutually-exclusive; the last in the list takes
- precedence over the first.
+ * `force_facedir`: if `true`, forcefully reset the facedir to north
+ when placing on the floor or ceiling.
+ * The first four options are mutually-exclusive; the last in the list
+ takes precedence over the first.
* `minetest.rotate_node(itemstack, placer, pointed_thing)`
- * calls `rotate_and_place()` with infinitestacks set according to the state of
- the creative mode setting, and checks for "sneak" to set the `invert_wall`
- parameter.
+ * calls `rotate_and_place()` with infinitestacks set according to the state
+ of the creative mode setting, and checks for "sneak" to set the
+ `invert_wall` parameter.
* `minetest.forceload_block(pos[, transient])`
* forceloads the position `pos`.
@@ -3156,10 +3708,12 @@ These functions return the leftover itemstack.
* `minetest.request_insecure_environment()`: returns an environment containing
insecure functions if the calling mod has been listed as trusted in the
- `secure.trusted_mods` setting or security is disabled, otherwise returns `nil`.
- * Only works at init time and must be called from the mod's main scope (not from a function).
- * **DO NOT ALLOW ANY OTHER MODS TO ACCESS THE RETURNED ENVIRONMENT, STORE IT IN
- A LOCAL VARIABLE!**
+ `secure.trusted_mods` setting or security is disabled, otherwise returns
+ `nil`.
+ * Only works at init time and must be called from the mod's main scope (not
+ from a function).
+ * **DO NOT ALLOW ANY OTHER MODS TO ACCESS THE RETURNED ENVIRONMENT, STORE
+ IT IN A LOCAL VARIABLE!**
* `minetest.global_exists(name)`
* Checks if a global variable has been set, without triggering a warning.
@@ -3167,8 +3721,8 @@ These functions return the leftover itemstack.
### Global objects
* `minetest.env`: `EnvRef` of the server environment and world.
* Any function in the minetest namespace can be called using the syntax
- `minetest.env:somefunction(somearguments)`
- instead of `minetest.somefunction(somearguments)`
+ `minetest.env:somefunction(somearguments)`
+ instead of `minetest.somefunction(somearguments)`
* Deprecated, but support is not to be dropped soon
### Global tables
@@ -3198,6 +3752,23 @@ These functions return the leftover itemstack.
Class reference
---------------
+### ModChannel
+
+An interface to use mod channels on client and server
+
+#### Methods
+* `leave()`: leave the mod channel.
+ * Server leaves channel `channel_name`.
+ * No more incoming or outgoing messages can be sent to this channel from
+ server mods.
+ * This invalidate all future object usage.
+ * Ensure your set mod_channel to nil after that to free Lua resources.
+* `is_writeable()`: returns true if channel is writeable and mod can send over
+ it.
+* `send_all(message)`: Send `message` though the mod channel.
+ * If mod channel is not writeable or invalid, message will be dropped.
+ * Message size is limited to 65535 characters by protocol.
+
### `MetaDataRef`
See `StorageRef`, `NodeMetaRef` and `ItemStackMetaRef`.
@@ -3227,8 +3798,9 @@ Can be obtained via `minetest.get_meta(pos)`.
* `get_inventory()`: returns `InvRef`
* `mark_as_private(name or {name1, name2, ...})`: Mark specific vars as private
This will prevent them from being sent to the client. Note that the "private"
- status will only be remembered if an associated key-value pair exists, meaning
- it's best to call this when initializing all other meta (e.g. `on_construct`).
+ status will only be remembered if an associated key-value pair exists,
+ meaning it's best to call this when initializing all other meta (e.g.
+ `on_construct`).
### `ItemStackMetaRef`
ItemStack metadata: reference extra data and functionality stored in a stack.
@@ -3236,6 +3808,10 @@ Can be obtained via `item:get_meta()`.
#### Methods
* All methods in MetaDataRef
+* `set_tool_capabilities([tool_capabilities])`
+ * Overrides the item's tool capabilities
+ * A nil value will clear the override data and restore the original
+ behavior.
### `StorageRef`
Mod metadata: per mod metadata, saved automatically.
@@ -3253,7 +3829,8 @@ Can be gotten via `minetest.get_node_timer(pos)`.
* set a timer's state
* `timeout` is in seconds, and supports fractional values (0.1 etc)
* `elapsed` is in seconds, and supports fractional values (0.1 etc)
- * will trigger the node's `on_timer` function after `(timeout - elapsed)` seconds
+ * will trigger the node's `on_timer` function after `(timeout - elapsed)`
+ seconds.
* `start(timeout)`
* start a timer
* equivalent to `set(timeout,0)`
@@ -3262,7 +3839,8 @@ Can be gotten via `minetest.get_node_timer(pos)`.
* `get_timeout()`: returns current timeout in seconds
* if `timeout` equals `0`, timer is inactive
* `get_elapsed()`: returns current elapsed time in seconds
- * the node's `on_timer` function will be called after `(timeout - elapsed)` seconds
+ * the node's `on_timer` function will be called after `(timeout - elapsed)`
+ seconds.
* `is_started()`: returns boolean state of timer
* returns `true` if timer is started, otherwise `false`
@@ -3285,19 +3863,29 @@ This is basically a reference to a C++ `ServerActiveObject`
* `get_hp()`: returns number of hitpoints (2 * number of hearts)
* `set_hp(hp)`: set number of hitpoints (2 * number of hearts)
* `get_inventory()`: returns an `InvRef`
-* `get_wield_list()`: returns the name of the inventory list the wielded item is in
+* `get_wield_list()`: returns the name of the inventory list the wielded item
+ is in.
* `get_wield_index()`: returns the index of the wielded item
* `get_wielded_item()`: returns an `ItemStack`
-* `set_wielded_item(item)`: replaces the wielded item, returns `true` if successful
+* `set_wielded_item(item)`: replaces the wielded item, returns `true` if
+ successful.
* `set_armor_groups({group1=rating, group2=rating, ...})`
* `get_armor_groups()`: returns a table with the armor group ratings
-* `set_animation({x=1,y=1}, frame_speed=15, frame_blend=0, frame_loop=true)`
-* `get_animation()`: returns `range`, `frame_speed`, `frame_blend` and `frame_loop`
+* `set_animation(frame_range, frame_speed, frame_blend, frame_loop)`
+ * `frame_range`: table {x=num, y=num}, default: `{x=1, y=1}`
+ * `frame_speed`: number, default: `15.0`
+ * `frame_blend`: number, default: `0.0`
+ * `frame_loop`: boolean, default: `true`
+* `get_animation()`: returns `range`, `frame_speed`, `frame_blend` and
+ `frame_loop`.
+* `set_animation_frame_speed(frame_speed)`
+ * `frame_speed`: number, default: `15.0`
* `set_attach(parent, bone, position, rotation)`
* `bone`: string
* `position`: `{x=num, y=num, z=num}` (relative)
- * `rotation`: `{x=num, y=num, z=num}`
-* `get_attach()`: returns parent, bone, position, rotation or nil if it isn't attached
+ * `rotation`: `{x=num, y=num, z=num}` = Rotation on each axis, in degrees
+* `get_attach()`: returns parent, bone, position, rotation or nil if it isn't
+ attached.
* `set_detach()`
* `set_bone_position(bone, position, rotation)`
* `bone`: string
@@ -3322,18 +3910,25 @@ This is basically a reference to a C++ `ServerActiveObject`
}
##### LuaEntitySAO-only (no-op for other objects)
-* `set_velocity({x=num, y=num, z=num})`
-* `get_velocity()`: returns `{x=num, y=num, z=num}`
-* `set_acceleration({x=num, y=num, z=num})`
-* `get_acceleration()`: returns `{x=num, y=num, z=num}`
+* `set_velocity(vel)`
+ * `vel` is a vector, e.g. `{x=0.0, y=2.3, z=1.0}`
+* `get_velocity()`: returns the velocity, a vector
+* `set_acceleration(acc)`
+ * `acc` is a vector
+* `get_acceleration()`: returns the acceleration, a vector
* `set_yaw(radians)`
* `get_yaw()`: returns number in radians
* `set_texture_mod(mod)`
* `get_texture_mod()` returns current texture modifier
-* `set_sprite(p={x=0,y=0}, num_frames=1, framelength=0.2,
- select_horiz_by_yawpitch=false)`
- * Select sprite from spritesheet with optional animation and DM-style
- texture selection based on yaw relative to camera
+* `set_sprite(p, num_frames, framelength, select_horiz_by_yawpitch)`
+ * Select sprite from spritesheet with optional animation and Dungeon Master
+ style texture selection based on yaw relative to camera
+ * `p`: {x=number, y=number}, the coordinate of the first frame
+ (x: column, y: row), default: `{x=0, y=0}`
+ * `num_frames`: number, default: `1`
+ * `framelength`: number, default: `0.2`
+ * `select_horiz_by_yawpitch`: boolean, this was once used for the Dungeon
+ Master mob, default: `false`
* `get_entity_name()` (**Deprecated**: Will be removed in a future version)
* `get_luaentity()`
@@ -3343,29 +3938,36 @@ This is basically a reference to a C++ `ServerActiveObject`
table {x, y, z} representing the player's instantaneous velocity in nodes/s
* `get_look_dir()`: get camera direction as a unit vector
* `get_look_vertical()`: pitch in radians
- * Angle ranges between -pi/2 and pi/2, which are straight up and down respectively.
+ * Angle ranges between -pi/2 and pi/2, which are straight up and down
+ respectively.
* `get_look_horizontal()`: yaw in radians
- * Angle is counter-clockwise from the +z direction.
+ * Angle is counter-clockwise from the +z direction.
* `set_look_vertical(radians)`: sets look pitch
- * radians - Angle from looking forward, where positive is downwards.
+ * radians - Angle from looking forward, where positive is downwards.
* `set_look_horizontal(radians)`: sets look yaw
- * radians - Angle from the +z direction, where positive is counter-clockwise.
-* `get_look_pitch()`: pitch in radians - Deprecated as broken. Use `get_look_vertical`.
- * Angle ranges between -pi/2 and pi/2, which are straight down and up respectively.
-* `get_look_yaw()`: yaw in radians - Deprecated as broken. Use `get_look_horizontal`.
- * Angle is counter-clockwise from the +x direction.
-* `set_look_pitch(radians)`: sets look pitch - Deprecated. Use `set_look_vertical`.
-* `set_look_yaw(radians)`: sets look yaw - Deprecated. Use `set_look_horizontal`.
+ * radians - Angle from the +z direction, where positive is
+ counter-clockwise.
+* `get_look_pitch()`: pitch in radians - Deprecated as broken. Use
+ `get_look_vertical`.
+ * Angle ranges between -pi/2 and pi/2, which are straight down and up
+ respectively.
+* `get_look_yaw()`: yaw in radians - Deprecated as broken. Use
+ `get_look_horizontal`.
+ * Angle is counter-clockwise from the +x direction.
+* `set_look_pitch(radians)`: sets look pitch - Deprecated. Use
+ `set_look_vertical`.
+* `set_look_yaw(radians)`: sets look yaw - Deprecated. Use
+ `set_look_horizontal`.
* `get_breath()`: returns players breath
* `set_breath(value)`: sets players breath
- * values:
- * `0`: player is drowning,
- * `1`-`10`: remaining number of bubbles
- * `11`: bubbles bar is not shown
- * See constant: `minetest.PLAYER_MAX_BREATH`
+ * values:
+ * `0`: player is drowning
+ * max: bubbles bar is not shown
+ * See Object Properties for more information
* `set_attribute(attribute, value)`:
* Sets an extra attribute with value on player.
- * `value` must be a string.
+ * `value` must be a string, or a number which will be converted to a
+ string.
* If `value` is `nil`, remove attribute from player.
* `get_attribute(attribute)`:
* Returns value (a string) for extra attribute.
@@ -3375,9 +3977,14 @@ This is basically a reference to a C++ `ServerActiveObject`
* Should usually be called in `on_joinplayer`
* `get_inventory_formspec()`: returns a formspec string
* `get_player_control()`: returns table with player pressed keys
- * `{jump=bool,right=bool,left=bool,LMB=bool,RMB=bool,sneak=bool,aux1=bool,down=bool,up=bool}`
-* `get_player_control_bits()`: returns integer with bit packed player pressed keys
- * bit nr/meaning: 0/up ,1/down ,2/left ,3/right ,4/jump ,5/aux1 ,6/sneak ,7/LMB ,8/RMB
+ * The table consists of fields with boolean value representing the pressed
+ keys, the fields are jump, right, left, LMB, RMB, sneak, aux1, down, up.
+ * example: `{jump=false, right=true, left=false, LMB=false, RMB=false,
+ sneak=true, aux1=false, down=false, up=false}`
+* `get_player_control_bits()`: returns integer with bit packed player pressed
+ keys.
+ * bit nr/meaning: 0/up, 1/down, 2/left, 3/right, 4/jump, 5/aux1, 6/sneak,
+ 7/LMB, 8/RMB
* `set_physics_override(override_table)`
* `override_table` is a table with the following fields:
* `speed`: multiplier to default walking speed value (default: `1`)
@@ -3393,16 +4000,19 @@ This is basically a reference to a C++ `ServerActiveObject`
* `hud_add(hud definition)`: add a HUD element described by HUD def, returns ID
number on success
* `hud_remove(id)`: remove the HUD element of the specified id
-* `hud_change(id, stat, value)`: change a value of a previously added HUD element
- * element `stat` values: `position`, `name`, `scale`, `text`, `number`, `item`, `dir`
+* `hud_change(id, stat, value)`: change a value of a previously added HUD
+ element.
+ * element `stat` values:
+ `position`, `name`, `scale`, `text`, `number`, `item`, `dir`
* `hud_get(id)`: gets the HUD element definition structure of the specified ID
* `hud_set_flags(flags)`: sets specified HUD flags to `true`/`false`
- * `flags`: (is visible) `hotbar`, `healthbar`, `crosshair`, `wielditem`, `breathbar`,
- `minimap`, `minimap_radar`
- * pass a table containing a `true`/`false` value of each flag to be set or unset
+ * `flags`: (is visible) `hotbar`, `healthbar`, `crosshair`, `wielditem`,
+ `breathbar`, `minimap`, `minimap_radar`
+ * pass a table containing a `true`/`false` value of each flag to be set or
+ unset.
* if a flag equals `nil`, the flag is not modified
- * note that setting `minimap` modifies the client's permission to view the minimap -
- * the client may locally elect to not view the minimap
+ * note that setting `minimap` modifies the client's permission to view the
+ minimap - the client may locally elect to not view the minimap.
* minimap `radar` is only usable when `minimap` is true
* `hud_get_flags()`: returns a table containing status of hud flags
* returns `{hotbar=true, healthbar=true, crosshair=true, wielditem=true,
@@ -3426,30 +4036,36 @@ This is basically a reference to a C++ `ServerActiveObject`
`"plain"` custom skyboxes (default: `true`)
* `get_sky()`: returns bgcolor, type, table of textures, clouds
* `set_clouds(parameters)`: set cloud parameters
- * `parameters` is a table with the following optional fields:
- * `density`: from `0` (no clouds) to `1` (full clouds) (default `0.4`)
- * `color`: basic cloud color with alpha channel, ColorSpec (default `#fff0f0e5`)
- * `ambient`: cloud color lower bound, use for a "glow at night" effect.
- ColorSpec (alpha ignored, default `#000000`)
- * `height`: cloud height, i.e. y of cloud base (default per conf, usually `120`)
- * `thickness`: cloud thickness in nodes (default `16`)
- * `speed`: 2D cloud speed + direction in nodes per second (default `{x=0, z=-2}`)
-* `get_clouds()`: returns a table with the current cloud parameters as in `set_clouds`
+ * `parameters` is a table with the following optional fields:
+ * `density`: from `0` (no clouds) to `1` (full clouds) (default `0.4`)
+ * `color`: basic cloud color with alpha channel, ColorSpec
+ (default `#fff0f0e5`).
+ * `ambient`: cloud color lower bound, use for a "glow at night" effect.
+ ColorSpec (alpha ignored, default `#000000`)
+ * `height`: cloud height, i.e. y of cloud base (default per conf,
+ usually `120`)
+ * `thickness`: cloud thickness in nodes (default `16`)
+ * `speed`: 2D cloud speed + direction in nodes per second
+ (default `{x=0, z=-2}`).
+* `get_clouds()`: returns a table with the current cloud parameters as in
+ `set_clouds`.
* `override_day_night_ratio(ratio or nil)`
- * `0`...`1`: Overrides day-night ratio, controlling sunlight to a specific amount
+ * `0`...`1`: Overrides day-night ratio, controlling sunlight to a specific
+ amount.
* `nil`: Disables override, defaulting to sunlight based on day-night cycle
* `get_day_night_ratio()`: returns the ratio or nil if it isn't overridden
-* `set_local_animation(stand/idle, walk, dig, walk+dig, frame_speed=frame_speed)`
-
- set animation for player model in third person view
+* `set_local_animation(stand/idle, walk, dig, walk+dig, frame_speed=frame_speed)`:
+ set animation for player model in third person view
set_local_animation({x=0, y=79}, -- < stand/idle animation key frames
{x=168, y=187}, -- < walk animation key frames
{x=189, y=198}, -- < dig animation key frames
{x=200, y=219}, -- < walk+dig animation key frames
frame_speed=30): -- < animation frame speed
-* `get_local_animation()`: returns stand, walk, dig, dig+walk tables and `frame_speed`
-* `set_eye_offset({x=0,y=0,z=0},{x=0,y=0,z=0})`: defines offset value for camera per player
+* `get_local_animation()`: returns stand, walk, dig, dig+walk tables and
+ `frame_speed`.
+* `set_eye_offset({x=0,y=0,z=0},{x=0,y=0,z=0})`: defines offset value for
+ camera per player.
* in first person view
* in third person view (max. values `{x=-10/10,y=-10,15,z=-5/5}`)
* `get_eye_offset()`: returns `offset_first` and `offset_third`
@@ -3470,60 +4086,81 @@ An `InvRef` is a reference to an inventory.
* `set_list(listname, list)`: set full list (size will not change)
* `get_lists()`: returns list of inventory lists
* `set_lists(lists)`: sets inventory lists (size will not change)
-* `add_item(listname, stack)`: add item somewhere in list, returns leftover `ItemStack`
+* `add_item(listname, stack)`: add item somewhere in list, returns leftover
+ `ItemStack`.
* `room_for_item(listname, stack):` returns `true` if the stack of items
can be fully added to the list
* `contains_item(listname, stack, [match_meta])`: returns `true` if
the stack of items can be fully taken from the list.
- If `match_meta` is false, only the items' names are compared (default: `false`).
-* `remove_item(listname, stack)`: take as many items as specified from the list,
- returns the items that were actually removed (as an `ItemStack`) -- note that
- any item metadata is ignored, so attempting to remove a specific unique
- item this way will likely remove the wrong one -- to do that use `set_stack`
- with an empty `ItemStack`
-* `get_location()`: returns a location compatible to `minetest.get_inventory(location)`
+ If `match_meta` is false, only the items' names are compared
+ (default: `false`).
+* `remove_item(listname, stack)`: take as many items as specified from the
+ list, returns the items that were actually removed (as an `ItemStack`)
+ -- note that any item metadata is ignored, so attempting to remove a specific
+ unique item this way will likely remove the wrong one -- to do that use
+ `set_stack` with an empty `ItemStack`.
+* `get_location()`: returns a location compatible to
+ `minetest.get_inventory(location)`.
* returns `{type="undefined"}` in case location is not known
### `AreaStore`
-A fast access data structure to store areas, and find areas near a given position or area.
+A fast access data structure to store areas, and find areas near a given
+position or area.
Every area has a `data` string attribute to store additional information.
-You can create an empty `AreaStore` by calling `AreaStore()`, or `AreaStore(type_name)`.
-If you chose the parameter-less constructor, a fast implementation will be automatically
-chosen for you.
+You can create an empty `AreaStore` by calling `AreaStore()`, or
+`AreaStore(type_name)`.
+If you chose the parameter-less constructor, a fast implementation will be
+automatically chosen for you.
#### Methods
-* `get_area(id, include_borders, include_data)`: returns the area with the id `id`.
- (optional) Boolean values `include_borders` and `include_data` control what's copied.
+* `get_area(id, include_borders, include_data)`: returns the area with the id
+ `id`.
+ (optional) Boolean values `include_borders` and `include_data` control what's
+ copied.
Returns nil if specified area id does not exist.
-* `get_areas_for_pos(pos, include_borders, include_data)`: returns all areas that contain
- the position `pos`. (optional) Boolean values `include_borders` and `include_data` control
- what's copied.
+* `get_areas_for_pos(pos, include_borders, include_data)`: returns all areas
+ that contain the position `pos`.
+ (optional) Boolean values `include_borders` and `include_data` control what's
+ copied.
* `get_areas_in_area(edge1, edge2, accept_overlap, include_borders, include_data)`:
- returns all areas that contain all nodes inside the area specified by `edge1` and `edge2` (inclusive).
- If `accept_overlap` is true, also areas are returned that have nodes in common with the specified area.
- (optional) Boolean values `include_borders` and `include_data` control what's copied.
-* `insert_area(edge1, edge2, data, [id])`: inserts an area into the store. Returns the new area's ID,
- or nil if the insertion failed. The (inclusive) positions `edge1` and `edge2` describe the area.
- `data` is a string stored with the area. If passed, `id` will be used as the internal area ID,
- it must be a unique number between 0 and 2^32-2. If you use the `id` parameter you must always use it,
- or insertions are likely to fail due to conflicts.
-* `reserve(count)`: reserves resources for at most `count` many contained areas.
+ returns all areas that contain all nodes inside the area specified by `edge1`
+ and `edge2` (inclusive).
+ If `accept_overlap` is true, also areas are returned that have nodes in
+ common with the specified area.
+ (optional) Boolean values `include_borders` and `include_data` control what's
+ copied.
+* `insert_area(edge1, edge2, data, [id])`: inserts an area into the store.
+ Returns the new area's ID, or nil if the insertion failed.
+ The (inclusive) positions `edge1` and `edge2` describe the area.
+ `data` is a string stored with the area. If passed, `id` will be used as the
+ internal area ID, it must be a unique number between 0 and 2^32-2. If you use
+ the `id` parameter you must always use it, or insertions are likely to fail
+ due to conflicts.
+* `reserve(count)`: reserves resources for at most `count` many contained
+ areas.
Only needed for efficiency, and only some implementations profit.
-* `remove_area(id)`: removes the area with the given id from the store, returns success.
+* `remove_area(id)`: removes the area with the given id from the store, returns
+ success.
* `set_cache_params(params)`: sets params for the included prefiltering cache.
- Calling invalidates the cache, so that its elements have to be newly generated.
+ Calling invalidates the cache, so that its elements have to be newly
+ generated.
* `params`:
{
- enabled = boolean, -- whether to enable, default true
- block_radius = number, -- the radius (in nodes) of the areas the cache generates
- prefiltered lists for, minimum 16, default 64
- limit = number, -- the cache's size, minimum 20, default 1000
+ enabled = boolean, -- whether to enable, default true
+ block_radius = number, -- the radius (in nodes) of the areas the cache
+ generates prefiltered lists for, minimum 16,
+ default 64.
+ limit = number, -- the cache's 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 a file.
-* `from_string(str)`: Experimental. Deserializes string and loads it into the AreaStore.
+* `to_string()`: Experimental. Returns area store serialized as a (binary)
+ string.
+* `to_file(filename)`: Experimental. Like `to_string()`, but writes the data to
+ a file.
+* `from_string(str)`: Experimental. Deserializes string and loads it into the
+ AreaStore.
Returns success and, optionally, an error message.
-* `from_file(filename)`: Experimental. Like `from_string()`, but reads the data from a file.
+* `from_file(filename)`: Experimental. Like `from_string()`, but reads the data
+ from a file.
### `ItemStack`
An `ItemStack` is a stack of items.
@@ -3532,36 +4169,45 @@ It can be created via `ItemStack(x)`, where x is an `ItemStack`,
an itemstring, a table or `nil`.
#### Methods
-* `is_empty()`: Returns `true` if stack is empty.
-* `get_name()`: Returns item name (e.g. `"default:stone"`).
-* `set_name(item_name)`: Returns boolean whether item was cleared
+* `is_empty()`: returns `true` if stack is empty.
+* `get_name()`: returns item name (e.g. `"default:stone"`).
+* `set_name(item_name)`: returns a boolean indicating whether the item was
+ cleared.
* `get_count()`: Returns number of items on the stack.
-* `set_count(count)`: Returns boolean whether item was cleared
-* `get_wear()`: Returns tool wear (`0`-`65535`), `0` for non-tools.
-* `set_wear(wear)`: Returns boolean whether item was cleared
-* `get_meta()`: Returns ItemStackMetaRef. See section for more details
-* `get_metadata()`: (DEPRECATED) Returns metadata (a string attached to an item stack).
+* `set_count(count)`: returns a boolean indicating whether the item was cleared
+ * `count`: number, unsigned 16 bit integer
+* `get_wear()`: returns tool wear (`0`-`65535`), `0` for non-tools.
+* `set_wear(wear)`: returns boolean indicating whether item was cleared
+ * `wear`: number, unsigned 16 bit integer
+* `get_meta()`: returns ItemStackMetaRef. See section for more details
+* `get_metadata()`: (DEPRECATED) Returns metadata (a string attached to an item
+ stack).
* `set_metadata(metadata)`: (DEPRECATED) Returns true.
* `clear()`: removes all items from the stack, making it empty.
* `replace(item)`: replace the contents of this stack.
* `item` can also be an itemstring or table.
-* `to_string()`: Returns the stack in itemstring form.
-* `to_table()`: Returns the stack in Lua table form.
-* `get_stack_max()`: Returns the maximum size of the stack (depends on the item).
-* `get_free_space()`: Returns `get_stack_max() - get_count()`.
-* `is_known()`: Returns `true` if the item name refers to a defined item type.
-* `get_definition()`: Returns the item definition table.
-* `get_tool_capabilities()`: Returns the digging properties of the item,
+* `to_string()`: returns the stack in itemstring form.
+* `to_table()`: returns the stack in Lua table form.
+* `get_stack_max()`: returns the maximum size of the stack (depends on the
+ item).
+* `get_free_space()`: returns `get_stack_max() - get_count()`.
+* `is_known()`: returns `true` if the item name refers to a defined item type.
+* `get_definition()`: returns the item definition table.
+* `get_tool_capabilities()`: returns the digging properties of the item,
or those of the hand if none are defined for this item type
-* `add_wear(amount)`: Increases wear by `amount` if the item is a tool.
-* `add_item(item)`: Put some item or stack onto this stack.
- Returns leftover `ItemStack`.
-* `item_fits(item)`: Returns `true` if item or stack can be fully added to
+* `add_wear(amount)`
+ * Increases wear by `amount` if the item is a tool
+ * `amount`: number, integer
+* `add_item(item)`: returns leftover `ItemStack`
+ * Put some item or stack onto this stack
+* `item_fits(item)`: returns `true` if item or stack can be fully added to
this one.
-* `take_item(n=1)`: Take (and remove) up to `n` items from this stack.
- Returns taken `ItemStack`.
-* `peek_item(n=1)`: copy (don't remove) up to `n` items from this stack.
- Returns taken `ItemStack`.
+* `take_item(n)`: returns taken `ItemStack`
+ * Take (and remove) up to `n` items from this stack
+ * `n`: number, default: `1`
+* `peek_item(n)`: returns taken `ItemStack`
+ * Copy (don't remove) up to `n` items from this stack
+ * `n`: number, default: `1`
### `PseudoRandom`
A 16-bit pseudorandom number generator.
@@ -3577,27 +4223,30 @@ It can be created via `PseudoRandom(seed)`.
### `PcgRandom`
A 32-bit pseudorandom number generator.
-Uses PCG32, an algorithm of the permuted congruential generator family, offering very strong randomness.
+Uses PCG32, an algorithm of the permuted congruential generator family,
+offering very strong randomness.
It can be created via `PcgRandom(seed)` or `PcgRandom(seed, sequence)`.
#### Methods
* `next()`: return next integer random number [`-2147483648`...`2147483647`]
* `next(min, max)`: return next integer random number [`min`...`max`]
-* `rand_normal_dist(min, max, num_trials=6)`: return normally distributed random number [`min`...`max`]
+* `rand_normal_dist(min, max, num_trials=6)`: return normally distributed
+ random number [`min`...`max`].
* This is only a rough approximation of a normal distribution with:
- * `mean = (max - min) / 2`, and
- * `variance = (((max - min + 1) ^ 2) - 1) / (12 * num_trials)`
+ * `mean = (max - min) / 2`, and
+ * `variance = (((max - min + 1) ^ 2) - 1) / (12 * num_trials)`
* Increasing `num_trials` improves accuracy of the approximation
### `SecureRandom`
Interface for the operating system's crypto-secure PRNG.
-It can be created via `SecureRandom()`. The constructor returns nil if a secure random device cannot be
-be found on the system.
+It can be created via `SecureRandom()`. The constructor returns nil if a
+secure random device cannot be found on the system.
#### Methods
-* `next_bytes([count])`: return next `count` (default 1, capped at 2048) many random bytes, as a string.
+* `next_bytes([count])`: return next `count` (default 1, capped at 2048) many
+ random bytes, as a string.
### `PerlinNoise`
A perlin noise generator.
@@ -3607,8 +4256,8 @@ Alternatively with `minetest.get_perlin(seeddiff, octaves, persistence, scale)`
or `minetest.get_perlin(noiseparams)`.
#### Methods
-* `get2d(pos)`: returns 2D noise value at `pos={x=,y=}`
-* `get3d(pos)`: returns 3D noise value at `pos={x=,y=,z=}`
+* `get_2d(pos)`: returns 2D noise value at `pos={x=,y=}`
+* `get_3d(pos)`: returns 3D noise value at `pos={x=,y=,z=}`
### `PerlinNoiseMap`
A fast, bulk perlin noise generator.
@@ -3616,93 +4265,117 @@ A fast, bulk perlin noise generator.
It can be created via `PerlinNoiseMap(noiseparams, size)` or
`minetest.get_perlin_map(noiseparams, size)`.
-Format of `size` is `{x=dimx, y=dimy, z=dimz}`. The `z` conponent is ommitted
+Format of `size` is `{x=dimx, y=dimy, z=dimz}`. The `z` component is omitted
for 2D noise, and it must be must be larger than 1 for 3D noise (otherwise
`nil` is returned).
-For each of the functions with an optional `buffer` parameter: If `buffer` is not
-nil, this table will be used to store the result instead of creating a new table.
-
+For each of the functions with an optional `buffer` parameter: If `buffer` is
+not nil, this table will be used to store the result instead of creating a new
+table.
#### Methods
-* `get2dMap(pos)`: returns a `` times `` 2D array of 2D noise
- with values starting at `pos={x=,y=}`
-* `get3dMap(pos)`: returns a `` times `` times `` 3D array
- of 3D noise with values starting at `pos={x=,y=,z=}`
-* `get2dMap_flat(pos, buffer)`: returns a flat `` element array of 2D noise
+* `get_2d_map(pos)`: returns a `` times `` 2D array of 2D noise
with values starting at `pos={x=,y=}`
-* `get3dMap_flat(pos, buffer)`: Same as `get2dMap_flat`, but 3D noise
-* `calc2dMap(pos)`: Calculates the 2d noise map starting at `pos`. The result is stored internally.
-* `calc3dMap(pos)`: Calculates the 3d noise map starting at `pos`. The result is stored internally.
-* `getMapSlice(slice_offset, slice_size, buffer)`: In the form of an array, returns a slice of the
- most recently computed noise results. The result slice begins at coordinates `slice_offset` and
- takes a chunk of `slice_size`.
- E.g. to grab a 2-slice high horizontal 2d plane of noise starting at buffer offset y = 20:
- `noisevals = noise:getMapSlice({y=20}, {y=2})`
- It is important to note that `slice_offset` offset coordinates begin at 1, and are relative to
- the starting position of the most recently calculated noise.
- To grab a single vertical column of noise starting at map coordinates x = 1023, y=1000, z = 1000:
- `noise:calc3dMap({x=1000, y=1000, z=1000})`
- `noisevals = noise:getMapSlice({x=24, z=1}, {x=1, z=1})`
+* `get_3d_map(pos)`: returns a `` times `` times ``
+ 3D array of 3D noise with values starting at `pos={x=,y=,z=}`.
+* `get_2d_map_flat(pos, buffer)`: returns a flat `` element
+ array of 2D noise with values starting at `pos={x=,y=}`
+* `get_3d_map_flat(pos, buffer)`: Same as `get2dMap_flat`, but 3D noise
+* `calc_2d_map(pos)`: Calculates the 2d noise map starting at `pos`. The result
+ is stored internally.
+* `calc_3d_map(pos)`: Calculates the 3d noise map starting at `pos`. The result
+ is stored internally.
+* `get_map_slice(slice_offset, slice_size, buffer)`: In the form of an array,
+ returns a slice of the most recently computed noise results. The result slice
+ begins at coordinates `slice_offset` and takes a chunk of `slice_size`.
+ E.g. to grab a 2-slice high horizontal 2d plane of noise starting at buffer
+ offset y = 20:
+ `noisevals = noise:get_map_slice({y=20}, {y=2})`
+ It is important to note that `slice_offset` offset coordinates begin at 1,
+ and are relative to the starting position of the most recently calculated
+ noise.
+ To grab a single vertical column of noise starting at map coordinates
+ x = 1023, y=1000, z = 1000:
+ `noise:calc_3d_map({x=1000, y=1000, z=1000})`
+ `noisevals = noise:get_map_slice({x=24, z=1}, {x=1, z=1})`
### `VoxelManip`
#### About VoxelManip
-VoxelManip is a scripting interface to the internal 'Map Voxel Manipulator' facility. The purpose of
-this object is for fast, low-level, bulk access to reading and writing Map content. As such, setting
-map nodes through VoxelManip will lack many of the higher level features and concepts you may be used
-to with other methods of setting nodes. For example, nodes will not have their construction and
-destruction callbacks run, and no rollback information is logged.
-
-It is important to note that VoxelManip is designed for speed, and *not* ease of use or flexibility.
-If your mod requires a map manipulation facility that will handle 100% of all edge cases, or the use
-of high level node placement features, perhaps `minetest.set_node()` is better suited for the job.
-
-In addition, VoxelManip might not be faster, or could even be slower, for your specific use case.
-VoxelManip is most effective when setting very large areas of map at once - for example, if only
-setting a 5x5x5 node area, a `minetest.set_node()` loop may be more optimal. Always profile code
-using both methods of map manipulation to determine which is most appropriate for your usage.
+VoxelManip is a scripting interface to the internal 'Map Voxel Manipulator'
+facility. The purpose of this object is for fast, low-level, bulk access to
+reading and writing Map content. As such, setting map nodes through VoxelManip
+will lack many of the higher level features and concepts you may be used to
+with other methods of setting nodes. For example, nodes will not have their
+construction and destruction callbacks run, and no rollback information is
+logged.
+
+It is important to note that VoxelManip is designed for speed, and *not* ease
+of use or flexibility. If your mod requires a map manipulation facility that
+will handle 100% of all edge cases, or the use of high level node placement
+features, perhaps `minetest.set_node()` is better suited for the job.
+
+In addition, VoxelManip might not be faster, or could even be slower, for your
+specific use case. VoxelManip is most effective when setting large areas of map
+at once - for example, if only setting a 3x3x3 node area, a
+`minetest.set_node()` loop may be more optimal. Always profile code using both
+methods of map manipulation to determine which is most appropriate for your
+usage.
+
+A recent simple test of setting cubic areas showed that `minetest.set_node()`
+is faster than a VoxelManip for a 3x3x3 node cube or smaller.
#### Using VoxelManip
A VoxelManip object can be created any time using either:
`VoxelManip([p1, p2])`, or `minetest.get_voxel_manip([p1, p2])`.
-If the optional position parameters are present for either of these routines, the specified region
-will be pre-loaded into the VoxelManip object on creation. Otherwise, the area of map you wish to
-manipulate must first be loaded into the VoxelManip object using `VoxelManip:read_from_map()`.
+If the optional position parameters are present for either of these routines,
+the specified region will be pre-loaded into the VoxelManip object on creation.
+Otherwise, the area of map you wish to manipulate must first be loaded into the
+VoxelManip object using `VoxelManip:read_from_map()`.
+
+Note that `VoxelManip:read_from_map()` returns two position vectors. The region
+formed by these positions indicate the minimum and maximum (respectively)
+positions of the area actually loaded in the VoxelManip, which may be larger
+than the area requested. For convenience, the loaded area coordinates can also
+be queried any time after loading map data with `VoxelManip:get_emerged_area()`.
-Note that `VoxelManip:read_from_map()` returns two position vectors. The region formed by these
-positions indicate the minimum and maximum (respectively) positions of the area actually loaded in
-the VoxelManip, which may be larger than the area requested. For convenience, the loaded area
-coordinates can also be queried any time after loading map data with `VoxelManip:get_emerged_area()`.
+Now that the VoxelManip object is populated with map data, your mod can fetch a
+copy of this data using either of two methods. `VoxelManip:get_node_at()`,
+which retrieves an individual node in a MapNode formatted table at the position
+requested is the simplest method to use, but also the slowest.
-Now that the VoxelManip object is populated with map data, your mod can fetch a copy of this data
-using either of two methods. `VoxelManip:get_node_at()`, which retrieves an individual node in a
-MapNode formatted table at the position requested is the simplest method to use, but also the slowest.
+Nodes in a VoxelManip object may also be read in bulk to a flat array table
+using:
-Nodes in a VoxelManip object may also be read in bulk to a flat array table using:
-`VoxelManip:get_data()` for node content (in Content ID form, see section 'Content IDs'),
-`VoxelManip:get_light_data()` for node light levels, and
-`VoxelManip:get_param2_data()` for the node type-dependent "param2" values.
+* `VoxelManip:get_data()` for node content (in Content ID form, see section
+ 'Content IDs'),
+* `VoxelManip:get_light_data()` for node light levels, and
+* `VoxelManip:get_param2_data()` for the node type-dependent "param2" values.
See section 'Flat array format' for more details.
-It is very important to understand that the tables returned by any of the above three functions
-represent a snapshot of the VoxelManip's internal state at the time of the call. This copy of the
-data will *not* magically update itself if another function modifies the internal VoxelManip state.
-Any functions that modify a VoxelManip's contents work on the VoxelManip's internal state unless
-otherwise explicitly stated.
+It is very important to understand that the tables returned by any of the above
+three functions represent a snapshot of the VoxelManip's internal state at the
+time of the call. This copy of the data will not magically update itself if
+another function modifies the internal VoxelManip state.
+Any functions that modify a VoxelManip's contents work on the VoxelManip's
+internal state unless otherwise explicitly stated.
-Once the bulk data has been edited to your liking, the internal VoxelManip state can be set using:
-`VoxelManip:set_data()` for node content (in Content ID form, see section 'Content IDs'),
-`VoxelManip:set_light_data()` for node light levels, and
-`VoxelManip:set_param2_data()` for the node type-dependent `param2` values.
+Once the bulk data has been edited to your liking, the internal VoxelManip
+state can be set using:
-The parameter to each of the above three functions can use any table at all in the same flat array
-format as produced by `get_data()` et al. and is *not required* to be a table retrieved from `get_data()`.
+* `VoxelManip:set_data()` for node content (in Content ID form, see section
+ 'Content IDs'),
+* `VoxelManip:set_light_data()` for node light levels, and
+* `VoxelManip:set_param2_data()` for the node type-dependent `param2` values.
-Once the internal VoxelManip state has been modified to your liking, the changes can be committed back
-to the map by calling `VoxelManip:write_to_map()`.
+The parameter to each of the above three functions can use any table at all in
+the same flat array format as produced by `get_data()` etc. and is not required
+to be a table retrieved from `get_data()`.
+
+Once the internal VoxelManip state has been modified to your liking, the
+changes can be committed back to the map by calling `VoxelManip:write_to_map()`
##### Flat array format
@@ -3711,8 +4384,8 @@ Let
`Ny = p2.Y - p1.Y + 1`, and
`Nz = p2.Z - p1.Z + 1`.
-Then, for a loaded region of p1..p2, this array ranges from `1` up to and including the value of
-the expression `Nx * Ny * Nz`.
+Then, for a loaded region of p1..p2, this array ranges from `1` up to and
+including the value of the expression `Nx * Ny * Nz`.
Positions offset from p1 are present in the array with the format of:
@@ -3734,75 +4407,93 @@ and the array index for a position p contained completely in p1..p2 is:
`(p.Z - p1.Z) * Ny * Nx + (p.Y - p1.Y) * Nx + (p.X - p1.X) + 1`
-Note that this is the same "flat 3D array" format as `PerlinNoiseMap:get3dMap_flat()`.
-VoxelArea objects (see section 'VoxelArea') can be used to simplify calculation of the index
-for a single point in a flat VoxelManip array.
+Note that this is the same "flat 3D array" format as
+`PerlinNoiseMap:get3dMap_flat()`.
+VoxelArea objects (see section 'VoxelArea') can be used to simplify calculation
+of the index for a single point in a flat VoxelManip array.
##### Content IDs
-A Content ID is a unique integer identifier for a specific node type. These IDs are used by VoxelManip
-in place of the node name string for `VoxelManip:get_data()` and `VoxelManip:set_data()`. You can use
-`minetest.get_content_id()` to look up the Content ID for the specified node name, and
-`minetest.get_name_from_content_id()` to look up the node name string for a given Content ID.
-After registration of a node, its Content ID will remain the same throughout execution of the mod.
+A Content ID is a unique integer identifier for a specific node type.
+These IDs are used by VoxelManip in place of the node name string for
+`VoxelManip:get_data()` and `VoxelManip:set_data()`. You can use
+`minetest.get_content_id()` to look up the Content ID for the specified node
+name, and `minetest.get_name_from_content_id()` to look up the node name string
+for a given Content ID.
+After registration of a node, its Content ID will remain the same throughout
+execution of the mod.
Note that the node being queried needs to have already been been registered.
The following builtin node types have their Content IDs defined as constants:
-* `minetest.CONTENT_UNKNOWN`: ID for "unknown" nodes
-* `minetest.CONTENT_AIR`: ID for "air" nodes
-* `minetest.CONTENT_IGNORE`: ID for "ignore" nodes
+* `minetest.CONTENT_UNKNOWN`: ID for "unknown" nodes
+* `minetest.CONTENT_AIR`: ID for "air" nodes
+* `minetest.CONTENT_IGNORE`: ID for "ignore" nodes
##### Mapgen VoxelManip objects
-Inside of `on_generated()` callbacks, it is possible to retrieve the same VoxelManip object used by the
-core's Map Generator (commonly abbreviated Mapgen). Most of the rules previously described still apply
-but with a few differences:
-
-* The Mapgen VoxelManip object is retrieved using: `minetest.get_mapgen_object("voxelmanip")`
-* This VoxelManip object already has the region of map just generated loaded into it; it's not necessary
- to call `VoxelManip:read_from_map()` before using a Mapgen VoxelManip.
-* The `on_generated()` callbacks of some mods may place individual nodes in the generated area using
- non-VoxelManip map modification methods. Because the same Mapgen VoxelManip object is passed through
- each `on_generated()` callback, it becomes necessary for the Mapgen VoxelManip object to maintain
- consistency with the current map state. For this reason, calling any of the following functions:
+Inside of `on_generated()` callbacks, it is possible to retrieve the same
+VoxelManip object used by the core's Map Generator (commonly abbreviated
+Mapgen). Most of the rules previously described still apply but with a few
+differences:
+
+* The Mapgen VoxelManip object is retrieved using:
+ `minetest.get_mapgen_object("voxelmanip")`
+* This VoxelManip object already has the region of map just generated loaded
+ into it; it's not necessary to call `VoxelManip:read_from_map()` before using
+ a Mapgen VoxelManip.
+* The `on_generated()` callbacks of some mods may place individual nodes in the
+ generated area using non-VoxelManip map modification methods. Because the
+ same Mapgen VoxelManip object is passed through each `on_generated()`
+ callback, it becomes necessary for the Mapgen VoxelManip object to maintain
+ consistency with the current map state. For this reason, calling any of the
+ following functions:
`minetest.add_node()`, `minetest.set_node()`, or `minetest.swap_node()`
- will also update the Mapgen VoxelManip object's internal state active on the current thread.
-* After modifying the Mapgen VoxelManip object's internal buffer, it may be necessary to update lighting
- information using either: `VoxelManip:calc_lighting()` or `VoxelManip:set_lighting()`.
+ will also update the Mapgen VoxelManip object's internal state active on the
+ current thread.
+* After modifying the Mapgen VoxelManip object's internal buffer, it may be
+ necessary to update lighting information using either:
+ `VoxelManip:calc_lighting()` or `VoxelManip:set_lighting()`.
##### Other API functions operating on a VoxelManip
-If any VoxelManip contents were set to a liquid node, `VoxelManip:update_liquids()` must be called
-for these liquid nodes to begin flowing. It is recommended to call this function only after having
-written all buffered data back to the VoxelManip object, save for special situations where the modder
-desires to only have certain liquid nodes begin flowing.
+If any VoxelManip contents were set to a liquid node,
+`VoxelManip:update_liquids()` must be called for these liquid nodes to begin
+flowing. It is recommended to call this function only after having written all
+buffered data back to the VoxelManip object, save for special situations where
+the modder desires to only have certain liquid nodes begin flowing.
-The functions `minetest.generate_ores()` and `minetest.generate_decorations()` will generate all
-registered decorations and ores throughout the full area inside of the specified VoxelManip object.
+The functions `minetest.generate_ores()` and `minetest.generate_decorations()`
+will generate all registered decorations and ores throughout the full area
+inside of the specified VoxelManip object.
-`minetest.place_schematic_on_vmanip()` is otherwise identical to `minetest.place_schematic()`,
-except instead of placing the specified schematic directly on the map at the specified position, it
-will place the schematic inside of the VoxelManip.
+`minetest.place_schematic_on_vmanip()` is otherwise identical to
+`minetest.place_schematic()`, except instead of placing the specified schematic
+directly on the map at the specified position, it will place the schematic
+inside the VoxelManip.
##### Notes
-* Attempting to read data from a VoxelManip object before map is read will result in a zero-length
- array table for `VoxelManip:get_data()`, and an "ignore" node at any position for
- `VoxelManip:get_node_at()`.
-* If either a region of map has not yet been generated or is out-of-bounds of the map, that region is
- filled with "ignore" nodes.
-* Other mods, or the core itself, could possibly modify the area of map currently loaded into a VoxelManip
- object. With the exception of Mapgen VoxelManips (see above section), the internal buffers are not
- updated. For this reason, it is strongly encouraged to complete the usage of a particular VoxelManip
- object in the same callback it had been created.
-* If a VoxelManip object will be used often, such as in an `on_generated()` callback, consider passing
- a file-scoped table as the optional parameter to `VoxelManip:get_data()`, which serves as a static
- buffer the function can use to write map data to instead of returning a new table each call. This
- greatly enhances performance by avoiding unnecessary memory allocations.
+* Attempting to read data from a VoxelManip object before map is read will
+ result in a zero-length array table for `VoxelManip:get_data()`, and an
+ "ignore" node at any position for `VoxelManip:get_node_at()`.
+* If either a region of map has not yet been generated or is out-of-bounds of
+ the map, that region is filled with "ignore" nodes.
+* Other mods, or the core itself, could possibly modify the area of map
+ currently loaded into a VoxelManip object. With the exception of Mapgen
+ VoxelManips (see above section), the internal buffers are not updated. For
+ this reason, it is strongly encouraged to complete the usage of a particular
+ VoxelManip object in the same callback it had been created.
+* If a VoxelManip object will be used often, such as in an `on_generated()`
+ callback, consider passing a file-scoped table as the optional parameter to
+ `VoxelManip:get_data()`, which serves as a static buffer the function can use
+ to write map data to instead of returning a new table each call. This greatly
+ enhances performance by avoiding unnecessary memory allocations.
#### Methods
-* `read_from_map(p1, p2)`: Loads a chunk of map into the VoxelManip object containing
- the region formed by `p1` and `p2`.
+* `read_from_map(p1, p2)`: Loads a chunk of map into the VoxelManip object
+ containing the region formed by `p1` and `p2`.
* returns actual emerged `pmin`, actual emerged `pmax`
-* `write_to_map([light])`: Writes the data loaded from the `VoxelManip` back to the map.
- * **important**: data must be set using `VoxelManip:set_data()` before calling this
+* `write_to_map([light])`: Writes the data loaded from the `VoxelManip` back to
+ the map.
+ * **important**: data must be set using `VoxelManip:set_data()` before
+ calling this.
* if `light` is true, then lighting is automatically recalculated.
The default value is true.
If `light` is false, no light calculations happen, and you should correct
@@ -3811,38 +4502,52 @@ will place the schematic inside of the VoxelManip.
more lighting bugs.
* `get_node_at(pos)`: Returns a `MapNode` table of the node currently loaded in
the `VoxelManip` at that position
-* `set_node_at(pos, node)`: Sets a specific `MapNode` in the `VoxelManip` at that position
-* `get_data([buffer])`: Retrieves the node content data loaded into the `VoxelManip` object
+* `set_node_at(pos, node)`: Sets a specific `MapNode` in the `VoxelManip` at
+ that position.
+* `get_data([buffer])`: Retrieves the node content data loaded into the
+ `VoxelManip` object.
* returns raw node data in the form of an array of node content IDs
- * if the param `buffer` is present, this table will be used to store the result instead
+ * if the param `buffer` is present, this table will be used to store the
+ result instead.
* `set_data(data)`: Sets the data contents of the `VoxelManip` object
* `update_map()`: Does nothing, kept for compatibility.
-* `set_lighting(light, [p1, p2])`: Set the lighting within the `VoxelManip` to a uniform value
+* `set_lighting(light, [p1, p2])`: Set the lighting within the `VoxelManip` to
+ a uniform value.
* `light` is a table, `{day=<0...15>, night=<0...15>}`
- * To be used only by a `VoxelManip` object from `minetest.get_mapgen_object`
- * (`p1`, `p2`) is the area in which lighting is set;
- defaults to the whole area if left out
+ * To be used only by a `VoxelManip` object from
+ `minetest.get_mapgen_object`.
+ * (`p1`, `p2`) is the area in which lighting is set, defaults to the whole
+ area if left out.
* `get_light_data()`: Gets the light data read into the `VoxelManip` object
- * Returns an array (indices 1 to volume) of integers ranging from `0` to `255`
- * Each value is the bitwise combination of day and night light values (`0` to `15` each)
+ * Returns an array (indices 1 to volume) of integers ranging from `0` to
+ `255`.
+ * Each value is the bitwise combination of day and night light values
+ (`0` to `15` each).
* `light = day + (night * 16)`
* `set_light_data(light_data)`: Sets the `param1` (light) contents of each node
- in the `VoxelManip`
+ in the `VoxelManip`.
* expects lighting data in the same format that `get_light_data()` returns
-* `get_param2_data([buffer])`: Gets the raw `param2` data read into the `VoxelManip` object
- * Returns an array (indices 1 to volume) of integers ranging from `0` to `255`
- * If the param `buffer` is present, this table will be used to store the result instead
-* `set_param2_data(param2_data)`: Sets the `param2` contents of each node in the `VoxelManip`
-* `calc_lighting([p1, p2], [propagate_shadow])`: Calculate lighting within the `VoxelManip`
- * To be used only by a `VoxelManip` object from `minetest.get_mapgen_object`
- * (`p1`, `p2`) is the area in which lighting is set; defaults to the whole area
- if left out or nil
- * `propagate_shadow` is an optional boolean deciding whether shadows in a generated
- mapchunk above are propagated down into the mapchunk; defaults to `true` if left out
+* `get_param2_data([buffer])`: Gets the raw `param2` data read into the
+ `VoxelManip` object.
+ * Returns an array (indices 1 to volume) of integers ranging from `0` to
+ `255`.
+ * If the param `buffer` is present, this table will be used to store the
+ result instead.
+* `set_param2_data(param2_data)`: Sets the `param2` contents of each node in
+ the `VoxelManip`.
+* `calc_lighting([p1, p2], [propagate_shadow])`: Calculate lighting within the
+ `VoxelManip`.
+ * To be used only by a `VoxelManip` object from
+ `minetest.get_mapgen_object`.
+ * (`p1`, `p2`) is the area in which lighting is set, defaults to the whole
+ area if left out or nil.
+ * `propagate_shadow` is an optional boolean deciding whether shadows in a
+ generated mapchunk above are propagated down into the mapchunk, defaults
+ to `true` if left out.
* `update_liquids()`: Update liquid flow
-* `was_modified()`: Returns `true` or `false` if the data in the voxel manipulator
- had been modified since the last read from map, due to a call to
- `minetest.set_data()` on the loaded area elsewhere
+* `was_modified()`: Returns `true` or `false` if the data in the voxel
+ manipulator had been modified since the last read from map, due to a call to
+ `minetest.set_data()` on the loaded area elsewhere.
* `get_emerged_area()`: Returns actual emerged minimum and maximum positions.
### `VoxelArea`
@@ -3852,18 +4557,24 @@ The coordinates are *inclusive*, like most other things in Minetest.
#### Methods
* `getExtent()`: returns a 3D vector containing the size of the area formed by
- `MinEdge` and `MaxEdge`
-* `getVolume()`: returns the volume of the area formed by `MinEdge` and `MaxEdge`
-* `index(x, y, z)`: returns the index of an absolute position in a flat array starting at `1`
+ `MinEdge` and `MaxEdge`.
+* `getVolume()`: returns the volume of the area formed by `MinEdge` and
+ `MaxEdge`.
+* `index(x, y, z)`: returns the index of an absolute position in a flat array
+ starting at `1`.
* useful for things like `VoxelManip`, raw Schematic specifiers,
- `PerlinNoiseMap:get2d`/`3dMap`, and so on
+ `PerlinNoiseMap:get2d`/`3dMap`, and so on.
* `indexp(p)`: same as above, except takes a vector
-* `position(i)`: returns the absolute position vector corresponding to index `i`
-* `contains(x, y, z)`: check if (`x`,`y`,`z`) is inside area formed by `MinEdge` and `MaxEdge`
+* `position(i)`: returns the absolute position vector corresponding to index
+ `i`.
+* `contains(x, y, z)`: check if (`x`,`y`,`z`) is inside area formed by
+ `MinEdge` and `MaxEdge`.
* `containsp(p)`: same as above, except takes a vector
* `containsi(i)`: same as above, except takes an index `i`
-* `iter(minx, miny, minz, maxx, maxy, maxz)`: returns an iterator that returns indices
- * from (`minx`,`miny`,`minz`) to (`maxx`,`maxy`,`maxz`) in the order of `[z [y [x]]]`
+* `iter(minx, miny, minz, maxx, maxy, maxz)`: returns an iterator that returns
+ indices.
+ * from (`minx`,`miny`,`minz`) to (`maxx`,`maxy`,`maxz`) in the order of
+ `[z [y [x]]]`.
* `iterp(minp, maxp)`: same as above, except takes a vector
### `Settings`
@@ -3873,13 +4584,20 @@ It can be created via `Settings(filename)`.
#### Methods
* `get(key)`: returns a value
-* `get_bool(key)`: returns a boolean
+* `get_bool(key, [default])`: returns a boolean
+ * `default` is the value returned if `key` is not found.
+ * Returns `nil` if `key` is not found and `default` not specified.
+* `get_np_group(key)`: returns a NoiseParams table
* `set(key, value)`
* Setting names can't contain whitespace or any of `="{}#`.
* Setting values can't contain the sequence `\n"""`.
- * Setting names starting with "secure." can't be set on the main settings object (`minetest.settings`).
+ * Setting names starting with "secure." can't be set on the main settings
+ object (`minetest.settings`).
* `set_bool(key, value)`
* See documentation for set() above.
+* `set_np_group(key, value)`
+ * `value` is a NoiseParams table.
+ * Also, see documentation for set() above.
* `remove(key)`: returns a boolean (`true` for success)
* `get_names()`: returns `{key1,...}`
* `write()`: returns a boolean (`true` for success)
@@ -3897,10 +4615,10 @@ the object.
It can be created via `Raycast(pos1, pos2, objects, liquids)` or
`minetest.raycast(pos1, pos2, objects, liquids)` where:
- * `pos1`: start of the ray
- * `pos2`: end of the ray
- * `objects` : if false, only nodes will be returned. Default is true.
- * `liquids' : if false, liquid nodes won't be returned. Default is false.
+* `pos1`: start of the ray
+* `pos2`: end of the ray
+* `objects` : if false, only nodes will be returned. Default is true.
+* `liquids' : if false, liquid nodes won't be returned. Default is false.
#### Methods
* `next()`: returns a `pointed_thing`
@@ -3908,17 +4626,18 @@ It can be created via `Raycast(pos1, pos2, objects, liquids)` or
Mapgen objects
--------------
-A mapgen object is a construct used in map generation. Mapgen objects can be used
-by an `on_generate` callback to speed up operations by avoiding unnecessary
-recalculations; these can be retrieved using the `minetest.get_mapgen_object()`
-function. If the requested Mapgen object is unavailable, or `get_mapgen_object()`
-was called outside of an `on_generate()` callback, `nil` is returned.
+A mapgen object is a construct used in map generation. Mapgen objects can be
+used by an `on_generate` callback to speed up operations by avoiding
+unnecessary recalculations, these can be retrieved using the
+`minetest.get_mapgen_object()` function. If the requested Mapgen object is
+unavailable, or `get_mapgen_object()` was called outside of an `on_generate()`
+callback, `nil` is returned.
The following Mapgen objects are currently available:
### `voxelmanip`
-This returns three values; the `VoxelManip` object to be used, minimum and maximum
-emerged position, in that order. All mapgens support this object.
+This returns three values; the `VoxelManip` object to be used, minimum and
+maximum emerged position, in that order. All mapgens support this object.
### `heightmap`
Returns an array containing the y coordinates of the ground levels of nodes in
@@ -3938,9 +4657,12 @@ generated chunk by the current mapgen.
### `gennotify`
Returns a table mapping requested generation notification types to arrays of
-positions at which the corresponding generated structures are located at within
+positions at which the corresponding generated structures are located within
the current chunk. To set the capture of positions of interest to be recorded
on generate, use `minetest.set_gen_notify()`.
+For decorations, the returned positions are the ground surface 'place_on'
+nodes, not the decorations themselves. A 'simple' type decoration is often 1
+node above the returned position and possibly displaced by 'place_offset_y'.
Possible fields of the table returned are:
@@ -3959,7 +4681,8 @@ Registered entities
-------------------
* Functions receive a "luaentity" as `self`:
* It has the member `.name`, which is the registered name `("mod:thing")`
- * It has the member `.object`, which is an `ObjectRef` pointing to the object
+ * It has the member `.object`, which is an `ObjectRef` pointing to the
+ object.
* The original prototype stuff is visible directly via a metatable
* Callbacks:
* `on_activate(self, staticdata, dtime_s)`
@@ -3968,20 +4691,21 @@ Registered entities
be used for updating the entity state.
* `on_step(self, dtime)`
* Called on every server tick, after movement and collision processing.
- `dtime` is usually 0.1 seconds, as per the `dedicated_server_step` setting
- `in minetest.conf`.
+ `dtime` is usually 0.1 seconds, as per the `dedicated_server_step`
+ setting `in minetest.conf`.
* `on_punch(self, puncher, time_from_last_punch, tool_capabilities, dir)`
* Called when somebody punches the object.
* Note that you probably want to handle most punches using the
automatic armor group system.
- * `puncher`: an `ObjectRef` (can be `nil`)
- * `time_from_last_punch`: Meant for disallowing spamming of clicks (can be `nil`)
- * `tool_capabilities`: capability table of used tool (can be `nil`)
- * `dir`: unit vector of direction of punch. Always defined. Points from
- the puncher to the punched.
- `on_death(self, killer)`
+ * `puncher`: an `ObjectRef` (can be `nil`)
+ * `time_from_last_punch`: Meant for disallowing spamming of clicks
+ (can be `nil`).
+ * `tool_capabilities`: capability table of used tool (can be `nil`)
+ * `dir`: unit vector of direction of punch. Always defined. Points from
+ the puncher to the punched.
+ * `on_death(self, killer)`
* Called when the object dies.
- * `killer`: an `ObjectRef` (can be `nil`)
+ * `killer`: an `ObjectRef` (can be `nil`)
* `on_rightclick(self, clicker)`
* `get_staticdata(self)`
* Should return a string that will be passed to `on_activate` when
@@ -3989,9 +4713,6 @@ Registered entities
L-system trees
--------------
-**Warning**
-L-system generation currently creates lighting bugs in the form of mapblock-sized shadows.
-Often these bugs appear as subtle shadows in water.
### Tree definition
@@ -4013,7 +4734,8 @@ Often these bugs appear as subtle shadows in water.
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
+ seed, --num random seed, if no seed is provided, the engine
+ will create one.
}
### Key for Special L-System Symbols used in Axioms
@@ -4067,24 +4789,72 @@ Definition tables
{
hp_max = 1,
- -- ^ For players, the maximal HP defaults to `minetest.PLAYER_MAX_HP_DEFAULT`
+ -- ^ For players: 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 zoomFOV values increase the distance loaded and/or 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.
+ -- Defaults to 1.625.
physical = true,
- collide_with_objects = true, -- collide with other objects if physical = true
+ collide_with_objects = true,
+ -- ^ Collide with other objects if physical = true.
weight = 5,
collisionbox = {-0.5, 0.0, -0.5, 0.5, 1.0, 0.5},
selectionbox = {-0.5, 0.0, -0.5, 0.5, 1.0, 0.5},
- -- ^ Default, uses collision box dimensions when not set
- pointable = true, -- overrides selection box when false
+ -- ^ Default, uses collision box dimensions when not set.
+ -- ^ For both boxes: {xmin, ymin, zmin, xmax, ymax, zmax} in nodes from
+ -- object position.
+ pointable = true,
+ -- ^ Overrides selection box when false.
visual = "cube" / "sprite" / "upright_sprite" / "mesh" / "wielditem",
+ -- ^ "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 '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'.
visual_size = {x = 1, y = 1},
+ -- ^ `x` multiplies horizontal (X and Z) visual size.
+ -- ^ `y` multiplies vertical (Y) visual size.
mesh = "model",
- textures = {}, -- number of required textures depends on visual
- colors = {}, -- number of required colors depends on visual
+ textures = {},
+ -- ^ Number of required textures depends on visual.
+ -- ^ "cube" uses 6 textures in the way a node does.
+ -- ^ "sprite" uses 1 texture.
+ -- ^ "upright_sprite" uses 2 textures: {front, back}.
+ -- ^ "wielditem" expects 'textures = {itemname}' (see 'visual' above).
+ colors = {},
+ -- ^ Number of required colors depends on visual.
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,
makes_footstep_sound = false,
- automatic_rotate = false,
+ automatic_rotate = 0,
+ -- ^ Set constant rotation in radians per second, positive or negative.
+ -- ^ Set to 0 to disable constant rotation.
stepheight = 0,
automatic_face_movement_dir = 0.0,
-- ^ Automatically set yaw to movement direction, offset in degrees,
@@ -4092,10 +4862,24 @@ Definition tables
automatic_face_movement_max_rotation_per_sec = -1,
-- ^ Limit automatic rotation to this value in degrees per second,
-- value < 0 no limit.
- backface_culling = true, -- false to disable backface_culling for model
- nametag = "", -- by default empty, for players their name is shown if empty
- nametag_color = , -- sets color of nametag as ColorSpec
- infotext = "", -- by default empty, text to be shown when pointed at object
+ 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 = "",
+ -- ^ By default empty, for players their name is shown if empty.
+ nametag_color = ,
+ -- ^ Sets color of nametag as ColorSpec.
+ infotext = "",
+ -- ^ By default empty, text to be shown when pointed at object.
+ 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'
}
### Entity definition (`register_entity`)
@@ -4113,28 +4897,43 @@ Definition tables
-- ^ Called sometimes; the string returned is passed to on_activate when
-- the entity is re-activated from static state
- -- Also you can define arbitrary member variables here (see item definition for
- -- more info)
_custom_field = whatever,
+ -- ^ You can define arbitrary member variables here (see item definition
+ -- for more info) by using a '_' prefix.
}
### ABM (ActiveBlockModifier) definition (`register_abm`)
{
label = "Lava cooling",
- -- ^ Descriptive label for profiling purposes (optional).
- -- Definitions with identical labels will be listed as one.
- -- In the following two fields, also group:groupname will work.
+ ^ Descriptive label for profiling purposes (optional).
+ Definitions with identical labels will be listed as one.
nodenames = {"default:lava_source"},
- neighbors = {"default:water_source", "default:water_flowing"}, -- Any of these --[[
- ^ If left out or empty, any neighbor will do ]]
- interval = 1.0, -- Operation interval in seconds
- chance = 1, -- Chance of trigger per-node per-interval is 1.0 / this
- catch_up = true, -- If true, catch-up behaviour is enabled --[[
- ^ The chance value is temporarily reduced when returning to
- an area to simulate time lost by the area being unattended.
- ^ Note chance value can often be reduced to 1 ]]
- action = func(pos, node, active_object_count, active_object_count_wider),
+ ^ 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 = 1.0,
+ ^ Operation interval in seconds.
+ chance = 1,
+ ^ Chance of triggering `action` per-node per-interval is 1.0 / this
+ value.
+ catch_up = true,
+ ^ If true, catch-up behaviour 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 estmate is calculated for them based on
+ loaded mapblocks.
}
### LBM (LoadingBlockModifier) definition (`register_lbm`)
@@ -4166,7 +4965,8 @@ Definition tables
{bendy = 2, snappy = 1},
{hard = 1, metal = 1, spikes = 1}
inventory_image = "default_tool_steelaxe.png",
- inventory_overlay = "overlay.png", -- an overlay which does not get colorized
+ inventory_overlay = "overlay.png",
+ ^ An overlay which does not get colorized.
wield_image = "",
wield_overlay = "",
palette = "",
@@ -4179,9 +4979,7 @@ Definition tables
^ "colorfacedir" and "colorwallmounted" nodes.
]]
color = "0xFFFFFFFF",
- --[[
^ The color of the item. The palette overrides this.
- ]]
wield_scale = {x = 1, y = 1, z = 1},
stack_max = 99,
range = 4.0,
@@ -4191,7 +4989,8 @@ Definition tables
max_drop_level = 0,
groupcaps = {
-- For example:
- choppy = {times = {[1] = 2.50, [2] = 1.40, [3] = 1.00}, uses = 20, maxlevel = 2},
+ choppy = {times = {[1] = 2.50, [2] = 1.40, [3] = 1.00},
+ uses = 20, maxlevel = 2},
},
damage_groups = {groupname = damage},
},
@@ -4204,6 +5003,13 @@ Definition tables
on ground when the player places the item. Server will always update
actual result to client in a short moment.
]]
+ 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 actual result shortly.
+ ]]
sound = {
breaks = "default_tool_break", -- tools only
place = --[[]],
@@ -4230,7 +5036,7 @@ Definition tables
^ default: nil
^ Function must return either nil if no item shall be removed from
inventory, or an itemstack to replace the original itemstack.
- e.g. itemstack:take_item(); return 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.
@@ -4259,12 +5065,21 @@ Definition tables
* `"image.png"`
* `{name="image.png", animation={Tile Animation definition}}`
* `{name="image.png", backface_culling=bool, tileable_vertical=bool,
- tileable_horizontal=bool}`
+ tileable_horizontal=bool, align_style="node"/"world"/"user", scale=int}`
* backface culling enabled by default for most nodes
* tileable flags are info for shaders, how they should treat texture
- when displacement mapping is used
- Directions are from the point of view of the tile texture,
- not the node it's on
+ when displacement mapping is used
+ Directions are from the point of view of the tile texture,
+ not the node it's on
+ * align style determines whether the texture will be rotated with the node
+ or kept aligned with its surroundings. "user" means that client
+ setting will be used, similar to `glasslike_framed_optional`.
+ Note: supported by solid nodes and nodeboxes only.
+ * scale is used to make texture span several (exactly `scale`) nodes,
+ instead of just one, in each direction. Works for world-aligned
+ textures only.
+ Note that as the effect is applied on per-mapblock basis, `16` should
+ be equally divisible by `scale` or you may get wrong results.
* `{name="image.png", color=ColorSpec}`
* the texture's color will be multiplied with this color.
* the tile's color overrides the owning node's color in all cases.
@@ -4273,25 +5088,25 @@ Definition tables
### Tile animation definition
- {
- type = "vertical_frames",
- aspect_w = 16,
- -- ^ specify width of a frame in pixels
- aspect_h = 16,
- -- ^ specify height of a frame in pixels
- length = 3.0,
- -- ^ specify full loop length
- }
-
- {
- type = "sheet_2d",
- frames_w = 5,
- -- ^ specify width in number of frames
- frames_h = 3,
- -- ^ specify height in number of frames
- frame_length = 0.5,
- -- ^ specify length of a single frame
- }
+ {
+ type = "vertical_frames",
+ aspect_w = 16,
+ -- ^ specify width of a frame in pixels
+ aspect_h = 16,
+ -- ^ specify height of a frame in pixels
+ length = 3.0,
+ -- ^ specify full loop length
+ }
+
+ {
+ type = "sheet_2d",
+ frames_w = 5,
+ -- ^ specify width in number of frames
+ frames_h = 3,
+ -- ^ specify height in number of frames
+ frame_length = 0.5,
+ -- ^ specify length of a single frame
+ }
### Node definition (`register_node`)
@@ -4306,36 +5121,44 @@ Definition tables
^ node, for the other drawtypes the image will be centered on the node.
^ Note that positioning for "torchlike" may still change. ]]
tiles = {tile definition 1, def2, def3, def4, def5, def6}, --[[
- ^ Textures of node; +Y, -Y, +X, -X, +Z, -Z (old field name: tile_images)
+ ^ Textures of node; +Y, -Y, +X, -X, +Z, -Z
+ ^ Old field name was 'tile_images'.
^ 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.
+ ^ is not recommended to use overlays on very common nodes. ]]
special_tiles = {tile definition 1, Tile definition 2}, --[[
- ^ Special textures of node; used rarely (old field name: special_materials)
+ ^ Special textures of node; used rarely
+ ^ Old field name was 'special_materials'.
^ 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 = false, -- Use texture's alpha channel
+ use_texture_alpha = false,
+ ^ Use texture's alpha channel.
palette = "palette.png", --[[
^ 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 = "green#0F", -- If player is inside node, see "ColorSpec"
- paramtype = "none", -- See "Nodes" --[[
- ^ paramtype = "light" allows light to propagate from or through the node with light value
- ^ falling by 1 per node. This line is essential for a light source node to spread its light. ]]
+ post_effect_color = "green#0F",
+ ^ Screen tint if player is inside node, see "ColorSpec".
+ paramtype = "none", --[[
+ ^ See "Nodes".
+ ^ paramtype = "light" allows light to propagate from or through the
+ ^ node with light value falling by 1 per node. This line is essential
+ ^ for a light source node to spread its light. ]]
paramtype2 = "none", -- See "Nodes"
place_param2 = nil, -- Force value for param2 when player places node
- is_ground_content = true, -- If false, the cave generator will not carve through this
- sunlight_propagates = false, -- If true, sunlight will go infinitely through this
+ is_ground_content = true,
+ ^ If false, the cave generator will not carve through this node.
+ sunlight_propagates = false,
+ ^ If true, sunlight will go infinitely through this.
walkable = true, -- If true, objects collide with node
pointable = true, -- If true, can be pointed at
diggable = true, -- If false, can never be dug
@@ -4343,41 +5166,55 @@ Definition tables
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' does not work and may cause problems. ]]
+ ^ Warning: making a liquid node 'floodable' will cause problems. ]]
liquidtype = "none", -- "none"/"source"/"flowing"
liquid_alternative_flowing = "", -- Flowing version of source liquid
liquid_alternative_source = "", -- Source version of flowing liquid
liquid_viscosity = 0, -- Higher viscosity = slower flow (max. 7)
liquid_renewable = true, --[[
- ^ If true, a new liquid source can be created by placing two or more sources nearby ]]
- leveled = 0, --[[
- ^ Block contains level in param2. Value is default level, used for snow.
- ^ Don't forget to use "leveled" type nodebox. ]]
+ ^ If true, a new liquid source can be created by placing two or more
+ sources nearby. ]]
+ leveled = 16, --[[
+ ^ 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 127. ]]
liquid_range = 8, -- number of flowing nodes around source (max. 8)
- drowning = 0, -- Player will take this amount of damage if no bubbles are left
+ drowning = 0,
+ ^ Player will take this amount of damage if no bubbles are left.
light_source = 0, --[[
^ Amount of light emitted by node.
- ^ To set the maximum (currently 14), use the value 'minetest.LIGHT_MAX'.
- ^ A value outside the range 0 to minetest.LIGHT_MAX causes undefined behavior.]]
- damage_per_second = 0, -- If player is inside node, this damage is caused
+ ^ To set the maximum (currently 14), use the value
+ ^ 'minetest.LIGHT_MAX'.
+ ^ A value outside the range 0 to minetest.LIGHT_MAX causes undefined
+ ^ behavior.]]
+ damage_per_second = 0,
+ ^ If player is inside node, this damage is caused.
node_box = {type="regular"}, -- See "Node boxes"
connects_to = nodenames, --[[
- * 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 = { "top", "bottom", "front", "left", "back", "right" }, --[[
- ^ Tells connected nodebox nodes to connect only to these sides of this node. ]]
+ ^ 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 = { "top", "bottom", "front", "left", "back", "right" },
+ -- [[
+ ^ Tells connected nodebox nodes to connect only to these sides of this
+ ^ node. ]]
mesh = "model",
- selection_box = {type="regular"}, -- See "Node boxes" --[[
- ^ If drawtype "nodebox" is used and selection_box is nil, then node_box is used. ]]
- legacy_facedir_simple = false, -- Support maps made in and before January 2012
- legacy_wallmounted = false, -- Support maps made in and before January 2012
- waving = 0, --[[ valid for mesh, nodebox, plantlike, allfaces_optional nodes
+ selection_box = {type="regular"}, --[[
+ ^ See "Node boxes".
+ ^ If drawtype "nodebox" is used and selection_box is nil, then node_box
+ ^ is used. ]]
+ legacy_facedir_simple = false,
+ ^ Support maps made in and before January 2012.
+ legacy_wallmounted = false,
+ ^ Support maps made in and before January 2012.
+ waving = 0, --[[
+ ^ Valid for mesh, nodebox, plantlike, allfaces_optional nodes.
^ 1 - wave node like plants (top of node moves, bottom is fixed)
- ^ 2 - wave node like leaves (whole node moves side-to-side synchronously)
- ^ caveats: not all models will properly wave
- ^ plantlike drawtype nodes can only wave like plants
- ^ allfaces_optional drawtype nodes can only wave like leaves --]]
+ ^ 2 - wave node like leaves (whole node moves side-to-side)
+ ^ caveats: not all models will properly wave.
+ ^ plantlike drawtype nodes can only wave like plants.
+ ^ allfaces_optional drawtype nodes can only wave like leaves. --]]
sounds = {
footstep = ,
dig = , -- "__group" = group-based sound (default)
@@ -4385,15 +5222,17 @@ Definition tables
place = ,
place_failed = ,
},
- drop = "", -- Name of dropped node when dug. Default is the node itself.
- -- Alternatively:
+ drop = "",
+ ^ Name of dropped node when dug. Default is the node itself.
+ ^ Alternatively:
drop = {
max_items = 1, -- Maximum number of items to drop.
- items = { -- Choose max_items randomly from this list.
+ items = { -- Choose max_items randomly from this list.
{
items = {"foo:bar", "baz:frob"}, -- Items to drop.
rarity = 1, -- Probability of dropping is 1 / rarity.
- inherit_color = true, -- To inherit palette color from the node
+ inherit_color = true, -- To inherit palette color from the
+ node.
},
},
},
@@ -4403,14 +5242,17 @@ Definition tables
^ Can set up metadata and stuff like that
^ Not called for bulk node placement (i.e. schematics and VoxelManip)
^ default: nil ]]
+
on_destruct = func(pos), --[[
^ Node destructor; called before removing node
^ Not called for bulk node placement (i.e. schematics and VoxelManip)
^ default: nil ]]
+
after_destruct = func(pos, oldnode), --[[
^ Node destructor; called after removing node
^ Not called for bulk node placement (i.e. schematics and VoxelManip)
^ default: nil ]]
+
on_flood = func(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
@@ -4418,18 +5260,31 @@ Definition tables
^ 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' does not work and may cause problems. ]]
+ ^ Warning: making a liquid node 'floodable' will cause problems. ]]
+
+ preserve_metadata = func(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.
+ ^ drops is a table of ItemStacks, 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 = func(pos, placer, itemstack, pointed_thing) --[[
^ Called after constructing node when node was placed using
- minetest.item_place_node / minetest.place_node
+ ^ 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 = func(pos, oldnode, oldmetadata, digger), --[[
^ oldmetadata is in table format
^ Called after destructing node when node was dug using
- minetest.node_dig / minetest.dig_node
+ ^ minetest.node_dig / minetest.dig_node
^ default: nil ]]
+
can_dig = function(pos, [player]) --[[
^ returns true if node can be dug, or false if not
^ default: nil ]]
@@ -4437,13 +5292,15 @@ Definition tables
on_punch = func(pos, node, puncher, pointed_thing), --[[
^ default: minetest.node_punch
^ By default: Calls minetest.register_on_punchnode callbacks ]]
- on_rightclick = func(pos, node, clicker, itemstack, pointed_thing), --[[
+
+ on_rightclick = func(pos, node, clicker, itemstack, pointed_thing),
+ --[[
^ default: nil
^ 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 ]]
+ ^ This function does not get triggered by clients <=0.4.16 if the
+ ^ "formspec" node metadata field is set ]]
on_dig = func(pos, node, digger), --[[
^ default: minetest.node_dig
@@ -4453,33 +5310,37 @@ Definition tables
^ 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 ]]
+ ^ return true to run the timer for another cycle with the same timeout
+ ^ value. ]]
on_receive_fields = func(pos, formname, fields, sender), --[[
^ fields = {name1 = value1, name2 = value2, ...}
^ Called when an UI form (e.g. sign text input) returns data
^ default: nil ]]
- allow_metadata_inventory_move = func(pos, from_list, from_index,
- to_list, to_index, count, player), --[[
+ allow_metadata_inventory_move = func(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 = func(pos, listname, index, stack, player), --[[
+ allow_metadata_inventory_put = func(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 = func(pos, listname, index, stack, player), --[[
+ allow_metadata_inventory_take = func(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 = func(pos, from_list, from_index,
- to_list, to_index, count, player),
+ on_metadata_inventory_move = func(pos, from_list, from_index, to_list, to_index, count, player),
on_metadata_inventory_put = func(pos, listname, index, stack, player),
- on_metadata_inventory_take = func(pos, listname, index, stack, player), --[[
- ^ Called after the actual action has happened, according to what was allowed.
+ on_metadata_inventory_take = func(pos, listname, index, stack, player),
+ --[[
+ ^ Called after the actual action has happened, according to what was
+ ^ allowed.
^ No return value ]]
on_blast = func(pos, intensity), --[[
@@ -4541,46 +5402,94 @@ Definition tables
### Ore definition (`register_ore`)
+ See 'Ore types' section above for essential information.
+
{
- ore_type = "scatter", -- See "Ore types"
+ ore_type = "scatter",
ore = "default:stone_with_coal",
+ ore_param2 = 3,
+ -- ^ Facedir rotation. Default is 0 (unchanged rotation)
wherein = "default:stone",
-- ^ a list of nodenames is supported too
- clust_scarcity = 8*8*8,
+ clust_scarcity = 8 * 8 * 8,
-- ^ Ore has a 1 out of clust_scarcity chance of spawning in a node
- -- ^ This value should be *MUCH* higher than your intuition might tell you!
+ -- ^ 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_size = 3,
-- ^ Size of the bounding box of the cluster
- -- ^ In this example, there is a 3x3x3 cluster where 8 out of the 27 nodes are coal ore
+ -- ^ 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 = 64,
-- ^ Lower and upper limits for ore.
- -- ^ Limits are relative to y = water_level - 1 for core mapgen, or
- -- ^ relative to y = 0 for minetest.generate_ores().
flags = "",
- -- ^ Attributes for this ore generation
+ -- ^ Attributes for this ore generation, see 'Ore attributes' section
+ -- ^ above.
noise_threshold = 0.5,
- -- ^ 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, persist=0.70}
- -- ^ NoiseParams structure describing the perlin noise used for ore distribution.
- -- ^ Needed for sheet ore_type. Omit from scatter ore_type for a uniform ore distribution
- random_factor = 1.0,
- -- ^ Multiplier of the randomness contribution to the noise value at any
- -- ^ given point to decide if ore should be placed. Set to 0 for solid veins.
- -- ^ This parameter is only valid for ore_type == "vein".
+ -- ^ 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,
+ persist = 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 decoration occurs. Occurs in all biomes if this is omitted,
- -- ^ and ignored if the Mapgen being used does not support biomes.
+ -- ^ 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.
+ column_height_min = 1,
+ column_height_max = 16,
+ column_midpoint_factor = 0.5,
+ -- ^ See 'Ore types' section above.
+ -- ^ The above 3 parameters are only valid for "sheet" ore.
+ np_puff_top = {
+ offset = 4,
+ scale = 2,
+ spread = {x = 100, y = 100, z = 100},
+ seed = 47,
+ octaves = 3,
+ persist = 0.7
+ },
+ np_puff_bottom = {
+ offset = 4,
+ scale = 2,
+ spread = {x = 100, y = 100, z = 100},
+ seed = 11,
+ octaves = 3,
+ persist = 0.7
+ },
+ -- ^ See 'Ore types' section above.
+ -- ^ The above 2 parameters are only valid for "puff" ore.
+ random_factor = 1.0,
+ -- ^ See 'Ore types' section above.
+ -- ^ Only valid for "vein" ore.
+ np_stratum_thickness = {
+ offset = 8,
+ scale = 4,
+ spread = {x = 100, y = 100, z = 100},
+ seed = 17,
+ octaves = 3,
+ persist = 0.7
+ },
+ stratum_thickness = 8,
+ -- ^ See 'Ore types' section above.
+ -- ^ The above 2 parameters are only valid for "stratum" ore.
}
### Biome definition (`register_biome`)
-**Note**
-The Biome API is still in an experimental phase and subject to change.
-
{
name = "tundra",
node_dust = "default:snow",
@@ -4597,35 +5506,36 @@ The Biome API is still in an experimental phase and subject to change.
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 defined surface layer.
+ -- ^ Node that replaces all seawater nodes not in the defined surface
+ -- ^ layer.
node_river_water = "default:ice",
- -- ^ Node that replaces river water in mapgens that use default:river_water.
+ -- ^ 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.
- y_min = 1,
y_max = 31000,
- -- ^ Lower and upper limits for biome.
- -- ^ Limits are relative to y = water_level - 1.
- -- ^ Because biome is not recalculated for every node in a node column
- -- ^ some biome materials can exceed their limits, especially stone.
- -- ^ For each node column in a mapchunk, biome is only recalculated at column
- -- ^ top and at each of these surfaces:
- -- ^ Ground below air, water below air, ground below water.
- -- ^ The selected biome then stays in effect for all nodes below until
- -- ^ column base or the next biome recalculation.
+ 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 average temperature and humidity for the biome.
- -- ^ These values create 'biome points' on a voronoi diagram that has heat
- -- ^ and humidity as axes. The resulting voronoi cells determine which
- -- ^ heat/humidity points belong to which biome, and therefore determine
- -- ^ the area and location of each biome in the world.
- -- ^ The biome points need to be carefully and evenly spaced on the voronoi
- -- ^ diagram to result in roughly equal size biomes.
+ -- ^ 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 also often exceed these values.
- -- ^ Heat is not in degrees celcius, both values are abstract.
+ -- ^ 0 and 100 but can exceed these values.
}
### Decoration definition (`register_decoration`)
@@ -4635,71 +5545,107 @@ The Biome API is still in an experimental phase and subject to change.
place_on = "default:dirt_with_grass",
-- ^ Node (or list of nodes) that the decoration can be placed on
sidelen = 8,
- -- ^ Size of divisions made in the chunk being generated.
- -- ^ If the chunk size is not evenly divisible by sidelen, sidelen is made equal to the chunk size.
+ -- ^ Size of the square 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,
- -- ^ Ratio of the area to be uniformly filled by the decoration.
+ -- ^ The value determines 'decorations per surface node'.
-- ^ Used only if noise_params is not specified.
- noise_params = {offset=0, scale=.45, spread={x=100, y=100, z=100}, seed=354, octaves=3, persist=0.7},
- -- ^ NoiseParams structure describing the perlin noise used for decoration distribution.
- -- ^ The result of this is multiplied by the 2d area of the division being decorated.
+ noise_params = {
+ offset = 0,
+ scale = 0.45,
+ spread = {x = 100, y = 100, z = 100},
+ seed = 354,
+ octaves = 3,
+ persist = 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.
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.
+ -- ^ 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.
- -- ^ Limits are relative to y = water_level - 1 for core mapgen, or
- -- ^ relative to y = 0 for minetest.generate_decorations().
- -- ^ This parameter refers to the `y` position of the decoration base, so
- -- the actual maximum height would be `height_max + size.Y`.
+ -- ^ 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 two horizontal planes of neighbouring nodes (including diagonal neighbours),
- -- ^ one plane at Y = surface and one plane at Y = surface = + 1.
+ -- ^ Checks two horizontal planes of 8 neighbouring nodes (including
+ -- ^ diagonal neighbours), one plane level with the 'place_on' node and a
+ -- ^ plane one node above that.
num_spawn_by = 1,
- -- ^ Number of spawn_by nodes that must be surrounding the decoration position to occur.
+ -- ^ 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",
+ 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.
+ -- ^ 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.
+ -- ^ Ceiling decorations act as an inversion of floor decorations so the
+ -- ^ effect of 'place_offset_y' is inverted.
+ -- ^ If a single decoration registration has both flags the floor and
+ -- ^ ceiling decorations will be aligned vertically and may sometimes
+ -- ^ meet to form a column.
----- 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.
+ -- ^ If instead a list of strings, a randomly selected node from the list
+ -- ^ is placed as the decoration.
height = 1,
- -- ^ Number of nodes high the decoration is made.
- -- ^ If height_max is not 0, this is the lower bound of the randomly selected height.
+ -- ^ Decoration height in nodes.
+ -- ^ If height_max is not 0, this is the lower limit of a randomly
+ -- ^ selected height.
height_max = 0,
- -- ^ Number of nodes the decoration can be at maximum.
+ -- ^ Upper limit of the randomly selected height.
-- ^ If absent, the parameter 'height' is used as a constant.
param2 = 0,
- -- ^ Param2 value of placed decoration node.
+ -- ^ 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.
+ -- ^ If schematic is a string, it is the filepath relative to the current
+ -- ^ working directory of the specified Minetest schematic file.
-- ^ - OR -, could be the ID of a previously registered schematic
- -- ^ - OR -, could instead be a table containing two mandatory fields, size and data,
- -- ^ and an optional table yslice_prob:
+ -- ^ - OR -, could instead be a table containing two mandatory fields,
+ -- ^ size and data, and an optional table yslice_prob:
schematic = {
- size = {x=4, y=6, z=4},
+ 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="ignore", param1=255, param2=0},
- {name="air", param1=255, param2=0},
+ {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},
+ {ypos = 2, prob = 128},
+ {ypos = 5, prob = 64},
...
},
},
@@ -4707,8 +5653,16 @@ The Biome API is still in an experimental phase and subject to change.
replacements = {["oldname"] = "convert_to", ...},
flags = "place_center_x, place_center_y, place_center_z",
-- ^ Flags for schematic decorations. See 'Schematic attributes'.
- rotation = "90" -- rotate schematic 90 degrees on placement
+ 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 (`register_chatcommand`)
@@ -4718,9 +5672,22 @@ The Biome API is still in an experimental phase and subject to change.
description = "Remove privilege from player", -- Full description
privs = {privs=true}, -- Require the "privs" privilege to run
func = function(name, param), -- Called when command is run.
- -- Returns boolean success and text output.
+ -- Returns boolean success and text
+ -- output.
}
+Note that in params, use of symbols is as follows:
+
+* `<>` signifies a placeholder to be replaced when the command is used. For
+ example, when a player name is needed: ``
+* `[]` signifies param is optional and not required when the command is used.
+ For example, if you require param1 but param2 is optional:
+ ` []`
+* `|` signifies exclusive or. The command requires one param from the options
+ provided. For example: ` | `
+* `()` signifies grouping. For example, when param1 and param2 are both
+ required, or only param3 is required: `( ) | `
+
### Detached inventory callbacks
{
@@ -4741,7 +5708,8 @@ The Biome API is still in an experimental phase and subject to change.
on_move = func(inv, from_list, from_index, to_list, to_index, count, player),
on_put = func(inv, listname, index, stack, player),
on_take = func(inv, listname, index, stack, player),
- -- ^ Called after the actual action has happened, according to what was allowed.
+ -- ^ Called after the actual action has happened, according to what was
+ -- ^ allowed.
-- ^ No return value
}
@@ -4749,11 +5717,12 @@ The Biome API is still in an experimental phase and subject to change.
{
hud_elem_type = "image", -- see HUD element types
- -- ^ type of HUD element, can be either of "image", "text", "statbar", or "inventory"
+ -- ^ type of HUD element, can be either of "image", "text", "statbar",
+ "inventory".
position = {x=0.5, y=0.5},
-- ^ Left corner position of element
name = "",
- scale = {x=2, y=2},
+ scale = {x = 2, y = 2},
text = "",
number = 2,
item = 3,
@@ -4801,7 +5770,8 @@ The Biome API is still in an experimental phase and subject to change.
{
amount = 1,
time = 1,
- -- ^ If time is 0 has infinite lifespan and spawns the amount on a per-second base
+ -- ^ If time is 0 has infinite lifespan and spawns the amount on a
+ -- ^ per-second basis.
minpos = {x=0, y=0, z=0},
maxpos = {x=0, y=0, z=0},
minvel = {x=0, y=0, z=0},
@@ -4813,22 +5783,28 @@ The Biome API is still in an experimental phase and subject to change.
minsize = 1,
maxsize = 1,
-- ^ The particle's properties are random values in between the bounds:
- -- ^ minpos/maxpos, minvel/maxvel (velocity), minacc/maxacc (acceleration),
- -- ^ minsize/maxsize, minexptime/maxexptime (expirationtime)
+ -- ^ minpos/maxpos, minvel/maxvel (velocity),
+ -- ^ minacc/maxacc (acceleration), minsize/maxsize,
+ -- ^ minexptime/maxexptime (expirationtime).
collisiondetection = false,
-- ^ collisiondetection: if true uses collision detection
collision_removal = false,
-- ^ collision_removal: if true then particle is removed when it collides,
-- ^ requires collisiondetection = true to have any effect
attached = ObjectRef,
- -- ^ attached: if defined, particle positions, velocities and accelerations
- -- ^ are relative to this object's position and yaw.
+ -- ^ attached: if defined, particle positions, velocities and
+ -- ^ accelerations are relative to this object's position and yaw.
vertical = false,
-- ^ vertical: if true faces player using y axis only
texture = "image.png",
-- ^ Uses texture (string)
playername = "singleplayer"
- -- ^ Playername is optional, if specified spawns particle only on the player's client
+ -- ^ Playername is 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
}
### `HTTPRequest` definition (`HTTPApiTable.fetch_async`, `HTTPApiTable.fetch_async`)
@@ -4836,31 +5812,67 @@ The Biome API is still in an experimental phase and subject to change.
{
url = "http://example.org",
timeout = 10,
- -- ^ Timeout for connection in seconds. Default is 3 seconds.
- post_data = "Raw POST request data string" OR { field1 = "data1", field2 = "data2" },
- -- ^ Optional, if specified a POST request with post_data is performed.
- -- ^ Accepts both a string and a table. If a table is specified, encodes table
- -- ^ as x-www-form-urlencoded key-value pairs.
- -- ^ If post_data ist not specified, a GET request is performed instead.
+ -- ^ Timeout for connection in seconds. Default is 3 seconds.
+ post_data = "Raw POST request data string" OR {field1 = "data1", field2 = "data2"},
+ -- ^ Optional, if specified a POST request with post_data is performed.
+ -- ^ Accepts both a string and a table. If a table is specified, encodes
+ -- ^ table as x-www-form-urlencoded key-value pairs.
+ -- ^ If post_data ist not specified, a GET request is performed instead.
user_agent = "ExampleUserAgent",
- -- ^ Optional, if specified replaces the default minetest user agent with given string
+ -- ^ Optional, if specified replaces the default minetest user agent with
+ -- ^ given string.
extra_headers = { "Accept-Language: en-us", "Accept-Charset: utf-8" },
- -- ^ Optional, if specified adds additional headers to the HTTP request. You must make sure
- -- ^ that the header strings follow HTTP specification ("Key: Value").
+ -- ^ Optional, if specified adds additional headers to the HTTP request.
+ -- ^ You must make sure that the header strings follow HTTP specification
+ -- ^ ("Key: Value").
multipart = boolean
- -- ^ Optional, if true performs a multipart HTTP request. Default is false.
+ -- ^ Optional, if true performs a multipart HTTP request.
+ -- ^ Default is false.
}
### `HTTPRequestResult` definition (`HTTPApiTable.fetch` callback, `HTTPApiTable.fetch_async_get`)
{
completed = true,
- -- ^ If true, the request has finished (either succeeded, failed or timed out)
+ -- ^ If true, the request has finished (either succeeded, failed or timed
+ out).
succeeded = true,
- -- ^ If true, the request was succesful
+ -- ^ If true, the request was successful
timeout = false,
- -- ^ If true, the request timed out
+ -- ^ If true, the request timed out
code = 200,
- -- ^ HTTP status code
+ -- ^ HTTP status code
data = "response"
}
+
+### Authentication handler definition
+
+ {
+ get_auth = func(name),
+ -- ^ Get authentication data for existing player `name` (`nil` if player
+ doesn't exist).
+ -- ^ returns following structure:
+ -- ^ `{password=, privileges=, last_login=}`
+ create_auth = func(name, password),
+ -- ^ Create new auth data for player `name`
+ -- ^ Note that `password` is not plain-text but an arbitrary
+ -- ^ representation decided by the engine
+ delete_auth = func(name),
+ -- ^ Delete auth data of player `name`, returns boolean indicating success
+ -- ^ (false if player nonexistant).
+ set_password = func(name, password),
+ -- ^ Set password of player `name` to `password`
+ Auth data should be created if not present
+ set_privileges = func(name, privileges),
+ -- ^ Set privileges of player `name`
+ -- ^ `privileges` is in table form, auth data should be created if not
+ -- ^ present.
+ reload = func(),
+ -- ^ Reload authentication data from the storage location
+ -- ^ Returns boolean indicating success
+ record_login = func(name),
+ -- ^ Called when player joins, used for keeping track of last_login
+ iterate = func(),
+ -- ^ Returns an iterator (use with `for` loops) for all player names
+ -- ^ currently in the auth database.
+ }
| | |