* `game.conf`, with the following keys:
* `name`: Required, human readable name e.g. `name = Minetest`
* `description`: Short description to be shown in the content tab
+ * `allowed_mapgens = <comma-separated mapgens>`
+ e.g. `allowed_mapgens = v5,v6,flat`
+ Mapgens not in this list are removed from the list of mapgens for
+ the game.
+ If not specified, all mapgens are allowed.
* `disallowed_mapgens = <comma-separated mapgens>`
e.g. `disallowed_mapgens = v5,v6,flat`
These mapgens are removed from the list of mapgens for the game.
+ When both `allowed_mapgens` and `disallowed_mapgens` are
+ specified, `allowed_mapgens` is applied before
+ `disallowed_mapgens`.
+ * `disallowed_mapgen_settings= <comma-separated mapgen settings>`
+ e.g. `disallowed_mapgen_settings = mgv5_spflags`
+ These settings are hidden for this game in the world creation
+ dialog and game start menu.
* `minetest.conf`:
Used to set default settings when running this game.
* `settingtypes.txt`:
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.
- * `main_menu`: Looped sound in the main menu (gain = 1.0)
* `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)
-
+ * `player_jump`: Played when the local player jumps
+ * `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.
- * Bits 0, 1 and 2 form a mesh selector.
- Currently the following meshes are choosable:
+ * Only valid for "plantlike" drawtype. `param2` encodes the shape and
+ optional modifiers of the "plant". `param2` is a bitfield.
+ * Bits 0 to 2 select the shape.
+ Use only one of the values below:
* 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.
+ * Bits 3 to 7 are used to enable any number of optional modifiers.
+ Just add the corresponding value(s) below to `param2`:
+ * 8 - Makes the plant slightly vary placement horizontally
+ * 16 - Makes the plant mesh 1.4x larger
+ * 32 - Moves each face randomly a small bit down (1/8 max)
+ * values 64 and 128 (bits 6-7) are reserved for future use.
+ * Example: `param2 = 0` selects a normal "x" shaped plant
+ * Example: `param2 = 17` selects a "+" shaped plant, 1.4x larger (1+16)
* `paramtype2 = "color"`
* `param2` tells which color is picked from the palette.
The palette should have 256 pixels.
* `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].
There are a bunch of different looking node types.
-Look for examples in `games/minimal` or `games/minetest_game`.
+Look for examples in `games/devtest` or `games/minetest_game`.
* `normal`
* A node-sized cube.
percentage of the screen, ranging in value from `0` to `1`.
The name field is not yet used, but should contain a description of what the
-HUD element represents. The direction field is the direction in which something
-is drawn.
+HUD element represents.
+The `direction` field is the direction in which something is drawn.
`0` draws from left to right, `1` draws from right to left, `2` draws from
top to bottom, and `3` draws from bottom to top.
**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. By convention, the following values are recommended:
+
+* -400: Graphical effects, such as vignette
+* -300: Name tags, waypoints
+* -200: Wieldhand
+* -100: Things that block the player's view, e.g. masks
+* 0: Default. For standard in-game HUD elements like crosshair, hotbar,
+ minimap, builtin statbars, etc.
+* 100: Temporary text messages or notification icons
+* 1000: Full-screen effects such as full-black screen or credits.
+ This includes effects that cover the entire screen
+* Other: If your HUD element doesn't fit into any category, pick a number
+ between the suggested values
+
+
+
Below are the specific uses for fields in each type; fields not listed for that
type are ignored.
text. Specify `0xFFFFFF` for white text, `0xFF0000` for red, and so on.
* `alignment`: The alignment of the text.
* `offset`: offset in pixels from position.
+* `size`: size of the text.
+ The player-set font size is multiplied by size.x (y value isn't used).
### `statbar`
-Displays a horizontal bar made up of half-images.
+Displays a horizontal bar made up of half-images with an optional background.
-* `text`: The name of the texture that is used.
+* `text`: The name of the texture to use.
+* `text2`: Optional texture name to enable a background / "off state"
+ texture (useful to visualize the maximal value). Both textures
+ must have the same size.
* `number`: The number of half-textures that are displayed.
If odd, will end with a vertically center-split texture.
-* `direction`
+* `item`: Same as `number` but for the "off state" texture
+* `direction`: To which direction the images will extend to
* `offset`: offset in pixels from position.
* `size`: If used, will force full-image size to this value (override texture
pack image size)
* `name`: The name of the waypoint.
* `text`: Distance suffix. Can be blank.
+* `precision`: Waypoint precision, integer >= 0. Defaults to 10.
+ If set to 0, distance is not shown. Shown value is `floor(distance*precision)/precision`.
+ When the precision is an integer multiple of 10, there will be `log_10(precision)` digits after the decimal point.
+ `precision = 1000`, for example, will show 3 decimal places (eg: `0.999`).
+ `precision = 2` will show multiples of `0.5`; precision = 5 will show multiples of `0.2` and so on:
+ `precision = n` will show multiples of `1/n`
* `number:` An integer containing the RGB value of the color used to draw the
text.
* `world_pos`: World position of the waypoint.
+* `offset`: offset in pixels from position.
+* `alignment`: The alignment of the waypoint.
+
+### `image_waypoint`
+Same as `image`, but does not accept a `position`; the position is instead determined by `world_pos`, the world position of the waypoint.
+
+* `scale`: The scale of the image, with 1 being the original texture size.
+ Only the X coordinate scale is used (positive values).
+ Negative values represent that percentage of the screen it
+ should take; e.g. `x=-100` means 100% (width).
+* `text`: The name of the texture that is displayed.
+* `alignment`: The alignment of the image.
+* `world_pos`: World position of the waypoint.
+* `offset`: offset in pixels from position.
-----
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}
* `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
+ or if their feet are in the node. Note: not supported for `new_move = false`
* `fall_damage_add_percent`: damage speed = `speed * (1 + value/100)`
* `falling_node`: if there is no walkable block under the node it will fall
* `float`: the node will not fall through liquids
Since formspec version 3, elements drawn in the order they are defined. All
background elements are drawn before all other elements.
-`list` elements are an exception here. They are drawn last. This, however, might
-be changed at any time.
**WARNING**: do _not_ use a element name starting with `key_`; those names are
reserved to pass key press events to formspec!
* End of a container, following elements are no longer relative to this
container.
+### `scroll_container[<X>,<Y>;<W>,<H>;<scrollbar name>;<orientation>;<scroll factor>]`
+
+* Start of a scroll_container block. All contained elements will ...
+ * take the scroll_container coordinate as position origin,
+ * be additionally moved by the current value of the scrollbar with the name
+ `scrollbar name` times `scroll factor` along the orientation `orientation` and
+ * be clipped to the rectangle defined by `X`, `Y`, `W` and `H`.
+* `orientation`: possible values are `vertical` and `horizontal`.
+* `scroll factor`: optional, defaults to `0.1`.
+* Nesting is possible.
+* Some elements might work a little different if they are in a scroll_container.
+* Note: If you want the scroll_container to actually work, you also need to add a
+ scrollbar element with the specified name. Furthermore, it is highly recommended
+ to use a scrollbaroptions element on this scrollbar.
+
+### `scroll_container_end[]`
+
+* End of a scroll_container, following elements are no longer bound to this
+ container.
+
### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]`
* Show an inventory list if it has been sent to the client. Nothing will
be shown if the inventory list is of size 0.
* **Note**: With the new coordinate system, the spacing between inventory
slots is one-fourth the size of an inventory slot.
-* **Note**: Lists are drawn after every other element. This might change at any time.
### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]`
be shown if the inventory list is of size 0.
* **Note**: With the new coordinate system, the spacing between inventory
slots is one-fourth the size of an inventory slot.
-* **Note**: Lists are drawn after every other element. This might change at any time.
### `listring[<inventory location>;<list name>]`
### `tooltip[<gui_element_name>;<tooltip_text>;<bgcolor>;<fontcolor>]`
* Adds tooltip for an element
-* `<bgcolor>` tooltip background color as `ColorString` (optional)
-* `<fontcolor>` tooltip font color as `ColorString` (optional)
+* `bgcolor` tooltip background color as `ColorString` (optional)
+* `fontcolor` tooltip font color as `ColorString` (optional)
### `tooltip[<X>,<Y>;<W>,<H>;<tooltip_text>;<bgcolor>;<fontcolor>]`
* Adds tooltip for an area. Other tooltips will take priority when present.
-* `<bgcolor>` tooltip background color as `ColorString` (optional)
-* `<fontcolor>` tooltip font color as `ColorString` (optional)
+* `bgcolor` tooltip background color as `ColorString` (optional)
+* `fontcolor` tooltip font color as `ColorString` (optional)
### `image[<X>,<Y>;<W>,<H>;<texture name>]`
* Show an image
+### `animated_image[<X>,<Y>;<W>,<H>;<name>;<texture name>;<frame count>;<frame duration>;<frame start>]`
+
+* 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
+* `name`: Element name to send when an event occurs. The event value is the index of the current frame.
+* `texture name`: The image to use.
+* `frame count`: The number of frames animating the image.
+* `frame duration`: Milliseconds between each frame. `0` means the frames don't advance.
+* `frame start` (Optional): The index of the frame to start on. Default `1`.
+
### `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`, a fullscreen background is drawn and the color is ignored
- (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>]`
* 9-sliced background. See https://en.wikipedia.org/wiki/9-slice_scaling
* Middle is a rect which defines the middle of the 9-slice.
- * `x` - The middle will be x pixels from all sides.
- * `x,y` - The middle will be x pixels from the horizontal and y from the vertical.
- * `x,y,x2,y2` - The middle will start at x,y, and end at x2, y2. Negative x2 and y2 values
- will be added to the width and height of the texture, allowing it to be used as the
- distance from the far end.
- * All numbers in middle are integers.
+ * `x` - The middle will be x pixels from all sides.
+ * `x,y` - The middle will be x pixels from the horizontal and y from the vertical.
+ * `x,y,x2,y2` - The middle will start at x,y, and end at x2, y2. Negative x2 and y2 values
+ will be added to the width and height of the texture, allowing it to be used as the
+ distance from the far end.
+ * All numbers in middle are integers.
* Example for formspec 8x4 in 16x resolution:
image shall be sized 8 times 16px times 4 times 16px
* If `auto_clip` is `true`, the background is clipped to the formspec size
an inventory slot.
### `hypertext[<X>,<Y>;<W>,<H>;<name>;<text>]`
-* Displays a static formated text with hyperlinks.
+* Displays a static formatted text with hyperlinks.
+* **Note**: This element is currently unstable and subject to change.
* `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.
+* `text` is the formatted text using `Markup Language` described below.
### `vertlabel[<X>,<Y>;<label>]`
* Textual label drawn vertically
* `name` fieldname data is transferred to Lua
* `caption 1`...: name shown on top of tab
* `current_tab`: index of selected tab 1...
-* `transparent` (optional): show transparent
-* `draw_border` (optional): draw border
+* `transparent` (optional): if true, tabs are semi-transparent
+* `draw_border` (optional): if true, draw a thin line at tab base
### `tabheader[<X>,<Y>;<H>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]`
### `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[<
selector 1>,<selector 2>;<prop1>;<prop2>;...]`
-* Set the style for the named element `name`.
+* Set the style for the element(s) matching `selector` by name.
+* `selector` can be one of:
+ * `<name>` - An element name. Includes `*`, which represents every element.
+ * `<name>:<state>` - An element name, a colon, and one or more states.
+* `state` is a list of states separated by the `+` character.
+ * If a state is provided, the style will only take effect when the element is in that state.
+ * All provided states must be active for the style to apply.
* Note: this **must** be before the element is defined.
* See [Styling Formspecs].
-### `style_type[<
type>;<prop1>;<prop2>;...]`
+### `style_type[<
selector 1>,<selector 2>;<prop1>;<prop2>;...]`
-* Sets the style for all elements of type `type` which appear after this element.
+* Set the style for the element(s) matching `selector` by type.
+* `selector` can be one of:
+ * `<type>` - An element type. Includes `*`, which represents every element.
+ * `<type>:<state>` - An element type, a colon, and one or more states.
+* `state` is a list of states separated by the `+` character.
+ * If a state is provided, the style will only take effect when the element is in that state.
+ * All provided states must be active for the style to apply.
* 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[<name 1>:<state>,<name 2>:<state>;<prop1>;<prop2>;...]
+ style_type[<type 1>,<type 2>;<prop1>;<prop2>;...]
+ style_type[<type 1>:<state>,<type 2>:<state>;<prop1>;<prop2>;...]
Where a prop is:
style[world_delete;bgcolor=red;textcolor=yellow]
button[4,3.95;2.6,1;world_delete;Delete]
+A name/type can optionally be a comma separated list of names/types, like so:
+
+ world_delete,world_create,world_configure
+ button,image_button
+
+A `*` type can be used to select every element in the formspec.
+
+Any name/type in the list can also be accompanied by a `+`-separated list of states, like so:
+
+ world_delete:hovered+pressed
+ button:pressed
+
+States allow you to apply styles in response to changes in the element, instead of applying at all times.
+
Setting a property to nothing will reset it to the default value. For example:
style_type[button;bgimg=button.png;bgimg_pressed=button_pressed.png;border=false]
Some types may inherit styles from parent types.
+* animated_image, inherits from image
* button
* button_exit, inherits from button
* checkbox
* 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.
* bgcolor_hovered - color when hovered. Defaults to a lighter bgcolor when not provided.
+ * This is deprecated, use states instead.
* bgcolor_pressed - color when pressed. Defaults to a darker bgcolor when not provided.
- * bgimg - standard image. Defaults to none.
- * bgimg_hovered - image when hovered. Defaults to bgimg when not provided.
- * bgimg_pressed - image when pressed. Defaults to bgimg when not provided.
+ * This is deprecated, use states instead.
+ * bgimg - standard background image. Defaults to none.
+ * bgimg_hovered - background image when hovered. Defaults to bgimg when not provided.
+ * This is deprecated, use states instead.
+ * bgimg_middle - Makes the bgimg textures render in 9-sliced mode and defines the middle rect.
+ See background9[] documentation for more details. This property also pads the
+ button's content when set.
+ * bgimg_pressed - background image when pressed. Defaults to bgimg when not provided.
+ * This is deprecated, use states instead.
* border - boolean, draw border. Set to false to hide the bevelled button pane. Default true.
+ * content_offset - 2d vector, shifts the position of the button's content without resizing it.
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
+ * padding - rect, adds space between the edges of the button and the content. This value is
+ relative to bgimg_middle.
* textcolor - color, default white.
* checkbox
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
* 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
- * 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.
+* image
* 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.
+ * This is deprecated, use states instead.
+ * fgimg_pressed - image when pressed. Defaults to fgimg when not provided.
+ * This is deprecated, use states instead.
+ * 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
+### Valid States
+
+* *all elements*
+ * default - Equivalent to providing no states
+* button, button_exit, image_button, item_image_button
+ * hovered - Active when the mouse is hovering over the element
+ * pressed - Active when the button is pressed
+
+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>`.
+Markup language used in `hypertext[]` elements uses tags that look like HTML tags.
+The markup language is currently unstable and subject to change. Use with caution.
+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.
* `vector.divide(v, x)`:
* Returns a scaled vector or Schur quotient.
+For the following functions `a` is an angle in radians and `r` is a rotation
+vector ({x = <pitch>, y = <yaw>, z = <roll>}) where pitch, yaw and roll are
+angles in radians.
+
+* `vector.rotate(v, r)`:
+ * Applies the rotation `r` to `v` and returns the result.
+ * `vector.rotate({x = 0, y = 0, z = 1}, r)` and
+ `vector.rotate({x = 0, y = 1, z = 0}, r)` return vectors pointing
+ forward and up relative to an entity's rotation `r`.
+* `vector.rotate_around_axis(v1, v2, a)`:
+ * Returns `v1` rotated around axis `v2` by `a` radians according to
+ the right hand rule.
+* `vector.dir_to_rotation(direction[, up])`:
+ * Returns a rotation vector for `direction` pointing forward using `up`
+ as the up vector.
+ * If `up` is omitted, the roll of the returned vector defaults to zero.
+ * Otherwise `direction` and `up` need to be vectors in a 90 degree angle to each other.
+
* `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
`minetest.translate`, but is in translation files.
* `@n` acts as a literal newline as well.
+Server side translations
+------------------------
+
+On some specific cases, server translation could be useful. For example, filter
+a list on labels and send results to client. A method is supplied to achieve
+that:
+
+`minetest.get_translated_string(lang_code, string)`: Translates `string` using
+translations for `lang_code` language. It gives the same result as if the string
+was translated by the client.
+The `lang_code` to use for a given player can be retrieved from
+the table returned by `minetest.get_player_information(name)`.
+IMPORTANT: This functionality should only be used for sorting, filtering or similar purposes.
+You do not need to use this to get translated strings to show up on the client.
Perlin noise
============
preferable for this to be different from other seeds, but sometimes it is useful
to be able to create identical noise patterns.
-When used in mapgen this is actually a 'seed offset', it is added to the
-'world seed' to create the seed used by the noise, to ensure the noise has a
-different pattern in different worlds.
+In some noise APIs the world seed is added to the seed specified in noise
+parameters. This is done to make the resulting noise pattern vary in different
+worlds, and be 'world-specific'.
### `octaves`
-----------
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`.
+
* `dir`: unit vector of direction of punch. Always defined. Points from the
puncher to the punched.
* `damage`: damage that will be done to entity.
+ * Can return `true` to prevent the default damage mechanism.
* `on_death(self, killer)`
* Called when the object dies.
* `killer`: an `ObjectRef` (can be `nil`)
formspec_version_element = true,
-- Whether AreaStore's IDs are kept on save/load (5.1.0)
area_store_persistent_ids = true,
+ -- Whether minetest.find_path is functional (5.2.0)
+ pathfinder_works = true,
+ -- Whether Collision info is available to an objects' on_step (5.3.0)
+ object_step_has_moveresult = true,
}
* `minetest.has_feature(arg)`: returns `boolean, missing_features`
{
address = "127.0.0.1", -- IP address of client
ip_version = 4, -- IPv4 / IPv6
+ connection_uptime = 200, -- seconds since client connected
+ protocol_version = 32, -- protocol version used by client
+ formspec_version = 2, -- supported formspec version
+ lang_code = "fr" -- Language code used for translation
+ -- the following keys can be missing if no stats have been collected yet
min_rtt = 0.01, -- minimum round trip time
max_rtt = 0.2, -- maximum round trip time
avg_rtt = 0.02, -- average round trip time
min_jitter = 0.01, -- minimum packet time jitter
max_jitter = 0.5, -- maximum packet time jitter
avg_jitter = 0.03, -- average packet time jitter
- connection_uptime = 200, -- seconds since client connected
- protocol_version = 32, -- protocol version used by client
- formspec_version = 2, -- supported formspec version
- -- following information is available on debug build only!!!
+ -- the following information is available in a debug build only!!!
-- DO NOT USE IN MODS
--ser_vers = 26, -- serialization version used by client
--major = 0, -- major version number
* `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.
* Called after generating a piece of world. Modifying nodes inside the area
is a bit faster than usually.
* `minetest.register_on_newplayer(function(ObjectRef))`
- * Called after a new player has been created
+ * Called when a new player enters the world for the first time
* `minetest.register_on_punchplayer(function(player, hitter, time_from_last_punch, tool_capabilities, dir, damage))`
* Called when a player is punched
* Note: This callback is invoked even if the punched player is dead.
* Called _before_ repositioning of player occurs
* return true in func to disable regular player placement
* `minetest.register_on_prejoinplayer(function(name, ip))`
- * Called before a player joins the game
- * If it returns a string, the player is disconnected with that string as
+ * Called when a client connects to the server, prior to authentication
+ * If it returns a string, the client is disconnected with that string as
reason.
-* `minetest.register_on_joinplayer(function(ObjectRef))`
+* `minetest.register_on_joinplayer(function(ObjectRef, last_login))`
* Called when a player joins the game
+ * `last_login`: The timestamp of the previous login, or nil if player is new
* `minetest.register_on_leaveplayer(function(ObjectRef, timed_out))`
* Called when a player leaves the game
* `timed_out`: True for timeout, false for other reasons.
+* `minetest.register_on_authplayer(function(name, ip, is_success))`
+ * Called when a client attempts to log into an account.
+ * `name`: The name of the account being authenticated.
+ * `ip`: The IP address of the client
+ * `is_success`: Whether the client was successfully authenticated
+ * For newly registered accounts, `is_success` will always be true
* `minetest.register_on_auth_fail(function(name, ip))`
- * Called when a client attempts to log into an account but supplies the
- wrong password.
- * `ip`: The IP address of the client.
- * `name`: The account the client attempted to log into.
+ * Deprecated: use `minetest.register_on_authplayer(name, ip, is_success)` instead.
* `minetest.register_on_cheat(function(ObjectRef, cheat))`
* Called when a player cheats
* `cheat`: `{type=<cheat_type>}`, where `<cheat_type>` is one of:
is a table containing each formspecs element value (as string), with
the `name` parameter as index for each. The value depends on the
formspec element type:
+ * `animated_image`: Returns the index of the current frame.
* `button` and variants: If pressed, contains the user-facing button
text as value. If not pressed, is `nil`
* `field`, `textarea` and variants: Text in the field
* The same as before, except that it is called before the player crafts, to
make craft prediction, and it should not change anything.
* `minetest.register_allow_player_inventory_action(function(player, action, inventory, inventory_info))`
- * Determinates how much of a stack may be taken, put or moved to a
+ * Determines how much of a stack may be taken, put or moved to a
player inventory.
* `player` (type `ObjectRef`) is the player who modified the inventory
`inventory` (type `InvRef`).
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.auth_reload()`
* See `reload()` in authentication handler definition
-`minetest.set_player_password`, `minetest_set_player_privs`,
-`minetest_get_player_privs` and `minetest.auth_reload` call the authentication
+`minetest.set_player_password`, `minetest.set_player_privs`,
+`minetest.get_player_privs` and `minetest.auth_reload` call the authentication
handler.
Chat
* Return value: Table with all node positions with a node air above
* Area volume is limited to 4,096,000 nodes
* `minetest.get_perlin(noiseparams)`
+ * Return world-specific perlin noise.
+ * The actual seed used is the noiseparams seed plus the world seed.
* `minetest.get_perlin(seeddiff, octaves, persistence, spread)`
- * Return world-specific perlin noise (`int(worldseed)+seeddiff`)
+ * Deprecated: use `minetest.get_perlin(noiseparams)` instead.
+ * Return world-specific perlin noise.
* `minetest.get_voxel_manip([pos1, pos2])`
* Return voxel manipulator object.
* Loads the manipulator from the map if positions are passed.
* `objects`: if false, only nodes will be returned. Default is `true`.
* `liquids`: if false, liquid nodes won't be returned. Default is `false`.
* `minetest.find_path(pos1,pos2,searchdistance,max_jump,max_drop,algorithm)`
- * returns table containing path
+ * returns table containing path that can be walked on
* returns a table of 3D points representing a path from `pos1` to `pos2` or
- `nil`.
+ `nil` on failure.
+ * Reasons for failure:
+ * No path exists at all
+ * No path exists within `searchdistance` (see below)
+ * Start or end pos is buried in land
* `pos1`: start position
* `pos2`: end position
- * `searchdistance`: number of blocks to search in each direction using a
- maximum metric.
+ * `searchdistance`: maximum distance from the search positions to search in.
+ In detail: Path must be completely inside a cuboid. The minimum
+ `searchdistance` of 1 will confine search between `pos1` and `pos2`.
+ Larger values will increase the size of this cuboid in all directions
* `max_jump`: maximum height difference to consider walkable
* `max_drop`: maximum height difference to consider droppable
- * `algorithm`: One of `"A*_noprefetch"` (default), `"A*"`, `"Dijkstra"`
+ * `algorithm`: One of `"A*_noprefetch"` (default), `"A*"`, `"Dijkstra"`.
+ Difference between `"A*"` and `"A*_noprefetch"` is that
+ `"A*"` will pre-calculate the cost-data, the other will calculate it
+ on-the-fly
* `minetest.spawn_tree (pos, {treedef})`
* spawns L-system tree at given `pos` with definition in `treedef` table
* `minetest.transforming_liquid_add(pos)`
* `minetest.add_node_level(pos, level)`
* increase level of leveled node by level, default `level` equals `1`
* if `totallevel > maxlevel`, returns rest (`total-max`)
- * can be negative for decreasing
+ * `level` must be between -127 and 127
* `minetest.fix_light(pos1, pos2)`: returns `true`/`false`
* resets the light in a cuboid-shaped part of
the map and removes lighting bugs.
given `param2` value.
* Returns `nil` if the given `paramtype2` does not contain color
information.
-* `minetest.get_node_drops(nodename, toolname)`
- * Returns list of item names.
- * **Note**: This will be removed or modified in a future version.
+* `minetest.get_node_drops(node, toolname)`
+ * Returns list of itemstrings that are dropped by `node` when dug
+ with `toolname`.
+ * `node`: node as table or node name
+ * `toolname`: name of the tool item (can be `nil`)
* `minetest.get_craft_result(input)`: returns `output, decremented_input`
* `input.method` = `"normal"` or `"cooking"` or `"fuel"`
* `input.width` = for example `3`
`{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.
* Returns a code (0: successful, 1: no such player, 2: player is connected)
* `minetest.remove_player_auth(name)`: remove player authentication data
* Returns boolean indicating success (false if player nonexistant)
+* `minetest.dynamic_add_media(filepath)`
+ * Adds the file at the given path to the media sent to clients by the server
+ on startup and also pushes this file to already connected clients.
+ The file must be a supported image, sound or model format. It must not be
+ modified, deleted, moved or renamed after calling this function.
+ The list of dynamically added media is not persisted.
+ * Returns boolean indicating success (duplicate files count as error)
+ * The media will be ready to use (in e.g. entity textures, sound_play)
+ immediately after calling this function.
+ Old clients that lack support for this feature will not see the media
+ unless they reconnect to the server.
+ * Since media transferred this way does not use client caching or HTTP
+ transfers, dynamic media should not be used with big files or performance
+ will suffer.
Bans
----
* Convert a table containing tables, strings, numbers, booleans and `nil`s
into string form readable by `minetest.deserialize`
* Example: `serialize({foo='bar'})`, returns `'return { ["foo"] = "bar" }'`
-* `minetest.deserialize(string)`: returns a table
- * Convert a string returned by `minetest.deserialize` into a table
+* `minetest.deserialize(string[, safe])`: returns a table
+ * Convert a string returned by `minetest.serialize` into a table
* `string` is loaded in an empty sandbox environment.
- * Will load functions, but they cannot access the global environment.
+ * Will load functions if safe is false or omitted. Although these functions
+ cannot directly access the global environment, they could bypass this
+ restriction with maliciously crafted Lua bytecode if mod security is
+ disabled.
+ * This function should not be used on untrusted data, regardless of the
+ value of `safe`. It is fine to serialize then deserialize user-provided
+ data, but directly providing user input to deserialize is always unsafe.
* Example: `deserialize('return { ["foo"] = "bar" }')`,
returns `{foo='bar'}`
* Example: `deserialize('print("foo")')`, returns `nil`
* Example: `minetest.rgba(10, 20, 30, 40)`, returns `"#0A141E28"`
* `minetest.encode_base64(string)`: returns string encoded in base64
* Encodes a string in base64.
-* `minetest.decode_base64(string)`: returns string
+* `minetest.decode_base64(string)`: returns string or nil for invalid base64
* Decodes a string encoded in base64.
* `minetest.is_protected(pos, name)`: returns boolean
* Returning `true` restricts the player `name` from modifying (i.e. digging,
* `minetest.record_protection_violation(pos, name)`
* This function calls functions registered with
`minetest.register_on_protection_violation`.
+* `minetest.is_creative_enabled(name)`: returns boolean
+ * Returning `true` means that Creative Mode is enabled for player `name`.
+ * `name` will be `""` for non-players or if the player is unknown.
+ * This function should be overridden by Creative Mode-related mods to
+ implement a per-player Creative Mode.
+ * By default, this function returns `true` if the setting
+ `creative_mode` is `true` and `false` otherwise.
* `minetest.is_area_protected(pos1, pos2, player_name, interval)`
* Returns the position of the first node that `player_name` may not modify
in the specified cuboid between `pos1` and `pos2`.
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).
+ * Only works at init time and must be called from the mod's main scope
+ (ie: the init.lua of the mod, not from another Lua file or within a function).
* **DO NOT ALLOW ANY OTHER MODS TO ACCESS THE RETURNED ENVIRONMENT, STORE
IT IN A LOCAL VARIABLE!**
-----------
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_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
+ * 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.
#### 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)`
* `0`: player is drowning
* max: bubbles bar is not shown
* See [Object properties] for more information
-* `set_fov(fov, is_multiplier)`: Sets player's FOV
+ * Is limited to range 0 ... 65535 (2^16 - 1)
+* `set_fov(fov, is_multiplier, transition_time)`: 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.
+ * `transition_time`: If defined, enables smooth FOV transition.
+ Interpreted as the time (in seconds) to reach target FOV.
+ If set to 0, FOV change is instantaneous. Defaults to 0.
+ * Set `fov` to 0 to clear FOV override.
+* `get_fov()`: Returns the following:
+ * Server-sent FOV value. Returns 0 if an FOV override doesn't exist.
+ * Boolean indicating whether the FOV value is a multiplier.
+ * Time (in seconds) taken for the FOV transition. Set by `set_fov`.
* `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
* `get_formspec_prepend(formspec)`: returns a formspec string.
* `get_player_control()`: returns table with player pressed keys
* The table consists of fields with boolean value representing the pressed
- keys, the fields are jump, right, left, LMB, RMB, sneak, aux1, down, up.
+ keys, the fields are jump, right, left, LMB, RMB, sneak, aux1, down, up, zoom.
* example: `{jump=false, right=true, left=false, LMB=false, RMB=false,
- sneak=true, aux1=false, down=false, up=false}`
+ sneak=true, aux1=false, down=false, up=false, zoom=false}`
+ * The `zoom` field is available since 5.3
* `get_player_control_bits()`: returns integer with bit packed player pressed
keys.
* bit nr/meaning: 0/up, 1/down, 2/left, 3/right, 4/jump, 5/aux1, 6/sneak,
- 7/LMB, 8/RMB
+ 7/LMB, 8/RMB, 9/zoom (zoom available since 5.3)
* `set_physics_override(override_table)`
* `override_table` is a table with the following fields:
* `speed`: multiplier to default walking speed value (default: `1`)
* `hud_set_hotbar_selected_image(texturename)`
* sets image for selected item of hotbar
* `hud_get_hotbar_selected_image`: returns texturename
-* `set_sky(bgcolor, type, {texture names}, clouds)`
- * `bgcolor`: ColorSpec, defaults to white
- * `type`: Available types:
- * `"regular"`: Uses 0 textures, `bgcolor` ignored
- * `"skybox"`: Uses 6 textures, `bgcolor` used
- * `"plain"`: Uses 0 textures, `bgcolor` used
- * `clouds`: Boolean for whether clouds appear in front of `"skybox"` or
- `"plain"` custom skyboxes (default: `true`)
-* `get_sky()`: returns bgcolor, type, table of textures, clouds
+* `set_sky(parameters)`
+ * `parameters` is a table with the following optional fields:
+ * `base_color`: ColorSpec, changes fog in "skybox" and "plain".
+ * `type`: Available types:
+ * `"regular"`: Uses 0 textures, `base_color` ignored
+ * `"skybox"`: Uses 6 textures, `base_color` used as fog.
+ * `"plain"`: Uses 0 textures, `base_color` used as both fog and sky.
+ * `textures`: A table containing up to six textures in the following
+ order: Y+ (top), Y- (bottom), X- (west), X+ (east), Z+ (north), Z- (south).
+ * `clouds`: Boolean for whether clouds appear. (default: `true`)
+ * `sky_color`: A table containing the following values, alpha is ignored:
+ * `day_sky`: ColorSpec, for the top half of the `"regular"`
+ sky during the day. (default: `#8cbafa`)
+ * `day_horizon`: ColorSpec, for the bottom half of the
+ `"regular"` sky during the day. (default: `#9bc1f0`)
+ * `dawn_sky`: ColorSpec, for the top half of the `"regular"`
+ sky during dawn/sunset. (default: `#b4bafa`)
+ The resulting sky color will be a darkened version of the ColorSpec.
+ Warning: The darkening of the ColorSpec is subject to change.
+ * `dawn_horizon`: ColorSpec, for the bottom half of the `"regular"`
+ sky during dawn/sunset. (default: `#bac1f0`)
+ The resulting sky color will be a darkened version of the ColorSpec.
+ Warning: The darkening of the ColorSpec is subject to change.
+ * `night_sky`: ColorSpec, for the top half of the `"regular"`
+ sky during the night. (default: `#006aff`)
+ The resulting sky color will be a dark version of the ColorSpec.
+ Warning: The darkening of the ColorSpec is subject to change.
+ * `night_horizon`: ColorSpec, for the bottom half of the `"regular"`
+ sky during the night. (default: `#4090ff`)
+ The resulting sky color will be a dark version of the ColorSpec.
+ Warning: The darkening of the ColorSpec is subject to change.
+ * `indoors`: ColorSpec, for when you're either indoors or
+ underground. Only applies to the `"regular"` sky.
+ (default: `#646464`)
+ * `fog_sun_tint`: ColorSpec, changes the fog tinting for the sun
+ at sunrise and sunset.
+ * `fog_moon_tint`: ColorSpec, changes the fog tinting for the moon
+ at sunrise and sunset.
+ * `fog_tint_type`: string, changes which mode the directional fog
+ abides by, `"custom"` uses `sun_tint` and `moon_tint`, while
+ `"default"` uses the classic Minetest sun and moon tinting.
+ Will use tonemaps, if set to `"default"`. (default: `"default"`)
+* `get_sky()`: returns base_color, type, table of textures, clouds.
+* `get_sky_color()`: returns a table with the `sky_color` parameters as in
+ `set_sky`.
+* `set_sun(parameters)`:
+ * `parameters` is a table with the following optional fields:
+ * `visible`: Boolean for whether the sun is visible.
+ (default: `true`)
+ * `texture`: A regular texture for the sun. Setting to `""`
+ will re-enable the mesh sun. (default: `"sun.png"`)
+ * `tonemap`: A 512x1 texture containing the tonemap for the sun
+ (default: `"sun_tonemap.png"`)
+ * `sunrise`: A regular texture for the sunrise texture.
+ (default: `"sunrisebg.png"`)
+ * `sunrise_visible`: Boolean for whether the sunrise texture is visible.
+ (default: `true`)
+ * `scale`: Float controlling the overall size of the sun. (default: `1`)
+* `get_sun()`: returns a table with the current sun parameters as in
+ `set_sun`.
+* `set_moon(parameters)`:
+ * `parameters` is a table with the following optional fields:
+ * `visible`: Boolean for whether the moon is visible.
+ (default: `true`)
+ * `texture`: A regular texture for the moon. Setting to `""`
+ will re-enable the mesh moon. (default: `"moon.png"`)
+ * `tonemap`: A 512x1 texture containing the tonemap for the moon
+ (default: `"moon_tonemap.png"`)
+ * `scale`: Float controlling the overall size of the moon (default: `1`)
+* `get_moon()`: returns a table with the current moon parameters as in
+ `set_moon`.
+* `set_stars(parameters)`:
+ * `parameters` is a table with the following optional fields:
+ * `visible`: Boolean for whether the stars are visible.
+ (default: `true`)
+ * `count`: Integer number to set the number of stars in
+ the skybox. Only applies to `"skybox"` and `"regular"` sky types.
+ (default: `1000`)
+ * `star_color`: ColorSpec, sets the colors of the stars,
+ alpha channel is used to set overall star brightness.
+ (default: `#ebebff69`)
+ * `scale`: Float controlling the overall size of the stars (default: `1`)
+* `get_stars()`: returns a table with the current stars parameters as in
+ `set_stars`.
* `set_clouds(parameters)`: set cloud parameters
* `parameters` is a table with the following optional fields:
* `density`: from `0` (no clouds) to `1` (full clouds) (default `0.4`)
-------------
A perlin noise generator.
-It can be created via `PerlinNoise(seed, octaves, persistence, spread)`
-or `PerlinNoise(noiseparams)`.
-Alternatively with `minetest.get_perlin(seeddiff, octaves, persistence, spread)`
-or `minetest.get_perlin(noiseparams)`.
+It can be created via `PerlinNoise()` or `minetest.get_perlin()`.
+For `minetest.get_perlin()`, the actual seed used is the noiseparams seed
+plus the world seed, to create world-specific noise.
+
+`PerlinNoise(noiseparams)`
+`PerlinNoise(seed, octaves, persistence, spread)` (Deprecated).
+
+`minetest.get_perlin(noiseparams)`
+`minetest.get_perlin(seeddiff, octaves, persistence, spread)` (Deprecated).
### Methods
It can be created via `PerlinNoiseMap(noiseparams, size)` or
`minetest.get_perlin_map(noiseparams, size)`.
+For `minetest.get_perlin_map()`, the actual seed used is the noiseparams seed
+plus the world seed, to create world-specific noise.
Format of `size` is `{x=dimx, y=dimy, z=dimz}`. The `z` component is omitted
for 2D noise, and it must be must be larger than 1 for 3D noise (otherwise
* `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"""`.
-- 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.
+ -- Object rotates along the local Y-axis, and works with set_rotation.
-- 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.
-- deleted when the block gets unloaded.
-- The get_staticdata() callback is never called then.
-- Defaults to 'true'.
+
+ damage_texture_modifier = "^[brighten",
+ -- Texture modifier to be applied for a short duration when object is hit
+
+ shaded = true,
+ -- Setting this to 'false' disables diffuse lighting of entity
}
Entity definition
on_activate = function(self, staticdata, dtime_s),
- on_step = function(self, dtime),
+ on_step = function(self, dtime, moveresult),
+ -- Called every server step
+ -- dtime: Elapsed time
+ -- moveresult: Table with collision info (only available if physical=true)
on_punch = function(self, puncher, time_from_last_punch, tool_capabilities, dir),
-- for more info) by using a '_' prefix
}
+Collision info passed to `on_step`:
+
+ {
+ touching_ground = boolean,
+ collides = boolean,
+ standing_on_object = boolean,
+ collisions = {
+ {
+ type = string, -- "node" or "object",
+ axis = string, -- "x", "y" or "z"
+ node_pos = vector, -- if type is "node"
+ object = ObjectRef, -- if type is "object"
+ old_velocity = vector,
+ new_velocity = vector,
+ },
+ ...
+ }
+ }
+
ABM (ActiveBlockModifier) definition
------------------------------------
wield_scale = {x = 1, y = 1, z = 1},
+ -- The default value of 99 may be configured by
+ -- users using the setting "default_stack_max"
stack_max = 99,
range = 4.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
-- 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),
visual_scale = 1.0,
-- Supported for drawtypes "plantlike", "signlike", "torchlike",
- -- "firelike", "mesh".
+ -- "firelike", "mesh", "nodebox", "allfaces".
-- 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
-- If true, a new liquid source can be created by placing two or more
-- sources nearby
- leveled = 16,
+ leveled = 0,
-- Only valid for "nodebox" drawtype with 'type = "leveled"'.
-- Allows defining the nodebox height without using param2.
-- The nodebox height is 'leveled' / 64 nodes.
- -- The maximum value of 'leveled' is 127.
+ -- The maximum value of 'leveled' is `leveled_max`.
+
+ leveled_max = 127,
+ -- Maximum value for `leveled` (0-127), enforced in
+ -- `minetest.set_node_level` and `minetest.add_node_level`.
liquid_range = 8, -- Number of flowing nodes around source (max. 8)
-- 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 = "",
-- node is deleted from the world or the drops are added. This is
-- generally the result of either the node being dug or an attached node
-- becoming detached.
+ -- oldmeta is the NodeMetaRef of the oldnode before deletion.
-- drops is a table of ItemStacks, so any metadata to be preserved can
-- be added directly to one or more of the dropped items. See
-- "ItemStackMetaRef".
on_punch = function(pos, node, puncher, pointed_thing),
-- default: minetest.node_punch
+ -- Called when puncher (an ObjectRef) punches the node at pos.
-- By default calls minetest.register_on_punchnode callbacks.
on_rightclick = function(pos, node, clicker, itemstack, pointed_thing),
-- default: nil
+ -- Called when clicker (an ObjectRef) "rightclicks"
+ -- ("rightclick" here stands for the placement key) while pointing at
+ -- the node at pos with 'node' being the node table.
-- itemstack will hold clicker's wielded item.
-- Shall return the leftover itemstack.
-- Note: pointed_thing can be nil, if a mod calls this function.
Used by `minetest.register_biome`.
+The maximum number of biomes that can be used is 65535. However, using an
+excessive number of biomes will slow down map generation. Depending on desired
+performance and computing power the practical limit is much lower.
+
{
name = "tundra",
text = "<text>",
+ text2 = "<text>",
+
number = 2,
item = 3,
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
size = 1,
-- Scales the visual size of the particle texture.
+ -- If `node` is set, size can be set to 0 to spawn a randomly-sized
+ -- particle (just like actual node dig particles).
collisiondetection = false,
-- If true collides with `walkable` nodes and, depending on the
-- If true faces player using y axis only
texture = "image.png",
+ -- The texture of the particle
playername = "singleplayer",
-- Optional, if specified spawns particle only on the player's client
glow = 0
-- Optional, specify particle self-luminescence in darkness.
-- Values 0-14.
+
+ node = {name = "ignore", param2 = 0},
+ -- Optional, if specified the particle will have the same appearance as
+ -- node dig particles for the given node.
+ -- `texture` and `animation` will be ignored if this is set.
+
+ node_tile = 0,
+ -- Optional, only valid in combination with `node`
+ -- If set to a valid number 1-6, specifies the tile from which the
+ -- particle texture is picked.
+ -- Otherwise, the default behavior is used. (currently: any random tile)
}
maxsize = 1,
-- The particles' properties are random values between the min and max
-- values.
- -- pos, velocity, acceleration, expirationtime, size
+ -- applies to: pos, velocity, acceleration, expirationtime, size
+ -- If `node` is set, min and maxsize can be set to 0 to spawn
+ -- randomly-sized particles (just like actual node dig particles).
collisiondetection = false,
-- If true collide with `walkable` nodes and, depending on the
-- If true face player using y axis only
texture = "image.png",
+ -- The texture of the particle
playername = "singleplayer",
-- Optional, if specified spawns particles only on the player's client
glow = 0
-- Optional, specify particle self-luminescence in darkness.
-- Values 0-14.
+
+ node = {name = "ignore", param2 = 0},
+ -- Optional, if specified the particles will have the same appearance as
+ -- node dig particles for the given node.
+ -- `texture` and `animation` will be ignored if this is set.
+
+ node_tile = 0,
+ -- Optional, only valid in combination with `node`
+ -- If set to a valid number 1-6, specifies the tile from which the
+ -- particle texture is picked.
+ -- Otherwise, the default behavior is used. (currently: any random tile)
}
`HTTPRequest` definition
projects / oweals / minetest.git / blobdiff