src/script/cpp_api

Minetest Lua Client Modding API Reference 0.5.0
================================================
* More information at <http://www.minetest.net/>
* Developer Wiki: <http://dev.minetest.net/>

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

**WARNING: The client API is currently unstable, and may break/change without warning.**

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.

Transfering client-sided mods form 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.

Paths
-----
* `RUN_IN_PLACE=1` (Windows release, local build)
    *  `$path_user`:
        * Linux: `<build directory>`
        * Windows: `<build directory>`
    * `$path_share`
        * Linux: `<build directory>`
        * Windows:  `<build directory>`
* `RUN_IN_PLACE=0`: (Linux release)
    * `$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:

* `$path_share/clientmods/`
* `$path_user/clientmods/` (User-installed mods)

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

* `minetest-0.4.x/clientmods/` (User-installed mods)

On an installed version on Linux:

* `/usr/share/minetest/clientmods/`
* `$HOME/.minetest/clientmods/` (User-installed mods)

Modpack support
----------------
**NOTE: Not implemented yet.**

Mods can be put in a subdirectory, if the parent directory, which otherwise
should be a mod, contains a file named `modpack.txt`. This file shall be
empty, except for lines starting with `#`, which are comments.

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

    clientmods
    ├── modname
    |   ├── depends.txt
    |   ├── init.lua
    └── another

### modname
The location of this directory.

### depends.txt
List of mods that have to be loaded before loading this mod.

A single line contains a single modname.

Optional dependencies can be defined by appending a question mark
to a single modname. Their meaning is that if the specified mod
is missing, that does not prevent this mod from being loaded.

### 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.

`minetest.setting_get(name)` and `minetest.setting_getbool(name)` can be used
to read custom or existing settings at load time, if necessary.

### `sounds`
Media files (sounds) that will be transferred to the
client and will be available for use by the mod.

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
------
**NOTE: max_hear_distance and connecting to objects is not implemented.**

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:

* `foomod_foosound.ogg`
* `foomod_foosound.0.ogg`
* `foomod_foosound.1.ogg`
* (...)
* `foomod_foosound.9.ogg`

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
        max_hear_distance = 32, -- default, uses an euclidean metric
    }
    -- Play connected to an object, looped
    {
        object = <an ObjectRef>,
        gain = 1.0, -- default
        max_hear_distance = 32, -- default, uses an euclidean metric
        loop = true,
    }

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

### SimpleSoundSpec
* e.g. `""`
* e.g. `"default_place_node"`
* e.g. `{}`
* e.g. `{name = "default_place_node"}`
* e.g. `{name = "default_place_node", gain = 1.0}`

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

### Position/vector

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

For helper functions see "Vector helpers".

