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 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 Mods are contained and ran solely on the server side. Definitions and media
18 files are automatically transferred to the client.
20 If you see a deficiency in the API, feel free to attempt to add the
21 functionality in the engine and API. You can send such improvements as
22 source code patches on GitHub (https://github.com/minetest/minetest).
26 If you have any difficulty in understanding this, please read
27 [Programming in Lua](http://www.lua.org/pil/).
31 Mods are loaded during client startup from the mod load paths by running
32 the `init.lua` scripts in a shared environment.
36 * `RUN_IN_PLACE=1` (Windows release, local build)
38 * Linux: `<build directory>`
39 * Windows: `<build directory>`
41 * Linux: `<build directory>`
42 * Windows: `<build directory>`
43 * `RUN_IN_PLACE=0`: (Linux release)
45 * Linux: `/usr/share/minetest`
46 * Windows: `<install directory>/minetest-0.4.x`
48 * Linux: `$HOME/.minetest`
49 * Windows: `C:/users/<user>/AppData/minetest` (maybe)
55 * `$path_share/clientmods/`
56 * `$path_user/clientmods/` (User-installed mods)
58 In a run-in-place version (e.g. the distributed windows version):
60 * `minetest-0.4.x/clientmods/` (User-installed mods)
62 On an installed version on Linux:
64 * `/usr/share/minetest/clientmods/`
65 * `$HOME/.minetest/clientmods/` (User-installed mods)
69 Mods can be put in a subdirectory, if the parent directory, which otherwise
70 should be a mod, contains a file named `modpack.txt`. This file shall be
71 empty, except for lines starting with `#`, which are comments.
73 Mod directory structure
74 ------------------------
81 | |-- settingtypes.txt
85 | | |-- modname_stuff.png
86 | | `-- modname_something_else.png
94 The location of this directory can be fetched by using
95 `minetest.get_modpath(modname)`.
98 List of mods that have to be loaded before loading this mod.
100 A single line contains a single modname.
102 Optional dependencies can be defined by appending a question mark
103 to a single modname. Their meaning is that if the specified mod
104 is missing, that does not prevent this mod from being loaded.
107 A screenshot shown in the mod manager within the main menu. It should
108 have an aspect ratio of 3:2 and a minimum size of 300×200 pixels.
110 ### `description.txt`
111 A File containing description to be shown within mainmenu.
113 ### `settingtypes.txt`
114 A file in the same format as the one in builtin. It will be parsed by the
115 settings menu and the settings will be displayed in the "Mods" category.
118 The main Lua script. Running this script should register everything it
119 wants to register. Subsequent execution depends on minetest calling the
120 registered callbacks.
122 `minetest.setting_get(name)` and `minetest.setting_getbool(name)` can be used
123 to read custom or existing settings at load time, if necessary.
126 Media files (sounds) that will be transferred to the
127 client and will be available for use by the mod.
129 Naming convention for registered textual names
130 ----------------------------------------------
131 Registered names should generally be in this format:
133 "modname:<whatever>" (<whatever> can have characters a-zA-Z0-9_)
135 This is to prevent conflicting names from corrupting maps and is
136 enforced by the mod loader.
139 In the mod `experimental`, there is the ideal item/node/entity name `tnt`.
140 So the name should be `experimental:tnt`.
142 Enforcement can be overridden by prefixing the name with `:`. This can
143 be used for overriding the registrations of some other mod.
145 Example: Any mod can redefine `experimental:tnt` by using the name
150 (also that mod is required to have `experimental` as a dependency)
152 The `:` prefix can also be used for maintaining backwards compatibility.
155 Aliases can be added by using `minetest.register_alias(name, convert_to)` or
156 `minetest.register_alias_force(name, convert_to).
158 This will make Minetest to convert things called name to things called
161 The only difference between `minetest.register_alias` and
162 `minetest.register_alias_force` is that if an item called `name` exists,
163 `minetest.register_alias` will do nothing while
164 `minetest.register_alias_force` will unregister it.
166 This can be used for maintaining backwards compatibility.
168 This can be also used for setting quick access names for things, e.g. if
169 you have an item called `epiclylongmodname:stuff`, you could do
171 minetest.register_alias("stuff", "epiclylongmodname:stuff")
173 and be able to use `/giveme stuff`.
177 Only Ogg Vorbis files are supported.
179 For positional playing of sounds, only single-channel (mono) files are
180 supported. Otherwise OpenAL will play them non-positionally.
182 Mods should generally prefix their sounds with `modname_`, e.g. given
183 the mod name "`foomod`", a sound could be called:
187 Sounds are referred to by their name with a dot, a single digit and the
188 file extension stripped out. When a sound is played, the actual sound file
189 is chosen randomly from the matching sounds.
191 When playing the sound `foomod_foosound`, the sound is chosen randomly
192 from the available ones of the following files:
194 * `foomod_foosound.ogg`
195 * `foomod_foosound.0.ogg`
196 * `foomod_foosound.1.ogg`
198 * `foomod_foosound.9.ogg`
200 Examples of sound parameter tables:
202 -- Play locationless on all clients
204 gain = 1.0, -- default
206 -- Play locationless to one player
209 gain = 1.0, -- default
211 -- Play locationless to one player, looped
214 gain = 1.0, -- default
217 -- Play in a location
219 pos = {x = 1, y = 2, z = 3},
220 gain = 1.0, -- default
221 max_hear_distance = 32, -- default, uses an euclidean metric
223 -- Play connected to an object, looped
225 object = <an ObjectRef>,
226 gain = 1.0, -- default
227 max_hear_distance = 32, -- default, uses an euclidean metric
231 Looped sounds must either be connected to an object or played locationless to
232 one player using `to_player = name,`
234 ### `SimpleSoundSpec`
236 * e.g. `"default_place_node"`
238 * e.g. `{name = "default_place_node"}`
239 * e.g. `{name = "default_place_node", gain = 1.0}`
241 Representations of simple things
242 --------------------------------
246 {x=num, y=num, z=num}
248 For helper functions see "Vector helpers".
252 * `{type="node", under=pos, above=pos}`
253 * `{type="object", ref=ObjectRef}`
255 Flag Specifier Format
256 ---------------------
257 Flags using the standardized flag specifier format can be specified in either of
258 two ways, by string or table.
260 The string format is a comma-delimited set of flag names; whitespace and
261 unrecognized flag fields are ignored. Specifying a flag in the string sets the
262 flag, and specifying a flag prefixed by the string `"no"` explicitly
263 clears the flag from whatever the default may be.
265 In addition to the standard string flag format, the schematic flags field can
266 also be a table of flag names to boolean values representing whether or not the
267 flag is set. Additionally, if a field with the flag name prefixed with `"no"`
268 is present, mapped to a boolean of any value, the specified flag is unset.
270 E.g. A flag field of value
272 {place_center_x = true, place_center_y=false, place_center_z=true}
276 {place_center_x = true, noplace_center_y=true, place_center_z=true}
278 which is equivalent to
280 "place_center_x, noplace_center_y, place_center_z"
284 "place_center_x, place_center_z"
286 since, by default, no schematic attributes are set.
290 Formspec defines a menu. Currently not much else than inventories are
291 supported. It is a string, with a somewhat strange format.
293 Spaces and newlines can be inserted between the blocks, as is used in the
301 list[context;main;0,0;8,4;]
302 list[current_player;main;0,5;8,4;]
307 list[context;fuel;2,3;1,1;]
308 list[context;src;2,1;1,1;]
309 list[context;dst;5,1;2,2;]
310 list[current_player;main;0,5;8,4;]
312 #### Minecraft-like player inventory
315 image[1,0.6;1,2;player.png]
316 list[current_player;main;0,3.5;8,4;]
317 list[current_player;craft;3,0;3,3;]
318 list[current_player;craftpreview;7,1;1,1;]
322 #### `size[<W>,<H>,<fixed_size>]`
323 * Define the size of the menu in inventory slots
324 * `fixed_size`: `true`/`false` (optional)
325 * deprecated: `invsize[<W>,<H>;]`
327 #### `container[<X>,<Y>]`
328 * Start of a container block, moves all physical elements in the container by (X, Y)
329 * Must have matching container_end
330 * Containers can be nested, in which case the offsets are added
331 (child containers are relative to parent containers)
333 #### `container_end[]`
334 * End of a container, following elements are no longer relative to this container
336 #### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]`
337 * Show an inventory list
339 #### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]`
340 * Show an inventory list
342 #### `listring[<inventory location>;<list name>]`
343 * Allows to create a ring of inventory lists
344 * Shift-clicking on items in one element of the ring
345 will send them to the next inventory list inside the ring
346 * The first occurrence of an element inside the ring will
347 determine the inventory where items will be sent to
350 * Shorthand for doing `listring[<inventory location>;<list name>]`
351 for the last two inventory lists added by list[...]
353 #### `listcolors[<slot_bg_normal>;<slot_bg_hover>]`
354 * Sets background color of slots as `ColorString`
355 * Sets background color of slots on mouse hovering
357 #### `listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>]`
358 * Sets background color of slots as `ColorString`
359 * Sets background color of slots on mouse hovering
360 * Sets color of slots border
362 #### `listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>;<tooltip_bgcolor>;<tooltip_fontcolor>]`
363 * Sets background color of slots as `ColorString`
364 * Sets background color of slots on mouse hovering
365 * Sets color of slots border
366 * Sets default background color of tooltips
367 * Sets default font color of tooltips
369 #### `tooltip[<gui_element_name>;<tooltip_text>;<bgcolor>,<fontcolor>]`
370 * Adds tooltip for an element
371 * `<bgcolor>` tooltip background color as `ColorString` (optional)
372 * `<fontcolor>` tooltip font color as `ColorString` (optional)
374 #### `image[<X>,<Y>;<W>,<H>;<texture name>]`
376 * Position and size units are inventory slots
378 #### `item_image[<X>,<Y>;<W>,<H>;<item name>]`
379 * Show an inventory image of registered item/node
380 * Position and size units are inventory slots
382 #### `bgcolor[<color>;<fullscreen>]`
383 * Sets background color of formspec as `ColorString`
384 * If `true`, the background color is drawn fullscreen (does not effect the size of the formspec)
386 #### `background[<X>,<Y>;<W>,<H>;<texture name>]`
387 * Use a background. Inventory rectangles are not drawn then.
388 * Position and size units are inventory slots
389 * Example for formspec 8x4 in 16x resolution: image shall be sized
390 8 times 16px times 4 times 16px.
392 #### `background[<X>,<Y>;<W>,<H>;<texture name>;<auto_clip>]`
393 * Use a background. Inventory rectangles are not drawn then.
394 * Position and size units are inventory slots
395 * Example for formspec 8x4 in 16x resolution:
396 image shall be sized 8 times 16px times 4 times 16px
397 * If `true` the background is clipped to formspec size
398 (`x` and `y` are used as offset values, `w` and `h` are ignored)
400 #### `pwdfield[<X>,<Y>;<W>,<H>;<name>;<label>]`
401 * Textual password style field; will be sent to server when a button is clicked
402 * When enter is pressed in field, fields.key_enter_field will be sent with the name
404 * `x` and `y` position the field relative to the top left of the menu
405 * `w` and `h` are the size of the field
406 * Fields are a set height, but will be vertically centred on `h`
407 * Position and size units are inventory slots
408 * `name` is the name of the field as returned in fields to `on_receive_fields`
409 * `label`, if not blank, will be text printed on the top left above the field
410 * See field_close_on_enter to stop enter closing the formspec
412 #### `field[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`
413 * Textual field; will be sent to server when a button is clicked
414 * When enter is pressed in field, fields.key_enter_field will be sent with the name
416 * `x` and `y` position the field relative to the top left of the menu
417 * `w` and `h` are the size of the field
418 * Fields are a set height, but will be vertically centred on `h`
419 * Position and size units are inventory slots
420 * `name` is the name of the field as returned in fields to `on_receive_fields`
421 * `label`, if not blank, will be text printed on the top left above the field
422 * `default` is the default value of the field
423 * `default` may contain variable references such as `${text}'` which
424 will fill the value from the metadata value `text`
425 * **Note**: no extra text or more than a single variable is supported ATM.
426 * See field_close_on_enter to stop enter closing the formspec
428 #### `field[<name>;<label>;<default>]`
429 * As above, but without position/size units
430 * When enter is pressed in field, fields.key_enter_field will be sent with the name
432 * Special field for creating simple forms, such as sign text input
433 * Must be used without a `size[]` element
434 * A "Proceed" button will be added automatically
435 * See field_close_on_enter to stop enter closing the formspec
437 #### `field_close_on_enter[<name>;<close_on_enter>]`
438 * <name> is the name of the field
439 * if <close_on_enter> is false, pressing enter in the field will submit the form but not close it
440 * defaults to true when not specified (ie: no tag for a field)
442 #### `textarea[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`
443 * Same as fields above, but with multi-line input
445 #### `label[<X>,<Y>;<label>]`
446 * `x` and `y` work as per field
447 * `label` is the text on the label
448 * Position and size units are inventory slots
450 #### `vertlabel[<X>,<Y>;<label>]`
451 * Textual label drawn vertically
452 * `x` and `y` work as per field
453 * `label` is the text on the label
454 * Position and size units are inventory slots
456 #### `button[<X>,<Y>;<W>,<H>;<name>;<label>]`
457 * Clickable button. When clicked, fields will be sent.
458 * `x`, `y` and `name` work as per field
459 * `w` and `h` are the size of the button
460 * `label` is the text on the button
461 * Position and size units are inventory slots
463 #### `image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]`
464 * `x`, `y`, `w`, `h`, and `name` work as per button
465 * `texture name` is the filename of an image
466 * Position and size units are inventory slots
468 #### `image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>;<noclip>;<drawborder>;<pressed texture name>]`
469 * `x`, `y`, `w`, `h`, and `name` work as per button
470 * `texture name` is the filename of an image
471 * Position and size units are inventory slots
472 * `noclip=true` means the image button doesn't need to be within specified formsize
473 * `drawborder`: draw button border or not
474 * `pressed texture name` is the filename of an image on pressed state
476 #### `item_image_button[<X>,<Y>;<W>,<H>;<item name>;<name>;<label>]`
477 * `x`, `y`, `w`, `h`, `name` and `label` work as per button
478 * `item name` is the registered name of an item/node,
479 tooltip will be made out of its description
480 to override it use tooltip element
481 * Position and size units are inventory slots
483 #### `button_exit[<X>,<Y>;<W>,<H>;<name>;<label>]`
484 * When clicked, fields will be sent and the form will quit.
486 #### `image_button_exit[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]`
487 * When clicked, fields will be sent and the form will quit.
489 #### `textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>]`
490 * Scrollable item list showing arbitrary text elements
491 * `x` and `y` position the itemlist relative to the top left of the menu
492 * `w` and `h` are the size of the itemlist
493 * `name` fieldname sent to server on doubleclick value is current selected element
494 * `listelements` can be prepended by #color in hexadecimal format RRGGBB (only),
495 * if you want a listelement to start with "#" write "##".
497 #### `textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>;<selected idx>;<transparent>]`
498 * Scrollable itemlist showing arbitrary text elements
499 * `x` and `y` position the item list relative to the top left of the menu
500 * `w` and `h` are the size of the item list
501 * `name` fieldname sent to server on doubleclick value is current selected element
502 * `listelements` can be prepended by #RRGGBB (only) in hexadecimal format
503 * if you want a listelement to start with "#" write "##"
504 * Index to be selected within textlist
505 * `true`/`false`: draw transparent background
506 * See also `minetest.explode_textlist_event` (main menu: `engine.explode_textlist_event`)
508 #### `tabheader[<X>,<Y>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]`
509 * Show a tab**header** at specific position (ignores formsize)
510 * `x` and `y` position the itemlist relative to the top left of the menu
511 * `name` fieldname data is transferred to Lua
512 * `caption 1`...: name shown on top of tab
513 * `current_tab`: index of selected tab 1...
514 * `transparent` (optional): show transparent
515 * `draw_border` (optional): draw border
517 #### `box[<X>,<Y>;<W>,<H>;<color>]`
518 * Simple colored semitransparent box
519 * `x` and `y` position the box relative to the top left of the menu
520 * `w` and `h` are the size of box
521 * `color` is color specified as a `ColorString`
523 #### `dropdown[<X>,<Y>;<W>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>]`
524 * Show a dropdown field
525 * **Important note**: There are two different operation modes:
526 1. handle directly on change (only changed dropdown is submitted)
527 2. read the value on pressing a button (all dropdown values are available)
528 * `x` and `y` position of dropdown
530 * Fieldname data is transferred to Lua
531 * Items to be shown in dropdown
532 * Index of currently selected dropdown item
534 #### `checkbox[<X>,<Y>;<name>;<label>;<selected>]`
536 * `x` and `y`: position of checkbox
537 * `name` fieldname data is transferred to Lua
538 * `label` to be shown left of checkbox
539 * `selected` (optional): `true`/`false`
541 #### `scrollbar[<X>,<Y>;<W>,<H>;<orientation>;<name>;<value>]`
543 * There are two ways to use it:
544 1. handle the changed event (only changed scrollbar is available)
545 2. read the value on pressing a button (all scrollbars are available)
546 * `x` and `y`: position of trackbar
547 * `w` and `h`: width and height
548 * `orientation`: `vertical`/`horizontal`
549 * Fieldname data is transferred to Lua
550 * Value this trackbar is set to (`0`-`1000`)
551 * See also `minetest.explode_scrollbar_event` (main menu: `engine.explode_scrollbar_event`)
553 #### `table[<X>,<Y>;<W>,<H>;<name>;<cell 1>,<cell 2>,...,<cell n>;<selected idx>]`
554 * Show scrollable table using options defined by the previous `tableoptions[]`
555 * Displays cells as defined by the previous `tablecolumns[]`
556 * `x` and `y`: position the itemlist relative to the top left of the menu
557 * `w` and `h` are the size of the itemlist
558 * `name`: fieldname sent to server on row select or doubleclick
559 * `cell 1`...`cell n`: cell contents given in row-major order
560 * `selected idx`: index of row to be selected within table (first row = `1`)
561 * See also `minetest.explode_table_event` (main menu: `engine.explode_table_event`)
563 #### `tableoptions[<opt 1>;<opt 2>;...]`
564 * Sets options for `table[]`
566 * default text color (`ColorString`), defaults to `#FFFFFF`
567 * `background=#RRGGBB`
568 * table background color (`ColorString`), defaults to `#000000`
569 * `border=<true/false>`
570 * should the table be drawn with a border? (default: `true`)
571 * `highlight=#RRGGBB`
572 * highlight background color (`ColorString`), defaults to `#466432`
573 * `highlight_text=#RRGGBB`
574 * highlight text color (`ColorString`), defaults to `#FFFFFF`
575 * `opendepth=<value>`
576 * all subtrees up to `depth < value` are open (default value = `0`)
577 * only useful when there is a column of type "tree"
579 #### `tablecolumns[<type 1>,<opt 1a>,<opt 1b>,...;<type 2>,<opt 2a>,<opt 2b>;...]`
580 * Sets columns for `table[]`
581 * Types: `text`, `image`, `color`, `indent`, `tree`
582 * `text`: show cell contents as text
583 * `image`: cell contents are an image index, use column options to define images
584 * `color`: cell contents are a ColorString and define color of following cell
585 * `indent`: cell contents are a number and define indentation of following cell
586 * `tree`: same as indent, but user can open and close subtrees (treeview-like)
589 * for `text` and `image`: content alignment within cells.
590 Available values: `left` (default), `center`, `right`, `inline`
592 * for `text` and `image`: minimum width in em (default: `0`)
593 * for `indent` and `tree`: indent width in em (default: `1.5`)
594 * `padding=<value>`: padding left of the column, in em (default `0.5`).
595 Exception: defaults to 0 for indent columns
596 * `tooltip=<value>`: tooltip text (default: empty)
597 * `image` column options:
598 * `0=<value>` sets image for image index 0
599 * `1=<value>` sets image for image index 1
600 * `2=<value>` sets image for image index 2
601 * and so on; defined indices need not be contiguous empty or
602 non-numeric cells are treated as `0`.
603 * `color` column options:
604 * `span=<value>`: number of following columns to affect (default: infinite)
606 **Note**: do _not_ use a element name starting with `key_`; those names are reserved to
607 pass key press events to formspec!
611 * `vector.new(a[, b, c])`: returns a vector:
612 * A copy of `a` if `a` is a vector.
613 * `{x = a, y = b, z = c}`, if all `a, b, c` are defined
614 * `vector.direction(p1, p2)`: returns a vector
615 * `vector.distance(p1, p2)`: returns a number
616 * `vector.length(v)`: returns a number
617 * `vector.normalize(v)`: returns a vector
618 * `vector.floor(v)`: returns a vector, each dimension rounded down
619 * `vector.round(v)`: returns a vector, each dimension rounded to nearest int
620 * `vector.apply(v, func)`: returns a vector
621 * `vector.equals(v1, v2)`: returns a boolean
623 For the following functions `x` can be either a vector or a number:
625 * `vector.add(v, x)`: returns a vector
626 * `vector.subtract(v, x)`: returns a vector
627 * `vector.multiply(v, x)`: returns a scaled vector or Schur product
628 * `vector.divide(v, x)`: returns a scaled vector or Schur quotient
632 * `dump2(obj, name="_", dumped={})`
633 * Return object serialized as a string, handles reference loops
634 * `dump(obj, dumped={})`
635 * Return object serialized as a string
637 * Get the hypotenuse of a triangle with legs x and y.
638 Useful for distance calculation.
639 * `math.sign(x, tolerance)`
640 * Get the sign of a number.
641 Optional: Also returns `0` when the absolute value is within the tolerance (default: `0`)
642 * `string.split(str, separator=",", include_empty=false, max_splits=-1,
643 * sep_is_pattern=false)`
644 * If `max_splits` is negative, do not limit splits.
645 * `sep_is_pattern` specifies if separator is a plain string or a pattern (regex).
646 * e.g. `string:split("a,b", ",") == {"a","b"}`
648 * e.g. `string.trim("\n \t\tfoo bar\t ") == "foo bar"`
649 * `minetest.is_yes(arg)`
650 * returns whether `arg` can be interpreted as yes
651 * `minetest.get_us_time()`
652 * returns time with microsecond precision. May not return wall time.
653 * `table.copy(table)`: returns a table
654 * returns a deep copy of `table`
656 `minetest` namespace reference
657 ------------------------------
661 * `minetest.get_current_modname()`: returns the currently loading mod's name, when we are loading a mod
662 * `minetest.get_version()`: returns a table containing components of the
663 engine version. Components:
664 * `project`: Name of the project, eg, "Minetest"
665 * `string`: Simple version, eg, "1.2.3-dev"
666 * `hash`: Full git version (only set if available), eg, "1.2.3-dev-01234567-dirty"
667 Use this for informational purposes only. The information in the returned
668 table does not represent the capabilities of the engine, nor is it
669 reliable or verifyable. Compatible forks will have a different name and
670 version entirely. To check for the presence of engine features, test
671 whether the functions exported by the wanted features exist. For example:
672 `if core.nodeupdate then ... end`.
675 * `minetest.debug(...)`
676 * Equivalent to `minetest.log(table.concat({...}, "\t"))`
677 * `minetest.log([level,] text)`
678 * `level` is one of `"none"`, `"error"`, `"warning"`, `"action"`,
679 `"info"`, or `"verbose"`. Default is `"none"`.
681 ### Global callback registration functions
682 Call these functions only at load time!
684 * `minetest.register_globalstep(func(dtime))`
685 * Called every client environment step, usually interval of 0.1s
686 * `minetest.register_on_shutdown(func())`
687 * Called before client shutdown
688 * **Warning**: If the client terminates abnormally (i.e. crashes), the registered
689 callbacks **will likely not be run**. Data should be saved at
690 semi-frequent intervals as well as on server shutdown.
691 * `minetest.register_on_receiving_chat_message(func(name, message))`
692 * Called always when a client receive a message
693 * Return `true` to mark the message as handled, which means that it will not be shown to chat
694 * `minetest.register_on_sending_chat_message(func(name, message))`
695 * Called always when a client send a message from chat
696 * Return `true` to mark the message as handled, which means that it will not be sent to server
697 * `minetest.register_chatcommand(cmd, chatcommand definition)`
698 * Adds definition to minetest.registered_chatcommands
699 * `minetest.register_on_death(func())`
700 * Called when the local player dies
701 * `minetest.register_on_hp_modification(func(hp))`
702 * Called when server modified player's HP
703 * `minetest.register_on_damage_taken(func(hp))`
704 * Called when the local player take damages
705 * `minetest.register_on_formspec_input(func(formname, fields))`
706 * Called when a button is pressed in the local player's inventory form
707 * Newest functions are called first
708 * If function returns `true`, remaining functions are not called
709 * `minetest.register_on_dignode(func(pos, node))`
710 * Called when the local player digs a node
711 * Newest functions are called first
712 * If any function returns true, the node isn't dug
713 * `minetest.register_on_punchnode(func(pos, node))`
714 * Called when the local player punches a node
715 * Newest functions are called first
716 * If any function returns true, the punch is ignored
718 * `minetest.sound_play(spec, parameters)`: returns a handle
719 * `spec` is a `SimpleSoundSpec`
720 * `parameters` is a sound parameter table
721 * `minetest.sound_stop(handle)`
724 * `minetest.after(time, func, ...)`
725 * Call the function `func` after `time` seconds, may be fractional
726 * Optional: Variable number of arguments that are passed to `func`
729 * `minetest.get_node(pos)`
730 * Returns the node at the given position as table in the format
731 `{name="node_name", param1=0, param2=0}`, returns `{name="ignore", param1=0, param2=0}`
733 * `minetest.get_node_or_nil(pos)`
734 * Same as `get_node` but returns `nil` for unloaded areas.
737 * `minetest.get_wielded_item()`
738 * Returns the itemstack the local player is holding
741 * `minetest.parse_json(string[, nullvalue])`: returns something
742 * Convert a string containing JSON data into the Lua equivalent
743 * `nullvalue`: returned in place of the JSON null; defaults to `nil`
744 * On success returns a table, a string, a number, a boolean or `nullvalue`
745 * On failure outputs an error message and returns `nil`
746 * Example: `parse_json("[10, {\"a\":false}]")`, returns `{10, {a = false}}`
747 * `minetest.write_json(data[, styled])`: returns a string or `nil` and an error message
748 * Convert a Lua table into a JSON string
749 * styled: Outputs in a human-readable format if this is set, defaults to false
750 * Unserializable things like functions and userdata are saved as null.
751 * **Warning**: JSON is more strict than the Lua table format.
752 1. You can only use strings and positive integers of at least one as keys.
753 2. You can not mix string and integer keys.
754 This is due to the fact that JSON has two distinct array and object values.
755 * Example: `write_json({10, {a = false}})`, returns `"[10, {\"a\": false}]"`
756 * `minetest.serialize(table)`: returns a string
757 * Convert a table containing tables, strings, numbers, booleans and `nil`s
758 into string form readable by `minetest.deserialize`
759 * Example: `serialize({foo='bar'})`, returns `'return { ["foo"] = "bar" }'`
760 * `minetest.deserialize(string)`: returns a table
761 * Convert a string returned by `minetest.deserialize` into a table
762 * `string` is loaded in an empty sandbox environment.
763 * Will load functions, but they cannot access the global environment.
764 * Example: `deserialize('return { ["foo"] = "bar" }')`, returns `{foo='bar'}`
765 * Example: `deserialize('print("foo")')`, returns `nil` (function call fails)
766 * `error:[string "print("foo")"]:1: attempt to call global 'print' (a nil value)`
767 * `minetest.compress(data, method, ...)`: returns `compressed_data`
768 * Compress a string of data.
769 * `method` is a string identifying the compression method to be used.
770 * Supported compression methods:
771 * Deflate (zlib): `"deflate"`
772 * `...` indicates method-specific arguments. Currently defined arguments are:
773 * Deflate: `level` - Compression level, `0`-`9` or `nil`.
774 * `minetest.decompress(compressed_data, method, ...)`: returns data
775 * Decompress a string of data (using ZLib).
776 * See documentation on `minetest.compress()` for supported compression methods.
777 * currently supported.
778 * `...` indicates method-specific arguments. Currently, no methods use this.
779 * `minetest.encode_base64(string)`: returns string encoded in base64
780 * Encodes a string in base64.
781 * `minetest.decode_base64(string)`: returns string
782 * Decodes a string encoded in base64.
783 * `core.gettext(string) : returns string
784 * look up the translation of a string in the gettext message catalog
785 * `fgettext_ne(string, ...)`
786 * call core.gettext(string), replace "$1"..."$9" with the given
787 extra arguments and return the result
788 * `fgettext(string, ...)` : returns string
789 * same as fgettext_ne(), but calls core.formspec_escape before returning result
790 * `show_formspec(formname, formspec)` : returns true on success
791 * Shows a formspec to the player
796 An interface to read config files in the format of `minetest.conf`.
798 It can be created via `Settings(filename)`.
801 * `get(key)`: returns a value
802 * `get_bool(key)`: returns a boolean
804 * `remove(key)`: returns a boolean (`true` for success)
805 * `get_names()`: returns `{key1,...}`
806 * `write()`: returns a boolean (`true` for success)
807 * write changes to file
808 * `to_table()`: returns `{[key1]=value1,...}`
813 ### Chat command definition (`register_chatcommand`)
816 params = "<name> <privilege>", -- Short parameter description
817 description = "Remove privilege from player", -- Full description
818 privs = {privs=true}, -- Require the "privs" privilege to run
819 func = function(name, param), -- Called when command is run.
820 -- Returns boolean success and text output.