1 Minetest Lua Client Modding API Reference 0.4.16
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 Transfering client-sided mods form 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.
35 * `RUN_IN_PLACE=1` (Windows release, local build)
37 * Linux: `<build directory>`
38 * Windows: `<build directory>`
40 * Linux: `<build directory>`
41 * Windows: `<build directory>`
42 * `RUN_IN_PLACE=0`: (Linux release)
44 * Linux: `/usr/share/minetest`
45 * Windows: `<install directory>/minetest-0.4.x`
47 * Linux: `$HOME/.minetest`
48 * Windows: `C:/users/<user>/AppData/minetest` (maybe)
54 * `$path_share/clientmods/`
55 * `$path_user/clientmods/` (User-installed mods)
57 In a run-in-place version (e.g. the distributed windows version):
59 * `minetest-0.4.x/clientmods/` (User-installed mods)
61 On an installed version on Linux:
63 * `/usr/share/minetest/clientmods/`
64 * `$HOME/.minetest/clientmods/` (User-installed mods)
68 **NOTE: Not implemented yet.**
70 Mods can be put in a subdirectory, if the parent directory, which otherwise
71 should be a mod, contains a file named `modpack.txt`. This file shall be
72 empty, except for lines starting with `#`, which are comments.
74 Mod directory structure
75 ------------------------
84 The location of this directory.
87 List of mods that have to be loaded before loading this mod.
89 A single line contains a single modname.
91 Optional dependencies can be defined by appending a question mark
92 to a single modname. Their meaning is that if the specified mod
93 is missing, that does not prevent this mod from being loaded.
96 The main Lua script. Running this script should register everything it
97 wants to register. Subsequent execution depends on minetest calling the
100 `minetest.setting_get(name)` and `minetest.setting_getbool(name)` can be used
101 to read custom or existing settings at load time, if necessary.
104 Media files (sounds) that will be transferred to the
105 client and will be available for use by the mod.
107 Naming convention for registered textual names
108 ----------------------------------------------
109 Registered names should generally be in this format:
111 "modname:<whatever>" (<whatever> can have characters a-zA-Z0-9_)
113 This is to prevent conflicting names from corrupting maps and is
114 enforced by the mod loader.
117 In the mod `experimental`, there is the ideal item/node/entity name `tnt`.
118 So the name should be `experimental:tnt`.
120 Enforcement can be overridden by prefixing the name with `:`. This can
121 be used for overriding the registrations of some other mod.
123 Example: Any mod can redefine `experimental:tnt` by using the name
128 (also that mod is required to have `experimental` as a dependency)
130 The `:` prefix can also be used for maintaining backwards compatibility.
134 **NOTE: max_hear_distance and connecting to objects is not implemented.**
136 Only Ogg Vorbis files are supported.
138 For positional playing of sounds, only single-channel (mono) files are
139 supported. Otherwise OpenAL will play them non-positionally.
141 Mods should generally prefix their sounds with `modname_`, e.g. given
142 the mod name "`foomod`", a sound could be called:
146 Sounds are referred to by their name with a dot, a single digit and the
147 file extension stripped out. When a sound is played, the actual sound file
148 is chosen randomly from the matching sounds.
150 When playing the sound `foomod_foosound`, the sound is chosen randomly
151 from the available ones of the following files:
153 * `foomod_foosound.ogg`
154 * `foomod_foosound.0.ogg`
155 * `foomod_foosound.1.ogg`
157 * `foomod_foosound.9.ogg`
159 Examples of sound parameter tables:
163 gain = 1.0, -- default
165 -- Play locationless, looped
167 gain = 1.0, -- default
170 -- Play in a location
172 pos = {x = 1, y = 2, z = 3},
173 gain = 1.0, -- default
174 max_hear_distance = 32, -- default, uses an euclidean metric
176 -- Play connected to an object, looped
178 object = <an ObjectRef>,
179 gain = 1.0, -- default
180 max_hear_distance = 32, -- default, uses an euclidean metric
184 Looped sounds must either be connected to an object or played locationless.
188 * e.g. `"default_place_node"`
190 * e.g. `{name = "default_place_node"}`
191 * e.g. `{name = "default_place_node", gain = 1.0}`
193 Representations of simple things
194 --------------------------------
198 {x=num, y=num, z=num}
200 For helper functions see "Vector helpers".
204 * `{type="node", under=pos, above=pos}`
205 * `{type="object", id=ObjectID}`
207 Flag Specifier Format
208 ---------------------
209 Flags using the standardized flag specifier format can be specified in either of
210 two ways, by string or table.
212 The string format is a comma-delimited set of flag names; whitespace and
213 unrecognized flag fields are ignored. Specifying a flag in the string sets the
214 flag, and specifying a flag prefixed by the string `"no"` explicitly
215 clears the flag from whatever the default may be.
217 In addition to the standard string flag format, the schematic flags field can
218 also be a table of flag names to boolean values representing whether or not the
219 flag is set. Additionally, if a field with the flag name prefixed with `"no"`
220 is present, mapped to a boolean of any value, the specified flag is unset.
222 E.g. A flag field of value
224 {place_center_x = true, place_center_y=false, place_center_z=true}
228 {place_center_x = true, noplace_center_y=true, place_center_z=true}
230 which is equivalent to
232 "place_center_x, noplace_center_y, place_center_z"
236 "place_center_x, place_center_z"
238 since, by default, no schematic attributes are set.
242 Formspec defines a menu. It is a string, with a somewhat strange format.
244 Spaces and newlines can be inserted between the blocks, as is used in the
252 list[context;main;0,0;8,4;]
253 list[current_player;main;0,5;8,4;]
258 list[context;fuel;2,3;1,1;]
259 list[context;src;2,1;1,1;]
260 list[context;dst;5,1;2,2;]
261 list[current_player;main;0,5;8,4;]
263 #### Minecraft-like player inventory
266 image[1,0.6;1,2;player.png]
267 list[current_player;main;0,3.5;8,4;]
268 list[current_player;craft;3,0;3,3;]
269 list[current_player;craftpreview;7,1;1,1;]
273 #### `size[<W>,<H>,<fixed_size>]`
274 * Define the size of the menu in inventory slots
275 * `fixed_size`: `true`/`false` (optional)
276 * deprecated: `invsize[<W>,<H>;]`
278 #### `container[<X>,<Y>]`
279 * Start of a container block, moves all physical elements in the container by (X, Y)
280 * Must have matching container_end
281 * Containers can be nested, in which case the offsets are added
282 (child containers are relative to parent containers)
284 #### `container_end[]`
285 * End of a container, following elements are no longer relative to this container
287 #### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]`
288 * Show an inventory list
290 #### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]`
291 * Show an inventory list
293 #### `listring[<inventory location>;<list name>]`
294 * Allows to create a ring of inventory lists
295 * Shift-clicking on items in one element of the ring
296 will send them to the next inventory list inside the ring
297 * The first occurrence of an element inside the ring will
298 determine the inventory where items will be sent to
301 * Shorthand for doing `listring[<inventory location>;<list name>]`
302 for the last two inventory lists added by list[...]
304 #### `listcolors[<slot_bg_normal>;<slot_bg_hover>]`
305 * Sets background color of slots as `ColorString`
306 * Sets background color of slots on mouse hovering
308 #### `listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>]`
309 * Sets background color of slots as `ColorString`
310 * Sets background color of slots on mouse hovering
311 * Sets color of slots border
313 #### `listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>;<tooltip_bgcolor>;<tooltip_fontcolor>]`
314 * Sets background color of slots as `ColorString`
315 * Sets background color of slots on mouse hovering
316 * Sets color of slots border
317 * Sets default background color of tooltips
318 * Sets default font color of tooltips
320 #### `tooltip[<gui_element_name>;<tooltip_text>;<bgcolor>,<fontcolor>]`
321 * Adds tooltip for an element
322 * `<bgcolor>` tooltip background color as `ColorString` (optional)
323 * `<fontcolor>` tooltip font color as `ColorString` (optional)
325 #### `image[<X>,<Y>;<W>,<H>;<texture name>]`
327 * Position and size units are inventory slots
329 #### `item_image[<X>,<Y>;<W>,<H>;<item name>]`
330 * Show an inventory image of registered item/node
331 * Position and size units are inventory slots
333 #### `bgcolor[<color>;<fullscreen>]`
334 * Sets background color of formspec as `ColorString`
335 * If `true`, the background color is drawn fullscreen (does not effect the size of the formspec)
337 #### `background[<X>,<Y>;<W>,<H>;<texture name>]`
338 * Use a background. Inventory rectangles are not drawn then.
339 * Position and size units are inventory slots
340 * Example for formspec 8x4 in 16x resolution: image shall be sized
341 8 times 16px times 4 times 16px.
343 #### `background[<X>,<Y>;<W>,<H>;<texture name>;<auto_clip>]`
344 * Use a background. Inventory rectangles are not drawn then.
345 * Position and size units are inventory slots
346 * Example for formspec 8x4 in 16x resolution:
347 image shall be sized 8 times 16px times 4 times 16px
348 * If `true` the background is clipped to formspec size
349 (`x` and `y` are used as offset values, `w` and `h` are ignored)
351 #### `pwdfield[<X>,<Y>;<W>,<H>;<name>;<label>]`
352 * Textual password style field; will be sent to server when a button is clicked
353 * When enter is pressed in field, fields.key_enter_field will be sent with the name
355 * `x` and `y` position the field relative to the top left of the menu
356 * `w` and `h` are the size of the field
357 * Fields are a set height, but will be vertically centred on `h`
358 * Position and size units are inventory slots
359 * `name` is the name of the field as returned in fields to `on_receive_fields`
360 * `label`, if not blank, will be text printed on the top left above the field
361 * See field_close_on_enter to stop enter closing the formspec
363 #### `field[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`
364 * Textual field; will be sent to server when a button is clicked
365 * When enter is pressed in field, fields.key_enter_field will be sent with the name
367 * `x` and `y` position the field relative to the top left of the menu
368 * `w` and `h` are the size of the field
369 * Fields are a set height, but will be vertically centred on `h`
370 * Position and size units are inventory slots
371 * `name` is the name of the field as returned in fields to `on_receive_fields`
372 * `label`, if not blank, will be text printed on the top left above the field
373 * `default` is the default value of the field
374 * `default` may contain variable references such as `${text}'` which
375 will fill the value from the metadata value `text`
376 * **Note**: no extra text or more than a single variable is supported ATM.
377 * See field_close_on_enter to stop enter closing the formspec
379 #### `field[<name>;<label>;<default>]`
380 * As above, but without position/size units
381 * When enter is pressed in field, fields.key_enter_field will be sent with the name
383 * Special field for creating simple forms, such as sign text input
384 * Must be used without a `size[]` element
385 * A "Proceed" button will be added automatically
386 * See field_close_on_enter to stop enter closing the formspec
388 #### `field_close_on_enter[<name>;<close_on_enter>]`
389 * <name> is the name of the field
390 * if <close_on_enter> is false, pressing enter in the field will submit the form but not close it
391 * defaults to true when not specified (ie: no tag for a field)
393 #### `textarea[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`
394 * Same as fields above, but with multi-line input
396 #### `label[<X>,<Y>;<label>]`
397 * `x` and `y` work as per field
398 * `label` is the text on the label
399 * Position and size units are inventory slots
401 #### `vertlabel[<X>,<Y>;<label>]`
402 * Textual label drawn vertically
403 * `x` and `y` work as per field
404 * `label` is the text on the label
405 * Position and size units are inventory slots
407 #### `button[<X>,<Y>;<W>,<H>;<name>;<label>]`
408 * Clickable button. When clicked, fields will be sent.
409 * `x`, `y` and `name` work as per field
410 * `w` and `h` are the size of the button
411 * Fixed button height. It will be vertically centred on `h`
412 * `label` is the text on the button
413 * Position and size units are inventory slots
415 #### `image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]`
416 * `x`, `y`, `w`, `h`, and `name` work as per button
417 * `texture name` is the filename of an image
418 * Position and size units are inventory slots
420 #### `image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>;<noclip>;<drawborder>;<pressed texture name>]`
421 * `x`, `y`, `w`, `h`, and `name` work as per button
422 * `texture name` is the filename of an image
423 * Position and size units are inventory slots
424 * `noclip=true` means the image button doesn't need to be within specified formsize
425 * `drawborder`: draw button border or not
426 * `pressed texture name` is the filename of an image on pressed state
428 #### `item_image_button[<X>,<Y>;<W>,<H>;<item name>;<name>;<label>]`
429 * `x`, `y`, `w`, `h`, `name` and `label` work as per button
430 * `item name` is the registered name of an item/node,
431 tooltip will be made out of its description
432 to override it use tooltip element
433 * Position and size units are inventory slots
435 #### `button_exit[<X>,<Y>;<W>,<H>;<name>;<label>]`
436 * When clicked, fields will be sent and the form will quit.
438 #### `image_button_exit[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]`
439 * When clicked, fields will be sent and the form will quit.
441 #### `textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>]`
442 * Scrollable item list showing arbitrary text elements
443 * `x` and `y` position the itemlist relative to the top left of the menu
444 * `w` and `h` are the size of the itemlist
445 * `name` fieldname sent to server on doubleclick value is current selected element
446 * `listelements` can be prepended by #color in hexadecimal format RRGGBB (only),
447 * if you want a listelement to start with "#" write "##".
449 #### `textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>;<selected idx>;<transparent>]`
450 * Scrollable itemlist showing arbitrary text elements
451 * `x` and `y` position the item list relative to the top left of the menu
452 * `w` and `h` are the size of the item list
453 * `name` fieldname sent to server on doubleclick value is current selected element
454 * `listelements` can be prepended by #RRGGBB (only) in hexadecimal format
455 * if you want a listelement to start with "#" write "##"
456 * Index to be selected within textlist
457 * `true`/`false`: draw transparent background
458 * See also `minetest.explode_textlist_event` (main menu: `engine.explode_textlist_event`)
460 #### `tabheader[<X>,<Y>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]`
461 * Show a tab**header** at specific position (ignores formsize)
462 * `x` and `y` position the itemlist relative to the top left of the menu
463 * `name` fieldname data is transferred to Lua
464 * `caption 1`...: name shown on top of tab
465 * `current_tab`: index of selected tab 1...
466 * `transparent` (optional): show transparent
467 * `draw_border` (optional): draw border
469 #### `box[<X>,<Y>;<W>,<H>;<color>]`
470 * Simple colored semitransparent box
471 * `x` and `y` position the box relative to the top left of the menu
472 * `w` and `h` are the size of box
473 * `color` is color specified as a `ColorString`
475 #### `dropdown[<X>,<Y>;<W>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>]`
476 * Show a dropdown field
477 * **Important note**: There are two different operation modes:
478 1. handle directly on change (only changed dropdown is submitted)
479 2. read the value on pressing a button (all dropdown values are available)
480 * `x` and `y` position of dropdown
482 * Fieldname data is transferred to Lua
483 * Items to be shown in dropdown
484 * Index of currently selected dropdown item
486 #### `checkbox[<X>,<Y>;<name>;<label>;<selected>]`
488 * `x` and `y`: position of checkbox
489 * `name` fieldname data is transferred to Lua
490 * `label` to be shown left of checkbox
491 * `selected` (optional): `true`/`false`
493 #### `scrollbar[<X>,<Y>;<W>,<H>;<orientation>;<name>;<value>]`
495 * There are two ways to use it:
496 1. handle the changed event (only changed scrollbar is available)
497 2. read the value on pressing a button (all scrollbars are available)
498 * `x` and `y`: position of trackbar
499 * `w` and `h`: width and height
500 * `orientation`: `vertical`/`horizontal`
501 * Fieldname data is transferred to Lua
502 * Value this trackbar is set to (`0`-`1000`)
503 * See also `minetest.explode_scrollbar_event` (main menu: `engine.explode_scrollbar_event`)
505 #### `table[<X>,<Y>;<W>,<H>;<name>;<cell 1>,<cell 2>,...,<cell n>;<selected idx>]`
506 * Show scrollable table using options defined by the previous `tableoptions[]`
507 * Displays cells as defined by the previous `tablecolumns[]`
508 * `x` and `y`: position the itemlist relative to the top left of the menu
509 * `w` and `h` are the size of the itemlist
510 * `name`: fieldname sent to server on row select or doubleclick
511 * `cell 1`...`cell n`: cell contents given in row-major order
512 * `selected idx`: index of row to be selected within table (first row = `1`)
513 * See also `minetest.explode_table_event` (main menu: `engine.explode_table_event`)
515 #### `tableoptions[<opt 1>;<opt 2>;...]`
516 * Sets options for `table[]`
518 * default text color (`ColorString`), defaults to `#FFFFFF`
519 * `background=#RRGGBB`
520 * table background color (`ColorString`), defaults to `#000000`
521 * `border=<true/false>`
522 * should the table be drawn with a border? (default: `true`)
523 * `highlight=#RRGGBB`
524 * highlight background color (`ColorString`), defaults to `#466432`
525 * `highlight_text=#RRGGBB`
526 * highlight text color (`ColorString`), defaults to `#FFFFFF`
527 * `opendepth=<value>`
528 * all subtrees up to `depth < value` are open (default value = `0`)
529 * only useful when there is a column of type "tree"
531 #### `tablecolumns[<type 1>,<opt 1a>,<opt 1b>,...;<type 2>,<opt 2a>,<opt 2b>;...]`
532 * Sets columns for `table[]`
533 * Types: `text`, `image`, `color`, `indent`, `tree`
534 * `text`: show cell contents as text
535 * `image`: cell contents are an image index, use column options to define images
536 * `color`: cell contents are a ColorString and define color of following cell
537 * `indent`: cell contents are a number and define indentation of following cell
538 * `tree`: same as indent, but user can open and close subtrees (treeview-like)
541 * for `text` and `image`: content alignment within cells.
542 Available values: `left` (default), `center`, `right`, `inline`
544 * for `text` and `image`: minimum width in em (default: `0`)
545 * for `indent` and `tree`: indent width in em (default: `1.5`)
546 * `padding=<value>`: padding left of the column, in em (default `0.5`).
547 Exception: defaults to 0 for indent columns
548 * `tooltip=<value>`: tooltip text (default: empty)
549 * `image` column options:
550 * `0=<value>` sets image for image index 0
551 * `1=<value>` sets image for image index 1
552 * `2=<value>` sets image for image index 2
553 * and so on; defined indices need not be contiguous empty or
554 non-numeric cells are treated as `0`.
555 * `color` column options:
556 * `span=<value>`: number of following columns to affect (default: infinite)
558 **Note**: do _not_ use a element name starting with `key_`; those names are reserved to
559 pass key press events to formspec!
563 * `vector.new(a[, b, c])`: returns a vector:
564 * A copy of `a` if `a` is a vector.
565 * `{x = a, y = b, z = c}`, if all `a, b, c` are defined
566 * `vector.direction(p1, p2)`: returns a vector
567 * `vector.distance(p1, p2)`: returns a number
568 * `vector.length(v)`: returns a number
569 * `vector.normalize(v)`: returns a vector
570 * `vector.floor(v)`: returns a vector, each dimension rounded down
571 * `vector.round(v)`: returns a vector, each dimension rounded to nearest int
572 * `vector.apply(v, func)`: returns a vector
573 * `vector.equals(v1, v2)`: returns a boolean
575 For the following functions `x` can be either a vector or a number:
577 * `vector.add(v, x)`: returns a vector
578 * `vector.subtract(v, x)`: returns a vector
579 * `vector.multiply(v, x)`: returns a scaled vector or Schur product
580 * `vector.divide(v, x)`: returns a scaled vector or Schur quotient
584 * `dump2(obj, name="_", dumped={})`
585 * Return object serialized as a string, handles reference loops
586 * `dump(obj, dumped={})`
587 * Return object serialized as a string
589 * Get the hypotenuse of a triangle with legs x and y.
590 Useful for distance calculation.
591 * `math.sign(x, tolerance)`
592 * Get the sign of a number.
593 Optional: Also returns `0` when the absolute value is within the tolerance (default: `0`)
594 * `string.split(str, separator=",", include_empty=false, max_splits=-1, sep_is_pattern=false)`
595 * If `max_splits` is negative, do not limit splits.
596 * `sep_is_pattern` specifies if separator is a plain string or a pattern (regex).
597 * e.g. `string:split("a,b", ",") == {"a","b"}`
599 * e.g. `string.trim("\n \t\tfoo bar\t ") == "foo bar"`
600 * `minetest.wrap_text(str, limit)`: returns a string
601 * Adds new lines to the string to keep it within the specified character limit
602 * limit: Maximal amount of characters in one line
603 * `minetest.pos_to_string({x=X,y=Y,z=Z}, decimal_places))`: returns string `"(X,Y,Z)"`
604 * Convert position to a printable string
605 Optional: 'decimal_places' will round the x, y and z of the pos to the given decimal place.
606 * `minetest.string_to_pos(string)`: returns a position
607 * Same but in reverse. Returns `nil` if the string can't be parsed to a position.
608 * `minetest.string_to_area("(X1, Y1, Z1) (X2, Y2, Z2)")`: returns two positions
609 * Converts a string representing an area box into two positions
610 * `minetest.is_yes(arg)`
611 * returns whether `arg` can be interpreted as yes
612 * `table.copy(table)`: returns a table
613 * returns a deep copy of `table`
615 Minetest namespace reference
616 ------------------------------
620 * `minetest.get_current_modname()`: returns the currently loading mod's name, when we are loading a mod
621 * `minetest.get_version()`: returns a table containing components of the
622 engine version. Components:
623 * `project`: Name of the project, eg, "Minetest"
624 * `string`: Simple version, eg, "1.2.3-dev"
625 * `hash`: Full git version (only set if available), eg, "1.2.3-dev-01234567-dirty"
626 Use this for informational purposes only. The information in the returned
627 table does not represent the capabilities of the engine, nor is it
628 reliable or verifyable. Compatible forks will have a different name and
629 version entirely. To check for the presence of engine features, test
630 whether the functions exported by the wanted features exist. For example:
631 `if minetest.nodeupdate then ... end`.
634 * `minetest.debug(...)`
635 * Equivalent to `minetest.log(table.concat({...}, "\t"))`
636 * `minetest.log([level,] text)`
637 * `level` is one of `"none"`, `"error"`, `"warning"`, `"action"`,
638 `"info"`, or `"verbose"`. Default is `"none"`.
640 ### Global callback registration functions
641 Call these functions only at load time!
643 * `minetest.register_globalstep(func(dtime))`
644 * Called every client environment step, usually interval of 0.1s
645 * `minetest.register_on_shutdown(func())`
646 * Called before client shutdown
647 * **Warning**: If the client terminates abnormally (i.e. crashes), the registered
648 callbacks **will likely not be run**. Data should be saved at
649 semi-frequent intervals as well as on server shutdown.
650 * `minetest.register_on_connect(func())`
651 * Called at the end of client connection (when player is loaded onto map)
652 * `minetest.register_on_receiving_chat_message(func(message))`
653 * Called always when a client receive a message
654 * Return `true` to mark the message as handled, which means that it will not be shown to chat
655 * `minetest.register_on_sending_chat_message(func(message))`
656 * Called always when a client send a message from chat
657 * Return `true` to mark the message as handled, which means that it will not be sent to server
658 * `minetest.register_chatcommand(cmd, chatcommand definition)`
659 * Adds definition to minetest.registered_chatcommands
660 * `minetest.unregister_chatcommand(name)`
661 * Unregisters a chatcommands registered with register_chatcommand.
662 * `minetest.register_on_death(func())`
663 * Called when the local player dies
664 * `minetest.register_on_hp_modification(func(hp))`
665 * Called when server modified player's HP
666 * `minetest.register_on_damage_taken(func(hp))`
667 * Called when the local player take damages
668 * `minetest.register_on_formspec_input(func(formname, fields))`
669 * Called when a button is pressed in the local player's inventory form
670 * Newest functions are called first
671 * If function returns `true`, remaining functions are not called
672 * `minetest.register_on_dignode(func(pos, node))`
673 * Called when the local player digs a node
674 * Newest functions are called first
675 * If any function returns true, the node isn't dug
676 * `minetest.register_on_punchnode(func(pos, node))`
677 * Called when the local player punches a node
678 * Newest functions are called first
679 * If any function returns true, the punch is ignored
680 * `minetest.register_on_placenode(function(pointed_thing, node))`
681 * Called when a node has been placed
682 * `minetest.register_on_item_use(func(item, pointed_thing))`
683 * Called when the local player uses an item.
684 * Newest functions are called first.
685 * If any function returns true, the item use is not sent to server.
687 * `minetest.sound_play(spec, parameters)`: returns a handle
688 * `spec` is a `SimpleSoundSpec`
689 * `parameters` is a sound parameter table
690 * `minetest.sound_stop(handle)`
693 * `minetest.after(time, func, ...)`
694 * Call the function `func` after `time` seconds, may be fractional
695 * Optional: Variable number of arguments that are passed to `func`
696 * `minetest.get_us_time()`
697 * Returns time with microsecond precision. May not return wall time.
698 * `minetest.get_day_count()`
699 * Returns number days elapsed since world was created, accounting for time changes.
700 * `minetest.get_timeofday()`
701 * Returns the time of day: `0` for midnight, `0.5` for midday
704 * `minetest.get_node_or_nil(pos)`
705 * Returns the node at the given position as table in the format
706 `{name="node_name", param1=0, param2=0}`, returns `nil`
707 for unloaded areas or flavour limited areas.
708 * `minetest.find_node_near(pos, radius, nodenames, [search_center])`: returns pos or `nil`
709 * `radius`: using a maximum metric
710 * `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
711 * `search_center` is an optional boolean (default: `false`)
712 If true `pos` is also checked for the nodes
713 * `minetest.get_meta(pos)`
714 * Get a `NodeMetaRef` at that position
715 * `minetest.get_node_level(pos)`
716 * get level of leveled node (water, snow)
717 * `minetest.get_node_max_level(pos)`
718 * get max available level for leveled node
721 * `minetest.get_wielded_item()`
722 * Returns the itemstack the local player is holding
723 * `minetest.send_chat_message(message)`
724 * Act as if `message` was typed by the player into the terminal.
725 * `minetest.run_server_chatcommand(cmd, param)`
726 * Alias for `minetest.send_chat_message("/" .. cmd .. " " .. param)`
727 * `minetest.clear_out_chat_queue()`
728 * Clears the out chat queue
729 * `minetest.localplayer`
730 * Reference to the LocalPlayer object. See [`LocalPlayer`](#localplayer) class reference for methods.
733 * `minetest.get_privilege_list()`
734 * Returns a list of privileges the currect player has in the format `{priv1=true,...}`
735 * `minetest.string_to_privs(str)`: returns `{priv1=true,...}`
736 * `minetest.privs_to_string(privs)`: returns `"priv1,priv2,..."`
737 * Convert between two privilege representations
739 ### Client Environment
740 * `minetest.get_player_names()`
741 * Returns list of player names on server
742 * `minetest.disconnect()`
743 * Disconnect from the server and exit to main menu.
744 * Returns `false` if the client is already disconnecting otherwise returns `true`.
745 * `minetest.take_screenshot()`
747 * `minetest.get_server_info()`
748 * Returns [server info](#server-info).
749 * `minetest.send_respawn()`
750 * Sends a respawn request to the server.
753 * `minetest.get_mod_storage()`:
754 * returns reference to mod private `StorageRef`
755 * must be called during mod load time
758 * `minetest.parse_json(string[, nullvalue])`: returns something
759 * Convert a string containing JSON data into the Lua equivalent
760 * `nullvalue`: returned in place of the JSON null; defaults to `nil`
761 * On success returns a table, a string, a number, a boolean or `nullvalue`
762 * On failure outputs an error message and returns `nil`
763 * Example: `parse_json("[10, {\"a\":false}]")`, returns `{10, {a = false}}`
764 * `minetest.write_json(data[, styled])`: returns a string or `nil` and an error message
765 * Convert a Lua table into a JSON string
766 * styled: Outputs in a human-readable format if this is set, defaults to false
767 * Unserializable things like functions and userdata are saved as null.
768 * **Warning**: JSON is more strict than the Lua table format.
769 1. You can only use strings and positive integers of at least one as keys.
770 2. You can not mix string and integer keys.
771 This is due to the fact that JSON has two distinct array and object values.
772 * Example: `write_json({10, {a = false}})`, returns `"[10, {\"a\": false}]"`
773 * `minetest.serialize(table)`: returns a string
774 * Convert a table containing tables, strings, numbers, booleans and `nil`s
775 into string form readable by `minetest.deserialize`
776 * Example: `serialize({foo='bar'})`, returns `'return { ["foo"] = "bar" }'`
777 * `minetest.deserialize(string)`: returns a table
778 * Convert a string returned by `minetest.deserialize` into a table
779 * `string` is loaded in an empty sandbox environment.
780 * Will load functions, but they cannot access the global environment.
781 * Example: `deserialize('return { ["foo"] = "bar" }')`, returns `{foo='bar'}`
782 * Example: `deserialize('print("foo")')`, returns `nil` (function call fails)
783 * `error:[string "print("foo")"]:1: attempt to call global 'print' (a nil value)`
784 * `minetest.compress(data, method, ...)`: returns `compressed_data`
785 * Compress a string of data.
786 * `method` is a string identifying the compression method to be used.
787 * Supported compression methods:
788 * Deflate (zlib): `"deflate"`
789 * `...` indicates method-specific arguments. Currently defined arguments are:
790 * Deflate: `level` - Compression level, `0`-`9` or `nil`.
791 * `minetest.decompress(compressed_data, method, ...)`: returns data
792 * Decompress a string of data (using ZLib).
793 * See documentation on `minetest.compress()` for supported compression methods.
794 * currently supported.
795 * `...` indicates method-specific arguments. Currently, no methods use this.
796 * `minetest.rgba(red, green, blue[, alpha])`: returns a string
797 * Each argument is a 8 Bit unsigned integer
798 * Returns the ColorString from rgb or rgba values
799 * Example: `minetest.rgba(10, 20, 30, 40)`, returns `"#0A141E28"`
800 * `minetest.encode_base64(string)`: returns string encoded in base64
801 * Encodes a string in base64.
802 * `minetest.decode_base64(string)`: returns string
803 * Decodes a string encoded in base64.
804 * `minetest.gettext(string)` : returns string
805 * look up the translation of a string in the gettext message catalog
806 * `fgettext_ne(string, ...)`
807 * call minetest.gettext(string), replace "$1"..."$9" with the given
808 extra arguments and return the result
809 * `fgettext(string, ...)` : returns string
810 * same as fgettext_ne(), but calls minetest.formspec_escape before returning result
811 * `minetest.pointed_thing_to_face_pos(placer, pointed_thing)`: returns a position
812 * returns the exact position on the surface of a pointed node
813 * `minetest.global_exists(name)`
814 * Checks if a global variable has been set, without triggering a warning.
817 * `minetest.ui.minimap`
818 * Reference to the minimap object. See [`Minimap`](#minimap) class reference for methods.
819 * If client disabled minimap (using enable_minimap setting) this reference will be nil.
821 * Reference to the camera object. See [`Camera`](#camera) class reference for methods.
822 * `minetest.show_formspec(formname, formspec)` : returns true on success
823 * Shows a formspec to the player
824 * `minetest.display_chat_message(message)` returns true on success
825 * Shows a chat message to the current player.
831 An interface to manipulate minimap on client UI
833 * `show()`: shows the minimap (if not disabled by server)
834 * `hide()`: hides the minimap
835 * `set_pos(pos)`: sets the minimap position on screen
836 * `get_pos()`: returns the minimap current position
837 * `set_angle(deg)`: sets the minimap angle in degrees
838 * `get_angle()`: returns the current minimap angle in degrees
839 * `set_mode(mode)`: sets the minimap mode (0 to 6)
840 * `get_mode()`: returns the current minimap mode
841 * `set_shape(shape)`: Sets the minimap shape. (0 = square, 1 = round)
842 * `get_shape()`: Gets the minimap shape. (0 = square, 1 = round)
845 An interface to get or set information about the camera and cameranode.
846 Please do not try to access the reference until the camera is initialized, otherwise the reference will be nil.
849 * `set_camera_mode(mode)`
850 * Pass `0` for first-person, `1` for third person, and `2` for third person front
851 * `get_camera_mode()`
852 * Returns with same syntax as above
866 * Returns position of camera with view bobbing
868 * Returns eye offset vector
870 * Returns eye direction unit vector
871 * `get_look_vertical()`
872 * Returns pitch in radians
873 * `get_look_horizontal()`
874 * Returns yaw in radians
875 * `get_aspect_ratio()`
876 * Returns aspect ratio of screen
879 An interface to retrieve information about the player. The player is
880 not accessible until the client is fully done loading and therefore
881 not at module init time.
883 To get the localplayer handle correctly, use `on_connect()` as follows:
887 minetest.register_on_connect(function()
888 localplayer = minetest.localplayer
895 * returns current player current position
897 * returns player speed vector
901 * returns player name
903 * returns true if player is attached
904 * `is_touching_ground()`
905 * returns true if player touching ground
907 * returns true if player is in a liquid (This oscillates so that the player jumps a bit above the surface)
908 * `is_in_liquid_stable()`
909 * returns true if player is in a stable liquid (This is more stable and defines the maximum speed of the player)
910 * `get_liquid_viscosity()`
911 * returns liquid viscosity (Gets the viscosity of liquid to calculate friction)
913 * returns true if player is climbing
914 * `swimming_vertical()`
915 * returns true if player is swimming in vertical
916 * `get_physics_override()`
925 sneak_glitch = boolean
929 * `get_override_pos()`
930 * returns override position
932 * returns last player position before the current client step
933 * `get_last_velocity()`
934 * returns last player speed
936 * returns the player's breath
937 * `get_movement_acceleration()`
938 * returns acceleration of the player in different environments:
948 * `get_movement_speed()`
949 * returns player's speed in different environments:
962 * returns player's movement in different environments:
966 liquid_fluidity = float,
968 liquid_fluidity_smooth = float,
973 * `get_last_look_horizontal()`:
974 * returns last look horizontal angle
975 * `get_last_look_vertical()`:
976 * returns last look vertical angle
977 * `get_key_pressed()`:
978 * returns last key typed by the player
981 An interface to read config files in the format of `minetest.conf`.
983 It can be created via `Settings(filename)`.
986 * `get(key)`: returns a value
987 * `get_bool(key)`: returns a boolean
989 * `remove(key)`: returns a boolean (`true` for success)
990 * `get_names()`: returns `{key1,...}`
991 * `write()`: returns a boolean (`true` for success)
992 * write changes to file
993 * `to_table()`: returns `{[key1]=value1,...}`
996 Node metadata: reference extra data and functionality stored in a node.
997 Can be obtained via `minetest.get_meta(pos)`.
1000 * `get_string(name)`
1003 * `to_table()`: returns `nil` or a table with keys:
1004 * `fields`: key-value storage
1005 * `inventory`: `{list1 = {}, ...}}`
1009 * `minetest.get_node_def(nodename)`
1010 * Returns [node definition](#node-definition) table of `nodename`
1011 * `minetest.get_item_def(itemstring)`
1012 * Returns item definition table of `itemstring`
1014 #### Node Definition
1018 has_on_construct = bool, -- Whether the node has the on_construct callback defined
1019 has_on_destruct = bool, -- Whether the node has the on_destruct callback defined
1020 has_after_destruct = bool, -- Whether the node has the after_destruct callback defined
1021 name = string, -- The name of the node e.g. "air", "default:dirt"
1022 groups = table, -- The groups of the node
1023 paramtype = string, -- Paramtype of the node
1024 paramtype2 = string, -- ParamType2 of the node
1025 drawtype = string, -- Drawtype of the node
1026 mesh = <string>, -- Mesh name if existant
1027 minimap_color = <Color>, -- Color of node on minimap *May not exist*
1028 visual_scale = number, -- Visual scale of node
1029 alpha = number, -- Alpha of the node. Only used for liquids
1030 color = <Color>, -- Color of node *May not exist*
1031 palette_name = <string>, -- Filename of palette *May not exist*
1032 palette = <{ -- List of colors
1036 waving = number, -- 0 of not waving, 1 if waving
1037 connect_sides = number, -- Used for connected nodes
1038 connects_to = { -- List of nodes to connect to
1042 post_effect_color = Color, -- Color overlayed on the screen when the player is in the node
1043 leveled = number, -- Max level for node
1044 sunlight_propogates = bool, -- Whether light passes through the block
1045 light_source = number, -- Light emitted by the block
1046 is_ground_content = bool, -- Whether caves should cut through the node
1047 walkable = bool, -- Whether the player collides with the node
1048 pointable = bool, -- Whether the player can select the node
1049 diggable = bool, -- Whether the player can dig the node
1050 climbable = bool, -- Whether the player can climb up the node
1051 buildable_to = bool, -- Whether the player can replace the node by placing a node on it
1052 rightclickable = bool, -- Whether the player can place nodes pointing at this node
1053 damage_per_second = number, -- HP of damage per second when the player is in the node
1054 liquid_type = <string>, -- A string containing "none", "flowing", or "source" *May not exist*
1055 liquid_alternative_flowing = <string>, -- Alternative node for liquid *May not exist*
1056 liquid_alternative_source = <string>, -- Alternative node for liquid *May not exist*
1057 liquid_viscosity = <number>, -- How fast the liquid flows *May not exist*
1058 liquid_renewable = <boolean>, -- Whether the liquid makes an infinite source *May not exist*
1059 liquid_range = <number>, -- How far the liquid flows *May not exist*
1060 drowning = bool, -- Whether the player will drown in the node
1061 floodable = bool, -- Whether nodes will be replaced by liquids (flooded)
1062 node_box = table, -- Nodebox to draw the node with
1063 collision_box = table, -- Nodebox to set the collision area
1064 selection_box = table, -- Nodebox to set the area selected by the player
1065 sounds = { -- Table of sounds that the block makes
1066 sound_footstep = SimpleSoundSpec,
1067 sound_dig = SimpleSoundSpec,
1068 sound_dug = SimpleSoundSpec
1070 legacy_facedir_simple = bool, -- Whether to use old facedir
1071 legacy_wallmounted = bool -- Whether to use old wallmounted
1075 #### Item Definition
1079 name = string, -- Name of the item e.g. "default:stone"
1080 description = string, -- Description of the item e.g. "Stone"
1081 type = string, -- Item type: "none", "node", "craftitem", "tool"
1082 inventory_image = string, -- Image in the inventory
1083 wield_image = string, -- Image in wieldmesh
1084 palette_image = string, -- Image for palette
1085 color = Color, -- Color for item
1086 wield_scale = Vector, -- Wieldmesh scale
1087 stack_max = number, -- Number of items stackable together
1088 usable = bool, -- Has on_use callback defined
1089 liquids_pointable = bool, -- Whether you can point at liquids with the item
1090 tool_capabilities = <table>, -- If the item is a tool, tool capabiltites of the item
1091 groups = table, -- Groups of the item
1092 sound_place = SimpleSoundSpec, -- Sound played when placed
1093 sound_place_failed = SimpleSoundSpec, -- Sound played when placement failed
1094 node_placement_prediction = string -- Node placed in client until server catches up
1099 ### Chat command definition (`register_chatcommand`)
1102 params = "<name> <privilege>", -- Short parameter description
1103 description = "Remove privilege from player", -- Full description
1104 func = function(param), -- Called when command is run.
1105 -- Returns boolean success and text output.
1110 address = "minetest.example.org", -- The domain name/IP address of a remote server or "" for a local server.
1111 ip = "203.0.113.156", -- The IP address of the server.
1112 port = 30000, -- The port the client is connected to.
1113 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.
1119 Most text can contain escape sequences, that can for example color the text.
1120 There are a few exceptions: tab headers, dropdowns and vertical labels can't.
1121 The following functions provide escape sequences:
1122 * `minetest.get_color_escape_sequence(color)`:
1123 * `color` is a [ColorString](#colorstring)
1124 * The escape sequence sets the text color to `color`
1125 * `minetest.colorize(color, message)`:
1127 `minetest.get_color_escape_sequence(color) ..
1129 minetest.get_color_escape_sequence("#ffffff")`
1130 * `minetest.get_background_escape_sequence(color)`
1131 * `color` is a [ColorString](#colorstring)
1132 * The escape sequence sets the background of the whole text element to
1133 `color`. Only defined for item descriptions and tooltips.
1134 * `minetest.strip_foreground_colors(str)`
1135 * Removes foreground colors added by `get_color_escape_sequence`.
1136 * `minetest.strip_background_colors(str)`
1137 * Removes background colors added by `get_background_escape_sequence`.
1138 * `minetest.strip_colors(str)`
1139 * Removes all color escape sequences.
1143 `#RGB` defines a color in hexadecimal format.
1145 `#RGBA` defines a color in hexadecimal format and alpha channel.
1147 `#RRGGBB` defines a color in hexadecimal format.
1149 `#RRGGBBAA` defines a color in hexadecimal format and alpha channel.
1151 Named colors are also supported and are equivalent to
1152 [CSS Color Module Level 4](http://dev.w3.org/csswg/css-color/#named-colors).
1153 To specify the value of the alpha channel, append `#AA` to the end of the color name
1154 (e.g. `colorname#08`). For named colors the hexadecimal string representing the alpha
1155 value must (always) be two hexadecimal digits.
1159 `{a = alpha, r = red, g = green, b = blue}` defines an ARGB8 color.