-Minetest Lua Modding API Reference 0.4.12
+Minetest Lua Modding API Reference 0.4.15
=========================================
* More information at <http://www.minetest.net/>
* Developer Wiki: <http://dev.minetest.net/>
The game directory can contain the file minetest.conf, which will be used
to set default settings when running the particular game.
+It can also contain a settingtypes.txt in the same format as the one in builtin.
+This settingtypes.txt will be parsed by the menu and the settings will be displayed
+in the "Games" category in the settings tab.
+
+### 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
-------------
| |-- depends.txt
| |-- screenshot.png
| |-- description.txt
+ | |-- settingtypes.txt
| |-- init.lua
| |-- models
| |-- textures
is missing, that does not prevent this mod from being loaded.
### `screenshot.png`
-A screenshot shown in modmanager within mainmenu.
+A screenshot shown in the mod manager within the main menu. It should
+have an aspect ratio of 3:2 and a minimum size of 300×200 pixels.
### `description.txt`
A File containing description to be shown within mainmenu.
+### `settingtypes.txt`
+A file in the same format as the one in builtin. It will be parsed by the
+settings menu and the settings will be displayed in the "Mods" category.
+
### `init.lua`
The main Lua script. Running this script should register everything it
wants to register. Subsequent execution depends on minetest calling the
The `:` prefix can also be used for maintaining backwards compatibility.
### Aliases
-Aliases can be added by using `minetest.register_alias(name, convert_to)`.
+Aliases can be added by using `minetest.register_alias(name, convert_to)` or
+`minetest.register_alias_force(name, convert_to).
This will make Minetest to convert things called name to things called
`convert_to`.
+The only difference between `minetest.register_alias` and
+`minetest.register_alias_force` is that if an item called `name` exists,
+`minetest.register_alias` will do nothing while
+`minetest.register_alias_force` will unregister it.
+
This can be used for maintaining backwards compatibility.
This can be also used for setting quick access names for things, e.g. if
default_dirt.png^default_grass_side.png
`default_grass_side.png` is overlayed over `default_dirt.png`.
+The texture with the lower resolution will be automatically upscaled to
+the higher resolution texture.
### Texture grouping
Textures can be grouped together by enclosing them in `(` and `)`.
Example: `cobble.png^(thing1.png^thing2.png)`
A texture for `thing1.png^thing2.png` is created and the resulting
-texture is overlaid over `cobble.png`.
+texture is overlaid on top of `cobble.png`.
+
+### Escaping
+Modifiers that accept texture names (e.g. `[combine`) accept escaping to allow
+passing complex texture names as arguments. Escaping is done with backslash and
+is required for `^` and `:`.
+
+Example: `cobble.png^[lowpart:50:color.png\^[mask\:trans.png`
+
+The lower 50 percent of `color.png^[mask:trans.png` are overlaid
+on top of `cobble.png`.
### Advanced texture modifiers
default_cobble.png^[crack:10:1
-#### `[combine:<w>x<h>:<x1>,<y1>=<file1>:<x2>,<y2>=<file2>`
+#### `[combine:<w>x<h>:<x1>,<y1>=<file1>:<x2>,<y2>=<file2>:...`
* `<w>` = width
* `<h>` = height
-* `<x1>`/`<x2>` = x positions
-* `<y1>`/`<y1>` = y positions
-* `<file1>`/`<file2>` = textures to combine
+* `<x>` = x position
+* `<y>` = y position
+* `<file>` = texture to combine
-Create a texture of size `<w>` times `<h>` and blit `<file1>` to (`<x1>`,`<y1>`)
-and blit `<file2>` to (`<x2>`,`<y2>`).
+Creates a texture of size `<w>` times `<h>` and blits the listed files to their
+specified coordinates.
Example:
[combine:16x32:0,0=default_cobble.png:0,16=default_wood.png
+#### `[resize:<w>x<h>`
+Resizes the texture to the given dimensions.
+
+Example:
+
+ default_sandstone.png^[resize:16x16
+
+#### `[opacity:<r>`
+ Makes the base image transparent according to the given ratio.
+ r must be between 0 and 255.
+ 0 means totally transparent.
+ 255 means totally opaque.
+
+Example:
+
+ default_sandstone.png^[opacity:127
+
+#### `[invert:<mode>`
+Inverts the given channels of the base image.
+Mode may contain the characters "r", "g", "b", "a".
+Only the channels that are mentioned in the mode string will be inverted.
+
+Example:
+
+ default_apple.png^[invert:rgb
+
#### `[brighten`
Brightens the texture.
default_stone.png^[transformFXR90
#### `[inventorycube{<top>{<left>{<right>`
-`^` is replaced by `&` in texture names.
+Escaping does not apply here and `^` is replaced by `&` in texture names instead.
Create an inventory cube texture using the side textures.
The mask is applied using binary AND.
+#### `[sheet:<w>x<h>:<x>,<y>`
+Retrieves a tile at position x,y from the base image
+which it assumes to be a tilesheet with dimensions w,h.
+
+
#### `[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.
+`<ratio>` is an int ranging from 0 to 255 or the word "`alpha`". If
+it is an int, then it specifies how far to interpolate between the
+colors where 0 is only the texture color and 255 is only `<color>`. If
+omitted, the alpha of `<color>` will be used as the ratio. If it is
+the word "`alpha`", then each texture pixel will contain the RGB of
+`<color>` and the alpha of `<color>` multiplied by the alpha of the
+texture pixel.
+
+#### `[multiply:<color>`
+Multiplies texture colors with the given color.
+`<color>` is specified as a `ColorString`.
+Result is more like what you'd expect if you put a color on top of another
+color. Meaning white surfaces get a lot of your new color while black parts don't
+change very much.
Sounds
------
Examples of sound parameter tables:
- -- Play location-less on all clients
+ -- Play locationless on all clients
{
gain = 1.0, -- default
}
- -- Play location-less to a player
+ -- Play locationless to one player
{
to_player = name,
gain = 1.0, -- default
}
+ -- Play locationless to one player, looped
+ {
+ to_player = name,
+ gain = 1.0, -- default
+ loop = true,
+ }
-- Play in a location
{
- pos = {x=1,y=2,z=3},
+ pos = {x = 1, y = 2, z = 3},
gain = 1.0, -- default
- max_hear_distance = 32, -- default
+ max_hear_distance = 32, -- default, uses an euclidean metric
}
-- Play connected to an object, looped
{
object = <an ObjectRef>,
gain = 1.0, -- default
- max_hear_distance = 32, -- default
- loop = true, -- only sounds connected to objects can be looped
+ max_hear_distance = 32, -- default, uses an euclidean metric
+ loop = true,
}
+Looped sounds must either be connected to an object or played locationless to
+one player using `to_player = name,`
+
### `SimpleSoundSpec`
* e.g. `""`
* e.g. `"default_place_node"`
* e.g. `{}`
-* e.g. `{name="default_place_node"}`
-* e.g. `{name="default_place_node", gain=1.0}`
+* e.g. `{name = "default_place_node"}`
+* e.g. `{name = "default_place_node", gain = 1.0}`
Registered definitions of stuff
-------------------------------
* `minetest.register_craftitem(name, item definition)`
* added to `minetest.registered_items[name]`
+* `minetest.unregister_item(name)`
+ * Unregisters the item name from engine, and deletes the entry with key
+ * `name` from `minetest.registered_items` and from the associated item
+ * table according to its nature: minetest.registered_nodes[] etc
+
* `minetest.register_biome(biome definition)`
* returns an integer uniquely identifying the registered biome
* added to `minetest.registered_biome` with the key of `biome.name`
* 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
+ * 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
^ The rotation of the node is stored in param2. Furnaces and chests are
rotated this way. Can be made by using minetest.dir_to_facedir().
Values range 0 - 23
- facedir modulo 4 = axisdir
+ facedir / 4 = axis direction:
0 = y+ 1 = z+ 2 = z- 3 = x+ 4 = x- 5 = y-
- facedir's two less significant bits are rotation around the axis
+ facedir modulo 4 = rotation around that axis
paramtype2 == "leveled"
+ paramtype2 == "degrotate"
+ ^ The rotation of this node is stored in param2. Plants are rotated this way.
+ Values range 0 - 179. The value stored in param2 is multiplied by two to
+ get the actual rotation of the node.
+ paramtype2 == "meshoptions"
+ ^ Only valid for "plantlike". The value of param2 becomes a bitfield which can
+ be used to change how the client draws plantlike nodes. Bits 0, 1 and 2 form
+ a mesh selector. Currently the following meshes are choosable:
+ 0 = a "x" shaped plant (ordinary plant)
+ 1 = a "+" shaped plant (just rotated 45 degrees)
+ 2 = a "*" shaped plant with 3 faces instead of 2
+ 3 = a "#" shaped plant with 4 faces instead of 2
+ 4 = a "#" shaped plant with 4 faces that lean outwards
+ 5-7 are unused and reserved for future meshes.
+ Bits 3 through 7 are optional flags that can be combined and give these
+ effects:
+ bit 3 (0x08) - Makes the plant slightly vary placement horizontally
+ bit 4 (0x10) - Makes the plant mesh 1.4x larger
+ bit 5 (0x20) - Moves each face randomly a small bit down (1/8 max)
+ bits 6-7 are reserved for future use.
+ paramtype2 == "color"
+ ^ `param2` tells which color is picked from the palette.
+ The palette should have 256 pixels.
+ paramtype2 == "colorfacedir"
+ ^ Same as `facedir`, but with colors.
+ The first three bits of `param2` tells which color
+ is picked from the palette.
+ The palette should have 8 pixels.
+ paramtype2 == "colorwallmounted"
+ ^ Same as `wallmounted`, but with colors.
+ The first five bits of `param2` tells which color
+ is picked from the palette.
+ The palette should have 32 pixels.
+ paramtype2 == "glasslikeliquidlevel"
+ ^ Only valid for "glasslike_framed" or "glasslike_framed_optional" drawtypes.
+ param2 defines 64 levels of internal liquid.
+ Liquid texture is defined using `special_tiles = {"modname_tilename.png"},`
collision_box = {
type = "fixed",
fixed = {
wall_bottom = box,
wall_side = box
}
+ {
+ -- A node that has optional boxes depending on neighbouring nodes'
+ -- presence and type. See also `connects_to`.
+ type = "connected",
+ fixed = box OR {box1, box2, ...}
+ connect_top = box OR {box1, box2, ...}
+ connect_bottom = box OR {box1, box2, ...}
+ connect_front = box OR {box1, box2, ...}
+ connect_left = box OR {box1, box2, ...}
+ connect_back = box OR {box1, box2, ...}
+ connect_right = box OR {box1, box2, ...}
+ }
A `box` is defined as:
### `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`.
+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 eminates 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.
-**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`.
+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.
-`clust_scarcity` and `clust_num_ores` are ignored.
+The vertical top and bottom displacement of each puff are determined by the noise
+parameters `np_puff_top` and `np_puff_bottom`, respectively.
-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
`noise_params`. The maximum size of the blob is `clust_size`, and
`clust_scarcity` has the same meaning as with the `scatter` type.
-### `vein
+
+### `vein`
Creates veins of ore varying in density by according to the intersection of two
instances of 3d perlin noise with diffferent 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_threshhold`.
+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:
persist = 0.5,
flags = "eased",
},
- noise_threshhold = 1.6
+ noise_threshold = 1.6
WARNING: Use this ore type *very* sparingly since it is ~200x more
computationally expensive than any other ore.
Useful for having ore in sky realms without having to duplicate ore entries.
+### `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.
-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.
+papyri, waterlilies and so on.
### `schematic`
Copies a box of `MapNodes` from a specified schematic file (or raw description).
--------------------
See section "Flag Specifier Format".
-Currently supported flags: `place_center_x`, `place_center_y`,
- `place_center_z`, `force_placement`.
+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.
* `number`: Number of items in the inventory to be displayed.
* `item`: Position of item that is selected.
* `direction`
+* `offset`: offset in pixels from position.
### `waypoint`
Displays distance to selected world position.
On the Lua side, every punch calls:
- entity:on_punch(puncher, time_from_last_punch, tool_capabilities, direction)
+ entity:on_punch(puncher, time_from_last_punch, tool_capabilities, direction, damage)
This should never be called directly, because damage is usually not handled by
the entity itself.
* `tool_capabilities` can be `nil`.
* `direction` is a unit vector, pointing from the source of the punch to
the punched object.
+* `damage` damage that will be done to entity
+Return value of this function will determin if damage is done by this function
+(retval true) or shall be done by engine (retval false)
To punch an entity/object in Lua, call:
-------------
The instance of a node in the world normally only contains the three values
mentioned in "Nodes". However, it is possible to insert extra data into a
-node. It is called "node metadata"; See "`NodeMetaRef`".
+node. It is called "node metadata"; See `NodeMetaRef`.
+
+Node metadata contains two things:
-Metadata contains two things:
* A key-value store
* An inventory
Some of the values in the key-value store are handled specially:
+
* `formspec`: Defines a right-click inventory menu. See "Formspec".
* `infotext`: Text shown on the screen when the node is pointed at
}
})
+Item Metadata
+-------------
+Item stacks can store metadata too. See `ItemStackMetaRef`.
+
+Item metadata only contains a key-value store.
+
+Some of the values in the key-value store are handled specially:
+
+* `description`: Set the itemstack's description. Defaults to idef.description
+
+Example stuff:
+
+ local meta = stack:get_meta()
+ meta:set_string("key", "value")
+ print(dump(meta:to_table()))
+
Formspec
--------
Formspec defines a menu. Currently not much else than inventories are
* `fixed_size`: `true`/`false` (optional)
* deprecated: `invsize[<W>,<H>;]`
+#### `position[<X>,<Y>]`
+* Define the position of the formspec
+* A value between 0.0 and 1.0 represents a position inside the screen
+* The default value is the center of the screen (0.5, 0.5)
+
+#### `anchor[<X>,<Y>]`
+* Define the anchor of the formspec
+* A value between 0.0 and 1.0 represents an anchor inside the formspec
+* The default value is the center of the formspec (0.5, 0.5)
+
+#### `container[<X>,<Y>]`
+* Start of a container block, moves all physical elements in the container by (X, Y)
+* Must have matching container_end
+* Containers can be nested, in which case the offsets are added
+ (child containers are relative to parent containers)
+
+#### `container_end[]`
+* End of a container, following elements are no longer relative to this container
+
#### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]`
* Show an inventory list
#### `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
#### `pwdfield[<X>,<Y>;<W>,<H>;<name>;<label>]`
* Textual password style field; will be sent to server when a button is clicked
+* When enter is pressed in field, fields.key_enter_field will be sent with the name
+ of this field.
* `x` and `y` position the field relative to the top left of the menu
* `w` and `h` are the size of the field
-* fields are a set height, but will be vertically centred on `h`
+* Fields are a set height, but will be vertically centred on `h`
* Position and size units are inventory slots
* `name` is the name of the field as returned in fields to `on_receive_fields`
* `label`, if not blank, will be text printed on the top left above the field
+* See field_close_on_enter to stop enter closing the formspec
#### `field[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`
* Textual field; will be sent to server when a button is clicked
+* When enter is pressed in field, fields.key_enter_field will be sent with the name
+ of this field.
* `x` and `y` position the field relative to the top left of the menu
* `w` and `h` are the size of the field
-* fields are a set height, but will be vertically centred on `h`
+* Fields are a set height, but will be vertically centred on `h`
* Position and size units are inventory slots
* `name` is the name of the field as returned in fields to `on_receive_fields`
* `label`, if not blank, will be text printed on the top left above the field
* `default` may contain variable references such as `${text}'` which
will fill the value from the metadata value `text`
* **Note**: no extra text or more than a single variable is supported ATM.
+* See field_close_on_enter to stop enter closing the formspec
#### `field[<name>;<label>;<default>]`
-* as above, but without position/size units
-* special field for creating simple forms, such as sign text input
-* must be used without a `size[]` element
-* a "Proceed" button will be added automatically
+* As above, but without position/size units
+* When enter is pressed in field, fields.key_enter_field will be sent with the name
+ of this field.
+* Special field for creating simple forms, such as sign text input
+* Must be used without a `size[]` element
+* A "Proceed" button will be added automatically
+* See field_close_on_enter to stop enter closing the formspec
+
+#### `field_close_on_enter[<name>;<close_on_enter>]`
+* <name> is the name of the field
+* if <close_on_enter> is false, pressing enter in the field will submit the form but not close it
+* defaults to true when not specified (ie: no tag for a field)
#### `textarea[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`
-* same as fields above, but with multi-line input
+* Same as fields above, but with multi-line input
#### `label[<X>,<Y>;<label>]`
* `x` and `y` work as per field
* `name` fieldname sent to server on doubleclick value is current selected element
* `listelements` can be prepended by #RRGGBB (only) in hexadecimal format
* if you want a listelement to start with "#" write "##"
-* index to be selected within textlist
+* Index to be selected within textlist
* `true`/`false`: draw transparent background
-* see also `minetest.explode_textlist_event` (main menu: `engine.explode_textlist_event`)
+* See also `minetest.explode_textlist_event` (main menu: `engine.explode_textlist_event`)
#### `tabheader[<X>,<Y>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]`
-* show a tab**header** at specific position (ignores formsize)
+* Show a tab**header** at specific position (ignores formsize)
* `x` and `y` position the itemlist relative to the top left of the menu
* `name` fieldname data is transferred to Lua
* `caption 1`...: name shown on top of tab
* `draw_border` (optional): draw border
#### `box[<X>,<Y>;<W>,<H>;<color>]`
-* simple colored semitransparent box
+* Simple colored semitransparent box
* `x` and `y` position the box relative to the top left of the menu
* `w` and `h` are the size of box
* `color` is color specified as a `ColorString`
#### `dropdown[<X>,<Y>;<W>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>]`
-* show a dropdown field
+* Show a dropdown field
* **Important note**: There are two different operation modes:
1. handle directly on change (only changed dropdown is submitted)
2. read the value on pressing a button (all dropdown values are available)
* `x` and `y` position of dropdown
-* width of dropdown
-* fieldname data is transferred to Lua
-* items to be shown in dropdown
-* index of currently selected dropdown item
+* Width of dropdown
+* Fieldname data is transferred to Lua
+* Items to be shown in dropdown
+* Index of currently selected dropdown item
-#### `checkbox[<X>,<Y>;<name>;<label>;<selected>;<tooltip>]`
-* show a checkbox
+#### `checkbox[<X>,<Y>;<name>;<label>;<selected>]`
+* Show a checkbox
* `x` and `y`: position of checkbox
* `name` fieldname data is transferred to Lua
* `label` to be shown left of checkbox
* `selected` (optional): `true`/`false`
-* `tooltip` (optional)
#### `scrollbar[<X>,<Y>;<W>,<H>;<orientation>;<name>;<value>]`
-* show a scrollbar
-* there are two ways to use it:
+* Show a scrollbar
+* There are two ways to use it:
1. handle the changed event (only changed scrollbar is available)
2. read the value on pressing a button (all scrollbars are available)
* `x` and `y`: position of trackbar
* `w` and `h`: width and height
* `orientation`: `vertical`/`horizontal`
-* fieldname data is transferred to Lua
-* value this trackbar is set to (`0`-`1000`)
-* see also `minetest.explode_scrollbar_event` (main menu: `engine.explode_scrollbar_event`)
+* Fieldname data is transferred to Lua
+* Value this trackbar is set to (`0`-`1000`)
+* See also `minetest.explode_scrollbar_event` (main menu: `engine.explode_scrollbar_event`)
#### `table[<X>,<Y>;<W>,<H>;<name>;<cell 1>,<cell 2>,...,<cell n>;<selected idx>]`
-* show scrollable table using options defined by the previous `tableoptions[]`
-* displays cells as defined by the previous `tablecolumns[]`
+* Show scrollable table using options defined by the previous `tableoptions[]`
+* Displays cells as defined by the previous `tablecolumns[]`
* `x` and `y`: position the itemlist relative to the top left of the menu
* `w` and `h` are the size of the itemlist
* `name`: fieldname sent to server on row select or doubleclick
* `cell 1`...`cell n`: cell contents given in row-major order
* `selected idx`: index of row to be selected within table (first row = `1`)
-* see also `minetest.explode_table_event` (main menu: `engine.explode_table_event`)
+* See also `minetest.explode_table_event` (main menu: `engine.explode_table_event`)
#### `tableoptions[<opt 1>;<opt 2>;...]`
-* sets options for `table[]`
+* Sets options for `table[]`
* `color=#RRGGBB`
* default text color (`ColorString`), defaults to `#FFFFFF`
* `background=#RRGGBB`
* only useful when there is a column of type "tree"
#### `tablecolumns[<type 1>,<opt 1a>,<opt 1b>,...;<type 2>,<opt 2a>,<opt 2b>;...]`
-* sets columns for `table[]`
-* types: `text`, `image`, `color`, `indent`, `tree`
+* Sets columns for `table[]`
+* Types: `text`, `image`, `color`, `indent`, `tree`
* `text`: show cell contents as text
* `image`: cell contents are an image index, use column options to define images
- * `colo`: cell contents are a ColorString and define color of following cell
+ * `color`: cell contents are a ColorString and define color of following cell
* `indent`: cell contents are a number and define indentation of following cell
* `tree`: same as indent, but user can open and close subtrees (treeview-like)
-* column options:
+* Column options:
* `align=<value>`
* for `text` and `image`: content alignment within cells.
Available values: `left` (default), `center`, `right`, `inline`
* `"nodemeta:<X>,<Y>,<Z>"`: Any node metadata
* `"detached:<name>"`: A detached inventory
+Player Inventory lists
+----------------------
+* `main`: list containing the default inventory
+* `craft`: list containing the craft input
+* `craftpreview`: list containing the craft output
+* `hand`: list containing an override for the empty hand
+
`ColorString`
-------------
`#RGB` defines a color in hexadecimal format.
(e.g. `colorname#08`). For named colors the hexadecimal string representing the alpha
value must (always) be two hexadecimal digits.
-Vector helpers
---------------
-
-* `vector.new([x[, y, z]])`: returns a vector.
- * `x` is a table or the `x` position.
-
+`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"`
+
+Escape sequences
+----------------
+Most text can contain escape sequences, that can for example color the text.
+There are a few exceptions: tab headers, dropdowns and vertical labels can't.
+The following functions provide escape sequences:
+* `core.get_color_escape_sequence(color)`:
+ * `color` is a ColorString
+ * The escape sequence sets the text color to `color`
+* `core.colorize(color, message)`:
+ * Equivalent to:
+ `core.get_color_escape_sequence(color) ..
+ message ..
+ core.get_color_escape_sequence("#ffffff")`
+* `color.get_background_escape_sequence(color)`
+ * `color` is a ColorString
+ * The escape sequence sets the background of the whole text element to
+ `color`. Only defined for item descriptions and tooltips.
+* `color.strip_foreground_colors(str)`
+ * Removes foreground colors added by `get_color_escape_sequence`.
+* `color.strip_background_colors(str)`
+ * Removes background colors added by `get_background_escape_sequence`.
+* `color.strip_colors(str)`
+ * Removes all color escape sequences.
+
+Spatial Vectors
+---------------
+* `vector.new(a[, b, c])`: returns a vector:
+ * A copy of `a` if `a` is a vector.
+ * `{x = a, y = b, z = c}`, if all `a, b, c` are defined
* `vector.direction(p1, p2)`: returns a vector
* `vector.distance(p1, p2)`: returns a number
* `vector.length(v)`: returns a number
* `vector.normalize(v)`: returns a vector
-* `vector.round(v)`: returns a vector
+* `vector.floor(v)`: returns a vector, each dimension rounded down
+* `vector.round(v)`: returns a vector, each dimension rounded to nearest int
* `vector.apply(v, func)`: returns a vector
* `vector.equals(v1, v2)`: returns a boolean
+* `vector.sort(v1, v2)`: returns minp, maxp vectors of the cuboid defined by v1 and v2
For the following functions `x` can be either a vector or a number:
* `vector.add(v, x)`: returns a vector
* `vector.subtract(v, x)`: returns a vector
-* `vector.multiply(v, x)`: returns a vector
-* `vector.divide(v, x)`: returns a vector
+* `vector.multiply(v, x)`: returns a scaled vector or Schur product
+* `vector.divide(v, x)`: returns a scaled vector or Schur quotient
Helper functions
------------------
+----------------
* `dump2(obj, name="_", dumped={})`
* Return object serialized as a string, handles reference loops
* `dump(obj, dumped={})`
* e.g. `string:split("a,b", ",") == {"a","b"}`
* `string:trim()`
* e.g. `string.trim("\n \t\tfoo bar\t ") == "foo bar"`
-* `minetest.pos_to_string({x=X,y=Y,z=Z})`: returns `"(X,Y,Z)"`
+* `minetest.pos_to_string({x=X,y=Y,z=Z}, decimal_places))`: returns `"(X,Y,Z)"`
* Convert position to a printable string
+ Optional: 'decimal_places' will round the x, y and z of the pos to the given decimal place.
* `minetest.string_to_pos(string)`: returns a position
* Same but in reverse. Returns `nil` if the string can't be parsed to a position.
+* `minetest.string_to_area("(X1, Y1, Z1) (X2, Y2, Z2)")`: returns two positions
+ * Converts a string representing an area box into two positions
* `minetest.formspec_escape(string)`: returns a string
* escapes the characters "[", "]", "\", "," and ";", which can not be used in formspecs
* `minetest.is_yes(arg)`
- * returns whether `arg` can be interpreted as yes
+ * returns true if passed 'y', 'yes', 'true' or a number that isn't zero.
* `minetest.get_us_time()`
- * returns time with microsecond precision
+ * returns time with microsecond precision. May not return wall time.
* `table.copy(table)`: returns a table
* returns a deep copy of `table`
* `minetest.get_worldpath()`: returns e.g. `"/home/user/.minetest/world"`
* Useful for storing custom data
* `minetest.is_singleplayer()`
-* `minetest.features`
- * table containing API feature flags: `{foo=true, bar=true}`
+* `minetest.features`: Table containing API feature flags
+ {
+ glasslike_framed = true,
+ nodebox_as_selectionbox = true,
+ chat_send_player_param3 = true,
+ get_all_craft_recipes_works = true,
+ use_texture_alpha = true,
+ -- ^ The transparency channel of textures can be used optionally
+ no_legacy_abms = true,
+ -- ^ Tree and grass ABMs are no longer done from C++
+ texture_names_parens = true,
+ -- ^ Texture grouping is possible using parentheses
+ area_store_custom_ids = true,
+ -- ^ Unique Area ID for AreaStore:insert_area
+ add_entity_with_staticdata = true,
+ -- ^ add_entity supports passing initial staticdata to on_activate
+ no_chat_message_prediction = true,
+ -- ^ Chat messages are no longer predicted
+ }
* `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 a player
+ Example return value:
+ {
+ address = "127.0.0.1", -- IP address of client
+ ip_version = 4, -- IPv4 / IPv6
+ min_rtt = 0.01, -- minimum round trip time
+ max_rtt = 0.2, -- maximum round trip time
+ avg_rtt = 0.02, -- average round trip time
+ min_jitter = 0.01, -- minimum packet time jitter
+ max_jitter = 0.5, -- maximum packet time jitter
+ avg_jitter = 0.03, -- average packet time jitter
+ connection_uptime = 200, -- seconds since client connected
+
+ -- 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.
+* `minetest.get_version()`: returns a table containing components of the
+ engine version. Components:
+ * `project`: Name of the project, eg, "Minetest"
+ * `string`: Simple version, eg, "1.2.3-dev"
+ * `hash`: Full git version (only set if available), eg, "1.2.3-dev-01234567-dirty"
+ Use this for informational purposes only. The information in the returned
+ table does not represent the capabilities of the engine, nor is it
+ reliable or verifyable. Compatible forks will have a different name and
+ version entirely. To check for the presence of engine features, test
+ whether the functions exported by the wanted features exist. For example:
+ `if core.nodeupdate then ... end`.
### Logging
-* `minetest.debug(line)`
- * Always printed to `stderr` and logfile (`print()` is redirected here)
-* `minetest.log(line)`
-* `minetest.log(loglevel, line)`
- * `loglevel` is one of `"error"`, `"action"`, `"info"`, `"verbose"`
+* `minetest.debug(...)`
+ * Equivalent to `minetest.log(table.concat({...}, "\t"))`
+* `minetest.log([level,] text)`
+ * `level` is one of `"none"`, `"error"`, `"warning"`, `"action"`,
+ `"info"`, or `"verbose"`. Default is `"none"`.
### Registration functions
Call these functions only at load time!
* `minetest.register_entity(name, prototype table)`
* `minetest.register_abm(abm definition)`
+* `minetest.register_lbm(lbm definition)`
* `minetest.register_node(name, node definition)`
* `minetest.register_tool(name, item definition)`
* `minetest.register_craftitem(name, item definition)`
+* `minetest.unregister_item(name)`
* `minetest.register_alias(name, convert_to)`
+* `minetest.register_alias_force(name, convert_to)`
* `minetest.register_craft(recipe)`
+ * Check recipe table syntax for different types below.
+* `minetest.clear_craft(recipe)`
+ * Will erase existing craft based either on output item or on input recipe.
+ * Specify either output or input only. If you specify both, input will be ignored. For input use the same recipe table
+ syntax as for `minetest.register_craft(recipe)`. For output specify only the item, without a quantity.
+ * If no erase candidate could be found, Lua exception will be thrown.
+ * Warning! The type field ("shaped","cooking" or any other) will be ignored if the recipe
+ contains output. Erasing is then done independently from the crafting method.
* `minetest.register_ore(ore definition)`
+* `minetest.register_biome(biome definition)`
* `minetest.register_decoration(decoration definition)`
* `minetest.override_item(name, redefinition)`
* Overrides fields of an item registered with register_node/tool/craftitem.
* Note: Item must already be defined, (opt)depend on the mod defining it.
* Example: `minetest.override_item("default:mese", {light_source=LIGHT_MAX})`
-
* `minetest.clear_registered_ores()`
+* `minetest.clear_registered_biomes()`
* `minetest.clear_registered_decorations()`
### Global callback registration functions
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.
+ Non-modifiers receive the final hp change calculated by the modifiers.
* `minetest.register_on_respawnplayer(func(ObjectRef))`
* Called when player is to be respawned
* Called _before_ repositioning of player occurs
* If it returns a string, the player is disconnected with that string as reason
* `minetest.register_on_joinplayer(func(ObjectRef))`
* Called when a player joins the game
-* `minetest.register_on_leaveplayer(func(ObjectRef))`
+* `minetest.register_on_leaveplayer(func(ObjectRef, timed_out))`
* Called when a player leaves the game
+ * `timed_out`: True for timeout, false for other reasons.
* `minetest.register_on_cheat(func(ObjectRef, cheat))`
* Called when a player cheats
* `cheat`: `{type=<cheat_type>}`, where `<cheat_type>` is one of:
- * `"moved_too_fast"`
- * `"interacted_too_far"`
- * `"finished_unknown_dig"`
+ * `moved_too_fast`
+ * `interacted_too_far`
+ * `interacted_while_dead`
+ * `finished_unknown_dig`
* `dug_unbreakable`
* `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
### Other registration functions
* `minetest.register_chatcommand(cmd, chatcommand definition)`
+ * Adds definition to minetest.registered_chatcommands
+* `minetest.override_chatcommand(name, redefinition)`
+ * Overrides fields of a chatcommand registered with register_chatcommand.
+* `minetest.unregister_chatcommand(name)`
+ * Unregisters a chatcommands registered with register_chatcommand.
* `minetest.register_privilege(name, definition)`
* `definition`: `"description text"`
- * `definition`: `{ description = "description text", give_to_singleplayer = boolean, -- default: true }`
+ * `definition`: `{ description = "description text", give_to_singleplayer = boolean}`
+ the default of `give_to_singleplayer` is true
+ * To allow players with basic_privs to grant, see basic_privs minetest.conf setting.
* `minetest.register_authentication_handler(handler)`
* See `minetest.builtin_auth_handler` in `builtin.lua` for reference
### 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.notify_authentication_modified(name)`
* Should be called by the authentication handler if privileges changes.
* To report everybody, set `name=nil`.
+* `minetest.check_password_entry(name, entry, password)`
+ * Returns true if the "db entry" for a player with name matches given
+ * password, false otherwise.
+ * The "db entry" is the usually player-individual value that is derived
+ * from the player's chosen password and stored on the server in order to allow
+ * authentication whenever the player desires to log in.
+ * Only use this function for making it possible to log in via the password from
+ * via protocols like IRC, other uses for inside the game are frowned upon.
* `minetest.get_password_hash(name, raw_password)`
- * Convert a name-password pair to a password hash that Minetest can use
+ * Convert a name-password pair to a password hash that Minetest can use.
+ * The returned value alone is not a good basis for password checks based
+ * on comparing the password hash in the database with the password hash
+ * from the function, with an externally provided password, as the hash
+ * in the db might use the new SRP verifier format.
+ * For this purpose, use minetest.check_password_entry instead.
* `minetest.string_to_privs(str)`: returns `{priv1=true,...}`
* `minetest.privs_to_string(privs)`: returns `"priv1,priv2,..."`
* Convert between two privilege representations
* `minetest.set_player_privs(name, {priv1=true,...})`
* `minetest.get_player_privs(name) -> {priv1=true,...}`
* `minetest.auth_reload()`
-* `minetest.check_player_privs(name, {priv1=true,...})`: returns `bool, missing_privs`
- * A quickhand for checking privileges
+* `minetest.check_player_privs(player_or_name, ...)`: returns `bool, missing_privs`
+ * A quickhand for checking privileges.
+ * `player_or_name`: Either a Player object or the name of a player.
+ * `...` is either a list of strings, e.g. `"priva", "privb"` or
+ a table, e.g. `{ priva = true, privb = true }`.
* `minetest.get_player_ip(name)`: returns an IP address string
`minetest.set_player_password`, `minetest_set_player_privs`, `minetest_get_player_privs`
* `minetest.set_node(pos, node)`
* `minetest.add_node(pos, node): alias set_node(pos, node)`
* Set node at position (`node = {name="foo", param1=0, param2=0}`)
-* `minetest.swap_node(pos, node`
+* `minetest.swap_node(pos, node)`
* Set node at position, but don't remove metadata
* `minetest.remove_node(pos)`
* Equivalent to `set_node(pos, "air")`
* `minetest.get_node(pos)`
- * Returns `{name="ignore", ...}` for unloaded area
+ * Returns the node at the given position as table in the format
+ `{name="node_name", param1=0, param2=0}`, returns `{name="ignore", param1=0, param2=0}`
+ for unloaded areas.
* `minetest.get_node_or_nil(pos)`
- * Returns `nil` for unloaded area
-* `minetest.get_node_light(pos, timeofday)` returns a number between `0` and `15` or `nil`
+ * Same as `get_node` but returns `nil` for unloaded areas.
+* `minetest.get_node_light(pos, timeofday)`
+ * Gets the light value at the given position. Note that the light value
+ "inside" the node at the given position is returned, so you usually want
+ to get the light value of a neighbor.
+ * `pos`: The position where to measure the light.
* `timeofday`: `nil` for current time, `0` for night, `0.5` for day
-
+ * Returns a number between `0` and `15` or `nil`
* `minetest.place_node(pos, node)`
* Place node with the same effects that a player would cause
* `minetest.dig_node(pos)`
* Returns `true` if successful, `false` on failure (e.g. protected location)
* `minetest.punch_node(pos)`
* Punch node with the same effects that a player would cause
+* `minetest.spawn_falling_node(pos)`
+ * Change node into falling node
+ * Returns `true` if successful, `false` on failure
* `minetest.find_nodes_with_meta(pos1, pos2)`
* Get a table of positions of nodes that have metadata within a region {pos1, pos2}
* `minetest.get_node_timer(pos)`
* Get `NodeTimerRef`
-* `minetest.add_entity(pos, name)`: Spawn Lua-defined entity at position
+* `minetest.add_entity(pos, name, [staticdata])`: Spawn Lua-defined entity at position
* Returns `ObjectRef`, or `nil` if failed
* `minetest.add_item(pos, item)`: Spawn item
* Returns `ObjectRef`, or `nil` if failed
* `minetest.get_player_by_name(name)`: Get an `ObjectRef` to a player
* `minetest.get_objects_inside_radius(pos, radius)`
+ * `radius`: using an euclidean metric
* `minetest.set_timeofday(val)`
* `val` is between `0` and `1`; `0` for midnight, `0.5` for midday
* `minetest.get_timeofday()`
* `minetest.get_gametime()`: returns the time, in seconds, since the world was created
+* `minetest.get_day_count()`: returns number days elapsed since world was created,
+ * accounting for time changes.
* `minetest.find_node_near(pos, radius, nodenames)`: returns pos or `nil`
+ * `radius`: using a maximum metric
* `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
* `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_biome_id(biome_name)`
+ * Returns the biome id, as used in the biomemap Mapgen object, for a
+ given biome_name string.
* `minetest.get_mapgen_params()` Returns mapgen parameters, a table containing
`mgname`, `seed`, `chunksize`, `water_level`, and `flags`.
+ * Deprecated: use minetest.get_mapgen_setting(name) instead
* `minetest.set_mapgen_params(MapgenParams)`
+ * Deprecated: use minetest.set_mapgen_setting(name, value, override) instead
* Set map generation parameters
* Function cannot be called after the registration period; only initialization
and `on_mapgen_init`
* `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.get_mapgen_setting(name)`
+ * Gets the *active* mapgen setting (or nil if none exists) in string format with the following
+ order of precedence:
+ 1) Settings loaded from map_meta.txt or overrides set during mod execution
+ 2) Settings set by mods without a metafile override
+ 3) Settings explicitly set in the user config file, minetest.conf
+ 4) Settings set as the user config default
+* `minetest.get_mapgen_setting_noiseparams(name)`
+ * Same as above, but returns the value as a NoiseParams table if the setting `name` exists
+ and is a valid NoiseParams
+* `minetest.set_mapgen_setting(name, value, [override_meta])`
+ * Sets a mapgen param to `value`, and will take effect if the corresponding mapgen setting
+ is not already present in map_meta.txt.
+ * `override_meta` is an optional boolean (default: `false`). If this is set to true,
+ the setting will become the active setting regardless of the map metafile contents.
+ * Note: to set the seed, use "seed", not "fixed_map_seed"
+* `minetest.set_mapgen_setting_noiseparams(name, value, [override_meta])`
+ * Same as above, except value is a NoiseParams table.
* `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.clear_objects([options])`
+ * Clear all objects in the environment
+ * Takes an optional table as an argument with the field `mode`.
+ * mode = `"full"`: Load and go through every mapblock, clearing objects (default).
+ * mode = `"quick"`: Clear objects immediately in loaded mapblocks;
+ clear objects in unloaded mapblocks only when the mapblocks are next activated.
+* `minetest.emerge_area(pos1, pos2, [callback], [param])`
+ * Queue all blocks in the area from `pos1` to `pos2`, inclusive, to be asynchronously
+ * fetched from memory, loaded from disk, or if inexistent, generates them.
+ * If `callback` is a valid Lua function, this will be called for each block emerged.
+ * The function signature of callback is:
+ * `function EmergeAreaCallback(blockpos, action, calls_remaining, param)`
+ * - `blockpos` is the *block* coordinates of the block that had been emerged
+ * - `action` could be one of the following constant values:
+ * `core.EMERGE_CANCELLED`, `core.EMERGE_ERRORED`, `core.EMERGE_FROM_MEMORY`,
+ * `core.EMERGE_FROM_DISK`, `core.EMERGE_GENERATED`
+ * - `calls_remaining` is the number of callbacks to be expected after this one
+ * - `param` is the user-defined parameter passed to emerge_area (or nil if the
+ * parameter was absent)
* `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`
* returns a table of 3D points representing a path from `pos1` to `pos2` or `nil`
* `pos1`: start position
* `pos2`: end position
- * `searchdistance`: number of blocks to search in each direction
+ * `searchdistance`: number of blocks to search in each direction using a maximum metric
* `max_jump`: maximum height difference to consider walkable
* `max_drop`: maximum height difference to consider droppable
* `algorithm`: One of `"A*_noprefetch"` (default), `"A*"`, `"Dijkstra"`
* `minetest.spawn_tree (pos, {treedef})`
- * spawns L-System tree at given `pos` with definition in `treedef` table
+ * spawns L-system tree at given `pos` with definition in `treedef` table
+ * Warning: L-system generation currently creates lighting bugs in the form of mapblock-sized shadows.
+ Often these bugs appear as subtle shadows in water.
* `minetest.transforming_liquid_add(pos)`
* add node to liquid update queue
* `minetest.get_node_max_level(pos)`
* increase level of leveled node by level, default `level` equals `1`
* if `totallevel > maxlevel`, returns rest (`total-max`)
* can be negative for decreasing
+* `core.check_single_for_falling(pos)`
+ * causes an unsupported `group:falling_node` node to fall and causes an
+ unattached `group:attached_node` node to fall.
+ * does not spread these updates to neighbours.
+* `core.check_for_falling(pos)`
+ * causes an unsupported `group:falling_node` node to fall and causes an
+ unattached `group:attached_node` node to fall.
+ * spread these updates to neighbours and can cause a cascade
+ of nodes to fall.
### Inventory
`minetest.get_inventory(location)`: returns an `InvRef`
* `{type="player", name="celeron55"}`
* `{type="node", pos={x=, y=, z=}}`
* `{type="detached", name="creative"}`
-* `minetest.create_detached_inventory(name, callbacks)`: returns an `InvRef`
+* `minetest.create_detached_inventory(name, callbacks, [player_name])`: returns an `InvRef`
* callbacks: See "Detached inventory callbacks"
+ * player_name: Make detached inventory available to one player exclusively,
+ by default they will be sent to every player (even if not used).
+ Note that this parameter is mostly just a workaround and will be removed in future releases.
* 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
* `formname`: name passed to `on_player_receive_fields` callbacks.
It should follow the `"modname:<whatever>"` naming convention
* `formspec`: formspec to display
+* `minetest.close_formspec(playername, formname)`
+ * `playername`: name of player to close formspec
+ * `formname`: has to exactly match the one given in show_formspec, or the formspec will
+ not close.
+ * calling show_formspec(playername, formname, "") is equal to this expression
+ * to close a formspec regardless of the formname, call
+ minetest.close_formspec(playername, ""). USE THIS ONLY WHEN ABSOLUTELY NECESSARY!
* `minetest.formspec_escape(string)`: returns a string
* escapes the characters "[", "]", "\", "," and ";", which can not be used in formspecs
* `minetest.explode_table_event(string)`: returns a table
* Convert a facedir back into a vector aimed directly out the "back" of a node
* `minetest.dir_to_wallmounted(dir)`
* Convert a vector to a wallmounted value, used for `paramtype2="wallmounted"`
+* `minetest.wallmounted_to_dir(wallmounted)`
+ * Convert a wallmounted value back into a vector aimed directly out the "back" of a node
+* `minetest.dir_to_yaw(dir)`
+ * Convert a vector into a yaw (angle)
+* `minetest.yaw_to_dir(yaw)`
+ * Convert yaw (angle) to a vector
* `minetest.get_node_drops(nodename, toolname)`
* Returns list of item names.
* **Note**: This will be removed or modified in a future version.
`{ 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)
### Timing
* `minetest.after(time, func, ...)`
- * Call the function `func` after `time` seconds
+ * Call the function `func` after `time` seconds, may be fractional
* Optional: Variable number of arguments that are passed to `func`
### Server
-* `minetest.request_shutdown()`: request for server shutdown
+* `minetest.request_shutdown([message],[reconnect])`: request for server shutdown. Will display `message` to clients,
+ and `reconnect` == true displays a reconnect button.
* `minetest.get_server_status()`: returns server status string
+* `minetest.get_server_uptime()`: returns the server uptime in seconds
### Bans
* `minetest.get_ban_list()`: returns the ban list (same as `minetest.get_ban_description("")`)
* `minetest.add_particlespawner(particlespawner definition)`
* Add a `ParticleSpawner`, an object that spawns an amount of particles over `time` seconds
- * Returns an `id`
+ * Returns an `id`, and -1 if adding didn't succeed
* `Deprecated: minetest.add_particlespawner(amount, time,
minpos, maxpos,
minvel, maxvel,
* `replacements` = `{["old_name"] = "convert_to", ...}`
* `force_placement` is a boolean indicating whether nodes other than `air` and
`ignore` are replaced by the schematic
+ * Returns nil if the schematic could not be loaded.
+
+* `minetest.place_schematic_on_vmanip(vmanip, pos, schematic, rotation, replacement, force_placement)`:
+ * This function is analagous to minetest.place_schematic, but places a schematic onto the
+ specified VoxelManip object `vmanip` instead of the whole map.
+ * Returns false if any part of the schematic was cut-off due to the VoxelManip not
+ containing the full area required, and true if the whole schematic was able to fit.
+ * Returns nil if the schematic could not be loaded.
+ * After execution, any external copies of the VoxelManip contents are invalidated.
* `minetest.serialize_schematic(schematic, format, options)`
* Return the serialized schematic specified by schematic (see: Schematic specifier)
* 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.
+### HTTP Requests:
+* `minetest.request_http_api()`:
+ * returns `HTTPApiTable` containing http functions if the calling mod has been granted
+ access by being listed in the `secure.http_mods` or `secure.trusted_mods` setting,
+ otherwise returns `nil`.
+ * The returned table contains the functions `fetch`, `fetch_async` and `fetch_async_get`
+ described below.
+ * Only works at init time and must be called from the mod's main scope (not from a function).
+ * Function only exists if minetest server was built with cURL support.
+ * **DO NOT ALLOW ANY OTHER MODS TO ACCESS THE RETURNED TABLE, STORE IT IN
+ A LOCAL VARIABLE!**
+* `HTTPApiTable.fetch(HTTPRequest req, callback)`
+ * Performs given request asynchronously and calls callback upon completion
+ * callback: `function(HTTPRequestResult res)`
+ * Use this HTTP function if you are unsure, the others are for advanced use.
+* `HTTPApiTable.fetch_async(HTTPRequest req)`: returns handle
+ * Performs given request asynchronously and returns handle for `HTTPApiTable.fetch_async_get`
+* `HTTPApiTable.fetch_async_get(handle)`: returns HTTPRequestResult
+ * Return response data for given asynchronous HTTP request
+
+### Storage API:
+* `minetest.get_mod_storage()`:
+ * returns reference to mod private `StorageRef`
+ * must be called during mod load time
+
### Misc.
* `minetest.get_connected_players()`: returns list of `ObjectRefs`
+* `minetest.player_exists(name)`: boolean, whether player exists (regardless of online status)
+* `minetest.hud_replace_builtin(name, hud_definition)`
+ * Replaces definition of a builtin hud element
+ * `name`: `"breath"` or `"health"`
+ * `hud_definition`: definition to replace builtin definition
* `minetest.hash_node_position({x=,y=,z=})`: returns an 48-bit integer
* Gives a unique hash number for a node position (16+16+16=48bit)
* `minetest.get_position_from_hash(hash)`: returns a position
* See documentation on `minetest.compress()` for supported compression methods.
* currently supported.
* `...` indicates method-specific arguments. Currently, no methods use this.
+* `minetest.encode_base64(string)`: returns string encoded in base64
+ * Encodes a string in base64.
+* `minetest.decode_base64(string)`: returns string
+ * Decodes a string encoded in base64.
* `minetest.is_protected(pos, name)`: returns boolean
+ * Returns true, if player `name` shouldn't be abled to dig at `pos` or do other
+ actions, defineable by mods, due to some mod-defined ownership-like concept.
+ Returns false or nil, if the player is allowed to do such actions.
* This function should be overridden by protection mods and should be used to
check if a player can interact at a position.
* This function should call the old version of itself if the position is not
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)`
+* `minetest.forceload_block(pos[, transient])`
* forceloads the position `pos`.
* returns `true` if area could be forceloaded
+ * If `transient` is `false` or absent, the forceload will be persistent
+ (saved between server runs). If `true`, the forceload will be transient
+ (not saved between server runs).
-* `minetest.forceload_free_block(pos)`
+* `minetest.forceload_free_block(pos[, transient])`
* stops forceloading the position `pos`
-Please note that forceloaded areas are saved when the server restarts.
+ * If `transient` is `false` or absent, frees a persistent forceload.
+ If `true`, frees a transient forceload.
+
+* `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 and must be called from the mod's main scope (not from a function).
+ * **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.
+* `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`
* Map of object references, indexed by active object id
* `minetest.luaentities`
* Map of Lua entities, indexed by active object id
+* `minetest.registered_chatcommands`
+ * Map of registered chat command definitions, indexed by name
* `minetest.registered_ores`
* List of registered ore definitions.
+* `minetest.registered_biomes`
+ * List of registered biome definitions.
* `minetest.registered_decorations`
* List of registered decoration definitions.
Class reference
---------------
-### `NodeMetaRef`
-Node metadata: reference extra data and functionality stored in a node.
-Can be gotten via `minetest.get_meta(pos)`.
+### `MetaDataRef`
+See `StorageRef`, `NodeMetaRef` and `ItemStackMetaRef`.
#### Methods
* `set_string(name, value)`
* `get_int(name)`
* `set_float(name, value)`
* `get_float(name)`
-* `get_inventory()`: returns `InvRef`
-* `to_table()`: returns `nil` or `{fields = {...}, inventory = {list1 = {}, ...}}`
+* `to_table()`: returns `nil` or a table with keys:
+ * `fields`: key-value storage
+ * `inventory`: `{list1 = {}, ...}}` (NodeMetaRef only)
* `from_table(nil or {})`
- * See "Node Metadata"
+ * Any non-table value will clear the metadata
+ * See "Node Metadata" for an example
+ * returns `true` on success
+
+### `NodeMetaRef`
+Node metadata: reference extra data and functionality stored in a node.
+Can be obtained via `minetest.get_meta(pos)`.
-### `NoteTimerRef`
+#### Methods
+* All methods in MetaDataRef
+* `get_inventory()`: returns `InvRef`
+
+### `ItemStackMetaRef`
+ItemStack metadata: reference extra data and functionality stored in a stack.
+Can be obtained via `item:get_meta()`.
+
+#### Methods
+* All methods in MetaDataRef
+
+### `StorageRef`
+Mod metadata: per mod metadata, saved automatically.
+Can be obtained via `minetest.get_mod_storage()` during load time.
+
+#### Methods
+* All methods in MetaDataRef
+
+### `NodeTimerRef`
Node Timers: a high resolution persistent per-node timer.
Can be gotten via `minetest.get_node_timer(pos)`.
#### 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_pos()`: returns `{x=num, y=num, z=num}`
+* `set_pos(pos)`; `pos`=`{x=num, y=num, z=num}`
+* `move_to(pos, continuous=false)`: interpolated move
* `punch(puncher, time_from_last_punch, tool_capabilities, direction)`
* `puncher` = another `ObjectRef`,
* `time_from_last_punch` = time since last punch action of the puncher
* `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
+* `get_nametag_attributes()`
+ * returns a table with the attributes of the nametag of an object
+ * {
+ color = {a=0..255, r=0..255, g=0..255, b=0..255},
+ text = "",
+ }
+* `set_nametag_attributes(attributes)`
+ * sets the attributes of the nametag of an object
+ * `attributes`:
+ {
+ color = ColorSpec,
+ text = "My Nametag",
+ }
##### LuaEntitySAO-only (no-op for other objects)
-* `setvelocity({x=num, y=num, z=num})`
-* `getvelocity()`: returns `{x=num, y=num, z=num}`
-* `setacceleration({x=num, y=num, z=num})`
-* `getacceleration()`: returns `{x=num, y=num, z=num}`
-* `setyaw(radians)`
-* `getyaw()`: returns number in radians
-* `settexturemod(mod)`
-* `setsprite(p={x=0,y=0}, num_frames=1, framelength=0.2,
+* `set_velocity({x=num, y=num, z=num})`
+* `get_velocity()`: returns `{x=num, y=num, z=num}`
+* `set_acceleration({x=num, y=num, z=num})`
+* `get_acceleration()`: returns `{x=num, y=num, z=num}`
+* `set_yaw(radians)`
+* `get_yaw()`: returns number in radians
+* `set_texture_mod(mod)`
+* `get_texture_mod()` returns current texture modifier
+* `set_sprite(p={x=0,y=0}, num_frames=1, framelength=0.2,
select_horiz_by_yawpitch=false)`
* Select sprite from spritesheet with optional animation and DM-style
texture selection based on yaw relative to camera
##### Player-only (no-op for other objects)
* `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)
-* `set_look_pitch(radians)`: sets look pitch
-* `set_look_yaw(radians)`: sets look yaw
+* `get_look_vertical()`: pitch in radians
+ * Angle ranges between -pi/2 and pi/2, which are straight up and down respectively.
+* `get_look_horizontal()`: yaw in radians
+ * Angle is counter-clockwise from the +z direction.
+* `set_look_vertical(radians)`: sets look pitch
+ * radians - Angle from looking forward, where positive is downwards.
+* `set_look_horizontal(radians)`: sets look yaw
+ * radians - Angle from the +z direction, where positive is counter-clockwise.
+* `get_look_pitch()`: pitch in radians - Deprecated as broken. Use get_look_vertical.
+ * Angle ranges between -pi/2 and pi/2, which are straight down and up respectively.
+* `get_look_yaw()`: yaw in radians - Deprecated as broken. Use get_look_horizontal.
+ * Angle is counter-clockwise from the +x direction.
+* `set_look_pitch(radians)`: sets look pitch - Deprecated. Use set_look_vertical.
+* `set_look_yaw(radians)`: sets look yaw - Deprecated. Use set_look_horizontal.
* `get_breath()`: returns players breath
* `set_breath(value)`: sets players breath
* values:
* `0`: player is drowning,
* `1`-`10`: remaining number of bubbles
* `11`: bubbles bar is not shown
+* `set_attribute(attribute, value)`: sets an extra attribute with value on player
+* `get_attribute(attribute)`: returns value for extra attribute. Returns nil if no attribute found.
* `set_inventory_formspec(formspec)`
* Redefine player's inventory form
* Should usually be called in on_joinplayer
* `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`)
+* `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
* element `stat` values: `position`, `name`, `scale`, `text`, `number`, `item`, `dir`
* `hud_get(id)`: gets the HUD element definition structure of the specified ID
* `hud_set_flags(flags)`: sets specified HUD flags to `true`/`false`
- * `flags`: (is visible) `hotbar`, `healthbar`, `crosshair`, `wielditem`
+ * `flags`: (is visible) `hotbar`, `healthbar`, `crosshair`, `wielditem`, `minimap`
* pass a table containing a `true`/`false` value of each flag to be set or unset
* if a flag equals `nil`, the flag is not modified
+ * note that setting `minimap` modifies the client's permission to view the minimap -
+ * the client may locally elect to not view the minimap
* `hud_get_flags()`: returns a table containing status of hud flags
- * returns `{ hotbar=true, healthbar=true, crosshair=true, wielditem=true, breathbar=true }`
+ * returns `{ hotbar=true, healthbar=true, crosshair=true, wielditem=true, breathbar=true, minimap=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_replace_builtin(name, hud_definition)`
- * replace definition of a builtin hud element
- * `name`: `"breath"` or `"health"`
- * `hud_definition`: definition to replace builtin definition
+* `hud_get_hotbar_selected_image`: returns texturename
* `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(walk, dig, walk+dig, frame_speed=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
{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_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 = { a = 0...255, r = 0...255, g = 0...255, b = 0...255 }
- }
+* `get_eye_offset()`: returns offset_first and offset_third
### `InvRef`
An `InvRef` is a reference to an inventory.
* `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.
#### Methods
* `is_empty()`: Returns `true` if stack is empty.
* `get_name()`: Returns item name (e.g. `"default:stone"`).
-* `set_name(item_name)`: Returns boolean success.
- Clears item on failure.
+* `set_name(item_name)`: Returns boolean whether item was cleared
* `get_count()`: Returns number of items on the stack.
-* `set_count(count)`
+* `set_count(count)`: Returns boolean whether item was cleared
* `get_wear()`: Returns tool wear (`0`-`65535`), `0` for non-tools.
-* `set_wear(wear)`: Returns boolean success.
- Clears item on failure.
-* `get_metadata()`: Returns metadata (a string attached to an item stack).
-* `set_metadata(metadata)`: Returns true.
+* `set_wear(wear)`: Returns boolean whether item was cleared
+* `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.
* `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
+ * This is only a rough approximation of a normal distribution with:
+ * mean = (max - min) / 2, and
+ * 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
+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)`
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
+* `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)`: Same as `get2dMap_flat`, but 3D noise
+* `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.
-It can be created via `VoxelManip()` or `minetest.get_voxel_manip()`.
-The map will be pre-loaded if two positions are passed to either.
+#### 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 very large areas of map at once - for example, if only
+setting a 5x5x5 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.
+
+#### 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() et al. 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:
+```
+core.CONTENT_UNKNOWN (ID for "unknown" nodes)
+core.CONTENT_AIR (ID for "air" nodes)
+core.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 of 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)`: Reads a chunk of map from the map containing the
- region formed by `p1` and `p2`.
+* `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()`: Writes the data loaded from the `VoxelManip` back to the map.
- * **important**: data must be set using `VoxelManip:set_data` before calling this
+ * **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
+* `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()`: 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`
-* `set_lighting(light, p1, p2)`: Set the lighting within the `VoxelManip` to a uniform value
+* `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;
* `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
+* `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)`: Calculate lighting within 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
+ 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
* 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)`
+ * `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`
+ * `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.
L-system trees
--------------
+**Warning**
+L-system generation currently creates lighting bugs in the form of mapblock-sized shadows.
+Often these bugs appear as subtle shadows in water.
### Tree definition
stepheight = 0,
automatic_face_movement_dir = 0.0,
-- ^ automatically set yaw to movement direction; offset in degrees; false to disable
+ automatic_face_movement_max_rotation_per_sec = -1,
+ -- ^ limit automatic rotation to this value in degrees per second. values < 0 no limit
+ backface_culling = true, -- false to disable backface_culling for model
+ nametag = "", -- by default empty, for players their name is shown if empty
+ nametag_color = <color>, -- sets color of nametag as ColorSpec
+ infotext = "", -- by default empty, text to be shown when pointed at object
}
### Entity definition (`register_entity`)
on_activate = function(self, staticdata, dtime_s),
on_step = function(self, dtime),
- on_punch = function(self, hitter),
+ on_punch = function(self, puncher, time_from_last_punch, tool_capabilities, dir),
on_rightclick = function(self, clicker),
get_staticdata = function(self),
-- ^ Called sometimes; the string returned is passed to on_activate when
-- the entity is re-activated from static state
- -- Also you can define arbitrary member variables here
- myvariable = whatever,
+ -- Also you can define arbitrary member variables here (see item definition for
+ -- more info)
+ _custom_field = whatever,
}
### ABM (ActiveBlockModifier) definition (`register_abm`)
{
+ label = "Lava cooling",
+ -- ^ Descriptive label for profiling purposes (optional).
+ -- Definitions with identical labels will be listed as one.
-- In the following two fields, also group:groupname will work.
nodenames = {"default:lava_source"},
- neighbors = {"default:water_source", "default:water_flowing"}, -- (any of these)
- -- ^ If left out or empty, any neighbor will do
- interval = 1.0, -- (operation interval)
- chance = 1, -- (chance of trigger is 1.0/this)
+ neighbors = {"default:water_source", "default:water_flowing"}, -- Any of these --[[
+ ^ If left out or empty, any neighbor will do ]]
+ interval = 1.0, -- Operation interval in seconds
+ chance = 1, -- Chance of trigger per-node per-interval is 1.0 / this
+ catch_up = true, -- If true, catch-up behaviour is enabled --[[
+ ^ The chance value is temporarily reduced when returning to
+ an area to simulate time lost by the area being unattended.
+ ^ Note chance value can often be reduced to 1 ]]
action = func(pos, node, active_object_count, active_object_count_wider),
}
+### LBM (LoadingBlockModifier) definition (`register_lbm`)
+
+ {
+ label = "Upgrade legacy doors",
+ -- ^ Descriptive label for profiling purposes (optional).
+ -- Definitions with identical labels will be listed as one.
+ name = "modname:replace_legacy_door",
+ nodenames = {"default:lava_source"},
+ -- ^ List of node names to trigger the LBM on.
+ -- Also non-registered nodes will work.
+ -- Groups (as of group:groupname) will work as well.
+ run_at_every_load = false,
+ -- ^ Whether to run the LBM's action every time a block gets loaded,
+ -- and not just for blocks that were saved last time before LBMs were
+ -- introduced to the world.
+ action = func(pos, node),
+ }
+
### Item definition (`register_node`, `register_craftitem`, `register_tool`)
{
description = "Steel Axe",
- groups = {}, -- key=name, value=rating; rating=1..3.
+ groups = {}, -- key = name, value = rating; rating = 1..3.
if rating not applicable, use 1.
- e.g. {wool=1, fluffy=3}
- {soil=2, outerspace=1, crumbly=1}
- {bendy=2, snappy=1},
- {hard=1, metal=1, spikes=1}
+ e.g. {wool = 1, fluffy = 3}
+ {soil = 2, outerspace = 1, crumbly = 1}
+ {bendy = 2, snappy = 1},
+ {hard = 1, metal = 1, spikes = 1}
inventory_image = "default_tool_steelaxe.png",
wield_image = "",
- wield_scale = {x=1,y=1,z=1},
+ wield_scale = {x = 1, y = 1, z = 1},
stack_max = 99,
range = 4.0,
liquids_pointable = false,
tool_capabilities = {
full_punch_interval = 1.0,
- max_drop_level=0,
- groupcaps={
+ max_drop_level = 0,
+ groupcaps = {
-- For example:
- snappy={times={[2]=0.80, [3]=0.40}, maxwear=0.05, maxlevel=1},
- choppy={times={[3]=0.90}, maxwear=0.05, maxlevel=0}
+ choppy = {times = {[1] = 2.50, [2] = 1.40, [3] = 1.00}, uses = 20, maxlevel = 2},
},
- damage_groups = {groupname=damage},
+ damage_groups = {groupname = damage},
},
node_placement_prediction = nil,
--[[
actual result to client in a short moment.
]]
sound = {
+ breaks = "default_tool_break", -- tools only
place = --[[<SimpleSoundSpec>]],
},
on_place = func(itemstack, placer, pointed_thing),
--[[
^ Shall place item and return the leftover itemstack
+ ^ The placer may be any ObjectRef or nil.
^ default: minetest.item_place ]]
+ on_secondary_use = func(itemstack, user, pointed_thing),
+ --[[
+ ^ Same as on_place but called when pointing at nothing.
+ ^ The user may be any ObjectRef or nil.
+ ^ pointed_thing : always { type = "nothing" }
+ ]]
on_drop = func(itemstack, dropper, pos),
--[[
^ Shall drop item and return the leftover itemstack
+ ^ The dropper may be any ObjectRef or nil.
^ default: minetest.item_drop ]]
on_use = func(itemstack, user, pointed_thing),
--[[
inventory, or an itemstack to replace the original itemstack.
e.g. itemstack:take_item(); return itemstack
^ Otherwise, the function is free to do what it wants.
+ ^ The user may be any ObjectRef or nil.
^ The default functions handle regular use cases.
]]
after_use = func(itemstack, user, node, digparams),
itemstack:add_wear(digparams.wear)
return itemstack
end
+ ^ The user may be any ObjectRef or nil.
+ ]]
+ _custom_field = whatever,
+ --[[
+ ^ Add your own custom fields. By convention, all custom field names
+ should start with `_` to avoid naming collisions with future engine
+ usage.
]]
}
### 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 enabled by default for most nodes
+ * 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
+* `{name="image.png", color=ColorSpec}`
+ * the texture's color will be multiplied with this color.
+ * the tile's color overrides the owning node's color in all cases.
* deprecated, yet still supported field names:
* `image` (name)
### Tile animation definition
-* `{type="vertical_frames", aspect_w=16, aspect_h=16, length=3.0}`
+
+ {
+ type = "vertical_frames",
+ aspect_w = 16,
+ -- ^ specify width of a frame in pixels
+ aspect_h = 16,
+ -- ^ specify height of a frame in pixels
+ length = 3.0,
+ -- ^ specify full loop length
+ }
+
+ {
+ type = "sheet_2d",
+ frames_w = 5,
+ -- ^ specify width in number of frames
+ frames_h = 3,
+ -- ^ specify height in number of frames
+ frame_length = 0.5,
+ -- ^ specify length of a single frame
+ }
### Node definition (`register_node`)
drawtype = "normal", -- See "Node drawtypes"
visual_scale = 1.0, --[[
- ^ Supported for drawtypes "plantlike", "signlike", "torchlike", "mesh".
- ^ For plantlike, the image will start at the bottom of the node; for the
- ^ other drawtypes, the image will be centered on the node.
+ ^ Supported for drawtypes "plantlike", "signlike", "torchlike",
+ ^ "firelike", "mesh".
+ ^ For plantlike and firelike, the image will start at the bottom of the
+ ^ node, for the other drawtypes the image will be centered on the node.
^ Note that positioning for "torchlike" may still change. ]]
tiles = {tile definition 1, def2, def3, def4, def5, def6}, --[[
^ Textures of node; +Y, -Y, +X, -X, +Z, -Z (old field name: tile_images)
special_tiles = {tile definition 1, Tile definition 2}, --[[
^ Special textures of node; used rarely (old field name: special_materials)
^ List can be shortened to needed length ]]
- alpha = 255,
+ color = ColorSpec, --[[
+ ^ The node's original color will be multiplied with this color.
+ ^ If the node has a palette, then this setting only has an effect
+ ^ in the inventory and on the wield item. ]]
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
+ palette = "palette.png", --[[
+ ^ The node's `param2` is used to select a pixel from the image
+ ^ (pixels are arranged from left to right and from top to bottom).
+ ^ The node's color will be multiplied with the selected pixel's
+ ^ color. Tiles can override this behavior.
+ ^ Only when `paramtype2` supports palettes. ]]
+ 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"
+ place_param2 = nil, -- Force value for param2 when player places node
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
walkable = true, -- If true, objects collide with node
diggable = true, -- If false, can never be dug
climbable = false, -- If true, can be climbed on (ladder)
buildable_to = false, -- If true, placed nodes can replace this node
+ floodable = false, -- If true, liquids flow into and replace this node
liquidtype = "none", -- "none"/"source"/"flowing"
liquid_alternative_flowing = "", -- Flowing version of source liquid
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?
+ liquid_renewable = true, --[[
+ ^ If true, a new liquid source can be created by placing two or more sources nearby ]]
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
+ light_source = 0, --[[
+ ^ Amount of light emitted by node.
+ ^ To set the maximum (currently 14), use the value 'minetest.LIGHT_MAX'.
+ ^ A value outside the range 0 to minetest.LIGHT_MAX causes undefined behavior.]]
damage_per_second = 0, -- If player is inside node, this damage is caused
node_box = {type="regular"}, -- See "Node boxes"
+ connects_to = nodenames, --[[
+ * Used for nodebox nodes with the type == "connected"
+ * Specifies to what neighboring nodes connections will be drawn
+ * e.g. `{"group:fence", "default:wood"}` or `"default:stone"` ]]
+ connect_sides = { "top", "bottom", "front", "left", "back", "right" }, --[[
+ ^ Tells connected nodebox nodes to connect only to these sides of this node. ]]
mesh = "model",
selection_box = {type="regular"}, -- See "Node boxes" --[[
^ If drawtype "nodebox" is used and selection_box is nil, then node_box is used. ]]
dig = <SimpleSoundSpec>, -- "__group" = group-based sound (default)
dug = <SimpleSoundSpec>,
place = <SimpleSoundSpec>,
+ place_failed = <SimpleSoundSpec>,
},
drop = "", -- Name of dropped node when dug. Default is the node itself.
-- Alternatively:
max_items = 1, -- Maximum number of items to drop.
items = { -- Choose max_items randomly from this list.
{
- items = {"foo:bar", "baz:frob"}, -- Choose one item randomly from this list.
- rarity = 1, -- Probability of getting is 1 / rarity.
+ items = {"foo:bar", "baz:frob"}, -- Items to drop.
+ rarity = 1, -- Probability of dropping is 1 / rarity.
},
},
},
on_construct = func(pos), --[[
- ^ Node constructor; always called after adding node
+ ^ Node constructor; called after adding node
^ Can set up metadata and stuff like that
+ ^ Not called for bulk node placement (i.e. schematics and VoxelManip)
^ default: nil ]]
on_destruct = func(pos), --[[
- ^ Node destructor; always called before removing node
+ ^ Node destructor; called before removing node
+ ^ Not called for bulk node placement (i.e. schematics and VoxelManip)
^ default: nil ]]
after_destruct = func(pos, oldnode), --[[
- ^ Node destructor; always called after removing node
+ ^ Node destructor; called after removing node
+ ^ Not called for bulk node placement (i.e. schematics and VoxelManip)
^ default: nil ]]
after_place_node = func(pos, placer, itemstack, pointed_thing) --[[
y_max = 64,
flags = "",
-- ^ Attributes for this ore generation
- noise_threshhold = 0.5,
+ noise_threshold = 0.5,
-- ^ If noise is above this threshold, ore is placed. Not needed for a uniform distribution
noise_params = {offset=0, scale=1, spread={x=100, y=100, z=100}, seed=23, octaves=3, persist=0.70}
-- ^ NoiseParams structure describing the perlin noise used for ore distribution.
-- ^ Can be a list of (or a single) biome names, IDs, or definitions.
}
+### Biome definition (`register_biome`)
+
+**Note**
+The Biome API is still in an experimental phase and subject to change.
+
+ {
+ name = "tundra",
+ node_dust = "default:snow",
+ -- ^ Node dropped onto upper surface after all else is generated.
+ node_top = "default:dirt_with_snow",
+ depth_top = 1,
+ -- ^ Node forming surface layer of biome and thickness of this layer.
+ node_filler = "default:permafrost",
+ depth_filler = 3,
+ -- ^ Node forming lower layer of biome and thickness of this layer.
+ node_stone = "default:bluestone",
+ -- ^ Node that replaces all stone nodes between roughly y_min and y_max.
+ node_water_top = "default:ice",
+ depth_water_top = 10,
+ -- ^ Node forming a surface layer in seawater with the defined thickness.
+ node_water = "",
+ -- ^ Node that replaces all seawater nodes not in the defined surface layer.
+ node_river_water = "default:ice",
+ -- ^ Node that replaces river water in mapgens that use default:river_water.
+ node_riverbed = "default:gravel",
+ depth_riverbed = 2,
+ -- ^ Node placed under river water and thickness of this layer.
+ y_min = 1,
+ y_max = 31000,
+ -- ^ Lower and upper limits for biome.
+ -- ^ Because biome is not recalculated for every node in a node column
+ -- ^ some biome materials can exceed their limits, especially stone.
+ -- ^ For each node column in a mapchunk, biome is only recalculated at column
+ -- ^ top and at each of these surfaces:
+ -- ^ Ground below air, water below air, ground below water.
+ -- ^ The selected biome then stays in effect for all nodes below until
+ -- ^ column base or the next biome recalculation.
+ heat_point = 0,
+ humidity_point = 50,
+ -- ^ Characteristic average temperature and humidity for the biome.
+ -- ^ These values create 'biome points' on a voronoi diagram that has heat
+ -- ^ and humidity as axes. The resulting voronoi cells determine which
+ -- ^ heat/humidity points belong to which biome, and therefore determine
+ -- ^ the area and location of each biome in the world.
+ -- ^ The biome points need to be carefully and evenly spaced on the voronoi
+ -- ^ diagram to result in roughly equal size biomes.
+ -- ^ Heat and humidity have average values of 50, vary mostly between
+ -- ^ 0 and 100 but also often exceed these values.
+ -- ^ Heat is not in degrees celcius, both values are abstract.
+ }
+
### Decoration definition (`register_decoration`)
{
deco_type = "simple", -- See "Decoration types"
place_on = "default:dirt_with_grass",
- -- ^ Node that decoration can be placed on
+ -- ^ Node (or list of nodes) that the decoration can be placed on
sidelen = 8,
-- ^ Size of divisions made in the chunk being generated.
-- ^ If the chunk size is not evenly divisible by sidelen, sidelen is made equal to the chunk size.
-- ^ Minimum and maximum `y` positions these decorations can be generated at.
-- ^ This parameter refers to the `y` position of the decoration base, so
-- the actual maximum height would be `height_max + size.Y`.
+ spawn_by = "default:water",
+ -- ^ Node (or list of nodes) that the decoration only spawns next to.
+ -- ^ Checks two horizontal planes of neighbouring nodes (including diagonal neighbours),
+ -- ^ one plane at Y = surface and one plane at Y = surface = + 1.
+ 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.
+ flags = "liquid_surface, force_placement",
+ -- ^ Flags for all decoration types.
+ -- ^ "liquid_surface": Instead of placement on the highest solid surface
+ -- ^ in a mapchunk column, placement is on the highest liquid surface.
+ -- ^ Placement is disabled if solid nodes are found above the liquid surface.
+ -- ^ "force_placement": Nodes other than "air" and "ignore" are replaced by the decoration.
----- Simple-type parameters
decoration = "default:grass",
-- ^ Number of nodes high the decoration is made.
-- ^ If height_max is not 0, this is the lower bound of the randomly selected height.
height_max = 0,
- -- ^ Number of nodes the decoration can be at maximum.
+ -- ^ 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.
- 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.
+ param2 = 0,
+ -- ^ Param2 value of placed decoration node.
----- Schematic-type parameters
schematic = "foobar.mts",
},
-- ^ See 'Schematic specifier' for details.
replacements = {["oldname"] = "convert_to", ...},
- flags = "place_center_x, place_center_y, place_center_z, force_placement",
+ flags = "place_center_x, place_center_y, place_center_z",
-- ^ Flags for schematic decorations. See 'Schematic attributes'.
rotation = "90" -- rotate schematic 90 degrees on placement
-- ^ Rotation can be "0", "90", "180", "270", or "random".
size = 1,
collisiondetection = false,
-- ^ collisiondetection: if true collides with physical objects
+ collision_removal = false,
+ -- ^ collision_removal: if true then particle is removed when it collides,
+ -- ^ requires collisiondetection = true to have any effect
vertical = false,
-- ^ vertical: if true faces player using y axis only
texture = "image.png",
-- ^ Uses texture (string)
- playername = "singleplayer"
+ playername = "singleplayer",
-- ^ optional, if specified spawns particle only on the player's client
+ animation = {Tile Animation definition},
+ -- ^ optional, specifies how to animate the particle texture
+ glow = 0
+ -- ^ optional, specify particle self-luminescence in darkness
}
+
### `ParticleSpawner` definition (`add_particlespawner`)
{
-- ^ minsize/maxsize, minexptime/maxexptime (expirationtime)
collisiondetection = false,
-- ^ collisiondetection: if true uses collision detection
+ collision_removal = false,
+ -- ^ collision_removal: if true then particle is removed when it collides,
+ -- ^ requires collisiondetection = true to have any effect
+ attached = ObjectRef,
+ -- ^ attached: if defined, particle positions, velocities and accelerations
+ -- ^ are relative to this object's position and yaw.
vertical = false,
-- ^ vertical: if true faces player using y axis only
texture = "image.png",
playername = "singleplayer"
-- ^ Playername is optional, if specified spawns particle only on the player's client
}
+
+### `HTTPRequest` definition (`HTTPApiTable.fetch_async`, `HTTPApiTable.fetch_async`)
+
+ {
+ url = "http://example.org",
+ timeout = 10,
+ -- ^ Timeout for connection in seconds. Default is 3 seconds.
+ post_data = "Raw POST request data string" OR { field1 = "data1", field2 = "data2" },
+ -- ^ Optional, if specified a POST request with post_data is performed.
+ -- ^ Accepts both a string and a table. If a table is specified, encodes table
+ -- ^ as x-www-form-urlencoded key-value pairs.
+ -- ^ If post_data ist not specified, a GET request is performed instead.
+ user_agent = "ExampleUserAgent",
+ -- ^ Optional, if specified replaces the default minetest user agent with given string
+ extra_headers = { "Accept-Language: en-us", "Accept-Charset: utf-8" },
+ -- ^ Optional, if specified adds additional headers to the HTTP request. You must make sure
+ -- ^ that the header strings follow HTTP specification ("Key: Value").
+ multipart = boolean
+ -- ^ Optional, if true performs a multipart HTTP request. Default is false.
+ }
+
+### `HTTPRequestResult` definition (`HTTPApiTable.fetch` callback, `HTTPApiTable.fetch_async_get`)
+
+ {
+ completed = true,
+ -- ^ If true, the request has finished (either succeeded, failed or timed out)
+ succeeded = true,
+ -- ^ If true, the request was succesful
+ timeout = false,
+ -- ^ If true, the request timed out
+ code = 200,
+ -- ^ HTTP status code
+ data = "response"
+ }
projects / oweals / minetest.git / blobdiff