💾 Archived View for gemini.minetest.land › docs › engine › client_lua_api.txt captured on 2022-04-28 at 18:07:39.

View Raw

More Information

-=-=-=-=-=-=-

Minetest Lua Client Modding API Reference 5.6.0
================================================


Introduction
------------



Content and functionality can be added to Minetest 0.4.15-dev+ by using Lua
scripting in run-time loaded mods.

A mod is a self-contained bunch of scripts, textures and other related
things that is loaded by and interfaces with Minetest.

Transferring client-sided mods from the server to the client is planned, but not implemented yet.

If you see a deficiency in the API, feel free to attempt to add the
functionality in the engine and API. You can send such improvements as
source code patches on GitHub (https://github.com/minetest/minetest).

Programming in Lua
------------------
If you have any difficulty in understanding this, please read
[Programming in Lua](http://www.lua.org/pil/).

Startup
-------
Mods are loaded during client startup from the mod load paths by running
the `init.lua` scripts in a shared environment.

In order to load client-side mods, the following conditions need to be satisfied:

1) `$path_user/minetest.conf` contains the setting `enable_client_modding = true`

2) The client-side mod located in `$path_user/clientmods/<modname>` is added to
    `$path_user/clientmods/mods.conf` as `load_mod_<modname> = true`.

Note: Depending on the remote server's settings, client-side mods might not
be loaded or have limited functionality. See setting `csm_restriction_flags` for reference.

Paths
-----

    * `$path_user`: `<build directory>`
    * `$path_share`: `<build directory>`

    * `$path_share`:
        * Linux: `/usr/share/minetest`
        * Windows: `<install directory>/minetest-0.4.x`
    * `$path_user`:
        * Linux: `$HOME/.minetest`
        * Windows: `C:/users/<user>/AppData/minetest` (maybe)

Mod load path
-------------
Generic:



In a run-in-place version (e.g. the distributed windows version):



On an installed version on Linux:



Modpack support
----------------

Mods can be put in a subdirectory, if the parent directory, which otherwise
should be a mod, contains a file named `modpack.conf`.
The file is a key-value store of modpack details.


                 menu.

Mod directory structure
------------------------

    clientmods
    ├── modname
    │   ├── mod.conf
    │   ├── init.lua
    └── another

### modname

The location of this directory.

### mod.conf

An (optional) settings file that provides meta information about the mod.


          folder is wrongly named.

                 menu.

             loaded before this mod.

                      Like a dependency, but no error if the mod doesn't exist.

### `init.lua`

The main Lua script. Running this script should register everything it
wants to register. Subsequent execution depends on minetest calling the
registered callbacks.


themselves. Any media referenced in function calls must already be loaded
(provided by mods that exist on the server).

Naming convention for registered textual names
----------------------------------------------
Registered names should generally be in this format:

    "modname:<whatever>" (<whatever> can have characters a-zA-Z0-9_)

This is to prevent conflicting names from corrupting maps and is
enforced by the mod loader.

### Example
In the mod `experimental`, there is the ideal item/node/entity name `tnt`.
So the name should be `experimental:tnt`.

Enforcement can be overridden by prefixing the name with `:`. This can
be used for overriding the registrations of some other mod.

Example: Any mod can redefine `experimental:tnt` by using the name

    :experimental:tnt

when registering it.
(also that mod is required to have `experimental` as a dependency)

The `:` prefix can also be used for maintaining backwards compatibility.

Sounds
------


Only Ogg Vorbis files are supported.

For positional playing of sounds, only single-channel (mono) files are
supported. Otherwise OpenAL will play them non-positionally.

Mods should generally prefix their sounds with `modname_`, e.g. given
the mod name "`foomod`", a sound could be called:

    foomod_foosound.ogg

Sounds are referred to by their name with a dot, a single digit and the
file extension stripped out. When a sound is played, the actual sound file
is chosen randomly from the matching sounds.

When playing the sound `foomod_foosound`, the sound is chosen randomly
from the available ones of the following files:



Examples of sound parameter tables:

    -- Play locationless
    {
        gain = 1.0, -- default
    }
    -- Play locationless, looped
    {
        gain = 1.0, -- default
        loop = true,
    }
    -- Play in a location
    {
        pos = {x = 1, y = 2, z = 3},
        gain = 1.0, -- default
    }
    -- Play connected to an object, looped
    {
        object = <an ObjectRef>,
        gain = 1.0, -- default
        loop = true,
    }

Looped sounds must either be connected to an object or played locationless.

### SimpleSoundSpec


Representations of simple things
--------------------------------

### Position/vector

    {x=num, y=num, z=num}

For helper functions see "Vector helpers".

### pointed_thing


Flag Specifier Format
---------------------
Flags using the standardized flag specifier format can be specified in either of
two ways, by string or table.

