* More information at <http://www.minetest.net/>
* Developer Wiki: <http://dev.minetest.net/>
+* (Unofficial) Minetest Modding Book by rubenwardy: <https://rubenwardy.com/minetest_modding_book/>
Introduction
------------
### mod.conf
-A key-value store of mod details.
+A `Settings` file that provides meta information about the mod.
* `name`: The mod name. Allows Minetest to determine the mod name even if the
folder is wrongly named.
### `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.
+The format is documented in `builtin/settingtypes.txt`.
+It is parsed by the main menu settings dialogue to list mod-specific
+settings in the "Mods" category.
### `init.lua`
gain = 1.0, -- default
loop = true,
}
- -- Play in a location
+ -- Play at a location
{
pos = {x = 1, y = 2, z = 3},
gain = 1.0, -- default
max_hear_distance = 32, -- default, uses an euclidean metric
loop = true,
}
+ -- Play at a location, heard by anyone *but* the given player
+ {
+ pos = {x = 32, y = 0, z = 100},
+ max_hear_distance = 40,
+ exclude_player = name,
+ }
Looped sounds must either be connected to an object or played locationless to
-one player using `to_player = name,`.
+one player using `to_player = name`.
A positional sound will only be heard by players that are within
`max_hear_distance` of the sound position, at the start of the sound.
+`exclude_player = name` can be applied to locationless, positional and object-
+bound sounds to exclude a single player from hearing them.
+
`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", gain = 1.0, pitch = 1.0}`
+Specifies a sound name, gain (=volume) and pitch.
+This is either a string or a table.
+
+In string form, you just specify the sound name or
+the empty string for no sound.
+
+Table form has the following fields:
+
+* `name`: Sound name
+* `gain`: Volume (`1.0` = 100%)
+* `pitch`: Pitch (`1.0` = 100%)
+`gain` and `pitch` are optional and default to `1.0`.
+
+Examples:
+
+* `""`: No sound
+* `{}`: No sound
+* `"default_place_node"`: Play e.g. `default_place_node.ogg`
+* `{name = "default_place_node"}`: Same as above
+* `{name = "default_place_node", gain = 0.5}`: 50% volume
+* `{name = "default_place_node", gain = 0.9, pitch = 1.1}`: 90% volume, 110% pitch
+
+Special sound files
+-------------------
+These sound files are played back by the engine if provided.
+ * `player_damage`: Played when the local player takes damage (gain = 0.5)
+ * `player_falling_damage`: Played when the local player takes
+ damage by falling (gain = 0.5)
+ * `default_dig_<groupname>`: Default node digging sound
+ (see node sound definition for details)
Registered definitions
======================
The functions of `param1` and `param2` are determined by certain fields in the
node definition.
-`param1` is reserved for the engine when `paramtype != "none"`:
+The function of `param1` is determined by `paramtype` in node definition.
+`param1` is reserved for the engine when `paramtype != "none"`.
* `paramtype = "light"`
* The value stores light with and without sun in its upper and lower 4 bits
* mesh
* plantlike
* plantlike_rooted
-
-`param2` is reserved for the engine when any of these are used:
-
-* `liquidtype = "flowing"`
- * The level and some flags of the liquid is stored in `param2`
-* `drawtype = "flowingliquid"`
- * The drawn liquid level is read from `param2`
-* `drawtype = "torchlike"`
-* `drawtype = "signlike"`
+* `paramtype = "none"`
+ * `param1` will not be used by the engine and can be used to store
+ an arbitrary value
+
+The function of `param2` is determined by `paramtype2` in node definition.
+`param2` is reserved for the engine when `paramtype2 != "none"`.
+
+* `paramtype2 = "flowingliquid"`
+ * Used by `drawtype = "flowingliquid"` and `liquidtype = "flowing"`
+ * The liquid level and a flag of the liquid are stored in `param2`
+ * Bits 0-2: Liquid level (0-7). The higher, the more liquid is in this node
+ * Bit 3: If set, liquid is flowing downwards (no graphical effect)
* `paramtype2 = "wallmounted"`
- * The rotation of the node is stored in `param2`. You can make this value
- by using `minetest.dir_to_wallmounted()`.
+ * Supported drawtypes: "torchlike", "signlike", "normal", "nodebox", "mesh"
+ * The rotation of the node is stored in `param2`
+ * You can make this value by using `minetest.dir_to_wallmounted()`
+ * Values range 0 - 5
+ * The value denotes at which direction the node is "mounted":
+ 0 = y+, 1 = y-, 2 = x+, 3 = x-, 4 = z+, 5 = z-
* `paramtype2 = "facedir"`
+ * Supported drawtypes: "normal", "nodebox", "mesh"
* 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
* The height of the 'plantlike' section is stored in `param2`.
* The height is (`param2` / 16) nodes.
* `paramtype2 = "degrotate"`
- * Only valid for "plantlike". The rotation of the node is stored in
+ * Only valid for "plantlike" drawtype. The rotation of the node is stored in
`param2`.
* Values range 0 - 179. The value stored in `param2` is multiplied by two to
get the actual rotation in degrees 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.
+ * Only valid for "plantlike" drawtype. 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)
* `param2` values 0-63 define 64 levels of internal liquid, 0 being empty
and 63 being full.
* Liquid texture is defined using `special_tiles = {"modname_tilename.png"}`
+* `paramtype2 = "none"`
+ * `param2` will not be used by the engine and can be used to store
+ an arbitrary value
Nodes can also contain extra data. See [Node Metadata].
**Note**: `offset` _will_ adapt to screen DPI as well as user defined scaling
factor!
+The `z_index` field specifies the order of HUD elements from back to front.
+Lower z-index elements are displayed behind higher z-index elements. Elements
+with same z-index are displayed in an arbitrary order. Default 0.
+Supports negative values.
+
Below are the specific uses for fields in each type; fields not listed for that
type are ignored.
* `{type="nothing"}`
* `{type="node", under=pos, above=pos}`
+ * Indicates a pointed node selection box.
+ * `under` refers to the node position behind the pointed face.
+ * `above` refers to the node position in front of the pointed face.
* `{type="object", ref=ObjectRef}`
Exact pointing location (currently only `Raycast` supports these fields):
-----
Groups are stored in a table, having the group names with keys and the
-group ratings as values. For example:
+group ratings as values. Group ratings are integer values within the
+range [-32767, 32767]. For example:
-- Default dirt
groups = {crumbly=3, soil=1}
Special groups
--------------
-* `immortal`: Skips all damage and breath handling for an object. This group
- will also hide the integrated HUD status bars for players, and is
- automatically set to all players when damage is disabled on the server.
-* `punch_operable`: For entities; disables the regular damage mechanism for
- players punching it by hand or a non-tool item, so that it can do something
- else than take damage.
-* `level`: Can be used to give an additional sense of progression in the game.
- * A larger level will cause e.g. a weapon of a lower level make much less
- damage, and get worn out much faster, or not be able to get drops
- from destroyed nodes.
- * `0` is something that is directly accessible at the start of gameplay
- * There is no upper limit
+The asterisk `(*)` after a group name describes that there is no engine
+functionality bound to it, and implementation is left up as a suggestion
+to games.
+
+### Node, item and tool groups
+
+* `not_in_creative_inventory`: (*) Special group for inventory mods to indicate
+ that the item should be hidden in item lists.
+
+
+### Node-only groups
+
+* `attached_node`: if the node under it is not a walkable block the node will be
+ dropped as an item. If the node is wallmounted the wallmounted direction is
+ checked.
+* `bouncy`: value is bounce speed in percent
+* `connect_to_raillike`: makes nodes of raillike drawtype with same group value
+ connect to each other
* `dig_immediate`: Player can always pick up node without reducing tool wear
* `2`: the node always gets the digging time 0.5 seconds (rail, sign)
* `3`: the node always gets the digging time 0 seconds (torch)
* `disable_jump`: Player (and possibly other things) cannot jump from node
* `fall_damage_add_percent`: damage speed = `speed * (1 + value/100)`
-* `bouncy`: value is bounce speed in percent
* `falling_node`: if there is no walkable block under the node it will fall
* `float`: the node will not fall through liquids
-* `attached_node`: if the node under it is not a walkable block the node will be
- dropped as an item. If the node is wallmounted the wallmounted direction is
- checked.
-* `connect_to_raillike`: makes nodes of raillike drawtype with same group value
- connect to each other
+* `level`: Can be used to give an additional sense of progression in the game.
+ * A larger level will cause e.g. a weapon of a lower level make much less
+ damage, and get worn out much faster, or not be able to get drops
+ from destroyed nodes.
+ * `0` is something that is directly accessible at the start of gameplay
+ * There is no upper limit
+ * See also: `leveldiff` in [Tools]
* `slippery`: Players and items will slide on the node.
Slipperiness rises steadily with `slippery` value, starting at 1.
+
+
+### Tool-only groups
+
* `disable_repair`: If set to 1 for a tool, it cannot be repaired using the
`"toolrepair"` crafting recipe
+
+### `ObjectRef` groups
+
+* `immortal`: Skips all damage and breath handling for an object. This group
+ will also hide the integrated HUD status bars for players, and is
+ automatically set to all players when damage is disabled on the server.
+* `punch_operable`: For entities; disables the regular damage mechanism for
+ players punching it by hand or a non-tool item, so that it can do something
+ else than take damage.
+
+
+
Known damage and digging time defining groups
---------------------------------------------
Determines how many uses the tool has when it is used for digging a node,
of this group, of the maximum level. For lower leveled nodes, the use count
is multiplied by `3^leveldiff`.
+`leveldiff` is the difference of the tool's `maxlevel` `groupcaps` and the
+node's `level` group. The node cannot be dug if `leveldiff` is less than zero.
* `uses=10, leveldiff=0`: actual uses: 10
* `uses=10, leveldiff=1`: actual uses: 30
use `minetest.formspec_escape`.
For coloured text you can use `minetest.colorize`.
+Since formspec version 3, elements drawn in the order they are defined. All
+background elements are drawn before all other elements.
+
**WARNING**: do _not_ use a element name starting with `key_`; those names are
reserved to pass key press events to formspec!
Elements
--------
+### `formspec_version[<version>]`
+
+* Set the formspec version to a certain number. If not specified,
+ version 1 is assumed.
+* Must be specified before `size` element.
+* Clients older than this version can neither show newer elements nor display
+ elements with new arguments correctly.
+* Available since feature `formspec_version_element`.
+
### `size[<W>,<H>,<fixed_size>]`
* Define the size of the menu in inventory slots
### `real_coordinates[<bool>]`
+* INFORMATION: Enable it automatically using `formspec_version` version 2 or newer.
* When set to true, all following formspec elements will use the new coordinate system.
* If used immediately after `size`, `position`, `anchor`, and `no_prepend` elements
(if present), the form size will use the new coordinate system.
* Show an image
+### `animated_image[<X>,<Y>;<W>,<H>;<texture name>:<frame count>,<frame duration>]`
+
+* Show an animated image. The image is drawn like a "vertical_frames" tile
+ animation (See Tile animation definition), but uses a frame count/duration
+ for simplicity
+* `<texture name>` is the image to use
+* `<frame count>` is the number of frames animating the image
+* `<frame duration>` is in milliseconds
+
### `item_image[<X>,<Y>;<W>,<H>;<item name>]`
* Show an inventory image of registered item/node
-### `bgcolor[<color>;<fullscreen>]`
+### `bgcolor[<bgcolor>;<fullscreen>;<fbgcolor>]`
-* Sets background color of formspec as `ColorString`
-* If `true`, the background color is drawn fullscreen (does not affect the size
- of the formspec).
+* Sets background color of formspec.
+* `bgcolor` and `fbgcolor` (optional) are `ColorString`s, they define the color
+ of the non-fullscreen and the fullscreen background.
+* `fullscreen` (optional) can be one of the following:
+ * `false`: Only the non-fullscreen background color is drawn. (default)
+ * `true`: Only the fullscreen background color is drawn.
+ * `both`: The non-fullscreen and the fullscreen background color are drawn.
+ * `neither`: No background color is drawn.
+* Note: Leave a parameter empty to not modify the value.
+* Note: `fbgcolor`, leaving parameters empty and values for `fullscreen` that
+ are not bools are only available since formspec version 3.
### `background[<X>,<Y>;<W>,<H>;<texture name>]`
* If `auto_clip` is `true`, the background is clipped to the formspec size
(`x` and `y` are used as offset values, `w` and `h` are ignored)
-### `background[<X>,<Y>;<W>,<H>;<texture name>;<auto_clip>;<middle>]`
+### `background
9[<X>,<Y>;<W>,<H>;<texture name>;<auto_clip>;<middle>]`
* 9-sliced background. See https://en.wikipedia.org/wiki/9-slice_scaling
* Middle is a rect which defines the middle of the 9-slice.
image shall be sized 8 times 16px times 4 times 16px
* If `auto_clip` is `true`, the background is clipped to the formspec size
(`x` and `y` are used as offset values, `w` and `h` are ignored)
+* Available since formspec version 2
### `pwdfield[<X>,<Y>;<W>,<H>;<name>;<label>]`
half a coordinate. With the old system, newlines are spaced 2/5 of
an inventory slot.
-### `vertlabel[<X>,<Y>;<label>]`
+### `hypertext[<X>,<Y>;<W>,<H>;<name>;<text>]`
+* Displays a static formatted text with hyperlinks.
+* `x`, `y`, `w` and `h` work as per field
+* `name` is the name of the field as returned in fields to `on_receive_fields` in case of action in text.
+* `text` is the formatted text using `markup language` described below.
+### `vertlabel[<X>,<Y>;<label>]`
* Textual label drawn vertically
* `label` is the text on the label
* **Note**: If the new coordinate system is enabled, vertlabels are
### `scrollbar[<X>,<Y>;<W>,<H>;<orientation>;<name>;<value>]`
-* Show a scrollbar
+* Show a scrollbar using options defined by the previous `scrollbaroptions[]`
* 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)
* `orientation`: `vertical`/`horizontal`
* Fieldname data is transferred to Lua
-* Value this trackbar is set to (`0`-`1000`)
+* Value of this trackbar is set to (`0`-`1000`) by default
* See also `minetest.explode_scrollbar_event`
(main menu: `core.explode_scrollbar_event`).
+### `scrollbaroptions[opt1;opt2;...]`
+* Sets options for all following `scrollbar[]` elements
+* `min=<int>`
+ * Sets scrollbar minimum value, defaults to `0`.
+* `max=<int>`
+ * Sets scrollbar maximum value, defaults to `1000`.
+ If the max is equal to the min, the scrollbar will be disabled.
+* `smallstep=<int>`
+ * Sets scrollbar step value when the arrows are clicked or the mouse wheel is
+ scrolled.
+ * If this is set to a negative number, the value will be reset to `10`.
+* `largestep=<int>`
+ * Sets scrollbar step value used by page up and page down.
+ * If this is set to a negative number, the value will be reset to `100`.
+* `thumbsize=<int>`
+ * Sets size of the thumb on the scrollbar. Size is calculated in the number of
+ units the thumb spans out of the range of the scrollbar values.
+ * Example: If a scrollbar has a `min` of 1 and a `max` of 100, a thumbsize of 10
+ would span a tenth of the scrollbar space.
+ * If this is set to zero or less, the value will be reset to `1`.
+* `arrows=<show/hide/default>`
+ * Whether to show the arrow buttons on the scrollbar. `default` hides the arrows
+ when the scrollbar gets too small, but shows them otherwise.
+
### `table[<X>,<Y>;<W>,<H>;<name>;<cell 1>,<cell 2>,...,<cell n>;<selected idx>]`
* Show scrollable table using options defined by the previous `tableoptions[]`
* `span=<value>`: number of following columns to affect
(default: infinite).
-### `style[<name
>;<prop1>;<prop2>;...]`
+### `style[<name
1>,<name 2>,...;<prop1>;<prop2>;...]`
-* Set the style for the named element `name`.
+* Set the style for the named element(s) `name`.
* Note: this **must** be before the element is defined.
* See [Styling Formspecs].
-### `style_type[<type
>;<prop1>;<prop2>;...]`
+### `style_type[<type
1>,<type 2>,...;<prop1>;<prop2>;...]`
-* Sets the style for all elements of type `type` which appear after this element.
+* Sets the style for all elements of type(s) `type` which appear after this element.
* See [Styling Formspecs].
Migrating to Real Coordinates
Formspec elements can be themed using the style elements:
- style[<name
>;<prop1>;<prop2>;...]
- style_type[<type
>;<prop1>;<prop2>;...]
+ style[<name
1>,<name 2>,...;<prop1>;<prop2>;...]
+ style_type[<type
1>,<type 2>,...;<prop1>;<prop2>;...]
Where a prop is:
property_name=property_value
+A name/type can optionally be a comma separated list of names/types, like so:
+
+ world_delete,world_create,world_configure
+ button,image_button
+
For example:
style_type[button;bgcolor=#006699]
* label
* vertlabel, inherits from field
* image_button
-* item_image_button, inherits from image_button
+* item_image_button
* tabheader
### Valid Properties
-* button, button_exit
+* animated_image
+ * noclip - boolean, set to true to allow the element to exceed formspec bounds.
+* box
+ * noclip - boolean, set to true to allow the element to exceed formspec bounds.
+ * Default to false in formspec_version version 3 or higher
+* button, button_exit, image_button, item_image_button
* alpha - boolean, whether to draw alpha in bgimg. Default true.
* bgcolor - color, sets button tint.
- * bgimg - standard image. Defaults to none.
- * bgimg_pressed - image when pressed. Defaults to bgimg when not provided.
+ * bgcolor_hovered - color when hovered. Defaults to a lighter bgcolor when not provided.
+ * bgcolor_pressed - color when pressed. Defaults to a darker bgcolor when not provided.
+ * bgimg - standard background image. Defaults to none.
+ * bgimg_hovered - background image when hovered. Defaults to bgimg when not provided.
+ * bgimg_middle - Makes the bgimg textures render in 9-sliced mode and defines the middle rect.
+ See background9[] documentation for more details
+ * bgimg_pressed - background image when pressed. Defaults to bgimg when not provided.
* border - boolean, draw border. Set to false to hide the bevelled button pane. Default true.
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
* textcolor - color, default white.
* border - set to false to hide the textbox background and border. Default true.
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
* textcolor - color. Default white.
-* label, vertlabel
+* image
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
-* image_button
- * alpha - boolean, whether to draw alpha in bgimg. Default true.
- * border - boolean, draw border. Set to false to hide the bevelled button pane. Default false.
- * noclip - boolean, set to true to allow the element to exceed formspec bounds.
-* item_image_button
- * border - boolean, draw border. Set to false to hide the bevelled button pane. Default false.
+ * Default to false in formspec_version version 3 or higher
+* item_image
+ * noclip - boolean, set to true to allow the element to exceed formspec bounds. Default to false.
+* label, vertlabel
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
+* image_button (additional properties)
+ * fgimg - standard image. Defaults to none.
+ * fgimg_hovered - image when hovered. Defaults to fgimg when not provided.
+ * fgimg_pressed - image when pressed. Defaults to fgimg when not provided.
+ * NOTE: The parameters of any given image_button will take precedence over fgimg/fgimg_pressed
* tabheader
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
* textcolor - color. Default white.
+Markup language
+---------------
+
+Markup language used in `hypertext[]` elements uses tag that look like HTML tags. Some
+tags can enclose text, they open with `<tagname>` and close with `</tagname>`.
+Tags can have attributes, in that case, attributes are in the opening tag in
+form of a key/value separated with equal signs. Attribute values should not be quoted.
+
+These are the technically basic tags but see below for usual tags. Base tags are:
+
+`<style color=... font=... size=...>...</style>`
+
+Changes the style of the text.
+
+* `color`: Text color. Given color is a `colorspec`.
+* `size`: Text size.
+* `font`: Text font (`mono` or `normal`).
+
+`<global background=... margin=... valign=... color=... hovercolor=... size=... font=... halign=... >`
+
+Sets global style.
+
+Global only styles:
+* `background`: Text background, a `colorspec` or `none`.
+* `margin`: Page margins in pixel.
+* `valign`: Text vertical alignment (`top`, `middle`, `bottom`).
+
+Inheriting styles (affects child elements):
+* `color`: Default text color. Given color is a `colorspec`.
+* `hovercolor`: Color of <action> tags when mouse is over.
+* `size`: Default text size.
+* `font`: Default text font (`mono` or `normal`).
+* `halign`: Default text horizontal alignment (`left`, `right`, `center`, `justify`).
+
+This tag needs to be placed only once as it changes the global settings of the
+text. Anyway, if several tags are placed, each changed will be made in the order
+tags appear.
+
+`<tag name=... color=... hovercolor=... font=... size=...>`
+
+Defines or redefines tag style. This can be used to define new tags.
+* `name`: Name of the tag to define or change.
+* `color`: Text color. Given color is a `colorspec`.
+* `hovercolor`: Text color when element hovered (only for `action` tags). Given color is a `colorspec`.
+* `size`: Text size.
+* `font`: Text font (`mono` or `normal`).
+
+Following tags are the usual tags for text layout. They are defined by default.
+Other tags can be added using `<tag ...>` tag.
+
+`<normal>...</normal>`: Normal size text
+
+`<big>...</big>`: Big text
+
+`<bigger>...</bigger>`: Bigger text
+
+`<center>...</center>`: Centered text
+
+`<left>...</left>`: Left-aligned text
+
+`<right>...</right>`: Right-aligned text
+
+`<justify>...</justify>`: Justified text
+
+`<mono>...</mono>`: Monospaced font
+
+`<b>...</b>`, `<i>...</i>`, `<u>...</u>`: Bold, italic, underline styles.
+
+`<action name=...>...</action>`
+
+Make that text a clickable text triggering an action.
+
+* `name`: Name of the action (mandatory).
+
+When clicked, the formspec is send to the server. The value of the text field
+sent to `on_player_receive_fields` will be "action:" concatenated to the action
+name.
+
+`<img name=... float=... width=... height=...>`
+
+Draws an image which is present in the client media cache.
+
+* `name`: Name of the texture (mandatory).
+* `float`: If present, makes the image floating (`left` or `right`).
+* `width`: Force image width instead of taking texture width.
+* `height`: Force image height instead of taking texture height.
+
+If only width or height given, texture aspect is kept.
+
+`<item name=... float=... width=... height=... rotate=...>`
+
+Draws an item image.
+
+* `name`: Item string of the item to draw (mandatory).
+* `float`: If present, makes the image floating (`left` or `right`).
+* `width`: Item image width.
+* `height`: Item image height.
+* `rotate`: Rotate item image if set to `yes` or `X,Y,Z`. X, Y and Z being
+rotation speeds in percent of standard speed (-1000 to 1000). Works only if
+`inventory_items_animations` is set to true.
+* `angle`: Angle in which the item image is shown. Value has `X,Y,Z` form.
+X, Y and Z being angles around each three axes. Works only if
+`inventory_items_animations` is set to true.
+
Inventory
=========
* `craftresult`: list containing the crafted output
* `hand`: list containing an override for the empty hand
* Is not created automatically, use `InvRef:set_size`
-
-
-
+ * Is only used to enhance the empty hand's tool capabilities
Colors
======
* `table.insert_all(table, other_table)`:
* Appends all values in `other_table` to `table` - uses `#table + 1` to
find new indices.
+* `table.key_value_swap(t)`: returns a table with keys and values swapped
+ * If multiple keys in `t` map to the same value, the result is undefined.
+* `table.shuffle(table, [from], [to], [random_func])`:
+ * Shuffles elements `from` to `to` in `table` in place
+ * `from` defaults to `1`
+ * `to` defaults to `#table`
+ * `random_func` defaults to `math.random`. This function receives two
+ integers as arguments and should return a random integer inclusively
+ between them.
* `minetest.pointed_thing_to_face_pos(placer, pointed_thing)`: returns a
position.
* returns the exact position on the surface of a pointed node
-----------
A helper class for voxel areas.
-It can be created via `VoxelArea:new{MinEdge=pmin, MaxEdge=pmax}`.
+It can be created via `VoxelArea:new{MinEdge = pmin, MaxEdge = pmax}`.
The coordinates are *inclusive*, like most other things in Minetest.
### Methods
`[z [y [x]]]`.
* `iterp(minp, maxp)`: same as above, except takes a vector
+### Y stride and z stride of a flat array
+
+For a particular position in a voxel area, whose flat array index is known,
+it is often useful to know the index of a neighboring or nearby position.
+The table below shows the changes of index required for 1 node movements along
+the axes in a voxel area:
+
+ Movement Change of index
+ +x +1
+ -x -1
+ +y +ystride
+ -y -ystride
+ +z +zstride
+ -z -zstride
+
+If, for example:
+
+ local area = VoxelArea:new{MinEdge = emin, MaxEdge = emax}
+
+The values of `ystride` and `zstride` can be obtained using `area.ystride` and
+`area.zstride`.
+
-- Specifies whether binary data can be uploaded or downloaded using
-- the HTTP API (5.1.0)
httpfetch_binary_data = true,
+ -- Whether formspec_version[<version>] may be used (5.1.0)
+ formspec_version_element = true,
+ -- Whether AreaStore's IDs are kept on save/load (5.1.0)
+ area_store_persistent_ids = true,
}
* `minetest.has_feature(arg)`: returns `boolean, missing_features`
avg_jitter = 0.03, -- average packet time jitter
connection_uptime = 200, -- seconds since client connected
protocol_version = 32, -- protocol version used by client
+ formspec_version = 2, -- supported formspec version
-- following information is available on debug build only!!!
-- DO NOT USE IN MODS
--ser_vers = 26, -- serialization version used by client
* `minetest.unregister_biome(name)`
* Unregisters the biome from the engine, and deletes the entry with key
`name` from `minetest.registered_biomes`.
+ * Warning: This alters the biome to biome ID correspondences, so any
+ decorations or ores using the 'biomes' field must afterwards be cleared
+ and re-registered.
* `minetest.register_decoration(decoration definition)`
* Returns an integer object handle uniquely identifying the registered
decoration on success. To get the decoration ID, use
* If the function is called when loading the mod, and `name` is a relative
path, then the current mod path will be prepended to the schematic
filename.
-* `minetest.clear_registered_ores()`
- * Clears all ores currently registered.
* `minetest.clear_registered_biomes()`
* Clears all biomes currently registered.
+ * Warning: Clearing and re-registering biomes alters the biome to biome ID
+ correspondences, so any decorations or ores using the 'biomes' field must
+ afterwards be cleared and re-registered.
* `minetest.clear_registered_decorations()`
* Clears all decorations currently registered.
+* `minetest.clear_registered_ores()`
+ * Clears all ores currently registered.
* `minetest.clear_registered_schematics()`
* Clears all schematics currently registered.
allow for multiple protection mods.
* `minetest.register_on_item_eat(function(hp_change, replace_with_item, itemstack, user, pointed_thing))`
* Called when an item is eaten, by `minetest.item_eat`
- * Return `true` or `itemstack` to cancel the default item eat response
- (i.e.: hp increase).
+ * Return `itemstack` to cancel the default item eat response (i.e.: hp increase).
* `minetest.register_on_priv_grant(function(name, granter, priv))`
* Called when `granter` grants the priv `priv` to `name`.
* Note that the callback will be called twice if it's done by a player,
Authentication
--------------
-* `minetest.string_to_privs(str)`: returns `{priv1=true,...}`
-* `minetest.privs_to_string(privs)`: returns `"priv1,priv2,..."`
- * Convert between two privilege representations
+* `minetest.string_to_privs(str[, delim])`:
+ * Converts string representation of privs into table form
+ * `delim`: String separating the privs. Defaults to `","`.
+ * Returns `{ priv1 = true, ... }`
+* `minetest.privs_to_string(privs[, delim])`:
+ * Returns the string representation of `privs`
+ * `delim`: String to delimit privs. Defaults to `","`.
* `minetest.get_player_privs(name) -> {priv1=true,...}`
* `minetest.check_player_privs(player_or_name, ...)`:
returns `bool, missing_privs`
* `minetest.inventorycube(img1, img2, img3)`
* Returns a string for making an image of a cube (useful as an item image)
* `minetest.get_pointed_thing_position(pointed_thing, above)`
- * Get position of a `pointed_thing` (that you can get from somewhere)
+ * Returns the position of a `pointed_thing` or `nil` if the `pointed_thing`
+ does not refer to a node or entity.
+ * If the optional `above` parameter is true and the `pointed_thing` refers
+ to a node, then it will return the `above` position of the `pointed_thing`.
* `minetest.dir_to_facedir(dir, is6d)`
* Convert a vector to a facedir value, used in `param2` for
`paramtype2="facedir"`.
`{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`
+ * `output.replacements` = List of replacement `ItemStack`s that couldn't be
+ placed in `decremented_input.items`. Replacements can be placed in
+ `decremented_input` if the stack of the replaced item has a count of 1.
* `decremented_input` = like `input`
* `minetest.get_craft_recipe(output)`: returns input
* returns last registered recipe for output item (node)
* Revert latest actions of someone
* `actor`: `"player:<name>"`, also `"liquid"`.
-Defaults for the `on_*` item definition functions
--------------------------------------------------
-
-These functions return the leftover itemstack.
+Defaults for the `on_place` and `on_drop` item definition functions
+-------------------------------------------------------------------
* `minetest.item_place_node(itemstack, placer, pointed_thing[, param2, prevent_after_place])`
* Place item as a node
* `param2` overrides `facedir` and wallmounted `param2`
* `prevent_after_place`: if set to `true`, `after_place_node` is not called
for the newly placed node to prevent a callback and placement loop
- * returns `itemstack, success`
+ * returns `itemstack, position`
+ * `position`: the location the node was placed to. `nil` if nothing was placed.
* `minetest.item_place_object(itemstack, placer, pointed_thing)`
* Place item as-is
-* `minetest.item_place(itemstack, placer, pointed_thing, param2)`
- * Use one of the above based on what the item is.
+ * returns the leftover itemstack
+ * **Note**: This function is deprecated and will never be called.
+* `minetest.item_place(itemstack, placer, pointed_thing[, param2])`
+ * Wrapper that calls `minetest.item_place_node` if appropriate
* Calls `on_rightclick` of `pointed_thing.under` if defined instead
* **Note**: is not called when wielded item overrides `on_place`
- * `param2` overrides `facedir` and wallmounted `param2`
- * returns `itemstack, success`
+ * `param2` overrides facedir and wallmounted `param2`
+ * returns `itemstack, position`
+ * `position`: the location the node was placed to. `nil` if nothing was placed.
* `minetest.item_drop(itemstack, dropper, pos)`
* Drop the item
-* `minetest.item_eat(hp_change, replace_with_item)`
- * Eat the item.
+ * returns the leftover itemstack
+* `minetest.item_eat(hp_change[, replace_with_item])`
+ * Returns `function(itemstack, user, pointed_thing)` as a
+ function wrapper for `minetest.do_item_eat`.
* `replace_with_item` is the itemstring which is added to the inventory.
If the player is eating a stack, then replace_with_item goes to a
- different spot. Can be `nil`
- * See `minetest.do_item_eat`
+ different spot.
Defaults for the `on_punch` and `on_dig` node definition callbacks
------------------------------------------------------------------
Sounds
------
-* `minetest.sound_play(spec, parameters)`: returns a handle
+* `minetest.sound_play(spec, parameters, [ephemeral])`: returns a handle
* `spec` is a `SimpleSoundSpec`
* `parameters` is a sound parameter table
+ * `ephemeral` is a boolean (default: false)
+ Ephemeral sounds will not return a handle and can't be stopped or faded.
+ It is recommend to use this for short sounds that happen in response to
+ player actions (e.g. door closing).
* `minetest.sound_stop(handle)`
+ * `handle` is a handle returned by `minetest.sound_play`
* `minetest.sound_fade(handle, step, gain)`
* `handle` is a handle returned by `minetest.sound_play`
* `step` determines how fast a sound will fade.
Bans
----
-* `minetest.get_ban_list()`: returns the ban list
- (same as `minetest.get_ban_description("")`).
-* `minetest.get_ban_description(ip_or_name)`: returns ban description (string)
-* `minetest.ban_player(name)`: ban a player
-* `minetest.unban_player_or_ip(name)`: unban player or IP address
-* `minetest.kick_player(name, [reason])`: disconnect a player with a optional
+* `minetest.get_ban_list()`: returns a list of all bans formatted as string
+* `minetest.get_ban_description(ip_or_name)`: returns list of bans matching
+ IP address or name formatted as string
+* `minetest.ban_player(name)`: ban the IP of a currently connected player
+ * Returns boolean indicating success
+* `minetest.unban_player_or_ip(ip_or_name)`: remove ban record matching
+ IP address or name
+* `minetest.kick_player(name, [reason])`: disconnect a player with an optional
reason.
+ * Returns boolean indicating success (false if player nonexistant)
Particles
---------
the Lua code generated will use that number of spaces as indentation
instead of a tab character.
+* `minetest.read_schematic(schematic, options)`
+ * Returns a Lua table representing the schematic (see: [Schematic specifier])
+ * `schematic` is the schematic to read (see: [Schematic specifier])
+ * `options` is a table containing the following optional parameters:
+ * `write_yslice_prob`: string value:
+ * `none`: no `write_yslice_prob` table is inserted,
+ * `low`: only probabilities that are not 254 or 255 are written in
+ the `write_ylisce_prob` table,
+ * `all`: write all probabilities to the `write_yslice_prob` table.
+ * The default for this option is `all`.
+ * Any invalid value will be interpreted as `all`.
+
HTTP Requests
-------------
of the creative mode setting, checks for "sneak" to set the `invert_wall`
parameter and `prevent_after_place` set to `true`.
+* `minetest.calculate_knockback(player, hitter, time_from_last_punch,
+ tool_capabilities, dir, distance, damage)`
+ * Returns the amount of knockback applied on the punched player.
+ * Arguments are equivalent to `register_on_punchplayer`, except the following:
+ * `distance`: distance between puncher and punched player
+ * This function can be overriden by mods that wish to modify this behaviour.
+ * You may want to cache and call the old function to allow multiple mods to
+ change knockback behaviour.
+
* `minetest.forceload_block(pos[, transient])`
* forceloads the position `pos`.
* returns `true` if area could be forceloaded
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)`.
+`AreaStore(type_name)`. The mod decides where to save and load AreaStore.
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.
+* `get_area(id, include_borders, include_data)`
+ * Returns the area information about the specified ID.
+ * Returned values are either of these:
+
+ nil -- Area not found
+ true -- Without `include_borders` and `include_data`
+ {
+ min = pos, max = pos -- `include_borders == true`
+ data = string -- `include_data == true`
+ }
+
+* `get_areas_for_pos(pos, include_borders, include_data)`
+ * Returns all areas as table, indexed by the area ID.
+ * Table values: see `get_area`.
+* `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).
+ * `accept_overlap`: if `true`, areas are returned that have nodes in
+ common (intersect) with the specified area.
+ * Returns the same values as `get_areas_for_pos`.
* `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.
+ * 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.
+ * `id` (optional): will be used as the internal area ID if it is an unique
+ number between 0 and 2^32-2.
* `reserve(count)`: reserves resources for at most `count` many contained
areas.
Only needed for efficiency, and only some implementations profit.
* `get_metadata()`: (DEPRECATED) Returns metadata (a string attached to an item
stack).
* `set_metadata(metadata)`: (DEPRECATED) Returns true.
+* `get_description()`: returns the description shown in inventory list tooltips.
* `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.
`MetaDataRef`
-------------
-See [`StorageRef`], [`NodeMetaRef`], [`ItemStackMetaRef`], and [`PlayerMetaRef`].
+Base class used by [`StorageRef`], [`NodeMetaRef`], [`ItemStackMetaRef`],
+and [`PlayerMetaRef`].
### Methods
-----------
Moving things in the game are generally these.
+This is basically a reference to a C++ `ServerActiveObject`.
+
+### Advice on handling `ObjectRefs`
+
+When you receive an `ObjectRef` as a callback argument or from another API
+function, it is possible to store the reference somewhere and keep it around.
+It will keep functioning until the object is unloaded or removed.
+
+However, doing this is **NOT** recommended as there is (intentionally) no method
+to test if a previously acquired `ObjectRef` is still valid.
+Instead, `ObjectRefs` should be "let go" of as soon as control is returned from
+Lua back to the engine.
+Doing so is much less error-prone and you will never need to wonder if the
+object you are working with still exists.
-This is basically a reference to a C++ `ServerActiveObject`
### Methods
* `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
+* `move_to(pos, continuous=false)`
+ * Does an interpolated move for Lua entities for visually smooth transitions.
+ * If `continuous` is true, the Lua entity will not be moved to the current
+ position before starting the interpolated move.
+ * For players this does the same as `set_pos`,`continuous` is ignored.
* `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_hp()`: returns number of hitpoints (2 * number of hearts)
* `set_hp(hp, reason)`: set number of hitpoints (2 * number of hearts).
* See reason in register_on_player_hpchange
-* `get_inventory()`: returns an `InvRef`
+ * Is limited to the range of 0 ... 65535 (2^16 - 1)
+ * For players: HP are also limited by `hp_max` specified in the player's
+ object properties
+* `get_inventory()`: returns an `InvRef` for players, otherwise returns `nil`
* `get_wield_list()`: returns the name of the inventory list the wielded item
is in.
* `get_wield_index()`: returns the index of the wielded item
#### Lua entity only (no-op for other objects)
-* `remove()`: remove object (after returning from Lua)
+* `remove()`: remove object
+ * The object is removed after returning from Lua. However the `ObjectRef`
+ itself instantly becomes unusable with all further method calls having
+ no effect and returning `nil`.
* `set_velocity(vel)`
* `vel` is a vector, e.g. `{x=0.0, y=2.3, z=1.0}`
* `add_velocity(vel)`
* `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
+* `add_player_velocity(vel)`
+ * Adds to player velocity, this happens client-side and only once.
+ * Does not apply during free_move.
+ * Note that since the player speed is normalized at each move step,
+ increasing e.g. Y velocity beyond what would usually be achieved
+ (see: physics overrides) will cause existing X/Z velocity to be reduced.
+ * Example: `add_player_velocity({x=0, y=6.5, z=0})` is equivalent to
+ pressing the jump key (assuming default settings)
* `get_look_dir()`: get camera direction as a unit vector
* `get_look_vertical()`: pitch in radians
* Angle ranges between -pi/2 and pi/2, which are straight up and down
`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
+* `get_breath()`: returns player's breath
+* `set_breath(value)`: sets player's breath
* values:
* `0`: player is drowning
* max: bubbles bar is not shown
* See [Object properties] for more information
+ * Is limited to range 0 ... 65535 (2^16 - 1)
+* `set_fov(fov, is_multiplier)`: Sets player's FOV
+ * `fov`: FOV value.
+ * `is_multiplier`: Set to `true` if the FOV value is a multiplier.
+ Defaults to `false`.
+ * Set to 0 to clear FOV override.
+* `get_fov()`:
+ * Returns player's FOV override in degrees, and a boolean depending on whether
+ the value is a multiplier.
+ * Returns 0 as first value if player's FOV hasn't been overridden.
* `set_attribute(attribute, value)`: DEPRECATED, use get_meta() instead
* Sets an extra attribute with value on player.
* `value` must be a string, or a number which will be converted to a
* `default` is the value returned if `key` is not found.
* Returns `nil` if `key` is not found and `default` not specified.
* `get_np_group(key)`: returns a NoiseParams table
+* `get_flags(key)`:
+ * Returns `{flag = true/false, ...}` according to the set flags.
+ * Is currently limited to mapgen flags `mg_flags` and mapgen-specific
+ flags like `mgv5_spflags`.
* `set(key, value)`
* Setting names can't contain whitespace or any of `="{}#`.
* Setting values can't contain the sequence `\n"""`.
* Writes changes to file.
* `to_table()`: returns `{[key1]=value1,...}`
+### Format
+
+The settings have the format `key = value`. Example:
+
+ foo = example text
+ bar = """
+ Multiline
+ value
+ """
+
+
`StorageRef`
------------
Mod metadata: per mod metadata, saved automatically.
Can be obtained via `minetest.get_mod_storage()` during load time.
+WARNING: This storage backend is incaptable to save raw binary data due
+to restrictions of JSON.
+
### Methods
* All methods in MetaDataRef
-----------------
Used by `ObjectRef` methods. Part of an Entity definition.
+These properties are not persistent, but are applied automatically to the
+corresponding Lua entity using the given registration fields.
+Player properties need to be saved manually.
{
hp_max = 1,
-- Defaults to 1.625.
physical = true,
+ -- Collide with `walkable` nodes.
collide_with_objects = true,
-- Collide with other objects if physical = true
- weight = 5,
-
collisionbox = {-0.5, 0.0, -0.5, 0.5, 1.0, 0.5}, -- Default
selectionbox = {-0.5, 0.0, -0.5, 0.5, 1.0, 0.5},
-- Selection box uses collision box dimensions when not set.
-- Multipliers for the visual size. If `z` is not specified, `x` will be used
-- to scale the entity along both horizontal axes.
- mesh = "model",
+ mesh = "model.obj",
+ -- File name of mesh when using "mesh" visual
textures = {},
-- Number of required textures depends on visual.
-- spritesheet.
is_visible = true,
+ -- If false, object is invisible and can't be pointed.
makes_footstep_sound = false,
+ -- If true, is able to make footstep sounds of nodes
+ -- (see node sound definition for details).
automatic_rotate = 0,
-- Set constant rotation in radians per second, positive or negative.
-- Set to 0 to disable constant rotation.
stepheight = 0,
+ -- If positive number, object will climb upwards when it moves
+ -- horizontally against a `walkable` node, if the height difference
+ -- is within `stepheight`.
automatic_face_movement_dir = 0.0,
-- Automatically set yaw to movement direction, offset in degrees.
Used by `minetest.register_lbm`.
+A loading block modifier (LBM) is used to define a function that is called for
+specific nodes (defined by `nodenames`) when a mapblock which contains such nodes
+gets loaded.
+
{
label = "Upgrade legacy doors",
-- Descriptive label for profiling purposes (optional).
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.
+ -- and not only the first time the block gets loaded after the LBM
+ -- was introduced.
action = function(pos, node),
}
liquids_pointable = false,
- -- See "Tools" section
+ -- See "Tools" section for an example including explanation
tool_capabilities = {
full_punch_interval = 1.0,
max_drop_level = 0,
uses = 20, maxlevel = 2},
},
damage_groups = {groupname = damage},
+ -- Damage values must be between -32768 and 32767 (2^15)
+
+ punch_attack_uses = nil,
+ -- Amount of uses this tool has for attacking players and entities
+ -- by punching them (0 = infinite uses).
+ -- For compatibility, this is automatically set from the first
+ -- suitable groupcap using the forumla "uses * 3^(maxlevel - 1)".
+ -- It is recommend to set this explicitly instead of relying on the
+ -- fallback behavior.
},
node_placement_prediction = nil,
-- upon digging. Server will always update actual result shortly.
sound = {
- breaks = "default_tool_break", -- tools only
- place = <SimpleSoundSpec>,
+ -- Definition of items sounds to be played at various events.
+ -- All fields in this table are optional.
+
+ breaks = <SimpleSoundSpec>,
+ -- When tool breaks due to wear. Ignored for non-tools
+
eat = <SimpleSoundSpec>,
+ -- When item is eaten with `minetest.do_item_eat`
},
on_place = function(itemstack, placer, pointed_thing),
-- default: minetest.item_place
on_secondary_use = function(itemstack, user, pointed_thing),
- -- Same as on_place but called when pointing at nothing.
+ -- Same as on_place but called when not pointing at a node.
-- The user may be any ObjectRef or nil.
- -- pointed_thing: always { type = "nothing" }
+ -- default: nil
on_drop = function(itemstack, dropper, pos),
-- Shall drop item and return the leftover itemstack.
-- 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.
+ -- node. For torchlike, the image will start at the surface to which the
+ -- node "attaches". For the other drawtypes the image will be centered
+ -- on the node.
tiles = {tile definition 1, def2, def3, def4, def5, def6},
-- Textures of node; +Y, -Y, +X, -X, +Z, -Z
-- Tells connected nodebox nodes to connect only to these sides of this
-- node
- mesh = "model",
+ mesh = "model.obj",
+ -- File name of mesh when using "mesh" drawtype
selection_box = {
type = "fixed",
-- liquid, flowingliquid drawtypes can only wave like liquids.
sounds = {
+ -- Definition of node sounds to be played at various events.
+ -- All fields in this table are optional.
+
footstep = <SimpleSoundSpec>,
- dig = <SimpleSoundSpec>, -- "__group" = group-based sound (default)
+ -- If walkable, played when object walks on it. If node is
+ -- climbable or a liquid, played when object moves through it
+
+ dig = <SimpleSoundSpec> or "__group",
+ -- While digging node.
+ -- If `"__group"`, then the sound will be
+ -- `default_dig_<groupname>`, where `<groupname>` is the
+ -- name of the tool's digging group with the fastest digging time.
+ -- In case of a tie, one of the sounds will be played (but we
+ -- cannot predict which one)
+ -- Default value: `"__group"`
+
dug = <SimpleSoundSpec>,
+ -- Node was dug
+
place = <SimpleSoundSpec>,
+ -- Node was placed. Also played after falling
+
place_failed = <SimpleSoundSpec>,
+ -- When node placement failed
+
fall = <SimpleSoundSpec>,
+ -- When node starts to fall
},
drop = "",
-- Name of dropped item when dug.
-- Default dropped item is the node itself.
- -- Using a table allows multiple items, drop chances and tool filtering:
+ -- Using a table allows multiple items, drop chances and tool filtering.
+ -- Tool filtering was undocumented until recently, tool filtering by string
+ -- matching is deprecated.
drop = {
max_items = 1,
-- Maximum number of item lists to drop.
},
{
-- Only drop if using a tool whose name contains
- -- "default:shovel_".
+ -- "default:shovel_" (this tool filtering by string matching
+ -- is deprecated).
tools = {"~default:shovel_"},
rarity = 2,
-- The item list dropped.
-- default: nil
can_dig = function(pos, [player]),
-
- on_punch = function(pos, node, puncher, pointed_thing),
-- Returns true if node can be dug, or false if not.
-- default: nil
+
+ on_punch = function(pos, node, puncher, pointed_thing),
-- default: minetest.node_punch
-- By default calls minetest.register_on_punchnode callbacks.
Used by `minetest.register_privilege`.
{
- description = "Can teleport", -- Privilege description
+ description = "",
+ -- Privilege description
- give_to_singleplayer = false,
- -- Whether to grant the privilege to singleplayer (default true).
+ give_to_singleplayer = true,
+ -- Whether to grant the privilege to singleplayer.
give_to_admin = true,
-- Whether to grant the privilege to the server admin.
size = { x=100, y=100 },
-- Size of element in pixels
+
+ z_index = 0,
+ -- Z index : lower z-index HUDs are displayed behind higher z-index HUDs
}
Particle definition
projects / oweals / minetest.git / blobdiff