### pointed_thing
* `{type="nothing"}`
* `{type="node", under=pos, above=pos}`
* `{type="object", id=ObjectID}`

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>]`
* Define the size of the menu in inventory slots
* `fixed_size`: `true`/`false` (optional)
* deprecated: `invsize[<W>,<H>;]`

#### `container[<X>,<Y>]`
* Start of a container block, moves all physical elements in the container by (X, Y)
* Must have matching container_end
* Containers can be nested, in which case the offsets are added
  (child containers are relative to parent containers)

#### `container_end[]`
* End of a container, following elements are no longer relative to this container

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

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

#### `listring[<inventory location>;<list name>]`
* Allows to create a ring of inventory lists
* Shift-clicking on items in one element of the ring
  will send them to the next inventory list inside the ring
* The first occurrence of an element inside the ring will
  determine the inventory where items will be sent to

#### `listring[]`
* Shorthand for doing `listring[<inventory location>;<list name>]`
  for the last two inventory lists added by list[...]

#### `listcolors[<slot_bg_normal>;<slot_bg_hover>]`
* Sets background color of slots as `ColorString`
* Sets background color of slots on mouse hovering

#### `listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>]`
* Sets background color of slots as `ColorString`
* Sets background color of slots on mouse hovering
* Sets color of slots border

#### `listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>;<tooltip_bgcolor>;<tooltip_fontcolor>]`
* Sets background color of slots as `ColorString`
* Sets background color of slots on mouse hovering
* Sets color of slots border
* Sets default background color of tooltips
* Sets default font color of tooltips

#### `tooltip[<gui_element_name>;<tooltip_text>;<bgcolor>,<fontcolor>]`
* Adds tooltip for an element
* `<bgcolor>` tooltip background color as `ColorString` (optional)
* `<fontcolor>` tooltip font color as `ColorString` (optional)

#### `image[<X>,<Y>;<W>,<H>;<texture name>]`
* Show an image
* Position and size units are inventory slots

#### `item_image[<X>,<Y>;<W>,<H>;<item name>]`
* Show an inventory image of registered item/node
* Position and size units are inventory slots

#### `bgcolor[<color>;<fullscreen>]`
* Sets background color of formspec as `ColorString`
* If `true`, the background color is drawn fullscreen (does not effect the size of the formspec)

#### `background[<X>,<Y>;<W>,<H>;<texture name>]`
* Use a background. Inventory rectangles are not drawn then.
* Position and size units are inventory slots
* Example for formspec 8x4 in 16x resolution: image shall be sized
  8 times 16px  times  4 times 16px.

#### `background[<X>,<Y>;<W>,<H>;<texture name>;<auto_clip>]`
* Use a background. Inventory rectangles are not drawn then.
* Position and size units are inventory slots
* Example for formspec 8x4 in 16x resolution:
  image shall be sized 8 times 16px  times  4 times 16px
* If `true` the background is clipped to formspec size
  (`x` and `y` are used as offset values, `w` and `h` are ignored)

#### `pwdfield[<X>,<Y>;<W>,<H>;<name>;<label>]`
* Textual password style field; will be sent to server when a button is clicked
* When enter is pressed in field, fields.key_enter_field will be sent with the name
  of this field.
* `x` and `y` position the field relative to the top left of the menu
* `w` and `h` are the size of the field
* Fields are a set height, but will be vertically centred on `h`
Mode	Name	Size
-rw-r--r--	CMakeLists.txt	686	log plain
-rw-r--r--	s_async.cpp	7326	log plain
-rw-r--r--	s_async.h	4014	log plain
-rw-r--r--	s_base.cpp	12547	log plain
-rw-r--r--	s_base.h	4363	log plain
-rw-r--r--	s_client.cpp	6503	log plain
-rw-r--r--	s_client.h	1986	log plain
-rw-r--r--	s_entity.cpp	8437	log plain
-rw-r--r--	s_entity.h	1952	log plain
-rw-r--r--	s_env.cpp	7655	log plain
-rw-r--r--	s_env.h	1461	log plain
-rw-r--r--	s_internal.h	2896	log plain
-rw-r--r--	s_inventory.cpp	7313	log plain
-rw-r--r--	s_inventory.h	1943	log plain
-rw-r--r--	s_item.cpp	7237	log plain
-rw-r--r--	s_item.h	2112	log plain
-rw-r--r--	s_mainmenu.cpp	2660	log plain
-rw-r--r--	s_mainmenu.h	1396	log plain
-rw-r--r--	s_modchannels.cpp	1690	log plain
-rw-r--r--	s_modchannels.h	1124	log plain
-rw-r--r--	s_node.cpp	7401	log plain
-rw-r--r--	s_node.h	1915	log plain
-rw-r--r--	s_nodemeta.cpp	8097	log plain
-rw-r--r--	s_nodemeta.h	1966	log plain
-rw-r--r--	s_player.cpp	10500	log plain
-rw-r--r--	s_player.h	3311	log plain
-rw-r--r--	s_security.cpp	18548	log plain
-rw-r--r--	s_security.h	2925	log plain
-rw-r--r--	s_server.cpp	5476	log plain
-rw-r--r--	s_server.h	1712	log plain