-Minetest Lua Modding API Reference 0.4.11
+Minetest Lua Modding API Reference 0.4.12
=========================================
* More information at <http://www.minetest.net/>
* Developer Wiki: <http://dev.minetest.net/>
Programming in Lua
------------------
-If you have any difficulty in understanding this, please read [Programming in Lua](http://www.lua.org/pil/).
+If you have any difficulty in understanding this, please read
+[Programming in Lua](http://www.lua.org/pil/).
Startup
-------
The game directory can contain the file minetest.conf, which will be used
to set default settings when running the particular game.
+### Menu images
+
+Games can provide custom main menu images. They are put inside a `menu` directory inside the game directory.
+
+The images are named `$identifier.png`, where `$identifier` is one of `overlay,background,footer,header`.
+If you want to specify multiple images for one identifier, add additional images named like `$identifier.$n.png`, with an ascending number $n starting with 1,
+and a random image will be chosen from the provided ones.
+
+
Mod load path
-------------
Generic:
The mask is applied using binary AND.
-#### `[colorize:<color>`
+#### `[colorize:<color>:<ratio>`
Colorize the textures with the given color.
`<color>` is specified as a `ColorString`.
+`<ratio>` is an int ranging from 0 to 255, and specifies how much of the
+color to apply. If ommitted, the alpha will be used.
Sounds
------
* `minetest.register_craftitem(name, item definition)`
* added to `minetest.registered_items[name]`
+* `minetest.register_biome(biome definition)`
+ * returns an integer uniquely identifying the registered biome
+ * added to `minetest.registered_biome` with the key of `biome.name`
+ * if `biome.name` is nil, the key is the returned ID
+
+* `minetest.register_ore(ore definition)`
+ * returns an integer uniquely identifying the registered ore
+ * added to `minetest.registered_ores` with the key of `ore.name`
+ * if `ore.name` is nil, the key is the returned ID
+
+* `minetest.register_decoration(decoration definition)`
+ * returns an integer uniquely identifying the registered decoration
+ * added to `minetest.registered_decorations` with the key of `decoration.name`
+ * if `decoration.name` is nil, the key is the returned ID
+
+* `minetest.register_schematic(schematic definition)`
+ * returns an integer uniquely identifying the registered schematic
+ * added to `minetest.registered_schematic` with the key of `schematic.name`
+ * if `schematic.name` is nil, the key is the returned ID
+ * if the schematic is loaded from a file, schematic.name is set to the filename
+ * if the function is called when loading the mod, and schematic.name is a relative path,
+ * then the current mod path will be prepended to the schematic filename
+
+* `minetest.clear_registered_biomes()`
+ * clears all biomes currently registered
+
+* `minetest.clear_registered_ores()`
+ * clears all ores currently registered
+
+* `minetest.clear_registered_decorations()`
+ * clears all decorations currently registered
+
+* `minetest.clear_registered_schematics()`
+ * clears all schematics currently registered
+
Note that in some cases you will stumble upon things that are not contained
in these tables (e.g. when a mod has been removed). Always check for
existence before trying to access the fields.
`param1` is reserved for the engine when `paramtype != "none"`:
paramtype = "light"
- ^ The value stores light with and without sun in it's
- upper and lower 4 bits.
+ ^ The value stores light with and without sun in its upper and lower 4 bits
+ respectively. Allows light to propagate from or through the node with
+ light value falling by 1 per node. This is essential for a light source
+ node to spread its light.
`param2` is reserved for the engine when any of these are used:
Meshes
------
If drawtype `mesh` is used, tiles should hold model materials textures.
-Only static meshes are implemented.
+Only static meshes are implemented.
For supported model formats see Irrlicht engine documentation.
Noise Parameters
----------------
-Noise Parameters, or commonly called "`NoiseParams`", define the properties of perlin noise.
+Noise Parameters, or commonly called "`NoiseParams`", define the properties of
+perlin noise.
### `offset`
Offset that the noise is translated by (i.e. added) after calculation.
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.
+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`.
-The relative height of the sheet can be controlled by the same perlin noise as well, by specifying
-a non-zero `scale` parameter in `noise_params`.
+Creates a sheet of ore in a blob shape according to the 2D perlin noise
+described by `noise_params`. The relative height of the sheet can be
+controlled by the same perlin noise as well, by specifying a non-zero
+`scale` parameter in `noise_params`.
-**IMPORTANT**: The noise is not transformed by `offset` or `scale` when comparing against the noise
-threshold, but scale is used to determine relative height.
+**IMPORTANT**: The noise is not transformed by `offset` or `scale` when comparing
+against the noise threshold, but scale is used to determine relative height.
The height of the blob is randomly scattered, with a maximum height of `clust_size`.
`clust_scarcity` and `clust_num_ores` are ignored.
-This is essentially an improved version of the so-called "stratus" ore seen in some unofficial mods.
+This is essentially an improved version of the so-called "stratus" ore seen in
+some unofficial mods.
### `blob`
-Creates a deformed sphere of ore according to 3d perlin noise described by
+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
The default value is `simple`, and is currently the only type supported.
### `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,
-and so on.
+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, 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.
+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 must specify two fields:
-
-* The `size` field is a 3D vector containing the dimensions of the provided schematic.
-* The `data` field is a flat table of MapNodes making up the schematic, in the order of `[z [y [x]]]`.
-
-**Important**: The default value for `param1` in MapNodes here is `255`, which represents "always place".
-
-In the bulk `MapNode` data, `param1`, instead of the typical light values, instead represents the
-probability of that node appearing in the structure.
-
-When passed to `minetest.create_schematic`, probability is an integer value ranging from `0` to `255`:
-
-* A probability value of `0` means that node will never appear (0% chance).
-* A probability value of `255` means the node will always appear (100% chance).
-* If the probability value `p` is greater than `0`, then there is a `(p / 256 * 100)`% chance that node
- will appear when the schematic is placed on the map.
-
-**Important note**: Node aliases cannot be used for a raw schematic provided when registering as a decoration.
+A schematic specifier identifies a schematic by either a filename to a
+Minetest Schematic file (`.mts`) or through raw data supplied through Lua,
+in the form of a table. This table specifies the following fields:
+
+* The `size` field is a 3D vector containing the dimensions of the provided schematic. (required)
+* The `yslice_prob` field is a table of {ypos, prob} which sets the `ypos`th vertical slice
+ of the schematic to have a `prob / 256 * 100` chance of occuring. (default: 255)
+* The `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`.
+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
-----------------
The position field is used for all element types.
-To account for differing resolutions, the position coordinates are the percentage of the screen,
-ranging in value from `0` to `1`.
+To account for differing resolutions, the position coordinates are the percentage
+of the screen, ranging in value from `0` to `1`.
-The name field is not yet used, but should contain a description of what the HUD element represents.
-The direction field is the direction in which something is drawn.
+The name field is not yet used, but should contain a description of what the
+HUD element represents. The direction field is the direction in which something
+is drawn.
-`0` draws from left to right, `1` draws from right to left, `2` draws from top to bottom,
-and `3` draws from bottom to top.
+`0` draws from left to right, `1` draws from right to left, `2` draws from
+top to bottom, and `3` draws from bottom to top.
The `alignment` field specifies how the item will be aligned. It ranges from `-1` to `1`,
with `0` being the center, `-1` is moved to the left/up, and `1` is to the right/down.
Below are the specific uses for fields in each type; fields not listed for that type are ignored.
-**Note**: Future revisions to the HUD API may be incompatible; the HUD API is still in the experimental stages.
+**Note**: Future revisions to the HUD API may be incompatible; the HUD API is still
+in the experimental stages.
### `image`
Displays an image on the HUD.
Flag Specifier Format
---------------------
-Flags using the standardized flag specifier format can be specified in either of two ways, by string or table.
+Flags using the standardized flag specifier format can be specified in either of
+two ways, by string or table.
-The string format is a comma-delimited set of flag names; whitespace and unrecognized flag fields are ignored.
-Specifying a flag in the string sets the flag, and specifying a flag prefixed by the string `"no"` explicitly
+The string format is a comma-delimited set of flag names; whitespace and
+unrecognized flag fields are ignored. Specifying a flag in the string sets the
+flag, and specifying a flag prefixed by the string `"no"` explicitly
clears the flag from whatever the default may be.
-In addition to the standard string flag format, the schematic flags field can also be a table of flag names
-to boolean values representing whether or not the flag is set. Additionally, if a field with the flag name
-prefixed with `"no"` is present, mapped to a boolean of any value, the specified flag is unset.
+In addition to the standard string flag format, the schematic flags field can
+also be a table of flag names to boolean values representing whether or not the
+flag is set. Additionally, if a field with the flag name prefixed with `"no"`
+is present, mapped to a boolean of any value, the specified flag is unset.
E.g. A flag field of value
dropped as an item. If the node is wallmounted the wallmounted direction is
checked.
* `soil`: saplings will grow on nodes in this group
-* `connect_to_raillike`: makes nodes of raillike drawtype connect to
- other group members with same drawtype
+* `connect_to_raillike`: makes nodes of raillike drawtype with same group value
+ connect to each other
### Known damage and digging time defining groups
* `crumbly`: dirt, sand
damage = 0
foreach group in cap.damage_groups:
- damage += cap.damage_groups[group] * limit(actual_interval / cap.full_punch_interval, 0.0, 1.0)
+ damage += cap.damage_groups[group] * limit(actual_interval /
+ cap.full_punch_interval, 0.0, 1.0)
* (object.armor_groups[group] / 100.0)
-- Where object.armor_groups[group] is 0 for inexistent values
return damage
Client predicts damage based on damage groups. Because of this, it is able to
give an immediate response when an entity is damaged or dies; the response is
pre-defined somehow (e.g. by defining a sprite animation) (not implemented;
-TODO).
+TODO).
Currently a smoke puff will appear when an entity dies.
The group `immortal` completely disables normal damage.
entity:on_punch(puncher, time_from_last_punch, tool_capabilities, direction)
-This should never be called directly, because damage is usually not handled by the entity
-itself.
+This should never be called directly, because damage is usually not handled by
+the entity itself.
* `puncher` is the object performing the punch. Can be `nil`. Should never be
accessed unless absolutely required, to encourage interoperability.
print(dump(meta:to_table()))
meta:from_table({
inventory = {
- main = {[1] = "default:dirt", [2] = "", [3] = "", [4] = "", [5] = "", [6] = "",
- [7] = "", [8] = "", [9] = "", [10] = "", [11] = "", [12] = "", [13] = "",
- [14] = "default:cobble", [15] = "", [16] = "", [17] = "", [18] = "",
- [19] = "", [20] = "default:cobble", [21] = "", [22] = "", [23] = "",
- [24] = "", [25] = "", [26] = "", [27] = "", [28] = "", [29] = "", [30] = "",
- [31] = "", [32] = ""}
+ main = {[1] = "default:dirt", [2] = "", [3] = "", [4] = "",
+ [5] = "", [6] = "", [7] = "", [8] = "", [9] = "",
+ [10] = "", [11] = "", [12] = "", [13] = "",
+ [14] = "default:cobble", [15] = "", [16] = "", [17] = "",
+ [18] = "", [19] = "", [20] = "default:cobble", [21] = "",
+ [22] = "", [23] = "", [24] = "", [25] = "", [26] = "",
+ [27] = "", [28] = "", [29] = "", [30] = "", [31] = "",
+ [32] = ""}
},
fields = {
formspec = "size[8,9]list[context;main;0,0;8,4;]list[current_player;main;0,5;8,4;]",
#### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]`
* Show an inventory list
+#### `listring[<inventory location>;<list name>]`
+* Allows to create a ring of inventory lists
+* Shift-clicking on items in one element of the ring
+* will send them to the next inventory list inside the ring
+* The first occurrence of an element inside the ring will
+* determine the inventory where items will be sent to
+
+#### `listring[]`
+* Shorthand for doing `listring[<inventory location>;<list name>]`
+* for the last two inventory lists added by list[...]
+
#### `listcolors[<slot_bg_normal>;<slot_bg_hover>]`
* Sets background color of slots as `ColorString`
* Sets background color of slots on mouse hovering
* Position and size units are inventory slots
* Example for formspec 8x4 in 16x resolution:
image shall be sized 8 times 16px times 4 times 16px
-* If `true` the background is clipped to formspec size (`x` and `y` are used as offset values, `w` and `h` are ignored)
+* If `true` the background is clipped to formspec size
+ (`x` and `y` are used as offset values, `w` and `h` are ignored)
#### `pwdfield[<X>,<Y>;<W>,<H>;<name>;<label>]`
* Textual password style field; will be sent to server when a button is clicked
(e.g. `colorname#08`). For named colors the hexadecimal string representing the alpha
value must (always) be two hexadecimal digits.
+`ColorSpec`
+-----------
+A ColorSpec specifies a 32-bit color. It can be written in either:
+table form, each element ranging from 0..255 (a, if absent, defaults to 255):
+ `colorspec = {a=255, r=0, g=255, b=0}`
+numerical form, the raw integer value of an ARGB8 quad:
+ `colorspec = 0xFF00FF00`
+or string form, a ColorString (defined above):
+ `colorspec = "green"`
+
Vector helpers
--------------
### Utilities
-* `minetest.get_current_modname()`: returns a string
+* `minetest.get_current_modname()`: returns the currently loading mod's name, when we are loading a mod
* `minetest.get_modpath(modname)`: returns e.g. `"/home/user/.minetest/usermods/modname"`
* Useful for loading additional `.lua` modules or static data from mod
* `minetest.get_modnames()`: returns a list of installed mods
* Useful for storing custom data
* `minetest.is_singleplayer()`
* `minetest.features`
- * table containing API feature flags: `{foo=true, bar=true}`
+ * Table containing API feature flags: `{foo=true, bar=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(playername)`
- * table containing information about player peer.
-
-Example of `minetest.get_player_information` 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
-
- -- following information is available on debug build only!!!
- -- DO NOT USE IN MODS
- --ser_vers = 26, -- serialization version used by client
- --prot_vers = 23, -- protocol 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.get_player_information(player_name)`: returns a table containing
+ information about 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
+
+ -- following information is available on debug build only!!!
+ -- DO NOT USE IN MODS
+ --ser_vers = 26, -- serialization version used by client
+ --prot_vers = 23, -- protocol 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.
### Logging
* `minetest.debug(line)`
* Note: Item must already be defined, (opt)depend on the mod defining it.
* Example: `minetest.override_item("default:mese", {light_source=LIGHT_MAX})`
+* `minetest.clear_registered_ores()`
+* `minetest.clear_registered_decorations()`
+
### Global callback registration functions
Call these functions only at load time!
* Called after a new player has been created
* `minetest.register_on_dieplayer(func(ObjectRef))`
* Called when a player dies
+* `minetest.register_on_punchplayer(func(player, hitter, time_from_last_punch, tool_capabilities, dir, damage))`
+ * Called when a player is punched
+ * `player` - ObjectRef - Player that was punched
+ * `hitter` - ObjectRef - Player that hit
+ * `time_from_last_punch`: Meant for disallowing spamming of clicks (can be nil)
+ * `tool_capabilities`: capability table of used tool (can be nil)
+ * `dir`: unit vector of direction of punch. Always defined. Points from
+ the puncher to the punched.
+ * `damage` - number that represents the damage calculated by the engine
+ * should return `true` to prevent the default damage mechanism
+* `minetest.register_on_player_hpchange(func(player, hp_change), modifier)`
+ * Called when the player gets damaged or healed
+ * `player`: ObjectRef of the player
+ * `hp_change`: the amount of change. Negative when it is damage.
+ * `modifier`: when true, the function should return the actual hp_change.
+ Note: modifiers only get a temporary hp_change that can be modified by later modifiers.
+ modifiers can return true as a second argument to stop the execution of further functions.
* `minetest.register_on_respawnplayer(func(ObjectRef))`
* Called when player is to be respawned
* Called _before_ repositioning of player occurs
* `dug_too_fast`
* `minetest.register_on_chat_message(func(name, message))`
* Called always when a player says something
+ * Return `true` to mark the message as handled, which means that it will not be sent to other players
* `minetest.register_on_player_receive_fields(func(player, formname, fields))`
* Called when a button is pressed in player's inventory form
* Newest functions are called first
### Setting-related
* `minetest.setting_set(name, value)`
+ * Setting names can't contain whitespace or any of `="{}#`.
+ * Setting values can't contain the sequence `\n"""`.
+ * Setting names starting with "secure." can't be set.
* `minetest.setting_get(name)`: returns string or `nil`
* `minetest.setting_setbool(name, value)`
+ * See documentation on `setting_set` for restrictions.
* `minetest.setting_getbool(name)`: returns boolean or `nil`
* `minetest.setting_get_pos(name)`: returns position or nil
* `minetest.setting_save()`, returns `nil`, save all settings to config file
* `minetest.punch_node(pos)`
* Punch node with the same effects that a player would cause
+* `minetest.find_nodes_with_meta(pos1, pos2)`
+ * Get a table of positions of nodes that have metadata within a region {pos1, pos2}
* `minetest.get_meta(pos)`
* Get a `NodeMetaRef` at that position
* `minetest.get_node_timer(pos)`
* `minetest.find_node_near(pos, radius, nodenames)`: returns pos or `nil`
* `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
* `minetest.find_nodes_in_area(minp, maxp, nodenames)`: returns a list of positions
+ * returns as second value a table with the count of the individual nodes found
+ * `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
+* `minetest.find_nodes_in_area_under_air(minp, maxp, nodenames)`: returns a list of positions
+ * returned positions are nodes with a node air above
* `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
* `minetest.get_perlin(noiseparams)`
* `minetest.get_perlin(seeddiff, octaves, persistence, scale)`
* `flags` is a flag field with the available flags: `dungeon`, `temple`, `cave_begin`,
`cave_end`, `large_cave_begin`, `large_cave_end`, `decoration`
* The second parameter is a list of IDS of decorations which notification is requested for
+* `get_gen_notify()`: returns a flagstring and a table with the deco_ids
* `minetest.get_mapgen_object(objectname)`
* Return requested mapgen object if available (see "Mapgen objects")
* `minetest.get_mapgen_params()` Returns mapgen parameters, a table containing
`mgname`, `seed`, `chunksize`, `water_level`, and `flags`.
* `minetest.set_mapgen_params(MapgenParams)`
* Set map generation parameters
- * Function cannot be called after the registration period; only initialization and `on_mapgen_init`
- * Takes a table as an argument with the fields `mgname`, `seed`, `water_level`, and `flags`.
+ * Function cannot be called after the registration period; only initialization
+ and `on_mapgen_init`
+ * Takes a table as an argument with the fields `mgname`, `seed`, `water_level`,
+ and `flags`.
* Leave field unset to leave that parameter unchanged
- * `flags` contains a comma-delimited string of flags to set, or if the prefix `"no"` is attached, clears instead.
+ * `flags` contains a comma-delimited string of flags to set,
+ or if the prefix `"no"` is attached, clears instead.
* `flags` is in the same format and has the same options as `mg_flags` in `minetest.conf`
* `minetest.set_noiseparams(name, noiseparams, set_default)`
* Sets the noiseparams setting of `name` to the noiseparams table specified in `noiseparams`.
* `set_default` is an optional boolean (default: `true`) that specifies whether the setting
should be applied to the default config or current active config
+* `minetest.get_noiseparams(name)`: returns a table of the noiseparams for name
+* `minetest.generate_ores(vm, pos1, pos2)`
+ * Generate all registered ores within the VoxelManip `vm` and in the area from `pos1` to `pos2`.
+ * `pos1` and `pos2` are optional and default to mapchunk minp and maxp.
+* `minetest.generate_decorations(vm, pos1, pos2)`
+ * Generate all registered decorations within the VoxelManip `vm` and in the area from `pos1` to `pos2`.
+ * `pos1` and `pos2` are optional and default to mapchunk minp and maxp.
* `minetest.clear_objects()`
* clear all objects in the environments
+* `minetest.delete_area(pos1, pos2)`
+ * delete all mapblocks in the area from pos1 to pos2, inclusive
* `minetest.line_of_sight(pos1, pos2, stepsize)`: returns `boolean, pos`
* Check if there is a direct line of sight between `pos1` and `pos2`
* Returns the position of the blocking node when `false`
* `minetest.create_detached_inventory(name, callbacks)`: returns an `InvRef`
* callbacks: See "Detached inventory callbacks"
* Creates a detached inventory. If it already exists, it is cleared.
+* `minetest.do_item_eat(hp_change, replace_with_item, itemstack, user, pointed_thing)`:
+ returns left over ItemStack
+ * See `minetest.item_eat` and `minetest.register_on_item_eat`
### Formspec
* `minetest.show_formspec(playername, formname, formspec)`
* Get position of a `pointed_thing` (that you can get from somewhere)
* `minetest.dir_to_facedir(dir, is6d)`
* Convert a vector to a facedir value, used in `param2` for `paramtype2="facedir"`;
- * passing something non-`nil`/`false` for the optional second parameter causes it to take the y component into account
+ * passing something non-`nil`/`false` for the optional second parameter causes it to
+ take the y component into account
* `minetest.facedir_to_dir(facedir)`
* Convert a facedir back into a vector aimed directly out the "back" of a node
* `minetest.dir_to_wallmounted(dir)`
`{ stack1, stack2, stack3, stack4, stack 5, stack 6, stack 7, stack 8, stack 9 }`
* `output.item` = `ItemStack`, if unsuccessful: empty `ItemStack`
* `output.time` = a number, if unsuccessful: `0`
+ * `output.replacements` = list of `ItemStack`s that couldn't be placed in
+ `decremented_input.items`
* `decremented_input` = like `input`
* `minetest.get_craft_recipe(output)`: returns input
* returns last registered recipe for output item (node)
ground)
### Rollback
-* `minetest.rollback_get_node_actions(pos, range, seconds, limit)`: returns `{{actor, pos, time, oldnode, newnode}, ...}`
+* `minetest.rollback_get_node_actions(pos, range, seconds, limit)`:
+ returns `{{actor, pos, time, oldnode, newnode}, ...}`
* Find who has done something to a node, or near a node
* `actor`: `"player:<name>"`, also `"liquid"`.
* `minetest.rollback_revert_actions_by(actor, seconds)`: returns `boolean, log_messages`
* `minetest.item_drop(itemstack, dropper, pos)`
* Drop the item
* `minetest.item_eat(hp_change, replace_with_item)`
- * Eat the item. `replace_with_item` can be `nil`.
+ * Eat the item.
+ * `replace_with_item` is the itemstring which is added to the inventory.
+ If the player is eating a stack, then replace_with_item goes to a
+ different spot. Can be `nil`
+ * See `minetest.do_item_eat`
### Defaults for the `on_punch` and `on_dig` node definition callbacks
* `minetest.node_punch(pos, node, puncher, pointed_thing)`
* Create a schematic from the volume of map specified by the box formed by p1 and p2.
* Apply the specified probability values to the specified nodes in `probability_list`.
* `probability_list` is an array of tables containing two fields, `pos` and `prob`.
- * `pos` is the 3D vector specifying the absolute coordinates of the node being modified,
+ * `pos` is the 3D vector specifying the absolute coordinates of the
+ node being modified,
* `prob` is the integer value from `0` to `255` of the probability (see: Schematic specifier).
- * If there are two or more entries with the same pos value, the last entry is used.
+ * If there are two or more entries with the same pos value, the
+ last entry is used.
* If `pos` is not inside the box formed by `p1` and `p2`, it is ignored.
* If `probability_list` equals `nil`, no probabilities are applied.
- * Slice probability works in the same manner, except takes a field called `ypos` instead which indicates
- the y position of the slice with a probability applied.
+ * Slice probability works in the same manner, except takes a field
+ called `ypos` instead which
+ indicates the y position of the slice with a probability applied.
* If slice probability list equals `nil`, no slice probabilities are applied.
* Saves schematic in the Minetest Schematic format to filename.
* `force_placement` is a boolean indicating whether nodes other than `air` and
`ignore` are replaced by the schematic
+* `minetest.serialize_schematic(schematic, format, options)`
+ * Return the serialized schematic specified by schematic (see: Schematic specifier)
+ * in the `format` of either "mts" or "lua".
+ * "mts" - a string containing the binary MTS data used in the MTS file format
+ * "lua" - a string containing Lua code representing the schematic in table format
+ * `options` is a table containing the following optional parameters:
+ * If `lua_use_comments` is true and `format` is "lua", the Lua code generated will have (X, Z)
+ * position comments for every X row generated in the schematic data for easier reading.
+ * If `lua_num_indent_spaces` is a nonzero number and `format` is "lua", the Lua code generated
+ * will use that number of spaces as indentation instead of a tab character.
+
### Misc.
* `minetest.get_connected_players()`: returns list of `ObjectRefs`
* `minetest.hash_node_position({x=,y=,z=})`: returns an 48-bit integer
* Get rating of a group of an item. (`0` means: not in group)
* `minetest.get_node_group(name, group)`: returns a rating
* Deprecated: An alias for the former.
+* `minetest.raillike_group(name)`: returns a rating
+ * Returns rating of the connect_to_raillike group corresponding to name
+ * If name is not yet the name of a connect_to_raillike group, a new group id
+ * is created, with that name
* `minetest.get_content_id(name)`: returns an integer
* Gets the internal content ID of `name`
* `minetest.get_name_from_content_id(content_id)`: returns a string
the floor or ceiling
* The first four options are mutually-exclusive; the last in the list takes
precedence over the first.
-
-
-
* `minetest.rotate_node(itemstack, placer, pointed_thing)`
- * calls `rotate_and_place()` with infinitestacks set according to the state of
+ * calls `rotate_and_place()` with infinitestacks set according to the state of
the creative mode setting, and checks for "sneak" to set the `invert_wall`
parameter.
* `minetest.forceload_block(pos)`
* forceloads the position `pos`.
* returns `true` if area could be forceloaded
+ * Please note that forceloaded areas are saved when the server restarts.
* `minetest.forceload_free_block(pos)`
* stops forceloading the position `pos`
-Please note that forceloaded areas are saved when the server restarts.
+* `minetest.request_insecure_environment()`: returns an environment containing
+ insecure functions if the calling mod has been listed as trusted in the
+ `secure.trusted_mods` setting or security is disabled, otherwise returns `nil`.
+ * Only works at init time.
+ * **DO NOT ALLOW ANY OTHER MODS TO ACCESS THE RETURNED ENVIRONMENT, STORE IT IN
+ A LOCAL VARIABLE!**
+
+* `minetest.global_exists(name)`
+ * Checks if a global variable has been set, without triggering a warning.
### Global objects
* `minetest.env`: `EnvRef` of the server environment and world.
* Any function in the minetest namespace can be called using the syntax
`minetest.env:somefunction(somearguments)`
instead of `minetest.somefunction(somearguments)`
- * Deprecated, but support is not to be dropped soon
+ * Deprecated, but support is not to be dropped soon
### Global tables
* `minetest.registered_items`
- * List of registered items, indexed by name
+ * Map of registered items, indexed by name
* `minetest.registered_nodes`
- * List of registered node definitions, indexed by name
+ * Map of registered node definitions, indexed by name
* `minetest.registered_craftitems`
- * List of registered craft item definitions, indexed by name
+ * Map of registered craft item definitions, indexed by name
* `minetest.registered_tools`
- * List of registered tool definitions, indexed by name
+ * Map of registered tool definitions, indexed by name
* `minetest.registered_entities`
- * List of registered entity prototypes, indexed by name
+ * Map of registered entity prototypes, indexed by name
* `minetest.object_refs`
- * List of object references, indexed by active object id
+ * Map of object references, indexed by active object id
* `minetest.luaentities`
- * List of Lua entities, indexed by active object id
+ * Map of Lua entities, indexed by active object id
+* `minetest.registered_ores`
+ * List of registered ore definitions.
+* `minetest.registered_decorations`
+ * List of registered decoration definitions.
Class reference
---------------
### `NodeMetaRef`
-Node metadata: reference extra data and functionality stored in a node.
+Node metadata: reference extra data and functionality stored in a node.
Can be gotten via `minetest.get_meta(pos)`.
#### Methods
* See "Node Metadata"
### `NoteTimerRef`
-Node Timers: a high resolution persistent per-node timer.
+Node Timers: a high resolution persistent per-node timer.
Can be gotten via `minetest.get_node_timer(pos)`.
#### Methods
#### Methods
* `remove()`: remove object (after returning from Lua)
+ * Note: Doesn't work on players, use minetest.kick_player instead
* `getpos()`: returns `{x=num, y=num, z=num}`
* `setpos(pos)`; `pos`=`{x=num, y=num, z=num}`
* `moveto(pos, continuous=false)`: interpolated move
* `get_wielded_item()`: returns an `ItemStack`
* `set_wielded_item(item)`: replaces the wielded item, returns `true` if successful
* `set_armor_groups({group1=rating, group2=rating, ...})`
-* `set_animation({x=1,y=1}, frame_speed=15, frame_blend=0)`
+* `get_armor_groups()`: returns a table with the armor group ratings
+* `set_animation({x=1,y=1}, frame_speed=15, frame_blend=0, frame_loop=true)`
+* `get_animation()`: returns range, frame_speed, frame_blend and frame_loop
* `set_attach(parent, bone, position, rotation)`
* `bone`: string
* `position`: `{x=num, y=num, z=num}` (relative)
* `rotation`: `{x=num, y=num, z=num}`
+* `get_attach()`: returns parent, bone, position, rotation or nil if it isn't attached
* `set_detach()`
* `set_bone_position(bone, position, rotation)`
* `bone`: string
* `position`: `{x=num, y=num, z=num}` (relative)
* `rotation`: `{x=num, y=num, z=num}`
+* `get_bone_position(bone)`: returns position and rotation of the bone
* `set_properties(object property table)`
+* `get_properties()`: returns object property table
+* `is_player()`: returns true for players, false otherwise
##### LuaEntitySAO-only (no-op for other objects)
* `setvelocity({x=num, y=num, z=num})`
* `get_luaentity()`
##### Player-only (no-op for other objects)
-* `is_player()`: true for players, false for others
* `get_player_name()`: returns `""` if is not a player
+* `get_player_velocity()`: returns `nil` if is not a player otherwise a table {x, y, z} representing the player's instantaneous velocity in nodes/s
* `get_look_dir()`: get camera direction as a unit vector
* `get_look_pitch()`: pitch in radians
* `get_look_yaw()`: yaw in radians (wraps around pretty randomly as of now)
* `gravity`: multiplier to default gravity value (default: `1`)
* `sneak`: whether player can sneak (default: `true`)
* `sneak_glitch`: whether player can use the sneak glitch (default: `true`)
-* `hud_add(hud definition)`: add a HUD element described by HUD def, returns ID number on success
+* `get_physics_override()`: returns the table given to set_physics_override
+* `hud_add(hud definition)`: add a HUD element described by HUD def, returns ID
+ number on success
* `hud_remove(id)`: remove the HUD element of the specified id
* `hud_change(id, stat, value)`: change a value of a previously added HUD element
* element `stat` values: `position`, `name`, `scale`, `text`, `number`, `item`, `dir`
* returns `{ hotbar=true, healthbar=true, crosshair=true, wielditem=true, breathbar=true }`
* `hud_set_hotbar_itemcount(count)`: sets number of items in builtin hotbar
* `count`: number of items, must be between `1` and `23`
+* `hud_get_hotbar_itemcount`: returns number of visible items
* `hud_set_hotbar_image(texturename)`
* sets background image for hotbar
+* `hud_get_hotbar_image`: returns texturename
* `hud_set_hotbar_selected_image(texturename)`
* sets image for selected item of hotbar
+* `hud_get_hotbar_selected_image`: returns texturename
* `hud_replace_builtin(name, hud_definition)`
* replace definition of a builtin hud element
* `name`: `"breath"` or `"health"`
* `hud_definition`: definition to replace builtin definition
* `set_sky(bgcolor, type, {texture names})`
- * `bgcolor`: `{r=0...255, g=0...255, b=0...255}` or `nil`, defaults to white
+ * `bgcolor`: ColorSpec, defaults to white
* Available types:
* `"regular"`: Uses 0 textures, `bgcolor` ignored
* `"skybox"`: Uses 6 textures, `bgcolor` used
* `"plain"`: Uses 0 textures, `bgcolor` used
* **Note**: currently does not work directly in `on_joinplayer`; use
`minetest.after(0)` in there.
+* `get_sky()`: returns bgcolor, type and a table with the textures
* `override_day_night_ratio(ratio or nil)`
* `0`...`1`: Overrides day-night ratio, controlling sunlight to a specific amount
* `nil`: Disables override, defaulting to sunlight based on day-night cycle
-* `set_local_animation({x=0, y=79}, {x=168, y=187}, {x=189, y=198}, {x=200, y=219}, frame_speed=30)`: set animation for player model in third person view
- * stand/idle animation key frames
- * walk animation key frames
- * dig animation key frames
- * walk+dig animation key frames
- * animation frame speed
+* `get_day_night_ratio()`: returns the ratio or nil if it isn't overridden
+* `set_local_animation(stand/idle, walk, dig, walk+dig, frame_speed=frame_speed)`
+
+ set animation for player model in third person view
+
+ set_local_animation({x=0, y=79}, -- < stand/idle animation key frames
+ {x=168, y=187}, -- < walk animation key frames
+ {x=189, y=198}, -- < dig animation key frames
+ {x=200, y=219}, -- < walk+dig animation key frames
+ frame_speed=30): -- < animation frame speed
+* `get_local_animation()`: returns stand, walk, dig, dig+walk tables and frame_speed
* `set_eye_offset({x=0,y=0,z=0},{x=0,y=0,z=0})`: defines offset value for camera per player
* in first person view
* in third person view (max. values `{x=-10/10,y=-10,15,z=-5/5}`)
+* `get_eye_offset()`: returns offset_first and offset_third
+* `get_nametag_attributes()`
+ * returns a table with the attributes of the nametag of the player
+ * {
+ color = {a=0..255, r=0..255, g=0..255, b=0..255},
+ }
+* `set_nametag_attributes(attributes)`
+ * sets the attributes of the nametag of the player
+ * `attributes`:
+ {
+ color = ColorSpec,
+ }
### `InvRef`
An `InvRef` is a reference to an inventory.
Returns taken `ItemStack`.
### `PseudoRandom`
-A pseudorandom number generator.
+A 16-bit pseudorandom number generator.
+Uses a well-known LCG algorithm introduced by K&R.
It can be created via `PseudoRandom(seed)`.
* `((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, offering very strong randomness.
+
+It can be created via `PcgRandom(seed)` or `PcgRandom(seed, sequence)`.
+
+#### Methods
+* `next()`: return next integer random number [`-2147483648`...`2147483647`]
+* `next(min, max)`: return next integer random number [`min`...`max`]
+* `rand_normal_dist(min, max, num_trials=6)`: return normally distributed random number [`min`...`max`]
+ * This is only a rough approximation of a normal distribution with mean=(max-min)/2 and variance=1
+ * Increasing num_trials improves accuracy of the approximation
+
### `PerlinNoise`
A perlin noise generator.
It can be created via `PerlinNoise(seed, octaves, persistence, scale)`
-or `PerlinNoise(noiseparams)`.
+or `PerlinNoise(noiseparams)`.
Alternatively with `minetest.get_perlin(seeddiff, octaves, persistence, scale)`
or `minetest.get_perlin(noiseparams)`.
for 2D noise, and it must be must be larger than 1 for 3D noise (otherwise
`nil` is returned).
+For each of the functions with an optional `buffer` parameter: If `buffer` is not
+nil, this table will be used to store the result instead of creating a new table.
+
+
#### Methods
* `get2dMap(pos)`: returns a `<size.x>` times `<size.y>` 2D array of 2D noise
with values starting at `pos={x=,y=}`
* `get3dMap(pos)`: returns a `<size.x>` times `<size.y>` times `<size.z>` 3D array
of 3D noise with values starting at `pos={x=,y=,z=}`
-* `get2dMap_flat(pos)`: returns a flat `<size.x * size.y>` element array of 2D noise with values starting at `pos={x=,y=}`
-* `get3dMap_flat(pos)`: Same as `get2dMap_flat`, but 3D noise
+* `get2dMap_flat(pos, buffer)`: returns a flat `<size.x * size.y>` element array of 2D noise
+ with values starting at `pos={x=,y=}`
+* `get3dMap_flat(pos, buffer)`: Same as `get2dMap_flat`, but 3D noise
+* `calc2dMap(pos)`: Calculates the 2d noise map starting at `pos`. The result is stored internally.
+* `calc3dMap(pos)`: Calculates the 3d noise map starting at `pos`. The result is stored internally.
+* `getMapSlice(slice_offset, slice_size, buffer)`: In the form of an array, returns a slice of the
+ most recently computed noise results. The result slice begins at coordinates `slice_offset` and
+ takes a chunk of `slice_size`.
+ E.g. to grab a 2-slice high horizontal 2d plane of noise starting at buffer offset y = 20:
+ `noisevals = noise:getMapSlice({y=20}, {y=2})`
+ It is important to note that `slice_offset` offset coordinates begin at 1, and are relative to
+ the starting position of the most recently calculated noise.
+ To grab a single vertical column of noise starting at map coordinates x = 1023, y=1000, z = 1000:
+ `noise:calc3dMap({x=1000, y=1000, z=1000})`
+ `noisevals = noise:getMapSlice({x=24, z=1}, {x=1, z=1})`
### `VoxelManip`
An interface to the `MapVoxelManipulator` for Lua.
The map will be pre-loaded if two positions are passed to either.
#### Methods
-* `read_from_map(p1, p2)`: Reads a chunk of map from the map containing the region formed by `p1` and `p2`.
+* `read_from_map(p1, p2)`: Reads a chunk of map from the map containing the
+ region formed by `p1` and `p2`.
* returns actual emerged `pmin`, actual emerged `pmax`
* `write_to_map()`: Writes the data loaded from the `VoxelManip` back to the map.
* **important**: data must be set using `VoxelManip:set_data` before calling this
-* `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()`: Gets the data read into the `VoxelManip` object
- * returns raw node data is in the form of an array of node content IDs
+* `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)`: Gets the data read 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()`: Update map after writing chunk back to map.
- * To be used only by `VoxelManip` objects created by the mod itself; not a `VoxelManip` that was
- retrieved from `minetest.get_mapgen_object`
+ * To be used only by `VoxelManip` objects created by the mod itself;
+ not a `VoxelManip` that was retrieved from `minetest.get_mapgen_object`
* `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
+ * (`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`
+* `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()`: Gets the raw `param2` data read into the `VoxelManip` object
* `set_param2_data(param2_data)`: Sets the `param2` contents of each node in the `VoxelManip`
* `calc_lighting(p1, p2)`: 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
+ * (`p1`, `p2`) is the area in which lighting is set; defaults to the whole area
+ if left out
* `update_liquids()`: Update liquid flow
-* `was_modified()`: Returns `true` or `false` if the data in the voxel manipulator had been modified since
- the last read from map, due to a call to `minetest.set_data()` on the loaded area elsewhere
+* `was_modified()`: Returns `true` or `false` if the data in the voxel manipulator
+ had been modified since the last read from map, due to a call to
+ `minetest.set_data()` on the loaded area elsewhere
* `get_emerged_area()`: Returns actual emerged minimum and maximum positions.
### `VoxelArea`
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`
+* `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`
- * useful for things like `VoxelManip`, raw Schematic specifiers, `PerlinNoiseMap:get2d`/`3dMap`, and so on
+ * useful for things like `VoxelManip`, raw Schematic specifiers,
+ `PerlinNoiseMap:get2d`/`3dMap`, and so on
* `indexp(p)`: same as above, except takes a vector
* `position(i)`: returns the absolute position vector corresponding to index `i`
* `contains(x, y, z)`: check if (`x`,`y`,`z`) is inside area formed by `MinEdge` and `MaxEdge`
Mapgen objects
--------------
-A mapgen object is a construct used in map generation. Mapgen objects can be used by an `on_generate`
-callback to speed up operations by avoiding unnecessary recalculations; these can be retrieved using the
-`minetest.get_mapgen_object()` function. If the requested Mapgen object is unavailable, or
-`get_mapgen_object()` was called outside of an `on_generate()` callback, `nil` is returned.
+A mapgen object is a construct used in map generation. Mapgen objects can be used
+by an `on_generate` callback to speed up operations by avoiding unnecessary
+recalculations; these can be retrieved using the `minetest.get_mapgen_object()`
+function. If the requested Mapgen object is unavailable, or `get_mapgen_object()`
+was called outside of an `on_generate()` callback, `nil` is returned.
The following Mapgen objects are currently available:
### `voxelmanip`
-This returns three values; the `VoxelManip` object to be used, minimum and maximum emerged position, in that
-order. All mapgens support this object.
+This returns three values; the `VoxelManip` object to be used, minimum and maximum
+emerged position, in that order. All mapgens support this object.
### `heightmap`
-Returns an array containing the y coordinates of the ground levels of nodes in the most recently
-generated chunk by the current mapgen.
+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.
+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.
+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.
+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 at within the current chunk. To set the capture of positions
-of interest to be recorded on generate, use `minetest.set_gen_notify()`.
+Returns a table mapping requested generation notification types to arrays of
+positions at which the corresponding generated structures are located at within
+the current chunk. To set the capture of positions of interest to be recorded
+on generate, use `minetest.set_gen_notify()`.
Possible fields of the table returned are:
* `large_cave_end`
* `decoration`
-Decorations have a key in the format of `"decoration#id"`, where `id` is the numeric unique decoration ID.
+Decorations have a key in the format of `"decoration#id"`, where `id` is the
+numeric unique decoration ID.
Registered entities
-------------------
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
+ 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
### Tile definition
* `"image.png"`
* `{name="image.png", animation={Tile Animation definition}}`
-* `{name="image.png", backface_culling=bool}`
- * backface culling only supported in special tiles
+* `{name="image.png", backface_culling=bool, tileable_vertical=bool,
+ tileable_horizontal=bool}`
+ * backface culling only supported in special tiles.
+ * tileable flags are info for shaders, how they should treat texture
+ when displacement mapping is used
+ Directions are from the point of view of the tile texture,
+ not the node it's on
* deprecated, yet still supported field names:
* `image` (name)
^ List can be shortened to needed length ]]
alpha = 255,
use_texture_alpha = false, -- Use texture's alpha channel
- post_effect_color = {a=0, r=0, g=0, b=0}, -- If player is inside node
- paramtype = "none", -- See "Nodes"
+ post_effect_color = "green#0F", -- If player is inside node, see "ColorSpec"
+ paramtype = "none", -- See "Nodes" --[[
+ ^ paramtype = "light" allows light to propagate from or through the node with light value
+ ^ falling by 1 per node. This line is essential for a light source node to spread its light. ]]
paramtype2 = "none", -- See "Nodes"
is_ground_content = true, -- If false, the cave generator will not carve through this
sunlight_propagates = false, -- If true, sunlight will go infinitely through this
liquid_alternative_source = "", -- Source version of flowing liquid
liquid_viscosity = 0, -- Higher viscosity = slower flow (max. 7)
liquid_renewable = true, -- Can new liquid source be created by placing two or more sources nearby?
- freezemelt = "", -- water for snow/ice, ice/snow for water
- leveled = 0, -- Block contain level in param2. value - default level, used for snow. Don't forget use "leveled" type nodebox
+ leveled = 0, --[[
+ ^ Block contains level in param2. Value is default level, used for snow.
+ ^ Don't forget to use "leveled" type nodebox. ]]
liquid_range = 8, -- number of flowing nodes around source (max. 8)
drowning = 0, -- Player will take this amount of damage if no bubbles are left
light_source = 0, -- Amount of light emitted by node
damage_per_second = 0, -- If player is inside node, this damage is caused
node_box = {type="regular"}, -- See "Node boxes"
mesh = "model",
- selection_box = {type="regular"}, -- See "Node boxes"
- ^ If drawtype "nodebox" is used and selection_box is nil, then node_box is used
+ selection_box = {type="regular"}, -- See "Node boxes" --[[
+ ^ If drawtype "nodebox" is used and selection_box is nil, then node_box is used. ]]
legacy_facedir_simple = false, -- Support maps made in and before January 2012
legacy_wallmounted = false, -- Support maps made in and before January 2012
sounds = {
^ Called after destructing node when node was dug using
minetest.node_dig / minetest.dig_node
^ default: nil ]]
- can_dig = function(pos,player) --[[
+ can_dig = function(pos, [player]) --[[
^ returns true if node can be dug, or false if not
^ default: nil ]]
-- ^ Multiplier of the randomness contribution to the noise value at any
-- given point to decide if ore should be placed. Set to 0 for solid veins.
-- ^ This parameter is only valid for ore_type == "vein".
+ biomes = {"desert", "rainforest"}
+ -- ^ List of biomes in which this decoration occurs. Occurs in all biomes if this is omitted,
+ -- ^ and ignored if the Mapgen being used does not support biomes.
+ -- ^ Can be a list of (or a single) biome names, IDs, or definitions.
}
### Decoration definition (`register_decoration`)
biomes = {"Oceanside", "Hills", "Plains"},
-- ^ List of biomes in which this decoration occurs. Occurs in all biomes if this is omitted,
-- ^ and ignored if the Mapgen being used does not support biomes.
+ -- ^ Can be a list of (or a single) biome names, IDs, or definitions.
y_min = -31000
y_max = 31000
-- ^ Minimum and maximum `y` positions these decorations can be generated at.
-- ^ Number of nodes the decoration can be at maximum.
-- ^ If absent, the parameter 'height' is used as a constant.
spawn_by = "default:water",
- -- ^ Node that the decoration only spawns next to, in a 1-node square radius.
+ -- ^ Node that the decoration only spawns next to.
+ -- ^ The neighbours checked are the 8 nodes horizontally surrounding the lowest node of the
+ -- ^ decoration, and the 8 nodes horizontally surrounding the ground node below the decoration.
num_spawn_by = 1,
-- ^ Number of spawn_by nodes that must be surrounding the decoration position to occur.
-- ^ If absent or -1, decorations occur next to any nodes.
schematic = "foobar.mts",
-- ^ If schematic is a string, it is the filepath relative to the current working directory of the
-- ^ specified Minetest schematic file.
+ -- ^ - OR -, could be the ID of a previously registered schematic
-- ^ - OR -, could instead be a table containing two mandatory fields, size and data,
-- ^ and an optional table yslice_prob:
schematic = {
size = {x=4, y=6, z=4},
data = {
- {name="cobble", param1=255, param2=0},
- {name="dirt_with_grass", param1=255, param2=0},
+ {name="default:cobble", param1=255, param2=0},
+ {name="default:dirt_with_grass", param1=255, param2=0},
+ {name="ignore", param1=255, param2=0},
+ {name="air", param1=255, param2=0},
...
},
yslice_prob = {
},
-- ^ See 'Schematic specifier' for details.
replacements = {["oldname"] = "convert_to", ...},
- flags = "place_center_x, place_center_z",
+ flags = "place_center_x, place_center_y, place_center_z, force_placement",
-- ^ Flags for schematic decorations. See 'Schematic attributes'.
rotation = "90" -- rotate schematic 90 degrees on placement
-- ^ Rotation can be "0", "90", "180", "270", or "random".
playername = "singleplayer"
-- ^ Playername is optional, if specified spawns particle only on the player's client
}
-
projects / dragonfireclient.git / blobdiff