doc/client_lua_api.txt

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