doc/client_lua_api.md

   1 Minetest Lua Client Modding API Reference 0.4.15
   2 ================================================
   3 * More information at <http://www.minetest.net/>
   4 * Developer Wiki: <http://dev.minetest.net/>
   5
   6 Introduction
   7 ------------
   8
   9 **WARNING: The client API is currently unstable, and may break/change without warning.**
  10
  11 Content and functionality can be added to Minetest 0.4.15-dev+ by using Lua
  12 scripting in run-time loaded mods.
  13
  14 A mod is a self-contained bunch of scripts, textures and other related
  15 things that is loaded by and interfaces with Minetest.
  16
  17 Transfering client-sided mods form the server to the client is planned, but not implemented yet.
  18
  19 If you see a deficiency in the API, feel free to attempt to add the
  20 functionality in the engine and API. You can send such improvements as
  21 source code patches on GitHub (https://github.com/minetest/minetest).
  22
  23 Programming in Lua
  24 ------------------
  25 If you have any difficulty in understanding this, please read
  26 [Programming in Lua](http://www.lua.org/pil/).
  27
  28 Startup
  29 -------
  30 Mods are loaded during client startup from the mod load paths by running
  31 the `init.lua` scripts in a shared environment.
  32
  33 Paths
  34 -----
  35 * `RUN_IN_PLACE=1` (Windows release, local build)
  36     *  `$path_user`:
  37         * Linux: `<build directory>`
  38         * Windows: `<build directory>`
  39     * `$path_share`
  40         * Linux: `<build directory>`
  41         * Windows:  `<build directory>`
  42 * `RUN_IN_PLACE=0`: (Linux release)
  43     * `$path_share`
  44         * Linux: `/usr/share/minetest`
  45         * Windows: `<install directory>/minetest-0.4.x`
  46     * `$path_user`:
  47         * Linux: `$HOME/.minetest`
  48         * Windows: `C:/users/<user>/AppData/minetest` (maybe)
  49
  50 Mod load path
  51 -------------
  52 Generic:
  53
  54 * `$path_share/clientmods/`
  55 * `$path_user/clientmods/` (User-installed mods)
  56
  57 In a run-in-place version (e.g. the distributed windows version):
  58
  59 * `minetest-0.4.x/clientmods/` (User-installed mods)
  60
  61 On an installed version on Linux:
  62
  63 * `/usr/share/minetest/clientmods/`
  64 * `$HOME/.minetest/clientmods/` (User-installed mods)
  65
  66 Modpack support
  67 ----------------
  68 **NOTE: Not implemented yet.**
  69
  70 Mods can be put in a subdirectory, if the parent directory, which otherwise
  71 should be a mod, contains a file named `modpack.txt`. This file shall be
  72 empty, except for lines starting with `#`, which are comments.
  73
  74 Mod directory structure
  75 ------------------------
  76
  77     clientmods
  78     ├── modname
  79     |   ├── depends.txt
  80     |   ├── init.lua
  81     └── another
  82
  83 ### modname
  84 The location of this directory.
  85
  86 ### depends.txt
  87 List of mods that have to be loaded before loading this mod.
  88
  89 A single line contains a single modname.
  90
  91 Optional dependencies can be defined by appending a question mark
  92 to a single modname. Their meaning is that if the specified mod
  93 is missing, that does not prevent this mod from being loaded.
  94
  95 ### init.lua
  96 The main Lua script. Running this script should register everything it
  97 wants to register. Subsequent execution depends on minetest calling the
  98 registered callbacks.
  99
 100 `minetest.setting_get(name)` and `minetest.setting_getbool(name)` can be used
 101 to read custom or existing settings at load time, if necessary.
 102
 103 ### `sounds`
 104 Media files (sounds) that will be transferred to the
 105 client and will be available for use by the mod.
 106
 107 Naming convention for registered textual names
 108 ----------------------------------------------
 109 Registered names should generally be in this format:
 110
 111     "modname:<whatever>" (<whatever> can have characters a-zA-Z0-9_)
 112
 113 This is to prevent conflicting names from corrupting maps and is
 114 enforced by the mod loader.
 115
 116 ### Example
 117 In the mod `experimental`, there is the ideal item/node/entity name `tnt`.
 118 So the name should be `experimental:tnt`.
 119
 120 Enforcement can be overridden by prefixing the name with `:`. This can
 121 be used for overriding the registrations of some other mod.
 122
 123 Example: Any mod can redefine `experimental:tnt` by using the name
 124
 125     :experimental:tnt
 126
 127 when registering it.
 128 (also that mod is required to have `experimental` as a dependency)
 129
 130 The `:` prefix can also be used for maintaining backwards compatibility.
 131
 132 Sounds
 133 ------
 134 **NOTE: Not fully implemented yet.**
 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 on all clients
 162     {
 163         gain = 1.0, -- default
 164     }
 165     -- Play locationless to one player
 166     {
 167         to_player = name,
 168         gain = 1.0, -- default
 169     }
 170     -- Play locationless to one player, looped
 171     {
 172         to_player = name,
 173         gain = 1.0, -- default
 174         loop = true,
 175     }
 176     -- Play in a location
 177     {
 178         pos = {x = 1, y = 2, z = 3},
 179         gain = 1.0, -- default
 180         max_hear_distance = 32, -- default, uses an euclidean metric
 181     }
 182     -- Play connected to an object, looped
 183     {
 184         object = <an ObjectRef>,
 185         gain = 1.0, -- default
 186         max_hear_distance = 32, -- default, uses an euclidean metric
 187         loop = true,
 188     }
 189
 190 Looped sounds must either be connected to an object or played locationless to
 191 one player using `to_player = name,`
 192
 193 ### SimpleSoundSpec
 194 * e.g. `""`
 195 * e.g. `"default_place_node"`
 196 * e.g. `{}`
 197 * e.g. `{name = "default_place_node"}`
 198 * e.g. `{name = "default_place_node", gain = 1.0}`
 199
 200 Representations of simple things
 201 --------------------------------
 202
 203 ### Position/vector
 204
 205     {x=num, y=num, z=num}
 206
 207 For helper functions see "Vector helpers".
 208
 209 ### pointed_thing
 210 * `{type="nothing"}`
 211 * `{type="node", under=pos, above=pos}`
 212 * `{type="object", ref=ObjectRef}`
 213
 214 Flag Specifier Format
 215 ---------------------
 216 Flags using the standardized flag specifier format can be specified in either of
 217 two ways, by string or table.
 218
 219 The string format is a comma-delimited set of flag names; whitespace and
 220 unrecognized flag fields are ignored. Specifying a flag in the string sets the
 221 flag, and specifying a flag prefixed by the string `"no"` explicitly
 222 clears the flag from whatever the default may be.
 223
 224 In addition to the standard string flag format, the schematic flags field can
 225 also be a table of flag names to boolean values representing whether or not the
 226 flag is set. Additionally, if a field with the flag name prefixed with `"no"`
 227 is present, mapped to a boolean of any value, the specified flag is unset.
 228
 229 E.g. A flag field of value
 230
 231     {place_center_x = true, place_center_y=false, place_center_z=true}
 232
 233 is equivalent to
 234
 235     {place_center_x = true, noplace_center_y=true, place_center_z=true}
 236
 237 which is equivalent to
 238
 239     "place_center_x, noplace_center_y, place_center_z"
 240
 241 or even
 242
 243     "place_center_x, place_center_z"
 244
 245 since, by default, no schematic attributes are set.
 246
 247 Formspec
 248 --------
 249 Formspec defines a menu. It is a string, with a somewhat strange format.
 250
 251 Spaces and newlines can be inserted between the blocks, as is used in the
 252 examples.
 253
 254 ### Examples
 255
 256 #### Chest
 257
 258     size[8,9]
 259     list[context;main;0,0;8,4;]
 260     list[current_player;main;0,5;8,4;]
 261
 262 #### Furnace
 263
 264     size[8,9]
 265     list[context;fuel;2,3;1,1;]
 266     list[context;src;2,1;1,1;]
 267     list[context;dst;5,1;2,2;]
 268     list[current_player;main;0,5;8,4;]
 269
 270 #### Minecraft-like player inventory
 271
 272     size[8,7.5]
 273     image[1,0.6;1,2;player.png]
 274     list[current_player;main;0,3.5;8,4;]
 275     list[current_player;craft;3,0;3,3;]
 276     list[current_player;craftpreview;7,1;1,1;]
 277
 278 ### Elements
 279
 280 #### `size[<W>,<H>,<fixed_size>]`
 281 * Define the size of the menu in inventory slots
 282 * `fixed_size`: `true`/`false` (optional)
 283 * deprecated: `invsize[<W>,<H>;]`
 284
 285 #### `container[<X>,<Y>]`
 286 * Start of a container block, moves all physical elements in the container by (X, Y)
 287 * Must have matching container_end
 288 * Containers can be nested, in which case the offsets are added
 289   (child containers are relative to parent containers)
 290
 291 #### `container_end[]`
 292 * End of a container, following elements are no longer relative to this container
 293
 294 #### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]`
 295 * Show an inventory list
 296
 297 #### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]`
 298 * Show an inventory list
 299
 300 #### `listring[<inventory location>;<list name>]`
 301 * Allows to create a ring of inventory lists
 302 * Shift-clicking on items in one element of the ring
 303   will send them to the next inventory list inside the ring
 304 * The first occurrence of an element inside the ring will
 305   determine the inventory where items will be sent to
 306
 307 #### `listring[]`
 308 * Shorthand for doing `listring[<inventory location>;<list name>]`
 309   for the last two inventory lists added by list[...]
 310
 311 #### `listcolors[<slot_bg_normal>;<slot_bg_hover>]`
 312 * Sets background color of slots as `ColorString`
 313 * Sets background color of slots on mouse hovering
 314
 315 #### `listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>]`
 316 * Sets background color of slots as `ColorString`
 317 * Sets background color of slots on mouse hovering
 318 * Sets color of slots border
 319
 320 #### `listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>;<tooltip_bgcolor>;<tooltip_fontcolor>]`
 321 * Sets background color of slots as `ColorString`
 322 * Sets background color of slots on mouse hovering
 323 * Sets color of slots border
 324 * Sets default background color of tooltips
 325 * Sets default font color of tooltips
 326
 327 #### `tooltip[<gui_element_name>;<tooltip_text>;<bgcolor>,<fontcolor>]`
 328 * Adds tooltip for an element
 329 * `<bgcolor>` tooltip background color as `ColorString` (optional)
 330 * `<fontcolor>` tooltip font color as `ColorString` (optional)
 331
 332 #### `image[<X>,<Y>;<W>,<H>;<texture name>]`
 333 * Show an image
 334 * Position and size units are inventory slots
 335
 336 #### `item_image[<X>,<Y>;<W>,<H>;<item name>]`
 337 * Show an inventory image of registered item/node
 338 * Position and size units are inventory slots
 339
 340 #### `bgcolor[<color>;<fullscreen>]`
 341 * Sets background color of formspec as `ColorString`
 342 * If `true`, the background color is drawn fullscreen (does not effect the size of the formspec)
 343
 344 #### `background[<X>,<Y>;<W>,<H>;<texture name>]`
 345 * Use a background. Inventory rectangles are not drawn then.
 346 * Position and size units are inventory slots
 347 * Example for formspec 8x4 in 16x resolution: image shall be sized
 348   8 times 16px  times  4 times 16px.
 349
 350 #### `background[<X>,<Y>;<W>,<H>;<texture name>;<auto_clip>]`
 351 * Use a background. Inventory rectangles are not drawn then.
 352 * Position and size units are inventory slots
 353 * Example for formspec 8x4 in 16x resolution:
 354   image shall be sized 8 times 16px  times  4 times 16px
 355 * If `true` the background is clipped to formspec size
 356   (`x` and `y` are used as offset values, `w` and `h` are ignored)
 357
 358 #### `pwdfield[<X>,<Y>;<W>,<H>;<name>;<label>]`
 359 * Textual password style field; will be sent to server when a button is clicked
 360 * When enter is pressed in field, fields.key_enter_field will be sent with the name
 361   of this field.
 362 * `x` and `y` position the field relative to the top left of the menu
 363 * `w` and `h` are the size of the field
 364 * Fields are a set height, but will be vertically centred on `h`
 365 * Position and size units are inventory slots
 366 * `name` is the name of the field as returned in fields to `on_receive_fields`
 367 * `label`, if not blank, will be text printed on the top left above the field
 368 * See field_close_on_enter to stop enter closing the formspec
 369
 370 #### `field[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`
 371 * Textual field; will be sent to server when a button is clicked
 372 * When enter is pressed in field, fields.key_enter_field will be sent with the name
 373   of this field.
 374 * `x` and `y` position the field relative to the top left of the menu
 375 * `w` and `h` are the size of the field
 376 * Fields are a set height, but will be vertically centred on `h`
 377 * Position and size units are inventory slots
 378 * `name` is the name of the field as returned in fields to `on_receive_fields`
 379 * `label`, if not blank, will be text printed on the top left above the field
 380 * `default` is the default value of the field
 381     * `default` may contain variable references such as `${text}'` which
 382       will fill the value from the metadata value `text`
 383     * **Note**: no extra text or more than a single variable is supported ATM.
 384 * See field_close_on_enter to stop enter closing the formspec
 385
 386 #### `field[<name>;<label>;<default>]`
 387 * As above, but without position/size units
 388 * When enter is pressed in field, fields.key_enter_field will be sent with the name
 389   of this field.
 390 * Special field for creating simple forms, such as sign text input
 391 * Must be used without a `size[]` element
 392 * A "Proceed" button will be added automatically
 393 * See field_close_on_enter to stop enter closing the formspec
 394
 395 #### `field_close_on_enter[<name>;<close_on_enter>]`
 396 * <name> is the name of the field
 397 * if <close_on_enter> is false, pressing enter in the field will submit the form but not close it
 398 * defaults to true when not specified (ie: no tag for a field)
 399
 400 #### `textarea[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`
 401 * Same as fields above, but with multi-line input
 402
 403 #### `label[<X>,<Y>;<label>]`
 404 * `x` and `y` work as per field
 405 * `label` is the text on the label
 406 * Position and size units are inventory slots
 407
 408 #### `vertlabel[<X>,<Y>;<label>]`
 409 * Textual label drawn vertically
 410 * `x` and `y` work as per field
 411 * `label` is the text on the label
 412 * Position and size units are inventory slots
 413
 414 #### `button[<X>,<Y>;<W>,<H>;<name>;<label>]`
 415 * Clickable button. When clicked, fields will be sent.
 416 * `x`, `y` and `name` work as per field
 417 * `w` and `h` are the size of the button
 418 * `label` is the text on the button
 419 * Position and size units are inventory slots
 420
 421 #### `image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]`
 422 * `x`, `y`, `w`, `h`, and `name` work as per button
 423 * `texture name` is the filename of an image
 424 * Position and size units are inventory slots
 425
 426 #### `image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>;<noclip>;<drawborder>;<pressed texture name>]`
 427 * `x`, `y`, `w`, `h`, and `name` work as per button
 428 * `texture name` is the filename of an image
 429 * Position and size units are inventory slots
 430 * `noclip=true` means the image button doesn't need to be within specified formsize
 431 * `drawborder`: draw button border or not
 432 * `pressed texture name` is the filename of an image on pressed state
 433
 434 #### `item_image_button[<X>,<Y>;<W>,<H>;<item name>;<name>;<label>]`
 435 * `x`, `y`, `w`, `h`, `name` and `label` work as per button
 436 * `item name` is the registered name of an item/node,
 437    tooltip will be made out of its description
 438    to override it use tooltip element
 439 * Position and size units are inventory slots
 440
 441 #### `button_exit[<X>,<Y>;<W>,<H>;<name>;<label>]`
 442 * When clicked, fields will be sent and the form will quit.
 443
 444 #### `image_button_exit[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]`
 445 * When clicked, fields will be sent and the form will quit.
 446
 447 #### `textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>]`
 448 * Scrollable item list showing arbitrary text elements
 449 * `x` and `y` position the itemlist relative to the top left of the menu
 450 * `w` and `h` are the size of the itemlist
 451 * `name` fieldname sent to server on doubleclick value is current selected element
 452 * `listelements` can be prepended by #color in hexadecimal format RRGGBB (only),
 453      * if you want a listelement to start with "#" write "##".
 454
 455 #### `textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>;<selected idx>;<transparent>]`
 456 * Scrollable itemlist showing arbitrary text elements
 457 * `x` and `y` position the item list relative to the top left of the menu
 458 * `w` and `h` are the size of the item list
 459 * `name` fieldname sent to server on doubleclick value is current selected element
 460 * `listelements` can be prepended by #RRGGBB (only) in hexadecimal format
 461      * if you want a listelement to start with "#" write "##"
 462 * Index to be selected within textlist
 463 * `true`/`false`: draw transparent background
 464 * See also `minetest.explode_textlist_event` (main menu: `engine.explode_textlist_event`)
 465
 466 #### `tabheader[<X>,<Y>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]`
 467 * Show a tab**header** at specific position (ignores formsize)
 468 * `x` and `y` position the itemlist relative to the top left of the menu
 469 * `name` fieldname data is transferred to Lua
 470 * `caption 1`...: name shown on top of tab
 471 * `current_tab`: index of selected tab 1...
 472 * `transparent` (optional): show transparent
 473 * `draw_border` (optional): draw border
 474
 475 #### `box[<X>,<Y>;<W>,<H>;<color>]`
 476 * Simple colored semitransparent box
 477 * `x` and `y` position the box relative to the top left of the menu
 478 * `w` and `h` are the size of box
 479 * `color` is color specified as a `ColorString`
 480
 481 #### `dropdown[<X>,<Y>;<W>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>]`
 482 * Show a dropdown field
 483 * **Important note**: There are two different operation modes:
 484      1. handle directly on change (only changed dropdown is submitted)
 485      2. read the value on pressing a button (all dropdown values are available)
 486 * `x` and `y` position of dropdown
 487 * Width of dropdown
 488 * Fieldname data is transferred to Lua
 489 * Items to be shown in dropdown
 490 * Index of currently selected dropdown item
 491
 492 #### `checkbox[<X>,<Y>;<name>;<label>;<selected>]`
 493 * Show a checkbox
 494 * `x` and `y`: position of checkbox
 495 * `name` fieldname data is transferred to Lua
 496 * `label` to be shown left of checkbox
 497 * `selected` (optional): `true`/`false`
 498
 499 #### `scrollbar[<X>,<Y>;<W>,<H>;<orientation>;<name>;<value>]`
 500 * Show a scrollbar
 501 * There are two ways to use it:
 502      1. handle the changed event (only changed scrollbar is available)
 503      2. read the value on pressing a button (all scrollbars are available)
 504 * `x` and `y`: position of trackbar
 505 * `w` and `h`: width and height
 506 * `orientation`:  `vertical`/`horizontal`
 507 * Fieldname data is transferred to Lua
 508 * Value this trackbar is set to (`0`-`1000`)
 509 * See also `minetest.explode_scrollbar_event` (main menu: `engine.explode_scrollbar_event`)
 510
 511 #### `table[<X>,<Y>;<W>,<H>;<name>;<cell 1>,<cell 2>,...,<cell n>;<selected idx>]`
 512 * Show scrollable table using options defined by the previous `tableoptions[]`
 513 * Displays cells as defined by the previous `tablecolumns[]`
 514 * `x` and `y`: position the itemlist relative to the top left of the menu
 515 * `w` and `h` are the size of the itemlist
 516 * `name`: fieldname sent to server on row select or doubleclick
 517 * `cell 1`...`cell n`: cell contents given in row-major order
 518 * `selected idx`: index of row to be selected within table (first row = `1`)
 519 * See also `minetest.explode_table_event` (main menu: `engine.explode_table_event`)
 520
 521 #### `tableoptions[<opt 1>;<opt 2>;...]`
 522 * Sets options for `table[]`
 523 * `color=#RRGGBB`
 524      * default text color (`ColorString`), defaults to `#FFFFFF`
 525 * `background=#RRGGBB`
 526      * table background color (`ColorString`), defaults to `#000000`
 527 * `border=<true/false>`
 528      * should the table be drawn with a border? (default: `true`)
 529 * `highlight=#RRGGBB`
 530      * highlight background color (`ColorString`), defaults to `#466432`
 531 * `highlight_text=#RRGGBB`
 532      * highlight text color (`ColorString`), defaults to `#FFFFFF`
 533 * `opendepth=<value>`
 534      * all subtrees up to `depth < value` are open (default value = `0`)
 535      * only useful when there is a column of type "tree"
 536
 537 #### `tablecolumns[<type 1>,<opt 1a>,<opt 1b>,...;<type 2>,<opt 2a>,<opt 2b>;...]`
 538 * Sets columns for `table[]`
 539 * Types: `text`, `image`, `color`, `indent`, `tree`
 540     * `text`:   show cell contents as text
 541     * `image`:  cell contents are an image index, use column options to define images
 542     * `color`:   cell contents are a ColorString and define color of following cell
 543     * `indent`: cell contents are a number and define indentation of following cell
 544     * `tree`:   same as indent, but user can open and close subtrees (treeview-like)
 545 * Column options:
 546     * `align=<value>`
 547         * for `text` and `image`: content alignment within cells.
 548           Available values: `left` (default), `center`, `right`, `inline`
 549     * `width=<value>`
 550         * for `text` and `image`: minimum width in em (default: `0`)
 551         * for `indent` and `tree`: indent width in em (default: `1.5`)
 552     * `padding=<value>`: padding left of the column, in em (default `0.5`).
 553       Exception: defaults to 0 for indent columns
 554     * `tooltip=<value>`: tooltip text (default: empty)
 555     * `image` column options:
 556         * `0=<value>` sets image for image index 0
 557         * `1=<value>` sets image for image index 1
 558         * `2=<value>` sets image for image index 2
 559         * and so on; defined indices need not be contiguous empty or
 560           non-numeric cells are treated as `0`.
 561     * `color` column options:
 562         * `span=<value>`: number of following columns to affect (default: infinite)
 563
 564 **Note**: do _not_ use a element name starting with `key_`; those names are reserved to
 565 pass key press events to formspec!
 566
 567 Spatial Vectors
 568 ---------------
 569 * `vector.new(a[, b, c])`: returns a vector:
 570     * A copy of `a` if `a` is a vector.
 571     * `{x = a, y = b, z = c}`, if all `a, b, c` are defined
 572 * `vector.direction(p1, p2)`: returns a vector
 573 * `vector.distance(p1, p2)`: returns a number
 574 * `vector.length(v)`: returns a number
 575 * `vector.normalize(v)`: returns a vector
 576 * `vector.floor(v)`: returns a vector, each dimension rounded down
 577 * `vector.round(v)`: returns a vector, each dimension rounded to nearest int
 578 * `vector.apply(v, func)`: returns a vector
 579 * `vector.equals(v1, v2)`: returns a boolean
 580
 581 For the following functions `x` can be either a vector or a number:
 582
 583 * `vector.add(v, x)`: returns a vector
 584 * `vector.subtract(v, x)`: returns a vector
 585 * `vector.multiply(v, x)`: returns a scaled vector or Schur product
 586 * `vector.divide(v, x)`: returns a scaled vector or Schur quotient
 587
 588 Helper functions
 589 ----------------
 590 * `dump2(obj, name="_", dumped={})`
 591      * Return object serialized as a string, handles reference loops
 592 * `dump(obj, dumped={})`
 593     * Return object serialized as a string
 594 * `math.hypot(x, y)`
 595     * Get the hypotenuse of a triangle with legs x and y.
 596       Useful for distance calculation.
 597 * `math.sign(x, tolerance)`
 598     * Get the sign of a number.
 599       Optional: Also returns `0` when the absolute value is within the tolerance (default: `0`)
 600 * `string.split(str, separator=",", include_empty=false, max_splits=-1,
 601 * sep_is_pattern=false)`
 602     * If `max_splits` is negative, do not limit splits.
 603     * `sep_is_pattern` specifies if separator is a plain string or a pattern (regex).
 604     * e.g. `string:split("a,b", ",") == {"a","b"}`
 605 * `string:trim()`
 606     * e.g. `string.trim("\n \t\tfoo bar\t ") == "foo bar"`
 607 * `minetest.is_yes(arg)`
 608     * returns whether `arg` can be interpreted as yes
 609 * `minetest.get_us_time()`
 610     * returns time with microsecond precision. May not return wall time.
 611 * `table.copy(table)`: returns a table
 612     * returns a deep copy of `table`
 613
 614 Minetest namespace reference
 615 ------------------------------
 616
 617 ### Utilities
 618
 619 * `minetest.get_current_modname()`: returns the currently loading mod's name, when we are loading a mod
 620 * `minetest.get_version()`: returns a table containing components of the
 621    engine version.  Components:
 622     * `project`: Name of the project, eg, "Minetest"
 623     * `string`: Simple version, eg, "1.2.3-dev"
 624     * `hash`: Full git version (only set if available), eg, "1.2.3-dev-01234567-dirty"
 625   Use this for informational purposes only. The information in the returned
 626   table does not represent the capabilities of the engine, nor is it
 627   reliable or verifyable. Compatible forks will have a different name and
 628   version entirely. To check for the presence of engine features, test
 629   whether the functions exported by the wanted features exist. For example:
 630   `if minetest.nodeupdate then ... end`.
 631
 632 ### Logging
 633 * `minetest.debug(...)`
 634     * Equivalent to `minetest.log(table.concat({...}, "\t"))`
 635 * `minetest.log([level,] text)`
 636     * `level` is one of `"none"`, `"error"`, `"warning"`, `"action"`,
 637       `"info"`, or `"verbose"`.  Default is `"none"`.
 638
 639 ### Global callback registration functions
 640 Call these functions only at load time!
 641
 642 * `minetest.register_globalstep(func(dtime))`
 643     * Called every client environment step, usually interval of 0.1s
 644 * `minetest.register_on_shutdown(func())`
 645     * Called before client shutdown
 646     * **Warning**: If the client terminates abnormally (i.e. crashes), the registered
 647       callbacks **will likely not be run**. Data should be saved at
 648       semi-frequent intervals as well as on server shutdown.
 649 * `minetest.register_on_receiving_chat_message(func(name, message))`
 650     * Called always when a client receive a message
 651     * Return `true` to mark the message as handled, which means that it will not be shown to chat
 652 * `minetest.register_on_sending_chat_message(func(name, message))`
 653     * Called always when a client send a message from chat
 654     * Return `true` to mark the message as handled, which means that it will not be sent to server
 655 * `minetest.register_chatcommand(cmd, chatcommand definition)`
 656     * Adds definition to minetest.registered_chatcommands
 657 * `minetest.register_on_death(func())`
 658     * Called when the local player dies
 659 * `minetest.register_on_hp_modification(func(hp))`
 660     * Called when server modified player's HP
 661 * `minetest.register_on_damage_taken(func(hp))`
 662     * Called when the local player take damages
 663 * `minetest.register_on_formspec_input(func(formname, fields))`
 664     * Called when a button is pressed in the local player's inventory form
 665     * Newest functions are called first
 666     * If function returns `true`, remaining functions are not called
 667 * `minetest.register_on_dignode(func(pos, node))`
 668     * Called when the local player digs a node
 669     * Newest functions are called first
 670     * If any function returns true, the node isn't dug
 671 * `minetest.register_on_punchnode(func(pos, node))`
 672     * Called when the local player punches a node
 673     * Newest functions are called first
 674     * If any function returns true, the punch is ignored
 675 ### Sounds
 676 * `minetest.sound_play(spec, parameters)`: returns a handle
 677     * `spec` is a `SimpleSoundSpec`
 678     * `parameters` is a sound parameter table
 679 * `minetest.sound_stop(handle)`
 680
 681 ### Timing
 682 * `minetest.after(time, func, ...)`
 683     * Call the function `func` after `time` seconds, may be fractional
 684     * Optional: Variable number of arguments that are passed to `func`
 685
 686 ### Map
 687 * `minetest.get_node(pos)`
 688     * Returns the node at the given position as table in the format
 689       `{name="node_name", param1=0, param2=0}`, returns `{name="ignore", param1=0, param2=0}`
 690       for unloaded areas.
 691 * `minetest.get_node_or_nil(pos)`
 692     * Same as `get_node` but returns `nil` for unloaded areas.
 693
 694 ### Player
 695 * `minetest.get_wielded_item()`
 696     * Returns the itemstack the local player is holding
 697
 698 ### Client Environment
 699 * `minetest.get_player_names()`
 700     * Returns list of player names on server
 701 * `minetest.disconnect()`
 702     * Disconnect from the server and exit to main menu.
 703     * Returns `false` if the client is already disconnecting otherwise returns `true`.
 704
 705 ### Misc.
 706 * `minetest.parse_json(string[, nullvalue])`: returns something
 707     * Convert a string containing JSON data into the Lua equivalent
 708     * `nullvalue`: returned in place of the JSON null; defaults to `nil`
 709     * On success returns a table, a string, a number, a boolean or `nullvalue`
 710     * On failure outputs an error message and returns `nil`
 711     * Example: `parse_json("[10, {\"a\":false}]")`, returns `{10, {a = false}}`
 712 * `minetest.write_json(data[, styled])`: returns a string or `nil` and an error message
 713     * Convert a Lua table into a JSON string
 714     * styled: Outputs in a human-readable format if this is set, defaults to false
 715     * Unserializable things like functions and userdata are saved as null.
 716     * **Warning**: JSON is more strict than the Lua table format.
 717         1. You can only use strings and positive integers of at least one as keys.
 718         2. You can not mix string and integer keys.
 719            This is due to the fact that JSON has two distinct array and object values.
 720     * Example: `write_json({10, {a = false}})`, returns `"[10, {\"a\": false}]"`
 721 * `minetest.serialize(table)`: returns a string
 722     * Convert a table containing tables, strings, numbers, booleans and `nil`s
 723       into string form readable by `minetest.deserialize`
 724     * Example: `serialize({foo='bar'})`, returns `'return { ["foo"] = "bar" }'`
 725 * `minetest.deserialize(string)`: returns a table
 726     * Convert a string returned by `minetest.deserialize` into a table
 727     * `string` is loaded in an empty sandbox environment.
 728     * Will load functions, but they cannot access the global environment.
 729     * Example: `deserialize('return { ["foo"] = "bar" }')`, returns `{foo='bar'}`
 730     * Example: `deserialize('print("foo")')`, returns `nil` (function call fails)
 731         * `error:[string "print("foo")"]:1: attempt to call global 'print' (a nil value)`
 732 * `minetest.compress(data, method, ...)`: returns `compressed_data`
 733     * Compress a string of data.
 734     * `method` is a string identifying the compression method to be used.
 735     * Supported compression methods:
 736     *     Deflate (zlib): `"deflate"`
 737     * `...` indicates method-specific arguments.  Currently defined arguments are:
 738     *     Deflate: `level` - Compression level, `0`-`9` or `nil`.
 739 * `minetest.decompress(compressed_data, method, ...)`: returns data
 740     * Decompress a string of data (using ZLib).
 741     * See documentation on `minetest.compress()` for supported compression methods.
 742     * currently supported.
 743     * `...` indicates method-specific arguments. Currently, no methods use this.
 744 * `minetest.encode_base64(string)`: returns string encoded in base64
 745     * Encodes a string in base64.
 746 * `minetest.decode_base64(string)`: returns string
 747     * Decodes a string encoded in base64.
 748 * `minetest.gettext(string) : returns string
 749     * look up the translation of a string in the gettext message catalog
 750 * `fgettext_ne(string, ...)`
 751     * call minetest.gettext(string), replace "$1"..."$9" with the given
 752       extra arguments and return the result
 753 * `fgettext(string, ...)` : returns string
 754     * same as fgettext_ne(), but calls minetest.formspec_escape before returning result
 755
 756 ### UI
 757 * `minetest.ui.minimap`
 758     * Reference to the minimap object. See `Minimap` class reference for methods.
 759 * `minetest.show_formspec(formname, formspec)` : returns true on success
 760         * Shows a formspec to the player
 761 * `minetest.display_chat_message(message)` returns true on success
 762         * Shows a chat message to the current player.
 763
 764 Class reference
 765 ---------------
 766
 767 ### Minimap
 768 An interface to manipulate minimap on client UI
 769
 770 * `show()`: shows the minimap (if not disabled by server)
 771 * `hide()`: hides the minimap
 772 * `set_pos(pos)`: sets the minimap position on screen
 773 * `get_pos()`: returns the minimap current position
 774 * `set_angle(deg)`: sets the minimap angle in degrees
 775 * `get_angle()`: returns the current minimap angle in degrees
 776 * `set_mode(mode)`: sets the minimap mode (0 to 6)
 777 * `get_mode()`: returns the current minimap mode
 778 * `toggle_shape()`: toggles minimap shape to round or square.
 779
 780 ### Settings
 781 An interface to read config files in the format of `minetest.conf`.
 782
 783 It can be created via `Settings(filename)`.
 784
 785 #### Methods
 786 * `get(key)`: returns a value
 787 * `get_bool(key)`: returns a boolean
 788 * `set(key, value)`
 789 * `remove(key)`: returns a boolean (`true` for success)
 790 * `get_names()`: returns `{key1,...}`
 791 * `write()`: returns a boolean (`true` for success)
 792     * write changes to file
 793 * `to_table()`: returns `{[key1]=value1,...}`
 794
 795 Definition tables
 796 -----------------
 797
 798 ### Chat command definition (`register_chatcommand`)
 799
 800     {
 801         params = "<name> <privilege>", -- Short parameter description
 802         description = "Remove privilege from player", -- Full description
 803         func = function(param), -- Called when command is run.
 804                                       -- Returns boolean success and text output.
 805     }
 806
 807 Escape sequences
 808 ----------------
 809 Most text can contain escape sequences, that can for example color the text.
 810 There are a few exceptions: tab headers, dropdowns and vertical labels can't.
 811 The following functions provide escape sequences:
 812 * `minetest.get_color_escape_sequence(color)`:
 813     * `color` is a ColorString
 814     * The escape sequence sets the text color to `color`
 815 * `minetest.colorize(color, message)`:
 816     * Equivalent to:
 817       `minetest.get_color_escape_sequence(color) ..
 818        message ..
 819        minetest.get_color_escape_sequence("#ffffff")`
 820 * `color.get_background_escape_sequence(color)`
 821     * `color` is a ColorString
 822     * The escape sequence sets the background of the whole text element to
 823       `color`. Only defined for item descriptions and tooltips.
 824 * `color.strip_foreground_colors(str)`
 825     * Removes foreground colors added by `get_color_escape_sequence`.
 826 * `color.strip_background_colors(str)`
 827     * Removes background colors added by `get_background_escape_sequence`.
 828 * `color.strip_colors(str)`
 829     * Removes all color escape sequences.
 830
 831 `ColorString`
 832 -------------
 833 `#RGB` defines a color in hexadecimal format.
 834
 835 `#RGBA` defines a color in hexadecimal format and alpha channel.
 836
 837 `#RRGGBB` defines a color in hexadecimal format.
 838
 839 `#RRGGBBAA` defines a color in hexadecimal format and alpha channel.
 840
 841 Named colors are also supported and are equivalent to
 842 [CSS Color Module Level 4](http://dev.w3.org/csswg/css-color/#named-colors).
 843 To specify the value of the alpha channel, append `#AA` to the end of the color name
 844 (e.g. `colorname#08`). For named colors the hexadecimal string representing the alpha
 845 value must (always) be two hexadecimal digits.