doc/client_lua_api.md

   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/>
   5
   6 Introduction
   7 ------------
   8
   9 **WARNING: The client API is currently unstable, and may break/change without warning.**
  10
  11 Content and functionality can be added to Minetest 0.4.15-dev+ by using Lua
  12 scripting in run-time loaded mods.
  13
  14 A mod is a self-contained bunch of scripts, textures and other related
  15 things that is loaded by and interfaces with Minetest.
  16
  17 Transfering client-sided mods form the server to the client is planned, but not implemented yet.
  18
  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).
  22
  23 Programming in Lua
  24 ------------------
  25 If you have any difficulty in understanding this, please read
  26 [Programming in Lua](http://www.lua.org/pil/).
  27
  28 Startup
  29 -------
  30 Mods are loaded during client startup from the mod load paths by running
  31 the `init.lua` scripts in a shared environment.
  32
  33 Paths
  34 -----
  35 * `RUN_IN_PLACE=1` (Windows release, local build)
  36     *  `$path_user`:
  37         * Linux: `<build directory>`
  38         * Windows: `<build directory>`
  39     * `$path_share`
  40         * Linux: `<build directory>`
  41         * Windows:  `<build directory>`
  42 * `RUN_IN_PLACE=0`: (Linux release)
  43     * `$path_share`
  44         * Linux: `/usr/share/minetest`
  45         * Windows: `<install directory>/minetest-0.4.x`
  46     * `$path_user`:
  47         * Linux: `$HOME/.minetest`
  48         * Windows: `C:/users/<user>/AppData/minetest` (maybe)
  49
  50 Mod load path
  51 -------------
  52 Generic:
  53
  54 * `$path_share/clientmods/`
  55 * `$path_user/clientmods/` (User-installed mods)
  56
  57 In a run-in-place version (e.g. the distributed windows version):
  58
  59 * `minetest-0.4.x/clientmods/` (User-installed mods)
  60
  61 On an installed version on Linux:
  62
  63 * `/usr/share/minetest/clientmods/`
  64 * `$HOME/.minetest/clientmods/` (User-installed mods)
  65
  66 Modpack support
  67 ----------------
  68 **NOTE: Not implemented yet.**
  69
  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.
  73
  74 Mod directory structure
  75 ------------------------
  76
  77     clientmods
  78     ├── modname
  79     |   ├── depends.txt
  80     |   ├── init.lua
  81     └── another
  82
  83 ### modname
  84 The location of this directory.
  85
  86 ### depends.txt
  87 List of mods that have to be loaded before loading this mod.
  88
  89 A single line contains a single modname.
  90
  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.
  94
  95 ### init.lua
  96 The main Lua script. Running this script should register everything it
  97 wants to register. Subsequent execution depends on minetest calling the
  98 registered callbacks.
  99
 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.
 102
 103 ### `sounds`
 104 Media files (sounds) that will be transferred to the
 105 client and will be available for use by the mod.
 106
 107 Naming convention for registered textual names
 108 ----------------------------------------------
 109 Registered names should generally be in this format:
 110
 111     "modname:<whatever>" (<whatever> can have characters a-zA-Z0-9_)
 112
 113 This is to prevent conflicting names from corrupting maps and is
 114 enforced by the mod loader.
 115
 116 ### Example
 117 In the mod `experimental`, there is the ideal item/node/entity name `tnt`.
 118 So the name should be `experimental:tnt`.
 119
 120 Enforcement can be overridden by prefixing the name with `:`. This can
 121 be used for overriding the registrations of some other mod.
 122
 123 Example: Any mod can redefine `experimental:tnt` by using the name
 124
 125     :experimental:tnt
 126
 127 when registering it.
 128 (also that mod is required to have `experimental` as a dependency)
 129
 130 The `:` prefix can also be used for maintaining backwards compatibility.
 131
 132 Sounds
 133 ------
 134 **NOTE: max_hear_distance and connecting to objects is not implemented.**
 135
 136 Only Ogg Vorbis files are supported.
 137
 138 For positional playing of sounds, only single-channel (mono) files are
 139 supported. Otherwise OpenAL will play them non-positionally.
 140
 141 Mods should generally prefix their sounds with `modname_`, e.g. given
 142 the mod name "`foomod`", a sound could be called:
 143
 144     foomod_foosound.ogg
 145
 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.
 149
 150 When playing the sound `foomod_foosound`, the sound is chosen randomly
 151 from the available ones of the following files:
 152
 153 * `foomod_foosound.ogg`
 154 * `foomod_foosound.0.ogg`
 155 * `foomod_foosound.1.ogg`
 156 * (...)
 157 * `foomod_foosound.9.ogg`
 158
 159 Examples of sound parameter tables:
 160
 161     -- Play locationless
 162     {
 163         gain = 1.0, -- default
 164     }
 165     -- Play locationless, looped
 166     {
 167         gain = 1.0, -- default
 168         loop = true,
 169     }
 170     -- Play in a location
 171     {
 172         pos = {x = 1, y = 2, z = 3},
 173         gain = 1.0, -- default
 174         max_hear_distance = 32, -- default, uses an euclidean metric
 175     }
 176     -- Play connected to an object, looped
 177     {
 178         object = <an ObjectRef>,
 179         gain = 1.0, -- default
 180         max_hear_distance = 32, -- default, uses an euclidean metric
 181         loop = true,
 182     }
 183
 184 Looped sounds must either be connected to an object or played locationless.
 185
 186 ### SimpleSoundSpec
 187 * e.g. `""`
 188 * e.g. `"default_place_node"`
 189 * e.g. `{}`
 190 * e.g. `{name = "default_place_node"}`
 191 * e.g. `{name = "default_place_node", gain = 1.0}`
 192
 193 Representations of simple things
 194 --------------------------------
 195
 196 ### Position/vector
 197
 198     {x=num, y=num, z=num}
 199
 200 For helper functions see "Vector helpers".
 201
 202 ### pointed_thing
 203 * `{type="nothing"}`
 204 * `{type="node", under=pos, above=pos}`
 205 * `{type="object", ref=ObjectRef}`
 206
 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.
 211
 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.
 216
 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.
 221
 222 E.g. A flag field of value
 223
 224     {place_center_x = true, place_center_y=false, place_center_z=true}
 225
 226 is equivalent to
 227
 228     {place_center_x = true, noplace_center_y=true, place_center_z=true}
 229
 230 which is equivalent to
 231
 232     "place_center_x, noplace_center_y, place_center_z"
 233
 234 or even
 235
 236     "place_center_x, place_center_z"
 237
 238 since, by default, no schematic attributes are set.
 239
 240 Formspec
 241 --------
 242 Formspec defines a menu. It is a string, with a somewhat strange format.
 243
 244 Spaces and newlines can be inserted between the blocks, as is used in the
 245 examples.
 246
 247 ### Examples
 248
 249 #### Chest
 250
 251     size[8,9]
 252     list[context;main;0,0;8,4;]
 253     list[current_player;main;0,5;8,4;]
 254
 255 #### Furnace
 256
 257     size[8,9]
 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;]
 262
 263 #### Minecraft-like player inventory
 264
 265     size[8,7.5]
 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;]
 270
 271 ### Elements
 272
 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>;]`
 277
 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)
 283
 284 #### `container_end[]`
 285 * End of a container, following elements are no longer relative to this container
 286
 287 #### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]`
 288 * Show an inventory list
 289
 290 #### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]`
 291 * Show an inventory list
 292
 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
 299
 300 #### `listring[]`
 301 * Shorthand for doing `listring[<inventory location>;<list name>]`
 302   for the last two inventory lists added by list[...]
 303
 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
 307
 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
 312
 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
 319
 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)
 324
 325 #### `image[<X>,<Y>;<W>,<H>;<texture name>]`
 326 * Show an image
 327 * Position and size units are inventory slots
 328
 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
 332
 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)
 336
 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.
 342
 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)
 350
 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
 354   of this field.
 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
 362
 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
 366   of this field.
 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
 378
 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
 382   of this field.
 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
 387
 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)
 392
 393 #### `textarea[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`
 394 * Same as fields above, but with multi-line input
 395
 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
 400
 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
 406
 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 * `label` is the text on the button
 412 * Position and size units are inventory slots
 413
 414 #### `image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]`
 415 * `x`, `y`, `w`, `h`, and `name` work as per button
 416 * `texture name` is the filename of an image
 417 * Position and size units are inventory slots
 418
 419 #### `image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>;<noclip>;<drawborder>;<pressed texture name>]`
 420 * `x`, `y`, `w`, `h`, and `name` work as per button
 421 * `texture name` is the filename of an image
 422 * Position and size units are inventory slots
 423 * `noclip=true` means the image button doesn't need to be within specified formsize
 424 * `drawborder`: draw button border or not
 425 * `pressed texture name` is the filename of an image on pressed state
 426
 427 #### `item_image_button[<X>,<Y>;<W>,<H>;<item name>;<name>;<label>]`
 428 * `x`, `y`, `w`, `h`, `name` and `label` work as per button
 429 * `item name` is the registered name of an item/node,
 430    tooltip will be made out of its description
 431    to override it use tooltip element
 432 * Position and size units are inventory slots
 433
 434 #### `button_exit[<X>,<Y>;<W>,<H>;<name>;<label>]`
 435 * When clicked, fields will be sent and the form will quit.
 436
 437 #### `image_button_exit[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]`
 438 * When clicked, fields will be sent and the form will quit.
 439
 440 #### `textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>]`
 441 * Scrollable item list showing arbitrary text elements
 442 * `x` and `y` position the itemlist relative to the top left of the menu
 443 * `w` and `h` are the size of the itemlist
 444 * `name` fieldname sent to server on doubleclick value is current selected element
 445 * `listelements` can be prepended by #color in hexadecimal format RRGGBB (only),
 446      * if you want a listelement to start with "#" write "##".
 447
 448 #### `textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>;<selected idx>;<transparent>]`
 449 * Scrollable itemlist showing arbitrary text elements
 450 * `x` and `y` position the item list relative to the top left of the menu
 451 * `w` and `h` are the size of the item list
 452 * `name` fieldname sent to server on doubleclick value is current selected element
 453 * `listelements` can be prepended by #RRGGBB (only) in hexadecimal format
 454      * if you want a listelement to start with "#" write "##"
 455 * Index to be selected within textlist
 456 * `true`/`false`: draw transparent background
 457 * See also `minetest.explode_textlist_event` (main menu: `engine.explode_textlist_event`)
 458
 459 #### `tabheader[<X>,<Y>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]`
 460 * Show a tab**header** at specific position (ignores formsize)
 461 * `x` and `y` position the itemlist relative to the top left of the menu
 462 * `name` fieldname data is transferred to Lua
 463 * `caption 1`...: name shown on top of tab
 464 * `current_tab`: index of selected tab 1...
 465 * `transparent` (optional): show transparent
 466 * `draw_border` (optional): draw border
 467
 468 #### `box[<X>,<Y>;<W>,<H>;<color>]`
 469 * Simple colored semitransparent box
 470 * `x` and `y` position the box relative to the top left of the menu
 471 * `w` and `h` are the size of box
 472 * `color` is color specified as a `ColorString`
 473
 474 #### `dropdown[<X>,<Y>;<W>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>]`
 475 * Show a dropdown field
 476 * **Important note**: There are two different operation modes:
 477      1. handle directly on change (only changed dropdown is submitted)
 478      2. read the value on pressing a button (all dropdown values are available)
 479 * `x` and `y` position of dropdown
 480 * Width of dropdown
 481 * Fieldname data is transferred to Lua
 482 * Items to be shown in dropdown
 483 * Index of currently selected dropdown item
 484
 485 #### `checkbox[<X>,<Y>;<name>;<label>;<selected>]`
 486 * Show a checkbox
 487 * `x` and `y`: position of checkbox
 488 * `name` fieldname data is transferred to Lua
 489 * `label` to be shown left of checkbox
 490 * `selected` (optional): `true`/`false`
 491
 492 #### `scrollbar[<X>,<Y>;<W>,<H>;<orientation>;<name>;<value>]`
 493 * Show a scrollbar
 494 * There are two ways to use it:
 495      1. handle the changed event (only changed scrollbar is available)
 496      2. read the value on pressing a button (all scrollbars are available)
 497 * `x` and `y`: position of trackbar
 498 * `w` and `h`: width and height
 499 * `orientation`:  `vertical`/`horizontal`
 500 * Fieldname data is transferred to Lua
 501 * Value this trackbar is set to (`0`-`1000`)
 502 * See also `minetest.explode_scrollbar_event` (main menu: `engine.explode_scrollbar_event`)
 503
 504 #### `table[<X>,<Y>;<W>,<H>;<name>;<cell 1>,<cell 2>,...,<cell n>;<selected idx>]`
 505 * Show scrollable table using options defined by the previous `tableoptions[]`
 506 * Displays cells as defined by the previous `tablecolumns[]`
 507 * `x` and `y`: position the itemlist relative to the top left of the menu
 508 * `w` and `h` are the size of the itemlist
 509 * `name`: fieldname sent to server on row select or doubleclick
 510 * `cell 1`...`cell n`: cell contents given in row-major order
 511 * `selected idx`: index of row to be selected within table (first row = `1`)
 512 * See also `minetest.explode_table_event` (main menu: `engine.explode_table_event`)
 513
 514 #### `tableoptions[<opt 1>;<opt 2>;...]`
 515 * Sets options for `table[]`
 516 * `color=#RRGGBB`
 517      * default text color (`ColorString`), defaults to `#FFFFFF`
 518 * `background=#RRGGBB`
 519      * table background color (`ColorString`), defaults to `#000000`
 520 * `border=<true/false>`
 521      * should the table be drawn with a border? (default: `true`)
 522 * `highlight=#RRGGBB`
 523      * highlight background color (`ColorString`), defaults to `#466432`
 524 * `highlight_text=#RRGGBB`
 525      * highlight text color (`ColorString`), defaults to `#FFFFFF`
 526 * `opendepth=<value>`
 527      * all subtrees up to `depth < value` are open (default value = `0`)
 528      * only useful when there is a column of type "tree"
 529
 530 #### `tablecolumns[<type 1>,<opt 1a>,<opt 1b>,...;<type 2>,<opt 2a>,<opt 2b>;...]`
 531 * Sets columns for `table[]`
 532 * Types: `text`, `image`, `color`, `indent`, `tree`
 533     * `text`:   show cell contents as text
 534     * `image`:  cell contents are an image index, use column options to define images
 535     * `color`:   cell contents are a ColorString and define color of following cell
 536     * `indent`: cell contents are a number and define indentation of following cell
 537     * `tree`:   same as indent, but user can open and close subtrees (treeview-like)
 538 * Column options:
 539     * `align=<value>`
 540         * for `text` and `image`: content alignment within cells.
 541           Available values: `left` (default), `center`, `right`, `inline`
 542     * `width=<value>`
 543         * for `text` and `image`: minimum width in em (default: `0`)
 544         * for `indent` and `tree`: indent width in em (default: `1.5`)
 545     * `padding=<value>`: padding left of the column, in em (default `0.5`).
 546       Exception: defaults to 0 for indent columns
 547     * `tooltip=<value>`: tooltip text (default: empty)
 548     * `image` column options:
 549         * `0=<value>` sets image for image index 0
 550         * `1=<value>` sets image for image index 1
 551         * `2=<value>` sets image for image index 2
 552         * and so on; defined indices need not be contiguous empty or
 553           non-numeric cells are treated as `0`.
 554     * `color` column options:
 555         * `span=<value>`: number of following columns to affect (default: infinite)
 556
 557 **Note**: do _not_ use a element name starting with `key_`; those names are reserved to
 558 pass key press events to formspec!
 559
 560 Spatial Vectors
 561 ---------------
 562 * `vector.new(a[, b, c])`: returns a vector:
 563     * A copy of `a` if `a` is a vector.
 564     * `{x = a, y = b, z = c}`, if all `a, b, c` are defined
 565 * `vector.direction(p1, p2)`: returns a vector
 566 * `vector.distance(p1, p2)`: returns a number
 567 * `vector.length(v)`: returns a number
 568 * `vector.normalize(v)`: returns a vector
 569 * `vector.floor(v)`: returns a vector, each dimension rounded down
 570 * `vector.round(v)`: returns a vector, each dimension rounded to nearest int
 571 * `vector.apply(v, func)`: returns a vector
 572 * `vector.equals(v1, v2)`: returns a boolean
 573
 574 For the following functions `x` can be either a vector or a number:
 575
 576 * `vector.add(v, x)`: returns a vector
 577 * `vector.subtract(v, x)`: returns a vector
 578 * `vector.multiply(v, x)`: returns a scaled vector or Schur product
 579 * `vector.divide(v, x)`: returns a scaled vector or Schur quotient
 580
 581 Helper functions
 582 ----------------
 583 * `dump2(obj, name="_", dumped={})`
 584      * Return object serialized as a string, handles reference loops
 585 * `dump(obj, dumped={})`
 586     * Return object serialized as a string
 587 * `math.hypot(x, y)`
 588     * Get the hypotenuse of a triangle with legs x and y.
 589       Useful for distance calculation.
 590 * `math.sign(x, tolerance)`
 591     * Get the sign of a number.
 592       Optional: Also returns `0` when the absolute value is within the tolerance (default: `0`)
 593 * `string.split(str, separator=",", include_empty=false, max_splits=-1,
 594 * 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"}`
 598 * `string:trim()`
 599     * e.g. `string.trim("\n \t\tfoo bar\t ") == "foo bar"`
 600 * `minetest.is_yes(arg)`
 601     * returns whether `arg` can be interpreted as yes
 602 * `minetest.get_us_time()`
 603     * returns time with microsecond precision. May not return wall time.
 604 * `table.copy(table)`: returns a table
 605     * returns a deep copy of `table`
 606
 607 Minetest namespace reference
 608 ------------------------------
 609
 610 ### Utilities
 611
 612 * `minetest.get_current_modname()`: returns the currently loading mod's name, when we are loading a mod
 613 * `minetest.get_version()`: returns a table containing components of the
 614    engine version.  Components:
 615     * `project`: Name of the project, eg, "Minetest"
 616     * `string`: Simple version, eg, "1.2.3-dev"
 617     * `hash`: Full git version (only set if available), eg, "1.2.3-dev-01234567-dirty"
 618   Use this for informational purposes only. The information in the returned
 619   table does not represent the capabilities of the engine, nor is it
 620   reliable or verifyable. Compatible forks will have a different name and
 621   version entirely. To check for the presence of engine features, test
 622   whether the functions exported by the wanted features exist. For example:
 623   `if minetest.nodeupdate then ... end`.
 624
 625 ### Logging
 626 * `minetest.debug(...)`
 627     * Equivalent to `minetest.log(table.concat({...}, "\t"))`
 628 * `minetest.log([level,] text)`
 629     * `level` is one of `"none"`, `"error"`, `"warning"`, `"action"`,
 630       `"info"`, or `"verbose"`.  Default is `"none"`.
 631
 632 ### Global callback registration functions
 633 Call these functions only at load time!
 634
 635 * `minetest.register_globalstep(func(dtime))`
 636     * Called every client environment step, usually interval of 0.1s
 637 * `minetest.register_on_shutdown(func())`
 638     * Called before client shutdown
 639     * **Warning**: If the client terminates abnormally (i.e. crashes), the registered
 640       callbacks **will likely not be run**. Data should be saved at
 641       semi-frequent intervals as well as on server shutdown.
 642 * `minetest.register_on_connect(func())`
 643     * Called at the end of client connection (when player is loaded onto map)
 644 * `minetest.register_on_receiving_chat_message(func(name, message))`
 645     * Called always when a client receive a message
 646     * Return `true` to mark the message as handled, which means that it will not be shown to chat
 647 * `minetest.register_on_sending_chat_message(func(name, message))`
 648     * Called always when a client send a message from chat
 649     * Return `true` to mark the message as handled, which means that it will not be sent to server
 650 * `minetest.register_chatcommand(cmd, chatcommand definition)`
 651     * Adds definition to minetest.registered_chatcommands
 652 * `minetest.register_on_death(func())`
 653     * Called when the local player dies
 654 * `minetest.register_on_hp_modification(func(hp))`
 655     * Called when server modified player's HP
 656 * `minetest.register_on_damage_taken(func(hp))`
 657     * Called when the local player take damages
 658 * `minetest.register_on_formspec_input(func(formname, fields))`
 659     * Called when a button is pressed in the local player's inventory form
 660     * Newest functions are called first
 661     * If function returns `true`, remaining functions are not called
 662 * `minetest.register_on_dignode(func(pos, node))`
 663     * Called when the local player digs a node
 664     * Newest functions are called first
 665     * If any function returns true, the node isn't dug
 666 * `minetest.register_on_punchnode(func(pos, node))`
 667     * Called when the local player punches a node
 668     * Newest functions are called first
 669     * If any function returns true, the punch is ignored
 670 * `minetest.register_on_placenode(function(pointed_thing, node))`
 671     * Called when a node has been placed
 672 ### Sounds
 673 * `minetest.sound_play(spec, parameters)`: returns a handle
 674     * `spec` is a `SimpleSoundSpec`
 675     * `parameters` is a sound parameter table
 676 * `minetest.sound_stop(handle)`
 677
 678 ### Timing
 679 * `minetest.after(time, func, ...)`
 680     * Call the function `func` after `time` seconds, may be fractional
 681     * Optional: Variable number of arguments that are passed to `func`
 682
 683 ### Map
 684 * `minetest.get_node(pos)`
 685     * Returns the node at the given position as table in the format
 686       `{name="node_name", param1=0, param2=0}`, returns `{name="ignore", param1=0, param2=0}`
 687       for unloaded areas.
 688 * `minetest.get_node_or_nil(pos)`
 689     * Same as `get_node` but returns `nil` for unloaded areas.
 690 * `minetest.get_meta(pos)`
 691     * Get a `NodeMetaRef` at that position
 692
 693 ### Player
 694 * `minetest.get_wielded_item()`
 695     * Returns the itemstack the local player is holding
 696 * `minetest.localplayer`
 697     * Reference to the LocalPlayer object. See `LocalPlayer` class reference for methods.
 698
 699 ### Client Environment
 700 * `minetest.get_player_names()`
 701     * Returns list of player names on server
 702 * `minetest.disconnect()`
 703     * Disconnect from the server and exit to main menu.
 704     * Returns `false` if the client is already disconnecting otherwise returns `true`.
 705 * `minetest.get_protocol_version()`
 706     * Returns the protocol version of the server.
 707     * Might not be accurate at start up as the client might not be connected to the server yet, in that case it will return 0.
 708 * `minetest.take_screenshot()`
 709     * Take a screenshot.
 710
 711 ### Misc.
 712 * `minetest.parse_json(string[, nullvalue])`: returns something
 713     * Convert a string containing JSON data into the Lua equivalent
 714     * `nullvalue`: returned in place of the JSON null; defaults to `nil`
 715     * On success returns a table, a string, a number, a boolean or `nullvalue`
 716     * On failure outputs an error message and returns `nil`
 717     * Example: `parse_json("[10, {\"a\":false}]")`, returns `{10, {a = false}}`
 718 * `minetest.write_json(data[, styled])`: returns a string or `nil` and an error message
 719     * Convert a Lua table into a JSON string
 720     * styled: Outputs in a human-readable format if this is set, defaults to false
 721     * Unserializable things like functions and userdata are saved as null.
 722     * **Warning**: JSON is more strict than the Lua table format.
 723         1. You can only use strings and positive integers of at least one as keys.
 724         2. You can not mix string and integer keys.
 725            This is due to the fact that JSON has two distinct array and object values.
 726     * Example: `write_json({10, {a = false}})`, returns `"[10, {\"a\": false}]"`
 727 * `minetest.serialize(table)`: returns a string
 728     * Convert a table containing tables, strings, numbers, booleans and `nil`s
 729       into string form readable by `minetest.deserialize`
 730     * Example: `serialize({foo='bar'})`, returns `'return { ["foo"] = "bar" }'`
 731 * `minetest.deserialize(string)`: returns a table
 732     * Convert a string returned by `minetest.deserialize` into a table
 733     * `string` is loaded in an empty sandbox environment.
 734     * Will load functions, but they cannot access the global environment.
 735     * Example: `deserialize('return { ["foo"] = "bar" }')`, returns `{foo='bar'}`
 736     * Example: `deserialize('print("foo")')`, returns `nil` (function call fails)
 737         * `error:[string "print("foo")"]:1: attempt to call global 'print' (a nil value)`
 738 * `minetest.compress(data, method, ...)`: returns `compressed_data`
 739     * Compress a string of data.
 740     * `method` is a string identifying the compression method to be used.
 741     * Supported compression methods:
 742     *     Deflate (zlib): `"deflate"`
 743     * `...` indicates method-specific arguments.  Currently defined arguments are:
 744     *     Deflate: `level` - Compression level, `0`-`9` or `nil`.
 745 * `minetest.decompress(compressed_data, method, ...)`: returns data
 746     * Decompress a string of data (using ZLib).
 747     * See documentation on `minetest.compress()` for supported compression methods.
 748     * currently supported.
 749     * `...` indicates method-specific arguments. Currently, no methods use this.
 750 * `minetest.encode_base64(string)`: returns string encoded in base64
 751     * Encodes a string in base64.
 752 * `minetest.decode_base64(string)`: returns string
 753     * Decodes a string encoded in base64.
 754 * `minetest.gettext(string) : returns string
 755     * look up the translation of a string in the gettext message catalog
 756 * `fgettext_ne(string, ...)`
 757     * call minetest.gettext(string), replace "$1"..."$9" with the given
 758       extra arguments and return the result
 759 * `fgettext(string, ...)` : returns string
 760     * same as fgettext_ne(), but calls minetest.formspec_escape before returning result
 761 * `minetest.pointed_thing_to_face_pos(placer, pointed_thing)`: returns a position
 762     * returns the exact position on the surface of a pointed node
 763
 764 ### UI
 765 * `minetest.ui.minimap`
 766     * Reference to the minimap object. See `Minimap` class reference for methods.
 767 * `minetest.show_formspec(formname, formspec)` : returns true on success
 768         * Shows a formspec to the player
 769 * `minetest.display_chat_message(message)` returns true on success
 770         * Shows a chat message to the current player.
 771
 772 Class reference
 773 ---------------
 774
 775 ### Minimap
 776 An interface to manipulate minimap on client UI
 777
 778 * `show()`: shows the minimap (if not disabled by server)
 779 * `hide()`: hides the minimap
 780 * `set_pos(pos)`: sets the minimap position on screen
 781 * `get_pos()`: returns the minimap current position
 782 * `set_angle(deg)`: sets the minimap angle in degrees
 783 * `get_angle()`: returns the current minimap angle in degrees
 784 * `set_mode(mode)`: sets the minimap mode (0 to 6)
 785 * `get_mode()`: returns the current minimap mode
 786 * `set_shape(shape)`: Sets the minimap shape. (0 = square, 1 = round)
 787 * `get_shape()`: Gets the minimap shape. (0 = square, 1 = round)
 788
 789 ### LocalPlayer
 790 An interface to retrieve information about the player. The player is
 791 not accessible until the client is fully done loading and therefore
 792 not at module init time.
 793
 794 To get the localplayer handle correctly, use `on_connect()` as follows:
 795
 796 ```lua
 797 local localplayer
 798 minetest.register_on_connect(function()
 799         localplayer = minetest.localplayer
 800 end)
 801 ```
 802
 803 Methods:
 804
 805 * `get_pos()`
 806     * returns current player current position
 807 * `get_velocity()`
 808     * returns player speed vector
 809 * `get_hp()`
 810     * returns player HP
 811 * `get_name()`
 812     * returns player name
 813 * `got_teleported()`
 814     * returns true if player was teleported
 815 * `is_attached()`
 816     * returns true if player is attached
 817 * `is_touching_ground()`
 818     * returns true if player touching ground
 819 * `is_in_liquid()`
 820     * returns true if player is in a liquid (This oscillates so that the player jumps a bit above the surface)
 821 * `is_in_liquid_stable()`
 822     * returns true if player is in a stable liquid (This is more stable and defines the maximum speed of the player)
 823 * `get_liquid_viscosity()`
 824     * returns liquid viscosity (Gets the viscosity of liquid to calculate friction)
 825 * `is_climbing()`
 826     * returns true if player is climbing
 827 * `swimming_vertical()`
 828     * returns true if player is swimming in vertical
 829 * `get_physics_override()`
 830     * returns:
 831
 832 ```lua
 833     {
 834         speed = float,
 835         jump = float,
 836         gravity = float,
 837         sneak = boolean,
 838         sneak_glitch = boolean
 839     }
 840 ```
 841
 842 * `get_override_pos()`
 843     * returns override position
 844 * `get_last_pos()`
 845     * returns last player position before the current client step
 846 * `get_last_velocity()`
 847     * returns last player speed
 848 * `get_breath()`
 849     * returns the player's breath
 850 * `get_look_dir()`
 851     * returns look direction vector
 852 * `get_look_horizontal()`
 853     * returns look horizontal angle
 854 * `get_look_vertical()`
 855     * returns look vertical angle
 856 * `get_eye_pos()`
 857     * returns the player's eye position
 858 * `get_eye_offset()`
 859     * returns the player's eye shift vector
 860 * `get_movement_acceleration()`
 861     * returns acceleration of the player in different environments:
 862
 863 ```lua
 864     {
 865        fast = float,
 866        air = float,
 867        default = float,
 868     }
 869 ```
 870
 871 * `get_movement_speed()`
 872     * returns player's speed in different environments:
 873
 874 ```lua
 875     {
 876        walk = float,
 877        jump = float,
 878        crouch = float,
 879        fast = float,
 880        climb = float,
 881     }
 882 ```
 883
 884 * `get_movement()`
 885     * returns player's movement in different environments:
 886
 887 ```lua
 888     {
 889        liquid_fluidity = float,
 890        liquid_sink = float,
 891        liquid_fluidity_smooth = float,
 892        gravity = float,
 893     }
 894 ```
 895
 896 * `get_last_look_horizontal()`:
 897     * returns last look horizontal angle
 898 * `get_last_look_vertical()`:
 899     * returns last look vertical angle
 900 * `get_key_pressed()`:
 901     * returns last key typed by the player
 902
 903 ### Settings
 904 An interface to read config files in the format of `minetest.conf`.
 905
 906 It can be created via `Settings(filename)`.
 907
 908 #### Methods
 909 * `get(key)`: returns a value
 910 * `get_bool(key)`: returns a boolean
 911 * `set(key, value)`
 912 * `remove(key)`: returns a boolean (`true` for success)
 913 * `get_names()`: returns `{key1,...}`
 914 * `write()`: returns a boolean (`true` for success)
 915     * write changes to file
 916 * `to_table()`: returns `{[key1]=value1,...}`
 917
 918 ### NodeMetaRef
 919 Node metadata: reference extra data and functionality stored in a node.
 920 Can be obtained via `minetest.get_meta(pos)`.
 921
 922 #### Methods
 923 * `get_string(name)`
 924 * `get_int(name)`
 925 * `get_float(name)`
 926 * `to_table()`: returns `nil` or a table with keys:
 927     * `fields`: key-value storage
 928     * `inventory`: `{list1 = {}, ...}}`
 929
 930 -----------------
 931
 932 ### Chat command definition (`register_chatcommand`)
 933
 934     {
 935         params = "<name> <privilege>", -- Short parameter description
 936         description = "Remove privilege from player", -- Full description
 937         func = function(param), -- Called when command is run.
 938                                       -- Returns boolean success and text output.
 939     }
 940
 941 Escape sequences
 942 ----------------
 943 Most text can contain escape sequences, that can for example color the text.
 944 There are a few exceptions: tab headers, dropdowns and vertical labels can't.
 945 The following functions provide escape sequences:
 946 * `minetest.get_color_escape_sequence(color)`:
 947     * `color` is a ColorString
 948     * The escape sequence sets the text color to `color`
 949 * `minetest.colorize(color, message)`:
 950     * Equivalent to:
 951       `minetest.get_color_escape_sequence(color) ..
 952        message ..
 953        minetest.get_color_escape_sequence("#ffffff")`
 954 * `color.get_background_escape_sequence(color)`
 955     * `color` is a ColorString
 956     * The escape sequence sets the background of the whole text element to
 957       `color`. Only defined for item descriptions and tooltips.
 958 * `color.strip_foreground_colors(str)`
 959     * Removes foreground colors added by `get_color_escape_sequence`.
 960 * `color.strip_background_colors(str)`
 961     * Removes background colors added by `get_background_escape_sequence`.
 962 * `color.strip_colors(str)`
 963     * Removes all color escape sequences.
 964
 965 `ColorString`
 966 -------------
 967 `#RGB` defines a color in hexadecimal format.
 968
 969 `#RGBA` defines a color in hexadecimal format and alpha channel.
 970
 971 `#RRGGBB` defines a color in hexadecimal format.
 972
 973 `#RRGGBBAA` defines a color in hexadecimal format and alpha channel.
 974
 975 Named colors are also supported and are equivalent to
 976 [CSS Color Module Level 4](http://dev.w3.org/csswg/css-color/#named-colors).
 977 To specify the value of the alpha channel, append `#AA` to the end of the color name
 978 (e.g. `colorname#08`). For named colors the hexadecimal string representing the alpha
 979 value must (always) be two hexadecimal digits.