The string format is a comma-delimited set of flag names; whitespace and
unrecognized flag fields are ignored. Specifying a flag in the string sets the
flag, and specifying a flag prefixed by the string `"no"` explicitly
clears the flag from whatever the default may be.

In addition to the standard string flag format, the schematic flags field can
also be a table of flag names to boolean values representing whether or not the
flag is set. Additionally, if a field with the flag name prefixed with `"no"`
is present, mapped to a boolean of any value, the specified flag is unset.

E.g. A flag field of value

    {place_center_x = true, place_center_y=false, place_center_z=true}

is equivalent to

    {place_center_x = true, noplace_center_y=true, place_center_z=true}

which is equivalent to

    "place_center_x, noplace_center_y, place_center_z"

or even

    "place_center_x, place_center_z"

since, by default, no schematic attributes are set.

Formspec
--------
Formspec defines a menu. It is a string, with a somewhat strange format.

Spaces and newlines can be inserted between the blocks, as is used in the
examples.

### Examples

#### Chest

    size[8,9]
    list[context;main;0,0;8,4;]
    list[current_player;main;0,5;8,4;]

#### Furnace

    size[8,9]
    list[context;fuel;2,3;1,1;]
    list[context;src;2,1;1,1;]
    list[context;dst;5,1;2,2;]
    list[current_player;main;0,5;8,4;]

#### Minecraft-like player inventory

    size[8,7.5]
    image[1,0.6;1,2;player.png]
    list[current_player;main;0,3.5;8,4;]
    list[current_player;craft;3,0;3,3;]
    list[current_player;craftpreview;7,1;1,1;]

### Elements

#### `size[<W>,<H>,<fixed_size>]`


#### `container[<X>,<Y>]`

  (child containers are relative to parent containers)

#### `container_end[]`


#### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]`


#### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]`


#### `listring[<inventory location>;<list name>]`

  will send them to the next inventory list inside the ring

  determine the inventory where items will be sent to

#### `listring[]`

  for the last two inventory lists added by list[...]

#### `listcolors[<slot_bg_normal>;<slot_bg_hover>]`


#### `listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>]`


#### `listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>;<tooltip_bgcolor>;<tooltip_fontcolor>]`


#### `tooltip[<gui_element_name>;<tooltip_text>;<bgcolor>,<fontcolor>]`


#### `image[<X>,<Y>;<W>,<H>;<texture name>]`


#### `item_image[<X>,<Y>;<W>,<H>;<item name>]`


#### `bgcolor[<color>;<fullscreen>]`


#### `background[<X>,<Y>;<W>,<H>;<texture name>]`

  8 times 16px  times  4 times 16px.

#### `background[<X>,<Y>;<W>,<H>;<texture name>;<auto_clip>]`

  image shall be sized 8 times 16px  times  4 times 16px

  (`x` and `y` are used as offset values, `w` and `h` are ignored)

#### `pwdfield[<X>,<Y>;<W>,<H>;<name>;<label>]`

  of this field.


#### `field[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`

  of this field.

    * `default` may contain variable references such as `${text}'` which
      will fill the value from the metadata value `text`
    * **Note**: no extra text or more than a single variable is supported ATM.


#### `field[<name>;<label>;<default>]`

  of this field.


#### `field_close_on_enter[<name>;<close_on_enter>]`


#### `textarea[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`


#### `label[<X>,<Y>;<label>]`


#### `vertlabel[<X>,<Y>;<label>]`


#### `button[<X>,<Y>;<W>,<H>;<name>;<label>]`


#### `image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]`


#### `image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>;<noclip>;<drawborder>;<pressed texture name>]`


#### `item_image_button[<X>,<Y>;<W>,<H>;<item name>;<name>;<label>]`

   tooltip will be made out of its description
   to override it use tooltip element


#### `button_exit[<X>,<Y>;<W>,<H>;<name>;<label>]`


#### `image_button_exit[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]`


#### `textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>]`

     * if you want a listelement to start with "#" write "##".

#### `textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>;<selected idx>;<transparent>]`

     * if you want a listelement to start with "#" write "##"


#### `tabheader[<X>,<Y>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]`


#### `box[<X>,<Y>;<W>,<H>;<color>]`


#### `dropdown[<X>,<Y>;<W>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>]`

     1. handle directly on change (only changed dropdown is submitted)
     2. read the value on pressing a button (all dropdown values are available)


#### `checkbox[<X>,<Y>;<name>;<label>;<selected>]`


#### `scrollbar[<X>,<Y>;<W>,<H>;<orientation>;<name>;<value>]`

     1. handle the changed event (only changed scrollbar is available)
     2. read the value on pressing a button (all scrollbars are available)


#### `table[<X>,<Y>;<W>,<H>;<name>;<cell 1>,<cell 2>,...,<cell n>;<selected idx>]`


