The game directory can contain the following files:
* `game.conf`, with the following keys:
- * `name`: Required, human readable name e.g. `name = Minetest`
+ * `name`: Required, a human readable title to address the game, 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.
+ 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`
e.g. `disallowed_mapgen_settings = mgv5_spflags`
These settings are hidden for this game in the world creation
dialog and game start menu.
+ * `author`: The author of the game. It only appears when downloaded from
+ ContentDB.
+ * `release`: Ignore this: Should only ever be set by ContentDB, as it is
+ an internal ID used to track versions.
* `minetest.conf`:
Used to set default settings when running this game.
* `settingtypes.txt`:
should be a mod, contains a file named `modpack.conf`.
The file is a key-value store of modpack details.
-* `name`: The modpack name.
+* `name`: The modpack name. Allows Minetest to determine the modpack name even
+ if the folder is wrongly named.
* `description`: Description of mod to be shown in the Mods tab of the main
menu.
+* `author`: The author of the modpack. It only appears when downloaded from
+ ContentDB.
+* `release`: Ignore this: Should only ever be set by ContentDB, as it is an
+ internal ID used to track versions.
+* `title`: A human-readable title to address the modpack.
Note: to support 0.4.x, please also create an empty modpack.txt file.
│ ├── models
│ ├── textures
│ │ ├── modname_stuff.png
- │ │ └── modname_something_else.png
+ │ │ ├── modname_stuff_normal.png
+ │ │ ├── modname_something_else.png
+ │ │ ├── subfolder_foo
+ │ │ │ ├── modname_more_stuff.png
+ │ │ │ └── another_subfolder
+ │ │ └── bar_subfolder
│ ├── sounds
│ ├── media
│ ├── locale
loaded before this mod.
* `optional_depends`: A comma separated list of optional dependencies.
Like a dependency, but no error if the mod doesn't exist.
+* `author`: The author of the mod. It only appears when downloaded from
+ ContentDB.
+* `release`: Ignore this: Should only ever be set by ContentDB, as it is an
+ internal ID used to track versions.
+* `title`: A human-readable title to address the mod.
Note: to support 0.4.x, please also provide depends.txt.
`minetest.settings` can be used to read custom or existing settings at load
time, if necessary. (See [`Settings`])
-### `models`
-
-Models for entities or meshnodes.
-
-### `textures`, `sounds`, `media`
+### `textures`, `sounds`, `media`, `models`, `locale`
Media files (textures, sounds, whatever) that will be transferred to the
-client and will be available for use by the mod.
+client and will be available for use by the mod and translation files for
+the clients (see [Translations]).
-### `locale`
+It is suggested to use the folders for the purpous they are thought for,
+eg. put textures into `textures`, translation files into `locale`,
+models for entities or meshnodes into `models` et cetera.
-Translation files for the clients. (See [Translations])
+These folders and subfolders can contain subfolders.
+Subfolders with names starting with `_` or `.` are ignored.
+If a subfolder contains a media file with the same name as a media file
+in one of its parents, the parent's file is used.
+
+Although it is discouraged, a mod can overwrite a media file of any mod that it
+depends on by supplying a file with an equal name.
Naming conventions
------------------
* e.g. `foomod_foothing.png`
* e.g. `foomod_foothing`
+
Texture modifiers
-----------------
There are various texture modifiers that can be used
-to generate textures on-the-fly.
+to let the client generate textures on-the-fly.
+The modifiers are applied directly in sRGB colorspace,
+i.e. without gamma-correction.
### Texture overlaying
-- Overlay tiles: define them in the same style
-- The top and bottom tile does not have overlay
overlay_tiles = {"", "",
- {name = "default_grass_side.png", tileable_vertical = false}},
+ {name = "default_grass_side.png"}},
-- Global color, used in inventory
color = "green",
-- Palette in the world
* `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
+ * Bits 0-2: Liquid level (0-7). The higher, the more liquid is in this node;
+ see `minetest.get_node_level`, `minetest.set_node_level` and `minetest.add_node_level`
+ to access/manipulate the content of this field
* Bit 3: If set, liquid is flowing downwards (no graphical effect)
* `paramtype2 = "wallmounted"`
* Supported drawtypes: "torchlike", "signlike", "normal", "nodebox", "mesh"
* The height of the 'plantlike' section is stored in `param2`.
* The height is (`param2` / 16) nodes.
* `paramtype2 = "degrotate"`
- * 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
+ * Valid for `plantlike` and `mesh` drawtypes. The rotation of the node is
+ stored in `param2`.
+ * Values range 0–239. The value stored in `param2` is multiplied by 1.5 to
get the actual rotation in degrees of the node.
* `paramtype2 = "meshoptions"`
* Only valid for "plantlike" drawtype. `param2` encodes the shape and
* `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 = "colordegrotate"`
+ * Same as `degrotate`, but with colors.
+ * The first (most-significant) three bits of `param2` tells which color
+ is picked from the palette. The palette should have 8 pixels.
+ * Remaining 5 bits store rotation in range 0–23 (i.e. in 15° steps)
* `paramtype2 = "none"`
* `param2` will not be used by the engine and can be used to store
an arbitrary value
* Invisible, uses no texture.
* `liquid`
* The cubic source node for a liquid.
+ * Faces bordering to the same node are never rendered.
+ * Connects to node specified in `liquid_alternative_flowing`.
+ * Use `backface_culling = false` for the tiles you want to make
+ visible when inside the node.
* `flowingliquid`
* The flowing version of a liquid, appears with various heights and slopes.
+ * Faces bordering to the same node are never rendered.
+ * Connects to node specified in `liquid_alternative_source`.
+ * Node textures are defined with `special_tiles` where the first tile
+ is for the top and bottom faces and the second tile is for the side
+ faces.
+ * `tiles` is used for the item/inventory/wield image rendering.
+ * Use `backface_culling = false` for the special tiles you want to make
+ visible when inside the node
* `glasslike`
* Often used for partially-transparent nodes.
* Only external sides of textures are visible.
used to compensate for how `glasslike` reduces visual thickness.
* `torchlike`
* A single vertical texture.
- * If placed on top of a node, uses the first texture specified in `tiles`.
- * If placed against the underside of a node, uses the second texture
- specified in `tiles`.
- * If placed on the side of a node, uses the third texture specified in
- `tiles` and is perpendicular to that node.
+ * If `paramtype2="[color]wallmounted":
+ * If placed on top of a node, uses the first texture specified in `tiles`.
+ * If placed against the underside of a node, uses the second texture
+ specified in `tiles`.
+ * If placed on the side of a node, uses the third texture specified in
+ `tiles` and is perpendicular to that node.
+ * If `paramtype2="none"`:
+ * Will be rendered as if placed on top of a node (see
+ above) and only the first texture is used.
* `signlike`
* A single texture parallel to, and mounted against, the top, underside or
side of a node.
+ * If `paramtype2="[color]wallmounted", it rotates according to `param2`
+ * If `paramtype2="none"`, it will always be on the floor.
* `plantlike`
* Two vertical and diagonal textures at right-angles to each other.
* See `paramtype2 = "meshoptions"` above for other options.
base cube without affecting them.
* The base cube texture tiles are defined as normal, the `plantlike`
extension uses the defined special tile, for example:
- `special_tiles = {{name = "default_papyrus.png", tileable_vertical = true}},`
+ `special_tiles = {{name = "default_papyrus.png"}},`
`*_optional` drawtypes need less rendering time if deactivated
(always client-side).
{-0.5, -0.5, -0.5, 0.5, 0.5, 0.5},
+To avoid collision issues, keep each value within the range of +/- 1.45.
+This also applies to leveled nodeboxes, where the final height shall not
+exceed this soft limit.
* `world_pos`: World position of the waypoint.
* `offset`: offset in pixels from position.
+### `compass`
+Displays an image oriented or translated according to current heading direction.
+
+* `size`: The size of this element. Negative values represent percentage
+ of the screen; e.g. `x=-100` means 100% (width).
+* `scale`: Scale of the translated image (used only for dir = 2 or dir = 3).
+* `text`: The name of the texture to use.
+* `alignment`: The alignment of the image.
+* `offset`: Offset in pixels from position.
+* `dir`: How the image is rotated/translated:
+ * 0 - Rotate as heading direction
+ * 1 - Rotate in reverse direction
+ * 2 - Translate as landscape direction
+ * 3 - Translate in reverse direction
+
+If translation is chosen, texture is repeated horizontally to fill the whole element.
+
+### `minimap`
+
+Displays a minimap on the HUD.
+
+* `size`: Size of the minimap to display. Minimap should be a square to avoid
+ distortion.
+* `alignment`: The alignment of the minimap.
+* `offset`: offset in pixels from position.
Representations of simple things
================================
{x=num, y=num, z=num}
+ Note: it is highly recommended to construct a vector using the helper function:
+ vector.new(num, num, num)
+
For helper functions see [Spatial Vectors].
`pointed_thing`
* `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)`
+* `fall_damage_add_percent`: modifies the fall damage suffered when hitting
+ the top of this node. There's also an armor group with the same name.
+ The final player damage is determined by the following formula:
+ damage =
+ collision speed
+ * ((node_fall_damage_add_percent + 100) / 100) -- node group
+ * ((player_fall_damage_add_percent + 100) / 100) -- player armor group
+ - (14) -- constant tolerance
+ Negative damage values are discarded as no damage.
* `falling_node`: if there is no walkable block under the node it will fall
* `float`: the node will not fall through liquids
* `level`: Can be used to give an additional sense of progression in the game.
`"toolrepair"` crafting recipe
-### `ObjectRef` groups
+### `ObjectRef` armor 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.
+ will also hide the integrated HUD status bars for players. It is
+ automatically set to all players when damage is disabled on the server and
+ cannot be reset (subject to change).
+* `fall_damage_add_percent`: Modifies the fall damage suffered by players
+ when they hit the ground. It is analog to the node group with the same
+ name. See the node group above for the exact calculation.
* `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.
Some of the values in the key-value store are handled specially:
-* `description`: Set the item stack's description. Defaults to
- `idef.description`.
+* `description`: Set the item stack's description.
+ See also: `get_description` in [`ItemStack`]
+* `short_description`: Set the item stack's short description.
+ See also: `get_short_description` in [`ItemStack`]
* `color`: A `ColorString`, which sets the stack's color.
* `palette_index`: If the item has a palette, this is used to get the
current color from the palette.
list[current_player;craft;3,0;3,3;]
list[current_player;craftpreview;7,1;1,1;]
+Version History
+---------------
+
+* FORMSPEC VERSION 1:
+ * (too much)
+* FORMSPEC VERSION 2:
+ * Forced real coordinates
+ * background9[]: 9-slice scaling parameters
+* FORMSPEC VERSION 3:
+ * Formspec elements are drawn in the order of definition
+ * bgcolor[]: use 3 parameters (bgcolor, formspec (now an enum), fbgcolor)
+ * box[] and image[] elements enable clipping by default
+ * new element: scroll_container[]
+* FORMSPEC VERSION 4:
+ * Allow dropdown indexing events
+
Elements
--------
* Clients older than this version can neither show newer elements nor display
elements with new arguments correctly.
* Available since feature `formspec_version_element`.
+* See also: [Version History]
### `size[<W>,<H>,<fixed_size>]`
* 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.
+ slots is one-fourth the size of an inventory slot by default. Also see
+ [Styling Formspecs] for changing the size of slots and spacing.
### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]`
* `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`.
+### `model[<X>,<Y>;<W>,<H>;<name>;<mesh>;<textures>;<rotation X,Y>;<continuous>;<mouse control>;<frame loop range>;<animation speed>]`
+
+* Show a mesh model.
+* `name`: Element name that can be used for styling
+* `mesh`: The mesh model to use.
+* `textures`: The mesh textures to use according to the mesh materials.
+ Texture names must be separated by commas.
+* `rotation {X,Y}` (Optional): Initial rotation of the camera.
+ The axes are euler angles in degrees.
+* `continuous` (Optional): Whether the rotation is continuous. Default `false`.
+* `mouse control` (Optional): Whether the model can be controlled with the mouse. Default `true`.
+* `frame loop range` (Optional): Range of the animation frames.
+ * Defaults to the full range of all available frames.
+ * Syntax: `<begin>,<end>`
+* `animation speed` (Optional): Sets the animation speed. Default 0 FPS.
+
### `item_image[<X>,<Y>;<W>,<H>;<item name>]`
* Show an inventory image of registered item/node
* Simple colored box
* `color` is color specified as a `ColorString`.
If the alpha component is left blank, the box will be semitransparent.
+ If the color is not specified, the box will use the options specified by
+ its style. If the color is specified, all styling options will be ignored.
-### `dropdown[<X>,<Y>;<W>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>]`
+### `dropdown[<X>,<Y>;<W>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>;<index event>]`
* Show a dropdown field
* **Important note**: There are two different operation modes:
* Fieldname data is transferred to Lua
* Items to be shown in dropdown
* Index of currently selected dropdown item
+* `index event` (optional, allowed parameter since formspec version 4): Specifies the
+ event field value for selected items.
+ * `true`: Selected item index
+ * `false` (default): Selected item value
-### `dropdown[<X>,<Y>;<W>,<H>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>]`
+### `dropdown[<X>,<Y>;<W>,<H>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>;<index event>]`
* Show a dropdown field
* **Important note**: This syntax for dropdowns can only be used with the
* Fieldname data is transferred to Lua
* Items to be shown in dropdown
* Index of currently selected dropdown item
+* `index event` (optional, allowed parameter since formspec version 4): Specifies the
+ event field value for selected items.
+ * `true`: Selected item index
+ * `false` (default): Selected item value
### `checkbox[<X>,<Y>;<name>;<label>;<selected>]`
* 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`
+* `orientation`: `vertical`/`horizontal`. Default horizontal.
* Fieldname data is transferred to Lua
* Value of this trackbar is set to (`0`-`1000`) by default
* See also `minetest.explode_scrollbar_event`
* `span=<value>`: number of following columns to affect
(default: infinite).
-### `style[<selector 1>,<selector 2>;<prop1>;<prop2>;...]`
+### `style[<selector 1>,<selector 2>
,...;<prop1>;<prop2>;...]`
* Set the style for the element(s) matching `selector` by name.
* `selector` can be one of:
* See [Styling Formspecs].
-### `style_type[<selector 1>,<selector 2>;<prop1>;<prop2>;...]`
+### `style_type[<selector 1>,<selector 2>
,...;<prop1>;<prop2>;...]`
* Set the style for the element(s) matching `selector` by type.
* `selector` can be one of:
* All provided states must be active for the style to apply.
* See [Styling Formspecs].
+### `set_focus[<name>;<force>]`
+
+* Sets the focus to the element with the same `name` parameter.
+* **Note**: This element must be placed before the element it focuses.
+* `force` (optional, default `false`): By default, focus is not applied for
+ re-sent formspecs with the same name so that player-set focus is kept.
+ `true` sets the focus to the specified element for every sent formspec.
+* The following elements have the ability to be focused:
+ * checkbox
+ * button
+ * button_exit
+ * image_button
+ * image_button_exit
+ * item_image_button
+ * table
+ * textlist
+ * dropdown
+ * field
+ * pwdfield
+ * textarea
+ * scrollbar
+
Migrating to Real Coordinates
-----------------------------
Formspec elements can be themed using the style elements:
- 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>;...]
+ 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:
Some types may inherit styles from parent types.
* animated_image, inherits from image
+* box
* button
* button_exit, inherits from button
* checkbox
-* scrollbar
-* table
-* textlist
* dropdown
* field
-* pwdfield, inherits from field
-* textarea
-* label
-* vertlabel, inherits from field
+* image
* image_button
* item_image_button
+* label
+* list
+* model
+* pwdfield, inherits from field
+* scrollbar
* tabheader
+* table
+* textarea
+* textlist
+* vertlabel, inherits from label
### Valid Properties
* 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
+ * Defaults to false in formspec_version version 3 or higher
+ * **Note**: `colors`, `bordercolors`, and `borderwidths` accept multiple input types:
+ * Single value (e.g. `#FF0`): All corners/borders.
+ * Two values (e.g. `red,#FFAAFF`): top-left and bottom-right,top-right and bottom-left/
+ top and bottom,left and right.
+ * Four values (e.g. `blue,#A0F,green,#FFFA`): top-left/top and rotates clockwise.
+ * These work similarly to CSS borders.
+ * colors - `ColorString`. Sets the color(s) of the box corners. Default `black`.
+ * bordercolors - `ColorString`. Sets the color(s) of the borders. Default `black`.
+ * borderwidths - Integer. Sets the width(s) of the borders in pixels. If the width is
+ negative, the border will extend inside the box, whereas positive extends outside
+ the box. A width of zero results in no border; this is default.
* 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.
+ * 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.
+ * font - Sets font type. This is a comma separated list of options. Valid options:
+ * Main font type options. These cannot be combined with each other:
+ * `normal`: Default font
+ * `mono`: Monospaced font
+ * Font modification options. If used without a main font type, `normal` is used:
+ * `bold`: Makes font bold.
+ * `italic`: Makes font italic.
+ Default `normal`.
+ * font_size - Sets font size. Default is user-set. Can have multiple values:
+ * `<number>`: Sets absolute font size to `number`.
+ * `+<number>`/`-<number>`: Offsets default font size by `number` points.
+ * `*<number>`: Multiplies default font size by `number`, similar to CSS `em`.
* 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.
+ * sound - a sound to be played when triggered.
* textcolor - color, default white.
* checkbox
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
-* scrollbar
- * noclip - boolean, set to true to allow the element to exceed formspec bounds.
-* table, textlist
- * noclip - boolean, set to true to allow the element to exceed formspec bounds.
+ * sound - a sound to be played when triggered.
* dropdown
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
+ * sound - a sound to be played when the entry is changed.
* field, pwdfield, textarea
* border - set to false to hide the textbox background and border. Default true.
+ * font - Sets font type. See button `font` property for more information.
+ * font_size - Sets font size. See button `font_size` property for more information.
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
* textcolor - color. Default white.
+* model
+ * bgcolor - color, sets background color.
+ * noclip - boolean, set to true to allow the element to exceed formspec bounds.
+ * Default to false in formspec_version version 3 or higher
* image
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
* 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
+ * font - Sets font type. See button `font` property for more information.
+ * font_size - Sets font size. See button `font_size` property for more information.
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
+* list
+ * noclip - boolean, set to true to allow the element to exceed formspec bounds.
+ * size - 2d vector, sets the size of inventory slots in coordinates.
+ * spacing - 2d vector, sets the space between inventory slots in coordinates.
* 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
+ * sound - a sound to be played when triggered.
+* scrollbar
+ * noclip - boolean, set to true to allow the element to exceed formspec bounds.
* tabheader
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
+ * sound - a sound to be played when a different tab is selected.
* textcolor - color. Default white.
+* table, textlist
+ * font - Sets font type. See button `font` property for more information.
+ * font_size - Sets font size. See button `font_size` property for more information.
+ * noclip - boolean, set to true to allow the element to exceed formspec bounds.
### Valid States
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.
+If you want to insert a literal greater-than sign or a backslash into the text,
+you must escape it by preceding it with a backslash.
+
These are the technically basic tags but see below for usual tags. Base tags are:
`<style color=... font=... size=...>...</style>`
Named colors are also supported and are equivalent to
[CSS Color Module Level 4](http://dev.w3.org/csswg/css-color/#named-colors).
-To specify the value of the alpha channel, append `#AA` to the end of the color
-name (e.g. `colorname#08`). For named colors the hexadecimal string
-representing the alpha value must (always) be two hexadecimal digits.
+To specify the value of the alpha channel, append `#A` or `#AA` to the end of
+the color name (e.g. `colorname#08`).
`ColorSpec`
-----------
Internally, it is implemented as a table with the 3 fields
`x`, `y` and `z`. Example: `{x = 0, y = 1, z = 0}`.
+However, one should *never* create a vector manually as above, such misbehavior
+is deprecated. The vector helpers set a metatable for the created vectors which
+allows indexing with numbers, calling functions directly on vectors and using
+operators (like `+`). Furthermore, the internal implementation might change in
+the future.
+Old code might still use vectors without metatables, be aware of this!
+
+All these forms of addressing a vector `v` are valid:
+`v[1]`, `v[3]`, `v.x`, `v[1] = 42`, `v.y = 13`
+
+Where `v` is a vector and `foo` stands for any function name, `v:foo(...)` does
+the same as `vector.foo(v, ...)`, apart from deprecated functionality.
+
+The metatable that is used for vectors can be accessed via `vector.metatable`.
+Do not modify it!
+
+All `vector.*` functions allow vectors `{x = X, y = Y, z = Z}` without metatables.
+Returned vectors always have a metatable set.
For the following functions, `v`, `v1`, `v2` are vectors,
-`p1`, `p2` are positions:
+`p1`, `p2` are positions,
+`s` is a scalar (a number),
+vectors are written like this: `(x, y, z)`:
-* `vector.new(a[, b, c])`:
+* `vector.new([a[, b, c]])`:
* Returns a vector.
* A copy of `a` if `a` is a vector.
- * `{x = a, y = b, z = c}`, if all of `a`, `b`, `c` are defined numbers.
+ * `(a, b, c)`, if all of `a`, `b`, `c` are defined numbers.
+ * `(0, 0, 0)`, if no arguments are given.
+* `vector.from_string(s[, init])`:
+ * Returns `v, np`, where `v` is a vector read from the given string `s` and
+ `np` is the next position in the string after the vector.
+ * Returns `nil` on failure.
+ * `s`: Has to begin with a substring of the form `"(x, y, z)"`. Additional
+ spaces, leaving away commas and adding an additional comma to the end
+ is allowed.
+ * `init`: If given starts looking for the vector at this string index.
+* `vector.to_string(v)`:
+ * Returns a string of the form `"(x, y, z)"`.
* `vector.direction(p1, p2)`:
* Returns a vector of length 1 with direction `p1` to `p2`.
- * If `p1` and `p2` are identical, returns `{x = 0, y = 0, z = 0}`.
+ * If `p1` and `p2` are identical, returns `(0, 0, 0)`.
* `vector.distance(p1, p2)`:
* Returns zero or a positive number, the distance between `p1` and `p2`.
* `vector.length(v)`:
* Returns zero or a positive number, the length of vector `v`.
* `vector.normalize(v)`:
* Returns a vector of length 1 with direction of vector `v`.
- * If `v` has zero length, returns `{x = 0, y = 0, z = 0}`.
+ * If `v` has zero length, returns `(0, 0, 0)`.
* `vector.floor(v)`:
* Returns a vector, each dimension rounded down.
* `vector.round(v)`:
* Returns a vector, each dimension rounded to nearest integer.
+ * At a multiple of 0.5, rounds away from zero.
* `vector.apply(v, func)`:
* Returns a vector where the function `func` has been applied to each
component.
* Returns in order minp, maxp vectors of the cuboid defined by `v1`, `v2`.
* `vector.angle(v1, v2)`:
* Returns the angle between `v1` and `v2` in radians.
-* `vector.dot(v1, v2)`
- * Returns the dot product of `v1` and `v2`
-* `vector.cross(v1, v2)`
- * Returns the cross product of `v1` and `v2`
+* `vector.dot(v1, v2)`:
+ * Returns the dot product of `v1` and `v2`.
+* `vector.cross(v1, v2)`:
+ * Returns the cross product of `v1` and `v2`.
+* `vector.offset(v, x, y, z)`:
+ * Returns the sum of the vectors `v` and `(x, y, z)`.
+* `vector.check()`:
+ * Returns a boolean value indicating whether `v` is a real vector, eg. created
+ by a `vector.*` function.
+ * Returns `false` for anything else, including tables like `{x=3,y=1,z=4}`.
For the following functions `x` can be either a vector or a number:
* Returns a vector.
* If `x` is a vector: Returns the difference of `v` subtracted by `x`.
* If `x` is a number: Subtracts `x` from each component of `v`.
-* `vector.multiply(v, x)`:
- * Returns a scaled vector or Schur product.
-* `vector.divide(v, x)`:
- * Returns a scaled vector or Schur quotient.
+* `vector.multiply(v, s)`:
+ * Returns a scaled vector.
+ * Deprecated: If `s` is a vector: Returns the Schur product.
+* `vector.divide(v, s)`:
+ * Returns a scaled vector.
+ * Deprecated: If `s` is a vector: Returns the Schur quotient.
+
+Operators can be used if all of the involved vectors have metatables:
+* `v1 == v2`:
+ * Returns whether `v1` and `v2` are identical.
+* `-v`:
+ * Returns the additive inverse of v.
+* `v1 + v2`:
+ * Returns the sum of both vectors.
+ * Note: `+` can not be used together with scalars.
+* `v1 - v2`:
+ * Returns the difference of `v1` subtracted by `v2`.
+ * Note: `-` can not be used together with scalars.
+* `v * s` or `s * v`:
+ * Returns `v` scaled by `s`.
+* `v / s`:
+ * Returns `v` scaled by `1 / s`.
+
+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(vector.new(0, 0, 1), r)` and
+ `vector.rotate(vector.new(0, 1, 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.
* If the absolute value of `x` is within the `tolerance` or `x` is NaN,
`0` is returned.
* `math.factorial(x)`: returns the factorial of `x`
+* `math.round(x)`: Returns `x` rounded to the nearest integer.
+ * At a multiple of 0.5, rounds away from zero.
* `string.split(str, separator, include_empty, max_splits, sep_is_pattern)`
* `separator`: string, default: `","`
* `include_empty`: boolean, default: `false`
* 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.
+ * If multiple keys in `t` map to the same value, it is unspecified which
+ value maps to that key.
* `table.shuffle(table, [from], [to], [random_func])`:
* Shuffles elements `from` to `to` in `table` in place
* `from` defaults to `1`
* Called when the object is instantiated.
* `dtime_s` is the time passed since the object was unloaded, which can be
used for updating the entity state.
+* `on_deactivate(self)
+ * Called when the object is about to get removed or unloaded.
* `on_step(self, dtime)`
* Called on every server tick, after movement and collision processing.
`dtime` is usually 0.1 seconds, as per the `dedicated_server_step` setting
* `minetest.get_current_modname()`: returns the currently loading mod's name,
when loading a mod.
-* `minetest.get_modpath(modname)`: returns e.g.
- `"/home/user/.minetest/usermods/modname"`.
- * Useful for loading additional `.lua` modules or static data from mod
-* `minetest.get_modnames()`: returns a list of installed mods
- * Return a list of installed mods, sorted alphabetically
+* `minetest.get_modpath(modname)`: returns the directory path for a mod,
+ e.g. `"/home/user/.minetest/usermods/modname"`.
+ * Returns nil if the mod is not enabled or does not exist (not installed).
+ * Works regardless of whether the mod has been loaded yet.
+ * Useful for loading additional `.lua` modules or static data from a mod,
+ or checking if a mod is enabled.
+* `minetest.get_modnames()`: returns a list of enabled mods, sorted alphabetically.
+ * Does not include disabled mods, even if they are installed.
* `minetest.get_worldpath()`: returns e.g. `"/home/user/.minetest/world"`
* Useful for storing custom data
* `minetest.is_singleplayer()`
pathfinder_works = true,
-- Whether Collision info is available to an objects' on_step (5.3.0)
object_step_has_moveresult = true,
+ -- Whether get_velocity() and add_velocity() can be used on players (5.4.0)
+ direct_velocity_on_players = true,
+ -- nodedef's use_texture_alpha accepts new string modes (5.4.0)
+ use_texture_alpha_string_modes = true,
+ -- degrotate param2 rotates in units of 1.5° instead of 2°
+ -- thus changing the range of values from 0-179 to 0-240 (5.5.0)
+ degrotate_240_steps = true,
+ -- ABM supports min_y and max_y fields in definition (5.5.0)
+ abm_min_max_y = true,
}
* `minetest.has_feature(arg)`: returns `boolean, missing_features`
* `minetest.sha1(data, [raw])`: returns the sha1 hash of data
* `data`: string of data to hash
* `raw`: return raw bytes instead of hex digits, default: false
+* `minetest.colorspec_to_colorstring(colorspec)`: Converts a ColorSpec to a
+ ColorString. If the ColorSpec is invalid, returns `nil`.
+ * `colorspec`: The ColorSpec to convert
Logging
-------
the puncher to the punched.
* `damage`: Number that represents the damage calculated by the engine
* should return `true` to prevent the default damage mechanism
+* `minetest.register_on_rightclickplayer(function(player, clicker))`
+ * Called when a player is right-clicked
+ * `player`: ObjectRef - Player that was right-clicked
+ * `clicker`: ObjectRef - Object that right-clicked, may or may not be a player
* `minetest.register_on_player_hpchange(function(player, hp_change, reason), modifier)`
* Called when the player gets damaged or healed
* `player`: ObjectRef of the player
* `cheat`: `{type=<cheat_type>}`, where `<cheat_type>` is one of:
* `moved_too_fast`
* `interacted_too_far`
+ * `interacted_with_self`
* `interacted_while_dead`
* `finished_unknown_dig`
* `dug_unbreakable`
* Called always when a player says something
* Return `true` to mark the message as handled, which means that it will
not be sent to other players.
+* `minetest.register_on_chatcommand(function(name, command, params))`
+ * Called always when a chatcommand is triggered, before `minetest.registered_chatcommands`
+ is checked to see if the command exists, but after the input is parsed.
+ * Return `true` to mark the command as handled, which means that the default
+ handlers will be prevented.
* `minetest.register_on_player_receive_fields(function(player, formname, fields))`
* Called when the server received input from `player` in a formspec with
the given `formname`. Specifically, this is called on any of the
* a button was pressed,
* Enter was pressed while the focus was on a text field
* a checkbox was toggled,
- * something was selecteed in a drop-down list,
+ * something was selected in a dropdown list,
* a different tab was selected,
* selection was changed in a textlist or table,
* an entry was double-clicked in a textlist or table,
* `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
- * `dropdown`: Text of selected item
+ * `dropdown`: Either the index or value, depending on the `index event`
+ dropdown argument.
* `tabheader`: Tab index, starting with `"1"` (only if tab changed)
* `checkbox`: `"true"` if checked, `"false"` if unchecked
* `textlist`: See `minetest.explode_textlist_event`
* `pos`: The position where to measure the light.
* `timeofday`: `nil` for current time, `0` for night, `0.5` for day
* Returns a number between `0` and `15` or `nil`
+ * `nil` is returned e.g. when the map isn't loaded at `pos`
+* `minetest.get_natural_light(pos[, timeofday])`
+ * Figures out the sunlight (or moonlight) value at pos at the given time of
+ day.
+ * `pos`: The position of the node
+ * `timeofday`: `nil` for current time, `0` for night, `0.5` for day
+ * Returns a number between `0` and `15` or `nil`
+ * This function tests 203 nodes in the worst case, which happens very
+ unlikely
+* `minetest.get_artificial_light(param1)`
+ * Calculates the artificial light (light from e.g. torches) value from the
+ `param1` value.
+ * `param1`: The param1 value of a `paramtype = "light"` node.
+ * Returns a number between `0` and `15`
+ * Currently it's the same as `math.floor(param1 / 16)`, except that it
+ ensures compatibility.
* `minetest.place_node(pos, node)`
* Place node with the same effects that a player would cause
* `minetest.dig_node(pos)`
* Punch node with the same effects that a player would cause
* `minetest.spawn_falling_node(pos)`
* Change node into falling node
- * Returns `true` if successful, `false` on failure
+ * Returns `true` and the ObjectRef of the spawned entity if successful, `false` on failure
* `minetest.find_nodes_with_meta(pos1, pos2)`
* Get a table of positions of nodes that have metadata within a region
* `minetest.get_objects_inside_radius(pos, radius)`: returns a list of
ObjectRefs.
* `radius`: using an euclidean metric
+* `minetest.get_objects_in_area(pos1, pos2)`: returns a list of
+ ObjectRefs.
+ * `pos1` and `pos2` are the min and max positions of the area to search.
* `minetest.set_timeofday(val)`
* `val` is between `0` and `1`; `0` for midnight, `0.5` for midday
* `minetest.get_timeofday()`
* `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
* `search_center` is an optional boolean (default: `false`)
If true `pos` is also checked for the nodes
-* `minetest.find_nodes_in_area(pos1, pos2, nodenames)`: returns a list of
- positions.
+* `minetest.find_nodes_in_area(pos1, pos2, nodenames, [grouped])`
+ * `pos1` and `pos2` are the min and max positions of the area to search.
* `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
- * First return value: Table with all node positions
- * Second return value: Table with the count of each node with the node name
- as index.
+ * If `grouped` is true the return value is a table indexed by node name
+ which contains lists of positions.
+ * If `grouped` is false or absent the return values are as follows:
+ first value: Table with all node positions
+ second value: Table with the count of each node with the node name
+ as index
* Area volume is limited to 4,096,000 nodes
* `minetest.find_nodes_in_area_under_air(pos1, pos2, nodenames)`: returns a
list of positions.
* `minetest.sound_fade(handle, step, gain)`
* `handle` is a handle returned by `minetest.sound_play`
* `step` determines how fast a sound will fade.
- Negative step will lower the sound volume, positive step will increase
- the sound volume.
+ The gain will change by this much per second,
+ until it reaches the target gain.
+ Note: Older versions used a signed step. This is deprecated, but old
+ code will still work. (the client uses abs(step) to correct it)
* `gain` the target gain for the fade.
+ Fading to zero will delete the sound.
Timing
------
-* `minetest.after(time, func, ...)`
+* `minetest.after(time, func, ...)` : returns job table to use as below.
* Call the function `func` after `time` seconds, may be fractional
* Optional: Variable number of arguments that are passed to `func`
+* `job:cancel()`
+ * Cancels the job function from being called
+
Server
------
* 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, callback)`
+ * `filepath`: path to a media file on the filesystem
+ * `callback`: function with arguments `name`, where name is a player name
+ (previously there was no callback argument; omitting it is deprecated)
+ * Adds the file 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 false on error, true if the request was accepted
+ * The given callback will be called for every player as soon as the
+ media is available on the client.
+ Old clients that lack support for this feature will not see the media
+ unless they reconnect to the server. (callback won't be called)
+ * Since media transferred this way currently does not use client caching
+ or HTTP transfers, dynamic media should not be used with big files.
Bans
----
* 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 or nil for invalid base64
+* `minetest.decode_base64(string)`: returns string or nil on failure
+ * Padding characters are only supported starting at version 5.4.0, where
+ 5.5.0 and newer perform proper checks.
* Decodes a string encoded in base64.
* `minetest.is_protected(pos, name)`: returns boolean
* Returning `true` restricts the player `name` from modifying (i.e. digging,
* If `transient` is `false` or absent, frees a persistent forceload.
If `true`, frees a transient forceload.
+* `minetest.compare_block_status(pos, condition)`
+ * Checks whether the mapblock at positition `pos` is in the wanted condition.
+ * `condition` may be one of the following values:
+ * `"unknown"`: not in memory
+ * `"emerging"`: in the queue for loading from disk or generating
+ * `"loaded"`: in memory but inactive (no ABMs are executed)
+ * `"active"`: in memory and active
+ * Other values are reserved for future functionality extensions
+ * Return value, the comparison status:
+ * `false`: Mapblock does not fulfil the wanted condition
+ * `true`: Mapblock meets the requirement
+ * `nil`: Unsupported `condition` value
+
* `minetest.request_insecure_environment()`: returns an environment containing
insecure functions if the calling mod has been listed as trusted in the
`secure.trusted_mods` setting or security is disabled, otherwise returns
* Map of registered tool definitions, indexed by name
* `minetest.registered_entities`
* Map of registered entity prototypes, indexed by name
+ * Values in this table may be modified directly.
+ Note: changes to initial properties will only affect entities spawned afterwards,
+ as they are only read when spawning.
* `minetest.object_refs`
* Map of object references, indexed by active object id
* `minetest.luaentities`
* Map of registered chat command definitions, indexed by name
* `minetest.registered_privileges`
* Map of registered privilege definitions, indexed by name
+ * Registered privileges can be modified directly in this table.
### Registered callback tables
`minetest.get_inventory(location)`.
* returns `{type="undefined"}` in case location is not known
+### Callbacks
+
+Detached & nodemeta inventories provide the following callbacks for move actions:
+
+#### Before
+
+The `allow_*` callbacks return how many items can be moved.
+
+* `allow_move`/`allow_metadata_inventory_move`: Moving items in the inventory
+* `allow_take`/`allow_metadata_inventory_take`: Taking items from the inventory
+* `allow_put`/`allow_metadata_inventory_put`: Putting items to the inventory
+
+#### After
+
+The `on_*` callbacks are called after the items have been placed in the inventories.
+
+* `on_move`/`on_metadata_inventory_move`: Moving items in the inventory
+* `on_take`/`on_metadata_inventory_take`: Taking items from the inventory
+* `on_put`/`on_metadata_inventory_put`: Putting items to the inventory
+
+#### Swapping
+
+When a player tries to put an item to a place where another item is, the items are *swapped*.
+This means that all callbacks will be called twice (once for each action).
+
`ItemStack`
-----------
stack).
* `set_metadata(metadata)`: (DEPRECATED) Returns true.
* `get_description()`: returns the description shown in inventory list tooltips.
+ * The engine uses this when showing item descriptions in tooltips.
+ * Fields for finding the description, in order:
+ * `description` in item metadata (See [Item Metadata].)
+ * `description` in item definition
+ * item name
+* `get_short_description()`: returns the short description or nil.
+ * Unlike the description, this does not include new lines.
+ * Fields for finding the short description, in order:
+ * `short_description` in item metadata (See [Item Metadata].)
+ * `short_description` in item definition
+ * first line of the description (From item meta or def, see `get_description()`.)
+ * Returns nil if none of the above are set
* `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.
* `get_pos()`: returns `{x=num, y=num, z=num}`
* `set_pos(pos)`: `pos`=`{x=num, y=num, z=num}`
+* `get_velocity()`: returns the velocity, a vector.
+* `add_velocity(vel)`
+ * `vel` is a vector, e.g. `{x=0.0, y=2.3, z=1.0}`
+ * In comparison to using get_velocity, adding the velocity and then using
+ set_velocity, add_velocity is supposed to avoid synchronization problems.
+ Additionally, players also do not support set_velocity.
+ * If a player:
+ * 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_velocity({x=0, y=6.5, z=0})` is equivalent to
+ pressing the jump key (assuming default settings)
* `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
* `time_from_last_punch` = time since last punch action of the puncher
* `direction`: can be `nil`
* `right_click(clicker)`; `clicker` is another `ObjectRef`
-* `get_hp()`: returns number of hitpoints (2 * number of hearts)
-* `set_hp(hp, reason)`: set number of hitpoints (2 * number of hearts).
+* `get_hp()`: returns number of health points
+* `set_hp(hp, reason)`: set number of health points
* 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
`frame_loop`.
* `set_animation_frame_speed(frame_speed)`
* `frame_speed`: number, default: `15.0`
-* `set_attach(parent, bone, position, rotation)`
- * `bone`: string
- * `position`: `{x=num, y=num, z=num}` (relative)
- * `rotation`: `{x=num, y=num, z=num}` = Rotation on each axis, in degrees
-* `get_attach()`: returns parent, bone, position, rotation or nil if it isn't
- attached.
+* `set_attach(parent[, bone, position, rotation, forced_visible])`
+ * `bone`: string. Default is `""`, the root bone
+ * `position`: `{x=num, y=num, z=num}`, relative, default `{x=0, y=0, z=0}`
+ * `rotation`: `{x=num, y=num, z=num}` = Rotation on each axis, in degrees.
+ Default `{x=0, y=0, z=0}`
+ * `forced_visible`: Boolean to control whether the attached entity
+ should appear in first person. Default `false`.
+ * This command may fail silently (do nothing) when it would result
+ in circular attachments.
+* `get_attach()`: returns parent, bone, position, rotation, forced_visible,
+ or nil if it isn't attached.
+* `get_children()`: returns a list of ObjectRefs that are attached to the
+ object.
* `set_detach()`
-* `set_bone_position(bone, position, rotation)`
- * `bone`: string
- * `position`: `{x=num, y=num, z=num}` (relative)
- * `rotation`: `{x=num, y=num, z=num}`
+* `set_bone_position([bone, position, rotation])`
+ * `bone`: string. Default is `""`, the root bone
+ * `position`: `{x=num, y=num, z=num}`, relative, `default {x=0, y=0, z=0}`
+ * `rotation`: `{x=num, y=num, z=num}`, default `{x=0, y=0, z=0}`
* `get_bone_position(bone)`: returns position and rotation of the bone
* `set_properties(object property table)`
* `get_properties()`: returns object property table
* `get_nametag_attributes()`
* returns a table with the attributes of the nametag of an object
* {
- color = {a=0..255, r=0..255, g=0..255, b=0..255},
text = "",
+ color = {a=0..255, r=0..255, g=0..255, b=0..255},
+ bgcolor = {a=0..255, r=0..255, g=0..255, b=0..255},
}
* `set_nametag_attributes(attributes)`
* sets the attributes of the nametag of an object
* `attributes`:
{
- color = ColorSpec,
text = "My Nametag",
+ color = ColorSpec,
+ -- ^ Text color
+ bgcolor = ColorSpec or false,
+ -- ^ Sets background color of nametag
+ -- `false` will cause the background to be set automatically based on user settings
+ -- Default: false
}
#### Lua entity only (no-op for other objects)
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)`
- * `vel` is a vector, e.g. `{x=0.0, y=2.3, z=1.0}`
- * In comparison to using get_velocity, adding the velocity and then using
- set_velocity, add_velocity is supposed to avoid synchronization problems.
-* `get_velocity()`: returns the velocity, a vector
* `set_acceleration(acc)`
* `acc` is a vector
* `get_acceleration()`: returns the acceleration, a vector
* `rot` is a vector (radians). X is pitch (elevation), Y is yaw (heading)
and Z is roll (bank).
* `get_rotation()`: returns the rotation, a vector (radians)
-* `set_yaw(radians)`: sets the yaw (heading).
+* `set_yaw(yaw)`: sets the yaw in radians (heading).
* `get_yaw()`: returns number in radians
* `set_texture_mod(mod)`
+ * Set a texture modifier to the base texture, for sprites and meshes.
+ * When calling `set_texture_mod` again, the previous one is discarded.
+ * `mod` the texture modifier. See [Texture modifiers].
* `get_texture_mod()` returns current texture modifier
-* `set_sprite(p, num_frames, framelength, select_horiz_by_yawpitch)`
- * Select sprite from spritesheet with optional animation and Dungeon Master
- style texture selection based on yaw relative to camera
- * `p`: {x=number, y=number}, the coordinate of the first frame
- (x: column, y: row), default: `{x=0, y=0}`
- * `num_frames`: number, default: `1`
- * `framelength`: number, default: `0.2`
- * `select_horiz_by_yawpitch`: boolean, this was once used for the Dungeon
- Master mob, default: `false`
+* `set_sprite(start_frame, num_frames, framelength, select_x_by_camera)`
+ * Specifies and starts a sprite animation
+ * Animations iterate along the frame `y` position.
+ * `start_frame`: {x=column number, y=row number}, the coordinate of the
+ first frame, default: `{x=0, y=0}`
+ * `num_frames`: Total frames in the texture, default: `1`
+ * `framelength`: Time per animated frame in seconds, default: `0.2`
+ * `select_x_by_camera`: Only for visual = `sprite`. Changes the frame `x`
+ position according to the view direction. default: `false`.
+ * First column: subject facing the camera
+ * Second column: subject looking to the left
+ * Third column: subject backing the camera
+ * Fourth column: subject looking to the right
+ * Fifth column: subject viewed from above
+ * Sixth column: subject viewed from below
* `get_entity_name()` (**Deprecated**: Will be removed in a future version)
* `get_luaentity()`
#### Player only (no-op for other objects)
* `get_player_name()`: returns `""` if is not a player
-* `get_player_velocity()`: returns `nil` if is not a player, otherwise a
+* `get_player_velocity()`: **DEPRECATED**, use get_velocity() instead.
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)
+* `add_player_velocity(vel)`: **DEPRECATED**, use add_velocity(vel) instead.
* `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
* Only affects formspecs shown after this is called.
* `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.
- * example: `{jump=false, right=true, left=false, LMB=false, RMB=false,
- sneak=true, aux1=false, down=false, up=false}`
+ * The table consists of fields with the following boolean values
+ representing the pressed keys: `up`, `down`, `left`, `right`, `jump`,
+ `aux1`, `sneak`, `dig`, `place`, `LMB`, `RMB`, and `zoom`.
+ * The fields `LMB` and `RMB` are equal to `dig` and `place` respectively,
+ and exist only to preserve backwards compatibility.
* `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
+ keys. Bits:
+ * 0 - up
+ * 1 - down
+ * 2 - left
+ * 3 - right
+ * 4 - jump
+ * 5 - aux1
+ * 6 - sneak
+ * 7 - dig
+ * 8 - place
+ * 9 - zoom
* `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(parameters)`
- * `parameters` is a table with the following optional fields:
+* `set_minimap_modes({mode, mode, ...}, selected_mode)`
+ * Overrides the available minimap modes (and toggle order), and changes the
+ selected mode.
+ * `mode` is a table consisting of up to four fields:
+ * `type`: Available type:
+ * `off`: Minimap off
+ * `surface`: Minimap in surface mode
+ * `radar`: Minimap in radar mode
+ * `texture`: Texture to be displayed instead of terrain map
+ (texture is centered around 0,0 and can be scaled).
+ Texture size is limited to 512 x 512 pixel.
+ * `label`: Optional label to display on minimap mode toggle
+ The translation must be handled within the mod.
+ * `size`: Sidelength or diameter, in number of nodes, of the terrain
+ displayed in minimap
+ * `texture`: Only for texture type, name of the texture to display
+ * `scale`: Only for texture type, scale of the texture map in nodes per
+ pixel (for example a `scale` of 2 means each pixel represents a 2x2
+ nodes square)
+ * `selected_mode` is the mode index to be selected after modes have been changed
+ (0 is the first mode).
+* `set_sky(sky_parameters)`
+ * The presence of the function `set_sun`, `set_moon` or `set_stars` indicates
+ whether `set_sky` accepts this format. Check the legacy format otherwise.
+ * `sky_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
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"`)
+* `set_sky(base_color, type, {texture names}, clouds)`
+ * Deprecated. Use `set_sky(sky_parameters)`
+ * `base_color`: 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 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:
+* `set_sun(sun_parameters)`:
+ * `sun_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 `""`
* `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:
+* `set_moon(moon_parameters)`:
+ * `moon_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 `""`
* `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:
+* `set_stars(star_parameters)`:
+ * `star_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
* `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:
+* `set_clouds(cloud_parameters)`: set cloud parameters
+ * `cloud_parameters` is a table with the following optional fields:
* `density`: from `0` (no clouds) to `1` (full clouds) (default `0.4`)
* `color`: basic cloud color with alpha channel, ColorSpec
(default `#fff0f0e5`).
amount.
* `nil`: Disables override, defaulting to sunlight based on day-night cycle
* `get_day_night_ratio()`: returns the ratio or nil if it isn't overridden
-* `set_local_animation(stand/idle, walk, dig, walk+dig, frame_speed=frame_speed)`:
- set animation for player model in third person view
-
- set_local_animation({x=0, y=79}, -- stand/idle animation key frames
- {x=168, y=187}, -- walk animation key frames
- {x=189, y=198}, -- dig animation key frames
- {x=200, y=219}, -- walk+dig animation key frames
- frame_speed=30) -- animation frame speed
-* `get_local_animation()`: returns stand, walk, dig, dig+walk tables and
+* `set_local_animation(idle, walk, dig, walk_while_dig, frame_speed)`:
+ set animation for player model in third person view.
+ * Every animation equals to a `{x=starting frame, y=ending frame}` table.
+ * `frame_speed` sets the animations frame speed. Default is 30.
+* `get_local_animation()`: returns idle, walk, dig, walk_while_dig tables and
`frame_speed`.
-* `set_eye_offset({x=0,y=0,z=0},{x=0,y=0,z=0})`: defines offset value for
- camera per player.
+* `set_eye_offset([firstperson, thirdperson])`: defines offset vectors for
+ camera per player. An argument defaults to `{x=0, y=0, z=0}` if unspecified.
* in first person view
* in third person view (max. values `{x=-10/10,y=-10,15,z=-5/5}`)
-* `get_eye_offset()`: returns `offset_first` and `offset_third`
+* `get_eye_offset()`: returns first and third person offsets.
* `send_mapblock(blockpos)`:
* Sends a server-side loaded mapblock to the player.
* Returns `false` if failed.
-- in mods.
nametag = "",
- -- By default empty, for players their name is shown if empty
+ -- The name to display on the head of the object. By default empty.
+ -- If the object is a player, a nil or empty nametag is replaced by the player's name.
+ -- For all other objects, a nil or empty string removes the nametag.
+ -- To hide a nametag, set its color alpha to zero. That will disable it entirely.
nametag_color = <ColorSpec>,
- -- Sets color of nametag
+ -- Sets text color of nametag
+
+ nametag_bgcolor = <ColorSpec>,
+ -- Sets background color of nametag
+ -- `false` will cause the background to be set automatically based on user settings.
+ -- Default: false
infotext = "",
-- By default empty, text to be shown when pointed at object
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
+
+ show_on_minimap = false,
+ -- Defaults to true for players, false for other entities.
+ -- If set to true the entity will show as a marker on the minimap.
}
Entity definition
chance = 1,
-- Chance of triggering `action` per-node per-interval is 1.0 / this
-- value
+
+ min_y = -32768,
+ max_y = 32767,
+ -- min and max height levels where ABM will be processed
+ -- can be used to reduce CPU usage
catch_up = true,
-- If true, catch-up behaviour is enabled: The `chance` value is
* `"image.png"`
* `{name="image.png", animation={Tile Animation definition}}`
-* `{name="image.png", backface_culling=bool, tileable_vertical=bool,
- tileable_horizontal=bool, align_style="node"/"world"/"user", scale=int}`
+* `{name="image.png", backface_culling=bool, align_style="node"/"world"/"user", scale=int}`
* backface culling enabled by default for most nodes
- * tileable flags are info for shaders, how they should treat texture
- when displacement mapping is used.
- Directions are from the point of view of the tile texture,
- not the node it's on.
* align style determines whether the texture will be rotated with the node
or kept aligned with its surroundings. "user" means that client
setting will be used, similar to `glasslike_framed_optional`.
{
description = "Steel Axe",
+ -- Can contain new lines. "\n" has to be used as new line character.
+ -- See also: `get_description` in [`ItemStack`]
+
+ short_description = "Steel Axe",
+ -- Must not contain new lines.
+ -- Defaults to nil.
+ -- Use an [`ItemStack`] to get the short description, eg:
+ -- ItemStack(itemname):get_short_description()
groups = {},
-- key = name, value = rating; rating = 1..3.
liquids_pointable = false,
+ light_source = 0,
+ -- When used for nodes: Defines amount of light emitted by node.
+ -- Otherwise: Defines texture glow when viewed as a dropped item
+ -- To set the maximum (14), use the value 'minetest.LIGHT_MAX'.
+ -- A value outside the range 0 to minetest.LIGHT_MAX causes undefined
+ -- behavior.
+
-- See "Tools" section for an example including explanation
tool_capabilities = {
full_punch_interval = 1.0,
-- If the node has a palette, then this setting only has an effect in
-- the inventory and on the wield item.
- use_texture_alpha = false,
- -- Use texture's alpha channel
+ use_texture_alpha = ...,
+ -- Specifies how the texture's alpha channel will be used for rendering.
+ -- possible values:
+ -- * "opaque": Node is rendered opaque regardless of alpha channel
+ -- * "clip": A given pixel is either fully see-through or opaque
+ -- depending on the alpha channel being below/above 50% in value
+ -- * "blend": The alpha channel specifies how transparent a given pixel
+ -- of the rendered node is
+ -- The default is "opaque" for drawtypes normal, liquid and flowingliquid;
+ -- "clip" otherwise.
+ -- If set to a boolean value (deprecated): true either sets it to blend
+ -- or clip, false sets it to clip or opaque mode depending on the drawtype.
palette = "palette.png",
-- The node's `param2` is used to select a pixel from the image.
-- If true, liquids flow into and replace this node.
-- Warning: making a liquid node 'floodable' will cause problems.
- liquidtype = "none", -- "none" / "source" / "flowing"
+ liquidtype = "none", -- specifies liquid physics
+ -- * "none": no liquid physics
+ -- * "source": spawns flowing liquid nodes at all 4 sides and below;
+ -- recommended drawtype: "liquid".
+ -- * "flowing": spawned from source, spawns more flowing liquid nodes
+ -- around it until `liquid_range` is reached;
+ -- will drain out without a source;
+ -- recommended drawtype: "flowingliquid".
+ -- If it's "source" or "flowing" and `liquid_range > 0`, then
+ -- both `liquid_alternative_*` fields must be specified
liquid_alternative_flowing = "", -- Flowing version of source liquid
leveled_max = 127,
-- Maximum value for `leveled` (0-127), enforced in
-- `minetest.set_node_level` and `minetest.add_node_level`.
+ -- Values above 124 might causes collision detection issues.
- liquid_range = 8, -- Number of flowing nodes around source (max. 8)
+ liquid_range = 8,
+ -- Maximum distance that flowing liquid nodes can spread around
+ -- source on flat land;
+ -- maximum = 8; set to 0 to disable liquid flow
drowning = 0,
-- Player will take this amount of damage if no bubbles are left
- light_source = 0,
- -- Amount of light emitted by node.
- -- To set the maximum (14), use the value 'minetest.LIGHT_MAX'.
- -- A value outside the range 0 to minetest.LIGHT_MAX causes undefined
- -- behavior.
-
damage_per_second = 0,
-- If player is inside node, this damage is caused
type = "fixed",
fixed = {
{-2 / 16, -0.5, -2 / 16, 2 / 16, 3 / 16, 2 / 16},
+ -- Node box format: see [Node boxes]
},
},
-- Custom selection box definition. Multiple boxes can be defined.
type = "fixed",
fixed = {
{-2 / 16, -0.5, -2 / 16, 2 / 16, 3 / 16, 2 / 16},
+ -- Node box format: see [Node boxes]
},
},
-- Custom collision box definition. Multiple boxes can be defined.
-- If "nodebox" drawtype is used and collision_box is nil, then node_box
-- definition is used for the collision box.
- -- Both of the boxes above are defined as:
- -- {xmin, ymin, zmin, xmax, ymax, zmax} in nodes from node center.
-- Support maps made in and before January 2012
legacy_facedir_simple = false,
-- Node was placed. Also played after falling
place_failed = <SimpleSoundSpec>,
- -- When node placement failed
+ -- When node placement failed.
+ -- Note: This happens if the _built-in_ node placement failed.
+ -- This sound will still be played if the node is placed in the
+ -- `on_place` callback manually.
fall = <SimpleSoundSpec>,
- -- When node starts to fall
+ -- When node starts to fall or is detached
},
drop = "",
on_dig = function(pos, node, digger),
-- default: minetest.node_dig
-- By default checks privileges, wears out tool and removes node.
+ -- return true if the node was dug successfully, false otherwise.
+ -- Deprecated: returning nil is the same as returning true.
on_timer = function(pos, elapsed),
-- default: nil
-- intensity: 1.0 = mid range of regular TNT.
-- If defined, called when an explosion touches the node, instead of
-- removing the node.
+
+ mod_origin = "modname",
+ -- stores which mod actually registered a node
+ -- if it can not find a source, returns "??"
+ -- useful for getting what mod truly registered something
+ -- example: if a node is registered as ":othermodname:nodename",
+ -- nodename will show "othermodname", but mod_orgin will say "modname"
}
Crafting recipes
func = function(name, param),
-- Called when command is run. Returns boolean success and text output.
+ -- Special case: The help message is shown to the player if `func`
+ -- returns false without a text output.
}
Note that in params, use of symbols is as follows:
{
hud_elem_type = "image", -- See HUD element types
- -- Type of element, can be "image", "text", "statbar", or "inventory"
+ -- Type of element, can be "image", "text", "statbar", "inventory",
+ -- "compass" or "minimap"
position = {x=0.5, y=0.5},
-- Left corner position of element
url = "http://example.org",
timeout = 10,
- -- Timeout for connection in seconds. Default is 3 seconds.
+ -- Timeout for request to be completed in seconds. Default depends on engine settings.
- post_data = "Raw POST request data string" OR {field1 = "data1", field2 = "data2"},
- -- Optional, if specified a POST request with post_data is performed.
+ method = "GET", "POST", "PUT" or "DELETE"
+ -- The http method to use. Defaults to "GET".
+
+ data = "Raw request data string" OR {field1 = "data1", field2 = "data2"},
+ -- Data for the POST, PUT or DELETE request.
-- Accepts both a string and a table. If a table is specified, encodes
-- table as x-www-form-urlencoded key-value pairs.
- -- If post_data is not specified, a GET request is performed instead.
user_agent = "ExampleUserAgent",
-- Optional, if specified replaces the default minetest user agent with
multipart = boolean
-- Optional, if true performs a multipart HTTP request.
-- Default is false.
+ -- Post only, data must be array
+
+ post_data = "Raw POST request data string" OR {field1 = "data1", field2 = "data2"},
+ -- Deprecated, use `data` instead. Forces `method = "POST"`.
}
`HTTPRequestResult` definition
projects / minetest.git / blobdiff