doc/client_lua_api.txt

   1 Minetest Lua Client Modding API Reference 0.5.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.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", id=ObjectID}`
 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 * Fixed button height. It will be vertically centred on `h`
 412 * `label` is the text on the button
 413 * Position and size units are inventory slots
 414
 415 #### `image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]`
 416 * `x`, `y`, `w`, `h`, and `name` work as per button
 417 * `texture name` is the filename of an image
 418 * Position and size units are inventory slots
 419
 420 #### `image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>;<noclip>;<drawborder>;<pressed texture name>]`
 421 * `x`, `y`, `w`, `h`, and `name` work as per button
 422 * `texture name` is the filename of an image
 423 * Position and size units are inventory slots
 424 * `noclip=true` means the image button doesn't need to be within specified formsize
 425 * `drawborder`: draw button border or not
 426 * `pressed texture name` is the filename of an image on pressed state
 427
 428 #### `item_image_button[<X>,<Y>;<W>,<H>;<item name>;<name>;<label>]`
 429 * `x`, `y`, `w`, `h`, `name` and `label` work as per button
 430 * `item name` is the registered name of an item/node,
 431    tooltip will be made out of its description
 432    to override it use tooltip element
 433 * Position and size units are inventory slots
 434
 435 #### `button_exit[<X>,<Y>;<W>,<H>;<name>;<label>]`
 436 * When clicked, fields will be sent and the form will quit.
 437
 438 #### `image_button_exit[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]`
 439 * When clicked, fields will be sent and the form will quit.
 440
 441 #### `textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>]`
 442 * Scrollable item list showing arbitrary text elements
 443 * `x` and `y` position the itemlist relative to the top left of the menu
 444 * `w` and `h` are the size of the itemlist
 445 * `name` fieldname sent to server on doubleclick value is current selected element
 446 * `listelements` can be prepended by #color in hexadecimal format RRGGBB (only),
 447      * if you want a listelement to start with "#" write "##".
 448
 449 #### `textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>;<selected idx>;<transparent>]`
 450 * Scrollable itemlist showing arbitrary text elements
 451 * `x` and `y` position the item list relative to the top left of the menu
 452 * `w` and `h` are the size of the item list
 453 * `name` fieldname sent to server on doubleclick value is current selected element
 454 * `listelements` can be prepended by #RRGGBB (only) in hexadecimal format
 455      * if you want a listelement to start with "#" write "##"
 456 * Index to be selected within textlist
 457 * `true`/`false`: draw transparent background
 458 * See also `minetest.explode_textlist_event` (main menu: `engine.explode_textlist_event`)
 459
 460 #### `tabheader[<X>,<Y>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]`
 461 * Show a tab**header** at specific position (ignores formsize)
 462 * `x` and `y` position the itemlist relative to the top left of the menu
 463 * `name` fieldname data is transferred to Lua
 464 * `caption 1`...: name shown on top of tab
 465 * `current_tab`: index of selected tab 1...
 466 * `transparent` (optional): show transparent
 467 * `draw_border` (optional): draw border
 468
 469 #### `box[<X>,<Y>;<W>,<H>;<color>]`
 470 * Simple colored semitransparent box
 471 * `x` and `y` position the box relative to the top left of the menu
 472 * `w` and `h` are the size of box
 473 * `color` is color specified as a `ColorString`
 474
 475 #### `dropdown[<X>,<Y>;<W>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>]`
 476 * Show a dropdown field
 477 * **Important note**: There are two different operation modes:
 478      1. handle directly on change (only changed dropdown is submitted)
 479      2. read the value on pressing a button (all dropdown values are available)
 480 * `x` and `y` position of dropdown
 481 * Width of dropdown
 482 * Fieldname data is transferred to Lua
 483 * Items to be shown in dropdown
 484 * Index of currently selected dropdown item
 485
 486 #### `checkbox[<X>,<Y>;<name>;<label>;<selected>]`
 487 * Show a checkbox
 488 * `x` and `y`: position of checkbox
 489 * `name` fieldname data is transferred to Lua
 490 * `label` to be shown left of checkbox
 491 * `selected` (optional): `true`/`false`
 492
 493 #### `scrollbar[<X>,<Y>;<W>,<H>;<orientation>;<name>;<value>]`
 494 * Show a scrollbar
 495 * There are two ways to use it:
 496      1. handle the changed event (only changed scrollbar is available)
 497      2. read the value on pressing a button (all scrollbars are available)
 498 * `x` and `y`: position of trackbar
 499 * `w` and `h`: width and height
 500 * `orientation`:  `vertical`/`horizontal`
 501 * Fieldname data is transferred to Lua
 502 * Value this trackbar is set to (`0`-`1000`)
 503 * See also `minetest.explode_scrollbar_event` (main menu: `engine.explode_scrollbar_event`)
 504
 505 #### `table[<X>,<Y>;<W>,<H>;<name>;<cell 1>,<cell 2>,...,<cell n>;<selected idx>]`
 506 * Show scrollable table using options defined by the previous `tableoptions[]`
 507 * Displays cells as defined by the previous `tablecolumns[]`
 508 * `x` and `y`: position the itemlist relative to the top left of the menu
 509 * `w` and `h` are the size of the itemlist
 510 * `name`: fieldname sent to server on row select or doubleclick
 511 * `cell 1`...`cell n`: cell contents given in row-major order
 512 * `selected idx`: index of row to be selected within table (first row = `1`)
 513 * See also `minetest.explode_table_event` (main menu: `engine.explode_table_event`)
 514
 515 #### `tableoptions[<opt 1>;<opt 2>;...]`
 516 * Sets options for `table[]`
 517 * `color=#RRGGBB`
 518      * default text color (`ColorString`), defaults to `#FFFFFF`
 519 * `background=#RRGGBB`
 520      * table background color (`ColorString`), defaults to `#000000`
 521 * `border=<true/false>`
 522      * should the table be drawn with a border? (default: `true`)
 523 * `highlight=#RRGGBB`
 524      * highlight background color (`ColorString`), defaults to `#466432`
 525 * `highlight_text=#RRGGBB`
 526      * highlight text color (`ColorString`), defaults to `#FFFFFF`
 527 * `opendepth=<value>`
 528      * all subtrees up to `depth < value` are open (default value = `0`)
 529      * only useful when there is a column of type "tree"
 530
 531 #### `tablecolumns[<type 1>,<opt 1a>,<opt 1b>,...;<type 2>,<opt 2a>,<opt 2b>;...]`
 532 * Sets columns for `table[]`
 533 * Types: `text`, `image`, `color`, `indent`, `tree`
 534     * `text`:   show cell contents as text
 535     * `image`:  cell contents are an image index, use column options to define images
 536     * `color`:   cell contents are a ColorString and define color of following cell
 537     * `indent`: cell contents are a number and define indentation of following cell
 538     * `tree`:   same as indent, but user can open and close subtrees (treeview-like)
 539 * Column options:
 540     * `align=<value>`
 541         * for `text` and `image`: content alignment within cells.
 542           Available values: `left` (default), `center`, `right`, `inline`
 543     * `width=<value>`
 544         * for `text` and `image`: minimum width in em (default: `0`)
 545         * for `indent` and `tree`: indent width in em (default: `1.5`)
 546     * `padding=<value>`: padding left of the column, in em (default `0.5`).
 547       Exception: defaults to 0 for indent columns
 548     * `tooltip=<value>`: tooltip text (default: empty)
 549     * `image` column options:
 550         * `0=<value>` sets image for image index 0
 551         * `1=<value>` sets image for image index 1
 552         * `2=<value>` sets image for image index 2
 553         * and so on; defined indices need not be contiguous empty or
 554           non-numeric cells are treated as `0`.
 555     * `color` column options:
 556         * `span=<value>`: number of following columns to affect (default: infinite)
 557
 558 **Note**: do _not_ use a element name starting with `key_`; those names are reserved to
 559 pass key press events to formspec!
 560
 561 Spatial Vectors
 562 ---------------
 563 * `vector.new(a[, b, c])`: returns a vector:
 564     * A copy of `a` if `a` is a vector.
 565     * `{x = a, y = b, z = c}`, if all `a, b, c` are defined
 566 * `vector.direction(p1, p2)`: returns a vector
 567 * `vector.distance(p1, p2)`: returns a number
 568 * `vector.length(v)`: returns a number
 569 * `vector.normalize(v)`: returns a vector
 570 * `vector.floor(v)`: returns a vector, each dimension rounded down
 571 * `vector.round(v)`: returns a vector, each dimension rounded to nearest int
 572 * `vector.apply(v, func)`: returns a vector
 573 * `vector.equals(v1, v2)`: returns a boolean
 574
 575 For the following functions `x` can be either a vector or a number:
 576
 577 * `vector.add(v, x)`: returns a vector
 578 * `vector.subtract(v, x)`: returns a vector
 579 * `vector.multiply(v, x)`: returns a scaled vector or Schur product
 580 * `vector.divide(v, x)`: returns a scaled vector or Schur quotient
 581
 582 Helper functions
 583 ----------------
 584 * `dump2(obj, name="_", dumped={})`
 585      * Return object serialized as a string, handles reference loops
 586 * `dump(obj, dumped={})`
 587     * Return object serialized as a string
 588 * `math.hypot(x, y)`
 589     * Get the hypotenuse of a triangle with legs x and y.
 590       Useful for distance calculation.
 591 * `math.sign(x, tolerance)`
 592     * Get the sign of a number.
 593       Optional: Also returns `0` when the absolute value is within the tolerance (default: `0`)
 594 * `string.split(str, separator=",", include_empty=false, max_splits=-1, sep_is_pattern=false)`
 595     * If `max_splits` is negative, do not limit splits.
 596     * `sep_is_pattern` specifies if separator is a plain string or a pattern (regex).
 597     * e.g. `string:split("a,b", ",") == {"a","b"}`
 598 * `string:trim()`
 599     * e.g. `string.trim("\n \t\tfoo bar\t ") == "foo bar"`
 600 * `minetest.wrap_text(str, limit)`: returns a string
 601     * Adds new lines to the string to keep it within the specified character limit
 602     * limit: Maximal amount of characters in one line
 603 * `minetest.pos_to_string({x=X,y=Y,z=Z}, decimal_places))`: returns string `"(X,Y,Z)"`
 604     * Convert position to a printable string
 605       Optional: 'decimal_places' will round the x, y and z of the pos to the given decimal place.
 606 * `minetest.string_to_pos(string)`: returns a position
 607     * Same but in reverse. Returns `nil` if the string can't be parsed to a position.
 608 * `minetest.string_to_area("(X1, Y1, Z1) (X2, Y2, Z2)")`: returns two positions
 609     * Converts a string representing an area box into two positions
 610 * `minetest.is_yes(arg)`
 611     * returns whether `arg` can be interpreted as yes
 612 * `table.copy(table)`: returns a table
 613     * returns a deep copy of `table`
 614
 615 Minetest namespace reference
 616 ------------------------------
 617
 618 ### Utilities
 619
 620 * `minetest.get_current_modname()`: returns the currently loading mod's name, when we are loading a mod
 621 * `minetest.get_language()`: returns the currently set gettext language.
 622 * `minetest.get_version()`: returns a table containing components of the
 623    engine version.  Components:
 624     * `project`: Name of the project, eg, "Minetest"
 625     * `string`: Simple version, eg, "1.2.3-dev"
 626     * `hash`: Full git version (only set if available), eg, "1.2.3-dev-01234567-dirty"
 627   Use this for informational purposes only. The information in the returned
 628   table does not represent the capabilities of the engine, nor is it
 629   reliable or verifiable. Compatible forks will have a different name and
 630   version entirely. To check for the presence of engine features, test
 631   whether the functions exported by the wanted features exist. For example:
 632   `if minetest.check_for_falling then ... end`.
 633 * `minetest.sha1(data, [raw])`: returns the sha1 hash of data
 634     * `data`: string of data to hash
 635     * `raw`: return raw bytes instead of hex digits, default: false
 636
 637 ### Logging
 638 * `minetest.debug(...)`
 639     * Equivalent to `minetest.log(table.concat({...}, "\t"))`
 640 * `minetest.log([level,] text)`
 641     * `level` is one of `"none"`, `"error"`, `"warning"`, `"action"`,
 642       `"info"`, or `"verbose"`.  Default is `"none"`.
 643
 644 ### Global callback registration functions
 645 Call these functions only at load time!
 646
 647 * `minetest.register_globalstep(func(dtime))`
 648     * Called every client environment step, usually interval of 0.1s
 649 * `minetest.register_on_shutdown(func())`
 650     * Called before client shutdown
 651     * **Warning**: If the client terminates abnormally (i.e. crashes), the registered
 652       callbacks **will likely not be run**. Data should be saved at
 653       semi-frequent intervals as well as on server shutdown.
 654 * `minetest.register_on_connect(func())`
 655     * Called at the end of client connection (when player is loaded onto map)
 656 * `minetest.register_on_receiving_chat_message(func(message))`
 657     * Called always when a client receive a message
 658     * Return `true` to mark the message as handled, which means that it will not be shown to chat
 659 * `minetest.register_on_sending_chat_message(func(message))`
 660     * Called always when a client send a message from chat
 661     * Return `true` to mark the message as handled, which means that it will not be sent to server
 662 * `minetest.register_chatcommand(cmd, chatcommand definition)`
 663     * Adds definition to minetest.registered_chatcommands
 664 * `minetest.unregister_chatcommand(name)`
 665     * Unregisters a chatcommands registered with register_chatcommand.
 666 * `minetest.register_on_death(func())`
 667     * Called when the local player dies
 668 * `minetest.register_on_hp_modification(func(hp))`
 669     * Called when server modified player's HP
 670 * `minetest.register_on_damage_taken(func(hp))`
 671     * Called when the local player take damages
 672 * `minetest.register_on_formspec_input(func(formname, fields))`
 673     * Called when a button is pressed in the local player's inventory form
 674     * Newest functions are called first
 675     * If function returns `true`, remaining functions are not called
 676 * `minetest.register_on_dignode(func(pos, node))`
 677     * Called when the local player digs a node
 678     * Newest functions are called first
 679     * If any function returns true, the node isn't dug
 680 * `minetest.register_on_punchnode(func(pos, node))`
 681     * Called when the local player punches a node
 682     * Newest functions are called first
 683     * If any function returns true, the punch is ignored
 684 * `minetest.register_on_placenode(function(pointed_thing, node))`
 685     * Called when a node has been placed
 686 * `minetest.register_on_item_use(func(item, pointed_thing))`
 687     * Called when the local player uses an item.
 688     * Newest functions are called first.
 689     * If any function returns true, the item use is not sent to server.
 690 * `minetest.register_on_modchannel_message(func(channel_name, sender, message))`
 691     * Called when an incoming mod channel message is received
 692     * You must have joined some channels before, and server must acknowledge the
 693       join request.
 694     * If message comes from a server mod, `sender` field is an empty string.
 695 * `minetest.register_on_modchannel_signal(func(channel_name, signal))`
 696     * Called when a valid incoming mod channel signal is received
 697     * Signal id permit to react to server mod channel events
 698     * Possible values are:
 699       0: join_ok
 700       1: join_failed
 701       2: leave_ok
 702       3: leave_failed
 703       4: event_on_not_joined_channel
 704       5: state_changed
 705 * `minetest.register_on_inventory_open(func(inventory))`
 706     * Called when the local player open inventory
 707     * Newest functions are called first
 708     * If any function returns true, inventory doesn't open
 709 ### Sounds
 710 * `minetest.sound_play(spec, parameters)`: returns a handle
 711     * `spec` is a `SimpleSoundSpec`
 712     * `parameters` is a sound parameter table
 713 * `minetest.sound_stop(handle)`
 714
 715 ### Timing
 716 * `minetest.after(time, func, ...)`
 717     * Call the function `func` after `time` seconds, may be fractional
 718     * Optional: Variable number of arguments that are passed to `func`
 719 * `minetest.get_us_time()`
 720     * Returns time with microsecond precision. May not return wall time.
 721 * `minetest.get_day_count()`
 722     * Returns number days elapsed since world was created, accounting for time changes.
 723 * `minetest.get_timeofday()`
 724     * Returns the time of day: `0` for midnight, `0.5` for midday
 725
 726 ### Map
 727 * `minetest.get_node_or_nil(pos)`
 728     * Returns the node at the given position as table in the format
 729       `{name="node_name", param1=0, param2=0}`, returns `nil`
 730       for unloaded areas or flavor limited areas.
 731 * `minetest.find_node_near(pos, radius, nodenames, [search_center])`: returns pos or `nil`
 732     * `radius`: using a maximum metric
 733     * `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
 734     * `search_center` is an optional boolean (default: `false`)
 735       If true `pos` is also checked for the nodes
 736 * `minetest.get_meta(pos)`
 737     * Get a `NodeMetaRef` at that position
 738 * `minetest.get_node_level(pos)`
 739     * get level of leveled node (water, snow)
 740 * `minetest.get_node_max_level(pos)`
 741     * get max available level for leveled node
 742
 743 ### Player
 744 * `minetest.get_wielded_item()`
 745     * Returns the itemstack the local player is holding
 746 * `minetest.send_chat_message(message)`
 747     * Act as if `message` was typed by the player into the terminal.
 748 * `minetest.run_server_chatcommand(cmd, param)`
 749     * Alias for `minetest.send_chat_message("/" .. cmd .. " " .. param)`
 750 * `minetest.clear_out_chat_queue()`
 751     * Clears the out chat queue
 752 * `minetest.localplayer`
 753     * Reference to the LocalPlayer object. See [`LocalPlayer`](#localplayer) class reference for methods.
 754
 755 ### Privileges
 756 * `minetest.get_privilege_list()`
 757     * Returns a list of privileges the current player has in the format `{priv1=true,...}`
 758 * `minetest.string_to_privs(str)`: returns `{priv1=true,...}`
 759 * `minetest.privs_to_string(privs)`: returns `"priv1,priv2,..."`
 760     * Convert between two privilege representations
 761
 762 ### Client Environment
 763 * `minetest.get_player_names()`
 764     * Returns list of player names on server
 765 * `minetest.disconnect()`
 766     * Disconnect from the server and exit to main menu.
 767     * Returns `false` if the client is already disconnecting otherwise returns `true`.
 768 * `minetest.take_screenshot()`
 769     * Take a screenshot.
 770 * `minetest.get_server_info()`
 771     * Returns [server info](#server-info).
 772 * `minetest.send_respawn()`
 773     * Sends a respawn request to the server.
 774
 775 ### Storage API
 776 * `minetest.get_mod_storage()`:
 777     * returns reference to mod private `StorageRef`
 778     * must be called during mod load time
 779
 780 ### Mod channels
 781 ![Mod channels communication scheme](docs/mod channels.png)
 782
 783 * `minetest.mod_channel_join(channel_name)`
 784     * Client joins channel `channel_name`, and creates it, if necessary. You
 785       should listen from incoming messages with `minetest.register_on_modchannel_message`
 786       call to receive incoming messages. Warning, this function is asynchronous.
 787     * You should use a minetest.register_on_connect(function() ... end) to perform
 788       a successful channel join on client startup.
 789
 790 ### Particles
 791 * `minetest.add_particle(particle definition)`
 792
 793 * `minetest.add_particlespawner(particlespawner definition)`
 794     * Add a `ParticleSpawner`, an object that spawns an amount of particles over `time` seconds
 795     * Returns an `id`, and -1 if adding didn't succeed
 796
 797 * `minetest.delete_particlespawner(id)`
 798     * Delete `ParticleSpawner` with `id` (return value from `minetest.add_particlespawner`)
 799
 800 ### Misc.
 801 * `minetest.parse_json(string[, nullvalue])`: returns something
 802     * Convert a string containing JSON data into the Lua equivalent
 803     * `nullvalue`: returned in place of the JSON null; defaults to `nil`
 804     * On success returns a table, a string, a number, a boolean or `nullvalue`
 805     * On failure outputs an error message and returns `nil`
 806     * Example: `parse_json("[10, {\"a\":false}]")`, returns `{10, {a = false}}`
 807 * `minetest.write_json(data[, styled])`: returns a string or `nil` and an error message
 808     * Convert a Lua table into a JSON string
 809     * styled: Outputs in a human-readable format if this is set, defaults to false
 810     * Unserializable things like functions and userdata are saved as null.
 811     * **Warning**: JSON is more strict than the Lua table format.
 812         1. You can only use strings and positive integers of at least one as keys.
 813         2. You can not mix string and integer keys.
 814            This is due to the fact that JSON has two distinct array and object values.
 815     * Example: `write_json({10, {a = false}})`, returns `"[10, {\"a\": false}]"`
 816 * `minetest.serialize(table)`: returns a string
 817     * Convert a table containing tables, strings, numbers, booleans and `nil`s
 818       into string form readable by `minetest.deserialize`
 819     * Example: `serialize({foo='bar'})`, returns `'return { ["foo"] = "bar" }'`
 820 * `minetest.deserialize(string)`: returns a table
 821     * Convert a string returned by `minetest.deserialize` into a table
 822     * `string` is loaded in an empty sandbox environment.
 823     * Will load functions, but they cannot access the global environment.
 824     * Example: `deserialize('return { ["foo"] = "bar" }')`, returns `{foo='bar'}`
 825     * Example: `deserialize('print("foo")')`, returns `nil` (function call fails)
 826         * `error:[string "print("foo")"]:1: attempt to call global 'print' (a nil value)`
 827 * `minetest.compress(data, method, ...)`: returns `compressed_data`
 828     * Compress a string of data.
 829     * `method` is a string identifying the compression method to be used.
 830     * Supported compression methods:
 831     *     Deflate (zlib): `"deflate"`
 832     * `...` indicates method-specific arguments.  Currently defined arguments are:
 833     *     Deflate: `level` - Compression level, `0`-`9` or `nil`.
 834 * `minetest.decompress(compressed_data, method, ...)`: returns data
 835     * Decompress a string of data (using ZLib).
 836     * See documentation on `minetest.compress()` for supported compression methods.
 837     * currently supported.
 838     * `...` indicates method-specific arguments. Currently, no methods use this.
 839 * `minetest.rgba(red, green, blue[, alpha])`: returns a string
 840     * Each argument is a 8 Bit unsigned integer
 841     * Returns the ColorString from rgb or rgba values
 842     * Example: `minetest.rgba(10, 20, 30, 40)`, returns `"#0A141E28"`
 843 * `minetest.encode_base64(string)`: returns string encoded in base64
 844     * Encodes a string in base64.
 845 * `minetest.decode_base64(string)`: returns string
 846     * Decodes a string encoded in base64.
 847 * `minetest.gettext(string)` : returns string
 848     * look up the translation of a string in the gettext message catalog
 849 * `fgettext_ne(string, ...)`
 850     * call minetest.gettext(string), replace "$1"..."$9" with the given
 851       extra arguments and return the result
 852 * `fgettext(string, ...)` : returns string
 853     * same as fgettext_ne(), but calls minetest.formspec_escape before returning result
 854 * `minetest.pointed_thing_to_face_pos(placer, pointed_thing)`: returns a position
 855     * returns the exact position on the surface of a pointed node
 856 * `minetest.global_exists(name)`
 857     * Checks if a global variable has been set, without triggering a warning.
 858
 859 ### UI
 860 * `minetest.ui.minimap`
 861     * Reference to the minimap object. See [`Minimap`](#minimap) class reference for methods.
 862     * If client disabled minimap (using enable_minimap setting) this reference will be nil.
 863 * `minetest.camera`
 864     * Reference to the camera object. See [`Camera`](#camera) class reference for methods.
 865 * `minetest.show_formspec(formname, formspec)` : returns true on success
 866         * Shows a formspec to the player
 867 * `minetest.display_chat_message(message)` returns true on success
 868         * Shows a chat message to the current player.
 869
 870 Class reference
 871 ---------------
 872
 873 ### ModChannel
 874
 875 An interface to use mod channels on client and server
 876
 877 #### Methods
 878 * `leave()`: leave the mod channel.
 879     * Client leaves channel `channel_name`.
 880     * No more incoming or outgoing messages can be sent to this channel from client mods.
 881     * This invalidate all future object usage
 882     * Ensure your set mod_channel to nil after that to free Lua resources
 883 * `is_writeable()`: returns true if channel is writable and mod can send over it.
 884 * `send_all(message)`: Send `message` though the mod channel.
 885     * If mod channel is not writable or invalid, message will be dropped.
 886     * Message size is limited to 65535 characters by protocol.
 887
 888 ### Minimap
 889 An interface to manipulate minimap on client UI
 890
 891 #### Methods
 892 * `show()`: shows the minimap (if not disabled by server)
 893 * `hide()`: hides the minimap
 894 * `set_pos(pos)`: sets the minimap position on screen
 895 * `get_pos()`: returns the minimap current position
 896 * `set_angle(deg)`: sets the minimap angle in degrees
 897 * `get_angle()`: returns the current minimap angle in degrees
 898 * `set_mode(mode)`: sets the minimap mode (0 to 6)
 899 * `get_mode()`: returns the current minimap mode
 900 * `set_shape(shape)`: Sets the minimap shape. (0 = square, 1 = round)
 901 * `get_shape()`: Gets the minimap shape. (0 = square, 1 = round)
 902
 903 ### Camera
 904 An interface to get or set information about the camera and camera-node.
 905 Please do not try to access the reference until the camera is initialized, otherwise the reference will be nil.
 906
 907 #### Methods
 908 * `set_camera_mode(mode)`
 909     * Pass `0` for first-person, `1` for third person, and `2` for third person front
 910 * `get_camera_mode()`
 911     * Returns 0, 1, or 2 as described above
 912 * `get_fov()`
 913     * Returns:
 914
 915 ```lua
 916      {
 917          x = number,
 918          y = number,
 919          max = number,
 920          actual = number
 921      }
 922 ```
 923
 924 * `get_pos()`
 925     * Returns position of camera with view bobbing
 926 * `get_offset()`
 927     * Returns eye offset vector
 928 * `get_look_dir()`
 929     * Returns eye direction unit vector
 930 * `get_look_vertical()`
 931     * Returns pitch in radians
 932 * `get_look_horizontal()`
 933     * Returns yaw in radians
 934 * `get_aspect_ratio()`
 935     * Returns aspect ratio of screen
 936
 937 ### LocalPlayer
 938 An interface to retrieve information about the player. The player is
 939 not accessible until the client is fully done loading and therefore
 940 not at module init time.
 941
 942 To get the localplayer handle correctly, use `on_connect()` as follows:
 943
 944 ```lua
 945 local localplayer
 946 minetest.register_on_connect(function()
 947         localplayer = minetest.localplayer
 948 end)
 949 ```
 950
 951 Methods:
 952
 953 * `get_pos()`
 954     * returns current player current position
 955 * `get_velocity()`
 956     * returns player speed vector
 957 * `get_hp()`
 958     * returns player HP
 959 * `get_name()`
 960     * returns player name
 961 * `is_attached()`
 962     * returns true if player is attached
 963 * `is_touching_ground()`
 964     * returns true if player touching ground
 965 * `is_in_liquid()`
 966     * returns true if player is in a liquid (This oscillates so that the player jumps a bit above the surface)
 967 * `is_in_liquid_stable()`
 968     * returns true if player is in a stable liquid (This is more stable and defines the maximum speed of the player)
 969 * `get_liquid_viscosity()`
 970     * returns liquid viscosity (Gets the viscosity of liquid to calculate friction)
 971 * `is_climbing()`
 972     * returns true if player is climbing
 973 * `swimming_vertical()`
 974     * returns true if player is swimming in vertical
 975 * `get_physics_override()`
 976     * returns:
 977
 978 ```lua
 979     {
 980         speed = float,
 981         jump = float,
 982         gravity = float,
 983         sneak = boolean,
 984         sneak_glitch = boolean
 985     }
 986 ```
 987
 988 * `get_override_pos()`
 989     * returns override position
 990 * `get_last_pos()`
 991     * returns last player position before the current client step
 992 * `get_last_velocity()`
 993     * returns last player speed
 994 * `get_breath()`
 995     * returns the player's breath
 996 * `get_movement_acceleration()`
 997     * returns acceleration of the player in different environments:
 998
 999 ```lua
