diff options
| -rw-r--r-- | doc/lua_api.txt | 1985 |
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 ----------------- |