#### `tableoptions[<opt 1>;<opt 2>;...]`

     * default text color (`ColorString`), defaults to `#FFFFFF`

     * table background color (`ColorString`), defaults to `#000000`

     * should the table be drawn with a border? (default: `true`)

     * highlight background color (`ColorString`), defaults to `#466432`

     * highlight text color (`ColorString`), defaults to `#FFFFFF`

     * all subtrees up to `depth < value` are open (default value = `0`)
     * only useful when there is a column of type "tree"

#### `tablecolumns[<type 1>,<opt 1a>,<opt 1b>,...;<type 2>,<opt 2a>,<opt 2b>;...]`

    * `text`:   show cell contents as text
    * `image`:  cell contents are an image index, use column options to define images
    * `color`:   cell contents are a ColorString and define color of following cell
    * `indent`: cell contents are a number and define indentation of following cell
    * `tree`:   same as indent, but user can open and close subtrees (treeview-like)

    * `align=<value>`
        * for `text` and `image`: content alignment within cells.
          Available values: `left` (default), `center`, `right`, `inline`
    * `width=<value>`
        * for `text` and `image`: minimum width in em (default: `0`)
        * for `indent` and `tree`: indent width in em (default: `1.5`)
    * `padding=<value>`: padding left of the column, in em (default `0.5`).
      Exception: defaults to 0 for indent columns
    * `tooltip=<value>`: tooltip text (default: empty)
    * `image` column options:
        * `0=<value>` sets image for image index 0
        * `1=<value>` sets image for image index 1
        * `2=<value>` sets image for image index 2
        * and so on; defined indices need not be contiguous empty or
          non-numeric cells are treated as `0`.
    * `color` column options:
        * `span=<value>`: number of following columns to affect (default: infinite)


pass key press events to formspec!

Spatial Vectors
---------------

    * A copy of `a` if `a` is a vector.
    * `{x = a, y = b, z = c}`, if all `a, b, c` are defined


For the following functions `x` can be either a vector or a number:



Helper functions
----------------

     * Return object serialized as a string, handles reference loops

    * Return object serialized as a string

    * Get the hypotenuse of a triangle with legs x and y.
      Useful for distance calculation.

    * Get the sign of a number.
      Optional: Also returns `0` when the absolute value is within the tolerance (default: `0`)

    * If `max_splits` is negative, do not limit splits.
    * `sep_is_pattern` specifies if separator is a plain string or a pattern (regex).
    * e.g. `string:split("a,b", ",") == {"a","b"}`

    * e.g. `string.trim("\n \t\tfoo bar\t ") == "foo bar"`

    * Adds new lines to the string to keep it within the specified character limit
    * limit: Maximal amount of characters in one line

    * Convert position to a printable string
      Optional: 'decimal_places' will round the x, y and z of the pos to the given decimal place.

    * Same but in reverse. Returns `nil` if the string can't be parsed to a position.

    * Converts a string representing an area box into two positions

    * returns whether `arg` can be interpreted as yes

    * returns true when the passed number represents NaN.

    * returns a deep copy of `table`

Minetest namespace reference
------------------------------

### Utilities


   the trailing separator. This is useful to load additional Lua files
   contained in your mod:
   e.g. `dofile(minetest.get_modpath(minetest.get_current_modname()) .. "stuff.lua")`

   * the current gettext locale
   * the current language code (the same as used for client-side translations)

   engine version.  Components:
    * `project`: Name of the project, eg, "Minetest"
    * `string`: Simple version, eg, "1.2.3-dev"
    * `hash`: Full git version (only set if available), eg, "1.2.3-dev-01234567-dirty"
  Use this for informational purposes only. The information in the returned
  table does not represent the capabilities of the engine, nor is it
  reliable or verifiable. Compatible forks will have a different name and
  version entirely. To check for the presence of engine features, test
  whether the functions exported by the wanted features exist. For example:
  `if minetest.check_for_falling then ... end`.

    * `data`: string of data to hash
    * `raw`: return raw bytes instead of hex digits, default: false

  ColorString. If the ColorSpec is invalid, returns `nil`.
    * `colorspec`: The ColorSpec to convert

   restrictions applied to the current mod.
   * If a flag in this table is set to true, the feature is RESTRICTED.
   * Possible flags: `load_client_mods`, `chat_messages`, `read_itemdefs`,
                   `read_nodedefs`, `lookup_nodes`, `read_playerinfo`

### Logging

    * Equivalent to `minetest.log(table.concat({...}, "\t"))`

    * `level` is one of `"none"`, `"error"`, `"warning"`, `"action"`,
      `"info"`, or `"verbose"`.  Default is `"none"`.

