aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/lua_api.txt1985
1 files changed, 993 insertions, 992 deletions
diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 47931eb00..9fb22556b 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -1147,346 +1147,6 @@ A box of a regular node would look like:
{-0.5, -0.5, -0.5, 0.5, 0.5, 0.5},
-Perlin noise
-------------
-Perlin noise creates a continuously-varying value depending on the input values.
-Usually in Minetest the input values are either 2D or 3D co-ordinates in nodes.
-The result is used during map generation to create the terrain shape, vary heat
-and humidity to distribute biomes, vary the density of decorations or vary the
-structure of ores.
-
-### Structure of perlin noise
-An 'octave' is a simple noise generator that outputs a value between -1 and 1.
-The smooth wavy noise it generates has a single characteristic scale, almost
-like a 'wavelength', so on its own does not create fine detail.
-Due to this perlin noise combines several octaves to create variation on
-multiple scales. Each additional octave has a smaller 'wavelength' than the
-previous.
-
-This combination results in noise varying very roughly between -2.0 and 2.0 and
-with an average value of 0.0, so `scale` and `offset` are then used to multiply
-and offset the noise variation.
-
-The final perlin noise variation is created as follows:
-
-noise = offset + scale * (octave1 +
- octave2 * persistence +
- octave3 * persistence ^ 2 +
- octave4 * persistence ^ 3 +
- ...)
-
-Noise Parameters
-----------------
-Noise Parameters are commonly called `NoiseParams`.
-
-### `offset`
-After the multiplication by `scale` this is added to the result and is the final
-step in creating the noise value.
-Can be positive or negative.
-
-### `scale`
-Once all octaves have been combined, the result is multiplied by this.
-Can be positive or negative.
-
-### `spread`
-For octave1, this is roughly the change of input value needed for a very large
-variation in the noise value generated by octave1. It is almost like a
-'wavelength' for the wavy noise variation.
-Each additional octave has a 'wavelength' that is smaller than the previous
-octave, to create finer detail. `spread` will therefore roughly be the typical
-size of the largest structures in the final noise variation.
-
-`spread` is a vector with values for x, y, z to allow the noise variation to be
-stretched or compressed in the desired axes.
-Values are positive numbers.
-
-### `seed`
-This is a whole number that determines the entire pattern of the noise
-variation. Altering it enables different noise patterns to be created.
-With other parameters equal, different seeds produce different noise patterns
-and identical seeds produce identical noise patterns.
-
-For this parameter you can randomly choose any whole number. Usually it is
-preferable for this to be different from other seeds, but sometimes it is useful
-to be able to create identical noise patterns.
-
-When used in mapgen this is actually a 'seed offset', it is added to the
-'world seed' to create the seed used by the noise, to ensure the noise has a
-different pattern in different worlds.
-
-### `octaves`
-The number of simple noise generators that are combined.
-A whole number, 1 or more.
-Each additional octave adds finer detail to the noise but also increases the
-noise calculation load.
-3 is a typical minimum for a high quality, complex and natural-looking noise
-variation. 1 octave has a slight 'gridlike' appearence.
-
-Choose the number of octaves according to the `spread` and `lacunarity`, and the
-size of the finest detail you require. For example:
-if `spread` is 512 nodes, `lacunarity` is 2.0 and finest detail required is 16
-nodes, octaves will be 6 because the 'wavelengths' of the octaves will be
-512, 256, 128, 64, 32, 16 nodes.
-Warning: If the 'wavelength' of any octave falls below 1 an error will occur.
-
-### `persistence`
-Each additional octave has an amplitude that is the amplitude of the previous
-octave multiplied by `persistence`, to reduce the amplitude of finer details,
-as is often helpful and natural to do so.
-Since this controls the balance of fine detail to large-scale detail
-`persistence` can be thought of as the 'roughness' of the noise.
-
-A positive or negative non-zero number, often between 0.3 and 1.0.
-A common medium value is 0.5, such that each octave has half the amplitude of
-the previous octave.
-This may need to be tuned when altering `lacunarity`; when doing so consider
-that a common medium value is 1 / lacunarity.
-
-### `lacunarity`
-Each additional octave has a 'wavelength' that is the 'wavelength' of the
-previous octave multiplied by 1 / lacunarity, to create finer detail.
-'lacunarity' is often 2.0 so 'wavelength' often halves per octave.
-
-A positive number no smaller than 1.0.
-Values below 2.0 create higher quality noise at the expense of requiring more
-octaves to cover a paticular range of 'wavelengths'.
-
-### `flags`
-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.
-
-#### `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 with a slightly gridded
-appearence.
-If no flags are specified (or defaults is), 2D noise is eased and 3D noise is
-not eased.
-Easing a 3D noise significantly increases the noise calculation load, so use
-with restraint.
-
-#### `absvalue`
-The absolute value of each octave's noise variation is used when combining the
-octaves. The final perlin noise variation is created as follows:
-
-noise = offset + scale * (abs(octave1) +
- abs(octave2) * persistence +
- abs(octave3) * persistence ^ 2 +
- abs(octave4) * persistence ^ 3 +
- ...)
-
-###Format example
-For 2D or 3D perlin noise or perlin noise maps:
-
- np_terrain = {
- offset = 0,
- scale = 1,
- spread = {x = 500, y = 500, z = 500},
- seed = 571347,
- octaves = 5,
- persist = 0.63,
- lacunarity = 2.0,
- flags = "defaults, absvalue",
- }
-
-For 2D noise the Z component of `spread` is still defined but is ignored.
-A single noise parameter table can be used for 2D or 3D noise.
-
-Ore types
----------
-These tell in what manner the ore is generated.
-
-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.
-
-### `sheet`
-Creates a sheet of ore in a blob shape according to the 2D perlin noise
-described by `noise_params` and `noise_threshold`. This is essentially an
-improved version of the so-called "stratus" ore seen in some unofficial mods.
-
-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`.
-
-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.
-
-### `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.
-
-### `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
-`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 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,
- lacunarity = 2.0,
- flags = "eased",
- },
- noise_threshold = 1.6
-
-**WARNING**: Use this ore type *very* sparingly since it is ~200x more
-computationally expensive than any other ore.
-
-### `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".
-
-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`.
-
-### `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`.
-
-Decoration types
-----------------
-The varying types of decorations that can be placed.
-
-### `simple`
-Creates a 1 times `H` times 1 column of a specified node (or a random node from
-a list, if a decoration list is specified). Can specify a certain node it must
-spawn next to, such as water or lava, for example. Can also generate a
-decoration of random height between a specified lower and upper bound.
-This type of decoration is intended for placement of grass, flowers, cacti,
-papyri, waterlilies and so on.
-
-### `schematic`
-Copies a box of `MapNodes` from a specified schematic file (or raw description).
-Can specify a probability of a node randomly appearing when placed.
-This decoration type is intended to be used for multi-node sized discrete
-structures, such as trees, cave spikes, rocks, and so on.
-
-
-Schematic specifier
---------------------
-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
- 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)
-
-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).
-* 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.
-
-
-Schematic attributes
---------------------
-See section "Flag Specifier Format".
-
-Currently supported flags: `place_center_x`, `place_center_y`, `place_center_z`,
- `force_placement`.
-
-* `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.
HUD element types
@@ -2651,6 +2311,794 @@ Strings that need to be translated can contain several escapes, preceded by `@`.
`minetest.translate`, but is in translation files.
* `@n` acts as a literal newline as well.
+Perlin noise
+------------
+Perlin noise creates a continuously-varying value depending on the input values.
+Usually in Minetest the input values are either 2D or 3D co-ordinates in nodes.
+The result is used during map generation to create the terrain shape, vary heat
+and humidity to distribute biomes, vary the density of decorations or vary the
+structure of ores.
+
+### Structure of perlin noise
+An 'octave' is a simple noise generator that outputs a value between -1 and 1.
+The smooth wavy noise it generates has a single characteristic scale, almost
+like a 'wavelength', so on its own does not create fine detail.
+Due to this perlin noise combines several octaves to create variation on
+multiple scales. Each additional octave has a smaller 'wavelength' than the
+previous.
+
+This combination results in noise varying very roughly between -2.0 and 2.0 and
+with an average value of 0.0, so `scale` and `offset` are then used to multiply
+and offset the noise variation.
+
+The final perlin noise variation is created as follows:
+
+noise = offset + scale * (octave1 +
+ octave2 * persistence +
+ octave3 * persistence ^ 2 +
+ octave4 * persistence ^ 3 +
+ ...)
+
+Noise Parameters
+----------------
+Noise Parameters are commonly called `NoiseParams`.
+
+### `offset`
+After the multiplication by `scale` this is added to the result and is the final
+step in creating the noise value.
+Can be positive or negative.
+
+### `scale`
+Once all octaves have been combined, the result is multiplied by this.
+Can be positive or negative.
+
+### `spread`
+For octave1, this is roughly the change of input value needed for a very large
+variation in the noise value generated by octave1. It is almost like a
+'wavelength' for the wavy noise variation.
+Each additional octave has a 'wavelength' that is smaller than the previous
+octave, to create finer detail. `spread` will therefore roughly be the typical
+size of the largest structures in the final noise variation.
+
+`spread` is a vector with values for x, y, z to allow the noise variation to be
+stretched or compressed in the desired axes.
+Values are positive numbers.
+
+### `seed`
+This is a whole number that determines the entire pattern of the noise
+variation. Altering it enables different noise patterns to be created.
+With other parameters equal, different seeds produce different noise patterns
+and identical seeds produce identical noise patterns.
+
+For this parameter you can randomly choose any whole number. Usually it is
+preferable for this to be different from other seeds, but sometimes it is useful
+to be able to create identical noise patterns.
+
+When used in mapgen this is actually a 'seed offset', it is added to the
+'world seed' to create the seed used by the noise, to ensure the noise has a
+different pattern in different worlds.
+
+### `octaves`
+The number of simple noise generators that are combined.
+A whole number, 1 or more.
+Each additional octave adds finer detail to the noise but also increases the
+noise calculation load.
+3 is a typical minimum for a high quality, complex and natural-looking noise
+variation. 1 octave has a slight 'gridlike' appearence.
+
+Choose the number of octaves according to the `spread` and `lacunarity`, and the
+size of the finest detail you require. For example:
+if `spread` is 512 nodes, `lacunarity` is 2.0 and finest detail required is 16
+nodes, octaves will be 6 because the 'wavelengths' of the octaves will be
+512, 256, 128, 64, 32, 16 nodes.
+Warning: If the 'wavelength' of any octave falls below 1 an error will occur.
+
+### `persistence`
+Each additional octave has an amplitude that is the amplitude of the previous
+octave multiplied by `persistence`, to reduce the amplitude of finer details,
+as is often helpful and natural to do so.
+Since this controls the balance of fine detail to large-scale detail
+`persistence` can be thought of as the 'roughness' of the noise.
+
+A positive or negative non-zero number, often between 0.3 and 1.0.
+A common medium value is 0.5, such that each octave has half the amplitude of
+the previous octave.
+This may need to be tuned when altering `lacunarity`; when doing so consider
+that a common medium value is 1 / lacunarity.
+
+### `lacunarity`
+Each additional octave has a 'wavelength' that is the 'wavelength' of the
+previous octave multiplied by 1 / lacunarity, to create finer detail.
+'lacunarity' is often 2.0 so 'wavelength' often halves per octave.
+
+A positive number no smaller than 1.0.
+Values below 2.0 create higher quality noise at the expense of requiring more
+octaves to cover a paticular range of 'wavelengths'.
+
+### `flags`
+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.
+
+#### `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 with a slightly gridded
+appearence.
+If no flags are specified (or defaults is), 2D noise is eased and 3D noise is
+not eased.
+Easing a 3D noise significantly increases the noise calculation load, so use
+with restraint.
+
+#### `absvalue`
+The absolute value of each octave's noise variation is used when combining the
+octaves. The final perlin noise variation is created as follows:
+
+noise = offset + scale * (abs(octave1) +
+ abs(octave2) * persistence +
+ abs(octave3) * persistence ^ 2 +
+ abs(octave4) * persistence ^ 3 +
+ ...)
+
+### Format example
+For 2D or 3D perlin noise or perlin noise maps:
+
+ np_terrain = {
+ offset = 0,
+ scale = 1,
+ spread = {x = 500, y = 500, z = 500},
+ seed = 571347,
+ octaves = 5,
+ persist = 0.63,
+ lacunarity = 2.0,
+ flags = "defaults, absvalue",
+ }
+
+For 2D noise the Z component of `spread` is still defined but is ignored.
+A single noise parameter table can be used for 2D or 3D noise.
+
+Ore types
+---------
+These tell in what manner the ore is generated.
+
+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.
+
+### `sheet`
+Creates a sheet of ore in a blob shape according to the 2D perlin noise
+described by `noise_params` and `noise_threshold`. This is essentially an
+improved version of the so-called "stratus" ore seen in some unofficial mods.
+
+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`.
+
+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.
+
+### `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.
+
+### `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
+`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 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,
+ lacunarity = 2.0,
+ flags = "eased",
+ },
+ noise_threshold = 1.6
+
+**WARNING**: Use this ore type *very* sparingly since it is ~200x more
+computationally expensive than any other ore.
+
+### `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".
+
+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`.
+
+### `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`.
+
+Decoration types
+----------------
+The varying types of decorations that can be placed.
+
+### `simple`
+Creates a 1 times `H` times 1 column of a specified node (or a random node from
+a list, if a decoration list is specified). Can specify a certain node it must
+spawn next to, such as water or lava, for example. Can also generate a
+decoration of random height between a specified lower and upper bound.
+This type of decoration is intended for placement of grass, flowers, cacti,
+papyri, waterlilies and so on.
+
+### `schematic`
+Copies a box of `MapNodes` from a specified schematic file (or raw description).
+Can specify a probability of a node randomly appearing when placed.
+This decoration type is intended to be used for multi-node sized discrete
+structures, such as trees, cave spikes, rocks, and so on.
+
+Schematic specifier
+--------------------
+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
+ 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)
+
+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).
+* 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.
+
+Schematic attributes
+--------------------
+See section "Flag Specifier Format".
+
+Currently supported flags: `place_center_x`, `place_center_y`, `place_center_z`,
+ `force_placement`.
+
+* `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.
+
+Lua Voxel Manipulator
+---------------------
+### 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 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()`.
+
+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.
+
+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.
+
+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.
+
+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.
+
+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
+Let
+ `Nx = p2.X - p1.X + 1`,
+ `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`.
+
+Positions offset from p1 are present in the array with the format of:
+
+```
+[
+ (0, 0, 0), (1, 0, 0), (2, 0, 0), ... (Nx, 0, 0),
+ (0, 1, 0), (1, 1, 0), (2, 1, 0), ... (Nx, 1, 0),
+ ...
+ (0, Ny, 0), (1, Ny, 0), (2, Ny, 0), ... (Nx, Ny, 0),
+ (0, 0, 1), (1, 0, 1), (2, 0, 1), ... (Nx, 0, 1),
+ ...
+ (0, Ny, 2), (1, Ny, 2), (2, Ny, 2), ... (Nx, Ny, 2),
+ ...
+ (0, Ny, Nz), (1, Ny, Nz), (2, Ny, Nz), ... (Nx, Ny, Nz)
+]
+```
+
+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.
+
+#### 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.
+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
+
+#### 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:
+ `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()`.
+
+#### 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.
+
+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 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.
+
+### Methods
+* `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.
+ * 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
+ all modified blocks with `minetest.fix_light()` as soon as possible.
+ Keep in mind that modifying the map where light is incorrect can cause
+ 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.
+ * 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.
+* `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.
+ * `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.
+* `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).
+ * `light = day + (night * 16)`
+* `set_light_data(light_data)`: Sets the `param1` (light) contents of each node
+ 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.
+* `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.
+* `get_emerged_area()`: Returns actual emerged minimum and maximum positions.
+
+### `VoxelArea`
+A helper class for voxel areas.
+It can be created via `VoxelArea:new{MinEdge=pmin, MaxEdge=pmax}`.
+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`.
+ * `x`, `y` and `z` must be integers to avoid an incorrect index result.
+ * The position (x, y, z) is not checked for being inside the area volume,
+ being outside can cause an incorrect index result.
+ * Useful for things like `VoxelManip`, raw Schematic specifiers,
+ `PerlinNoiseMap:get2d`/`3dMap`, and so on.
+* `indexp(p)`: same functionality as `index(x, y, z)` but takes a vector.
+ * As with `index(x, y, z)`, the components of `p` must be integers, and `p`
+ is not checked for being inside the area volume.
+* `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]]]`.
+* `iterp(minp, maxp)`: same as above, except takes a vector
+
+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.
+
+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.
+
+### `heightmap`
+Returns an array containing the y coordinates of the ground levels of nodes in
+the most recently generated chunk by the current mapgen.
+
+### `biomemap`
+Returns an array containing the biome IDs of nodes in the most recently
+generated chunk by the current mapgen.
+
+### `heatmap`
+Returns an array containing the temperature values of nodes in the most
+recently generated chunk by the current mapgen.
+
+### `humiditymap`
+Returns an array containing the humidity values of nodes in the most recently
+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 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:
+
+* `dungeon`
+* `temple`
+* `cave_begin`
+* `cave_end`
+* `large_cave_begin`
+* `large_cave_end`
+* `decoration`
+
+Decorations have a key in the format of `"decoration#id"`, where `id` is the
+numeric unique decoration ID.
+
+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.
+ * The original prototype stuff is visible directly via a metatable
+* Callbacks:
+ * `on_activate(self, staticdata, dtime_s)`
+ * Called when the object is instantiated.
+ * `dtime_s` is the time passed since the object was unloaded, which can
+ 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`.
+ * `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)`
+ * Called when the object dies.
+ * `killer`: an `ObjectRef` (can be `nil`)
+ * `on_rightclick(self, clicker)`
+ * `on_attach_child(self, child)`
+ * `child`: an `ObjectRef` of the child that attaches
+ * `on_detach_child(self, child)`
+ * `child`: an `ObjectRef` of the child that detaches
+ * `on_detach(self, parent)`
+ * `parent`: an `ObjectRef` (can be `nil`) from where it got detached
+ * This happens before the parent object is removed from the world
+ * `get_staticdata(self)`
+ * Should return a string that will be passed to `on_activate` when
+ the object is instantiated the next time.
+
+L-system trees
+--------------
+
+### Tree definition
+
+ treedef={
+ axiom, --string initial tree axiom
+ rules_a, --string rules set A
+ rules_b, --string rules set B
+ rules_c, --string rules set C
+ rules_d, --string rules set D
+ trunk, --string trunk node name
+ leaves, --string leaves node name
+ leaves2, --string secondary leaves node name
+ leaves2_chance,--num chance (0-100) to replace leaves with leaves2
+ angle, --num angle in deg
+ iterations, --num max # of iterations, usually 2 -5
+ random_level, --num factor to lower nr of iterations, usually 0 - 3
+ trunk_type, --string single/double/crossed) type of trunk: 1 node,
+ -- 2x2 nodes or 3x3 in cross shape
+ thin_branches, --boolean true -> use thin (1 node) branches
+ fruit, --string fruit node name
+ fruit_chance, --num chance (0-100) to replace leaves with fruit node
+ seed, --num random seed, if no seed is provided, the engine
+ will create one.
+ }
+
+### Key for Special L-System Symbols used in Axioms
+
+* `G`: move forward one unit with the pen up
+* `F`: move forward one unit with the pen down drawing trunks and branches
+* `f`: move forward one unit with the pen down drawing leaves (100% chance)
+* `T`: move forward one unit with the pen down drawing trunks only
+* `R`: move forward one unit with the pen down placing fruit
+* `A`: replace with rules set A
+* `B`: replace with rules set B
+* `C`: replace with rules set C
+* `D`: replace with rules set D
+* `a`: replace with rules set A, chance 90%
+* `b`: replace with rules set B, chance 80%
+* `c`: replace with rules set C, chance 70%
+* `d`: replace with rules set D, chance 60%
+* `+`: yaw the turtle right by `angle` parameter
+* `-`: yaw the turtle left by `angle` parameter
+* `&`: pitch the turtle down by `angle` parameter
+* `^`: pitch the turtle up by `angle` parameter
+* `/`: roll the turtle to the right by `angle` parameter
+* `*`: roll the turtle to the left by `angle` parameter
+* `[`: save in stack current state info
+* `]`: recover from stack state info
+
+### Example
+Spawn a small apple tree:
+
+ pos = {x=230,y=20,z=4}
+ apple_tree={
+ axiom="FFFFFAFFBF",
+ rules_a="[&&&FFFFF&&FFFF][&&&++++FFFFF&&FFFF][&&&----FFFFF&&FFFF]",
+ rules_b="[&&&++FFFFF&&FFFF][&&&--FFFFF&&FFFF][&&&------FFFFF&&FFFF]",
+ trunk="default:tree",
+ leaves="default:leaves",
+ angle=30,
+ iterations=2,
+ random_level=0,
+ trunk_type="single",
+ thin_branches=true,
+ fruit_chance=10,
+ fruit="default:apple"
+ }
+ minetest.spawn_tree(pos,apple_tree)
+
+
`minetest` namespace reference
------------------------------
@@ -3898,25 +4346,159 @@ These functions return the leftover itemstack.
* `minetest.registered_decorations`
* List of registered decoration definitions.
+
Class reference
---------------
-### ModChannel
+### `AreaStore`
+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.
-An interface to use mod channels on client and server
+#### 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.
+ 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_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.
+ Only needed for efficiency, and only some implementations profit.
+* `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.
+ * `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
+ }
+* `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.
+
+### `InvRef`
+An `InvRef` is a reference to an inventory.
#### 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.
+* `is_empty(listname)`: return `true` if list is empty
+* `get_size(listname)`: get size of a list
+* `set_size(listname, size)`: set size of a list
+ * returns `false` on error (e.g. invalid `listname` or `size`)
+* `get_width(listname)`: get width of a list
+* `set_width(listname, width)`: set width of list; currently used for crafting
+* `get_stack(listname, i)`: get a copy of stack index `i` in list
+* `set_stack(listname, i, stack)`: copy `stack` to index `i` in list
+* `get_list(listname)`: return full list
+* `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`.
+* `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)`.
+ * returns `{type="undefined"}` in case location is not known
+
+### `ItemStack`
+An `ItemStack` is a stack of items.
+
+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 a boolean indicating whether the item was
+ cleared.
+* `get_count()`: Returns number of items on the 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,
+ 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
+ * `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)`: 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`
+
+### `ItemStackMetaRef`
+ItemStack metadata: reference extra data and functionality stored in a stack.
+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.
### `MetaDataRef`
See `StorageRef`, `NodeMetaRef`, `ItemStackMetaRef`, and `PlayerMetaRef`.
@@ -3941,6 +4523,22 @@ See `StorageRef`, `NodeMetaRef`, `ItemStackMetaRef`, and `PlayerMetaRef`.
* `equals(other)`
* returns `true` if this metadata has the same key-value pairs as `other`
+### 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.
+
### `NodeMetaRef`
Node metadata: reference extra data and functionality stored in a node.
Can be obtained via `minetest.get_meta(pos)`.
@@ -3954,33 +4552,6 @@ Can be obtained via `minetest.get_meta(pos)`.
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.
-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.
-Can be obtained via `minetest.get_mod_storage()` during load time.
-
-#### Methods
-* All methods in MetaDataRef
-
-### `PlayerMetaRef`
-Player metadata.
-Uses the same method of storage as the deprecated player attribute API, so
-data there will also be in player meta.
-Can be obtained using `player:get_meta()`.
-
-#### Methods
-* All methods in MetaDataRef
-
### `NodeTimerRef`
Node Timers: a high resolution persistent per-node timer.
Can be gotten via `minetest.get_node_timer(pos)`.
@@ -4244,157 +4815,6 @@ This is basically a reference to a C++ `ServerActiveObject`
* in third person view (max. values `{x=-10/10,y=-10,15,z=-5/5}`)
* `get_eye_offset()`: returns `offset_first` and `offset_third`
-### `InvRef`
-An `InvRef` is a reference to an inventory.
-
-#### Methods
-* `is_empty(listname)`: return `true` if list is empty
-* `get_size(listname)`: get size of a list
-* `set_size(listname, size)`: set size of a list
- * returns `false` on error (e.g. invalid `listname` or `size`)
-* `get_width(listname)`: get width of a list
-* `set_width(listname, width)`: set width of list; currently used for crafting
-* `get_stack(listname, i)`: get a copy of stack index `i` in list
-* `set_stack(listname, i, stack)`: copy `stack` to index `i` in list
-* `get_list(listname)`: return full list
-* `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`.
-* `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)`.
- * 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.
-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.
-
-#### 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.
- 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_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.
- Only needed for efficiency, and only some implementations profit.
-* `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.
- * `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
- }
-* `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.
-
-### `ItemStack`
-An `ItemStack` is a stack of items.
-
-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 a boolean indicating whether the item was
- cleared.
-* `get_count()`: Returns number of items on the 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,
- 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
- * `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)`: 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.
-Uses a well-known LCG algorithm introduced by K&R.
-
-It can be created via `PseudoRandom(seed)`.
-
-#### Methods
-* `next()`: return next integer random number [`0`...`32767`]
-* `next(min, max)`: return next integer random number [`min`...`max`]
- * `((max - min) == 32767) or ((max-min) <= 6553))` must be true
- due to the simple implementation making bad distribution otherwise.
-
### `PcgRandom`
A 32-bit pseudorandom number generator.
Uses PCG32, an algorithm of the permuted congruential generator family,
@@ -4412,16 +4832,6 @@ It can be created via `PcgRandom(seed)` or `PcgRandom(seed, sequence)`.
* `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 found on the system.
-
-#### Methods
-* `next_bytes([count])`: return next `count` (default 1, capped at 2048) many
- random bytes, as a string.
-
### `PerlinNoise`
A perlin noise generator.
It can be created via `PerlinNoise(seed, octaves, persistence, scale)`
@@ -4473,288 +4883,56 @@ table.
`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 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()`.
-
-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.
-
-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.
-
-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.
-
-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.
-
-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
-Let
- `Nx = p2.X - p1.X + 1`,
- `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`.
-
-Positions offset from p1 are present in the array with the format of:
-
-```
-[
- (0, 0, 0), (1, 0, 0), (2, 0, 0), ... (Nx, 0, 0),
- (0, 1, 0), (1, 1, 0), (2, 1, 0), ... (Nx, 1, 0),
- ...
- (0, Ny, 0), (1, Ny, 0), (2, Ny, 0), ... (Nx, Ny, 0),
- (0, 0, 1), (1, 0, 1), (2, 0, 1), ... (Nx, 0, 1),
- ...
- (0, Ny, 2), (1, Ny, 2), (2, Ny, 2), ... (Nx, Ny, 2),
- ...
- (0, Ny, Nz), (1, Ny, Nz), (2, Ny, Nz), ... (Nx, Ny, Nz)
-]
-```
-
-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.
-
-##### 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.
-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:
+### `PlayerMetaRef`
+Player metadata.
+Uses the same method of storage as the deprecated player attribute API, so
+data there will also be in player meta.
+Can be obtained using `player:get_meta()`.
-* `minetest.CONTENT_UNKNOWN`: ID for "unknown" nodes
-* `minetest.CONTENT_AIR`: ID for "air" nodes
-* `minetest.CONTENT_IGNORE`: ID for "ignore" nodes
+#### Methods
+* All methods in MetaDataRef
-##### 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:
+### `PseudoRandom`
+A 16-bit pseudorandom number generator.
+Uses a well-known LCG algorithm introduced by K&R.
-* 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()`.
+It can be created via `PseudoRandom(seed)`.
-##### 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.
+#### Methods
+* `next()`: return next integer random number [`0`...`32767`]
+* `next(min, max)`: return next integer random number [`min`...`max`]
+ * `((max - min) == 32767) or ((max-min) <= 6553))` must be true
+ due to the simple implementation making bad distribution otherwise.
-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.
+### `Raycast`
+A raycast on the map. It works with selection boxes.
+Can be used as an iterator in a for loop.
-`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.
+The map is loaded as the ray advances. If the
+map is modified after the `Raycast` is created,
+the changes may or may not have an effect on
+the object.
-##### 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.
+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.
#### Methods
-* `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.
- * 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
- all modified blocks with `minetest.fix_light()` as soon as possible.
- Keep in mind that modifying the map where light is incorrect can cause
- 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.
- * 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.
-* `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.
- * `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.
-* `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).
- * `light = day + (night * 16)`
-* `set_light_data(light_data)`: Sets the `param1` (light) contents of each node
- 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.
-* `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.
-* `get_emerged_area()`: Returns actual emerged minimum and maximum positions.
+* `next()`: returns a `pointed_thing`
+ * Returns the next thing pointed by the ray or nil.
-### `VoxelArea`
-A helper class for voxel areas.
-It can be created via `VoxelArea:new{MinEdge=pmin, MaxEdge=pmax}`.
-The coordinates are *inclusive*, like most other things in Minetest.
+### `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 found on the system.
#### 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`.
- * `x`, `y` and `z` must be integers to avoid an incorrect index result.
- * The position (x, y, z) is not checked for being inside the area volume,
- being outside can cause an incorrect index result.
- * Useful for things like `VoxelManip`, raw Schematic specifiers,
- `PerlinNoiseMap:get2d`/`3dMap`, and so on.
-* `indexp(p)`: same functionality as `index(x, y, z)` but takes a vector.
- * As with `index(x, y, z)`, the components of `p` must be integers, and `p`
- is not checked for being inside the area volume.
-* `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]]]`.
-* `iterp(minp, maxp)`: same as above, except takes a vector
+* `next_bytes([count])`: return next `count` (default 1, capped at 2048) many
+ random bytes, as a string.
### `Settings`
An interface to read config files in the format of `minetest.conf`.
@@ -4783,190 +4961,13 @@ It can be created via `Settings(filename)`.
* Writes changes to file.
* `to_table()`: returns `{[key1]=value1,...}`
-### `Raycast`
-A raycast on the map. It works with selection boxes.
-Can be used as an iterator in a for loop.
-
-The map is loaded as the ray advances. If the
-map is modified after the `Raycast` is created,
-the changes may or may not have an effect on
-the object.
-
-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.
+### `StorageRef`
+Mod metadata: per mod metadata, saved automatically.
+Can be obtained via `minetest.get_mod_storage()` during load time.
#### Methods
-* `next()`: returns a `pointed_thing`
- * Returns the next thing pointed by the ray or nil.
-
-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.
-
-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.
-
-### `heightmap`
-Returns an array containing the y coordinates of the ground levels of nodes in
-the most recently generated chunk by the current mapgen.
-
-### `biomemap`
-Returns an array containing the biome IDs of nodes in the most recently
-generated chunk by the current mapgen.
-
-### `heatmap`
-Returns an array containing the temperature values of nodes in the most
-recently generated chunk by the current mapgen.
-
-### `humiditymap`
-Returns an array containing the humidity values of nodes in the most recently
-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 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:
-
-* `dungeon`
-* `temple`
-* `cave_begin`
-* `cave_end`
-* `large_cave_begin`
-* `large_cave_end`
-* `decoration`
-
-Decorations have a key in the format of `"decoration#id"`, where `id` is the
-numeric unique decoration ID.
-
-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.
- * The original prototype stuff is visible directly via a metatable
-* Callbacks:
- * `on_activate(self, staticdata, dtime_s)`
- * Called when the object is instantiated.
- * `dtime_s` is the time passed since the object was unloaded, which can
- 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`.
- * `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)`
- * Called when the object dies.
- * `killer`: an `ObjectRef` (can be `nil`)
- * `on_rightclick(self, clicker)`
- * `on_attach_child(self, child)`
- * `child`: an `ObjectRef` of the child that attaches
- * `on_detach_child(self, child)`
- * `child`: an `ObjectRef` of the child that detaches
- * `on_detach(self, parent)`
- * `parent`: an `ObjectRef` (can be `nil`) from where it got detached
- * This happens before the parent object is removed from the world
- * `get_staticdata(self)`
- * Should return a string that will be passed to `on_activate` when
- the object is instantiated the next time.
-
-L-system trees
---------------
-
-### Tree definition
-
- treedef={
- axiom, --string initial tree axiom
- rules_a, --string rules set A
- rules_b, --string rules set B
- rules_c, --string rules set C
- rules_d, --string rules set D
- trunk, --string trunk node name
- leaves, --string leaves node name
- leaves2, --string secondary leaves node name
- leaves2_chance,--num chance (0-100) to replace leaves with leaves2
- angle, --num angle in deg
- iterations, --num max # of iterations, usually 2 -5
- random_level, --num factor to lower nr of iterations, usually 0 - 3
- trunk_type, --string single/double/crossed) type of trunk: 1 node,
- -- 2x2 nodes or 3x3 in cross shape
- thin_branches, --boolean true -> use thin (1 node) branches
- fruit, --string fruit node name
- fruit_chance, --num chance (0-100) to replace leaves with fruit node
- seed, --num random seed, if no seed is provided, the engine
- will create one.
- }
-
-### Key for Special L-System Symbols used in Axioms
-
-* `G`: move forward one unit with the pen up
-* `F`: move forward one unit with the pen down drawing trunks and branches
-* `f`: move forward one unit with the pen down drawing leaves (100% chance)
-* `T`: move forward one unit with the pen down drawing trunks only
-* `R`: move forward one unit with the pen down placing fruit
-* `A`: replace with rules set A
-* `B`: replace with rules set B
-* `C`: replace with rules set C
-* `D`: replace with rules set D
-* `a`: replace with rules set A, chance 90%
-* `b`: replace with rules set B, chance 80%
-* `c`: replace with rules set C, chance 70%
-* `d`: replace with rules set D, chance 60%
-* `+`: yaw the turtle right by `angle` parameter
-* `-`: yaw the turtle left by `angle` parameter
-* `&`: pitch the turtle down by `angle` parameter
-* `^`: pitch the turtle up by `angle` parameter
-* `/`: roll the turtle to the right by `angle` parameter
-* `*`: roll the turtle to the left by `angle` parameter
-* `[`: save in stack current state info
-* `]`: recover from stack state info
-
-### Example
-Spawn a small apple tree:
+* All methods in MetaDataRef
- pos = {x=230,y=20,z=4}
- apple_tree={
- axiom="FFFFFAFFBF",
- rules_a="[&&&FFFFF&&FFFF][&&&++++FFFFF&&FFFF][&&&----FFFFF&&FFFF]",
- rules_b="[&&&++FFFFF&&FFFF][&&&--FFFFF&&FFFF][&&&------FFFFF&&FFFF]",
- trunk="default:tree",
- leaves="default:leaves",
- angle=30,
- iterations=2,
- random_level=0,
- trunk_type="single",
- thin_branches=true,
- fruit_chance=10,
- fruit="default:apple"
- }
- minetest.spawn_tree(pos,apple_tree)
Definition tables
-----------------