1000     {
1001        fast = float,
1002        air = float,
1003        default = float,
1004     }
1005 ```
1006
1007 * `get_movement_speed()`
1008     * returns player's speed in different environments:
1009
1010 ```lua
1011     {
1012        walk = float,
1013        jump = float,
1014        crouch = float,
1015        fast = float,
1016        climb = float,
1017     }
1018 ```
1019
1020 * `get_movement()`
1021     * returns player's movement in different environments:
1022
1023 ```lua
1024     {
1025        liquid_fluidity = float,
1026        liquid_sink = float,
1027        liquid_fluidity_smooth = float,
1028        gravity = float,
1029     }
1030 ```
1031
1032 * `get_last_look_horizontal()`:
1033     * returns last look horizontal angle
1034 * `get_last_look_vertical()`:
1035     * returns last look vertical angle
1036 * `get_key_pressed()`:
1037     * returns last key typed by the player
1038 * `hud_add(definition)`
1039     * add a HUD element described by HUD def, returns ID number on success and `nil` on failure.
1040     * See [`HUD definition`](#hud-definition-hud_add-hud_get)
1041 * `hud_get(id)`
1042     * returns the [`definition`](#hud-definition-hud_add-hud_get) of the HUD with that ID number or `nil`, if non-existent.
1043 * `hud_remove(id)`
1044     * remove the HUD element of the specified id, returns `true` on success
1045 * `hud_change(id, stat, value)`
1046     * change a value of a previously added HUD element
1047     * element `stat` values: `position`, `name`, `scale`, `text`, `number`, `item`, `dir`
1048     * Returns `true` on success, otherwise returns `nil`
1049
1050 ### Settings
1051 An interface to read config files in the format of `minetest.conf`.
1052
1053 It can be created via `Settings(filename)`.
1054
1055 #### Methods
1056 * `get(key)`: returns a value
1057 * `get_bool(key)`: returns a boolean
1058 * `set(key, value)`
1059 * `remove(key)`: returns a boolean (`true` for success)
1060 * `get_names()`: returns `{key1,...}`
1061 * `write()`: returns a boolean (`true` for success)
1062     * write changes to file
1063 * `to_table()`: returns `{[key1]=value1,...}`
1064
1065 ### NodeMetaRef
1066 Node metadata: reference extra data and functionality stored in a node.
1067 Can be obtained via `minetest.get_meta(pos)`.
1068
1069 #### Methods
1070 * `get_string(name)`
1071 * `get_int(name)`
1072 * `get_float(name)`
1073 * `to_table()`: returns `nil` or a table with keys:
1074     * `fields`: key-value storage
1075     * `inventory`: `{list1 = {}, ...}}`
1076
1077 -----------------
1078 ### Definitions
1079 * `minetest.get_node_def(nodename)`
1080         * Returns [node definition](#node-definition) table of `nodename`
1081 * `minetest.get_item_def(itemstring)`
1082         * Returns item definition table of `itemstring`
1083
1084 #### Node Definition
1085
1086 ```lua
1087         {
1088                 has_on_construct = bool,        -- Whether the node has the on_construct callback defined
1089                 has_on_destruct = bool,         -- Whether the node has the on_destruct callback defined
1090                 has_after_destruct = bool,      -- Whether the node has the after_destruct callback defined
1091                 name = string,                  -- The name of the node e.g. "air", "default:dirt"
1092                 groups = table,                 -- The groups of the node
1093                 paramtype = string,             -- Paramtype of the node
1094                 paramtype2 = string,            -- ParamType2 of the node
1095                 drawtype = string,              -- Drawtype of the node
1096                 mesh = <string>,                -- Mesh name if existant
1097                 minimap_color = <Color>,        -- Color of node on minimap *May not exist*
1098                 visual_scale = number,          -- Visual scale of node
1099                 alpha = number,                 -- Alpha of the node. Only used for liquids
1100                 color = <Color>,                -- Color of node *May not exist*
1101                 palette_name = <string>,        -- Filename of palette *May not exist*
1102                 palette = <{                    -- List of colors
1103                         Color,
1104                         Color
1105                 }>,
1106                 waving = number,                -- 0 of not waving, 1 if waving
1107                 connect_sides = number,         -- Used for connected nodes
1108                 connects_to = {                 -- List of nodes to connect to
1109                         "node1",
1110                         "node2"
1111                 },
1112                 post_effect_color = Color,      -- Color overlayed on the screen when the player is in the node
1113                 leveled = number,               -- Max level for node
1114                 sunlight_propogates = bool,     -- Whether light passes through the block
1115                 light_source = number,          -- Light emitted by the block
1116                 is_ground_content = bool,       -- Whether caves should cut through the node
1117                 walkable = bool,                -- Whether the player collides with the node
1118                 pointable = bool,               -- Whether the player can select the node
1119                 diggable = bool,                -- Whether the player can dig the node
1120                 climbable = bool,               -- Whether the player can climb up the node
1121                 buildable_to = bool,            -- Whether the player can replace the node by placing a node on it
1122                 rightclickable = bool,          -- Whether the player can place nodes pointing at this node
1123                 damage_per_second = number,     -- HP of damage per second when the player is in the node
1124                 liquid_type = <string>,         -- A string containing "none", "flowing", or "source" *May not exist*
1125                 liquid_alternative_flowing = <string>, -- Alternative node for liquid *May not exist*
1126                 liquid_alternative_source = <string>, -- Alternative node for liquid *May not exist*
1127                 liquid_viscosity = <number>,    -- How fast the liquid flows *May not exist*
1128                 liquid_renewable = <boolean>,   -- Whether the liquid makes an infinite source *May not exist*
1129                 liquid_range = <number>,        -- How far the liquid flows *May not exist*
1130                 drowning = bool,                -- Whether the player will drown in the node
1131                 floodable = bool,               -- Whether nodes will be replaced by liquids (flooded)
1132                 node_box = table,               -- Nodebox to draw the node with
1133                 collision_box = table,          -- Nodebox to set the collision area
1134                 selection_box = table,          -- Nodebox to set the area selected by the player
1135                 sounds = {                      -- Table of sounds that the block makes
1136                         sound_footstep = SimpleSoundSpec,
1137                         sound_dig = SimpleSoundSpec,
1138                         sound_dug = SimpleSoundSpec
1139                 },
1140                 legacy_facedir_simple = bool,   -- Whether to use old facedir
1141                 legacy_wallmounted = bool       -- Whether to use old wallmounted
1142         }
1143 ```
1144
1145 #### Item Definition
1146
1147 ```lua
1148         {
1149                 name = string,                  -- Name of the item e.g. "default:stone"
1150                 description = string,           -- Description of the item e.g. "Stone"
1151                 type = string,                  -- Item type: "none", "node", "craftitem", "tool"
1152                 inventory_image = string,       -- Image in the inventory
1153                 wield_image = string,           -- Image in wieldmesh
1154                 palette_image = string,         -- Image for palette
1155                 color = Color,                  -- Color for item
1156                 wield_scale = Vector,           -- Wieldmesh scale
1157                 stack_max = number,             -- Number of items stackable together
1158                 usable = bool,                  -- Has on_use callback defined
1159                 liquids_pointable = bool,       -- Whether you can point at liquids with the item
1160                 tool_capabilities = <table>,    -- If the item is a tool, tool capabilities of the item
1161                 groups = table,                 -- Groups of the item
1162                 sound_place = SimpleSoundSpec,  -- Sound played when placed
1163                 sound_place_failed = SimpleSoundSpec, -- Sound played when placement failed
1164                 node_placement_prediction = string -- Node placed in client until server catches up
1165         }
1166 ```
1167 -----------------
1168
1169 ### Chat command definition (`register_chatcommand`)
1170
1171     {
1172         params = "<name> <privilege>", -- Short parameter description
1173         description = "Remove privilege from player", -- Full description
1174         func = function(param),        -- Called when command is run.
1175                                        -- Returns boolean success and text output.
1176     }
1177 ### Server info
1178 ```lua
1179 {
1180         address = "minetest.example.org", -- The domain name/IP address of a remote server or "" for a local server.
1181         ip = "203.0.113.156",             -- The IP address of the server.
1182         port = 30000,                     -- The port the client is connected to.
1183         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.
1184 }
1185 ```
1186
1187 ### HUD Definition (`hud_add`, `hud_get`)
1188 ```lua
1189     {
1190         hud_elem_type = "image", -- see HUD element types, default "text"
1191     --  ^ type of HUD element, can be either of "image", "text", "statbar", or "inventory"
1192         position = {x=0.5, y=0.5},
1193     --  ^ Left corner position of element, default `{x=0,y=0}`.
1194         name = "<name>",    -- default ""
1195         scale = {x=2, y=2}, -- default {x=0,y=0}
1196         text = "<text>",    -- default ""
1197         number = 2,         -- default 0
1198         item = 3,           -- default 0
1199     --  ^ Selected item in inventory.  0 for no item selected.
1200         direction = 0,      -- default 0
1201     --  ^ Direction: 0: left-right, 1: right-left, 2: top-bottom, 3: bottom-top
1202         alignment = {x=0, y=0},   -- default {x=0, y=0}
1203     --  ^ See "HUD Element Types"
1204         offset = {x=0, y=0},      -- default {x=0, y=0}
1205     --  ^ See "HUD Element Types"
1206         size = { x=100, y=100 },  -- default {x=0, y=0}
1207     --  ^ Size of element in pixels
1208     }
1209 ```
1210
1211 Escape sequences
1212 ----------------
1213 Most text can contain escape sequences, that can for example color the text.
1214 There are a few exceptions: tab headers, dropdowns and vertical labels can't.
1215 The following functions provide escape sequences:
1216 * `minetest.get_color_escape_sequence(color)`:
1217     * `color` is a [ColorString](#colorstring)
1218     * The escape sequence sets the text color to `color`
1219 * `minetest.colorize(color, message)`:
1220     * Equivalent to:
1221       `minetest.get_color_escape_sequence(color) ..
1222        message ..
1223        minetest.get_color_escape_sequence("#ffffff")`
1224 * `minetest.get_background_escape_sequence(color)`
1225     * `color` is a [ColorString](#colorstring)
1226     * The escape sequence sets the background of the whole text element to
1227       `color`. Only defined for item descriptions and tooltips.
1228 * `minetest.strip_foreground_colors(str)`
1229     * Removes foreground colors added by `get_color_escape_sequence`.
1230 * `minetest.strip_background_colors(str)`
1231     * Removes background colors added by `get_background_escape_sequence`.
1232 * `minetest.strip_colors(str)`
1233     * Removes all color escape sequences.
1234
1235 `ColorString`
1236 -------------
1237 `#RGB` defines a color in hexadecimal format.
1238
1239 `#RGBA` defines a color in hexadecimal format and alpha channel.
1240
1241 `#RRGGBB` defines a color in hexadecimal format.
1242
1243 `#RRGGBBAA` defines a color in hexadecimal format and alpha channel.
1244
1245 Named colors are also supported and are equivalent to
1246 [CSS Color Module Level 4](http://dev.w3.org/csswg/css-color/#named-colors).
1247 To specify the value of the alpha channel, append `#AA` to the end of the color name
1248 (e.g. `colorname#08`). For named colors the hexadecimal string representing the alpha
1249 value must (always) be two hexadecimal digits.
1250
1251 `Color`
1252 -------------
1253 `{a = alpha, r = red, g = green, b = blue}` defines an ARGB8 color.
1254
1255 HUD element types
1256 -----------------
1257 The position field is used for all element types.
1258
1259 To account for differing resolutions, the position coordinates are the percentage
1260 of the screen, ranging in value from `0` to `1`.
1261
1262 The name field is not yet used, but should contain a description of what the
1263 HUD element represents. The direction field is the direction in which something
1264 is drawn.
1265
1266 `0` draws from left to right, `1` draws from right to left, `2` draws from
1267 top to bottom, and `3` draws from bottom to top.
1268
1269 The `alignment` field specifies how the item will be aligned. It ranges from `-1` to `1`,
1270 with `0` being the center, `-1` is moved to the left/up, and `1` is to the right/down.
1271 Fractional values can be used.
1272
1273 The `offset` field specifies a pixel offset from the position. Contrary to position,
1274 the offset is not scaled to screen size. This allows for some precisely-positioned
1275 items in the HUD.
1276
1277 **Note**: `offset` _will_ adapt to screen DPI as well as user defined scaling factor!
1278
1279 Below are the specific uses for fields in each type; fields not listed for that type are ignored.
1280
1281 **Note**: Future revisions to the HUD API may be incompatible; the HUD API is still
1282 in the experimental stages.
1283
1284 ### `image`
1285 Displays an image on the HUD.
1286
1287 * `scale`: The scale of the image, with 1 being the original texture size.
1288   Only the X coordinate scale is used (positive values).
1289   Negative values represent that percentage of the screen it
1290   should take; e.g. `x=-100` means 100% (width).
1291 * `text`: The name of the texture that is displayed.
1292 * `alignment`: The alignment of the image.
1293 * `offset`: offset in pixels from position.
1294
1295 ### `text`
1296 Displays text on the HUD.
1297
1298 * `scale`: Defines the bounding rectangle of the text.
1299   A value such as `{x=100, y=100}` should work.
1300 * `text`: The text to be displayed in the HUD element.
1301 * `number`: An integer containing the RGB value of the color used to draw the text.
1302   Specify `0xFFFFFF` for white text, `0xFF0000` for red, and so on.
1303 * `alignment`: The alignment of the text.
1304 * `offset`: offset in pixels from position.
1305
1306 ### `statbar`
1307 Displays a horizontal bar made up of half-images.
1308
1309 * `text`: The name of the texture that is used.
1310 * `number`: The number of half-textures that are displayed.
1311   If odd, will end with a vertically center-split texture.
1312 * `direction`
1313 * `offset`: offset in pixels from position.
1314 * `size`: If used, will force full-image size to this value (override texture pack image size)
1315
1316 ### `inventory`
1317 * `text`: The name of the inventory list to be displayed.
1318 * `number`: Number of items in the inventory to be displayed.
1319 * `item`: Position of item that is selected.
1320 * `direction`
1321 * `offset`: offset in pixels from position.
1322
1323 ### `waypoint`
1324 Displays distance to selected world position.
1325
1326 * `name`: The name of the waypoint.
1327 * `text`: Distance suffix. Can be blank.
1328 * `number:` An integer containing the RGB value of the color used to draw the text.
1329 * `world_pos`: World position of the waypoint.
1330
1331 ### Particle definition (`add_particle`)
1332
1333     {
1334         pos = {x=0, y=0, z=0},
1335         velocity = {x=0, y=0, z=0},
1336         acceleration = {x=0, y=0, z=0},
1337     --  ^ Spawn particle at pos with velocity and acceleration
1338         expirationtime = 1,
1339     --  ^ Disappears after expirationtime seconds
1340         size = 1,
1341         collisiondetection = false,
1342     --  ^ collisiondetection: if true collides with physical objects
1343         collision_removal = false,
1344     --  ^ collision_removal: if true then particle is removed when it collides,
1345     --  ^ requires collisiondetection = true to have any effect
1346         vertical = false,
1347     --  ^ vertical: if true faces player using y axis only
1348         texture = "image.png",
1349     --  ^ Uses texture (string)
1350         animation = {Tile Animation definition},
1351     --  ^ optional, specifies how to animate the particle texture
1352         glow = 0
1353     --  ^ optional, specify particle self-luminescence in darkness
1354     }
1355
1356 ### `ParticleSpawner` definition (`add_particlespawner`)
1357
1358     {
1359         amount = 1,
1360         time = 1,
1361     --  ^ If time is 0 has infinite lifespan and spawns the amount on a per-second base
1362         minpos = {x=0, y=0, z=0},
1363         maxpos = {x=0, y=0, z=0},
1364         minvel = {x=0, y=0, z=0},
1365         maxvel = {x=0, y=0, z=0},
1366         minacc = {x=0, y=0, z=0},
1367         maxacc = {x=0, y=0, z=0},
1368         minexptime = 1,
1369         maxexptime = 1,
1370         minsize = 1,
1371         maxsize = 1,
1372     --  ^ The particle's properties are random values in between the bounds:
1373     --  ^ minpos/maxpos, minvel/maxvel (velocity), minacc/maxacc (acceleration),
1374     --  ^ minsize/maxsize, minexptime/maxexptime (expirationtime)
1375         collisiondetection = false,
1376     --  ^ collisiondetection: if true uses collision detection
1377         collision_removal = false,
1378     --  ^ collision_removal: if true then particle is removed when it collides,
1379     --  ^ requires collisiondetection = true to have any effect
1380         vertical = false,
1381     --  ^ vertical: if true faces player using y axis only
1382         texture = "image.png",
1383     --  ^ Uses texture (string)
1384     }