### Global callback registration functions
Call these functions only at load time!


    * Called every client environment step, usually interval of 0.1s

    * Called just after mods have finished loading.

    * Called before client shutdown
    * **Warning**: If the client terminates abnormally (i.e. crashes), the registered
      callbacks **will likely not be run**. Data should be saved at
      semi-frequent intervals as well as on server shutdown.

    * Called always when a client receive a message
    * Return `true` to mark the message as handled, which means that it will not be shown to chat

    * Called always when a client send a message from chat
    * Return `true` to mark the message as handled, which means that it will not be sent to server

    * Adds definition to minetest.registered_chatcommands

    * Unregisters a chatcommands registered with register_chatcommand.

    * Called always when a chatcommand is triggered, before `minetest.registered_chatcommands`
      is checked to see if that the command exists, but after the input is parsed.
    * Return `true` to mark the command as handled, which means that the default
      handlers will be prevented.

    * Called when the local player dies

    * Called when server modified player's HP

    * Called when the local player take damages

    * Called when a button is pressed in the local player's inventory form
    * Newest functions are called first
    * If function returns `true`, remaining functions are not called

    * Called when the local player digs a node
    * Newest functions are called first
    * If any function returns true, the node isn't dug

    * Called when the local player punches a node
    * Newest functions are called first
    * If any function returns true, the punch is ignored

    * Called when a node has been placed

    * Called when the local player uses an item.
    * Newest functions are called first.
    * If any function returns true, the item use is not sent to server.

    * Called when an incoming mod channel message is received
    * You must have joined some channels before, and server must acknowledge the
      join request.
    * If message comes from a server mod, `sender` field is an empty string.

    * Called when a valid incoming mod channel signal is received
    * Signal id permit to react to server mod channel events
    * Possible values are:
      0: join_ok
      1: join_failed
      2: leave_ok
      3: leave_failed
      4: event_on_not_joined_channel
      5: state_changed

    * Called when the local player open inventory
    * Newest functions are called first
    * If any function returns true, inventory doesn't open
### Sounds

    * `spec` is a `SimpleSoundSpec`
    * `parameters` is a sound parameter table

    * `handle` is a handle returned by `minetest.sound_play`

    * `handle` is a handle returned by `minetest.sound_play`
    * `step` determines how fast a sound will fade.
      Negative step will lower the sound volume, positive step will increase
      the sound volume.
    * `gain` the target gain for the fade.

### Timing

    * Call the function `func` after `time` seconds, may be fractional
    * Optional: Variable number of arguments that are passed to `func`

    * Returns time with microsecond precision. May not return wall time.

    * Returns the time of day: `0` for midnight, `0.5` for midday

