1 Minetest Lua Client Modding API Reference 5.5.0
2 ================================================
3 * More information at <http://www.minetest.net/>
4 * Developer Wiki: <http://dev.minetest.net/>
9 ** WARNING: The client API is currently unstable, and may break/change without warning. **
11 Content and functionality can be added to Minetest 0.4.15-dev+ by using Lua
12 scripting in run-time loaded mods.
14 A mod is a self-contained bunch of scripts, textures and other related
15 things that is loaded by and interfaces with Minetest.
17 Transferring client-sided mods from the server to the client is planned, but not implemented yet.
19 If you see a deficiency in the API, feel free to attempt to add the
20 functionality in the engine and API. You can send such improvements as
21 source code patches on GitHub (https://github.com/minetest/minetest).
25 If you have any difficulty in understanding this, please read
26 [Programming in Lua](http://www.lua.org/pil/).
30 Mods are loaded during client startup from the mod load paths by running
31 the `init.lua` scripts in a shared environment.
33 In order to load client-side mods, the following conditions need to be satisfied:
35 1) `$path_user/minetest.conf` contains the setting `enable_client_modding = true`
37 2) The client-side mod located in `$path_user/clientmods/<modname>` is added to
38 `$path_user/clientmods/mods.conf` as `load_mod_<modname> = true`.
40 Note: Depending on the remote server's settings, client-side mods might not
41 be loaded or have limited functionality. See setting `csm_restriction_flags` for reference.
45 * `RUN_IN_PLACE=1` (Windows release, local build)
46 * `$path_user`: `<build directory>`
47 * `$path_share`: `<build directory>`
48 * `RUN_IN_PLACE=0`: (Linux release)
50 * Linux: `/usr/share/minetest`
51 * Windows: `<install directory>/minetest-0.4.x`
53 * Linux: `$HOME/.minetest`
54 * Windows: `C:/users/<user>/AppData/minetest` (maybe)
60 * `$path_share/clientmods/`
61 * `$path_user/clientmods/` (User-installed mods)
63 In a run-in-place version (e.g. the distributed windows version):
65 * `minetest-0.4.x/clientmods/` (User-installed mods)
67 On an installed version on Linux:
69 * `/usr/share/minetest/clientmods/`
70 * `$HOME/.minetest/clientmods/` (User-installed mods)
75 Mods can be put in a subdirectory, if the parent directory, which otherwise
76 should be a mod, contains a file named `modpack.conf`.
77 The file is a key-value store of modpack details.
79 * `name`: The modpack name.
80 * `description`: Description of mod to be shown in the Mods tab of the main
83 Mod directory structure
84 ------------------------
94 The location of this directory.
98 An (optional) settings file that provides meta information about the mod.
100 * `name`: The mod name. Allows Minetest to determine the mod name even if the
101 folder is wrongly named.
102 * `description`: Description of mod to be shown in the Mods tab of the main
104 * `depends`: A comma separated list of dependencies. These are mods that must be
105 loaded before this mod.
106 * `optional_depends`: A comma separated list of optional dependencies.
107 Like a dependency, but no error if the mod doesn't exist.
111 The main Lua script. Running this script should register everything it
112 wants to register. Subsequent execution depends on minetest calling the
113 registered callbacks.
115 **NOTE**: Client mods currently can't provide textures, sounds, or models by
116 themselves. Any media referenced in function calls must already be loaded
117 (provided by mods that exist on the server).
119 Naming convention for registered textual names
120 ----------------------------------------------
121 Registered names should generally be in this format:
123 "modname:<whatever>" (<whatever> can have characters a-zA-Z0-9_)
125 This is to prevent conflicting names from corrupting maps and is
126 enforced by the mod loader.
129 In the mod `experimental`, there is the ideal item/node/entity name `tnt`.
130 So the name should be `experimental:tnt`.
132 Enforcement can be overridden by prefixing the name with `:`. This can
133 be used for overriding the registrations of some other mod.
135 Example: Any mod can redefine `experimental:tnt` by using the name
140 (also that mod is required to have `experimental` as a dependency)
142 The `:` prefix can also be used for maintaining backwards compatibility.
146 **NOTE: Connecting sounds to objects is not implemented.**
148 Only Ogg Vorbis files are supported.
150 For positional playing of sounds, only single-channel (mono) files are
151 supported. Otherwise OpenAL will play them non-positionally.
153 Mods should generally prefix their sounds with `modname_`, e.g. given
154 the mod name "`foomod`", a sound could be called:
158 Sounds are referred to by their name with a dot, a single digit and the
159 file extension stripped out. When a sound is played, the actual sound file
160 is chosen randomly from the matching sounds.
162 When playing the sound `foomod_foosound`, the sound is chosen randomly
163 from the available ones of the following files:
165 * `foomod_foosound.ogg`
166 * `foomod_foosound.0.ogg`
167 * `foomod_foosound.1.ogg`
169 * `foomod_foosound.9.ogg`
171 Examples of sound parameter tables:
175 gain = 1.0, -- default
177 -- Play locationless, looped
179 gain = 1.0, -- default
182 -- Play in a location
184 pos = {x = 1, y = 2, z = 3},
185 gain = 1.0, -- default
187 -- Play connected to an object, looped
189 object = <an ObjectRef>,
190 gain = 1.0, -- default
194 Looped sounds must either be connected to an object or played locationless.
198 * e.g. `"default_place_node"`
200 * e.g. `{name = "default_place_node"}`
201 * e.g. `{name = "default_place_node", gain = 1.0}`
203 Representations of simple things
204 --------------------------------
208 {x=num, y=num, z=num}
210 For helper functions see "Vector helpers".
214 * `{type="node", under=pos, above=pos}`
215 * `{type="object", id=ObjectID}`
217 Flag Specifier Format
218 ---------------------
219 Flags using the standardized flag specifier format can be specified in either of
220 two ways, by string or table.
222 The string format is a comma-delimited set of flag names; whitespace and
223 unrecognized flag fields are ignored. Specifying a flag in the string sets the
224 flag, and specifying a flag prefixed by the string `"no"` explicitly
225 clears the flag from whatever the default may be.
227 In addition to the standard string flag format, the schematic flags field can
228 also be a table of flag names to boolean values representing whether or not the
229 flag is set. Additionally, if a field with the flag name prefixed with `"no"`
230 is present, mapped to a boolean of any value, the specified flag is unset.
232 E.g. A flag field of value
234 {place_center_x = true, place_center_y=false, place_center_z=true}
238 {place_center_x = true, noplace_center_y=true, place_center_z=true}
240 which is equivalent to
242 "place_center_x, noplace_center_y, place_center_z"
246 "place_center_x, place_center_z"
248 since, by default, no schematic attributes are set.
252 Formspec defines a menu. It is a string, with a somewhat strange format.
254 Spaces and newlines can be inserted between the blocks, as is used in the
262 list[context;main;0,0;8,4;]
263 list[current_player;main;0,5;8,4;]
268 list[context;fuel;2,3;1,1;]
269 list[context;src;2,1;1,1;]
270 list[context;dst;5,1;2,2;]
271 list[current_player;main;0,5;8,4;]
273 #### Minecraft-like player inventory
276 image[1,0.6;1,2;player.png]
277 list[current_player;main;0,3.5;8,4;]
278 list[current_player;craft;3,0;3,3;]
279 list[current_player;craftpreview;7,1;1,1;]
283 #### `size[<W>,<H>,<fixed_size>]`
284 * Define the size of the menu in inventory slots
285 * `fixed_size`: `true`/`false` (optional)
286 * deprecated: `invsize[<W>,<H>;]`
288 #### `container[<X>,<Y>]`
289 * Start of a container block, moves all physical elements in the container by (X, Y)
290 * Must have matching container_end
291 * Containers can be nested, in which case the offsets are added
292 (child containers are relative to parent containers)
294 #### `container_end[]`
295 * End of a container, following elements are no longer relative to this container
297 #### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]`
298 * Show an inventory list
300 #### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]`
301 * Show an inventory list
303 #### `listring[<inventory location>;<list name>]`
304 * Allows to create a ring of inventory lists
305 * Shift-clicking on items in one element of the ring
306 will send them to the next inventory list inside the ring
307 * The first occurrence of an element inside the ring will
308 determine the inventory where items will be sent to
311 * Shorthand for doing `listring[<inventory location>;<list name>]`
312 for the last two inventory lists added by list[...]
314 #### `listcolors[<slot_bg_normal>;<slot_bg_hover>]`
315 * Sets background color of slots as `ColorString`
316 * Sets background color of slots on mouse hovering
318 #### `listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>]`
319 * Sets background color of slots as `ColorString`
320 * Sets background color of slots on mouse hovering
321 * Sets color of slots border
323 #### `listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>;<tooltip_bgcolor>;<tooltip_fontcolor>]`
324 * Sets background color of slots as `ColorString`
325 * Sets background color of slots on mouse hovering
326 * Sets color of slots border
327 * Sets default background color of tooltips
328 * Sets default font color of tooltips
330 #### `tooltip[<gui_element_name>;<tooltip_text>;<bgcolor>,<fontcolor>]`
331 * Adds tooltip for an element
332 * `<bgcolor>` tooltip background color as `ColorString` (optional)
333 * `<fontcolor>` tooltip font color as `ColorString` (optional)
335 #### `image[<X>,<Y>;<W>,<H>;<texture name>]`
337 * Position and size units are inventory slots
339 #### `item_image[<X>,<Y>;<W>,<H>;<item name>]`
340 * Show an inventory image of registered item/node
341 * Position and size units are inventory slots
343 #### `bgcolor[<color>;<fullscreen>]`
344 * Sets background color of formspec as `ColorString`
345 * If `true`, the background color is drawn fullscreen (does not effect the size of the formspec)
347 #### `background[<X>,<Y>;<W>,<H>;<texture name>]`
348 * Use a background. Inventory rectangles are not drawn then.
349 * Position and size units are inventory slots
350 * Example for formspec 8x4 in 16x resolution: image shall be sized
351 8 times 16px times 4 times 16px.
353 #### `background[<X>,<Y>;<W>,<H>;<texture name>;<auto_clip>]`
354 * Use a background. Inventory rectangles are not drawn then.
355 * Position and size units are inventory slots
356 * Example for formspec 8x4 in 16x resolution:
357 image shall be sized 8 times 16px times 4 times 16px
358 * If `true` the background is clipped to formspec size
359 (`x` and `y` are used as offset values, `w` and `h` are ignored)
361 #### `pwdfield[<X>,<Y>;<W>,<H>;<name>;<label>]`
362 * Textual password style field; will be sent to server when a button is clicked
363 * When enter is pressed in field, fields.key_enter_field will be sent with the name
365 * `x` and `y` position the field relative to the top left of the menu
366 * `w` and `h` are the size of the field
367 * Fields are a set height, but will be vertically centred on `h`
368 * Position and size units are inventory slots
369 * `name` is the name of the field as returned in fields to `on_receive_fields`
370 * `label`, if not blank, will be text printed on the top left above the field
371 * See field_close_on_enter to stop enter closing the formspec
373 #### `field[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`
374 * Textual field; will be sent to server when a button is clicked
375 * When enter is pressed in field, fields.key_enter_field will be sent with the name
377 * `x` and `y` position the field relative to the top left of the menu
378 * `w` and `h` are the size of the field
379 * Fields are a set height, but will be vertically centred on `h`
380 * Position and size units are inventory slots
381 * `name` is the name of the field as returned in fields to `on_receive_fields`
382 * `label`, if not blank, will be text printed on the top left above the field
383 * `default` is the default value of the field
384 * `default` may contain variable references such as `${text}'` which
385 will fill the value from the metadata value `text`
386 * **Note**: no extra text or more than a single variable is supported ATM.
387 * See field_close_on_enter to stop enter closing the formspec
389 #### `field[<name>;<label>;<default>]`
390 * As above, but without position/size units
391 * When enter is pressed in field, fields.key_enter_field will be sent with the name
393 * Special field for creating simple forms, such as sign text input
394 * Must be used without a `size[]` element
395 * A "Proceed" button will be added automatically
396 * See field_close_on_enter to stop enter closing the formspec
398 #### `field_close_on_enter[<name>;<close_on_enter>]`
399 * <name> is the name of the field
400 * if <close_on_enter> is false, pressing enter in the field will submit the form but not close it
401 * defaults to true when not specified (ie: no tag for a field)
403 #### `textarea[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`
404 * Same as fields above, but with multi-line input
406 #### `label[<X>,<Y>;<label>]`
407 * `x` and `y` work as per field
408 * `label` is the text on the label
409 * Position and size units are inventory slots
411 #### `vertlabel[<X>,<Y>;<label>]`
412 * Textual label drawn vertically
413 * `x` and `y` work as per field
414 * `label` is the text on the label
415 * Position and size units are inventory slots
417 #### `button[<X>,<Y>;<W>,<H>;<name>;<label>]`
418 * Clickable button. When clicked, fields will be sent.
419 * `x`, `y` and `name` work as per field
420 * `w` and `h` are the size of the button
421 * Fixed button height. It will be vertically centred on `h`
422 * `label` is the text on the button
423 * Position and size units are inventory slots
425 #### `image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]`
426 * `x`, `y`, `w`, `h`, and `name` work as per button
427 * `texture name` is the filename of an image
428 * Position and size units are inventory slots
430 #### `image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>;<noclip>;<drawborder>;<pressed texture name>]`
431 * `x`, `y`, `w`, `h`, and `name` work as per button
432 * `texture name` is the filename of an image
433 * Position and size units are inventory slots
434 * `noclip=true` means the image button doesn't need to be within specified formsize
435 * `drawborder`: draw button border or not
436 * `pressed texture name` is the filename of an image on pressed state
438 #### `item_image_button[<X>,<Y>;<W>,<H>;<item name>;<name>;<label>]`
439 * `x`, `y`, `w`, `h`, `name` and `label` work as per button
440 * `item name` is the registered name of an item/node,
441 tooltip will be made out of its description
442 to override it use tooltip element
443 * Position and size units are inventory slots
445 #### `button_exit[<X>,<Y>;<W>,<H>;<name>;<label>]`
446 * When clicked, fields will be sent and the form will quit.
448 #### `image_button_exit[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]`
449 * When clicked, fields will be sent and the form will quit.
451 #### `textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>]`
452 * Scrollable item list showing arbitrary text elements
453 * `x` and `y` position the itemlist relative to the top left of the menu
454 * `w` and `h` are the size of the itemlist
455 * `name` fieldname sent to server on doubleclick value is current selected element
456 * `listelements` can be prepended by #color in hexadecimal format RRGGBB (only),
457 * if you want a listelement to start with "#" write "##".
459 #### `textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>;<selected idx>;<transparent>]`
460 * Scrollable itemlist showing arbitrary text elements
461 * `x` and `y` position the item list relative to the top left of the menu
462 * `w` and `h` are the size of the item list
463 * `name` fieldname sent to server on doubleclick value is current selected element
464 * `listelements` can be prepended by #RRGGBB (only) in hexadecimal format
465 * if you want a listelement to start with "#" write "##"
466 * Index to be selected within textlist
467 * `true`/`false`: draw transparent background
468 * See also `minetest.explode_textlist_event` (main menu: `engine.explode_textlist_event`)
470 #### `tabheader[<X>,<Y>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]`
471 * Show a tab**header** at specific position (ignores formsize)
472 * `x` and `y` position the itemlist relative to the top left of the menu
473 * `name` fieldname data is transferred to Lua
474 * `caption 1`...: name shown on top of tab
475 * `current_tab`: index of selected tab 1...
476 * `transparent` (optional): show transparent
477 * `draw_border` (optional): draw border
479 #### `box[<X>,<Y>;<W>,<H>;<color>]`
480 * Simple colored semitransparent box
481 * `x` and `y` position the box relative to the top left of the menu
482 * `w` and `h` are the size of box
483 * `color` is color specified as a `ColorString`
485 #### `dropdown[<X>,<Y>;<W>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>]`
486 * Show a dropdown field
487 * **Important note**: There are two different operation modes:
488 1. handle directly on change (only changed dropdown is submitted)
489 2. read the value on pressing a button (all dropdown values are available)
490 * `x` and `y` position of dropdown
492 * Fieldname data is transferred to Lua
493 * Items to be shown in dropdown
494 * Index of currently selected dropdown item
496 #### `checkbox[<X>,<Y>;<name>;<label>;<selected>]`
498 * `x` and `y`: position of checkbox
499 * `name` fieldname data is transferred to Lua
500 * `label` to be shown left of checkbox
501 * `selected` (optional): `true`/`false`
503 #### `scrollbar[<X>,<Y>;<W>,<H>;<orientation>;<name>;<value>]`
505 * There are two ways to use it:
506 1. handle the changed event (only changed scrollbar is available)
507 2. read the value on pressing a button (all scrollbars are available)
508 * `x` and `y`: position of trackbar
509 * `w` and `h`: width and height
510 * `orientation`: `vertical`/`horizontal`
511 * Fieldname data is transferred to Lua
512 * Value this trackbar is set to (`0`-`1000`)
513 * See also `minetest.explode_scrollbar_event` (main menu: `engine.explode_scrollbar_event`)
515 #### `table[<X>,<Y>;<W>,<H>;<name>;<cell 1>,<cell 2>,...,<cell n>;<selected idx>]`
516 * Show scrollable table using options defined by the previous `tableoptions[]`
517 * Displays cells as defined by the previous `tablecolumns[]`
518 * `x` and `y`: position the itemlist relative to the top left of the menu
519 * `w` and `h` are the size of the itemlist
520 * `name`: fieldname sent to server on row select or doubleclick
521 * `cell 1`...`cell n`: cell contents given in row-major order
522 * `selected idx`: index of row to be selected within table (first row = `1`)
523 * See also `minetest.explode_table_event` (main menu: `engine.explode_table_event`)
525 #### `tableoptions[<opt 1>;<opt 2>;...]`
526 * Sets options for `table[]`
528 * default text color (`ColorString`), defaults to `#FFFFFF`
529 * `background=#RRGGBB`
530 * table background color (`ColorString`), defaults to `#000000`
531 * `border=<true/false>`
532 * should the table be drawn with a border? (default: `true`)
533 * `highlight=#RRGGBB`
534 * highlight background color (`ColorString`), defaults to `#466432`
535 * `highlight_text=#RRGGBB`
536 * highlight text color (`ColorString`), defaults to `#FFFFFF`
537 * `opendepth=<value>`
538 * all subtrees up to `depth < value` are open (default value = `0`)
539 * only useful when there is a column of type "tree"
541 #### `tablecolumns[<type 1>,<opt 1a>,<opt 1b>,...;<type 2>,<opt 2a>,<opt 2b>;...]`
542 * Sets columns for `table[]`
543 * Types: `text`, `image`, `color`, `indent`, `tree`
544 * `text`: show cell contents as text
545 * `image`: cell contents are an image index, use column options to define images
546 * `color`: cell contents are a ColorString and define color of following cell
547 * `indent`: cell contents are a number and define indentation of following cell
548 * `tree`: same as indent, but user can open and close subtrees (treeview-like)
551 * for `text` and `image`: content alignment within cells.
552 Available values: `left` (default), `center`, `right`, `inline`
554 * for `text` and `image`: minimum width in em (default: `0`)
555 * for `indent` and `tree`: indent width in em (default: `1.5`)
556 * `padding=<value>`: padding left of the column, in em (default `0.5`).
557 Exception: defaults to 0 for indent columns
558 * `tooltip=<value>`: tooltip text (default: empty)
559 * `image` column options:
560 * `0=<value>` sets image for image index 0
561 * `1=<value>` sets image for image index 1
562 * `2=<value>` sets image for image index 2
563 * and so on; defined indices need not be contiguous empty or
564 non-numeric cells are treated as `0`.
565 * `color` column options:
566 * `span=<value>`: number of following columns to affect (default: infinite)
568 **Note**: do _not_ use a element name starting with `key_`; those names are reserved to
569 pass key press events to formspec!
573 * `vector.new(a[, b, c])`: returns a vector:
574 * A copy of `a` if `a` is a vector.
575 * `{x = a, y = b, z = c}`, if all `a, b, c` are defined
576 * `vector.direction(p1, p2)`: returns a vector
577 * `vector.distance(p1, p2)`: returns a number
578 * `vector.length(v)`: returns a number
579 * `vector.normalize(v)`: returns a vector
580 * `vector.floor(v)`: returns a vector, each dimension rounded down
581 * `vector.round(v)`: returns a vector, each dimension rounded to nearest int
582 * `vector.apply(v, func)`: returns a vector
583 * `vector.equals(v1, v2)`: returns a boolean
585 For the following functions `x` can be either a vector or a number:
587 * `vector.add(v, x)`: returns a vector
588 * `vector.subtract(v, x)`: returns a vector
589 * `vector.multiply(v, x)`: returns a scaled vector or Schur product
590 * `vector.divide(v, x)`: returns a scaled vector or Schur quotient
594 * `dump2(obj, name="_", dumped={})`
595 * Return object serialized as a string, handles reference loops
596 * `dump(obj, dumped={})`
597 * Return object serialized as a string
599 * Get the hypotenuse of a triangle with legs x and y.
600 Useful for distance calculation.
601 * `math.sign(x, tolerance)`
602 * Get the sign of a number.
603 Optional: Also returns `0` when the absolute value is within the tolerance (default: `0`)
604 * `string.split(str, separator=",", include_empty=false, max_splits=-1, sep_is_pattern=false)`
605 * If `max_splits` is negative, do not limit splits.
606 * `sep_is_pattern` specifies if separator is a plain string or a pattern (regex).
607 * e.g. `string:split("a,b", ",") == {"a","b"}`
609 * e.g. `string.trim("\n \t\tfoo bar\t ") == "foo bar"`
610 * `minetest.wrap_text(str, limit)`: returns a string
611 * Adds new lines to the string to keep it within the specified character limit
612 * limit: Maximal amount of characters in one line
613 * `minetest.pos_to_string({x=X,y=Y,z=Z}, decimal_places))`: returns string `"(X,Y,Z)"`
614 * Convert position to a printable string
615 Optional: 'decimal_places' will round the x, y and z of the pos to the given decimal place.
616 * `minetest.string_to_pos(string)`: returns a position
617 * Same but in reverse. Returns `nil` if the string can't be parsed to a position.
618 * `minetest.string_to_area("(X1, Y1, Z1) (X2, Y2, Z2)")`: returns two positions
619 * Converts a string representing an area box into two positions
620 * `minetest.is_yes(arg)`
621 * returns whether `arg` can be interpreted as yes
622 * `minetest.is_nan(arg)`
623 * returns true when the passed number represents NaN.
624 * `table.copy(table)`: returns a table
625 * returns a deep copy of `table`
627 Minetest namespace reference
628 ------------------------------
632 * `minetest.get_current_modname()`: returns the currently loading mod's name, when we are loading a mod
633 * `minetest.get_modpath(modname)`: returns virtual path of given mod including
634 the trailing separator. This is useful to load additional Lua files
635 contained in your mod:
636 e.g. `dofile(minetest.get_modpath(minetest.get_current_modname()) .. "stuff.lua")`
637 * `minetest.get_language()`: returns two strings
638 * the current gettext locale
639 * the current language code (the same as used for client-side translations)
640 * `minetest.get_version()`: returns a table containing components of the
641 engine version. Components:
642 * `project`: Name of the project, eg, "Minetest"
643 * `string`: Simple version, eg, "1.2.3-dev"
644 * `hash`: Full git version (only set if available), eg, "1.2.3-dev-01234567-dirty"
645 Use this for informational purposes only. The information in the returned
646 table does not represent the capabilities of the engine, nor is it
647 reliable or verifiable. Compatible forks will have a different name and
648 version entirely. To check for the presence of engine features, test
649 whether the functions exported by the wanted features exist. For example:
650 `if minetest.check_for_falling then ... end`.
651 * `minetest.sha1(data, [raw])`: returns the sha1 hash of data
652 * `data`: string of data to hash
653 * `raw`: return raw bytes instead of hex digits, default: false
654 * `minetest.colorspec_to_colorstring(colorspec)`: Converts a ColorSpec to a
655 ColorString. If the ColorSpec is invalid, returns `nil`.
656 * `colorspec`: The ColorSpec to convert
657 * `minetest.get_csm_restrictions()`: returns a table of `Flags` indicating the
658 restrictions applied to the current mod.
659 * If a flag in this table is set to true, the feature is RESTRICTED.
660 * Possible flags: `load_client_mods`, `chat_messages`, `read_itemdefs`,
661 `read_nodedefs`, `lookup_nodes`, `read_playerinfo`
664 * `minetest.debug(...)`
665 * Equivalent to `minetest.log(table.concat({...}, "\t"))`
666 * `minetest.log([level,] text)`
667 * `level` is one of `"none"`, `"error"`, `"warning"`, `"action"`,
668 `"info"`, or `"verbose"`. Default is `"none"`.
670 ### Global callback registration functions
671 Call these functions only at load time!
673 * `minetest.register_globalstep(function(dtime))`
674 * Called every client environment step, usually interval of 0.1s
675 * `minetest.register_on_mods_loaded(function())`
676 * Called just after mods have finished loading.
677 * `minetest.register_on_shutdown(function())`
678 * Called before client shutdown
679 * **Warning**: If the client terminates abnormally (i.e. crashes), the registered
680 callbacks **will likely not be run**. Data should be saved at
681 semi-frequent intervals as well as on server shutdown.
682 * `minetest.register_on_receiving_chat_message(function(message))`
683 * Called always when a client receive a message
684 * Return `true` to mark the message as handled, which means that it will not be shown to chat
685 * `minetest.register_on_sending_chat_message(function(message))`
686 * Called always when a client send a message from chat
687 * Return `true` to mark the message as handled, which means that it will not be sent to server
688 * `minetest.register_chatcommand(cmd, chatcommand definition)`
689 * Adds definition to minetest.registered_chatcommands
690 * `minetest.unregister_chatcommand(name)`
691 * Unregisters a chatcommands registered with register_chatcommand.
692 * `minetest.register_on_chatcommand(function(command, params))`
693 * Called always when a chatcommand is triggered, before `minetest.registered_chatcommands`
694 is checked to see if that the command exists, but after the input is parsed.
695 * Return `true` to mark the command as handled, which means that the default
696 handlers will be prevented.
697 * `minetest.register_on_death(function())`
698 * Called when the local player dies
699 * `minetest.register_on_hp_modification(function(hp))`
700 * Called when server modified player's HP
701 * `minetest.register_on_damage_taken(function(hp))`
702 * Called when the local player take damages
703 * `minetest.register_on_formspec_input(function(formname, fields))`
704 * Called when a button is pressed in the local player's inventory form
705 * Newest functions are called first
706 * If function returns `true`, remaining functions are not called
707 * `minetest.register_on_dignode(function(pos, node))`
708 * Called when the local player digs a node
709 * Newest functions are called first
710 * If any function returns true, the node isn't dug
711 * `minetest.register_on_punchnode(function(pos, node))`
712 * Called when the local player punches a node
713 * Newest functions are called first
714 * If any function returns true, the punch is ignored
715 * `minetest.register_on_placenode(function(pointed_thing, node))`
716 * Called when a node has been placed
717 * `minetest.register_on_item_use(function(item, pointed_thing))`
718 * Called when the local player uses an item.
719 * Newest functions are called first.
720 * If any function returns true, the item use is not sent to server.
721 * `minetest.register_on_modchannel_message(function(channel_name, sender, message))`
722 * Called when an incoming mod channel message is received
723 * You must have joined some channels before, and server must acknowledge the
725 * If message comes from a server mod, `sender` field is an empty string.
726 * `minetest.register_on_modchannel_signal(function(channel_name, signal))`
727 * Called when a valid incoming mod channel signal is received
728 * Signal id permit to react to server mod channel events
729 * Possible values are:
734 4: event_on_not_joined_channel
736 * `minetest.register_on_inventory_open(function(inventory))`
737 * Called when the local player open inventory
738 * Newest functions are called first
739 * If any function returns true, inventory doesn't open
741 * `minetest.sound_play(spec, parameters)`: returns a handle
742 * `spec` is a `SimpleSoundSpec`
743 * `parameters` is a sound parameter table
744 * `minetest.sound_stop(handle)`
745 * `handle` is a handle returned by `minetest.sound_play`
746 * `minetest.sound_fade(handle, step, gain)`
747 * `handle` is a handle returned by `minetest.sound_play`
748 * `step` determines how fast a sound will fade.
749 Negative step will lower the sound volume, positive step will increase
751 * `gain` the target gain for the fade.
754 * `minetest.after(time, func, ...)`
755 * Call the function `func` after `time` seconds, may be fractional
756 * Optional: Variable number of arguments that are passed to `func`
757 * `minetest.get_us_time()`
758 * Returns time with microsecond precision. May not return wall time.
759 * `minetest.get_timeofday()`
760 * Returns the time of day: `0` for midnight, `0.5` for midday
763 * `minetest.get_node_or_nil(pos)`
764 * Returns the node at the given position as table in the format
765 `{name="node_name", param1=0, param2=0}`, returns `nil`
766 for unloaded areas or flavor limited areas.
767 * `minetest.get_node_light(pos, timeofday)`
768 * Gets the light value at the given position. Note that the light value
769 "inside" the node at the given position is returned, so you usually want
770 to get the light value of a neighbor.
771 * `pos`: The position where to measure the light.
772 * `timeofday`: `nil` for current time, `0` for night, `0.5` for day
773 * Returns a number between `0` and `15` or `nil`
774 * `minetest.find_node_near(pos, radius, nodenames, [search_center])`: returns pos or `nil`
775 * `radius`: using a maximum metric
776 * `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
777 * `search_center` is an optional boolean (default: `false`)
778 If true `pos` is also checked for the nodes
779 * `minetest.find_nodes_in_area(pos1, pos2, nodenames, [grouped])`
780 * `pos1` and `pos2` are the min and max positions of the area to search.
781 * `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
782 * If `grouped` is true the return value is a table indexed by node name
783 which contains lists of positions.
784 * If `grouped` is false or absent the return values are as follows:
785 first value: Table with all node positions
786 second value: Table with the count of each node with the node name
788 * Area volume is limited to 4,096,000 nodes
789 * `minetest.find_nodes_in_area_under_air(pos1, pos2, nodenames)`: returns a
791 * `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
792 * Return value: Table with all node positions with a node air above
793 * Area volume is limited to 4,096,000 nodes
794 * `minetest.line_of_sight(pos1, pos2)`: returns `boolean, pos`
795 * Checks if there is anything other than air between pos1 and pos2.
796 * Returns false if something is blocking the sight.
797 * Returns the position of the blocking node when `false`
798 * `pos1`: First position
799 * `pos2`: Second position
800 * `minetest.raycast(pos1, pos2, objects, liquids)`: returns `Raycast`
801 * Creates a `Raycast` object.
802 * `pos1`: start of the ray
803 * `pos2`: end of the ray
804 * `objects`: if false, only nodes will be returned. Default is `true`.
805 * `liquids`: if false, liquid nodes won't be returned. Default is `false`.
807 * `minetest.find_nodes_with_meta(pos1, pos2)`
808 * Get a table of positions of nodes that have metadata within a region
810 * `minetest.get_meta(pos)`
811 * Get a `NodeMetaRef` at that position
812 * `minetest.get_node_level(pos)`
813 * get level of leveled node (water, snow)
814 * `minetest.get_node_max_level(pos)`
815 * get max available level for leveled node
818 * `minetest.send_chat_message(message)`
819 * Act as if `message` was typed by the player into the terminal.
820 * `minetest.run_server_chatcommand(cmd, param)`
821 * Alias for `minetest.send_chat_message("/" .. cmd .. " " .. param)`
822 * `minetest.clear_out_chat_queue()`
823 * Clears the out chat queue
824 * `minetest.localplayer`
825 * Reference to the LocalPlayer object. See [`LocalPlayer`](#localplayer) class reference for methods.
828 * `minetest.get_privilege_list()`
829 * Returns a list of privileges the current player has in the format `{priv1=true,...}`
830 * `minetest.string_to_privs(str)`: returns `{priv1=true,...}`
831 * `minetest.privs_to_string(privs)`: returns `"priv1,priv2,..."`
832 * Convert between two privilege representations
834 ### Client Environment
835 * `minetest.get_player_names()`
836 * Returns list of player names on server (nil if CSM_RF_READ_PLAYERINFO is enabled by server)
837 * `minetest.disconnect()`
838 * Disconnect from the server and exit to main menu.
839 * Returns `false` if the client is already disconnecting otherwise returns `true`.
840 * `minetest.get_server_info()`
841 * Returns [server info](#server-info).
842 * `minetest.send_respawn()`
843 * Sends a respawn request to the server.
846 * `minetest.get_mod_storage()`:
847 * returns reference to mod private `StorageRef`
848 * must be called during mod load time
851 ![Mod channels communication scheme](docs/mod channels.png)
853 * `minetest.mod_channel_join(channel_name)`
854 * Client joins channel `channel_name`, and creates it, if necessary. You
855 should listen from incoming messages with `minetest.register_on_modchannel_message`
856 call to receive incoming messages. Warning, this function is asynchronous.
859 * `minetest.add_particle(particle definition)`
861 * `minetest.add_particlespawner(particlespawner definition)`
862 * Add a `ParticleSpawner`, an object that spawns an amount of particles over `time` seconds
863 * Returns an `id`, and -1 if adding didn't succeed
865 * `minetest.delete_particlespawner(id)`
866 * Delete `ParticleSpawner` with `id` (return value from `minetest.add_particlespawner`)
869 * `minetest.parse_json(string[, nullvalue])`: returns something
870 * Convert a string containing JSON data into the Lua equivalent
871 * `nullvalue`: returned in place of the JSON null; defaults to `nil`
872 * On success returns a table, a string, a number, a boolean or `nullvalue`
873 * On failure outputs an error message and returns `nil`
874 * Example: `parse_json("[10, {\"a\":false}]")`, returns `{10, {a = false}}`
875 * `minetest.write_json(data[, styled])`: returns a string or `nil` and an error message
876 * Convert a Lua table into a JSON string
877 * styled: Outputs in a human-readable format if this is set, defaults to false
878 * Unserializable things like functions and userdata are saved as null.
879 * **Warning**: JSON is more strict than the Lua table format.
880 1. You can only use strings and positive integers of at least one as keys.
881 2. You can not mix string and integer keys.
882 This is due to the fact that JSON has two distinct array and object values.
883 * Example: `write_json({10, {a = false}})`, returns `"[10, {\"a\": false}]"`
884 * `minetest.serialize(table)`: returns a string
885 * Convert a table containing tables, strings, numbers, booleans and `nil`s
886 into string form readable by `minetest.deserialize`
887 * Example: `serialize({foo='bar'})`, returns `'return { ["foo"] = "bar" }'`
888 * `minetest.deserialize(string)`: returns a table
889 * Convert a string returned by `minetest.deserialize` into a table
890 * `string` is loaded in an empty sandbox environment.
891 * Will load functions, but they cannot access the global environment.
892 * Example: `deserialize('return { ["foo"] = "bar" }')`, returns `{foo='bar'}`
893 * Example: `deserialize('print("foo")')`, returns `nil` (function call fails)
894 * `error:[string "print("foo")"]:1: attempt to call global 'print' (a nil value)`
895 * `minetest.compress(data, method, ...)`: returns `compressed_data`
896 * Compress a string of data.
897 * `method` is a string identifying the compression method to be used.
898 * Supported compression methods:
899 * Deflate (zlib): `"deflate"`
900 * `...` indicates method-specific arguments. Currently defined arguments are:
901 * Deflate: `level` - Compression level, `0`-`9` or `nil`.
902 * `minetest.decompress(compressed_data, method, ...)`: returns data
903 * Decompress a string of data (using ZLib).
904 * See documentation on `minetest.compress()` for supported compression methods.
905 * currently supported.
906 * `...` indicates method-specific arguments. Currently, no methods use this.
907 * `minetest.rgba(red, green, blue[, alpha])`: returns a string
908 * Each argument is a 8 Bit unsigned integer
909 * Returns the ColorString from rgb or rgba values
910 * Example: `minetest.rgba(10, 20, 30, 40)`, returns `"#0A141E28"`
911 * `minetest.encode_base64(string)`: returns string encoded in base64
912 * Encodes a string in base64.
913 * `minetest.decode_base64(string)`: returns string
914 * Decodes a string encoded in base64.
915 * `minetest.gettext(string)` : returns string
916 * look up the translation of a string in the gettext message catalog
917 * `fgettext_ne(string, ...)`
918 * call minetest.gettext(string), replace "$1"..."$9" with the given
919 extra arguments and return the result
920 * `fgettext(string, ...)` : returns string
921 * same as fgettext_ne(), but calls minetest.formspec_escape before returning result
922 * `minetest.pointed_thing_to_face_pos(placer, pointed_thing)`: returns a position
923 * returns the exact position on the surface of a pointed node
924 * `minetest.global_exists(name)`
925 * Checks if a global variable has been set, without triggering a warning.
928 * `minetest.ui.minimap`
929 * Reference to the minimap object. See [`Minimap`](#minimap) class reference for methods.
930 * If client disabled minimap (using enable_minimap setting) this reference will be nil.
932 * Reference to the camera object. See [`Camera`](#camera) class reference for methods.
933 * `minetest.show_formspec(formname, formspec)` : returns true on success
934 * Shows a formspec to the player
935 * `minetest.display_chat_message(message)` returns true on success
936 * Shows a chat message to the current player.
943 An interface to use mod channels on client and server
946 * `leave()`: leave the mod channel.
947 * Client leaves channel `channel_name`.
948 * No more incoming or outgoing messages can be sent to this channel from client mods.
949 * This invalidate all future object usage
950 * Ensure your set mod_channel to nil after that to free Lua resources
951 * `is_writeable()`: returns true if channel is writable and mod can send over it.
952 * `send_all(message)`: Send `message` though the mod channel.
953 * If mod channel is not writable or invalid, message will be dropped.
954 * Message size is limited to 65535 characters by protocol.
957 An interface to manipulate minimap on client UI
960 * `show()`: shows the minimap (if not disabled by server)
961 * `hide()`: hides the minimap
962 * `set_pos(pos)`: sets the minimap position on screen
963 * `get_pos()`: returns the minimap current position
964 * `set_angle(deg)`: sets the minimap angle in degrees
965 * `get_angle()`: returns the current minimap angle in degrees
966 * `set_mode(mode)`: sets the minimap mode (0 to 6)
967 * `get_mode()`: returns the current minimap mode
968 * `set_shape(shape)`: Sets the minimap shape. (0 = square, 1 = round)
969 * `get_shape()`: Gets the minimap shape. (0 = square, 1 = round)
972 An interface to get or set information about the camera and camera-node.
973 Please do not try to access the reference until the camera is initialized, otherwise the reference will be nil.
976 * `set_camera_mode(mode)`
977 * Pass `0` for first-person, `1` for third person, and `2` for third person front
978 * `get_camera_mode()`
979 * Returns 0, 1, or 2 as described above
981 * Returns a table with X, Y, maximum and actual FOV in degrees:
993 * Returns position of camera with view bobbing
995 * Returns eye offset vector
997 * Returns eye direction unit vector
998 * `get_look_vertical()`
999 * Returns pitch in radians
1000 * `get_look_horizontal()`
1001 * Returns yaw in radians
1002 * `get_aspect_ratio()`
1003 * Returns aspect ratio of screen
1006 An interface to retrieve information about the player.
1007 This object will only be available after the client is initialized. Earlier accesses will yield a `nil` value.
1012 * returns current player current position
1014 * returns player speed vector
1018 * returns player name
1019 * `get_wield_index()`
1020 * returns the index of the wielded item
1021 * `get_wielded_item()`
1022 * returns the itemstack the player is holding
1024 * returns true if player is attached
1025 * `is_touching_ground()`
1026 * returns true if player touching ground
1028 * returns true if player is in a liquid (This oscillates so that the player jumps a bit above the surface)
1029 * `is_in_liquid_stable()`
1030 * returns true if player is in a stable liquid (This is more stable and defines the maximum speed of the player)
1031 * `get_liquid_viscosity()`
1032 * returns liquid viscosity (Gets the viscosity of liquid to calculate friction)
1034 * returns true if player is climbing
1035 * `swimming_vertical()`
1036 * returns true if player is swimming in vertical
1037 * `get_physics_override()`
1046 sneak_glitch = boolean,
1051 * `get_override_pos()`
1052 * returns override position
1054 * returns last player position before the current client step
1055 * `get_last_velocity()`
1056 * returns last player speed
1058 * returns the player's breath
1059 * `get_movement_acceleration()`
1060 * returns acceleration of the player in different environments:
1070 * `get_movement_speed()`
1071 * returns player's speed in different environments:
1084 * returns player's movement in different environments:
1088 liquid_fluidity = float,
1089 liquid_sink = float,
1090 liquid_fluidity_smooth = float,
1095 * `get_last_look_horizontal()`:
1096 * returns last look horizontal angle
1097 * `get_last_look_vertical()`:
1098 * returns last look vertical angle
1100 * returns pressed player controls
1117 * `get_armor_groups()`
1118 * returns a table with the armor group ratings
1119 * `hud_add(definition)`
1120 * add a HUD element described by HUD def, returns ID number on success and `nil` on failure.
1121 * See [`HUD definition`](#hud-definition-hud_add-hud_get)
1123 * returns the [`definition`](#hud-definition-hud_add-hud_get) of the HUD with that ID number or `nil`, if non-existent.
1125 * remove the HUD element of the specified id, returns `true` on success
1126 * `hud_change(id, stat, value)`
1127 * change a value of a previously added HUD element
1128 * element `stat` values: `position`, `name`, `scale`, `text`, `number`, `item`, `dir`
1129 * Returns `true` on success, otherwise returns `nil`
1132 An interface to read config files in the format of `minetest.conf`.
1134 It can be created via `Settings(filename)`.
1137 * `get(key)`: returns a value
1138 * `get_bool(key)`: returns a boolean
1140 * `remove(key)`: returns a boolean (`true` for success)
1141 * `get_names()`: returns `{key1,...}`
1142 * `write()`: returns a boolean (`true` for success)
1143 * write changes to file
1144 * `to_table()`: returns `{[key1]=value1,...}`
1147 Node metadata: reference extra data and functionality stored in a node.
1148 Can be obtained via `minetest.get_meta(pos)`.
1151 * `get_string(name)`
1154 * `to_table()`: returns `nil` or a table with keys:
1155 * `fields`: key-value storage
1156 * `inventory`: `{list1 = {}, ...}}`
1160 A raycast on the map. It works with selection boxes.
1161 Can be used as an iterator in a for loop as:
1163 local ray = Raycast(...)
1164 for pointed_thing in ray do
1168 The map is loaded as the ray advances. If the map is modified after the
1169 `Raycast` is created, the changes may or may not have an effect on the object.
1171 It can be created via `Raycast(pos1, pos2, objects, liquids)` or
1172 `minetest.raycast(pos1, pos2, objects, liquids)` where:
1174 * `pos1`: start of the ray
1175 * `pos2`: end of the ray
1176 * `objects`: if false, only nodes will be returned. Default is true.
1177 * `liquids`: if false, liquid nodes won't be returned. Default is false.
1181 * `next()`: returns a `pointed_thing` with exact pointing location
1182 * Returns the next thing pointed by the ray or nil.
1186 * `minetest.get_node_def(nodename)`
1187 * Returns [node definition](#node-definition) table of `nodename`
1188 * `minetest.get_item_def(itemstring)`
1189 * Returns item definition table of `itemstring`
1191 #### Node Definition
1195 has_on_construct = bool, -- Whether the node has the on_construct callback defined
1196 has_on_destruct = bool, -- Whether the node has the on_destruct callback defined
1197 has_after_destruct = bool, -- Whether the node has the after_destruct callback defined
1198 name = string, -- The name of the node e.g. "air", "default:dirt"
1199 groups = table, -- The groups of the node
1200 paramtype = string, -- Paramtype of the node
1201 paramtype2 = string, -- ParamType2 of the node
1202 drawtype = string, -- Drawtype of the node
1203 mesh = <string>, -- Mesh name if existant
1204 minimap_color = <Color>, -- Color of node on minimap *May not exist*
1205 visual_scale = number, -- Visual scale of node
1206 alpha = number, -- Alpha of the node. Only used for liquids
1207 color = <Color>, -- Color of node *May not exist*
1208 palette_name = <string>, -- Filename of palette *May not exist*
1209 palette = <{ -- List of colors
1213 waving = number, -- 0 of not waving, 1 if waving
1214 connect_sides = number, -- Used for connected nodes
1215 connects_to = { -- List of nodes to connect to
1219 post_effect_color = Color, -- Color overlayed on the screen when the player is in the node
1220 leveled = number, -- Max level for node
1221 sunlight_propogates = bool, -- Whether light passes through the block
1222 light_source = number, -- Light emitted by the block
1223 is_ground_content = bool, -- Whether caves should cut through the node
1224 walkable = bool, -- Whether the player collides with the node
1225 pointable = bool, -- Whether the player can select the node
1226 diggable = bool, -- Whether the player can dig the node
1227 climbable = bool, -- Whether the player can climb up the node
1228 buildable_to = bool, -- Whether the player can replace the node by placing a node on it
1229 rightclickable = bool, -- Whether the player can place nodes pointing at this node
1230 damage_per_second = number, -- HP of damage per second when the player is in the node
1231 liquid_type = <string>, -- A string containing "none", "flowing", or "source" *May not exist*
1232 liquid_alternative_flowing = <string>, -- Alternative node for liquid *May not exist*
1233 liquid_alternative_source = <string>, -- Alternative node for liquid *May not exist*
1234 liquid_viscosity = <number>, -- How fast the liquid flows *May not exist*
1235 liquid_renewable = <boolean>, -- Whether the liquid makes an infinite source *May not exist*
1236 liquid_range = <number>, -- How far the liquid flows *May not exist*
1237 drowning = bool, -- Whether the player will drown in the node
1238 floodable = bool, -- Whether nodes will be replaced by liquids (flooded)
1239 node_box = table, -- Nodebox to draw the node with
1240 collision_box = table, -- Nodebox to set the collision area
1241 selection_box = table, -- Nodebox to set the area selected by the player
1242 sounds = { -- Table of sounds that the block makes
1243 sound_footstep = SimpleSoundSpec,
1244 sound_dig = SimpleSoundSpec,
1245 sound_dug = SimpleSoundSpec
1247 legacy_facedir_simple = bool, -- Whether to use old facedir
1248 legacy_wallmounted = bool -- Whether to use old wallmounted
1252 #### Item Definition
1256 name = string, -- Name of the item e.g. "default:stone"
1257 description = string, -- Description of the item e.g. "Stone"
1258 type = string, -- Item type: "none", "node", "craftitem", "tool"
1259 inventory_image = string, -- Image in the inventory
1260 wield_image = string, -- Image in wieldmesh
1261 palette_image = string, -- Image for palette
1262 color = Color, -- Color for item
1263 wield_scale = Vector, -- Wieldmesh scale
1264 stack_max = number, -- Number of items stackable together
1265 usable = bool, -- Has on_use callback defined
1266 liquids_pointable = bool, -- Whether you can point at liquids with the item
1267 tool_capabilities = <table>, -- If the item is a tool, tool capabilities of the item
1268 groups = table, -- Groups of the item
1269 sound_place = SimpleSoundSpec, -- Sound played when placed
1270 sound_place_failed = SimpleSoundSpec, -- Sound played when placement failed
1271 node_placement_prediction = string -- Node placed in client until server catches up
1276 ### Chat command definition (`register_chatcommand`)
1279 params = "<name> <privilege>", -- Short parameter description
1280 description = "Remove privilege from player", -- Full description
1281 func = function(param), -- Called when command is run.
1282 -- Returns boolean success and text output.
1287 address = "minetest.example.org", -- The domain name/IP address of a remote server or "" for a local server.
1288 ip = "203.0.113.156", -- The IP address of the server.
1289 port = 30000, -- The port the client is connected to.
1290 protocol_version = 30 -- Will not be accurate at start up as the client might not be connected to the server yet, in that case it will be 0.
1294 ### HUD Definition (`hud_add`, `hud_get`)
1297 hud_elem_type = "image", -- see HUD element types, default "text"
1298 -- ^ type of HUD element, can be either of "image", "text", "statbar", or "inventory"
1299 position = {x=0.5, y=0.5},
1300 -- ^ Left corner position of element, default `{x=0,y=0}`.
1301 name = "<name>", -- default ""
1302 scale = {x=2, y=2}, -- default {x=0,y=0}
1303 text = "<text>", -- default ""
1304 number = 2, -- default 0
1305 item = 3, -- default 0
1306 -- ^ Selected item in inventory. 0 for no item selected.
1307 direction = 0, -- default 0
1308 -- ^ Direction: 0: left-right, 1: right-left, 2: top-bottom, 3: bottom-top
1309 alignment = {x=0, y=0}, -- default {x=0, y=0}
1310 -- ^ See "HUD Element Types"
1311 offset = {x=0, y=0}, -- default {x=0, y=0}
1312 -- ^ See "HUD Element Types"
1313 size = { x=100, y=100 }, -- default {x=0, y=0}
1314 -- ^ Size of element in pixels
1320 Most text can contain escape sequences, that can for example color the text.
1321 There are a few exceptions: tab headers, dropdowns and vertical labels can't.
1322 The following functions provide escape sequences:
1323 * `minetest.get_color_escape_sequence(color)`:
1324 * `color` is a [ColorString](#colorstring)
1325 * The escape sequence sets the text color to `color`
1326 * `minetest.colorize(color, message)`:
1328 `minetest.get_color_escape_sequence(color) ..
1330 minetest.get_color_escape_sequence("#ffffff")`
1331 * `minetest.get_background_escape_sequence(color)`
1332 * `color` is a [ColorString](#colorstring)
1333 * The escape sequence sets the background of the whole text element to
1334 `color`. Only defined for item descriptions and tooltips.
1335 * `minetest.strip_foreground_colors(str)`
1336 * Removes foreground colors added by `get_color_escape_sequence`.
1337 * `minetest.strip_background_colors(str)`
1338 * Removes background colors added by `get_background_escape_sequence`.
1339 * `minetest.strip_colors(str)`
1340 * Removes all color escape sequences.
1344 `#RGB` defines a color in hexadecimal format.
1346 `#RGBA` defines a color in hexadecimal format and alpha channel.
1348 `#RRGGBB` defines a color in hexadecimal format.
1350 `#RRGGBBAA` defines a color in hexadecimal format and alpha channel.
1352 Named colors are also supported and are equivalent to
1353 [CSS Color Module Level 4](http://dev.w3.org/csswg/css-color/#named-colors).
1354 To specify the value of the alpha channel, append `#A` or `#AA` to the end of
1355 the color name (e.g. `colorname#08`).
1359 `{a = alpha, r = red, g = green, b = blue}` defines an ARGB8 color.
1363 The position field is used for all element types.
1365 To account for differing resolutions, the position coordinates are the percentage
1366 of the screen, ranging in value from `0` to `1`.
1368 The name field is not yet used, but should contain a description of what the
1369 HUD element represents. The direction field is the direction in which something
1372 `0` draws from left to right, `1` draws from right to left, `2` draws from
1373 top to bottom, and `3` draws from bottom to top.
1375 The `alignment` field specifies how the item will be aligned. It ranges from `-1` to `1`,
1376 with `0` being the center, `-1` is moved to the left/up, and `1` is to the right/down.
1377 Fractional values can be used.
1379 The `offset` field specifies a pixel offset from the position. Contrary to position,
1380 the offset is not scaled to screen size. This allows for some precisely-positioned
1383 **Note**: `offset` _will_ adapt to screen DPI as well as user defined scaling factor!
1385 Below are the specific uses for fields in each type; fields not listed for that type are ignored.
1387 **Note**: Future revisions to the HUD API may be incompatible; the HUD API is still
1388 in the experimental stages.
1391 Displays an image on the HUD.
1393 * `scale`: The scale of the image, with 1 being the original texture size.
1394 Only the X coordinate scale is used (positive values).
1395 Negative values represent that percentage of the screen it
1396 should take; e.g. `x=-100` means 100% (width).
1397 * `text`: The name of the texture that is displayed.
1398 * `alignment`: The alignment of the image.
1399 * `offset`: offset in pixels from position.
1402 Displays text on the HUD.
1404 * `scale`: Defines the bounding rectangle of the text.
1405 A value such as `{x=100, y=100}` should work.
1406 * `text`: The text to be displayed in the HUD element.
1407 * `number`: An integer containing the RGB value of the color used to draw the text.
1408 Specify `0xFFFFFF` for white text, `0xFF0000` for red, and so on.
1409 * `alignment`: The alignment of the text.
1410 * `offset`: offset in pixels from position.
1413 Displays a horizontal bar made up of half-images.
1415 * `text`: The name of the texture that is used.
1416 * `number`: The number of half-textures that are displayed.
1417 If odd, will end with a vertically center-split texture.
1419 * `offset`: offset in pixels from position.
1420 * `size`: If used, will force full-image size to this value (override texture pack image size)
1423 * `text`: The name of the inventory list to be displayed.
1424 * `number`: Number of items in the inventory to be displayed.
1425 * `item`: Position of item that is selected.
1427 * `offset`: offset in pixels from position.
1431 Displays distance to selected world position.
1433 * `name`: The name of the waypoint.
1434 * `text`: Distance suffix. Can be blank.
1435 * `precision`: Waypoint precision, integer >= 0. Defaults to 10.
1436 If set to 0, distance is not shown. Shown value is `floor(distance*precision)/precision`.
1437 When the precision is an integer multiple of 10, there will be `log_10(precision)` digits after the decimal point.
1438 `precision = 1000`, for example, will show 3 decimal places (eg: `0.999`).
1439 `precision = 2` will show multiples of `0.5`; precision = 5 will show multiples of `0.2` and so on:
1440 `precision = n` will show multiples of `1/n`
1441 * `number:` An integer containing the RGB value of the color used to draw the
1443 * `world_pos`: World position of the waypoint.
1444 * `offset`: offset in pixels from position.
1445 * `alignment`: The alignment of the waypoint.
1447 ### `image_waypoint`
1449 Same as `image`, but does not accept a `position`; the position is instead determined by `world_pos`, the world position of the waypoint.
1451 * `scale`: The scale of the image, with 1 being the original texture size.
1452 Only the X coordinate scale is used (positive values).
1453 Negative values represent that percentage of the screen it
1454 should take; e.g. `x=-100` means 100% (width).
1455 * `text`: The name of the texture that is displayed.
1456 * `alignment`: The alignment of the image.
1457 * `world_pos`: World position of the waypoint.
1458 * `offset`: offset in pixels from position.
1460 ### Particle definition (`add_particle`)
1463 pos = {x=0, y=0, z=0},
1464 velocity = {x=0, y=0, z=0},
1465 acceleration = {x=0, y=0, z=0},
1466 -- ^ Spawn particle at pos with velocity and acceleration
1468 -- ^ Disappears after expirationtime seconds
1470 collisiondetection = false,
1471 -- ^ collisiondetection: if true collides with physical objects
1472 collision_removal = false,
1473 -- ^ collision_removal: if true then particle is removed when it collides,
1474 -- ^ requires collisiondetection = true to have any effect
1476 -- ^ vertical: if true faces player using y axis only
1477 texture = "image.png",
1478 -- ^ Uses texture (string)
1479 animation = {Tile Animation definition},
1480 -- ^ optional, specifies how to animate the particle texture
1482 -- ^ optional, specify particle self-luminescence in darkness
1485 ### `ParticleSpawner` definition (`add_particlespawner`)
1490 -- ^ If time is 0 has infinite lifespan and spawns the amount on a per-second base
1491 minpos = {x=0, y=0, z=0},
1492 maxpos = {x=0, y=0, z=0},
1493 minvel = {x=0, y=0, z=0},
1494 maxvel = {x=0, y=0, z=0},
1495 minacc = {x=0, y=0, z=0},
1496 maxacc = {x=0, y=0, z=0},
1501 -- ^ The particle's properties are random values in between the bounds:
1502 -- ^ minpos/maxpos, minvel/maxvel (velocity), minacc/maxacc (acceleration),
1503 -- ^ minsize/maxsize, minexptime/maxexptime (expirationtime)
1504 collisiondetection = false,
1505 -- ^ collisiondetection: if true uses collision detection
1506 collision_removal = false,
1507 -- ^ collision_removal: if true then particle is removed when it collides,
1508 -- ^ requires collisiondetection = true to have any effect
1510 -- ^ vertical: if true faces player using y axis only
1511 texture = "image.png",
1512 -- ^ Uses texture (string)