minetest
/
minetest
mirror of https://github.com/minetest/minetest.git
1
0
Fork 0
Code Issues Releases Wiki Activity

Lua_api.txt: Split long lines part 2

This commit is contained in:
paramat 2018-03-10 04:26:38 +00:00 committed by paramat
parent 644d0ab2bb
commit 5a1884c21d
1 changed files with 219 additions and 150 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

369
doc/lua_api.txt
View File

@ -1353,8 +1353,8 @@ HUD element types
----------------- -----------------
The position field is used for all element types. The position field is used for all element types.
To account for differing resolutions, the position coordinates are the percentage To account for differing resolutions, the position coordinates are the
of the screen, ranging in value from `0` to `1`. 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 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 HUD element represents. The direction field is the direction in which something
@ -1363,20 +1363,22 @@ is drawn.
`0` draws from left to right, `1` draws from right to left, `2` draws from `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. top to bottom, and `3` draws from bottom to top.
The `alignment` field specifies how the item will be aligned. It ranges from `-1` to `1`, The `alignment` field specifies how the item will be aligned. It ranges from
with `0` being the center, `-1` is moved to the left/up, and `1` is to the right/down. `-1` to `1`, with `0` being the center. `-1` is moved to the left/up, and `1`
Fractional values can be used. is to the right/down. Fractional values can be used.
The `offset` field specifies a pixel offset from the position. Contrary to position, The `offset` field specifies a pixel offset from the position. Contrary to
the offset is not scaled to screen size. This allows for some precisely-positioned position, the offset is not scaled to screen size. This allows for some
items in the HUD. precisely positioned items in the HUD.
**Note**: `offset` _will_ adapt to screen DPI as well as user defined scaling factor! **Note**: `offset` _will_ adapt to screen DPI as well as user defined scaling
factor!
Below are the specific uses for fields in each type; fields not listed for that type are ignored. Below are the specific uses for fields in each type; fields not listed for that
type are ignored.
**Note**: Future revisions to the HUD API may be incompatible; the HUD API is still **Note**: Future revisions to the HUD API may be incompatible; the HUD API is
in the experimental stages. still in the experimental stages.
### `image` ### `image`
Displays an image on the HUD. Displays an image on the HUD.
@ -1395,8 +1397,8 @@ Displays text on the HUD.
* `scale`: Defines the bounding rectangle of the text. * `scale`: Defines the bounding rectangle of the text.
A value such as `{x=100, y=100}` should work. A value such as `{x=100, y=100}` should work.
* `text`: The text to be displayed in the HUD element. * `text`: The text to be displayed in the HUD element.
* `number`: An integer containing the RGB value of the color used to draw the text. * `number`: An integer containing the RGB value of the color used to draw the
Specify `0xFFFFFF` for white text, `0xFF0000` for red, and so on. text. Specify `0xFFFFFF` for white text, `0xFF0000` for red, and so on.
* `alignment`: The alignment of the text. * `alignment`: The alignment of the text.
* `offset`: offset in pixels from position. * `offset`: offset in pixels from position.
@ -1408,7 +1410,8 @@ Displays a horizontal bar made up of half-images.
If odd, will end with a vertically center-split texture. If odd, will end with a vertically center-split texture.
* `direction` * `direction`
* `offset`: offset in pixels from position. * `offset`: offset in pixels from position.
* `size`: If used, will force full-image size to this value (override texture pack image size) * `size`: If used, will force full-image size to this value (override texture
pack image size)
### `inventory` ### `inventory`
* `text`: The name of the inventory list to be displayed. * `text`: The name of the inventory list to be displayed.
@ -1422,7 +1425,8 @@ Displays distance to selected world position.
* `name`: The name of the waypoint. * `name`: The name of the waypoint.
* `text`: Distance suffix. Can be blank. * `text`: Distance suffix. Can be blank.
* `number:` An integer containing the RGB value of the color used to draw the text. * `number:` An integer containing the RGB value of the color used to draw the
text.
* `world_pos`: World position of the waypoint. * `world_pos`: World position of the waypoint.
Representations of simple things Representations of simple things
@ -1441,8 +1445,8 @@ For helper functions see "Vector helpers".
Flag Specifier Format Flag Specifier Format
--------------------- ---------------------
Flags using the standardized flag specifier format can be specified in either of Flags using the standardized flag specifier format can be specified in either
two ways, by string or table. of two ways, by string or table.
The string format is a comma-delimited set of flag names; whitespace and The string format is a comma-delimited set of flag names; whitespace and
unrecognized flag fields are ignored. Specifying a flag in the string sets the unrecognized flag fields are ignored. Specifying a flag in the string sets the
@ -1791,7 +1795,7 @@ a non-tool item, so that it can do something else than take damage.
On the Lua side, every punch calls: On the Lua side, every punch calls:
entity:on_punch(puncher, time_from_last_punch, tool_capabilities, direction, damage) entity:on_punch(puncher, time_from_last_punch, tool_capabilities, direction, damage)
This should never be called directly, because damage is usually not handled by This should never be called directly, because damage is usually not handled by
the entity itself. the entity itself.
@ -1808,12 +1812,12 @@ Return value of this function will determine if damage is done by this function
To punch an entity/object in Lua, call: To punch an entity/object in Lua, call:
object:punch(puncher, time_from_last_punch, tool_capabilities, direction) object:punch(puncher, time_from_last_punch, tool_capabilities, direction)
* Return value is tool wear. * Return value is tool wear.
* Parameters are equal to the above callback. * Parameters are equal to the above callback.
* If `direction` equals `nil` and `puncher` does not equal `nil`, * If `direction` equals `nil` and `puncher` does not equal `nil`, `direction`
`direction` will be automatically filled in based on the location of `puncher`. will be automatically filled in based on the location of `puncher`.
Node Metadata Node Metadata
------------- -------------
@ -1867,7 +1871,8 @@ Item metadata only contains a key-value store.
Some of the values in the key-value store are handled specially: 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. Defaults to
`idef.description`.
* `color`: A `ColorString`, which sets the stack's color. * `color`: A `ColorString`, which sets the stack's color.
* `palette_index`: If the item has a palette, this is used to get the * `palette_index`: If the item has a palette, this is used to get the
current color from the palette. current color from the palette.
@ -1920,7 +1925,8 @@ examples.
#### `position[<X>,<Y>]` #### `position[<X>,<Y>]`
* Must be used after `size` element. * Must be used after `size` element.
* Defines the position on the game window of the formspec's `anchor` point. * Defines the position on the game window of the formspec's `anchor` point.
* For X and Y, 0.0 and 1.0 represent opposite edges of the game window, for example: * For X and Y, 0.0 and 1.0 represent opposite edges of the game window,
for example:
* [0.0, 0.0] sets the position to the top left corner of the game window. * [0.0, 0.0] sets the position to the top left corner of the game window.
* [1.0, 1.0] sets the position to the bottom right of the game window. * [1.0, 1.0] sets the position to the bottom right of the game window.
* Defaults to the center of the game window [0.5, 0.5]. * Defaults to the center of the game window [0.5, 0.5].
@ -1928,7 +1934,8 @@ examples.
#### `anchor[<X>,<Y>]` #### `anchor[<X>,<Y>]`
* Must be used after both `size` and `position` (if present) elements. * Must be used after both `size` and `position` (if present) elements.
* Defines the location of the anchor point within the formspec. * Defines the location of the anchor point within the formspec.
* For X and Y, 0.0 and 1.0 represent opposite edges of the formspec, for example: * For X and Y, 0.0 and 1.0 represent opposite edges of the formspec,
for example:
* [0.0, 1.0] sets the anchor to the bottom left corner of the formspec. * [0.0, 1.0] sets the anchor to the bottom left corner of the formspec.
* [1.0, 0.0] sets the anchor to the top right of the formspec. * [1.0, 0.0] sets the anchor to the top right of the formspec.
* Defaults to the center of the formspec [0.5, 0.5]. * Defaults to the center of the formspec [0.5, 0.5].
@ -1937,13 +1944,15 @@ examples.
extending off the game window due to particular game window sizes. extending off the game window due to particular game window sizes.
#### `container[<X>,<Y>]` #### `container[<X>,<Y>]`
* Start of a container block, moves all physical elements in the container by (X, Y) * Start of a container block, moves all physical elements in the container by
(X, Y).
* Must have matching `container_end` * Must have matching `container_end`
* Containers can be nested, in which case the offsets are added * Containers can be nested, in which case the offsets are added
(child containers are relative to parent containers) (child containers are relative to parent containers)
#### `container_end[]` #### `container_end[]`
* End of a container, following elements are no longer relative to this container * End of a container, following elements are no longer relative to this
container.
#### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]` #### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]`
* Show an inventory list * Show an inventory list
@ -1993,7 +2002,8 @@ examples.
#### `bgcolor[<color>;<fullscreen>]` #### `bgcolor[<color>;<fullscreen>]`
* Sets background color of formspec as `ColorString` * 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 effect the size
of the formspec).
#### `background[<X>,<Y>;<W>,<H>;<texture name>]` #### `background[<X>,<Y>;<W>,<H>;<texture name>]`
* Use a background. Inventory rectangles are not drawn then. * Use a background. Inventory rectangles are not drawn then.
@ -2011,8 +2021,8 @@ examples.
#### `pwdfield[<X>,<Y>;<W>,<H>;<name>;<label>]` #### `pwdfield[<X>,<Y>;<W>,<H>;<name>;<label>]`
* Textual password style field; will be sent to server when a button is clicked * Textual password style field; will be sent to server when a button is clicked
* When enter is pressed in field, fields.key_enter_field will be sent with the name * When enter is pressed in field, fields.key_enter_field will be sent with the
of this field. name of this field.
* `x` and `y` position the field relative to the top left of the menu * `x` and `y` position the field relative to the top left of the menu
* `w` and `h` are the size of the field * `w` and `h` are the size of the field
* Fields are a set height, but will be vertically centred on `h` * Fields are a set height, but will be vertically centred on `h`
@ -2023,8 +2033,8 @@ examples.
#### `field[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]` #### `field[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`
* Textual field; will be sent to server when a button is clicked * Textual field; will be sent to server when a button is clicked
* When enter is pressed in field, `fields.key_enter_field` will be sent with the name * When enter is pressed in field, `fields.key_enter_field` will be sent with
of this field. the name of this field.
* `x` and `y` position the field relative to the top left of the menu * `x` and `y` position the field relative to the top left of the menu
* `w` and `h` are the size of the field * `w` and `h` are the size of the field
* Fields are a set height, but will be vertically centred on `h` * Fields are a set height, but will be vertically centred on `h`
@ -2039,8 +2049,8 @@ examples.
#### `field[<name>;<label>;<default>]` #### `field[<name>;<label>;<default>]`
* As above, but without position/size units * As above, but without position/size units
* When enter is pressed in field, `fields.key_enter_field` will be sent with the name * When enter is pressed in field, `fields.key_enter_field` will be sent with
of this field. the name of this field.
* Special field for creating simple forms, such as sign text input * Special field for creating simple forms, such as sign text input
* Must be used without a `size[]` element * Must be used without a `size[]` element
* A "Proceed" button will be added automatically * A "Proceed" button will be added automatically
@ -2048,13 +2058,14 @@ examples.
#### `field_close_on_enter[<name>;<close_on_enter>]` #### `field_close_on_enter[<name>;<close_on_enter>]`
* <name> is the name of the field * <name> is the name of the field
* if <close_on_enter> is false, pressing enter in the field will submit the form but not close it * if <close_on_enter> is false, pressing enter in the field will submit the
form but not close it.
* defaults to true when not specified (ie: no tag for a field) * defaults to true when not specified (ie: no tag for a field)
#### `textarea[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]` #### `textarea[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`
* Same as fields above, but with multi-line input * Same as fields above, but with multi-line input
* if the text overflows a vertical scrollbar is added * if the text overflows a vertical scrollbar is added
* if the name is empty the textarea is readonly. The label is not displayed then * if the name is empty the textarea is readonly, the label is not displayed.
#### `label[<X>,<Y>;<label>]` #### `label[<X>,<Y>;<label>]`
* `x` and `y` work as per field * `x` and `y` work as per field
@ -2084,7 +2095,8 @@ examples.
* `x`, `y`, `w`, `h`, and `name` work as per button * `x`, `y`, `w`, `h`, and `name` work as per button
* `texture name` is the filename of an image * `texture name` is the filename of an image
* Position and size units are inventory slots * Position and size units are inventory slots
* `noclip=true` means the image button doesn't need to be within specified formsize * `noclip=true` means the image button doesn't need to be within specified
formsize.
* `drawborder`: draw button border or not * `drawborder`: draw button border or not
* `pressed texture name` is the filename of an image on pressed state * `pressed texture name` is the filename of an image on pressed state
@ -2105,20 +2117,24 @@ examples.
* Scrollable item list showing arbitrary text elements * Scrollable item list showing arbitrary text elements
* `x` and `y` position the itemlist relative to the top left of the menu * `x` and `y` position the itemlist relative to the top left of the menu
* `w` and `h` are the size of the itemlist * `w` and `h` are the size of the itemlist
* `name` fieldname sent to server on doubleclick value is current selected element * `name` fieldname sent to server on doubleclick value is current selected
* `listelements` can be prepended by #color in hexadecimal format RRGGBB (only), element.
* `listelements` can be prepended by #color in hexadecimal format RRGGBB
(only).
* if you want a listelement to start with "#" write "##". * if you want a listelement to start with "#" write "##".
#### `textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>;<selected idx>;<transparent>]` #### `textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>;<selected idx>;<transparent>]`
* Scrollable itemlist showing arbitrary text elements * Scrollable itemlist showing arbitrary text elements
* `x` and `y` position the item list relative to the top left of the menu * `x` and `y` position the item list relative to the top left of the menu
* `w` and `h` are the size of the item list * `w` and `h` are the size of the item list
* `name` fieldname sent to server on doubleclick value is current selected element * `name` fieldname sent to server on doubleclick value is current selected
element.
* `listelements` can be prepended by #RRGGBB (only) in hexadecimal format * `listelements` can be prepended by #RRGGBB (only) in hexadecimal format
* if you want a listelement to start with "#" write "##" * if you want a listelement to start with "#" write "##"
* Index to be selected within textlist * Index to be selected within textlist
* `true`/`false`: draw transparent background * `true`/`false`: draw transparent background
* See also `minetest.explode_textlist_event` (main menu: `engine.explode_textlist_event`) * See also `minetest.explode_textlist_event`
(main menu: `engine.explode_textlist_event`).
#### `tabheader[<X>,<Y>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]` #### `tabheader[<X>,<Y>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]`
* Show a tab**header** at specific position (ignores formsize) * Show a tab**header** at specific position (ignores formsize)
@ -2163,7 +2179,8 @@ examples.
* `orientation`: `vertical`/`horizontal` * `orientation`: `vertical`/`horizontal`
* Fieldname data is transferred to Lua * Fieldname data is transferred to Lua
* Value this trackbar is set to (`0`-`1000`) * Value this trackbar is set to (`0`-`1000`)
* See also `minetest.explode_scrollbar_event` (main menu: `engine.explode_scrollbar_event`) * See also `minetest.explode_scrollbar_event`
(main menu: `engine.explode_scrollbar_event`).
#### `table[<X>,<Y>;<W>,<H>;<name>;<cell 1>,<cell 2>,...,<cell n>;<selected idx>]` #### `table[<X>,<Y>;<W>,<H>;<name>;<cell 1>,<cell 2>,...,<cell n>;<selected idx>]`
* Show scrollable table using options defined by the previous `tableoptions[]` * Show scrollable table using options defined by the previous `tableoptions[]`
@ -2173,7 +2190,8 @@ examples.
* `name`: fieldname sent to server on row select or doubleclick * `name`: fieldname sent to server on row select or doubleclick
* `cell 1`...`cell n`: cell contents given in row-major order * `cell 1`...`cell n`: cell contents given in row-major order
* `selected idx`: index of row to be selected within table (first row = `1`) * `selected idx`: index of row to be selected within table (first row = `1`)
* See also `minetest.explode_table_event` (main menu: `engine.explode_table_event`) * See also `minetest.explode_table_event`
(main menu: `engine.explode_table_event`).
#### `tableoptions[<opt 1>;<opt 2>;...]` #### `tableoptions[<opt 1>;<opt 2>;...]`
* Sets options for `table[]` * Sets options for `table[]`
@ -2195,10 +2213,14 @@ examples.
* Sets columns for `table[]` * Sets columns for `table[]`
* Types: `text`, `image`, `color`, `indent`, `tree` * Types: `text`, `image`, `color`, `indent`, `tree`
* `text`: show cell contents as text * `text`: show cell contents as text
* `image`: cell contents are an image index, use column options to define images * `image`: cell contents are an image index, use column options to define
* `color`: cell contents are a ColorString and define color of following cell images.
* `indent`: cell contents are a number and define indentation of following cell * `color`: cell contents are a ColorString and define color of following
* `tree`: same as indent, but user can open and close subtrees (treeview-like) cell.
* `indent`: cell contents are a number and define indentation of following
cell.
* `tree`: same as indent, but user can open and close subtrees
(treeview-like).
* Column options: * Column options:
* `align=<value>` * `align=<value>`
* for `text` and `image`: content alignment within cells. * for `text` and `image`: content alignment within cells.
@ -2216,10 +2238,11 @@ examples.
* and so on; defined indices need not be contiguous empty or * and so on; defined indices need not be contiguous empty or
non-numeric cells are treated as `0`. non-numeric cells are treated as `0`.
* `color` column options: * `color` column options:
* `span=<value>`: number of following columns to affect (default: infinite) * `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 a element name starting with `key_`; those names are
pass key press events to formspec! reserved to pass key press events to formspec!
Inventory locations Inventory locations
------------------- -------------------
@ -2248,9 +2271,9 @@ Player Inventory lists
Named colors are also supported and are equivalent to Named colors are also supported and are equivalent to
[CSS Color Module Level 4](http://dev.w3.org/csswg/css-color/#named-colors). [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 To specify the value of the alpha channel, append `#AA` to the end of the color
(e.g. `colorname#08`). For named colors the hexadecimal string representing the alpha name (e.g. `colorname#08`). For named colors the hexadecimal string
value must (always) be two hexadecimal digits. representing the alpha value must (always) be two hexadecimal digits.
`ColorSpec` `ColorSpec`
----------- -----------
@ -2289,7 +2312,8 @@ The following functions provide escape sequences:
Spatial Vectors Spatial Vectors
--------------- ---------------
For the following functions, `v`, `v1`, `v2` are vectors, `p1`, `p2` are positions: For the following functions, `v`, `v1`, `v2` are vectors,
`p1`, `p2` are positions:
* `vector.new(a[, b, c])`: * `vector.new(a[, b, c])`:
* Returns a vector. * Returns a vector.
@ -2310,7 +2334,8 @@ For the following functions, `v`, `v1`, `v2` are vectors, `p1`, `p2` are positio
* `vector.round(v)`: * `vector.round(v)`:
* Returns a vector, each dimension rounded to nearest integer. * Returns a vector, each dimension rounded to nearest integer.
* `vector.apply(v, func)`: * `vector.apply(v, func)`:
* Returns a vector where the function `func` has been applied to each component. * Returns a vector where the function `func` has been applied to each
component.
* `vector.equals(v1, v2)`: * `vector.equals(v1, v2)`:
* Returns a boolean, `true` if the vectors are identical. * Returns a boolean, `true` if the vectors are identical.
* `vector.sort(v1, v2)`: * `vector.sort(v1, v2)`:
@ -2329,12 +2354,12 @@ For the following functions `x` can be either a vector or a number:
Helper functions Helper functions
---------------- ----------------
* `dump2(obj, name, dumped)`: returns a string which makes `obj` human readable, * `dump2(obj, name, dumped)`: returns a string which makes `obj`
handles reference loops human-readable, handles reference loops.
* `obj`: arbitrary variable * `obj`: arbitrary variable
* `name`: string, default: `"_"` * `name`: string, default: `"_"`
* `dumped`: table, default: `{}` * `dumped`: table, default: `{}`
* `dump(obj, dumped)`: returns a string which makes `obj` human readable * `dump(obj, dumped)`: returns a string which makes `obj` human-readable
* `obj`: arbitrary variable * `obj`: arbitrary variable
* `dumped`: table, default: `{}` * `dumped`: table, default: `{}`
* `math.hypot(x, y)` * `math.hypot(x, y)`
@ -2374,49 +2399,60 @@ Helper functions
* `minetest.string_to_area("(X1, Y1, Z1) (X2, Y2, Z2)")`: returns two positions * `minetest.string_to_area("(X1, Y1, Z1) (X2, Y2, Z2)")`: returns two positions
* Converts a string representing an area box into two positions * Converts a string representing an area box into two positions
* `minetest.formspec_escape(string)`: returns a string * `minetest.formspec_escape(string)`: returns a string
* escapes the characters "[", "]", "\", "," and ";", which can not be used in formspecs * escapes the characters "[", "]", "\", "," and ";", which can not be used
in formspecs.
* `minetest.is_yes(arg)` * `minetest.is_yes(arg)`
* returns true if passed 'y', 'yes', 'true' or a number that isn't zero. * returns true if passed 'y', 'yes', 'true' or a number that isn't zero.
* `minetest.get_us_time()` * `minetest.get_us_time()`
* returns time with microsecond precision. May not return wall time. * returns time with microsecond precision. May not return wall time.
* `table.copy(table)`: returns a table * `table.copy(table)`: returns a table
* returns a deep copy of `table` * returns a deep copy of `table`
* `minetest.pointed_thing_to_face_pos(placer, pointed_thing)`: returns a position * `minetest.pointed_thing_to_face_pos(placer, pointed_thing)`: returns a
position.
* returns the exact position on the surface of a pointed node * returns the exact position on the surface of a pointed node
Translations Translations
------------ ------------
Texts can be translated client-side with the help of `minetest.translate` and translation files. Texts can be translated client-side with the help of `minetest.translate` and
translation files.
### Translating a string ### Translating a string
Two functions are provided to translate strings: `minetest.translate` and `minetest.get_translator`. Two functions are provided to translate strings: `minetest.translate` and
`minetest.get_translator`.
* `minetest.get_translator(textdomain)` is a simple wrapper around `minetest.translate`, and * `minetest.get_translator(textdomain)` is a simple wrapper around
`minetest.get_translator(textdomain)(str, ...)` is equivalent to `minetest.translate(textdomain, str, ...)`. `minetest.translate`, and `minetest.get_translator(textdomain)(str, ...)` is
It is intended to be used in the following way, so that it avoids verbose repetitions of `minetest.translate`: equivalent to `minetest.translate(textdomain, str, ...)`.
It is intended to be used in the following way, so that it avoids verbose
repetitions of `minetest.translate`:
local S = minetest.get_translator(textdomain) local S = minetest.get_translator(textdomain)
S(str, ...) S(str, ...)
As an extra commodity, if `textdomain` is nil, it is assumed to be "" instead. As an extra commodity, if `textdomain` is nil, it is assumed to be "" instead.
* `minetest.translate(textdomain, str, ...)` translates the string `str` with the given `textdomain` * `minetest.translate(textdomain, str, ...)` translates the string `str` with
for disambiguation. The textdomain must match the textdomain specified in the translation file in order the given `textdomain` for disambiguation. The textdomain must match the
to get the string translated. This can be used so that a string is translated differently in different contexts. textdomain specified in the translation file in order to get the string
It is advised to use the name of the mod as textdomain whenever possible, to avoid clashes with other mods. translated. This can be used so that a string is translated differently in
This function must be given a number of arguments equal to the number of arguments the translated string expects. different contexts.
Arguments are literal strings -- they will not be translated, so if you want them to be, they need to come as It is advised to use the name of the mod as textdomain whenever possible, to
outputs of `minetest.translate` as well. avoid clashes with other mods.
This function must be given a number of arguments equal to the number of
arguments the translated string expects.
Arguments are literal strings -- they will not be translated, so if you want
them to be, they need to come as outputs of `minetest.translate` as well.
For instance, suppose we want to translate "@1 Wool" with "@1" being replaced by the translation of "Red". For instance, suppose we want to translate "@1 Wool" with "@1" being replaced
We can do the following: by the translation of "Red". We can do the following:
local S = minetest.get_translator() local S = minetest.get_translator()
S("@1 Wool", S("Red")) S("@1 Wool", S("Red"))
This will be displayed as "Red Wool" on old clients and on clients that do not have localization enabled. This will be displayed as "Red Wool" on old clients and on clients that do
However, if we have for instance a translation file named `wool.fr.tr` containing the following: not have localization enabled. However, if we have for instance a translation
file named `wool.fr.tr` containing the following:
@1 Wool=Laine @1 @1 Wool=Laine @1
Red=Rouge Red=Rouge
@ -2425,36 +2461,43 @@ Two functions are provided to translate strings: `minetest.translate` and `minet
### Operations on translated strings ### Operations on translated strings
The output of `minetest.translate` is a string, with escape sequences adding additional information to that string The output of `minetest.translate` is a string, with escape sequences adding
so that it can be translated on the different clients. In particular, you can't expect operations like string.length additional information to that string so that it can be translated on the
to work on them like you would expect them to, or string.gsub to work in the expected manner. However, string different clients. In particular, you can't expect operations like string.length
concatenation will still work as expected (note that you should only use this for things like formspecs; do not to work on them like you would expect them to, or string.gsub to work in the
translate sentences by breaking them into parts; arguments should be used instead), and operations such as expected manner. However, string concatenation will still work as expected
`minetest.colorize` which are only concatenation under the hood as well. (note that you should only use this for things like formspecs; do not translate
sentences by breaking them into parts; arguments should be used instead), and
operations such as `minetest.colorize` which are also concatenation.
### Translation file format ### Translation file format
A translation file has the suffix `.[lang].tr`, where `[lang]` is the language it corresponds to. A translation file has the suffix `.[lang].tr`, where `[lang]` is the language
it corresponds to.
The file should be a text file, with the following format: The file should be a text file, with the following format:
* Lines beginning with `# textdomain:` (the space is significant) can be used to specify the text * Lines beginning with `# textdomain:` (the space is significant) can be used
domain of all following translations in the file. to specify the text domain of all following translations in the file.
* All other empty lines or lines beginning with `#` are ignored. * All other empty lines or lines beginning with `#` are ignored.
* Other lines should be in the format `original=translated`. Both `original` and `translated` can * Other lines should be in the format `original=translated`. Both `original`
contain escape sequences beginning with `@` to insert arguments, literal `@`, `=` or newline and `translated` can contain escape sequences beginning with `@` to insert
(See ### Escapes below). There must be no extraneous whitespace around the `=` or at the beginning arguments, literal `@`, `=` or newline (See ### Escapes below).
or the end of the line. There must be no extraneous whitespace around the `=` or at the beginning or
the end of the line.
### Escapes ### Escapes
Strings that need to be translated can contain several escapes, preceded by `@`. Strings that need to be translated can contain several escapes, preceded by `@`.
* `@@` acts as a literal `@`. * `@@` acts as a literal `@`.
* `@n`, where `n` is a digit between 1 and 9, is an argument for the translated string that will be inlined * `@n`, where `n` is a digit between 1 and 9, is an argument for the translated
when translation. Due to how translations are implemented, the original translation string **must** have string that will be inlined when translation. Due to how translations are
its arguments in increasing order, without gaps or repetitions, starting from 1. implemented, the original translation string **must** have its arguments in
* `@=` acts as a literal `=`. It is not required in strings given to `minetest.translate`, but is in translation increasing order, without gaps or repetitions, starting from 1.
files to avoid being confused with the `=` separating the original from the translation. * `@=` acts as a literal `=`. It is not required in strings given to
* `@\n` (where the `\n` is a literal newline) acts as a literal newline. As with `@=`, this escape is not required `minetest.translate`, but is in translation files to avoid being confused
in strings given to `minetest.translate`, but is in translation files. with the `=` separating the original from the translation.
* `@\n` (where the `\n` is a literal newline) acts as a literal newline.
As with `@=`, this escape is not required in strings given to
`minetest.translate`, but is in translation files.
* `@n` acts as a literal newline as well. * `@n` acts as a literal newline as well.
`minetest` namespace reference `minetest` namespace reference
@ -2462,8 +2505,10 @@ Strings that need to be translated can contain several escapes, preceded by `@`.
### Utilities ### Utilities
* `minetest.get_current_modname()`: returns the currently loading mod's name, when we are loading a mod * `minetest.get_current_modname()`: returns the currently loading mod's name,
* `minetest.get_modpath(modname)`: returns e.g. `"/home/user/.minetest/usermods/modname"` 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 * Useful for loading additional `.lua` modules or static data from mod
* `minetest.get_modnames()`: returns a list of installed mods * `minetest.get_modnames()`: returns a list of installed mods
* Return a list of installed mods, sorted alphabetically * Return a list of installed mods, sorted alphabetically
@ -2494,7 +2539,8 @@ Strings that need to be translated can contain several escapes, preceded by `@`.
* `arg`: string or table in format `{foo=true, bar=true}` * `arg`: string or table in format `{foo=true, bar=true}`
* `missing_features`: `{foo=true, bar=true}` * `missing_features`: `{foo=true, bar=true}`
* `minetest.get_player_information(player_name)`: * `minetest.get_player_information(player_name)`:
* Returns a table containing information about a player. Example return value: * Returns a table containing information about a player.
Example return value:
{ {
address = "127.0.0.1", -- IP address of client address = "127.0.0.1", -- IP address of client
@ -2525,14 +2571,15 @@ Strings that need to be translated can contain several escapes, preceded by `@`.
* true: return only subdirectory names, or * true: return only subdirectory names, or
* false: return only file names. * false: return only file names.
* `minetest.safe_file_write(path, content)`: returns boolean indicating success * `minetest.safe_file_write(path, content)`: returns boolean indicating success
* Replaces contents of file at path with new contents in a safe (atomic) way. * Replaces contents of file at path with new contents in a safe (atomic)
Use this instead of below code when writing e.g. database files: way. Use this instead of below code when writing e.g. database files:
`local f = io.open(path, "wb"); f:write(content); f:close()` `local f = io.open(path, "wb"); f:write(content); f:close()`
* `minetest.get_version()`: returns a table containing components of the * `minetest.get_version()`: returns a table containing components of the
engine version. Components: engine version. Components:
* `project`: Name of the project, eg, "Minetest" * `project`: Name of the project, eg, "Minetest"
* `string`: Simple version, eg, "1.2.3-dev" * `string`: Simple version, eg, "1.2.3-dev"
* `hash`: Full git version (only set if available), eg, "1.2.3-dev-01234567-dirty" * `hash`: Full git version (only set if available),
eg, "1.2.3-dev-01234567-dirty".
Use this for informational purposes only. The information in the returned Use this for informational purposes only. The information in the returned
table does not represent the capabilities of the engine, nor is it table does not represent the capabilities of the engine, nor is it
reliable or verifiable. Compatible forks will have a different name and reliable or verifiable. Compatible forks will have a different name and
@ -2568,11 +2615,14 @@ Call these functions only at load time!
* Check recipe table syntax for different types below. * Check recipe table syntax for different types below.
* `minetest.clear_craft(recipe)` * `minetest.clear_craft(recipe)`
* Will erase existing craft based either on output item or on input recipe. * Will erase existing craft based either on output item or on input recipe.
* Specify either output or input only. If you specify both, input will be ignored. For input use the same recipe table * Specify either output or input only. If you specify both, input will be
syntax as for `minetest.register_craft(recipe)`. For output specify only the item, without a quantity. ignored. For input use the same recipe table syntax as for
`minetest.register_craft(recipe)`. For output specify only the item,
without a quantity.
* If no erase candidate could be found, Lua exception will be thrown. * If no erase candidate could be found, Lua exception will be thrown.
* **Warning**! The type field ("shaped","cooking" or any other) will be ignored if the recipe * **Warning**! The type field ("shaped","cooking" or any other) will be
contains output. Erasing is then done independently from the crafting method. ignored if the recipe contains output. Erasing is then done independently
from the crafting method.
* `minetest.register_ore(ore definition)` * `minetest.register_ore(ore definition)`
* `minetest.register_biome(biome definition)` * `minetest.register_biome(biome definition)`
* `minetest.register_decoration(decoration definition)` * `minetest.register_decoration(decoration definition)`
@ -2591,19 +2641,19 @@ Call these functions only at load time!
* Called every server step, usually interval of 0.1s * Called every server step, usually interval of 0.1s
* `minetest.register_on_shutdown(func())` * `minetest.register_on_shutdown(func())`
* Called before server shutdown * Called before server shutdown
* **Warning**: If the server terminates abnormally (i.e. crashes), the registered * **Warning**: If the server terminates abnormally (i.e. crashes), the
callbacks **will likely not be run**. Data should be saved at registered callbacks **will likely not be run**. Data should be saved at
semi-frequent intervals as well as on server shutdown. semi-frequent intervals as well as on server shutdown.
* `minetest.register_on_placenode(func(pos, newnode, placer, oldnode, itemstack, pointed_thing))` * `minetest.register_on_placenode(func(pos, newnode, placer, oldnode, itemstack, pointed_thing))`
* Called when a node has been placed * Called when a node has been placed
* If return `true` no item is taken from `itemstack` * If return `true` no item is taken from `itemstack`
* `placer` may be any valid ObjectRef or nil. * `placer` may be any valid ObjectRef or nil.
* **Not recommended**; use `on_construct` or `after_place_node` in node definition * **Not recommended**; use `on_construct` or `after_place_node` in node
whenever possible definition whenever possible.
* `minetest.register_on_dignode(func(pos, oldnode, digger))` * `minetest.register_on_dignode(func(pos, oldnode, digger))`
* Called when a node has been dug. * Called when a node has been dug.
* **Not recommended**; Use `on_destruct` or `after_dig_node` in node definition * **Not recommended**; Use `on_destruct` or `after_dig_node` in node
whenever possible definition whenever possible.
* `minetest.register_on_punchnode(func(pos, node, puncher, pointed_thing))` * `minetest.register_on_punchnode(func(pos, node, puncher, pointed_thing))`
* Called when a node is punched * Called when a node is punched
* `minetest.register_on_generated(func(minp, maxp, blockseed))` * `minetest.register_on_generated(func(minp, maxp, blockseed))`
@ -2617,7 +2667,8 @@ Call these functions only at load time!
* Called when a player is punched * Called when a player is punched
* `player` - ObjectRef - Player that was punched * `player` - ObjectRef - Player that was punched
* `hitter` - ObjectRef - Player that hit * `hitter` - ObjectRef - Player that hit
* `time_from_last_punch`: Meant for disallowing spamming of clicks (can be nil) * `time_from_last_punch`: Meant for disallowing spamming of clicks
(can be nil).
* `tool_capabilities`: capability table of used tool (can be nil) * `tool_capabilities`: capability table of used tool (can be nil)
* `dir`: unit vector of direction of punch. Always defined. Points from * `dir`: unit vector of direction of punch. Always defined. Points from
the puncher to the punched. the puncher to the punched.
@ -2628,23 +2679,26 @@ Call these functions only at load time!
* `player`: ObjectRef of the player * `player`: ObjectRef of the player
* `hp_change`: the amount of change. Negative when it is damage. * `hp_change`: the amount of change. Negative when it is damage.
* `modifier`: when true, the function should return the actual `hp_change`. * `modifier`: when true, the function should return the actual `hp_change`.
Note: modifiers only get a temporary hp_change that can be modified by later modifiers. Note: modifiers only get a temporary hp_change that can be modified by
modifiers can return true as a second argument to stop the execution of further functions. later modifiers. modifiers can return true as a second argument to stop
Non-modifiers receive the final hp change calculated by the modifiers. the execution of further functions. Non-modifiers receive the final hp
change calculated by the modifiers.
* `minetest.register_on_respawnplayer(func(ObjectRef))` * `minetest.register_on_respawnplayer(func(ObjectRef))`
* Called when player is to be respawned * Called when player is to be respawned
* Called _before_ repositioning of player occurs * Called _before_ repositioning of player occurs
* return true in func to disable regular player placement * return true in func to disable regular player placement
* `minetest.register_on_prejoinplayer(func(name, ip))` * `minetest.register_on_prejoinplayer(func(name, ip))`
* Called before a player joins the game * Called before a player joins the game
* If it returns a string, the player is disconnected with that string as reason * If it returns a string, the player is disconnected with that string as
reason.
* `minetest.register_on_joinplayer(func(ObjectRef))` * `minetest.register_on_joinplayer(func(ObjectRef))`
* Called when a player joins the game * Called when a player joins the game
* `minetest.register_on_leaveplayer(func(ObjectRef, timed_out))` * `minetest.register_on_leaveplayer(func(ObjectRef, timed_out))`
* Called when a player leaves the game * Called when a player leaves the game
* `timed_out`: True for timeout, false for other reasons. * `timed_out`: True for timeout, false for other reasons.
* `minetest.register_on_auth_fail(func(name, ip))` * `minetest.register_on_auth_fail(func(name, ip))`
* Called when a client attempts to log into an account but supplies the wrong password. * Called when a client attempts to log into an account but supplies the
wrong password.
* `ip`: The IP address of the client. * `ip`: The IP address of the client.
* `name`: The account the client attempted to log into. * `name`: The account the client attempted to log into.
* `minetest.register_on_cheat(func(ObjectRef, cheat))` * `minetest.register_on_cheat(func(ObjectRef, cheat))`
@ -2658,7 +2712,8 @@ Call these functions only at load time!
* `dug_too_fast` * `dug_too_fast`
* `minetest.register_on_chat_message(func(name, message))` * `minetest.register_on_chat_message(func(name, message))`
* Called always when a player says something * 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 * Return `true` to mark the message as handled, which means that it will
not be sent to other players.
* `minetest.register_on_player_receive_fields(func(player, formname, fields))` * `minetest.register_on_player_receive_fields(func(player, formname, fields))`
* Called when a button is pressed in player's inventory form * Called when a button is pressed in player's inventory form
* Newest functions are called first * Newest functions are called first
@ -2666,30 +2721,34 @@ Call these functions only at load time!
* `minetest.register_on_craft(func(itemstack, player, old_craft_grid, craft_inv))` * `minetest.register_on_craft(func(itemstack, player, old_craft_grid, craft_inv))`
* Called when `player` crafts something * Called when `player` crafts something
* `itemstack` is the output * `itemstack` is the output
* `old_craft_grid` contains the recipe (Note: the one in the inventory is cleared) * `old_craft_grid` contains the recipe (Note: the one in the inventory is
cleared).
* `craft_inv` is the inventory with the crafting grid * `craft_inv` is the inventory with the crafting grid
* Return either an `ItemStack`, to replace the output, or `nil`, to not modify it * Return either an `ItemStack`, to replace the output, or `nil`, to not
modify it.
* `minetest.register_craft_predict(func(itemstack, player, old_craft_grid, craft_inv))` * `minetest.register_craft_predict(func(itemstack, player, old_craft_grid, craft_inv))`
* The same as before, except that it is called before the player crafts, to make * The same as before, except that it is called before the player crafts, to
craft prediction, and it should not change anything. make craft prediction, and it should not change anything.
* `minetest.register_on_protection_violation(func(pos, name))` * `minetest.register_on_protection_violation(func(pos, name))`
* Called by `builtin` and mods when a player violates protection at a position * Called by `builtin` and mods when a player violates protection at a
(eg, digs a node or punches a protected entity). position (eg, digs a node or punches a protected entity).
* The registered functions can be called using `minetest.record_protection_violation` * The registered functions can be called using
* The provided function should check that the position is protected by the mod `minetest.record_protection_violation`.
calling this function before it prints a message, if it does, to allow for * The provided function should check that the position is protected by the
multiple protection mods. mod calling this function before it prints a message, if it does, to
allow for multiple protection mods.
* `minetest.register_on_item_eat(func(hp_change, replace_with_item, itemstack, user, pointed_thing))` * `minetest.register_on_item_eat(func(hp_change, replace_with_item, itemstack, user, pointed_thing))`
* Called when an item is eaten, by `minetest.item_eat` * Called when an item is eaten, by `minetest.item_eat`
* Return `true` or `itemstack` to cancel the default item eat response (i.e.: hp increase) * Return `true` or `itemstack` to cancel the default item eat response
(i.e.: hp increase).
* `minetest.register_on_priv_grant(function(name, granter, priv))` * `minetest.register_on_priv_grant(function(name, granter, priv))`
* Called when `granter` grants the priv `priv` to `name`. * Called when `granter` grants the priv `priv` to `name`.
* Note that the callback will be called twice if it's done by a player, once with granter being the player name, * Note that the callback will be called twice if it's done by a player,
and again with granter being nil. once with granter being the player name, and again with granter being nil.
* `minetest.register_on_priv_revoke(function(name, revoker, priv))` * `minetest.register_on_priv_revoke(function(name, revoker, priv))`
* Called when `revoker` revokes the priv `priv` from `name`. * Called when `revoker` revokes the priv `priv` from `name`.
* Note that the callback will be called twice if it's done by a player, once with revoker being the player name, * Note that the callback will be called twice if it's done by a player,
and again with revoker being nil. once with revoker being the player name, and again with revoker being nil.
* `minetest.register_can_bypass_userlimit(function(name, ip))` * `minetest.register_can_bypass_userlimit(function(name, ip))`
* Called when `name` user connects with `ip`. * Called when `name` user connects with `ip`.
* Return `true` to by pass the player limit * Return `true` to by pass the player limit
@ -2707,16 +2766,21 @@ Call these functions only at load time!
* Unregisters a chatcommands registered with `register_chatcommand`. * Unregisters a chatcommands registered with `register_chatcommand`.
* `minetest.register_privilege(name, definition)` * `minetest.register_privilege(name, definition)`
* `definition`: `"description text"` * `definition`: `"description text"`
* `definition`: `{ description = "description text", give_to_singleplayer = boolean}` * `definition`:
the default of `give_to_singleplayer` is true `{description = "description text", give_to_singleplayer = boolean}`
* To allow players with `basic_privs` to grant, see `basic_privs` minetest.conf setting. the default of `give_to_singleplayer` is true.
* `on_grant(name, granter_name)`: Called when given to player `name` by `granter_name`. * To allow players with `basic_privs` to grant, see `basic_privs`
minetest.conf setting.
* `on_grant(name, granter_name)`: Called when given to player `name` by
`granter_name`.
`granter_name` will be nil if the priv was granted by a mod. `granter_name` will be nil if the priv was granted by a mod.
* `on_revoke(name, revoker_name)`: Called when taken from player `name` by `revoker_name`. * `on_revoke(name, revoker_name)`: Called when taken from player `name` by
`revoker_name`.
`revoker_name` will be nil if the priv was revoked by a mod `revoker_name` will be nil if the priv was revoked by a mod
* Note that the above two callbacks will be called twice if a player is responsible - * Note that the above two callbacks will be called twice if a player is
once with the player name, and then with a nil player name. responsible, once with the player name, and then with a nil player name.
* Return true in the above callbacks to stop register_on_priv_grant or revoke being called. * Return true in the above callbacks to stop register_on_priv_grant or
revoke being called.
* `minetest.register_authentication_handler(authentication handler definition)` * `minetest.register_authentication_handler(authentication handler definition)`
* Registers an auth handler that overrides the builtin one * Registers an auth handler that overrides the builtin one
* This function can be called by a single mod once only. * This function can be called by a single mod once only.
@ -2732,7 +2796,8 @@ Call these functions only at load time!
* `minetest.privs_to_string(privs)`: returns `"priv1,priv2,..."` * `minetest.privs_to_string(privs)`: returns `"priv1,priv2,..."`
* Convert between two privilege representations * Convert between two privilege representations
* `minetest.get_player_privs(name) -> {priv1=true,...}` * `minetest.get_player_privs(name) -> {priv1=true,...}`
* `minetest.check_player_privs(player_or_name, ...)`: returns `bool, missing_privs` * `minetest.check_player_privs(player_or_name, ...)`:
returns `bool, missing_privs`
* A quickhand for checking privileges. * A quickhand for checking privileges.
* `player_or_name`: Either a Player object or the name of a player. * `player_or_name`: Either a Player object or the name of a player.
* `...` is either a list of strings, e.g. `"priva", "privb"` or * `...` is either a list of strings, e.g. `"priva", "privb"` or
@ -2741,8 +2806,8 @@ Call these functions only at load time!
* `minetest.check_password_entry(name, entry, password)` * `minetest.check_password_entry(name, entry, password)`
* Returns true if the "password entry" for a player with name matches given * Returns true if the "password entry" for a player with name matches given
password, false otherwise. password, false otherwise.
* The "password entry" is the password representation generated by the engine * The "password entry" is the password representation generated by the
as returned as part of a `get_auth()` call on the auth handler. engine as returned as part of a `get_auth()` call on the auth handler.
* Only use this function for making it possible to log in via password from * Only use this function for making it possible to log in via password from
external protocols such as IRC, other uses are frowned upon. external protocols such as IRC, other uses are frowned upon.
* `minetest.get_password_hash(name, raw_password)` * `minetest.get_password_hash(name, raw_password)`
@ -2752,7 +2817,8 @@ Call these functions only at load time!
from the function, with an externally provided password, as the hash from the function, with an externally provided password, as the hash
in the db might use the new SRP verifier format. in the db might use the new SRP verifier format.
* For this purpose, use `minetest.check_password_entry` instead. * For this purpose, use `minetest.check_password_entry` instead.
* `minetest.get_player_ip(name)`: returns an IP address string for the player `name` * `minetest.get_player_ip(name)`: returns an IP address string for the player
`name`.
* The player needs to be online for this to be successful. * The player needs to be online for this to be successful.
* `minetest.get_auth_handler()`: Return the currently active auth handler * `minetest.get_auth_handler()`: Return the currently active auth handler
@ -2762,13 +2828,16 @@ Call these functions only at load time!
* `minetest.notify_authentication_modified(name)` * `minetest.notify_authentication_modified(name)`
* Must be called by the authentication handler for privilege changes. * Must be called by the authentication handler for privilege changes.
* `name`: string; if omitted, all auth data should be considered modified * `name`: string; if omitted, all auth data should be considered modified
* `minetest.set_player_password(name, password_hash)`: Set password hash of player `name` * `minetest.set_player_password(name, password_hash)`: Set password hash of
* `minetest.set_player_privs(name, {priv1=true,...})`: Set privileges of player `name` player `name`.
* `minetest.set_player_privs(name, {priv1=true,...})`: Set privileges of player
`name`.
* `minetest.auth_reload()` * `minetest.auth_reload()`
* See `reload()` in authentication handler definition * See `reload()` in authentication handler definition
`minetest.set_player_password`, `minetest_set_player_privs`, `minetest_get_player_privs` `minetest.set_player_password`, `minetest_set_player_privs`,
and `minetest.auth_reload` call the authentication handler. `minetest_get_player_privs` and `minetest.auth_reload` call the authentication
handler.
### Chat ### Chat
* `minetest.chat_send_all(text)` * `minetest.chat_send_all(text)`