### Map

    * Returns the node at the given position as table in the format
      `{name="node_name", param1=0, param2=0}`, returns `nil`
      for unloaded areas or flavor limited areas.

    * Gets the light value at the given position. Note that the light value
      "inside" the node at the given position is returned, so you usually want
      to get the light value of a neighbor.
    * `pos`: The position where to measure the light.
    * `timeofday`: `nil` for current time, `0` for night, `0.5` for day
    * Returns a number between `0` and `15` or `nil`

    * `radius`: using a maximum metric
    * `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
    * `search_center` is an optional boolean (default: `false`)
      If true `pos` is also checked for the nodes

    * `pos1` and `pos2` are the min and max positions of the area to search.
    * `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
    * If `grouped` is true the return value is a table indexed by node name
      which contains lists of positions.
    * If `grouped` is false or absent the return values are as follows:
      first value: Table with all node positions
      second value: Table with the count of each node with the node name
      as index
    * Area volume is limited to 4,096,000 nodes

  list of positions.
    * `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
    * Return value: Table with all node positions with a node air above
    * Area volume is limited to 4,096,000 nodes

    * Checks if there is anything other than air between pos1 and pos2.
    * Returns false if something is blocking the sight.
    * Returns the position of the blocking node when `false`
    * `pos1`: First position
    * `pos2`: Second position

    * Creates a `Raycast` object.
    * `pos1`: start of the ray
    * `pos2`: end of the ray
    * `objects`: if false, only nodes will be returned. Default is `true`.
    * `liquids`: if false, liquid nodes won't be returned. Default is `false`.


    * Get a table of positions of nodes that have metadata within a region
      {pos1, pos2}.

    * Get a `NodeMetaRef` at that position

    * get level of leveled node (water, snow)

    * get max available level for leveled node

### Player

    * Act as if `message` was typed by the player into the terminal.

    * Alias for `minetest.send_chat_message("/" .. cmd .. " " .. param)`

    * Clears the out chat queue

    * Reference to the LocalPlayer object. See [`LocalPlayer`](#localplayer) class reference for methods.

### Privileges

    * Returns a list of privileges the current player has in the format `{priv1=true,...}`

    * Convert between two privilege representations

### Client Environment

    * Returns list of player names on server (nil if CSM_RF_READ_PLAYERINFO is enabled by server)

    * Disconnect from the server and exit to main menu.
    * Returns `false` if the client is already disconnecting otherwise returns `true`.

    * Returns [server info](#server-info).

    * Sends a respawn request to the server.

### Storage API

    * returns reference to mod private `StorageRef`
    * must be called during mod load time

### Mod channels
![Mod channels communication scheme](docs/mod channels.png)


    * Client joins channel `channel_name`, and creates it, if necessary. You
      should listen from incoming messages with `minetest.register_on_modchannel_message`
      call to receive incoming messages. Warning, this function is asynchronous.

### Particles



    * Add a `ParticleSpawner`, an object that spawns an amount of particles over `time` seconds
    * Returns an `id`, and -1 if adding didn't succeed


    * Delete `ParticleSpawner` with `id` (return value from `minetest.add_particlespawner`)

### Misc.

    * Convert a string containing JSON data into the Lua equivalent
    * `nullvalue`: returned in place of the JSON null; defaults to `nil`
    * On success returns a table, a string, a number, a boolean or `nullvalue`
    * On failure outputs an error message and returns `nil`
    * Example: `parse_json("[10, {\"a\":false}]")`, returns `{10, {a = false}}`

    * Convert a Lua table into a JSON string
    * styled: Outputs in a human-readable format if this is set, defaults to false
    * Unserializable things like functions and userdata are saved as null.
    * **Warning**: JSON is more strict than the Lua table format.
        1. You can only use strings and positive integers of at least one as keys.
        2. You can not mix string and integer keys.
           This is due to the fact that JSON has two distinct array and object values.
    * Example: `write_json({10, {a = false}})`, returns `"[10, {\"a\": false}]"`

    * Convert a table containing tables, strings, numbers, booleans and `nil`s
      into string form readable by `minetest.deserialize`
    * Example: `serialize({foo='bar'})`, returns `'return { ["foo"] = "bar" }'`

    * Convert a string returned by `minetest.deserialize` into a table
    * `string` is loaded in an empty sandbox environment.
    * Will load functions, but they cannot access the global environment.
    * Example: `deserialize('return { ["foo"] = "bar" }')`, returns `{foo='bar'}`
    * Example: `deserialize('print("foo")')`, returns `nil` (function call fails)
        * `error:[string "print("foo")"]:1: attempt to call global 'print' (a nil value)`

    * Compress a string of data.
    * `method` is a string identifying the compression method to be used.
    * Supported compression methods:
    *     Deflate (zlib): `"deflate"`
    * `...` indicates method-specific arguments.  Currently defined arguments are:
    *     Deflate: `level` - Compression level, `0`-`9` or `nil`.

    * Decompress a string of data (using ZLib).
    * See documentation on `minetest.compress()` for supported compression methods.
    * currently supported.
    * `...` indicates method-specific arguments. Currently, no methods use this.

    * Each argument is a 8 Bit unsigned integer
    * Returns the ColorString from rgb or rgba values
    * Example: `minetest.rgba(10, 20, 30, 40)`, returns `"#0A141E28"`

    * Encodes a string in base64.

    * Padding characters are only supported starting at version 5.4.0, where
      5.5.0 and newer perform proper checks.
    * Decodes a string encoded in base64.

    * look up the translation of a string in the gettext message catalog

    * call minetest.gettext(string), replace "$1"..."$9" with the given
      extra arguments and return the result

    * same as fgettext_ne(), but calls minetest.formspec_escape before returning result

    * returns the exact position on the surface of a pointed node

    * Checks if a global variable has been set, without triggering a warning.

### UI

    * Reference to the minimap object. See [`Minimap`](#minimap) class reference for methods.
    * If client disabled minimap (using enable_minimap setting) this reference will be nil.

    * Reference to the camera object. See [`Camera`](#camera) class reference for methods.

	* Shows a formspec to the player

	* Shows a chat message to the current player.

Class reference
---------------

### ModChannel

An interface to use mod channels on client and server

#### Methods

    * Client leaves channel `channel_name`.
    * No more incoming or outgoing messages can be sent to this channel from client mods.
    * This invalidate all future object usage
    * Ensure your set mod_channel to nil after that to free Lua resources

    * If mod channel is not writable or invalid, message will be dropped.
    * Message size is limited to 65535 characters by protocol.

### Minimap
An interface to manipulate minimap on client UI

#### Methods


### Camera
An interface to get or set information about the camera and camera-node.
Please do not try to access the reference until the camera is initialized, otherwise the reference will be nil.

#### Methods

    * Pass `0` for first-person, `1` for third person, and `2` for third person front

    * Returns 0, 1, or 2 as described above

    * Returns a table with X, Y, maximum and actual FOV in degrees:

{

x = number,

y = number,

max = number,

actual = number

}



    * Returns position of camera with view bobbing

    * Returns eye offset vector

    * Returns eye direction unit vector

    * Returns pitch in radians

    * Returns yaw in radians

    * Returns aspect ratio of screen

### LocalPlayer
An interface to retrieve information about the player.
This object will only be available after the client is initialized. Earlier accesses will yield a `nil` value.

Methods:


    * returns current player current position

    * returns player speed vector

    * returns player HP

    * returns player name

    * returns the index of the wielded item

    * returns the itemstack the player is holding

    * returns true if player is attached

    * returns true if player touching ground

    * returns true if player is in a liquid (This oscillates so that the player jumps a bit above the surface)

    * returns true if player is in a stable liquid (This is more stable and defines the maximum speed of the player)

    * returns move resistance of current node, the higher the slower the player moves

    * returns true if player is climbing

    * returns true if player is swimming in vertical

    * returns:

{

speed = float,

jump = float,

gravity = float,

sneak = boolean,

sneak_glitch = boolean,

new_move = boolean,

}



    * returns override position

    * returns last player position before the current client step

    * returns last player speed

    * returns the player's breath

    * returns acceleration of the player in different environments:

{

fast = float,

air = float,

default = float,

}



    * returns player's speed in different environments:

{

walk = float,

jump = float,

crouch = float,

fast = float,

climb = float,

}



    * returns player's movement in different environments:

{

liquid_fluidity = float,

liquid_sink = float,

liquid_fluidity_smooth = float,

gravity = float,

}



    * returns last look horizontal angle

    * returns last look vertical angle

    * returns pressed player controls

{

up = boolean,

down = boolean,

left = boolean,

right = boolean,

jump = boolean,

aux1 = boolean,

sneak = boolean,

zoom = boolean,

dig = boolean,

place = boolean,

}



    * returns a table with the armor group ratings

    * add a HUD element described by HUD def, returns ID number on success and `nil` on failure.
    * See [`HUD definition`](#hud-definition-hud_add-hud_get)

    * returns the [`definition`](#hud-definition-hud_add-hud_get) of the HUD with that ID number or `nil`, if non-existent.

    * remove the HUD element of the specified id, returns `true` on success

    * change a value of a previously added HUD element
    * element `stat` values: `position`, `name`, `scale`, `text`, `number`, `item`, `dir`
    * Returns `true` on success, otherwise returns `nil`

### Settings
An interface to read config files in the format of `minetest.conf`.

It can be created via `Settings(filename)`.

#### Methods

    * write changes to file


### NodeMetaRef
Node metadata: reference extra data and functionality stored in a node.
Can be obtained via `minetest.get_meta(pos)`.

#### Methods

    * `fields`: key-value storage
    * `inventory`: `{list1 = {}, ...}}`

### `Raycast`

A raycast on the map. It works with selection boxes.
Can be used as an iterator in a for loop as:

    local ray = Raycast(...)
    for pointed_thing in ray do
        ...
    end

The map is loaded as the ray advances. If the map is modified after the
`Raycast` is created, the changes may or may not have an effect on the object.

It can be created via `Raycast(pos1, pos2, objects, liquids)` or
`minetest.raycast(pos1, pos2, objects, liquids)` where:



#### Methods


    * Returns the next thing pointed by the ray or nil.

-----------------
### Definitions

	* Returns [node definition](#node-definition) table of `nodename`

	* Returns item definition table of `itemstring`

#### Node Definition

{

has_on_construct = bool, -- Whether the node has the on_construct callback defined

has_on_destruct = bool, -- Whether the node has the on_destruct callback defined

has_after_destruct = bool, -- Whether the node has the after_destruct callback defined

name = string, -- The name of the node e.g. "air", "default:dirt"

groups = table, -- The groups of the node

paramtype = string, -- Paramtype of the node

paramtype2 = string, -- ParamType2 of the node

drawtype = string, -- Drawtype of the node

mesh = <string>, -- Mesh name if existant

minimap_color = <Color>, -- Color of node on minimap *May not exist*

visual_scale = number, -- Visual scale of node

alpha = number, -- Alpha of the node. Only used for liquids

color = <Color>, -- Color of node *May not exist*

palette_name = <string>, -- Filename of palette *May not exist*

palette = <{ -- List of colors

Color,

Color

}>,

waving = number, -- 0 of not waving, 1 if waving

connect_sides = number, -- Used for connected nodes

connects_to = { -- List of nodes to connect to

"node1",

"node2"

},

post_effect_color = Color, -- Color overlayed on the screen when the player is in the node

leveled = number, -- Max level for node

sunlight_propogates = bool, -- Whether light passes through the block

light_source = number, -- Light emitted by the block

is_ground_content = bool, -- Whether caves should cut through the node

walkable = bool, -- Whether the player collides with the node

pointable = bool, -- Whether the player can select the node

diggable = bool, -- Whether the player can dig the node

climbable = bool, -- Whether the player can climb up the node

buildable_to = bool, -- Whether the player can replace the node by placing a node on it

rightclickable = bool, -- Whether the player can place nodes pointing at this node

damage_per_second = number, -- HP of damage per second when the player is in the node

liquid_type = <string>, -- A string containing "none", "flowing", or "source" *May not exist*

liquid_alternative_flowing = <string>, -- Alternative node for liquid *May not exist*

liquid_alternative_source = <string>, -- Alternative node for liquid *May not exist*

liquid_viscosity = <number>, -- How slow the liquid flows *May not exist*

liquid_renewable = <boolean>, -- Whether the liquid makes an infinite source *May not exist*

liquid_range = <number>, -- How far the liquid flows *May not exist*

drowning = bool, -- Whether the player will drown in the node

floodable = bool, -- Whether nodes will be replaced by liquids (flooded)

node_box = table, -- Nodebox to draw the node with

collision_box = table, -- Nodebox to set the collision area

selection_box = table, -- Nodebox to set the area selected by the player

sounds = { -- Table of sounds that the block makes

sound_footstep = SimpleSoundSpec,

sound_dig = SimpleSoundSpec,

sound_dug = SimpleSoundSpec

},

legacy_facedir_simple = bool, -- Whether to use old facedir

legacy_wallmounted = bool -- Whether to use old wallmounted

move_resistance = <number>, -- How slow players can move through the node *May not exist*

}


#### Item Definition

{

name = string, -- Name of the item e.g. "default:stone"

description = string, -- Description of the item e.g. "Stone"

type = string, -- Item type: "none", "node", "craftitem", "tool"

inventory_image = string, -- Image in the inventory

wield_image = string, -- Image in wieldmesh

palette_image = string, -- Image for palette

color = Color, -- Color for item

wield_scale = Vector, -- Wieldmesh scale

stack_max = number, -- Number of items stackable together

usable = bool, -- Has on_use callback defined

liquids_pointable = bool, -- Whether you can point at liquids with the item

tool_capabilities = <table>, -- If the item is a tool, tool capabilities of the item

groups = table, -- Groups of the item

sound_place = SimpleSoundSpec, -- Sound played when placed

sound_place_failed = SimpleSoundSpec, -- Sound played when placement failed

node_placement_prediction = string -- Node placed in client until server catches up

}

-----------------

### Chat command definition (`register_chatcommand`)

    {
        params = "<name> <privilege>", -- Short parameter description
        description = "Remove privilege from player", -- Full description
        func = function(param),        -- Called when command is run.
                                       -- Returns boolean success and text output.
    }
### Server info

{

address = "minetest.example.org", -- The domain name/IP address of a remote server or "" for a local server.

ip = "203.0.113.156", -- The IP address of the server.

port = 30000, -- The port the client is connected to.

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.

}


### HUD Definition (`hud_add`, `hud_get`)

{

hud_elem_type = "image", -- see HUD element types, default "text"

-- ^ type of HUD element, can be either of "image", "text", "statbar", or "inventory"

position = {x=0.5, y=0.5},

-- ^ Left corner position of element, default `{x=0,y=0}`.

name = "<name>", -- default ""

scale = {x=2, y=2}, -- default {x=0,y=0}

text = "<text>", -- default ""

number = 2, -- default 0

item = 3, -- default 0

-- ^ Selected item in inventory. 0 for no item selected.

direction = 0, -- default 0

-- ^ Direction: 0: left-right, 1: right-left, 2: top-bottom, 3: bottom-top

alignment = {x=0, y=0}, -- default {x=0, y=0}

-- ^ See "HUD Element Types"

offset = {x=0, y=0}, -- default {x=0, y=0}

-- ^ See "HUD Element Types"

size = { x=100, y=100 }, -- default {x=0, y=0}

-- ^ Size of element in pixels

style = 0,

-- ^ For "text" elements sets font style: bitfield with 1 = bold, 2 = italic, 4 = monospace

}


Escape sequences
----------------
Most text can contain escape sequences, that can for example color the text.
There are a few exceptions: tab headers, dropdowns and vertical labels can't.
The following functions provide escape sequences:

    * `color` is a [ColorString](#colorstring)
    * The escape sequence sets the text color to `color`

    * Equivalent to:
      `minetest.get_color_escape_sequence(color) ..
       message ..
       minetest.get_color_escape_sequence("#ffffff")`

    * `color` is a [ColorString](#colorstring)
    * The escape sequence sets the background of the whole text element to
      `color`. Only defined for item descriptions and tooltips.

    * Removes foreground colors added by `get_color_escape_sequence`.

    * Removes background colors added by `get_background_escape_sequence`.

    * Removes all color escape sequences.

`ColorString`
-------------
`#RGB` defines a color in hexadecimal format.

