+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.
+
+
+
+
+Ores
+====
+
+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.
+
+
+
+
+Schematics
+==========
+
+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 field)
+* The `yslice_prob` field is a table of {ypos, prob} slice tables. A slice table
+ sets the probability of a particular horizontal slice of the schematic being
+ placed. (optional field)
+ `ypos` = 0 for the lowest horizontal slice of a schematic.
+ The default of `prob` is 255.
+* The `data` field is a flat table of MapNode tables making up the schematic,
+ in the order of `[z [y [x]]]`. (required field)
+ 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. For almost all uses these should be left out
+ or nil to use the default.
+ * `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, damage)`
+ * 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.
+ * `damage`: damage that will be done to entity.
+* `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
+==============================
+
+Utilities
+---------
+
+* `minetest.get_current_modname()`: returns the currently loading mod's name,
+ when loading a mod.
+* `minetest.get_modpath(modname)`: returns e.g.
+ `"/home/user/.minetest/usermods/modname"`.
+ * Useful for loading additional `.lua` modules or static data from mod
+* `minetest.get_modnames()`: returns a list of installed mods
+ * Return a list of installed mods, sorted alphabetically
+* `minetest.get_worldpath()`: returns e.g. `"/home/user/.minetest/world"`
+ * Useful for storing custom data
+* `minetest.is_singleplayer()`
+* `minetest.features`: Table containing API feature flags
+
+ {
+ glasslike_framed = true, -- 0.4.7
+ nodebox_as_selectionbox = true, -- 0.4.7
+ get_all_craft_recipes_works = true, -- 0.4.7
+ -- The transparency channel of textures can optionally be used on
+ -- nodes (0.4.7)
+ use_texture_alpha = true,
+ -- Tree and grass ABMs are no longer done from C++ (0.4.8)
+ no_legacy_abms = true,
+ -- Texture grouping is possible using parentheses (0.4.11)
+ texture_names_parens = true,
+ -- Unique Area ID for AreaStore:insert_area (0.4.14)
+ area_store_custom_ids = true,
+ -- add_entity supports passing initial staticdata to on_activate
+ -- (0.4.16)
+ add_entity_with_staticdata = true,
+ -- Chat messages are no longer predicted (0.4.16)
+ no_chat_message_prediction = true,
+ -- The transparency channel of textures can optionally be used on
+ -- objects (ie: players and lua entities) (5.0.0)
+ object_use_texture_alpha = true,
+ -- Object selectionbox is settable independently from collisionbox
+ -- (5.0.0)
+ object_independent_selectionbox = true,
+ -- Specifies whether binary data can be uploaded or downloaded using
+ -- the HTTP API (5.1.0)
+ httpfetch_binary_data = true,
+ }
+
+* `minetest.has_feature(arg)`: returns `boolean, missing_features`
+ * `arg`: string or table in format `{foo=true, bar=true}`
+ * `missing_features`: `{foo=true, bar=true}`
+* `minetest.get_player_information(player_name)`: Table containing information
+ about a player. Example return value:
+
+ {
+ address = "127.0.0.1", -- IP address of client
+ ip_version = 4, -- IPv4 / IPv6
+ min_rtt = 0.01, -- minimum round trip time
+ max_rtt = 0.2, -- maximum round trip time
+ avg_rtt = 0.02, -- average round trip time
+ min_jitter = 0.01, -- minimum packet time jitter
+ max_jitter = 0.5, -- maximum packet time jitter
+ avg_jitter = 0.03, -- average packet time jitter
+ connection_uptime = 200, -- seconds since client connected
+ protocol_version = 32, -- protocol version used by client
+ -- following information is available on debug build only!!!
+ -- DO NOT USE IN MODS
+ --ser_vers = 26, -- serialization version used by client
+ --major = 0, -- major version number
+ --minor = 4, -- minor version number
+ --patch = 10, -- patch version number
+ --vers_string = "0.4.9-git", -- full version string
+ --state = "Active" -- current client state
+ }
+
+* `minetest.mkdir(path)`: returns success.
+ * Creates a directory specified by `path`, creating parent directories
+ if they don't exist.
+* `minetest.get_dir_list(path, [is_dir])`: returns list of entry names
+ * is_dir is one of:
+ * nil: return all entries,
+ * true: return only subdirectory names, or
+ * false: return only file names.
+* `minetest.safe_file_write(path, content)`: returns boolean indicating success
+ * Replaces contents of file at path with new contents in a safe (atomic)
+ way. Use this instead of below code when writing e.g. database files:
+ `local f = io.open(path, "wb"); f:write(content); f:close()`
+* `minetest.get_version()`: returns a table containing components of the
+ engine version. Components:
+ * `project`: Name of the project, eg, "Minetest"
+ * `string`: Simple version, eg, "1.2.3-dev"
+ * `hash`: Full git version (only set if available),
+ eg, "1.2.3-dev-01234567-dirty".
+ Use this for informational purposes only. The information in the returned
+ table does not represent the capabilities of the engine, nor is it
+ reliable or verifiable. Compatible forks will have a different name and
+ version entirely. To check for the presence of engine features, test
+ whether the functions exported by the wanted features exist. For example:
+ `if minetest.check_for_falling then ... end`.
+* `minetest.sha1(data, [raw])`: returns the sha1 hash of data
+ * `data`: string of data to hash
+ * `raw`: return raw bytes instead of hex digits, default: false
+
+Logging
+-------
+
+* `minetest.debug(...)`
+ * Equivalent to `minetest.log(table.concat({...}, "\t"))`
+* `minetest.log([level,] text)`
+ * `level` is one of `"none"`, `"error"`, `"warning"`, `"action"`,
+ `"info"`, or `"verbose"`. Default is `"none"`.
+
+Registration functions
+----------------------
+
+Call these functions only at load time!
+
+### Environment
+
+* `minetest.register_node(name, node definition)`
+* `minetest.register_craftitem(name, item definition)`
+* `minetest.register_tool(name, item definition)`
+* `minetest.override_item(name, redefinition)`
+ * Overrides fields of an item registered with register_node/tool/craftitem.
+ * Note: Item must already be defined, (opt)depend on the mod defining it.
+ * Example: `minetest.override_item("default:mese",
+ {light_source=minetest.LIGHT_MAX})`
+* `minetest.unregister_item(name)`
+ * Unregisters the item from the engine, and deletes the entry with key
+ `name` from `minetest.registered_items` and from the associated item table
+ according to its nature: `minetest.registered_nodes`, etc.
+* `minetest.register_entity(name, entity definition)`
+* `minetest.register_abm(abm definition)`
+* `minetest.register_lbm(lbm definition)`
+* `minetest.register_alias(alias, original_name)`
+ * Also use this to set the 'mapgen aliases' needed in a game for the core
+ mapgens. See [Mapgen aliases] section above.
+* `minetest.register_alias_force(alias, original_name)`
+* `minetest.register_ore(ore definition)`
+ * Returns an integer uniquely identifying the registered ore on success.
+ * The order of ore registrations determines the order of ore generation.
+* `minetest.register_biome(biome definition)`
+ * Returns an integer uniquely identifying the registered biome on success.
+* `minetest.unregister_biome(name)`
+ * Unregisters the biome from the engine, and deletes the entry with key
+ `name` from `minetest.registered_biomes`.
+* `minetest.register_decoration(decoration definition)`
+ * Returns an integer uniquely identifying the registered decoration on
+ success.
+ * The order of decoration registrations determines the order of decoration
+ generation.
+* `minetest.register_schematic(schematic definition)`
+ * Returns an integer uniquely identifying the registered schematic on
+ success.
+ * If the schematic is loaded from a file, the `name` field is set to the
+ filename.
+ * If the function is called when loading the mod, and `name` is a relative
+ path, then the current mod path will be prepended to the schematic
+ filename.
+* `minetest.clear_registered_ores()`
+ * Clears all ores currently registered.
+* `minetest.clear_registered_biomes()`
+ * Clears all biomes currently registered.
+* `minetest.clear_registered_decorations()`
+ * Clears all decorations currently registered.
+* `minetest.clear_registered_schematics()`
+ * Clears all schematics currently registered.
+
+### Gameplay
+
+* `minetest.register_craft(recipe)`
+ * Check recipe table syntax for different types below.
+* `minetest.clear_craft(recipe)`
+ * Will erase existing craft based either on output item or on input recipe.
+ * Specify either output or input only. If you specify both, input will be
+ ignored. For input use the same recipe table syntax as for
+ `minetest.register_craft(recipe)`. For output specify only the item,
+ without a quantity.
+ * Returns false if no erase candidate could be found, otherwise returns true.
+ * **Warning**! The type field ("shaped", "cooking" or any other) will be
+ ignored if the recipe contains output. Erasing is then done independently
+ from the crafting method.
+* `minetest.register_chatcommand(cmd, chatcommand definition)`
+* `minetest.override_chatcommand(name, redefinition)`
+ * Overrides fields of a chatcommand registered with `register_chatcommand`.
+* `minetest.unregister_chatcommand(name)`
+ * Unregisters a chatcommands registered with `register_chatcommand`.
+* `minetest.register_privilege(name, definition)`
+ * `definition` can be a description or a definition table (see [Privilege
+ definition]).
+ * If it is a description, the priv will be granted to singleplayer and admin
+ by default.
+ * To allow players with `basic_privs` to grant, see the `basic_privs`
+ minetest.conf setting.