Lua_api.txt: Re-order some sections. Alphabeticise class reference (#7487)

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
 -----------------