`#RGBA` defines a color in hexadecimal format and alpha channel.

`#RRGGBB` defines a color in hexadecimal format.

`#RRGGBBAA` defines a color in hexadecimal format and alpha channel.

Named colors are also supported and are equivalent to
[CSS Color Module Level 4](http://dev.w3.org/csswg/css-color/#named-colors).
To specify the value of the alpha channel, append `#A` or `#AA` to the end of
the color name (e.g. `colorname#08`).

`Color`
-------------
`{a = alpha, r = red, g = green, b = blue}` defines an ARGB8 color.

HUD element types
-----------------
The position field is used for all element types.

To account for differing resolutions, the position coordinates are the percentage
of the screen, ranging in value from `0` to `1`.

The name field is not yet used, but should contain a description of what the
HUD element represents. The direction field is the direction in which something
is drawn.

`0` draws from left to right, `1` draws from right to left, `2` draws from
top to bottom, and `3` draws from bottom to top.

The `alignment` field specifies how the item will be aligned. It ranges from `-1` to `1`,
with `0` being the center, `-1` is moved to the left/up, and `1` is to the right/down.
Fractional values can be used.

The `offset` field specifies a pixel offset from the position. Contrary to position,
the offset is not scaled to screen size. This allows for some precisely-positioned
items in the HUD.



Below are the specific uses for fields in each type; fields not listed for that type are ignored.


in the experimental stages.

### `image`
Displays an image on the HUD.


  Only the X coordinate scale is used (positive values).
  Negative values represent that percentage of the screen it
  should take; e.g. `x=-100` means 100% (width).


### `text`
Displays text on the HUD.


  A value such as `{x=100, y=100}` should work.

  Specify `0xFFFFFF` for white text, `0xFF0000` for red, and so on.


### `statbar`
Displays a horizontal bar made up of half-images.


  If odd, will end with a vertically center-split texture.


### `inventory`


### `waypoint`

Displays distance to selected world position.


  If set to 0, distance is not shown. Shown value is `floor(distance*precision)/precision`.
  When the precision is an integer multiple of 10, there will be `log_10(precision)` digits after the decimal point.
  `precision = 1000`, for example, will show 3 decimal places (eg: `0.999`).
  `precision = 2` will show multiples of `0.5`; precision = 5 will show multiples of `0.2` and so on:
  `precision = n` will show multiples of `1/n`

  text.


### `image_waypoint`

Same as `image`, but does not accept a `position`; the position is instead determined by `world_pos`, the world position of the waypoint.


  Only the X coordinate scale is used (positive values).
  Negative values represent that percentage of the screen it
  should take; e.g. `x=-100` means 100% (width).


### Particle definition (`add_particle`)

    {
        pos = {x=0, y=0, z=0},
        velocity = {x=0, y=0, z=0},
        acceleration = {x=0, y=0, z=0},
    --  ^ Spawn particle at pos with velocity and acceleration
        expirationtime = 1,
    --  ^ Disappears after expirationtime seconds
        size = 1,
        collisiondetection = false,
    --  ^ collisiondetection: if true collides with physical objects
        collision_removal = false,
    --  ^ collision_removal: if true then particle is removed when it collides,
    --  ^ requires collisiondetection = true to have any effect
        vertical = false,
    --  ^ vertical: if true faces player using y axis only
        texture = "image.png",
    --  ^ Uses texture (string)
        animation = {Tile Animation definition},
    --  ^ optional, specifies how to animate the particle texture
        glow = 0
    --  ^ optional, specify particle self-luminescence in darkness
    }

### `ParticleSpawner` definition (`add_particlespawner`)

    {
        amount = 1,
        time = 1,
    --  ^ If time is 0 has infinite lifespan and spawns the amount on a per-second base
        minpos = {x=0, y=0, z=0},
        maxpos = {x=0, y=0, z=0},
        minvel = {x=0, y=0, z=0},
        maxvel = {x=0, y=0, z=0},
        minacc = {x=0, y=0, z=0},
        maxacc = {x=0, y=0, z=0},
        minexptime = 1,
        maxexptime = 1,
        minsize = 1,
        maxsize = 1,
    --  ^ The particle's properties are random values in between the bounds:
    --  ^ minpos/maxpos, minvel/maxvel (velocity), minacc/maxacc (acceleration),
    --  ^ minsize/maxsize, minexptime/maxexptime (expirationtime)
        collisiondetection = false,
    --  ^ collisiondetection: if true uses collision detection
        collision_removal = false,
    --  ^ collision_removal: if true then particle is removed when it collides,
    --  ^ requires collisiondetection = true to have any effect
        vertical = false,
    --  ^ vertical: if true faces player using y axis only
        texture = "image.png",
    --  ^ Uses texture (string)
    }