-Minetest Lua Client Modding API Reference 5.4.0
+Minetest Lua Client Modding API Reference 5.7.0
================================================
* More information at <http://www.minetest.net/>
* Developer Wiki: <http://dev.minetest.net/>
#### `bgcolor[<color>;<fullscreen>]`
* Sets background color of formspec as `ColorString`
-* If `true`, the background color is drawn fullscreen (does not effect the size of the formspec)
+* If `true`, the background color is drawn fullscreen (does not affect the size of the formspec)
#### `background[<X>,<Y>;<W>,<H>;<texture name>]`
* Use a background. Inventory rectangles are not drawn then.
of this field.
* `x` and `y` position the field relative to the top left of the menu
* `w` and `h` are the size of the field
-* Fields are a set height, but will be vertically centred on `h`
+* Fields are a set height, but will be vertically centered on `h`
* Position and size units are inventory slots
* `name` is the name of the field as returned in fields to `on_receive_fields`
* `label`, if not blank, will be text printed on the top left above the field
of this field.
* `x` and `y` position the field relative to the top left of the menu
* `w` and `h` are the size of the field
-* Fields are a set height, but will be vertically centred on `h`
+* Fields are a set height, but will be vertically centered on `h`
* Position and size units are inventory slots
* `name` is the name of the field as returned in fields to `on_receive_fields`
* `label`, if not blank, will be text printed on the top left above the field
* Clickable button. When clicked, fields will be sent.
* `x`, `y` and `name` work as per field
* `w` and `h` are the size of the button
-* Fixed button height. It will be vertically centred on `h`
+* Fixed button height. It will be vertically centered on `h`
* `label` is the text on the button
* Position and size units are inventory slots
* `color` column options:
* `span=<value>`: number of following columns to affect (default: infinite)
-**Note**: do _not_ use a element name starting with `key_`; those names are reserved to
+**Note**: do _not_ use an element name starting with `key_`; those names are reserved to
pass key press events to formspec!
Spatial Vectors
* `vector.floor(v)`: returns a vector, each dimension rounded down
* `vector.round(v)`: returns a vector, each dimension rounded to nearest int
* `vector.apply(v, func)`: returns a vector
+* `vector.combine(v, w, func)`: returns a vector
* `vector.equals(v1, v2)`: returns a boolean
For the following functions `x` can be either a vector or a number:
* `minetest.is_yes(arg)`
* returns whether `arg` can be interpreted as yes
* `minetest.is_nan(arg)`
- * returns true true when the passed number represents NaN.
+ * returns true when the passed number represents NaN.
* `table.copy(table)`: returns a table
* returns a deep copy of `table`
* `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
* `minetest.get_csm_restrictions()`: returns a table of `Flags` indicating the
restrictions applied to the current mod.
* If a flag in this table is set to true, the feature is RESTRICTED.
* Called always when a client receive a message
* Return `true` to mark the message as handled, which means that it will not be shown to chat
* `minetest.register_on_sending_chat_message(function(message))`
- * Called always when a client send a message from chat
+ * Called always when a client sends a message from chat
* Return `true` to mark the message as handled, which means that it will not be sent to server
* `minetest.register_chatcommand(cmd, chatcommand definition)`
* Adds definition to minetest.registered_chatcommands
* Unregisters a chatcommands registered with register_chatcommand.
* `minetest.register_on_chatcommand(function(command, params))`
* Called always when a chatcommand is triggered, before `minetest.registered_chatcommands`
- is checked to see if that the command exists, but after the input is parsed.
+ 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_death(function())`
* Unserializable things like functions and userdata are saved as null.
* **Warning**: JSON is more strict than the Lua table format.
1. You can only use strings and positive integers of at least one as keys.
- 2. You can not mix string and integer keys.
+ 2. You cannot mix string and integer keys.
This is due to the fact that JSON has two distinct array and object values.
* Example: `write_json({10, {a = false}})`, returns `"[10, {\"a\": false}]"`
* `minetest.serialize(table)`: returns a string
* Compress a string of data.
* `method` is a string identifying the compression method to be used.
* Supported compression methods:
- * Deflate (zlib): `"deflate"`
- * `...` indicates method-specific arguments. Currently defined arguments are:
- * Deflate: `level` - Compression level, `0`-`9` or `nil`.
+ * Deflate (zlib): `"deflate"`
+ * Zstandard: `"zstd"`
+ * `...` indicates method-specific arguments. Currently defined arguments
+ are:
+ * Deflate: `level` - Compression level, `0`-`9` or `nil`.
+ * Zstandard: `level` - Compression level. Integer or `nil`. Default `3`.
+ Note any supported Zstandard compression level could be used here,
+ but these are subject to change between Zstandard versions.
* `minetest.decompress(compressed_data, method, ...)`: returns data
- * Decompress a string of data (using ZLib).
- * See documentation on `minetest.compress()` for supported compression methods.
- * currently supported.
- * `...` indicates method-specific arguments. Currently, no methods use this.
+ * Decompress a string of data using the algorithm specified by `method`.
+ * See documentation on `minetest.compress()` for supported compression
+ methods.
+ * `...` indicates method-specific arguments. Currently, no methods use this
* `minetest.rgba(red, green, blue[, alpha])`: returns a string
- * Each argument is a 8 Bit unsigned integer
+ * Each argument is an 8 Bit unsigned integer
* Returns the ColorString from rgb or rgba values
* 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 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.gettext(string)` : returns string
* look up the translation of a string in the gettext message catalog
* `minetest.display_chat_message(message)` returns true on success
* Shows a chat message to the current player.
+Setting-related
+---------------
+
+* `minetest.settings`: Settings object containing all of the settings from the
+ main config file (`minetest.conf`). Check lua_api.txt for class reference.
+* `minetest.setting_get_pos(name)`: Loads a setting from the main settings and
+ parses it as a position (in the format `(1,2,3)`). Returns a position or nil.
+
Class reference
---------------
* returns true if player is in a liquid (This oscillates so that the player jumps a bit above the surface)
* `is_in_liquid_stable()`
* returns true if player is in a stable liquid (This is more stable and defines the maximum speed of the player)
-* `get_liquid_viscosity()`
- * returns liquid viscosity (Gets the viscosity of liquid to calculate friction)
+* `get_move_resistance()`
+ * returns move resistance of current node, the higher the slower the player moves
* `is_climbing()`
* returns true if player is climbing
* `swimming_vertical()`
paramtype = string, -- Paramtype of the node
paramtype2 = string, -- ParamType2 of the node
drawtype = string, -- Drawtype of the node
- mesh = <string>, -- Mesh name if existant
+ mesh = <string>, -- Mesh name if existent
minimap_color = <Color>, -- Color of node on minimap *May not exist*
visual_scale = number, -- Visual scale of node
alpha = number, -- Alpha of the node. Only used for liquids
liquid_type = <string>, -- A string containing "none", "flowing", or "source" *May not exist*
liquid_alternative_flowing = <string>, -- Alternative node for liquid *May not exist*
liquid_alternative_source = <string>, -- Alternative node for liquid *May not exist*
- liquid_viscosity = <number>, -- How fast the liquid flows *May not exist*
+ liquid_viscosity = <number>, -- How slow the liquid flows *May not exist*
liquid_renewable = <boolean>, -- Whether the liquid makes an infinite source *May not exist*
liquid_range = <number>, -- How far the liquid flows *May not exist*
drowning = bool, -- Whether the player will drown in the node
},
legacy_facedir_simple = bool, -- Whether to use old facedir
legacy_wallmounted = bool -- Whether to use old wallmounted
+ move_resistance = <number>, -- How slow players can move through the node *May not exist*
}
```
-- ^ See "HUD Element Types"
size = { x=100, y=100 }, -- default {x=0, y=0}
-- ^ Size of element in pixels
+ style = 0,
+ -- ^ For "text" elements sets font style: bitfield with 1 = bold, 2 = italic, 4 = monospace
}
```
Escape sequences
----------------
-Most text can contain escape sequences, that can for example color the text.
+Most text can contain escape sequences that can for example color the text.
There are a few exceptions: tab headers, dropdowns and vertical labels can't.
The following functions provide escape sequences:
* `minetest.get_color_escape_sequence(color)`:
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`).
`Color`
-------------