1 Minetest Lua Client Modding API Reference 0.4.15
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: Not fully implemented yet.**
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:
161 -- Play locationless on all clients
163 gain = 1.0, -- default
165 -- Play locationless to one player
168 gain = 1.0, -- default
170 -- Play locationless to one player, looped
173 gain = 1.0, -- default
176 -- Play in a location
178 pos = {x = 1, y = 2, z = 3},
179 gain = 1.0, -- default
180 max_hear_distance = 32, -- default, uses an euclidean metric
182 -- Play connected to an object, looped
184 object = <an ObjectRef>,
185 gain = 1.0, -- default
186 max_hear_distance = 32, -- default, uses an euclidean metric
190 Looped sounds must either be connected to an object or played locationless to
191 one player using `to_player = name,`
195 * e.g. `"default_place_node"`
197 * e.g. `{name = "default_place_node"}`
198 * e.g. `{name = "default_place_node", gain = 1.0}`
200 Representations of simple things
201 --------------------------------
205 {x=num, y=num, z=num}
207 For helper functions see "Vector helpers".
211 * `{type="node", under=pos, above=pos}`
212 * `{type="object", ref=ObjectRef}`
214 Flag Specifier Format
215 ---------------------
216 Flags using the standardized flag specifier format can be specified in either of
217 two ways, by string or table.
219 The string format is a comma-delimited set of flag names; whitespace and
220 unrecognized flag fields are ignored. Specifying a flag in the string sets the
221 flag, and specifying a flag prefixed by the string `"no"` explicitly
222 clears the flag from whatever the default may be.
224 In addition to the standard string flag format, the schematic flags field can
225 also be a table of flag names to boolean values representing whether or not the
226 flag is set. Additionally, if a field with the flag name prefixed with `"no"`
227 is present, mapped to a boolean of any value, the specified flag is unset.
229 E.g. A flag field of value
231 {place_center_x = true, place_center_y=false, place_center_z=true}
235 {place_center_x = true, noplace_center_y=true, place_center_z=true}
237 which is equivalent to
239 "place_center_x, noplace_center_y, place_center_z"
243 "place_center_x, place_center_z"
245 since, by default, no schematic attributes are set.
249 Formspec defines a menu. It is a string, with a somewhat strange format.
251 Spaces and newlines can be inserted between the blocks, as is used in the
259 list[context;main;0,0;8,4;]
260 list[current_player;main;0,5;8,4;]
265 list[context;fuel;2,3;1,1;]
266 list[context;src;2,1;1,1;]
267 list[context;dst;5,1;2,2;]
268 list[current_player;main;0,5;8,4;]
270 #### Minecraft-like player inventory
273 image[1,0.6;1,2;player.png]
274 list[current_player;main;0,3.5;8,4;]
275 list[current_player;craft;3,0;3,3;]
276 list[current_player;craftpreview;7,1;1,1;]
280 #### `size[<W>,<H>,<fixed_size>]`
281 * Define the size of the menu in inventory slots
282 * `fixed_size`: `true`/`false` (optional)
283 * deprecated: `invsize[<W>,<H>;]`
285 #### `container[<X>,<Y>]`
286 * Start of a container block, moves all physical elements in the container by (X, Y)
287 * Must have matching container_end
288 * Containers can be nested, in which case the offsets are added
289 (child containers are relative to parent containers)
291 #### `container_end[]`
292 * End of a container, following elements are no longer relative to this container
294 #### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]`
295 * Show an inventory list
297 #### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]`
298 * Show an inventory list
300 #### `listring[<inventory location>;<list name>]`
301 * Allows to create a ring of inventory lists
302 * Shift-clicking on items in one element of the ring
303 will send them to the next inventory list inside the ring
304 * The first occurrence of an element inside the ring will
305 determine the inventory where items will be sent to
308 * Shorthand for doing `listring[<inventory location>;<list name>]`
309 for the last two inventory lists added by list[...]
311 #### `listcolors[<slot_bg_normal>;<slot_bg_hover>]`
312 * Sets background color of slots as `ColorString`
313 * Sets background color of slots on mouse hovering
315 #### `listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>]`
316 * Sets background color of slots as `ColorString`
317 * Sets background color of slots on mouse hovering
318 * Sets color of slots border
320 #### `listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>;<tooltip_bgcolor>;<tooltip_fontcolor>]`
321 * Sets background color of slots as `ColorString`
322 * Sets background color of slots on mouse hovering
323 * Sets color of slots border
324 * Sets default background color of tooltips
325 * Sets default font color of tooltips
327 #### `tooltip[<gui_element_name>;<tooltip_text>;<bgcolor>,<fontcolor>]`
328 * Adds tooltip for an element
329 * `<bgcolor>` tooltip background color as `ColorString` (optional)
330 * `<fontcolor>` tooltip font color as `ColorString` (optional)
332 #### `image[<X>,<Y>;<W>,<H>;<texture name>]`
334 * Position and size units are inventory slots
336 #### `item_image[<X>,<Y>;<W>,<H>;<item name>]`
337 * Show an inventory image of registered item/node
338 * Position and size units are inventory slots
340 #### `bgcolor[<color>;<fullscreen>]`
341 * Sets background color of formspec as `ColorString`
342 * If `true`, the background color is drawn fullscreen (does not effect the size of the formspec)
344 #### `background[<X>,<Y>;<W>,<H>;<texture name>]`
345 * Use a background. Inventory rectangles are not drawn then.
346 * Position and size units are inventory slots
347 * Example for formspec 8x4 in 16x resolution: image shall be sized
348 8 times 16px times 4 times 16px.
350 #### `background[<X>,<Y>;<W>,<H>;<texture name>;<auto_clip>]`
351 * Use a background. Inventory rectangles are not drawn then.
352 * Position and size units are inventory slots
353 * Example for formspec 8x4 in 16x resolution:
354 image shall be sized 8 times 16px times 4 times 16px
355 * If `true` the background is clipped to formspec size
356 (`x` and `y` are used as offset values, `w` and `h` are ignored)
358 #### `pwdfield[<X>,<Y>;<W>,<H>;<name>;<label>]`
359 * Textual password style field; will be sent to server when a button is clicked
360 * When enter is pressed in field, fields.key_enter_field will be sent with the name
362 * `x` and `y` position the field relative to the top left of the menu
363 * `w` and `h` are the size of the field
364 * Fields are a set height, but will be vertically centred on `h`
365 * Position and size units are inventory slots
366 * `name` is the name of the field as returned in fields to `on_receive_fields`
367 * `label`, if not blank, will be text printed on the top left above the field
368 * See field_close_on_enter to stop enter closing the formspec
370 #### `field[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`
371 * Textual field; will be sent to server when a button is clicked
372 * When enter is pressed in field, fields.key_enter_field will be sent with the name
374 * `x` and `y` position the field relative to the top left of the menu
375 * `w` and `h` are the size of the field
376 * Fields are a set height, but will be vertically centred on `h`
377 * Position and size units are inventory slots
378 * `name` is the name of the field as returned in fields to `on_receive_fields`
379 * `label`, if not blank, will be text printed on the top left above the field
380 * `default` is the default value of the field
381 * `default` may contain variable references such as `${text}'` which
382 will fill the value from the metadata value `text`
383 * **Note**: no extra text or more than a single variable is supported ATM.
384 * See field_close_on_enter to stop enter closing the formspec
386 #### `field[<name>;<label>;<default>]`
387 * As above, but without position/size units
388 * When enter is pressed in field, fields.key_enter_field will be sent with the name
390 * Special field for creating simple forms, such as sign text input
391 * Must be used without a `size[]` element
392 * A "Proceed" button will be added automatically
393 * See field_close_on_enter to stop enter closing the formspec
395 #### `field_close_on_enter[<name>;<close_on_enter>]`
396 * <name> is the name of the field
397 * if <close_on_enter> is false, pressing enter in the field will submit the form but not close it
398 * defaults to true when not specified (ie: no tag for a field)
400 #### `textarea[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`
401 * Same as fields above, but with multi-line input
403 #### `label[<X>,<Y>;<label>]`
404 * `x` and `y` work as per field
405 * `label` is the text on the label
406 * Position and size units are inventory slots
408 #### `vertlabel[<X>,<Y>;<label>]`
409 * Textual label drawn vertically
410 * `x` and `y` work as per field
411 * `label` is the text on the label
412 * Position and size units are inventory slots
414 #### `button[<X>,<Y>;<W>,<H>;<name>;<label>]`
415 * Clickable button. When clicked, fields will be sent.
416 * `x`, `y` and `name` work as per field
417 * `w` and `h` are the size of the button
418 * `label` is the text on the button
419 * Position and size units are inventory slots
421 #### `image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]`
422 * `x`, `y`, `w`, `h`, and `name` work as per button
423 * `texture name` is the filename of an image
424 * Position and size units are inventory slots
426 #### `image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>;<noclip>;<drawborder>;<pressed texture name>]`
427 * `x`, `y`, `w`, `h`, and `name` work as per button
428 * `texture name` is the filename of an image
429 * Position and size units are inventory slots
430 * `noclip=true` means the image button doesn't need to be within specified formsize
431 * `drawborder`: draw button border or not
432 * `pressed texture name` is the filename of an image on pressed state
434 #### `item_image_button[<X>,<Y>;<W>,<H>;<item name>;<name>;<label>]`
435 * `x`, `y`, `w`, `h`, `name` and `label` work as per button
436 * `item name` is the registered name of an item/node,
437 tooltip will be made out of its description
438 to override it use tooltip element
439 * Position and size units are inventory slots
441 #### `button_exit[<X>,<Y>;<W>,<H>;<name>;<label>]`
442 * When clicked, fields will be sent and the form will quit.
444 #### `image_button_exit[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]`
445 * When clicked, fields will be sent and the form will quit.
447 #### `textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>]`
448 * Scrollable item list showing arbitrary text elements
449 * `x` and `y` position the itemlist relative to the top left of the menu
450 * `w` and `h` are the size of the itemlist
451 * `name` fieldname sent to server on doubleclick value is current selected element
452 * `listelements` can be prepended by #color in hexadecimal format RRGGBB (only),
453 * if you want a listelement to start with "#" write "##".
455 #### `textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>;<selected idx>;<transparent>]`
456 * Scrollable itemlist showing arbitrary text elements
457 * `x` and `y` position the item list relative to the top left of the menu
458 * `w` and `h` are the size of the item list
459 * `name` fieldname sent to server on doubleclick value is current selected element
460 * `listelements` can be prepended by #RRGGBB (only) in hexadecimal format
461 * if you want a listelement to start with "#" write "##"
462 * Index to be selected within textlist
463 * `true`/`false`: draw transparent background
464 * See also `minetest.explode_textlist_event` (main menu: `engine.explode_textlist_event`)
466 #### `tabheader[<X>,<Y>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]`
467 * Show a tab**header** at specific position (ignores formsize)
468 * `x` and `y` position the itemlist relative to the top left of the menu
469 * `name` fieldname data is transferred to Lua
470 * `caption 1`...: name shown on top of tab
471 * `current_tab`: index of selected tab 1...
472 * `transparent` (optional): show transparent
473 * `draw_border` (optional): draw border
475 #### `box[<X>,<Y>;<W>,<H>;<color>]`
476 * Simple colored semitransparent box
477 * `x` and `y` position the box relative to the top left of the menu
478 * `w` and `h` are the size of box
479 * `color` is color specified as a `ColorString`
481 #### `dropdown[<X>,<Y>;<W>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>]`
482 * Show a dropdown field
483 * **Important note**: There are two different operation modes:
484 1. handle directly on change (only changed dropdown is submitted)
485 2. read the value on pressing a button (all dropdown values are available)
486 * `x` and `y` position of dropdown
488 * Fieldname data is transferred to Lua
489 * Items to be shown in dropdown
490 * Index of currently selected dropdown item
492 #### `checkbox[<X>,<Y>;<name>;<label>;<selected>]`
494 * `x` and `y`: position of checkbox
495 * `name` fieldname data is transferred to Lua
496 * `label` to be shown left of checkbox
497 * `selected` (optional): `true`/`false`
499 #### `scrollbar[<X>,<Y>;<W>,<H>;<orientation>;<name>;<value>]`
501 * There are two ways to use it:
502 1. handle the changed event (only changed scrollbar is available)
503 2. read the value on pressing a button (all scrollbars are available)
504 * `x` and `y`: position of trackbar
505 * `w` and `h`: width and height
506 * `orientation`: `vertical`/`horizontal`
507 * Fieldname data is transferred to Lua
508 * Value this trackbar is set to (`0`-`1000`)
509 * See also `minetest.explode_scrollbar_event` (main menu: `engine.explode_scrollbar_event`)
511 #### `table[<X>,<Y>;<W>,<H>;<name>;<cell 1>,<cell 2>,...,<cell n>;<selected idx>]`
512 * Show scrollable table using options defined by the previous `tableoptions[]`
513 * Displays cells as defined by the previous `tablecolumns[]`
514 * `x` and `y`: position the itemlist relative to the top left of the menu
515 * `w` and `h` are the size of the itemlist
516 * `name`: fieldname sent to server on row select or doubleclick
517 * `cell 1`...`cell n`: cell contents given in row-major order
518 * `selected idx`: index of row to be selected within table (first row = `1`)
519 * See also `minetest.explode_table_event` (main menu: `engine.explode_table_event`)
521 #### `tableoptions[<opt 1>;<opt 2>;...]`
522 * Sets options for `table[]`
524 * default text color (`ColorString`), defaults to `#FFFFFF`
525 * `background=#RRGGBB`
526 * table background color (`ColorString`), defaults to `#000000`
527 * `border=<true/false>`
528 * should the table be drawn with a border? (default: `true`)
529 * `highlight=#RRGGBB`
530 * highlight background color (`ColorString`), defaults to `#466432`
531 * `highlight_text=#RRGGBB`
532 * highlight text color (`ColorString`), defaults to `#FFFFFF`
533 * `opendepth=<value>`
534 * all subtrees up to `depth < value` are open (default value = `0`)
535 * only useful when there is a column of type "tree"
537 #### `tablecolumns[<type 1>,<opt 1a>,<opt 1b>,...;<type 2>,<opt 2a>,<opt 2b>;...]`
538 * Sets columns for `table[]`
539 * Types: `text`, `image`, `color`, `indent`, `tree`
540 * `text`: show cell contents as text
541 * `image`: cell contents are an image index, use column options to define images
542 * `color`: cell contents are a ColorString and define color of following cell
543 * `indent`: cell contents are a number and define indentation of following cell
544 * `tree`: same as indent, but user can open and close subtrees (treeview-like)
547 * for `text` and `image`: content alignment within cells.
548 Available values: `left` (default), `center`, `right`, `inline`
550 * for `text` and `image`: minimum width in em (default: `0`)
551 * for `indent` and `tree`: indent width in em (default: `1.5`)
552 * `padding=<value>`: padding left of the column, in em (default `0.5`).
553 Exception: defaults to 0 for indent columns
554 * `tooltip=<value>`: tooltip text (default: empty)
555 * `image` column options:
556 * `0=<value>` sets image for image index 0
557 * `1=<value>` sets image for image index 1
558 * `2=<value>` sets image for image index 2
559 * and so on; defined indices need not be contiguous empty or
560 non-numeric cells are treated as `0`.
561 * `color` column options:
562 * `span=<value>`: number of following columns to affect (default: infinite)
564 **Note**: do _not_ use a element name starting with `key_`; those names are reserved to
565 pass key press events to formspec!
569 * `vector.new(a[, b, c])`: returns a vector:
570 * A copy of `a` if `a` is a vector.
571 * `{x = a, y = b, z = c}`, if all `a, b, c` are defined
572 * `vector.direction(p1, p2)`: returns a vector
573 * `vector.distance(p1, p2)`: returns a number
574 * `vector.length(v)`: returns a number
575 * `vector.normalize(v)`: returns a vector
576 * `vector.floor(v)`: returns a vector, each dimension rounded down
577 * `vector.round(v)`: returns a vector, each dimension rounded to nearest int
578 * `vector.apply(v, func)`: returns a vector
579 * `vector.equals(v1, v2)`: returns a boolean
581 For the following functions `x` can be either a vector or a number:
583 * `vector.add(v, x)`: returns a vector
584 * `vector.subtract(v, x)`: returns a vector
585 * `vector.multiply(v, x)`: returns a scaled vector or Schur product
586 * `vector.divide(v, x)`: returns a scaled vector or Schur quotient
590 * `dump2(obj, name="_", dumped={})`
591 * Return object serialized as a string, handles reference loops
592 * `dump(obj, dumped={})`
593 * Return object serialized as a string
595 * Get the hypotenuse of a triangle with legs x and y.
596 Useful for distance calculation.
597 * `math.sign(x, tolerance)`
598 * Get the sign of a number.
599 Optional: Also returns `0` when the absolute value is within the tolerance (default: `0`)
600 * `string.split(str, separator=",", include_empty=false, max_splits=-1,
601 * sep_is_pattern=false)`
602 * If `max_splits` is negative, do not limit splits.
603 * `sep_is_pattern` specifies if separator is a plain string or a pattern (regex).
604 * e.g. `string:split("a,b", ",") == {"a","b"}`
606 * e.g. `string.trim("\n \t\tfoo bar\t ") == "foo bar"`
607 * `minetest.is_yes(arg)`
608 * returns whether `arg` can be interpreted as yes
609 * `minetest.get_us_time()`
610 * returns time with microsecond precision. May not return wall time.
611 * `table.copy(table)`: returns a table
612 * returns a deep copy of `table`
614 Minetest namespace reference
615 ------------------------------
619 * `minetest.get_current_modname()`: returns the currently loading mod's name, when we are loading a mod
620 * `minetest.get_version()`: returns a table containing components of the
621 engine version. Components:
622 * `project`: Name of the project, eg, "Minetest"
623 * `string`: Simple version, eg, "1.2.3-dev"
624 * `hash`: Full git version (only set if available), eg, "1.2.3-dev-01234567-dirty"
625 Use this for informational purposes only. The information in the returned
626 table does not represent the capabilities of the engine, nor is it
627 reliable or verifyable. Compatible forks will have a different name and
628 version entirely. To check for the presence of engine features, test
629 whether the functions exported by the wanted features exist. For example:
630 `if minetest.nodeupdate then ... end`.
633 * `minetest.debug(...)`
634 * Equivalent to `minetest.log(table.concat({...}, "\t"))`
635 * `minetest.log([level,] text)`
636 * `level` is one of `"none"`, `"error"`, `"warning"`, `"action"`,
637 `"info"`, or `"verbose"`. Default is `"none"`.
639 ### Global callback registration functions
640 Call these functions only at load time!
642 * `minetest.register_globalstep(func(dtime))`
643 * Called every client environment step, usually interval of 0.1s
644 * `minetest.register_on_shutdown(func())`
645 * Called before client shutdown
646 * **Warning**: If the client terminates abnormally (i.e. crashes), the registered
647 callbacks **will likely not be run**. Data should be saved at
648 semi-frequent intervals as well as on server shutdown.
649 * `minetest.register_on_receiving_chat_message(func(name, message))`
650 * Called always when a client receive a message
651 * Return `true` to mark the message as handled, which means that it will not be shown to chat
652 * `minetest.register_on_sending_chat_message(func(name, message))`
653 * Called always when a client send a message from chat
654 * Return `true` to mark the message as handled, which means that it will not be sent to server
655 * `minetest.register_chatcommand(cmd, chatcommand definition)`
656 * Adds definition to minetest.registered_chatcommands
657 * `minetest.register_on_death(func())`
658 * Called when the local player dies
659 * `minetest.register_on_hp_modification(func(hp))`
660 * Called when server modified player's HP
661 * `minetest.register_on_damage_taken(func(hp))`
662 * Called when the local player take damages
663 * `minetest.register_on_formspec_input(func(formname, fields))`
664 * Called when a button is pressed in the local player's inventory form
665 * Newest functions are called first
666 * If function returns `true`, remaining functions are not called
667 * `minetest.register_on_dignode(func(pos, node))`
668 * Called when the local player digs a node
669 * Newest functions are called first
670 * If any function returns true, the node isn't dug
671 * `minetest.register_on_punchnode(func(pos, node))`
672 * Called when the local player punches a node
673 * Newest functions are called first
674 * If any function returns true, the punch is ignored
676 * `minetest.sound_play(spec, parameters)`: returns a handle
677 * `spec` is a `SimpleSoundSpec`
678 * `parameters` is a sound parameter table
679 * `minetest.sound_stop(handle)`
682 * `minetest.after(time, func, ...)`
683 * Call the function `func` after `time` seconds, may be fractional
684 * Optional: Variable number of arguments that are passed to `func`
687 * `minetest.get_node(pos)`
688 * Returns the node at the given position as table in the format
689 `{name="node_name", param1=0, param2=0}`, returns `{name="ignore", param1=0, param2=0}`
691 * `minetest.get_node_or_nil(pos)`
692 * Same as `get_node` but returns `nil` for unloaded areas.
695 * `minetest.get_wielded_item()`
696 * Returns the itemstack the local player is holding
698 ### Client Environment
699 * `minetest.get_player_names()`
700 * Returns list of player names on server
701 * `minetest.disconnect()`
702 * Disconnect from the server and exit to main menu.
703 * Returns `false` if the client is already disconnecting otherwise returns `true`.
706 * `minetest.parse_json(string[, nullvalue])`: returns something
707 * Convert a string containing JSON data into the Lua equivalent
708 * `nullvalue`: returned in place of the JSON null; defaults to `nil`
709 * On success returns a table, a string, a number, a boolean or `nullvalue`
710 * On failure outputs an error message and returns `nil`
711 * Example: `parse_json("[10, {\"a\":false}]")`, returns `{10, {a = false}}`
712 * `minetest.write_json(data[, styled])`: returns a string or `nil` and an error message
713 * Convert a Lua table into a JSON string
714 * styled: Outputs in a human-readable format if this is set, defaults to false
715 * Unserializable things like functions and userdata are saved as null.
716 * **Warning**: JSON is more strict than the Lua table format.
717 1. You can only use strings and positive integers of at least one as keys.
718 2. You can not mix string and integer keys.
719 This is due to the fact that JSON has two distinct array and object values.
720 * Example: `write_json({10, {a = false}})`, returns `"[10, {\"a\": false}]"`
721 * `minetest.serialize(table)`: returns a string
722 * Convert a table containing tables, strings, numbers, booleans and `nil`s
723 into string form readable by `minetest.deserialize`
724 * Example: `serialize({foo='bar'})`, returns `'return { ["foo"] = "bar" }'`
725 * `minetest.deserialize(string)`: returns a table
726 * Convert a string returned by `minetest.deserialize` into a table
727 * `string` is loaded in an empty sandbox environment.
728 * Will load functions, but they cannot access the global environment.
729 * Example: `deserialize('return { ["foo"] = "bar" }')`, returns `{foo='bar'}`
730 * Example: `deserialize('print("foo")')`, returns `nil` (function call fails)
731 * `error:[string "print("foo")"]:1: attempt to call global 'print' (a nil value)`
732 * `minetest.compress(data, method, ...)`: returns `compressed_data`
733 * Compress a string of data.
734 * `method` is a string identifying the compression method to be used.
735 * Supported compression methods:
736 * Deflate (zlib): `"deflate"`
737 * `...` indicates method-specific arguments. Currently defined arguments are:
738 * Deflate: `level` - Compression level, `0`-`9` or `nil`.
739 * `minetest.decompress(compressed_data, method, ...)`: returns data
740 * Decompress a string of data (using ZLib).
741 * See documentation on `minetest.compress()` for supported compression methods.
742 * currently supported.
743 * `...` indicates method-specific arguments. Currently, no methods use this.
744 * `minetest.encode_base64(string)`: returns string encoded in base64
745 * Encodes a string in base64.
746 * `minetest.decode_base64(string)`: returns string
747 * Decodes a string encoded in base64.
748 * `minetest.gettext(string) : returns string
749 * look up the translation of a string in the gettext message catalog
750 * `fgettext_ne(string, ...)`
751 * call minetest.gettext(string), replace "$1"..."$9" with the given
752 extra arguments and return the result
753 * `fgettext(string, ...)` : returns string
754 * same as fgettext_ne(), but calls minetest.formspec_escape before returning result
757 * `minetest.ui.minimap`
758 * Reference to the minimap object. See `Minimap` class reference for methods.
759 * `minetest.show_formspec(formname, formspec)` : returns true on success
760 * Shows a formspec to the player
761 * `minetest.display_chat_message(message)` returns true on success
762 * Shows a chat message to the current player.
768 An interface to manipulate minimap on client UI
770 * `show()`: shows the minimap (if not disabled by server)
771 * `hide()`: hides the minimap
772 * `set_pos(pos)`: sets the minimap position on screen
773 * `get_pos()`: returns the minimap current position
774 * `set_angle(deg)`: sets the minimap angle in degrees
775 * `get_angle()`: returns the current minimap angle in degrees
776 * `set_mode(mode)`: sets the minimap mode (0 to 6)
777 * `get_mode()`: returns the current minimap mode
778 * `toggle_shape()`: toggles minimap shape to round or square.
781 An interface to read config files in the format of `minetest.conf`.
783 It can be created via `Settings(filename)`.
786 * `get(key)`: returns a value
787 * `get_bool(key)`: returns a boolean
789 * `remove(key)`: returns a boolean (`true` for success)
790 * `get_names()`: returns `{key1,...}`
791 * `write()`: returns a boolean (`true` for success)
792 * write changes to file
793 * `to_table()`: returns `{[key1]=value1,...}`
798 ### Chat command definition (`register_chatcommand`)
801 params = "<name> <privilege>", -- Short parameter description
802 description = "Remove privilege from player", -- Full description
803 func = function(param), -- Called when command is run.
804 -- Returns boolean success and text output.
809 Most text can contain escape sequences, that can for example color the text.
810 There are a few exceptions: tab headers, dropdowns and vertical labels can't.
811 The following functions provide escape sequences:
812 * `minetest.get_color_escape_sequence(color)`:
813 * `color` is a ColorString
814 * The escape sequence sets the text color to `color`
815 * `minetest.colorize(color, message)`:
817 `minetest.get_color_escape_sequence(color) ..
819 minetest.get_color_escape_sequence("#ffffff")`
820 * `color.get_background_escape_sequence(color)`
821 * `color` is a ColorString
822 * The escape sequence sets the background of the whole text element to
823 `color`. Only defined for item descriptions and tooltips.
824 * `color.strip_foreground_colors(str)`
825 * Removes foreground colors added by `get_color_escape_sequence`.
826 * `color.strip_background_colors(str)`
827 * Removes background colors added by `get_background_escape_sequence`.
828 * `color.strip_colors(str)`
829 * Removes all color escape sequences.
833 `#RGB` defines a color in hexadecimal format.
835 `#RGBA` defines a color in hexadecimal format and alpha channel.
837 `#RRGGBB` defines a color in hexadecimal format.
839 `#RRGGBBAA` defines a color in hexadecimal format and alpha channel.
841 Named colors are also supported and are equivalent to
842 [CSS Color Module Level 4](http://dev.w3.org/csswg/css-color/#named-colors).
843 To specify the value of the alpha channel, append `#AA` to the end of the color name
844 (e.g. `colorname#08`). For named colors the hexadecimal string representing the alpha
845 value must (always) be two hexadecimal digits.