1 Minetest Lua Client Modding API Reference 5.1.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 in a world, 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)
47 * Linux: `<build directory>`
48 * Windows: `<build directory>`
50 * Linux: `<build directory>`
51 * Windows: `<build directory>`
52 * `RUN_IN_PLACE=0`: (Linux release)
54 * Linux: `/usr/share/minetest`
55 * Windows: `<install directory>/minetest-0.4.x`
57 * Linux: `$HOME/.minetest`
58 * Windows: `C:/users/<user>/AppData/minetest` (maybe)
64 * `$path_share/clientmods/`
65 * `$path_user/clientmods/` (User-installed mods)
67 In a run-in-place version (e.g. the distributed windows version):
69 * `minetest-0.4.x/clientmods/` (User-installed mods)
71 On an installed version on Linux:
73 * `/usr/share/minetest/clientmods/`
74 * `$HOME/.minetest/clientmods/` (User-installed mods)
78 **NOTE: Not implemented yet.**
80 Mods can be put in a subdirectory, if the parent directory, which otherwise
81 should be a mod, contains a file named `modpack.conf`.
82 The file is a key-value store of modpack details.
84 * `name`: The modpack name.
85 * `description`: Description of mod to be shown in the Mods tab of the main
88 Mod directory structure
89 ------------------------
98 The location of this directory.
101 List of mods that have to be loaded before loading this mod.
103 A single line contains a single modname.
105 Optional dependencies can be defined by appending a question mark
106 to a single modname. Their meaning is that if the specified mod
107 is missing, that does not prevent this mod from being loaded.
110 The main Lua script. Running this script should register everything it
111 wants to register. Subsequent execution depends on minetest calling the
112 registered callbacks.
114 `minetest.setting_get(name)` and `minetest.setting_getbool(name)` can be used
115 to read custom or existing settings at load time, if necessary.
118 Media files (sounds) that will be transferred to the
119 client and will be available for use by the mod.
121 Naming convention for registered textual names
122 ----------------------------------------------
123 Registered names should generally be in this format:
125 "modname:<whatever>" (<whatever> can have characters a-zA-Z0-9_)
127 This is to prevent conflicting names from corrupting maps and is
128 enforced by the mod loader.
131 In the mod `experimental`, there is the ideal item/node/entity name `tnt`.
132 So the name should be `experimental:tnt`.
134 Enforcement can be overridden by prefixing the name with `:`. This can
135 be used for overriding the registrations of some other mod.
137 Example: Any mod can redefine `experimental:tnt` by using the name
142 (also that mod is required to have `experimental` as a dependency)
144 The `:` prefix can also be used for maintaining backwards compatibility.
148 **NOTE: max_hear_distance and connecting to objects is not implemented.**
150 Only Ogg Vorbis files are supported.
152 For positional playing of sounds, only single-channel (mono) files are
153 supported. Otherwise OpenAL will play them non-positionally.
155 Mods should generally prefix their sounds with `modname_`, e.g. given
156 the mod name "`foomod`", a sound could be called:
160 Sounds are referred to by their name with a dot, a single digit and the
161 file extension stripped out. When a sound is played, the actual sound file
162 is chosen randomly from the matching sounds.
164 When playing the sound `foomod_foosound`, the sound is chosen randomly
165 from the available ones of the following files:
167 * `foomod_foosound.ogg`
168 * `foomod_foosound.0.ogg`
169 * `foomod_foosound.1.ogg`
171 * `foomod_foosound.9.ogg`
173 Examples of sound parameter tables:
177 gain = 1.0, -- default
179 -- Play locationless, looped
181 gain = 1.0, -- default
184 -- Play in a location
186 pos = {x = 1, y = 2, z = 3},
187 gain = 1.0, -- default
188 max_hear_distance = 32, -- default, uses an euclidean metric
190 -- Play connected to an object, looped
192 object = <an ObjectRef>,
193 gain = 1.0, -- default
194 max_hear_distance = 32, -- default, uses an euclidean metric
198 Looped sounds must either be connected to an object or played locationless.
202 * e.g. `"default_place_node"`
204 * e.g. `{name = "default_place_node"}`
205 * e.g. `{name = "default_place_node", gain = 1.0}`
207 Representations of simple things
208 --------------------------------
212 {x=num, y=num, z=num}
214 For helper functions see "Vector helpers".
218 * `{type="node", under=pos, above=pos}`
219 * `{type="object", id=ObjectID}`
221 Flag Specifier Format
222 ---------------------
223 Flags using the standardized flag specifier format can be specified in either of
224 two ways, by string or table.
226 The string format is a comma-delimited set of flag names; whitespace and
227 unrecognized flag fields are ignored. Specifying a flag in the string sets the
228 flag, and specifying a flag prefixed by the string `"no"` explicitly
229 clears the flag from whatever the default may be.
231 In addition to the standard string flag format, the schematic flags field can
232 also be a table of flag names to boolean values representing whether or not the
233 flag is set. Additionally, if a field with the flag name prefixed with `"no"`
234 is present, mapped to a boolean of any value, the specified flag is unset.
236 E.g. A flag field of value
238 {place_center_x = true, place_center_y=false, place_center_z=true}
242 {place_center_x = true, noplace_center_y=true, place_center_z=true}
244 which is equivalent to
246 "place_center_x, noplace_center_y, place_center_z"
250 "place_center_x, place_center_z"
252 since, by default, no schematic attributes are set.
256 Formspec defines a menu. It is a string, with a somewhat strange format.
258 Spaces and newlines can be inserted between the blocks, as is used in the
266 list[context;main;0,0;8,4;]
267 list[current_player;main;0,5;8,4;]
272 list[context;fuel;2,3;1,1;]
273 list[context;src;2,1;1,1;]
274 list[context;dst;5,1;2,2;]
275 list[current_player;main;0,5;8,4;]
277 #### Minecraft-like player inventory
280 image[1,0.6;1,2;player.png]
281 list[current_player;main;0,3.5;8,4;]
282 list[current_player;craft;3,0;3,3;]
283 list[current_player;craftpreview;7,1;1,1;]
287 #### `size[<W>,<H>,<fixed_size>]`
288 * Define the size of the menu in inventory slots
289 * `fixed_size`: `true`/`false` (optional)
290 * deprecated: `invsize[<W>,<H>;]`
292 #### `container[<X>,<Y>]`
293 * Start of a container block, moves all physical elements in the container by (X, Y)
294 * Must have matching container_end
295 * Containers can be nested, in which case the offsets are added
296 (child containers are relative to parent containers)
298 #### `container_end[]`
299 * End of a container, following elements are no longer relative to this container
301 #### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]`
302 * Show an inventory list
304 #### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]`
305 * Show an inventory list
307 #### `listring[<inventory location>;<list name>]`
308 * Allows to create a ring of inventory lists
309 * Shift-clicking on items in one element of the ring
310 will send them to the next inventory list inside the ring
311 * The first occurrence of an element inside the ring will
312 determine the inventory where items will be sent to
315 * Shorthand for doing `listring[<inventory location>;<list name>]`
316 for the last two inventory lists added by list[...]
318 #### `listcolors[<slot_bg_normal>;<slot_bg_hover>]`
319 * Sets background color of slots as `ColorString`
320 * Sets background color of slots on mouse hovering
322 #### `listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>]`
323 * Sets background color of slots as `ColorString`
324 * Sets background color of slots on mouse hovering
325 * Sets color of slots border
327 #### `listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>;<tooltip_bgcolor>;<tooltip_fontcolor>]`
328 * Sets background color of slots as `ColorString`
329 * Sets background color of slots on mouse hovering
330 * Sets color of slots border
331 * Sets default background color of tooltips
332 * Sets default font color of tooltips
334 #### `tooltip[<gui_element_name>;<tooltip_text>;<bgcolor>,<fontcolor>]`
335 * Adds tooltip for an element
336 * `<bgcolor>` tooltip background color as `ColorString` (optional)
337 * `<fontcolor>` tooltip font color as `ColorString` (optional)
339 #### `image[<X>,<Y>;<W>,<H>;<texture name>]`
341 * Position and size units are inventory slots
343 #### `item_image[<X>,<Y>;<W>,<H>;<item name>]`
344 * Show an inventory image of registered item/node
345 * Position and size units are inventory slots
347 #### `bgcolor[<color>;<fullscreen>]`
348 * Sets background color of formspec as `ColorString`
349 * If `true`, the background color is drawn fullscreen (does not effect the size of the formspec)
351 #### `background[<X>,<Y>;<W>,<H>;<texture name>]`
352 * Use a background. Inventory rectangles are not drawn then.
353 * Position and size units are inventory slots
354 * Example for formspec 8x4 in 16x resolution: image shall be sized
355 8 times 16px times 4 times 16px.
357 #### `background[<X>,<Y>;<W>,<H>;<texture name>;<auto_clip>]`
358 * Use a background. Inventory rectangles are not drawn then.
359 * Position and size units are inventory slots
360 * Example for formspec 8x4 in 16x resolution:
361 image shall be sized 8 times 16px times 4 times 16px
362 * If `true` the background is clipped to formspec size
363 (`x` and `y` are used as offset values, `w` and `h` are ignored)
365 #### `pwdfield[<X>,<Y>;<W>,<H>;<name>;<label>]`
366 * Textual password style field; will be sent to server when a button is clicked
367 * When enter is pressed in field, fields.key_enter_field will be sent with the name
369 * `x` and `y` position the field relative to the top left of the menu
370 * `w` and `h` are the size of the field
371 * Fields are a set height, but will be vertically centred on `h`
372 * Position and size units are inventory slots
373 * `name` is the name of the field as returned in fields to `on_receive_fields`
374 * `label`, if not blank, will be text printed on the top left above the field
375 * See field_close_on_enter to stop enter closing the formspec
377 #### `field[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`
378 * Textual field; will be sent to server when a button is clicked
379 * When enter is pressed in field, fields.key_enter_field will be sent with the name
381 * `x` and `y` position the field relative to the top left of the menu
382 * `w` and `h` are the size of the field
383 * Fields are a set height, but will be vertically centred on `h`
384 * Position and size units are inventory slots
385 * `name` is the name of the field as returned in fields to `on_receive_fields`
386 * `label`, if not blank, will be text printed on the top left above the field
387 * `default` is the default value of the field
388 * `default` may contain variable references such as `${text}'` which
389 will fill the value from the metadata value `text`
390 * **Note**: no extra text or more than a single variable is supported ATM.
391 * See field_close_on_enter to stop enter closing the formspec
393 #### `field[<name>;<label>;<default>]`
394 * As above, but without position/size units
395 * When enter is pressed in field, fields.key_enter_field will be sent with the name
397 * Special field for creating simple forms, such as sign text input
398 * Must be used without a `size[]` element
399 * A "Proceed" button will be added automatically
400 * See field_close_on_enter to stop enter closing the formspec
402 #### `field_close_on_enter[<name>;<close_on_enter>]`
403 * <name> is the name of the field
404 * if <close_on_enter> is false, pressing enter in the field will submit the form but not close it
405 * defaults to true when not specified (ie: no tag for a field)
407 #### `textarea[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`
408 * Same as fields above, but with multi-line input
410 #### `label[<X>,<Y>;<label>]`
411 * `x` and `y` work as per field
412 * `label` is the text on the label
413 * Position and size units are inventory slots
415 #### `vertlabel[<X>,<Y>;<label>]`
416 * Textual label drawn vertically
417 * `x` and `y` work as per field
418 * `label` is the text on the label
419 * Position and size units are inventory slots
421 #### `button[<X>,<Y>;<W>,<H>;<name>;<label>]`
422 * Clickable button. When clicked, fields will be sent.
423 * `x`, `y` and `name` work as per field
424 * `w` and `h` are the size of the button
425 * Fixed button height. It will be vertically centred on `h`
426 * `label` is the text on the button
427 * Position and size units are inventory slots
429 #### `image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]`
430 * `x`, `y`, `w`, `h`, and `name` work as per button
431 * `texture name` is the filename of an image
432 * Position and size units are inventory slots
434 #### `image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>;<noclip>;<drawborder>;<pressed texture name>]`
435 * `x`, `y`, `w`, `h`, and `name` work as per button
436 * `texture name` is the filename of an image
437 * Position and size units are inventory slots
438 * `noclip=true` means the image button doesn't need to be within specified formsize
439 * `drawborder`: draw button border or not
440 * `pressed texture name` is the filename of an image on pressed state
442 #### `item_image_button[<X>,<Y>;<W>,<H>;<item name>;<name>;<label>]`
443 * `x`, `y`, `w`, `h`, `name` and `label` work as per button
444 * `item name` is the registered name of an item/node,
445 tooltip will be made out of its description
446 to override it use tooltip element
447 * Position and size units are inventory slots
449 #### `button_exit[<X>,<Y>;<W>,<H>;<name>;<label>]`
450 * When clicked, fields will be sent and the form will quit.
452 #### `image_button_exit[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]`
453 * When clicked, fields will be sent and the form will quit.
455 #### `textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>]`
456 * Scrollable item list showing arbitrary text elements
457 * `x` and `y` position the itemlist relative to the top left of the menu
458 * `w` and `h` are the size of the itemlist
459 * `name` fieldname sent to server on doubleclick value is current selected element
460 * `listelements` can be prepended by #color in hexadecimal format RRGGBB (only),
461 * if you want a listelement to start with "#" write "##".
463 #### `textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>;<selected idx>;<transparent>]`
464 * Scrollable itemlist showing arbitrary text elements
465 * `x` and `y` position the item list relative to the top left of the menu
466 * `w` and `h` are the size of the item list
467 * `name` fieldname sent to server on doubleclick value is current selected element
468 * `listelements` can be prepended by #RRGGBB (only) in hexadecimal format
469 * if you want a listelement to start with "#" write "##"
470 * Index to be selected within textlist
471 * `true`/`false`: draw transparent background
472 * See also `minetest.explode_textlist_event` (main menu: `engine.explode_textlist_event`)
474 #### `tabheader[<X>,<Y>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]`
475 * Show a tab**header** at specific position (ignores formsize)
476 * `x` and `y` position the itemlist relative to the top left of the menu
477 * `name` fieldname data is transferred to Lua
478 * `caption 1`...: name shown on top of tab
479 * `current_tab`: index of selected tab 1...
480 * `transparent` (optional): show transparent
481 * `draw_border` (optional): draw border
483 #### `box[<X>,<Y>;<W>,<H>;<color>]`
484 * Simple colored semitransparent box
485 * `x` and `y` position the box relative to the top left of the menu
486 * `w` and `h` are the size of box
487 * `color` is color specified as a `ColorString`
489 #### `dropdown[<X>,<Y>;<W>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>]`
490 * Show a dropdown field
491 * **Important note**: There are two different operation modes:
492 1. handle directly on change (only changed dropdown is submitted)
493 2. read the value on pressing a button (all dropdown values are available)
494 * `x` and `y` position of dropdown
496 * Fieldname data is transferred to Lua
497 * Items to be shown in dropdown
498 * Index of currently selected dropdown item
500 #### `checkbox[<X>,<Y>;<name>;<label>;<selected>]`
502 * `x` and `y`: position of checkbox
503 * `name` fieldname data is transferred to Lua
504 * `label` to be shown left of checkbox
505 * `selected` (optional): `true`/`false`
507 #### `scrollbar[<X>,<Y>;<W>,<H>;<orientation>;<name>;<value>]`
509 * There are two ways to use it:
510 1. handle the changed event (only changed scrollbar is available)
511 2. read the value on pressing a button (all scrollbars are available)
512 * `x` and `y`: position of trackbar
513 * `w` and `h`: width and height
514 * `orientation`: `vertical`/`horizontal`
515 * Fieldname data is transferred to Lua
516 * Value this trackbar is set to (`0`-`1000`)
517 * See also `minetest.explode_scrollbar_event` (main menu: `engine.explode_scrollbar_event`)
519 #### `table[<X>,<Y>;<W>,<H>;<name>;<cell 1>,<cell 2>,...,<cell n>;<selected idx>]`
520 * Show scrollable table using options defined by the previous `tableoptions[]`
521 * Displays cells as defined by the previous `tablecolumns[]`
522 * `x` and `y`: position the itemlist relative to the top left of the menu
523 * `w` and `h` are the size of the itemlist
524 * `name`: fieldname sent to server on row select or doubleclick
525 * `cell 1`...`cell n`: cell contents given in row-major order
526 * `selected idx`: index of row to be selected within table (first row = `1`)
527 * See also `minetest.explode_table_event` (main menu: `engine.explode_table_event`)
529 #### `tableoptions[<opt 1>;<opt 2>;...]`
530 * Sets options for `table[]`
532 * default text color (`ColorString`), defaults to `#FFFFFF`
533 * `background=#RRGGBB`
534 * table background color (`ColorString`), defaults to `#000000`
535 * `border=<true/false>`
536 * should the table be drawn with a border? (default: `true`)
537 * `highlight=#RRGGBB`
538 * highlight background color (`ColorString`), defaults to `#466432`
539 * `highlight_text=#RRGGBB`
540 * highlight text color (`ColorString`), defaults to `#FFFFFF`
541 * `opendepth=<value>`
542 * all subtrees up to `depth < value` are open (default value = `0`)
543 * only useful when there is a column of type "tree"
545 #### `tablecolumns[<type 1>,<opt 1a>,<opt 1b>,...;<type 2>,<opt 2a>,<opt 2b>;...]`
546 * Sets columns for `table[]`
547 * Types: `text`, `image`, `color`, `indent`, `tree`
548 * `text`: show cell contents as text
549 * `image`: cell contents are an image index, use column options to define images
550 * `color`: cell contents are a ColorString and define color of following cell
551 * `indent`: cell contents are a number and define indentation of following cell
552 * `tree`: same as indent, but user can open and close subtrees (treeview-like)
555 * for `text` and `image`: content alignment within cells.
556 Available values: `left` (default), `center`, `right`, `inline`
558 * for `text` and `image`: minimum width in em (default: `0`)
559 * for `indent` and `tree`: indent width in em (default: `1.5`)
560 * `padding=<value>`: padding left of the column, in em (default `0.5`).
561 Exception: defaults to 0 for indent columns
562 * `tooltip=<value>`: tooltip text (default: empty)
563 * `image` column options:
564 * `0=<value>` sets image for image index 0
565 * `1=<value>` sets image for image index 1
566 * `2=<value>` sets image for image index 2
567 * and so on; defined indices need not be contiguous empty or
568 non-numeric cells are treated as `0`.
569 * `color` column options:
570 * `span=<value>`: number of following columns to affect (default: infinite)
572 **Note**: do _not_ use a element name starting with `key_`; those names are reserved to
573 pass key press events to formspec!
577 * `vector.new(a[, b, c])`: returns a vector:
578 * A copy of `a` if `a` is a vector.
579 * `{x = a, y = b, z = c}`, if all `a, b, c` are defined
580 * `vector.direction(p1, p2)`: returns a vector
581 * `vector.distance(p1, p2)`: returns a number
582 * `vector.length(v)`: returns a number
583 * `vector.normalize(v)`: returns a vector
584 * `vector.floor(v)`: returns a vector, each dimension rounded down
585 * `vector.round(v)`: returns a vector, each dimension rounded to nearest int
586 * `vector.apply(v, func)`: returns a vector
587 * `vector.equals(v1, v2)`: returns a boolean
589 For the following functions `x` can be either a vector or a number:
591 * `vector.add(v, x)`: returns a vector
592 * `vector.subtract(v, x)`: returns a vector
593 * `vector.multiply(v, x)`: returns a scaled vector or Schur product
594 * `vector.divide(v, x)`: returns a scaled vector or Schur quotient
598 * `dump2(obj, name="_", dumped={})`
599 * Return object serialized as a string, handles reference loops
600 * `dump(obj, dumped={})`
601 * Return object serialized as a string
603 * Get the hypotenuse of a triangle with legs x and y.
604 Useful for distance calculation.
605 * `math.sign(x, tolerance)`
606 * Get the sign of a number.
607 Optional: Also returns `0` when the absolute value is within the tolerance (default: `0`)
608 * `string.split(str, separator=",", include_empty=false, max_splits=-1, sep_is_pattern=false)`
609 * If `max_splits` is negative, do not limit splits.
610 * `sep_is_pattern` specifies if separator is a plain string or a pattern (regex).
611 * e.g. `string:split("a,b", ",") == {"a","b"}`
613 * e.g. `string.trim("\n \t\tfoo bar\t ") == "foo bar"`
614 * `minetest.wrap_text(str, limit)`: returns a string
615 * Adds new lines to the string to keep it within the specified character limit
616 * limit: Maximal amount of characters in one line
617 * `minetest.pos_to_string({x=X,y=Y,z=Z}, decimal_places))`: returns string `"(X,Y,Z)"`
618 * Convert position to a printable string
619 Optional: 'decimal_places' will round the x, y and z of the pos to the given decimal place.
620 * `minetest.string_to_pos(string)`: returns a position
621 * Same but in reverse. Returns `nil` if the string can't be parsed to a position.
622 * `minetest.string_to_area("(X1, Y1, Z1) (X2, Y2, Z2)")`: returns two positions
623 * Converts a string representing an area box into two positions
624 * `minetest.is_yes(arg)`
625 * returns whether `arg` can be interpreted as yes
626 * `minetest.is_nan(arg)`
627 * returns true true when the passed number represents NaN.
628 * `table.copy(table)`: returns a table
629 * returns a deep copy of `table`
631 Minetest namespace reference
632 ------------------------------
636 * `minetest.get_current_modname()`: returns the currently loading mod's name, when we are loading a mod
637 * `minetest.get_language()`: returns the currently set gettext language.
638 * `minetest.get_version()`: returns a table containing components of the
639 engine version. Components:
640 * `project`: Name of the project, eg, "Minetest"
641 * `string`: Simple version, eg, "1.2.3-dev"
642 * `hash`: Full git version (only set if available), eg, "1.2.3-dev-01234567-dirty"
643 Use this for informational purposes only. The information in the returned
644 table does not represent the capabilities of the engine, nor is it
645 reliable or verifiable. Compatible forks will have a different name and
646 version entirely. To check for the presence of engine features, test
647 whether the functions exported by the wanted features exist. For example:
648 `if minetest.check_for_falling then ... end`.
649 * `minetest.sha1(data, [raw])`: returns the sha1 hash of data
650 * `data`: string of data to hash
651 * `raw`: return raw bytes instead of hex digits, default: false
654 * `minetest.debug(...)`
655 * Equivalent to `minetest.log(table.concat({...}, "\t"))`
656 * `minetest.log([level,] text)`
657 * `level` is one of `"none"`, `"error"`, `"warning"`, `"action"`,
658 `"info"`, or `"verbose"`. Default is `"none"`.
660 ### Global callback registration functions
661 Call these functions only at load time!
663 * `minetest.register_globalstep(function(dtime))`
664 * Called every client environment step, usually interval of 0.1s
665 * `minetest.register_on_mods_loaded(function())`
666 * Called just after mods have finished loading.
667 * `minetest.register_on_shutdown(function())`
668 * Called before client shutdown
669 * **Warning**: If the client terminates abnormally (i.e. crashes), the registered
670 callbacks **will likely not be run**. Data should be saved at
671 semi-frequent intervals as well as on server shutdown.
672 * `minetest.register_on_receiving_chat_message(function(message))`
673 * Called always when a client receive a message
674 * Return `true` to mark the message as handled, which means that it will not be shown to chat
675 * `minetest.register_on_sending_chat_message(function(message))`
676 * Called always when a client send a message from chat
677 * Return `true` to mark the message as handled, which means that it will not be sent to server
678 * `minetest.register_chatcommand(cmd, chatcommand definition)`
679 * Adds definition to minetest.registered_chatcommands
680 * `minetest.unregister_chatcommand(name)`
681 * Unregisters a chatcommands registered with register_chatcommand.
682 * `minetest.register_on_death(function())`
683 * Called when the local player dies
684 * `minetest.register_on_hp_modification(function(hp))`
685 * Called when server modified player's HP
686 * `minetest.register_on_damage_taken(function(hp))`
687 * Called when the local player take damages
688 * `minetest.register_on_formspec_input(function(formname, fields))`
689 * Called when a button is pressed in the local player's inventory form
690 * Newest functions are called first
691 * If function returns `true`, remaining functions are not called
692 * `minetest.register_on_dignode(function(pos, node))`
693 * Called when the local player digs a node
694 * Newest functions are called first
695 * If any function returns true, the node isn't dug
696 * `minetest.register_on_punchnode(function(pos, node))`
697 * Called when the local player punches a node
698 * Newest functions are called first
699 * If any function returns true, the punch is ignored
700 * `minetest.register_on_placenode(function(pointed_thing, node))`
701 * Called when a node has been placed
702 * `minetest.register_on_item_use(function(item, pointed_thing))`
703 * Called when the local player uses an item.
704 * Newest functions are called first.
705 * If any function returns true, the item use is not sent to server.
706 * `minetest.register_on_modchannel_message(function(channel_name, sender, message))`
707 * Called when an incoming mod channel message is received
708 * You must have joined some channels before, and server must acknowledge the
710 * If message comes from a server mod, `sender` field is an empty string.
711 * `minetest.register_on_modchannel_signal(function(channel_name, signal))`
712 * Called when a valid incoming mod channel signal is received
713 * Signal id permit to react to server mod channel events
714 * Possible values are:
719 4: event_on_not_joined_channel
721 * `minetest.register_on_inventory_open(function(inventory))`
722 * Called when the local player open inventory
723 * Newest functions are called first
724 * If any function returns true, inventory doesn't open
726 * `minetest.sound_play(spec, parameters)`: returns a handle
727 * `spec` is a `SimpleSoundSpec`
728 * `parameters` is a sound parameter table
729 * `minetest.sound_stop(handle)`
732 * `minetest.after(time, func, ...)`
733 * Call the function `func` after `time` seconds, may be fractional
734 * Optional: Variable number of arguments that are passed to `func`
735 * `minetest.get_us_time()`
736 * Returns time with microsecond precision. May not return wall time.
737 * `minetest.get_day_count()`
738 * Returns number days elapsed since world was created, accounting for time changes.
739 * `minetest.get_timeofday()`
740 * Returns the time of day: `0` for midnight, `0.5` for midday
743 * `minetest.get_node_or_nil(pos)`
744 * Returns the node at the given position as table in the format
745 `{name="node_name", param1=0, param2=0}`, returns `nil`
746 for unloaded areas or flavor limited areas.
747 * `minetest.find_node_near(pos, radius, nodenames, [search_center])`: returns pos or `nil`
748 * `radius`: using a maximum metric
749 * `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
750 * `search_center` is an optional boolean (default: `false`)
751 If true `pos` is also checked for the nodes
752 * `minetest.get_meta(pos)`
753 * Get a `NodeMetaRef` at that position
754 * `minetest.get_node_level(pos)`
755 * get level of leveled node (water, snow)
756 * `minetest.get_node_max_level(pos)`
757 * get max available level for leveled node
760 * `minetest.get_wielded_item()`
761 * Returns the itemstack the local player is holding
762 * `minetest.send_chat_message(message)`
763 * Act as if `message` was typed by the player into the terminal.
764 * `minetest.run_server_chatcommand(cmd, param)`
765 * Alias for `minetest.send_chat_message("/" .. cmd .. " " .. param)`
766 * `minetest.clear_out_chat_queue()`
767 * Clears the out chat queue
768 * `minetest.localplayer`
769 * Reference to the LocalPlayer object. See [`LocalPlayer`](#localplayer) class reference for methods.
772 * `minetest.get_privilege_list()`
773 * Returns a list of privileges the current player has in the format `{priv1=true,...}`
774 * `minetest.string_to_privs(str)`: returns `{priv1=true,...}`
775 * `minetest.privs_to_string(privs)`: returns `"priv1,priv2,..."`
776 * Convert between two privilege representations
778 ### Client Environment
779 * `minetest.get_player_names()`
780 * Returns list of player names on server (nil if CSM_RF_READ_PLAYERINFO is enabled by server)
781 * `minetest.disconnect()`
782 * Disconnect from the server and exit to main menu.
783 * Returns `false` if the client is already disconnecting otherwise returns `true`.
784 * `minetest.get_server_info()`
785 * Returns [server info](#server-info).
786 * `minetest.send_respawn()`
787 * Sends a respawn request to the server.
790 * `minetest.get_mod_storage()`:
791 * returns reference to mod private `StorageRef`
792 * must be called during mod load time
795 ![Mod channels communication scheme](docs/mod channels.png)
797 * `minetest.mod_channel_join(channel_name)`
798 * Client joins channel `channel_name`, and creates it, if necessary. You
799 should listen from incoming messages with `minetest.register_on_modchannel_message`
800 call to receive incoming messages. Warning, this function is asynchronous.
803 * `minetest.add_particle(particle definition)`
805 * `minetest.add_particlespawner(particlespawner definition)`
806 * Add a `ParticleSpawner`, an object that spawns an amount of particles over `time` seconds
807 * Returns an `id`, and -1 if adding didn't succeed
809 * `minetest.delete_particlespawner(id)`
810 * Delete `ParticleSpawner` with `id` (return value from `minetest.add_particlespawner`)
813 * `minetest.parse_json(string[, nullvalue])`: returns something
814 * Convert a string containing JSON data into the Lua equivalent
815 * `nullvalue`: returned in place of the JSON null; defaults to `nil`
816 * On success returns a table, a string, a number, a boolean or `nullvalue`
817 * On failure outputs an error message and returns `nil`
818 * Example: `parse_json("[10, {\"a\":false}]")`, returns `{10, {a = false}}`
819 * `minetest.write_json(data[, styled])`: returns a string or `nil` and an error message
820 * Convert a Lua table into a JSON string
821 * styled: Outputs in a human-readable format if this is set, defaults to false
822 * Unserializable things like functions and userdata are saved as null.
823 * **Warning**: JSON is more strict than the Lua table format.
824 1. You can only use strings and positive integers of at least one as keys.
825 2. You can not mix string and integer keys.
826 This is due to the fact that JSON has two distinct array and object values.
827 * Example: `write_json({10, {a = false}})`, returns `"[10, {\"a\": false}]"`
828 * `minetest.serialize(table)`: returns a string
829 * Convert a table containing tables, strings, numbers, booleans and `nil`s
830 into string form readable by `minetest.deserialize`
831 * Example: `serialize({foo='bar'})`, returns `'return { ["foo"] = "bar" }'`
832 * `minetest.deserialize(string)`: returns a table
833 * Convert a string returned by `minetest.deserialize` into a table
834 * `string` is loaded in an empty sandbox environment.
835 * Will load functions, but they cannot access the global environment.
836 * Example: `deserialize('return { ["foo"] = "bar" }')`, returns `{foo='bar'}`
837 * Example: `deserialize('print("foo")')`, returns `nil` (function call fails)
838 * `error:[string "print("foo")"]:1: attempt to call global 'print' (a nil value)`
839 * `minetest.compress(data, method, ...)`: returns `compressed_data`
840 * Compress a string of data.
841 * `method` is a string identifying the compression method to be used.
842 * Supported compression methods:
843 * Deflate (zlib): `"deflate"`
844 * `...` indicates method-specific arguments. Currently defined arguments are:
845 * Deflate: `level` - Compression level, `0`-`9` or `nil`.
846 * `minetest.decompress(compressed_data, method, ...)`: returns data
847 * Decompress a string of data (using ZLib).
848 * See documentation on `minetest.compress()` for supported compression methods.
849 * currently supported.
850 * `...` indicates method-specific arguments. Currently, no methods use this.
851 * `minetest.rgba(red, green, blue[, alpha])`: returns a string
852 * Each argument is a 8 Bit unsigned integer
853 * Returns the ColorString from rgb or rgba values
854 * Example: `minetest.rgba(10, 20, 30, 40)`, returns `"#0A141E28"`
855 * `minetest.encode_base64(string)`: returns string encoded in base64
856 * Encodes a string in base64.
857 * `minetest.decode_base64(string)`: returns string
858 * Decodes a string encoded in base64.
859 * `minetest.gettext(string)` : returns string
860 * look up the translation of a string in the gettext message catalog
861 * `fgettext_ne(string, ...)`
862 * call minetest.gettext(string), replace "$1"..."$9" with the given
863 extra arguments and return the result
864 * `fgettext(string, ...)` : returns string
865 * same as fgettext_ne(), but calls minetest.formspec_escape before returning result
866 * `minetest.pointed_thing_to_face_pos(placer, pointed_thing)`: returns a position
867 * returns the exact position on the surface of a pointed node
868 * `minetest.global_exists(name)`
869 * Checks if a global variable has been set, without triggering a warning.
872 * `minetest.ui.minimap`
873 * Reference to the minimap object. See [`Minimap`](#minimap) class reference for methods.
874 * If client disabled minimap (using enable_minimap setting) this reference will be nil.
876 * Reference to the camera object. See [`Camera`](#camera) class reference for methods.
877 * `minetest.show_formspec(formname, formspec)` : returns true on success
878 * Shows a formspec to the player
879 * `minetest.display_chat_message(message)` returns true on success
880 * Shows a chat message to the current player.
887 An interface to use mod channels on client and server
890 * `leave()`: leave the mod channel.
891 * Client leaves channel `channel_name`.
892 * No more incoming or outgoing messages can be sent to this channel from client mods.
893 * This invalidate all future object usage
894 * Ensure your set mod_channel to nil after that to free Lua resources
895 * `is_writeable()`: returns true if channel is writable and mod can send over it.
896 * `send_all(message)`: Send `message` though the mod channel.
897 * If mod channel is not writable or invalid, message will be dropped.
898 * Message size is limited to 65535 characters by protocol.
901 An interface to manipulate minimap on client UI
904 * `show()`: shows the minimap (if not disabled by server)
905 * `hide()`: hides the minimap
906 * `set_pos(pos)`: sets the minimap position on screen
907 * `get_pos()`: returns the minimap current position
908 * `set_angle(deg)`: sets the minimap angle in degrees
909 * `get_angle()`: returns the current minimap angle in degrees
910 * `set_mode(mode)`: sets the minimap mode (0 to 6)
911 * `get_mode()`: returns the current minimap mode
912 * `set_shape(shape)`: Sets the minimap shape. (0 = square, 1 = round)
913 * `get_shape()`: Gets the minimap shape. (0 = square, 1 = round)
916 An interface to get or set information about the camera and camera-node.
917 Please do not try to access the reference until the camera is initialized, otherwise the reference will be nil.
920 * `set_camera_mode(mode)`
921 * Pass `0` for first-person, `1` for third person, and `2` for third person front
922 * `get_camera_mode()`
923 * Returns 0, 1, or 2 as described above
937 * Returns position of camera with view bobbing
939 * Returns eye offset vector
941 * Returns eye direction unit vector
942 * `get_look_vertical()`
943 * Returns pitch in radians
944 * `get_look_horizontal()`
945 * Returns yaw in radians
946 * `get_aspect_ratio()`
947 * Returns aspect ratio of screen
950 An interface to retrieve information about the player.
955 * returns current player current position
957 * returns player speed vector
961 * returns player name
963 * returns true if player is attached
964 * `is_touching_ground()`
965 * returns true if player touching ground
967 * returns true if player is in a liquid (This oscillates so that the player jumps a bit above the surface)
968 * `is_in_liquid_stable()`
969 * returns true if player is in a stable liquid (This is more stable and defines the maximum speed of the player)
970 * `get_liquid_viscosity()`
971 * returns liquid viscosity (Gets the viscosity of liquid to calculate friction)
973 * returns true if player is climbing
974 * `swimming_vertical()`
975 * returns true if player is swimming in vertical
976 * `get_physics_override()`
985 sneak_glitch = boolean
989 * `get_override_pos()`
990 * returns override position
992 * returns last player position before the current client step
993 * `get_last_velocity()`
994 * returns last player speed
996 * returns the player's breath
997 * `get_movement_acceleration()`
998 * returns acceleration of the player in different environments:
1008 * `get_movement_speed()`
1009 * returns player's speed in different environments:
1022 * returns player's movement in different environments:
1026 liquid_fluidity = float,
1027 liquid_sink = float,
1028 liquid_fluidity_smooth = float,
1033 * `get_last_look_horizontal()`:
1034 * returns last look horizontal angle
1035 * `get_last_look_vertical()`:
1036 * returns last look vertical angle
1037 * `get_key_pressed()`:
1038 * returns last key typed by the player
1039 * `hud_add(definition)`
1040 * add a HUD element described by HUD def, returns ID number on success and `nil` on failure.
1041 * See [`HUD definition`](#hud-definition-hud_add-hud_get)
1043 * returns the [`definition`](#hud-definition-hud_add-hud_get) of the HUD with that ID number or `nil`, if non-existent.
1045 * remove the HUD element of the specified id, returns `true` on success
1046 * `hud_change(id, stat, value)`
1047 * change a value of a previously added HUD element
1048 * element `stat` values: `position`, `name`, `scale`, `text`, `number`, `item`, `dir`
1049 * Returns `true` on success, otherwise returns `nil`
1052 An interface to read config files in the format of `minetest.conf`.
1054 It can be created via `Settings(filename)`.
1057 * `get(key)`: returns a value
1058 * `get_bool(key)`: returns a boolean
1060 * `remove(key)`: returns a boolean (`true` for success)
1061 * `get_names()`: returns `{key1,...}`
1062 * `write()`: returns a boolean (`true` for success)
1063 * write changes to file
1064 * `to_table()`: returns `{[key1]=value1,...}`
1067 Node metadata: reference extra data and functionality stored in a node.
1068 Can be obtained via `minetest.get_meta(pos)`.
1071 * `get_string(name)`
1074 * `to_table()`: returns `nil` or a table with keys:
1075 * `fields`: key-value storage
1076 * `inventory`: `{list1 = {}, ...}}`
1080 * `minetest.get_node_def(nodename)`
1081 * Returns [node definition](#node-definition) table of `nodename`
1082 * `minetest.get_item_def(itemstring)`
1083 * Returns item definition table of `itemstring`
1085 #### Node Definition
1089 has_on_construct = bool, -- Whether the node has the on_construct callback defined
1090 has_on_destruct = bool, -- Whether the node has the on_destruct callback defined
1091 has_after_destruct = bool, -- Whether the node has the after_destruct callback defined
1092 name = string, -- The name of the node e.g. "air", "default:dirt"
1093 groups = table, -- The groups of the node
1094 paramtype = string, -- Paramtype of the node
1095 paramtype2 = string, -- ParamType2 of the node
1096 drawtype = string, -- Drawtype of the node
1097 mesh = <string>, -- Mesh name if existant
1098 minimap_color = <Color>, -- Color of node on minimap *May not exist*
1099 visual_scale = number, -- Visual scale of node
1100 alpha = number, -- Alpha of the node. Only used for liquids
1101 color = <Color>, -- Color of node *May not exist*
1102 palette_name = <string>, -- Filename of palette *May not exist*
1103 palette = <{ -- List of colors
1107 waving = number, -- 0 of not waving, 1 if waving
1108 connect_sides = number, -- Used for connected nodes
1109 connects_to = { -- List of nodes to connect to
1113 post_effect_color = Color, -- Color overlayed on the screen when the player is in the node
1114 leveled = number, -- Max level for node
1115 sunlight_propogates = bool, -- Whether light passes through the block
1116 light_source = number, -- Light emitted by the block
1117 is_ground_content = bool, -- Whether caves should cut through the node
1118 walkable = bool, -- Whether the player collides with the node
1119 pointable = bool, -- Whether the player can select the node
1120 diggable = bool, -- Whether the player can dig the node
1121 climbable = bool, -- Whether the player can climb up the node
1122 buildable_to = bool, -- Whether the player can replace the node by placing a node on it
1123 rightclickable = bool, -- Whether the player can place nodes pointing at this node
1124 damage_per_second = number, -- HP of damage per second when the player is in the node
1125 liquid_type = <string>, -- A string containing "none", "flowing", or "source" *May not exist*
1126 liquid_alternative_flowing = <string>, -- Alternative node for liquid *May not exist*
1127 liquid_alternative_source = <string>, -- Alternative node for liquid *May not exist*
1128 liquid_viscosity = <number>, -- How fast the liquid flows *May not exist*
1129 liquid_renewable = <boolean>, -- Whether the liquid makes an infinite source *May not exist*
1130 liquid_range = <number>, -- How far the liquid flows *May not exist*
1131 drowning = bool, -- Whether the player will drown in the node
1132 floodable = bool, -- Whether nodes will be replaced by liquids (flooded)
1133 node_box = table, -- Nodebox to draw the node with
1134 collision_box = table, -- Nodebox to set the collision area
1135 selection_box = table, -- Nodebox to set the area selected by the player
1136 sounds = { -- Table of sounds that the block makes
1137 sound_footstep = SimpleSoundSpec,
1138 sound_dig = SimpleSoundSpec,
1139 sound_dug = SimpleSoundSpec
1141 legacy_facedir_simple = bool, -- Whether to use old facedir
1142 legacy_wallmounted = bool -- Whether to use old wallmounted
1146 #### Item Definition
1150 name = string, -- Name of the item e.g. "default:stone"
1151 description = string, -- Description of the item e.g. "Stone"
1152 type = string, -- Item type: "none", "node", "craftitem", "tool"
1153 inventory_image = string, -- Image in the inventory
1154 wield_image = string, -- Image in wieldmesh
1155 palette_image = string, -- Image for palette
1156 color = Color, -- Color for item
1157 wield_scale = Vector, -- Wieldmesh scale
1158 stack_max = number, -- Number of items stackable together
1159 usable = bool, -- Has on_use callback defined
1160 liquids_pointable = bool, -- Whether you can point at liquids with the item
1161 tool_capabilities = <table>, -- If the item is a tool, tool capabilities of the item
1162 groups = table, -- Groups of the item
1163 sound_place = SimpleSoundSpec, -- Sound played when placed
1164 sound_place_failed = SimpleSoundSpec, -- Sound played when placement failed
1165 node_placement_prediction = string -- Node placed in client until server catches up
1170 ### Chat command definition (`register_chatcommand`)
1173 params = "<name> <privilege>", -- Short parameter description
1174 description = "Remove privilege from player", -- Full description
1175 func = function(param), -- Called when command is run.
1176 -- Returns boolean success and text output.
1181 address = "minetest.example.org", -- The domain name/IP address of a remote server or "" for a local server.
1182 ip = "203.0.113.156", -- The IP address of the server.
1183 port = 30000, -- The port the client is connected to.
1184 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.
1188 ### HUD Definition (`hud_add`, `hud_get`)
1191 hud_elem_type = "image", -- see HUD element types, default "text"
1192 -- ^ type of HUD element, can be either of "image", "text", "statbar", or "inventory"
1193 position = {x=0.5, y=0.5},
1194 -- ^ Left corner position of element, default `{x=0,y=0}`.
1195 name = "<name>", -- default ""
1196 scale = {x=2, y=2}, -- default {x=0,y=0}
1197 text = "<text>", -- default ""
1198 number = 2, -- default 0
1199 item = 3, -- default 0
1200 -- ^ Selected item in inventory. 0 for no item selected.
1201 direction = 0, -- default 0
1202 -- ^ Direction: 0: left-right, 1: right-left, 2: top-bottom, 3: bottom-top
1203 alignment = {x=0, y=0}, -- default {x=0, y=0}
1204 -- ^ See "HUD Element Types"
1205 offset = {x=0, y=0}, -- default {x=0, y=0}
1206 -- ^ See "HUD Element Types"
1207 size = { x=100, y=100 }, -- default {x=0, y=0}
1208 -- ^ Size of element in pixels
1214 Most text can contain escape sequences, that can for example color the text.
1215 There are a few exceptions: tab headers, dropdowns and vertical labels can't.
1216 The following functions provide escape sequences:
1217 * `minetest.get_color_escape_sequence(color)`:
1218 * `color` is a [ColorString](#colorstring)
1219 * The escape sequence sets the text color to `color`
1220 * `minetest.colorize(color, message)`:
1222 `minetest.get_color_escape_sequence(color) ..
1224 minetest.get_color_escape_sequence("#ffffff")`
1225 * `minetest.get_background_escape_sequence(color)`
1226 * `color` is a [ColorString](#colorstring)
1227 * The escape sequence sets the background of the whole text element to
1228 `color`. Only defined for item descriptions and tooltips.
1229 * `minetest.strip_foreground_colors(str)`
1230 * Removes foreground colors added by `get_color_escape_sequence`.
1231 * `minetest.strip_background_colors(str)`
1232 * Removes background colors added by `get_background_escape_sequence`.
1233 * `minetest.strip_colors(str)`
1234 * Removes all color escape sequences.
1238 `#RGB` defines a color in hexadecimal format.
1240 `#RGBA` defines a color in hexadecimal format and alpha channel.
1242 `#RRGGBB` defines a color in hexadecimal format.
1244 `#RRGGBBAA` defines a color in hexadecimal format and alpha channel.
1246 Named colors are also supported and are equivalent to
1247 [CSS Color Module Level 4](http://dev.w3.org/csswg/css-color/#named-colors).
1248 To specify the value of the alpha channel, append `#AA` to the end of the color name
1249 (e.g. `colorname#08`). For named colors the hexadecimal string representing the alpha
1250 value must (always) be two hexadecimal digits.
1254 `{a = alpha, r = red, g = green, b = blue}` defines an ARGB8 color.
1258 The position field is used for all element types.
1260 To account for differing resolutions, the position coordinates are the percentage
1261 of the screen, ranging in value from `0` to `1`.
1263 The name field is not yet used, but should contain a description of what the
1264 HUD element represents. The direction field is the direction in which something
1267 `0` draws from left to right, `1` draws from right to left, `2` draws from
1268 top to bottom, and `3` draws from bottom to top.
1270 The `alignment` field specifies how the item will be aligned. It ranges from `-1` to `1`,
1271 with `0` being the center, `-1` is moved to the left/up, and `1` is to the right/down.
1272 Fractional values can be used.
1274 The `offset` field specifies a pixel offset from the position. Contrary to position,
1275 the offset is not scaled to screen size. This allows for some precisely-positioned
1278 **Note**: `offset` _will_ adapt to screen DPI as well as user defined scaling factor!
1280 Below are the specific uses for fields in each type; fields not listed for that type are ignored.
1282 **Note**: Future revisions to the HUD API may be incompatible; the HUD API is still
1283 in the experimental stages.
1286 Displays an image on the HUD.
1288 * `scale`: The scale of the image, with 1 being the original texture size.
1289 Only the X coordinate scale is used (positive values).
1290 Negative values represent that percentage of the screen it
1291 should take; e.g. `x=-100` means 100% (width).
1292 * `text`: The name of the texture that is displayed.
1293 * `alignment`: The alignment of the image.
1294 * `offset`: offset in pixels from position.
1297 Displays text on the HUD.
1299 * `scale`: Defines the bounding rectangle of the text.
1300 A value such as `{x=100, y=100}` should work.
1301 * `text`: The text to be displayed in the HUD element.
1302 * `number`: An integer containing the RGB value of the color used to draw the text.
1303 Specify `0xFFFFFF` for white text, `0xFF0000` for red, and so on.
1304 * `alignment`: The alignment of the text.
1305 * `offset`: offset in pixels from position.
1308 Displays a horizontal bar made up of half-images.
1310 * `text`: The name of the texture that is used.
1311 * `number`: The number of half-textures that are displayed.
1312 If odd, will end with a vertically center-split texture.
1314 * `offset`: offset in pixels from position.
1315 * `size`: If used, will force full-image size to this value (override texture pack image size)
1318 * `text`: The name of the inventory list to be displayed.
1319 * `number`: Number of items in the inventory to be displayed.
1320 * `item`: Position of item that is selected.
1322 * `offset`: offset in pixels from position.
1325 Displays distance to selected world position.
1327 * `name`: The name of the waypoint.
1328 * `text`: Distance suffix. Can be blank.
1329 * `number:` An integer containing the RGB value of the color used to draw the text.
1330 * `world_pos`: World position of the waypoint.
1332 ### Particle definition (`add_particle`)
1335 pos = {x=0, y=0, z=0},
1336 velocity = {x=0, y=0, z=0},
1337 acceleration = {x=0, y=0, z=0},
1338 -- ^ Spawn particle at pos with velocity and acceleration
1340 -- ^ Disappears after expirationtime seconds
1342 collisiondetection = false,
1343 -- ^ collisiondetection: if true collides with physical objects
1344 collision_removal = false,
1345 -- ^ collision_removal: if true then particle is removed when it collides,
1346 -- ^ requires collisiondetection = true to have any effect
1348 -- ^ vertical: if true faces player using y axis only
1349 texture = "image.png",
1350 -- ^ Uses texture (string)
1351 animation = {Tile Animation definition},
1352 -- ^ optional, specifies how to animate the particle texture
1354 -- ^ optional, specify particle self-luminescence in darkness
1357 ### `ParticleSpawner` definition (`add_particlespawner`)
1362 -- ^ If time is 0 has infinite lifespan and spawns the amount on a per-second base
1363 minpos = {x=0, y=0, z=0},
1364 maxpos = {x=0, y=0, z=0},
1365 minvel = {x=0, y=0, z=0},
1366 maxvel = {x=0, y=0, z=0},
1367 minacc = {x=0, y=0, z=0},
1368 maxacc = {x=0, y=0, z=0},
1373 -- ^ The particle's properties are random values in between the bounds:
1374 -- ^ minpos/maxpos, minvel/maxvel (velocity), minacc/maxacc (acceleration),
1375 -- ^ minsize/maxsize, minexptime/maxexptime (expirationtime)
1376 collisiondetection = false,
1377 -- ^ collisiondetection: if true uses collision detection
1378 collision_removal = false,
1379 -- ^ collision_removal: if true then particle is removed when it collides,
1380 -- ^ requires collisiondetection = true to have any effect
1382 -- ^ vertical: if true faces player using y axis only
1383 texture = "image.png",
1384 -- ^ Uses texture (string)