diff options
Diffstat (limited to 'lua_api.dtxt2')
| -rw-r--r-- | lua_api.dtxt2 | 4676 |
1 files changed, 4676 insertions, 0 deletions
diff --git a/lua_api.dtxt2 b/lua_api.dtxt2 new file mode 100644 index 0000000..975fd64 --- /dev/null +++ b/lua_api.dtxt2 @@ -0,0 +1,4676 @@ +# Minetest Lua Modding API Reference 0.4.16 + +* More information at <http://www.minetest.net/> +* Developer Wiki: <http://dev.minetest.net/> + +Introduction +------------ +Content and functionality can be added to Minetest 0.4 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. + +Mods are contained and ran solely on the server side. Definitions and media +files are automatically transferred to the client. + +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 to <celeron55@gmail.com>. + +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 server 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) + +Games +----- +Games are looked up from: + +* `$path_share/games/gameid/` +* `$path_user/games/gameid/` + +where `gameid` is unique to each game. + +The game directory contains the file `game.conf`, which contains these fields: + + name = <Human-readable full name of the game> + +e.g. + + name = Minetest + +The game directory can contain the file minetest.conf, which will be used +to set default settings when running the particular game. +It can also contain a settingtypes.txt in the same format as the one in builtin. +This settingtypes.txt will be parsed by the menu and the settings will be displayed +in the "Games" category in the settings tab. + +### Menu images + +Games can provide custom main menu images. They are put inside a `menu` directory +inside the game directory. + +The images are named `$identifier.png`, where `$identifier` is +one of `overlay,background,footer,header`. +If you want to specify multiple images for one identifier, add additional images named +like `$identifier.$n.png`, with an ascending number $n starting with 1, and a random +image will be chosen from the provided ones. + + +Mod load path +------------- +Generic: + +* `$path_share/games/gameid/mods/` +* `$path_share/mods/` +* `$path_user/games/gameid/mods/` +* `$path_user/mods/` (User-installed mods) +* `$worldpath/worldmods/` + +In a run-in-place version (e.g. the distributed windows version): + +* `minetest-0.4.x/games/gameid/mods/` +* `minetest-0.4.x/mods/` (User-installed mods) +* `minetest-0.4.x/worlds/worldname/worldmods/` + +On an installed version on Linux: + +* `/usr/share/minetest/games/gameid/mods/` +* `$HOME/.minetest/mods/` (User-installed mods) +* `$HOME/.minetest/worlds/worldname/worldmods` + +Mod load path for world-specific games +-------------------------------------- +It is possible to include a game in a world; in this case, no mods or +games are loaded or checked from anywhere else. + +This is useful for e.g. adventure worlds. + +This happens if the following directory exists: + + $world/game/ + +Mods should be then be placed in: + + $world/game/mods/ + +Modpack support +---------------- +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 +------------------------ + + mods + |-- modname + | |-- depends.txt + | |-- screenshot.png + | |-- description.txt + | |-- settingtypes.txt + | |-- init.lua + | |-- models + | |-- textures + | | |-- modname_stuff.png + | | `-- modname_something_else.png + | |-- sounds + | |-- media + | `-- <custom data> + `-- another + + +### modname +The location of this directory can be fetched by using +`minetest.get_modpath(modname)`. + +### `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. + +### `screenshot.png` +A screenshot shown in the mod manager within the main menu. It should +have an aspect ratio of 3:2 and a minimum size of 300×200 pixels. + +### `description.txt` +A File containing description to be shown within mainmenu. + +### `settingtypes.txt` +A file in the same format as the one in builtin. It will be parsed by the +settings menu and the settings will be displayed in the "Mods" category. + +### `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.settings` can be used to read custom or existing settings at load +time, if necessary. (See `Settings`) + +### `models` +Models for entities or meshnodes. + +### `textures`, `sounds`, `media` +Media files (textures, sounds, whatever) 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 these 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. + +### Aliases +Aliases can be added by using `minetest.register_alias(name, convert_to)` or +`minetest.register_alias_force(name, convert_to)`. + +This will make Minetest to convert things called name to things called +`convert_to`. + +The only difference between `minetest.register_alias` and +`minetest.register_alias_force` is that if an item called `name` exists, +`minetest.register_alias` will do nothing while +`minetest.register_alias_force` will unregister it. + +This can be used for maintaining backwards compatibility. + +This can be also used for setting quick access names for things, e.g. if +you have an item called `epiclylongmodname:stuff`, you could do + + minetest.register_alias("stuff", "epiclylongmodname:stuff") + +and be able to use `/giveme stuff`. + +Textures +-------- +Mods should generally prefix their textures with `modname_`, e.g. given +the mod name `foomod`, a texture could be called: + + foomod_foothing.png + +Textures are referred to by their complete name, or alternatively by +stripping out the file extension: + +* e.g. `foomod_foothing.png` +* e.g. `foomod_foothing` + +Texture modifiers +----------------- +There are various texture modifiers that can be used +to generate textures on-the-fly. + +### Texture overlaying +Textures can be overlaid by putting a `^` between them. + +Example: + + default_dirt.png^default_grass_side.png + +`default_grass_side.png` is overlayed over `default_dirt.png`. +The texture with the lower resolution will be automatically upscaled to +the higher resolution texture. + +### Texture grouping +Textures can be grouped together by enclosing them in `(` and `)`. + +Example: `cobble.png^(thing1.png^thing2.png)` + +A texture for `thing1.png^thing2.png` is created and the resulting +texture is overlaid on top of `cobble.png`. + +### Escaping +Modifiers that accept texture names (e.g. `[combine`) accept escaping to allow +passing complex texture names as arguments. Escaping is done with backslash and +is required for `^` and `:`. + +Example: `cobble.png^[lowpart:50:color.png\^[mask\:trans.png` + +The lower 50 percent of `color.png^[mask:trans.png` are overlaid +on top of `cobble.png`. + +### Advanced texture modifiers + +#### `[crack:<n>:<p>` +* `<n>` = animation frame count +* `<p>` = current animation frame + +Draw a step of the crack animation on the texture. + +Example: + + default_cobble.png^[crack:10:1 + +#### `[combine:<w>x<h>:<x1>,<y1>=<file1>:<x2>,<y2>=<file2>:...` +* `<w>` = width +* `<h>` = height +* `<x>` = x position +* `<y>` = y position +* `<file>` = texture to combine + +Creates a texture of size `<w>` times `<h>` and blits the listed files to their +specified coordinates. + +Example: + + [combine:16x32:0,0=default_cobble.png:0,16=default_wood.png + +#### `[resize:<w>x<h>` +Resizes the texture to the given dimensions. + +Example: + + default_sandstone.png^[resize:16x16 + +#### `[opacity:<r>` +Makes the base image transparent according to the given ratio. + +`r` must be between 0 and 255. +0 means totally transparent. 255 means totally opaque. + +Example: + + default_sandstone.png^[opacity:127 + +#### `[invert:<mode>` +Inverts the given channels of the base image. +Mode may contain the characters "r", "g", "b", "a". +Only the channels that are mentioned in the mode string will be inverted. + +Example: + + default_apple.png^[invert:rgb + +#### `[brighten` +Brightens the texture. + +Example: + + tnt_tnt_side.png^[brighten + +#### `[noalpha` +Makes the texture completely opaque. + +Example: + + default_leaves.png^[noalpha + +#### `[makealpha:<r>,<g>,<b>` +Convert one color to transparency. + +Example: + + default_cobble.png^[makealpha:128,128,128 + +#### `[transform<t>` +* `<t>` = transformation(s) to apply + +Rotates and/or flips the image. + +`<t>` can be a number (between 0 and 7) or a transform name. +Rotations are counter-clockwise. + + 0 I identity + 1 R90 rotate by 90 degrees + 2 R180 rotate by 180 degrees + 3 R270 rotate by 270 degrees + 4 FX flip X + 5 FXR90 flip X then rotate by 90 degrees + 6 FY flip Y + 7 FYR90 flip Y then rotate by 90 degrees + +Example: + + default_stone.png^[transformFXR90 + +#### `[inventorycube{<top>{<left>{<right>` +Escaping does not apply here and `^` is replaced by `&` in texture names instead. + +Create an inventory cube texture using the side textures. + +Example: + + [inventorycube{grass.png{dirt.png&grass_side.png{dirt.png&grass_side.png + +Creates an inventorycube with `grass.png`, `dirt.png^grass_side.png` and +`dirt.png^grass_side.png` textures + +#### `[lowpart:<percent>:<file>` +Blit the lower `<percent>`% part of `<file>` on the texture. + +Example: + + base.png^[lowpart:25:overlay.png + +#### `[verticalframe:<t>:<n>` +* `<t>` = animation frame count +* `<n>` = current animation frame + +Crops the texture to a frame of a vertical animation. + +Example: + + default_torch_animated.png^[verticalframe:16:8 + +#### `[mask:<file>` +Apply a mask to the base image. + +The mask is applied using binary AND. + +#### `[sheet:<w>x<h>:<x>,<y>` +Retrieves a tile at position x,y from the base image +which it assumes to be a tilesheet with dimensions w,h. + + +#### `[colorize:<color>:<ratio>` +Colorize the textures with the given color. +`<color>` is specified as a `ColorString`. +`<ratio>` is an int ranging from 0 to 255 or the word "`alpha`". If +it is an int, then it specifies how far to interpolate between the +colors where 0 is only the texture color and 255 is only `<color>`. If +omitted, the alpha of `<color>` will be used as the ratio. If it is +the word "`alpha`", then each texture pixel will contain the RGB of +`<color>` and the alpha of `<color>` multiplied by the alpha of the +texture pixel. + +#### `[multiply:<color>` +Multiplies texture colors with the given color. +`<color>` is specified as a `ColorString`. +Result is more like what you'd expect if you put a color on top of another +color. Meaning white surfaces get a lot of your new color while black parts don't +change very much. + +Hardware coloring +----------------- +The goal of hardware coloring is to simplify the creation of +colorful nodes. If your textures use the same pattern, and they only +differ in their color (like colored wool blocks), you can use hardware +coloring instead of creating and managing many texture files. +All of these methods use color multiplication (so a white-black texture +with red coloring will result in red-black color). + +### Static coloring +This method is useful if you wish to create nodes/items with +the same texture, in different colors, each in a new node/item definition. + +#### Global color +When you register an item or node, set its `color` field (which accepts a +`ColorSpec`) to the desired color. + +An `ItemStack`s static color can be overwritten by the `color` metadata +field. If you set that field to a `ColorString`, that color will be used. + +#### Tile color +Each tile may have an individual static color, which overwrites every +other coloring methods. To disable the coloring of a face, +set its color to white (because multiplying with white does nothing). +You can set the `color` property of the tiles in the node's definition +if the tile is in table format. + +### Palettes +For nodes and items which can have many colors, a palette is more +suitable. A palette is a texture, which can contain up to 256 pixels. +Each pixel is one possible color for the node/item. +You can register one node/item, which can have up to 256 colors. + +#### Palette indexing +When using palettes, you always provide a pixel index for the given +node or `ItemStack`. The palette is read from left to right and from +top to bottom. If the palette has less than 256 pixels, then it is +stretched to contain exactly 256 pixels (after arranging the pixels +to one line). The indexing starts from 0. + +Examples: +* 16x16 palette, index = 0: the top left corner +* 16x16 palette, index = 4: the fifth pixel in the first row +* 16x16 palette, index = 16: the pixel below the top left corner +* 16x16 palette, index = 255: the bottom right corner +* 2 (width)x4 (height) palette, index=31: the top left corner. + The palette has 8 pixels, so each pixel is stretched to 32 pixels, + to ensure the total 256 pixels. +* 2x4 palette, index=32: the top right corner +* 2x4 palette, index=63: the top right corner +* 2x4 palette, index=64: the pixel below the top left corner + +#### Using palettes with items +When registering an item, set the item definition's `palette` field to +a texture. You can also use texture modifiers. + +The `ItemStack`'s color depends on the `palette_index` field of the +stack's metadata. `palette_index` is an integer, which specifies the +index of the pixel to use. + +#### Linking palettes with nodes +When registering a node, set the item definition's `palette` field to +a texture. You can also use texture modifiers. +The node's color depends on its `param2`, so you also must set an +appropriate `drawtype`: +* `drawtype = "color"` for nodes which use their full `param2` for + palette indexing. These nodes can have 256 different colors. + The palette should contain 256 pixels. +* `drawtype = "colorwallmounted"` for nodes which use the first + five bits (most significant) of `param2` for palette indexing. + The remaining three bits are describing rotation, as in `wallmounted` + draw type. Division by 8 yields the palette index (without stretching the + palette). These nodes can have 32 different colors, and the palette + should contain 32 pixels. + Examples: + * `param2 = 17` is 2 * 8 + 1, so the rotation is 1 and the third (= 2 + 1) + pixel will be picked from the palette. + * `param2 = 35` is 4 * 8 + 3, so the rotation is 3 and the fifth (= 4 + 1) + pixel will be picked from the palette. +* `drawtype = "colorfacedir"` for nodes which use the first + three bits of `param2` for palette indexing. The remaining + five bits are describing rotation, as in `facedir` draw type. + Division by 32 yields the palette index (without stretching the + palette). These nodes can have 8 different colors, and the + palette should contain 8 pixels. + Examples: + * `param2 = 17` is 0 * 32 + 17, so the rotation is 17 and the + first (= 0 + 1) pixel will be picked from the palette. + * `param2 = 35` is 1 * 32 + 3, so the rotation is 3 and the + second (= 1 + 1) pixel will be picked from the palette. + +To colorize a node on the map, set its `param2` value (according +to the node's draw type). + +### Conversion between nodes in the inventory and the on the map +Static coloring is the same for both cases, there is no need +for conversion. + +If the `ItemStack`'s metadata contains the `color` field, it will be +lost on placement, because nodes on the map can only use palettes. + +If the `ItemStack`'s metadata contains the `palette_index` field, you +currently must manually convert between it and the node's `param2` with +custom `on_place` and `on_dig` callbacks. + +### Colored items in craft recipes +Craft recipes only support item strings, but fortunately item strings +can also contain metadata. Example craft recipe registration: + + local stack = ItemStack("wool:block") + dyed:get_meta():set_int("palette_index", 3) -- add index + minetest.register_craft({ + output = dyed:to_string(), -- convert to string + type = "shapeless", + recipe = { + "wool:block", + "dye:red", + }, + }) + +Metadata field filtering in the `recipe` field are not supported yet, +so the craft output is independent of the color of the ingredients. + +Soft texture overlay +-------------------- +Sometimes hardware coloring is not enough, because it affects the +whole tile. Soft texture overlays were added to Minetest to allow +the dynamic coloring of only specific parts of the node's texture. +For example a grass block may have colored grass, while keeping the +dirt brown. + +These overlays are 'soft', because unlike texture modifiers, the layers +are not merged in the memory, but they are simply drawn on top of each +other. This allows different hardware coloring, but also means that +tiles with overlays are drawn slower. Using too much overlays might +cause FPS loss. + +To define an overlay, simply set the `overlay_tiles` field of the node +definition. These tiles are defined in the same way as plain tiles: +they can have a texture name, color etc. +To skip one face, set that overlay tile to an empty string. + +Example (colored grass block): + + minetest.register_node("default:dirt_with_grass", { + description = "Dirt with Grass", + -- Regular tiles, as usual + -- The dirt tile disables palette coloring + tiles = {{name = "default_grass.png"}, + {name = "default_dirt.png", color = "white"}}, + -- Overlay tiles: define them in the same style + -- The top and bottom tile does not have overlay + overlay_tiles = {"", "", + {name = "default_grass_side.png", tileable_vertical = false}}, + -- Global color, used in inventory + color = "green", + -- Palette in the world + paramtype2 = "color", + palette = "default_foilage.png", + }) + +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: + +* `foomod_foosound.ogg` +* `foomod_foosound.0.ogg` +* `foomod_foosound.1.ogg` +* (...) +* `foomod_foosound.9.ogg` + +Examples of sound parameter tables: + + -- Play locationless on all clients + { + gain = 1.0, -- default + fade = 0.0, -- default, change to a value > 0 to fade the sound in + } + -- Play locationless to one player + { + to_player = name, + gain = 1.0, -- default + fade = 0.0, -- default, change to a value > 0 to fade the sound in + } + -- Play locationless to one player, looped + { + to_player = name, + 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 to +one player using `to_player = name,` + +### `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}` + +## Registered definitions of stuff +------------------------------- +Anything added using certain `minetest.register_*` functions get added to +the global `minetest.registered_*` tables. + +* `minetest.register_entity(name, prototype table)` + * added to `minetest.registered_entities[name]` + +* `minetest.register_node(name, node definition)` + * added to `minetest.registered_items[name]` + * added to `minetest.registered_nodes[name]` + +* `minetest.register_tool(name, item definition)` + * added to `minetest.registered_items[name]` + +* `minetest.register_craftitem(name, item definition)` + * added to `minetest.registered_items[name]` + +* `minetest.unregister_item(name)` + * Unregisters the item name from engine, and deletes the entry with key + * `name` from `minetest.registered_items` and from the associated item + * table according to its nature: `minetest.registered_nodes[]` etc + +* `minetest.register_biome(biome definition)` + * returns an integer uniquely identifying the registered biome + * added to `minetest.registered_biome` with the key of `biome.name` + * if `biome.name` is nil, the key is the returned ID + +* `minetest.register_ore(ore definition)` + * returns an integer uniquely identifying the registered ore + * added to `minetest.registered_ores` with the key of `ore.name` + * if `ore.name` is nil, the key is the returned ID + +* `minetest.register_decoration(decoration definition)` + * returns an integer uniquely identifying the registered decoration + * added to `minetest.registered_decorations` with the key of `decoration.name` + * if `decoration.name` is nil, the key is the returned ID + +* `minetest.register_schematic(schematic definition)` + * returns an integer uniquely identifying the registered schematic + * added to `minetest.registered_schematic` with the key of `schematic.name` + * if `schematic.name` is nil, the key is the returned ID + * if the schematic is loaded from a file, schematic.name is set to the filename + * if the function is called when loading the mod, and schematic.name is a relative + path, then the current mod path will be prepended to the schematic filename + +* `minetest.clear_registered_biomes()` + * clears all biomes currently registered + +* `minetest.clear_registered_ores()` + * clears all ores currently registered + +* `minetest.clear_registered_decorations()` + * clears all decorations currently registered + +* `minetest.clear_registered_schematics()` + * clears all schematics currently registered + +Note that in some cases you will stumble upon things that are not contained +in these tables (e.g. when a mod has been removed). Always check for +existence before trying to access the fields. + +Example: If you want to check the drawtype of a node, you could do: + + local function get_nodedef_field(nodename, fieldname) + if not minetest.registered_nodes[nodename] then + return nil + end + return minetest.registered_nodes[nodename][fieldname] + end + local drawtype = get_nodedef_field(nodename, "drawtype") + +Example: `minetest.get_item_group(name, group)` has been implemented as: + + function minetest.get_item_group(name, group) + if not minetest.registered_items[name] or not + minetest.registered_items[name].groups[group] then + return 0 + end + return minetest.registered_items[name].groups[group] + end + +## Nodes +----- +Nodes are the bulk data of the world: cubes and other things that take the +space of a cube. Huge amounts of them are handled efficiently, but they +are quite static. + +The definition of a node is stored and can be accessed by name in + + minetest.registered_nodes[node.name] + +See "Registered definitions of stuff". + +Nodes are passed by value between Lua and the engine. +They are represented by a table: + + {name="name", param1=num, param2=num} + +`param1` and `param2` are 8-bit integers ranging from 0 to 255. The engine uses +them for certain automated functions. If you don't use these functions, you can +use them to store arbitrary values. + +The functions of `param1` and `param2` are determined by certain fields in the +node definition: + +`param1` is reserved for the engine when `paramtype != "none"`: + + paramtype = "light" + ^ The value stores light with and without sun in its upper and lower 4 bits + respectively. Allows light to propagate from or through the node with + light value falling by 1 per node. This is essential for a light source + node to spread its light. + +`param2` is reserved for the engine when any of these are used: + + liquidtype == "flowing" + ^ The level and some flags of the liquid is stored in param2 + drawtype == "flowingliquid" + ^ The drawn liquid level is read from param2 + drawtype == "torchlike" + drawtype == "signlike" + paramtype2 == "wallmounted" + ^ The rotation of the node is stored in param2. You can make this value + by using minetest.dir_to_wallmounted(). + paramtype2 == "facedir" + ^ The rotation of the node is stored in param2. Furnaces and chests are + rotated this way. Can be made by using minetest.dir_to_facedir(). + Values range 0 - 23 + facedir / 4 = axis direction: + 0 = y+ 1 = z+ 2 = z- 3 = x+ 4 = x- 5 = y- + facedir modulo 4 = rotation around that axis + paramtype2 == "leveled" + paramtype2 == "degrotate" + ^ The rotation of this node is stored in param2. Plants are rotated this way. + Values range 0 - 179. The value stored in param2 is multiplied by two to + get the actual rotation of the node. + paramtype2 == "meshoptions" + ^ Only valid for "plantlike". The value of param2 becomes a bitfield which can + be used to change how the client draws plantlike nodes. Bits 0, 1 and 2 form + a mesh selector. Currently the following meshes are choosable: + 0 = a "x" shaped plant (ordinary plant) + 1 = a "+" shaped plant (just rotated 45 degrees) + 2 = a "*" shaped plant with 3 faces instead of 2 + 3 = a "#" shaped plant with 4 faces instead of 2 + 4 = a "#" shaped plant with 4 faces that lean outwards + 5-7 are unused and reserved for future meshes. + Bits 3 through 7 are optional flags that can be combined and give these + effects: + bit 3 (0x08) - Makes the plant slightly vary placement horizontally + bit 4 (0x10) - Makes the plant mesh 1.4x larger + bit 5 (0x20) - Moves each face randomly a small bit down (1/8 max) + bits 6-7 are reserved for future use. + paramtype2 == "color" + ^ `param2` tells which color is picked from the palette. + The palette should have 256 pixels. + paramtype2 == "colorfacedir" + ^ Same as `facedir`, but with colors. + The first three bits of `param2` tells which color + is picked from the palette. + The palette should have 8 pixels. + paramtype2 == "colorwallmounted" + ^ Same as `wallmounted`, but with colors. + The first five bits of `param2` tells which color + is picked from the palette. + The palette should have 32 pixels. + paramtype2 == "glasslikeliquidlevel" + ^ Only valid for "glasslike_framed" or "glasslike_framed_optional" drawtypes. + param2 defines 64 levels of internal liquid. + Liquid texture is defined using `special_tiles = {"modname_tilename.png"},` + +Nodes can also contain extra data. See "Node Metadata". + +Node drawtypes +--------------- +There are a bunch of different looking node types. + +Look for examples in `games/minimal` or `games/minetest_game`. + +* `normal` +* `airlike` +* `liquid` +* `flowingliquid` +* `glasslike` +* `glasslike_framed` +* `glasslike_framed_optional` +* `allfaces` +* `allfaces_optional` +* `torchlike` +* `signlike` +* `plantlike` +* `firelike` +* `fencelike` +* `raillike` +* `nodebox` -- See below. (**Experimental!**) +* `mesh` -- use models for nodes + +`*_optional` drawtypes need less rendering time if deactivated (always client side). + +Node boxes +----------- +Node selection boxes are defined using "node boxes" + +The `nodebox` node drawtype allows defining visual of nodes consisting of +arbitrary number of boxes. It allows defining stuff like stairs. Only the +`fixed` and `leveled` box type is supported for these. + +Please note that this is still experimental, and may be incompatibly +changed in the future. + +A nodebox is defined as any of: + + { + -- A normal cube; the default in most things + type = "regular" + } + { + -- A fixed box (facedir param2 is used, if applicable) + type = "fixed", + fixed = box OR {box1, box2, ...} + } + { + -- A box like the selection box for torches + -- (wallmounted param2 is used, if applicable) + type = "wallmounted", + wall_top = box, + wall_bottom = box, + wall_side = box + } + { + -- A node that has optional boxes depending on neighbouring nodes' + -- presence and type. See also `connects_to`. + type = "connected", + fixed = box OR {box1, box2, ...} + connect_top = box OR {box1, box2, ...} + connect_bottom = box OR {box1, box2, ...} + connect_front = box OR {box1, box2, ...} + connect_left = box OR {box1, box2, ...} + connect_back = box OR {box1, box2, ...} + connect_right = box OR {box1, box2, ...} + } + +A `box` is defined as: + + {x1, y1, z1, x2, y2, z2} + +A box of a regular node would look like: + + {-0.5, -0.5, -0.5, 0.5, 0.5, 0.5}, + +`type = "leveled"` is same as `type = "fixed"`, but `y2` will be automatically +set to level from `param2`. + + +Meshes +------ +If drawtype `mesh` is used, tiles should hold model materials textures. +Only static meshes are implemented. +For supported model formats see Irrlicht engine documentation. + + +Noise Parameters +---------------- +Noise Parameters, or commonly called "`NoiseParams`", define the properties of +perlin noise. + +### `offset` +Offset that the noise is translated by (i.e. added) after calculation. + +### `scale` +Factor that the noise is scaled by (i.e. multiplied) after calculation. + +### `spread` +Vector containing values by which each coordinate is divided by before calculation. +Higher spread values result in larger noise features. + +A value of `{x=250, y=250, z=250}` is common. + +### `seed` +Random seed for the noise. Add the world seed to a seed offset for world-unique noise. +In the case of `minetest.get_perlin()`, this value has the world seed automatically added. + +### `octaves` +Number of times the noise gradient is accumulated into the noise. + +Increase this number to increase the amount of detail in the resulting noise. + +A value of `6` is common. + +### `persistence` +Factor by which the effect of the noise gradient function changes with each successive octave. + +Values less than `1` make the details of successive octaves' noise diminish, while values +greater than `1` make successive octaves stronger. + +A value of `0.6` is common. + +### `lacunarity` +Factor by which the noise feature sizes change with each successive octave. + +A value of `2.0` is common. + +### `flags` +Leave this field unset for no special handling. + +Currently supported are `defaults`, `eased` and `absvalue`. + +#### `defaults` +Specify this if you would like to keep auto-selection of eased/not-eased while specifying +some other flags. + +#### `eased` +Maps noise gradient values onto a quintic S-curve before performing interpolation. +This results in smooth, rolling noise. Disable this (`noeased`) for sharp-looking noise. +If no flags are specified (or defaults is), 2D noise is eased and 3D noise is not eased. + +#### `absvalue` +Accumulates the absolute value of each noise gradient result. + +Noise parameters format example for 2D or 3D perlin noise or perlin noise maps: + + np_terrain = { + offset = 0, + scale = 1, + spread = {x=500, y=500, z=500}, + seed = 571347, + octaves = 5, + persist = 0.63, + lacunarity = 2.0, + flags = "defaults, absvalue" + } + ^ A single noise parameter table can be used to get 2D or 3D noise, + when getting 2D noise spread.z is ignored. + + +Ore types +--------- +These tell in what manner the ore is generated. + +All default ores are of the uniformly-distributed scatter type. + +### `scatter` +Randomly chooses a location and generates a cluster of ore. + +If `noise_params` is specified, the ore will be placed if the 3D perlin noise at +that point is greater than the `noise_threshold`, giving the ability to create +a non-equal distribution of ore. + +### `sheet` +Creates a sheet of ore in a blob shape according to the 2D perlin noise +described by `noise_params` and `noise_threshold`. This is essentially an +improved version of the so-called "stratus" ore seen in some unofficial mods. + +This sheet consists of vertical columns of uniform randomly distributed height, +varying between the inclusive range `column_height_min` and `column_height_max`. +If `column_height_min` is not specified, this parameter defaults to 1. +If `column_height_max` is not specified, this parameter defaults to `clust_size` +for reverse compatibility. New code should prefer `column_height_max`. + +The `column_midpoint_factor` parameter controls the position of the column at which +ore eminates from. If 1, columns grow upward. If 0, columns grow downward. If 0.5, +columns grow equally starting from each direction. `column_midpoint_factor` is a +decimal number ranging in value from 0 to 1. If this parameter is not specified, +the default is 0.5. + +The ore parameters `clust_scarcity` and `clust_num_ores` are ignored for this ore type. + +### `puff` +Creates a sheet of ore in a cloud-like puff shape. + +As with the `sheet` ore type, the size and shape of puffs are described by +`noise_params` and `noise_threshold` and are placed at random vertical positions +within the currently generated chunk. + +The vertical top and bottom displacement of each puff are determined by the noise +parameters `np_puff_top` and `np_puff_bottom`, respectively. + + +### `blob` +Creates a deformed sphere of ore according to 3d perlin noise described by +`noise_params`. The maximum size of the blob is `clust_size`, and +`clust_scarcity` has the same meaning as with the `scatter` type. + +### `vein` +Creates veins of ore varying in density by according to the intersection of two +instances of 3d perlin noise with diffferent seeds, both described by +`noise_params`. `random_factor` varies the influence random chance has on +placement of an ore inside the vein, which is `1` by default. Note that +modifying this parameter may require adjusting `noise_threshold`. +The parameters `clust_scarcity`, `clust_num_ores`, and `clust_size` are ignored +by this ore type. This ore type is difficult to control since it is sensitive +to small changes. The following is a decent set of parameters to work from: + + noise_params = { + offset = 0, + scale = 3, + spread = {x=200, y=200, z=200}, + seed = 5390, + octaves = 4, + persist = 0.5, + flags = "eased", + }, + noise_threshold = 1.6 + +**WARNING**: Use this ore type *very* sparingly since it is ~200x more +computationally expensive than any other ore. + +Ore attributes +-------------- +See section "Flag Specifier Format". + +Currently supported flags: +`absheight`, `puff_cliffs`, `puff_additive_composition`. + +### `absheight` +Also produce this same ore between the height range of `-y_max` and `-y_min`. + +Useful for having ore in sky realms without having to duplicate ore entries. + +### `puff_cliffs` +If set, puff ore generation will not taper down large differences in displacement +when approaching the edge of a puff. This flag has no effect for ore types other +than `puff`. + +### `puff_additive_composition` +By default, when noise described by `np_puff_top` or `np_puff_bottom` results in a +negative displacement, the sub-column at that point is not generated. With this +attribute set, puff ore generation will instead generate the absolute difference in +noise displacement values. This flag has no effect for ore types other than `puff`. + +Decoration types +---------------- +The varying types of decorations that can be placed. + +### `simple` +Creates a 1 times `H` times 1 column of a specified node (or a random node from +a list, if a decoration list is specified). Can specify a certain node it must +spawn next to, such as water or lava, for example. Can also generate a +decoration of random height between a specified lower and upper bound. +This type of decoration is intended for placement of grass, flowers, cacti, +papyri, waterlilies and so on. + +### `schematic` +Copies a box of `MapNodes` from a specified schematic file (or raw description). +Can specify a probability of a node randomly appearing when placed. +This decoration type is intended to be used for multi-node sized discrete +structures, such as trees, cave spikes, rocks, and so on. + + +Schematic specifier +-------------------- +A schematic specifier identifies a schematic by either a filename to a +Minetest Schematic file (`.mts`) or through raw data supplied through Lua, +in the form of a table. This table specifies the following fields: + +* The `size` field is a 3D vector containing the dimensions of the provided schematic. (required) +* The `yslice_prob` field is a table of {ypos, prob} which sets the `ypos`th vertical slice + of the schematic to have a `prob / 256 * 100` chance of occuring. (default: 255) +* The `data` field is a flat table of MapNode tables making up the schematic, + in the order of `[z [y [x]]]`. (required) + Each MapNode table contains: + * `name`: the name of the map node to place (required) + * `prob` (alias `param1`): the probability of this node being placed (default: 255) + * `param2`: the raw param2 value of the node being placed onto the map (default: 0) + * `force_place`: boolean representing if the node should forcibly overwrite any + previous contents (default: false) + +About probability values: + +* A probability value of `0` or `1` means that node will never appear (0% chance). +* A probability value of `254` or `255` means the node will always appear (100% chance). +* If the probability value `p` is greater than `1`, then there is a + `(p / 256 * 100)` percent chance that node will appear when the schematic is + placed on the map. + + +Schematic attributes +-------------------- +See section "Flag Specifier Format". + +Currently supported flags: `place_center_x`, `place_center_y`, `place_center_z`, + `force_placement`. + +* `place_center_x`: Placement of this decoration is centered along the X axis. +* `place_center_y`: Placement of this decoration is centered along the Y axis. +* `place_center_z`: Placement of this decoration is centered along the Z axis. +* `force_placement`: Schematic nodes other than "ignore" will replace existing nodes. + + +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. + +**Note**: `offset` _will_ adapt to screen DPI as well as user defined scaling factor! + +Below are the specific uses for fields in each type; fields not listed for that type are ignored. + +**Note**: Future revisions to the HUD API may be incompatible; the HUD API is still +in the experimental stages. + +### `image` +Displays an image on the HUD. + +* `scale`: The scale of the image, with 1 being the original texture size. + 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`: The name of the texture that is displayed. +* `alignment`: The alignment of the image. +* `offset`: offset in pixels from position. + +### `text` +Displays text on the HUD. + +* `scale`: Defines the bounding rectangle of the text. + A value such as `{x=100, y=100}` should work. +* `text`: The text to be displayed in the HUD element. +* `number`: An integer containing the RGB value of the color used to draw the text. + Specify `0xFFFFFF` for white text, `0xFF0000` for red, and so on. +* `alignment`: The alignment of the text. +* `offset`: offset in pixels from position. + +### `statbar` +Displays a horizontal bar made up of half-images. + +* `text`: The name of the texture that is used. +* `number`: The number of half-textures that are displayed. + If odd, will end with a vertically center-split texture. +* `direction` +* `offset`: offset in pixels from position. +* `size`: If used, will force full-image size to this value (override texture pack image size) + +### `inventory` +* `text`: The name of the inventory list to be displayed. +* `number`: Number of items in the inventory to be displayed. +* `item`: Position of item that is selected. +* `direction` +* `offset`: offset in pixels from position. + +### `waypoint` +Displays distance to selected world position. + +* `name`: The name of the waypoint. +* `text`: Distance suffix. Can be blank. +* `number:` An integer containing the RGB value of the color used to draw the text. +* `world_pos`: World position of the waypoint. + +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", ref=ObjectRef}` + +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. + +Items +----- + +### Item types +There are three kinds of items: nodes, tools and craftitems. + +* Node (`register_node`): A node from the world. +* Tool (`register_tool`): A tool/weapon that can dig and damage + things according to `tool_capabilities`. +* Craftitem (`register_craftitem`): A miscellaneous item. + +### Amount and wear +All item stacks have an amount between 0 to 65535. It is 1 by +default. Tool item stacks can not have an amount greater than 1. + +Tools use a wear (=damage) value ranging from 0 to 65535. The +value 0 is the default and used is for unworn tools. The values +1 to 65535 are used for worn tools, where a higher value stands for +a higher wear. Non-tools always have a wear value of 0. + +### Item formats +Items and item stacks can exist in three formats: Serializes, table format +and `ItemStack`. + +#### Serialized +This is called "stackstring" or "itemstring". It is a simple string with +1-3 components: the full item identifier, an optional amount and an optional +wear value. Syntax: + + <identifier> [<amount>[ <wear>]] + +Examples: + +* `'default:apple'`: 1 apple +* `'default:dirt 5'`: 5 dirt +* `'default:pick_stone'`: a new stone pickaxe +* `'default:pick_wood 1 21323'`: a wooden pickaxe, ca. 1/3 worn out + +#### Table format +Examples: + +5 dirt nodes: + + {name="default:dirt", count=5, wear=0, metadata=""} + +A wooden pick about 1/3 worn out: + + {name="default:pick_wood", count=1, wear=21323, metadata=""} + +An apple: + + {name="default:apple", count=1, wear=0, metadata=""} + +#### `ItemStack` +A native C++ format with many helper methods. Useful for converting +between formats. See the Class reference section for details. + +When an item must be passed to a function, it can usually be in any of +these formats. + + +## Groups +------ +In a number of places, there is a group table. Groups define the +properties of a thing (item, node, armor of entity, capabilities of +tool) in such a way that the engine and other mods can can interact with +the thing without actually knowing what the thing is. + +### Usage +Groups are stored in a table, having the group names with keys and the +group ratings as values. For example: + + groups = {crumbly=3, soil=1} + -- ^ Default dirt + + groups = {crumbly=2, soil=1, level=2, outerspace=1} + -- ^ A more special dirt-kind of thing + +Groups always have a rating associated with them. If there is no +useful meaning for a rating for an enabled group, it shall be `1`. + +When not defined, the rating of a group defaults to `0`. Thus when you +read groups, you must interpret `nil` and `0` as the same value, `0`. + +You can read the rating of a group for an item or a node by using + + minetest.get_item_group(itemname, groupname) + +### Groups of items +Groups of items can define what kind of an item it is (e.g. wool). + +### Groups of nodes +In addition to the general item things, groups are used to define whether +a node is destroyable and how long it takes to destroy by a tool. + +### Groups of entities +For entities, groups are, as of now, used only for calculating damage. +The rating is the percentage of damage caused by tools with this damage group. +See "Entity damage mechanism". + + object.get_armor_groups() --> a group-rating table (e.g. {fleshy=100}) + object.set_armor_groups({fleshy=30, cracky=80}) + +### Groups of tools +Groups in tools define which groups of nodes and entities they are +effective towards. + +### Groups in crafting recipes +An example: Make meat soup from any meat, any water and any bowl: + + { + output = 'food:meat_soup_raw', + recipe = { + {'group:meat'}, + {'group:water'}, + {'group:bowl'}, + }, + -- preserve = {'group:bowl'}, -- Not implemented yet (TODO) + } + +Another example: Make red wool from white wool and red dye: + + { + type = 'shapeless', + output = 'wool:red', + recipe = {'wool:white', 'group:dye,basecolor_red'}, + } + +### Special groups +* `immortal`: Disables the group damage system for an entity +* `punch_operable`: For entities; disables the regular damage mechanism for + players punching it by hand or a non-tool item, so that it can do something + else than take damage. +* `level`: Can be used to give an additional sense of progression in the game. + * A larger level will cause e.g. a weapon of a lower level make much less + damage, and get worn out much faster, or not be able to get drops + from destroyed nodes. + * `0` is something that is directly accessible at the start of gameplay + * There is no upper limit +* `dig_immediate`: (player can always pick up node without reducing tool wear) + * `2`: the node always gets the digging time 0.5 seconds (rail, sign) + * `3`: the node always gets the digging time 0 seconds (torch) +* `disable_jump`: Player (and possibly other things) cannot jump from node +* `fall_damage_add_percent`: damage speed = `speed * (1 + value/100)` +* `bouncy`: value is bounce speed in percent +* `falling_node`: if there is no walkable block under the node it will fall +* `attached_node`: if the node under it is not a walkable block the node will be + dropped as an item. If the node is wallmounted the wallmounted direction is + checked. +* `soil`: saplings will grow on nodes in this group +* `connect_to_raillike`: makes nodes of raillike drawtype with same group value + connect to each other + +### Known damage and digging time defining groups +* `crumbly`: dirt, sand +* `cracky`: tough but crackable stuff like stone. +* `snappy`: something that can be cut using fine tools; e.g. leaves, small + plants, wire, sheets of metal +* `choppy`: something that can be cut using force; e.g. trees, wooden planks +* `fleshy`: Living things like animals and the player. This could imply + some blood effects when hitting. +* `explody`: Especially prone to explosions +* `oddly_breakable_by_hand`: + Can be added to nodes that shouldn't logically be breakable by the + hand but are. Somewhat similar to `dig_immediate`, but times are more + like `{[1]=3.50,[2]=2.00,[3]=0.70}` and this does not override the + speed of a tool if the tool can dig at a faster speed than this + suggests for the hand. + +### Examples of custom groups +Item groups are often used for defining, well, _groups of items_. + +* `meat`: any meat-kind of a thing (rating might define the size or healing + ability or be irrelevant -- it is not defined as of yet) +* `eatable`: anything that can be eaten. Rating might define HP gain in half + hearts. +* `flammable`: can be set on fire. Rating might define the intensity of the + fire, affecting e.g. the speed of the spreading of an open fire. +* `wool`: any wool (any origin, any color) +* `metal`: any metal +* `weapon`: any weapon +* `heavy`: anything considerably heavy + +### Digging time calculation specifics +Groups such as `crumbly`, `cracky` and `snappy` are used for this +purpose. Rating is `1`, `2` or `3`. A higher rating for such a group implies +faster digging time. + +The `level` group is used to limit the toughness of nodes a tool can dig +and to scale the digging times / damage to a greater extent. + +**Please do understand this**, otherwise you cannot use the system to it's +full potential. + +Tools define their properties by a list of parameters for groups. They +cannot dig other groups; thus it is important to use a standard bunch of +groups to enable interaction with tools. + +#### Tools definition +Tools define: + +* Full punch interval +* Maximum drop level +* For an arbitrary list of groups: + * Uses (until the tool breaks) + * Maximum level (usually `0`, `1`, `2` or `3`) + * Digging times + * Damage groups + +#### Full punch interval +When used as a weapon, the tool will do full damage if this time is spent +between punches. If e.g. half the time is spent, the tool will do half +damage. + +#### Maximum drop level +Suggests the maximum level of node, when dug with the tool, that will drop +it's useful item. (e.g. iron ore to drop a lump of iron). + +This is not automated; it is the responsibility of the node definition +to implement this. + +#### Uses +Determines how many uses the tool has when it is used for digging a node, +of this group, of the maximum level. For lower leveled nodes, the use count +is multiplied by `3^leveldiff`. + +* `uses=10, leveldiff=0`: actual uses: 10 +* `uses=10, leveldiff=1`: actual uses: 30 +* `uses=10, leveldiff=2`: actual uses: 90 + +#### Maximum level +Tells what is the maximum level of a node of this group that the tool will +be able to dig. + +#### Digging times +List of digging times for different ratings of the group, for nodes of the +maximum level. + +For example, as a Lua table, `times={2=2.00, 3=0.70}`. This would +result in the tool to be able to dig nodes that have a rating of `2` or `3` +for this group, and unable to dig the rating `1`, which is the toughest. +Unless there is a matching group that enables digging otherwise. + +If the result digging time is 0, a delay of 0.15 seconds is added between +digging nodes; If the player releases LMB after digging, this delay is set to 0, +i.e. players can more quickly click the nodes away instead of holding LMB. + +#### Damage groups +List of damage for groups of entities. See "Entity damage mechanism". + +#### Example definition of the capabilities of a tool + + tool_capabilities = { + full_punch_interval=1.5, + max_drop_level=1, + groupcaps={ + crumbly={maxlevel=2, uses=20, times={[1]=1.60, [2]=1.20, [3]=0.80}} + } + damage_groups = {fleshy=2}, + } + +This makes the tool be able to dig nodes that fulfil both of these: + +* Have the `crumbly` group +* Have a `level` group less or equal to `2` + +Table of resulting digging times: + + crumbly 0 1 2 3 4 <- level + -> 0 - - - - - + 1 0.80 1.60 1.60 - - + 2 0.60 1.20 1.20 - - + 3 0.40 0.80 0.80 - - + + level diff: 2 1 0 -1 -2 + +Table of resulting tool uses: + + -> 0 - - - - - + 1 180 60 20 - - + 2 180 60 20 - - + 3 180 60 20 - - + +**Notes**: + +* At `crumbly==0`, the node is not diggable. +* At `crumbly==3`, the level difference digging time divider kicks in and makes + easy nodes to be quickly breakable. +* At `level > 2`, the node is not diggable, because it's `level > maxlevel` + +Entity damage mechanism +----------------------- +Damage calculation: + + damage = 0 + foreach group in cap.damage_groups: + damage += cap.damage_groups[group] * limit(actual_interval / + cap.full_punch_interval, 0.0, 1.0) + * (object.armor_groups[group] / 100.0) + -- Where object.armor_groups[group] is 0 for inexistent values + return damage + +Client predicts damage based on damage groups. Because of this, it is able to +give an immediate response when an entity is damaged or dies; the response is +pre-defined somehow (e.g. by defining a sprite animation) (not implemented; +TODO). +Currently a smoke puff will appear when an entity dies. + +The group `immortal` completely disables normal damage. + +Entities can define a special armor group, which is `punch_operable`. This +group disables the regular damage mechanism for players punching it by hand or +a non-tool item, so that it can do something else than take damage. + +On the Lua side, every punch calls: + + entity:on_punch(puncher, time_from_last_punch, tool_capabilities, direction, damage) + +This should never be called directly, because damage is usually not handled by +the entity itself. + +* `puncher` is the object performing the punch. Can be `nil`. Should never be + accessed unless absolutely required, to encourage interoperability. +* `time_from_last_punch` is time from last punch (by `puncher`) or `nil`. +* `tool_capabilities` can be `nil`. +* `direction` is a unit vector, pointing from the source of the punch to + the punched object. +* `damage` damage that will be done to entity +Return value of this function will determin if damage is done by this function +(retval true) or shall be done by engine (retval false) + +To punch an entity/object in Lua, call: + + object:punch(puncher, time_from_last_punch, tool_capabilities, direction) + +* Return value is tool wear. +* Parameters are equal to the above callback. +* If `direction` equals `nil` and `puncher` does not equal `nil`, + `direction` will be automatically filled in based on the location of `puncher`. + +## Node Metadata +------------- +The instance of a node in the world normally only contains the three values +mentioned in "Nodes". However, it is possible to insert extra data into a +node. It is called "node metadata"; See `NodeMetaRef`. + +Node metadata contains two things: + +* A key-value store +* An inventory + +Some of the values in the key-value store are handled specially: + +* `formspec`: Defines a right-click inventory menu. See "Formspec". +* `infotext`: Text shown on the screen when the node is pointed at + +Example stuff: + + local meta = minetest.get_meta(pos) + meta:set_string("formspec", + "size[8,9]".. + "list[context;main;0,0;8,4;]".. + "list[current_player;main;0,5;8,4;]") + meta:set_string("infotext", "Chest"); + local inv = meta:get_inventory() + inv:set_size("main", 8*4) + print(dump(meta:to_table())) + meta:from_table({ + inventory = { + main = {[1] = "default:dirt", [2] = "", [3] = "", [4] = "", + [5] = "", [6] = "", [7] = "", [8] = "", [9] = "", + [10] = "", [11] = "", [12] = "", [13] = "", + [14] = "default:cobble", [15] = "", [16] = "", [17] = "", + [18] = "", [19] = "", [20] = "default:cobble", [21] = "", + [22] = "", [23] = "", [24] = "", [25] = "", [26] = "", + [27] = "", [28] = "", [29] = "", [30] = "", [31] = "", + [32] = ""} + }, + fields = { + formspec = "size[8,9]list[context;main;0,0;8,4;]list[current_player;main;0,5;8,4;]", + infotext = "Chest" + } + }) + +Item Metadata +------------- +Item stacks can store metadata too. See `ItemStackMetaRef`. + +Item metadata only contains a key-value store. + +Some of the values in the key-value store are handled specially: + +* `description`: Set the item stack's description. Defaults to `idef.description` +* `color`: A `ColorString`, which sets the stack's color. +* `palette_index`: If the item has a palette, this is used to get the + current color from the palette. + +Example stuff: + + local meta = stack:get_meta() + meta:set_string("key", "value") + print(dump(meta:to_table())) + +Formspec +-------- +Formspec defines a menu. Currently not much else than inventories are +supported. 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>;]` + +#### `position[<X>,<Y>]` +* Define the position of the formspec +* A value between 0.0 and 1.0 represents a position inside the screen +* The default value is the center of the screen (0.5, 0.5) + +#### `anchor[<X>,<Y>]` +* Define the anchor of the formspec +* A value between 0.0 and 1.0 represents an anchor inside the formspec +* The default value is the center of the formspec (0.5, 0.5) + +#### `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` +* Position and size units are inventory slots +* `name` is the name of the field as returned in fields to `on_receive_fields` +* `label`, if not blank, will be text printed on the top left above the field +* See field_close_on_enter to stop enter closing the formspec + +#### `field[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]` +* Textual 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` +* Position and size units are inventory slots +* `name` is the name of the field as returned in fields to `on_receive_fields` +* `label`, if not blank, will be text printed on the top left above the field +* `default` is the default value of the 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. +* See `field_close_on_enter` to stop enter closing the formspec + +#### `field[<name>;<label>;<default>]` +* As above, but without position/size units +* When enter is pressed in field, `fields.key_enter_field` will be sent with the name + of this field. +* Special field for creating simple forms, such as sign text input +* Must be used without a `size[]` element +* A "Proceed" button will be added automatically +* See `field_close_on_enter` to stop enter closing the formspec + +#### `field_close_on_enter[<name>;<close_on_enter>]` +* <name> is the name of the field +* if <close_on_enter> is false, pressing enter in the field will submit the form but not close it +* defaults to true when not specified (ie: no tag for a field) + +#### `textarea[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]` +* Same as fields above, but with multi-line input + +#### `label[<X>,<Y>;<label>]` +* `x` and `y` work as per field +* `label` is the text on the label +* Position and size units are inventory slots + +#### `vertlabel[<X>,<Y>;<label>]` +* Textual label drawn vertically +* `x` and `y` work as per field +* `label` is the text on the label +* Position and size units are inventory slots + +#### `button[<X>,<Y>;<W>,<H>;<name>;<label>]` +* Clickable button. When clicked, fields will be sent. +* `x`, `y` and `name` work as per field +* `w` and `h` are the size of the button +* `label` is the text on the button +* Position and size units are inventory slots + +#### `image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]` +* `x`, `y`, `w`, `h`, and `name` work as per button +* `texture name` is the filename of an image +* Position and size units are inventory slots + +#### `image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>;<noclip>;<drawborder>;<pressed texture name>]` +* `x`, `y`, `w`, `h`, and `name` work as per button +* `texture name` is the filename of an image +* Position and size units are inventory slots +* `noclip=true` means the image button doesn't need to be within specified formsize +* `drawborder`: draw button border or not +* `pressed texture name` is the filename of an image on pressed state + +#### `item_image_button[<X>,<Y>;<W>,<H>;<item name>;<name>;<label>]` +* `x`, `y`, `w`, `h`, `name` and `label` work as per button +* `item name` is the registered name of an item/node, + tooltip will be made out of its description + to override it use tooltip element +* Position and size units are inventory slots + +#### `button_exit[<X>,<Y>;<W>,<H>;<name>;<label>]` +* When clicked, fields will be sent and the form will quit. + +#### `image_button_exit[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]` +* When clicked, fields will be sent and the form will quit. + +#### `textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>]` +* Scrollable item list showing arbitrary text elements +* `x` and `y` position the itemlist relative to the top left of the menu +* `w` and `h` are the size of the itemlist +* `name` fieldname sent to server on doubleclick value is current selected element +* `listelements` can be prepended by #color in hexadecimal format RRGGBB (only), + * if you want a listelement to start with "#" write "##". + +#### `textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>;<selected idx>;<transparent>]` +* Scrollable itemlist showing arbitrary text elements +* `x` and `y` position the item list relative to the top left of the menu +* `w` and `h` are the size of the item list +* `name` fieldname sent to server on doubleclick value is current selected element +* `listelements` can be prepended by #RRGGBB (only) in hexadecimal format + * if you want a listelement to start with "#" write "##" +* Index to be selected within textlist +* `true`/`false`: draw transparent background +* See also `minetest.explode_textlist_event` (main menu: `engine.explode_textlist_event`) + +#### `tabheader[<X>,<Y>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]` +* Show a tab**header** at specific position (ignores formsize) +* `x` and `y` position the itemlist relative to the top left of the menu +* `name` fieldname data is transferred to Lua +* `caption 1`...: name shown on top of tab +* `current_tab`: index of selected tab 1... +* `transparent` (optional): show transparent +* `draw_border` (optional): draw border + +#### `box[<X>,<Y>;<W>,<H>;<color>]` +* Simple colored semitransparent box +* `x` and `y` position the box relative to the top left of the menu +* `w` and `h` are the size of box +* `color` is color specified as a `ColorString` + +#### `dropdown[<X>,<Y>;<W>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>]` +* Show a dropdown field +* **Important note**: There are two different operation modes: + 1. handle directly on change (only changed dropdown is submitted) + 2. read the value on pressing a button (all dropdown values are available) +* `x` and `y` position of dropdown +* Width of dropdown +* Fieldname data is transferred to Lua +* Items to be shown in dropdown +* Index of currently selected dropdown item + +#### `checkbox[<X>,<Y>;<name>;<label>;<selected>]` +* Show a checkbox +* `x` and `y`: position of checkbox +* `name` fieldname data is transferred to Lua +* `label` to be shown left of checkbox +* `selected` (optional): `true`/`false` + +#### `scrollbar[<X>,<Y>;<W>,<H>;<orientation>;<name>;<value>]` +* Show a scrollbar +* There are two ways to use it: + 1. handle the changed event (only changed scrollbar is available) + 2. read the value on pressing a button (all scrollbars are available) +* `x` and `y`: position of trackbar +* `w` and `h`: width and height +* `orientation`: `vertical`/`horizontal` +* Fieldname data is transferred to Lua +* Value this trackbar is set to (`0`-`1000`) +* See also `minetest.explode_scrollbar_event` (main menu: `engine.explode_scrollbar_event`) + +#### `table[<X>,<Y>;<W>,<H>;<name>;<cell 1>,<cell 2>,...,<cell n>;<selected idx>]` +* Show scrollable table using options defined by the previous `tableoptions[]` +* Displays cells as defined by the previous `tablecolumns[]` +* `x` and `y`: position the itemlist relative to the top left of the menu +* `w` and `h` are the size of the itemlist +* `name`: fieldname sent to server on row select or doubleclick +* `cell 1`...`cell n`: cell contents given in row-major order +* `selected idx`: index of row to be selected within table (first row = `1`) +* See also `minetest.explode_table_event` (main menu: `engine.explode_table_event`) + +#### `tableoptions[<opt 1>;<opt 2>;...]` +* Sets options for `table[]` +* `color=#RRGGBB` + * default text color (`ColorString`), defaults to `#FFFFFF` +* `background=#RRGGBB` + * table background color (`ColorString`), defaults to `#000000` +* `border=<true/false>` + * should the table be drawn with a border? (default: `true`) +* `highlight=#RRGGBB` + * highlight background color (`ColorString`), defaults to `#466432` +* `highlight_text=#RRGGBB` + * highlight text color (`ColorString`), defaults to `#FFFFFF` +* `opendepth=<value>` + * 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>;...]` +* Sets columns for `table[]` +* Types: `text`, `image`, `color`, `indent`, `tree` + * `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) +* Column options: + * `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) + +**Note**: do _not_ use a element name starting with `key_`; those names are reserved to +pass key press events to formspec! + +Inventory locations +------------------- +* `"context"`: Selected node metadata (deprecated: `"current_name"`) +* `"current_player"`: Player to whom the menu is shown +* `"player:<name>"`: Any player +* `"nodemeta:<X>,<Y>,<Z>"`: Any node metadata +* `"detached:<name>"`: A detached inventory + +Player Inventory lists +---------------------- +* `main`: list containing the default inventory +* `craft`: list containing the craft input +* `craftpreview`: list containing the craft output +* `hand`: list containing an override for the empty hand + +`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 `#AA` to the end of the color name +(e.g. `colorname#08`). For named colors the hexadecimal string representing the alpha +value must (always) be two hexadecimal digits. + +`ColorSpec` +----------- +A ColorSpec specifies a 32-bit color. It can be written in either: +table form, each element ranging from 0..255 (a, if absent, defaults to 255): + `colorspec = {a=255, r=0, g=255, b=0}` +numerical form, the raw integer value of an ARGB8 quad: + `colorspec = 0xFF00FF00` +or string form, a ColorString (defined above): + `colorspec = "green"` + +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: + +* `minetest.get_color_escape_sequence(color)`: + * `color` is a ColorString + * The escape sequence sets the text color to `color` +* `minetest.colorize(color, message)`: + * Equivalent to: + `minetest.get_color_escape_sequence(color) .. + message .. + minetest.get_color_escape_sequence("#ffffff")` +* `color.get_background_escape_sequence(color)` + * `color` is a ColorString + * The escape sequence sets the background of the whole text element to + `color`. Only defined for item descriptions and tooltips. +* `color.strip_foreground_colors(str)` + * Removes foreground colors added by `get_color_escape_sequence`. +* `color.strip_background_colors(str)` + * Removes background colors added by `get_background_escape_sequence`. +* `color.strip_colors(str)` + * Removes all color escape sequences. + +## Spatial Vectors +--------------- +* `vector.new(a[, b, c])`: returns a vector: + * A copy of `a` if `a` is a vector. + * `{x = a, y = b, z = c}`, if all `a, b, c` are defined +* `vector.direction(p1, p2)`: returns a vector +* `vector.distance(p1, p2)`: returns a number +* `vector.length(v)`: returns a number +* `vector.normalize(v)`: returns a vector +* `vector.floor(v)`: returns a vector, each dimension rounded down +* `vector.round(v)`: returns a vector, each dimension rounded to nearest int +* `vector.apply(v, func)`: returns a vector +* `vector.equals(v1, v2)`: returns a boolean +* `vector.sort(v1, v2)`: returns minp, maxp vectors of the cuboid defined by v1 and v2 + +For the following functions `x` can be either a vector or a number: + +* `vector.add(v, x)`: returns a vector +* `vector.subtract(v, x)`: returns a vector +* `vector.multiply(v, x)`: returns a scaled vector or Schur product +* `vector.divide(v, x)`: returns a scaled vector or Schur quotient + +## Helper functions +---------------- +* `dump2(obj, name="_", dumped={})` + * Return object serialized as a string, handles reference loops +* `dump(obj, dumped={})` + * Return object serialized as a string +* `math.hypot(x, y)` + * Get the hypotenuse of a triangle with legs x and y. + Useful for distance calculation. +* `math.sign(x, tolerance)` + * Get the sign of a number. + Optional: Also returns `0` when the absolute value is within the tolerance (default: `0`) +* `string.split(str, separator=",", include_empty=false, max_splits=-1, sep_is_pattern=false)` + * 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"}` +* `string:trim()` + * e.g. `string.trim("\n \t\tfoo bar\t ") == "foo bar"` +* `minetest.wrap_text(str, limit)`: returns a string + * Adds new lines to the string to keep it within the specified character limit + * limit: Maximal amount of characters in one line +* `minetest.pos_to_string({x=X,y=Y,z=Z}, decimal_places))`: returns string `"(X,Y,Z)"` + * Convert position to a printable string + Optional: 'decimal_places' will round the x, y and z of the pos to the given decimal place. +* `minetest.string_to_pos(string)`: returns a position + * Same but in reverse. Returns `nil` if the string can't be parsed to a position. +* `minetest.string_to_area("(X1, Y1, Z1) (X2, Y2, Z2)")`: returns two positions + * Converts a string representing an area box into two positions +* `minetest.formspec_escape(string)`: returns a string + * escapes the characters "[", "]", "\", "," and ";", which can not be used in formspecs +* `minetest.is_yes(arg)` + * returns true if passed 'y', 'yes', 'true' or a number that isn't zero. +* `minetest.get_us_time()` + * returns time with microsecond precision. May not return wall time. +* `table.copy(table)`: returns a table + * returns a deep copy of `table` +* `minetest.pointed_thing_to_face_pos(placer, pointed_thing)`: returns a position + * returns the exact position on the surface of a pointed node + +`minetest` namespace reference +------------------------------ + +## Utilities + +* `minetest.get_current_modname()`: returns the currently loading mod's name, when we are loading a mod +* `minetest.get_modpath(modname)`: returns e.g. `"/home/user/.minetest/usermods/modname"` + * Useful for loading additional `.lua` modules or static data from mod +* `minetest.get_modnames()`: returns a list of installed mods + * Return a list of installed mods, sorted alphabetically +* `minetest.get_worldpath()`: returns e.g. `"/home/user/.minetest/world"` + * Useful for storing custom data +* `minetest.is_singleplayer()` +* `minetest.features`: Table containing API feature flags + + { + glasslike_framed = true, + nodebox_as_selectionbox = true, + chat_send_player_param3 = true, + get_all_craft_recipes_works = true, + use_texture_alpha = true, + -- ^ The transparency channel of textures can be used optionally + no_legacy_abms = true, + -- ^ Tree and grass ABMs are no longer done from C++ + texture_names_parens = true, + -- ^ Texture grouping is possible using parentheses + area_store_custom_ids = true, + -- ^ Unique Area ID for AreaStore:insert_area + add_entity_with_staticdata = true, + -- ^ add_entity supports passing initial staticdata to on_activate + no_chat_message_prediction = true, + -- ^ Chat messages are no longer predicted + } +* `minetest.has_feature(arg)`: returns `boolean, missing_features` + * `arg`: string or table in format `{foo=true, bar=true}` + * `missing_features`: `{foo=true, bar=true}` +* `minetest.get_player_information(player_name)`: + * Returns a table containing information about a player. Example return value: + + { + address = "127.0.0.1", -- IP address of client + ip_version = 4, -- IPv4 / IPv6 + min_rtt = 0.01, -- minimum round trip time + max_rtt = 0.2, -- maximum round trip time + avg_rtt = 0.02, -- average round trip time + min_jitter = 0.01, -- minimum packet time jitter + max_jitter = 0.5, -- maximum packet time jitter + avg_jitter = 0.03, -- average packet time jitter + connection_uptime = 200, -- seconds since client connected + prot_vers = 31, -- protocol version used by client + -- following information is available on debug build only!!! + -- DO NOT USE IN MODS + --ser_vers = 26, -- serialization version used by client + --major = 0, -- major version number + --minor = 4, -- minor version number + --patch = 10, -- patch version number + --vers_string = "0.4.9-git", -- full version string + --state = "Active" -- current client state + } +* `minetest.mkdir(path)`: returns success. + * Creates a directory specified by `path`, creating parent directories + if they don't exist. +* `minetest.get_dir_list(path, [is_dir])`: returns list of entry names + * is_dir is one of: + * nil: return all entries, + * true: return only subdirectory names, or + * false: return only file names. +* `minetest.get_version()`: returns a table containing components of the + 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 verifyable. 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.nodeupdate then ... end`. + +### Logging +* `minetest.debug(...)` + * Equivalent to `minetest.log(table.concat({...}, "\t"))` +* `minetest.log([level,] text)` + * `level` is one of `"none"`, `"error"`, `"warning"`, `"action"`, + `"info"`, or `"verbose"`. Default is `"none"`. + +## Registration functions +Call these functions only at load time! + +* `minetest.register_entity(name, prototype table)` +* `minetest.register_abm(abm definition)` +* `minetest.register_lbm(lbm definition)` +* `minetest.register_node(name, node definition)` +* `minetest.register_tool(name, item definition)` +* `minetest.register_craftitem(name, item definition)` +* `minetest.unregister_item(name)` +* `minetest.register_alias(name, convert_to)` +* `minetest.register_alias_force(name, convert_to)` +* `minetest.register_craft(recipe)` + * Check recipe table syntax for different types below. +* `minetest.clear_craft(recipe)` + * Will erase existing craft based either on output item or on input recipe. + * Specify either output or input only. If you specify both, input will be ignored. For input use the same recipe table + syntax as for `minetest.register_craft(recipe)`. For output specify only the item, without a quantity. + * If no erase candidate could be found, Lua exception will be thrown. + * **Warning**! The type field ("shaped","cooking" or any other) will be ignored if the recipe + contains output. Erasing is then done independently from the crafting method. +* `minetest.register_ore(ore definition)` +* `minetest.register_biome(biome definition)` +* `minetest.register_decoration(decoration definition)` +* `minetest.override_item(name, redefinition)` + * Overrides fields of an item registered with register_node/tool/craftitem. + * Note: Item must already be defined, (opt)depend on the mod defining it. + * Example: `minetest.override_item("default:mese", {light_source=LIGHT_MAX})` +* `minetest.clear_registered_ores()` +* `minetest.clear_registered_biomes()` +* `minetest.clear_registered_decorations()` + +## Global callback registration functions +Call these functions only at load time! + +* `minetest.register_globalstep(func(dtime))` + * Called every server step, usually interval of 0.1s +* `minetest.register_on_shutdown(func())` + * Called before server shutdown + * **Warning**: If the server 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. +* `minetest.register_on_placenode(func(pos, newnode, placer, oldnode, itemstack, pointed_thing))` + * Called when a node has been placed + * If return `true` no item is taken from `itemstack` + * **Not recommended**; use `on_construct` or `after_place_node` in node definition + whenever possible +* `minetest.register_on_dignode(func(pos, oldnode, digger))` + * Called when a node has been dug. + * **Not recommended**; Use `on_destruct` or `after_dig_node` in node definition + whenever possible +* `minetest.register_on_punchnode(func(pos, node, puncher, pointed_thing))` + * Called when a node is punched +* `minetest.register_on_generated(func(minp, maxp, blockseed))` + * Called after generating a piece of world. Modifying nodes inside the area + is a bit faster than usually. +* `minetest.register_on_newplayer(func(ObjectRef))` + * Called after a new player has been created +* `minetest.register_on_dieplayer(func(ObjectRef))` + * Called when a player dies +* `minetest.register_on_punchplayer(func(player, hitter, time_from_last_punch, tool_capabilities, dir, damage))` + * Called when a player is punched + * `player` - ObjectRef - Player that was punched + * `hitter` - ObjectRef - Player that hit + * `time_from_last_punch`: Meant for disallowing spamming of clicks (can be nil) + * `tool_capabilities`: capability table of used tool (can be nil) + * `dir`: unit vector of direction of punch. Always defined. Points from + the puncher to the punched. + * `damage` - number that represents the damage calculated by the engine + * should return `true` to prevent the default damage mechanism +* `minetest.register_on_player_hpchange(func(player, hp_change), modifier)` + * Called when the player gets damaged or healed + * `player`: ObjectRef of the player + * `hp_change`: the amount of change. Negative when it is damage. + * `modifier`: when true, the function should return the actual `hp_change`. + Note: modifiers only get a temporary hp_change that can be modified by later modifiers. + modifiers can return true as a second argument to stop the execution of further functions. + Non-modifiers receive the final hp change calculated by the modifiers. +* `minetest.register_on_respawnplayer(func(ObjectRef))` + * Called when player is to be respawned + * Called _before_ repositioning of player occurs + * return true in func to disable regular player placement +* `minetest.register_on_prejoinplayer(func(name, ip))` + * Called before a player joins the game + * If it returns a string, the player is disconnected with that string as reason +* `minetest.register_on_joinplayer(func(ObjectRef))` + * Called when a player joins the game +* `minetest.register_on_leaveplayer(func(ObjectRef, timed_out))` + * Called when a player leaves the game + * `timed_out`: True for timeout, false for other reasons. +* `minetest.register_on_cheat(func(ObjectRef, cheat))` + * Called when a player cheats + * `cheat`: `{type=<cheat_type>}`, where `<cheat_type>` is one of: + * `moved_too_fast` + * `interacted_too_far` + * `interacted_while_dead` + * `finished_unknown_dig` + * `dug_unbreakable` + * `dug_too_fast` +* `minetest.register_on_chat_message(func(name, message))` + * Called always when a player says something + * Return `true` to mark the message as handled, which means that it will not be sent to other players +* `minetest.register_on_player_receive_fields(func(player, formname, fields))` + * Called when a button is pressed in player's inventory form + * Newest functions are called first + * If function returns `true`, remaining functions are not called +* `minetest.register_on_craft(func(itemstack, player, old_craft_grid, craft_inv))` + * Called when `player` crafts something + * `itemstack` is the output + * `old_craft_grid` contains the recipe (Note: the one in the inventory is cleared) + * `craft_inv` is the inventory with the crafting grid + * Return either an `ItemStack`, to replace the output, or `nil`, to not modify it +* `minetest.register_craft_predict(func(itemstack, player, old_craft_grid, craft_inv))` + * The same as before, except that it is called before the player crafts, to make + craft prediction, and it should not change anything. +* `minetest.register_on_protection_violation(func(pos, name))` + * Called by `builtin` and mods when a player violates protection at a position + (eg, digs a node or punches a protected entity). + * The registered functions can be called using `minetest.record_protection_violation` + * The provided function should check that the position is protected by the mod + calling this function before it prints a message, if it does, to allow for + multiple protection mods. +* `minetest.register_on_item_eat(func(hp_change, replace_with_item, itemstack, user, pointed_thing))` + * Called when an item is eaten, by `minetest.item_eat` + * Return `true` or `itemstack` to cancel the default item eat response (i.e.: hp increase) + +### Other registration functions +* `minetest.register_chatcommand(cmd, chatcommand definition)` + * Adds definition to `minetest.registered_chatcommands` +* `minetest.override_chatcommand(name, redefinition)` + * Overrides fields of a chatcommand registered with `register_chatcommand`. +* `minetest.unregister_chatcommand(name)` + * Unregisters a chatcommands registered with `register_chatcommand`. +* `minetest.register_privilege(name, definition)` + * `definition`: `"description text"` + * `definition`: `{ description = "description text", give_to_singleplayer = boolean}` + the default of `give_to_singleplayer` is true + * To allow players with `basic_privs` to grant, see `basic_privs` minetest.conf setting. +* `minetest.register_authentication_handler(handler)` + * See `minetest.builtin_auth_handler` in `builtin.lua` for reference + +### Setting-related +* `minetest.settings`: Settings object containing all of the settings from the + main config file (`minetest.conf`). +* `minetest.setting_get_pos(name)`: Loads a setting from the main settings and + parses it as a position (in the format `(1,2,3)`). Returns a position or nil. + +### Authentication +* `minetest.notify_authentication_modified(name)` + * Should be called by the authentication handler if privileges changes. + * To report everybody, set `name=nil`. +* `minetest.check_password_entry(name, entry, password)` + * Returns true if the "db entry" for a player with name matches given + * password, false otherwise. + * The "db entry" is the usually player-individual value that is derived + * from the player's chosen password and stored on the server in order to allow + * authentication whenever the player desires to log in. + * Only use this function for making it possible to log in via the password from + * via protocols like IRC, other uses for inside the game are frowned upon. +* `minetest.get_password_hash(name, raw_password)` + * Convert a name-password pair to a password hash that Minetest can use. + * The returned value alone is not a good basis for password checks based + * on comparing the password hash in the database with the password hash + * from the function, with an externally provided password, as the hash + * in the db might use the new SRP verifier format. + * For this purpose, use `minetest.check_password_entry` instead. +* `minetest.string_to_privs(str)`: returns `{priv1=true,...}` +* `minetest.privs_to_string(privs)`: returns `"priv1,priv2,..."` + * Convert between two privilege representations +* `minetest.set_player_password(name, password_hash)` +* `minetest.set_player_privs(name, {priv1=true,...})` +* `minetest.get_player_privs(name) -> {priv1=true,...}` +* `minetest.auth_reload()` +* `minetest.check_player_privs(player_or_name, ...)`: returns `bool, missing_privs` + * A quickhand for checking privileges. + * `player_or_name`: Either a Player object or the name of a player. + * `...` is either a list of strings, e.g. `"priva", "privb"` or + a table, e.g. `{ priva = true, privb = true }`. +* `minetest.get_player_ip(name)`: returns an IP address string + +`minetest.set_player_password`, `minetest_set_player_privs`, `minetest_get_player_privs` +and `minetest.auth_reload` call the authetification handler. + +### Chat +* `minetest.chat_send_all(text)` +* `minetest.chat_send_player(name, text)` + +## Environment access +* `minetest.set_node(pos, node)` +* `minetest.add_node(pos, node): alias set_node(pos, node)` + * Set node at position (`node = {name="foo", param1=0, param2=0}`) +* `minetest.swap_node(pos, node)` + * Set node at position, but don't remove metadata +* `minetest.remove_node(pos)` + * Equivalent to `set_node(pos, "air")` +* `minetest.get_node(pos)` + * Returns the node at the given position as table in the format + `{name="node_name", param1=0, param2=0}`, returns `{name="ignore", param1=0, param2=0}` + for unloaded areas. +* `minetest.get_node_or_nil(pos)` + * Same as `get_node` but returns `nil` for unloaded areas. +* `minetest.get_node_light(pos, timeofday)` + * 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` +* `minetest.place_node(pos, node)` + * Place node with the same effects that a player would cause +* `minetest.dig_node(pos)` + * Dig node with the same effects that a player would cause + * Returns `true` if successful, `false` on failure (e.g. protected location) +* `minetest.punch_node(pos)` + * Punch node with the same effects that a player would cause +* `minetest.spawn_falling_node(pos)` + * Change node into falling node + * Returns `true` if successful, `false` on failure + +* `minetest.find_nodes_with_meta(pos1, pos2)` + * Get a table of positions of nodes that have metadata within a region {pos1, pos2} +* `minetest.get_meta(pos)` + * Get a `NodeMetaRef` at that position +* `minetest.get_node_timer(pos)` + * Get `NodeTimerRef` + +* `minetest.add_entity(pos, name, [staticdata])`: Spawn Lua-defined entity at position + * Returns `ObjectRef`, or `nil` if failed +* `minetest.add_item(pos, item)`: Spawn item + * Returns `ObjectRef`, or `nil` if failed +* `minetest.get_player_by_name(name)`: Get an `ObjectRef` to a player +* `minetest.get_objects_inside_radius(pos, radius)` + * `radius`: using an euclidean metric +* `minetest.set_timeofday(val)` + * `val` is between `0` and `1`; `0` for midnight, `0.5` for midday +* `minetest.get_timeofday()` +* `minetest.get_gametime()`: returns the time, in seconds, since the world was created +* `minetest.get_day_count()`: returns number days elapsed since world was created, + * accounting for time changes. +* `minetest.find_node_near(pos, radius, nodenames, [search_center])`: returns pos 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 +* `minetest.find_nodes_in_area(minp, maxp, nodenames)`: returns a list of positions + * returns as second value a table with the count of the individual nodes found + * `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"` +* `minetest.find_nodes_in_area_under_air(minp, maxp, nodenames)`: returns a list of positions + * returned positions are nodes with a node air above + * `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"` +* `minetest.get_perlin(noiseparams)` +* `minetest.get_perlin(seeddiff, octaves, persistence, scale)` + * Return world-specific perlin noise (`int(worldseed)+seeddiff`) +* `minetest.get_voxel_manip([pos1, pos2])` + * Return voxel manipulator object. + * Loads the manipulator from the map if positions are passed. +* `minetest.set_gen_notify(flags, {deco_ids})` + * Set the types of on-generate notifications that should be collected + * `flags` is a flag field with the available flags: `dungeon`, `temple`, `cave_begin`, + `cave_end`, `large_cave_begin`, `large_cave_end`, `decoration` + * The second parameter is a list of IDS of decorations which notification is requested for +* `get_gen_notify()`: returns a flagstring and a table with the `deco_id`s +* `minetest.get_mapgen_object(objectname)` + * Return requested mapgen object if available (see "Mapgen objects") +* `minetest.get_biome_id(biome_name)` + * Returns the biome id, as used in the biomemap Mapgen object, for a + given biome_name string. +* `minetest.get_mapgen_params()` Returns mapgen parameters, a table containing + `mgname`, `seed`, `chunksize`, `water_level`, and `flags`. + * Deprecated: use `minetest.get_mapgen_setting(name)` instead +* `minetest.set_mapgen_params(MapgenParams)` + * Deprecated: use `minetest.set_mapgen_setting(name, value, override)` instead + * Set map generation parameters + * Function cannot be called after the registration period; only initialization + and `on_mapgen_init` + * Takes a table as an argument with the fields `mgname`, `seed`, `water_level`, + and `flags`. + * Leave field unset to leave that parameter unchanged + * `flags` contains a comma-delimited string of flags to set, + or if the prefix `"no"` is attached, clears instead. + * `flags` is in the same format and has the same options as `mg_flags` in `minetest.conf` +* `minetest.get_mapgen_setting(name)` + * Gets the *active* mapgen setting (or nil if none exists) in string format with the following + order of precedence: + 1) Settings loaded from map_meta.txt or overrides set during mod execution + 2) Settings set by mods without a metafile override + 3) Settings explicitly set in the user config file, minetest.conf + 4) Settings set as the user config default +* `minetest.get_mapgen_setting_noiseparams(name)` + * Same as above, but returns the value as a NoiseParams table if the setting `name` exists + and is a valid NoiseParams +* `minetest.set_mapgen_setting(name, value, [override_meta])` + * Sets a mapgen param to `value`, and will take effect if the corresponding mapgen setting + is not already present in map_meta.txt. + * `override_meta` is an optional boolean (default: `false`). If this is set to true, + the setting will become the active setting regardless of the map metafile contents. + * Note: to set the seed, use `"seed"`, not `"fixed_map_seed"` +* `minetest.set_mapgen_setting_noiseparams(name, value, [override_meta])` + * Same as above, except value is a NoiseParams table. +* `minetest.set_noiseparams(name, noiseparams, set_default)` + * Sets the noiseparams setting of `name` to the noiseparams table specified in `noiseparams`. + * `set_default` is an optional boolean (default: `true`) that specifies whether the setting + should be applied to the default config or current active config +* `minetest.get_noiseparams(name)`: returns a table of the noiseparams for name +* `minetest.generate_ores(vm, pos1, pos2)` + * Generate all registered ores within the VoxelManip `vm` and in the area from `pos1` to `pos2`. + * `pos1` and `pos2` are optional and default to mapchunk minp and maxp. +* `minetest.generate_decorations(vm, pos1, pos2)` + * Generate all registered decorations within the VoxelManip `vm` and in the area from `pos1` to `pos2`. + * `pos1` and `pos2` are optional and default to mapchunk minp and maxp. +* `minetest.clear_objects([options])` + * Clear all objects in the environment + * Takes an optional table as an argument with the field `mode`. + * mode = `"full"`: Load and go through every mapblock, clearing objects (default). + * mode = `"quick"`: Clear objects immediately in loaded mapblocks; + clear objects in unloaded mapblocks only when the mapblocks are next activated. +* `minetest.emerge_area(pos1, pos2, [callback], [param])` + * Queue all blocks in the area from `pos1` to `pos2`, inclusive, to be asynchronously + * fetched from memory, loaded from disk, or if inexistent, generates them. + * If `callback` is a valid Lua function, this will be called for each block emerged. + * The function signature of callback is: + * `function EmergeAreaCallback(blockpos, action, calls_remaining, param)` + * - `blockpos` is the *block* coordinates of the block that had been emerged + * - `action` could be one of the following constant values: + * `minetest.EMERGE_CANCELLED`, `minetest.EMERGE_ERRORED`, `minetest.EMERGE_FROM_MEMORY`, + * `minetest.EMERGE_FROM_DISK`, `minetest.EMERGE_GENERATED` + * - `calls_remaining` is the number of callbacks to be expected after this one + * - `param` is the user-defined parameter passed to emerge_area (or nil if the + * parameter was absent) +* `minetest.delete_area(pos1, pos2)` + * delete all mapblocks in the area from pos1 to pos2, inclusive +* `minetest.line_of_sight(pos1, pos2, stepsize)`: returns `boolean, pos` + * Check if there is a direct line of sight between `pos1` and `pos2` + * Returns the position of the blocking node when `false` + * `pos1`: First position + * `pos2`: Second position + * `stepsize`: smaller gives more accurate results but requires more computing + time. Default is `1`. +* `minetest.find_path(pos1,pos2,searchdistance,max_jump,max_drop,algorithm)` + * returns table containing path + * returns a table of 3D points representing a path from `pos1` to `pos2` or `nil` + * `pos1`: start position + * `pos2`: end position + * `searchdistance`: number of blocks to search in each direction using a maximum metric + * `max_jump`: maximum height difference to consider walkable + * `max_drop`: maximum height difference to consider droppable + * `algorithm`: One of `"A*_noprefetch"` (default), `"A*"`, `"Dijkstra"` +* `minetest.spawn_tree (pos, {treedef})` + * spawns L-system tree at given `pos` with definition in `treedef` table +* `minetest.transforming_liquid_add(pos)` + * add node to liquid update queue +* `minetest.get_node_max_level(pos)` + * get max available level for leveled node +* `minetest.get_node_level(pos)` + * get level of leveled node (water, snow) +* `minetest.set_node_level(pos, level)` + * set level of leveled node, default `level` equals `1` + * if `totallevel > maxlevel`, returns rest (`total-max`). +* `minetest.add_node_level(pos, level)` + * increase level of leveled node by level, default `level` equals `1` + * if `totallevel > maxlevel`, returns rest (`total-max`) + * can be negative for decreasing +* `minetest.fix_light(pos1, pos2)`: returns `true`/`false` + * resets the light in a cuboid-shaped part of + the map and removes lighting bugs. + * Loads the area if it is not loaded. + * `pos1` is the corner of the cuboid with the least coordinates + (in node coordinates), inclusive. + * `pos2` is the opposite corner of the cuboid, inclusive. + * The actual updated cuboid might be larger than the specified one, + because only whole map blocks can be updated. + The actual updated area consists of those map blocks that intersect + with the given cuboid. + * However, the neighborhood of the updated area might change + as well, as light can spread out of the cuboid, also light + might be removed. + * returns `false` if the area is not fully generated, + `true` otherwise +* `minetest.check_single_for_falling(pos)` + * causes an unsupported `group:falling_node` node to fall and causes an + unattached `group:attached_node` node to fall. + * does not spread these updates to neighbours. +* `minetest.check_for_falling(pos)` + * causes an unsupported `group:falling_node` node to fall and causes an + unattached `group:attached_node` node to fall. + * spread these updates to neighbours and can cause a cascade + of nodes to fall. + +### Inventory +`minetest.get_inventory(location)`: returns an `InvRef` + +* `location` = e.g. + * `{type="player", name="celeron55"}` + * `{type="node", pos={x=, y=, z=}}` + * `{type="detached", name="creative"}` +* `minetest.create_detached_inventory(name, callbacks, [player_name])`: returns an `InvRef` + * callbacks: See "Detached inventory callbacks" + * `player_name`: Make detached inventory available to one player exclusively, + by default they will be sent to every player (even if not used). + Note that this parameter is mostly just a workaround and will be removed in future releases. + * Creates a detached inventory. If it already exists, it is cleared. +* `minetest.do_item_eat(hp_change, replace_with_item, itemstack, user, pointed_thing)`: + returns left over ItemStack + * See `minetest.item_eat` and `minetest.register_on_item_eat` + +### Formspec +* `minetest.show_formspec(playername, formname, formspec)` + * `playername`: name of player to show formspec + * `formname`: name passed to `on_player_receive_fields` callbacks. + It should follow the `"modname:<whatever>"` naming convention + * `formspec`: formspec to display +* `minetest.close_formspec(playername, formname)` + * `playername`: name of player to close formspec + * `formname`: has to exactly match the one given in `show_formspec`, or the formspec will + not close. + * calling `show_formspec(playername, formname, "")` is equal to this expression + * to close a formspec regardless of the formname, call + `minetest.close_formspec(playername, "")`. **USE THIS ONLY WHEN ABSOLUTELY NECESSARY!** +* `minetest.formspec_escape(string)`: returns a string + * escapes the characters "[", "]", "\", "," and ";", which can not be used in formspecs +* `minetest.explode_table_event(string)`: returns a table + * returns e.g. `{type="CHG", row=1, column=2}` + * `type` is one of: + * `"INV"`: no row selected) + * `"CHG"`: selected) + * `"DCL"`: double-click +* `minetest.explode_textlist_event(string)`: returns a table + * returns e.g. `{type="CHG", index=1}` + * `type` is one of: + * `"INV"`: no row selected) + * `"CHG"`: selected) + * `"DCL"`: double-click +* `minetest.explode_scrollbar_event(string)`: returns a table + * returns e.g. `{type="CHG", value=500}` + * `type` is one of: + * `"INV"`: something failed + * `"CHG"`: has been changed + * `"VAL"`: not changed + +## Item handling +* `minetest.inventorycube(img1, img2, img3)` + * Returns a string for making an image of a cube (useful as an item image) +* `minetest.get_pointed_thing_position(pointed_thing, above)` + * Get position of a `pointed_thing` (that you can get from somewhere) +* `minetest.dir_to_facedir(dir, is6d)` + * Convert a vector to a facedir value, used in `param2` for `paramtype2="facedir"`; + * passing something non-`nil`/`false` for the optional second parameter causes it to + take the y component into account +* `minetest.facedir_to_dir(facedir)` + * Convert a facedir back into a vector aimed directly out the "back" of a node +* `minetest.dir_to_wallmounted(dir)` + * Convert a vector to a wallmounted value, used for `paramtype2="wallmounted"` +* `minetest.wallmounted_to_dir(wallmounted)` + * Convert a wallmounted value back into a vector aimed directly out the "back" of a node +* `minetest.dir_to_yaw(dir)` + * Convert a vector into a yaw (angle) +* `minetest.yaw_to_dir(yaw)` + * Convert yaw (angle) to a vector +* `minetest.get_node_drops(nodename, toolname)` + * Returns list of item names. + * **Note**: This will be removed or modified in a future version. +* `minetest.get_craft_result(input)`: returns `output, decremented_input` + * `input.method` = `"normal"` or `"cooking"` or `"fuel"` + * `input.width` = for example `3` + * `input.items` = for example + `{ stack1, stack2, stack3, stack4, stack 5, stack 6, stack 7, stack 8, stack 9 }` + * `output.item` = `ItemStack`, if unsuccessful: empty `ItemStack` + * `output.time` = a number, if unsuccessful: `0` + * `output.replacements` = list of `ItemStack`s that couldn't be placed in + `decremented_input.items` + * `decremented_input` = like `input` +* `minetest.get_craft_recipe(output)`: returns input + * returns last registered recipe for output item (node) + * `output` is a node or item type such as `"default:torch"` + * `input.method` = `"normal"` or `"cooking"` or `"fuel"` + * `input.width` = for example `3` + * `input.items` = for example + `{ stack1, stack2, stack3, stack4, stack 5, stack 6, stack 7, stack 8, stack 9 }` + * `input.items` = `nil` if no recipe found +* `minetest.get_all_craft_recipes(query item)`: returns a table or `nil` + * returns indexed table with all registered recipes for query item (node) + or `nil` if no recipe was found + * recipe entry table: + + { + method = 'normal' or 'cooking' or 'fuel' + width = 0-3, 0 means shapeless recipe + items = indexed [1-9] table with recipe items + output = string with item name and quantity + } + * Example query for `"default:gold_ingot"` will return table: + + { + [1]={type = "cooking", width = 3, output = "default:gold_ingot", + items = {1 = "default:gold_lump"}}, + [2]={type = "normal", width = 1, output = "default:gold_ingot 9", + items = {1 = "default:goldblock"}} + } +* `minetest.handle_node_drops(pos, drops, digger)` + * `drops`: list of itemstrings + * Handles drops from nodes after digging: Default action is to put them into + digger's inventory + * Can be overridden to get different functionality (e.g. dropping items on + ground) + +### Rollback +* `minetest.rollback_get_node_actions(pos, range, seconds, limit)`: + returns `{{actor, pos, time, oldnode, newnode}, ...}` + * Find who has done something to a node, or near a node + * `actor`: `"player:<name>"`, also `"liquid"`. +* `minetest.rollback_revert_actions_by(actor, seconds)`: returns `boolean, log_messages` + * Revert latest actions of someone + * `actor`: `"player:<name>"`, also `"liquid"`. + +### Defaults for the `on_*` item definition functions +These functions return the leftover itemstack. + +* `minetest.item_place_node(itemstack, placer, pointed_thing, param2)` + * Place item as a node + * `param2` overrides `facedir` and wallmounted `param2` + * returns `itemstack, success` +* `minetest.item_place_object(itemstack, placer, pointed_thing)` + * Place item as-is +* `minetest.item_place(itemstack, placer, pointed_thing, param2)` + * Use one of the above based on what the item is. + * Calls `on_rightclick` of `pointed_thing.under` if defined instead + * **Note**: is not called when wielded item overrides `on_place` + * `param2` overrides `facedir` and wallmounted `param2` + * returns `itemstack, success` +* `minetest.item_drop(itemstack, dropper, pos)` + * Drop the item +* `minetest.item_eat(hp_change, replace_with_item)` + * Eat the item. + * `replace_with_item` is the itemstring which is added to the inventory. + If the player is eating a stack, then replace_with_item goes to a + different spot. Can be `nil` + * See `minetest.do_item_eat` + +### Defaults for the `on_punch` and `on_dig` node definition callbacks +* `minetest.node_punch(pos, node, puncher, pointed_thing)` + * Calls functions registered by `minetest.register_on_punchnode()` +* `minetest.node_dig(pos, node, digger)` + * Checks if node can be dug, puts item into inventory, removes node + * Calls functions registered by `minetest.registered_on_dignodes()` + +### Sounds +* `minetest.sound_play(spec, parameters)`: returns a handle + * `spec` is a `SimpleSoundSpec` + * `parameters` is a sound parameter table +* `minetest.sound_stop(handle)` +* `minetest.sound_fade(handle, step, gain)` + * `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 +* `minetest.after(time, func, ...)` + * Call the function `func` after `time` seconds, may be fractional + * Optional: Variable number of arguments that are passed to `func` + +### Server +* `minetest.request_shutdown([message],[reconnect],[delay])`: request for server shutdown. Will display `message` to clients, + `reconnect` == true displays a reconnect button, + `delay` adds an optional delay (in seconds) before shutdown + negative delay cancels the current active shutdown + zero delay triggers an immediate shutdown. +* `minetest.cancel_shutdown_requests()`: cancel current delayed shutdown +* `minetest.get_server_status()`: returns server status string +* `minetest.get_server_uptime()`: returns the server uptime in seconds +* `minetest.remove_player(name)`: remove player from database (if he is not connected). + * Does not remove player authentication data, minetest.player_exists will continue to return true. + * Returns a code (0: successful, 1: no such player, 2: player is connected) + +### Bans +* `minetest.get_ban_list()`: returns the ban list (same as `minetest.get_ban_description("")`) +* `minetest.get_ban_description(ip_or_name)`: returns ban description (string) +* `minetest.ban_player(name)`: ban a player +* `minetest.unban_player_or_ip(name)`: unban player or IP address +* `minetest.kick_player(name, [reason])`: disconnect a player with a optional reason + +### Particles +* `minetest.add_particle(particle definition)` + * Deprecated: `minetest.add_particle(pos, velocity, acceleration, expirationtime, + size, collisiondetection, texture, playername)` + +* `minetest.add_particlespawner(particlespawner definition)` + * Add a `ParticleSpawner`, an object that spawns an amount of particles over `time` seconds + * Returns an `id`, and -1 if adding didn't succeed + * `Deprecated: minetest.add_particlespawner(amount, time, + minpos, maxpos, + minvel, maxvel, + minacc, maxacc, + minexptime, maxexptime, + minsize, maxsize, + collisiondetection, texture, playername)` + +* `minetest.delete_particlespawner(id, player)` + * Delete `ParticleSpawner` with `id` (return value from `minetest.add_particlespawner`) + * If playername is specified, only deletes on the player's client, + * otherwise on all clients + +### Schematics +* `minetest.create_schematic(p1, p2, probability_list, filename, slice_prob_list)` + * Create a schematic from the volume of map specified by the box formed by p1 and p2. + * Apply the specified probability values to the specified nodes in `probability_list`. + * `probability_list` is an array of tables containing two fields, `pos` and `prob`. + * `pos` is the 3D vector specifying the absolute coordinates of the + node being modified, + * `prob` is the integer value from `0` to `255` of the probability (see: Schematic specifier). + * If there are two or more entries with the same pos value, the + last entry is used. + * If `pos` is not inside the box formed by `p1` and `p2`, it is ignored. + * If `probability_list` equals `nil`, no probabilities are applied. + * Slice probability works in the same manner, except takes a field + called `ypos` instead which + indicates the y position of the slice with a probability applied. + * If slice probability list equals `nil`, no slice probabilities are applied. + * Saves schematic in the Minetest Schematic format to filename. + +* `minetest.place_schematic(pos, schematic, rotation, replacements, force_placement)` + * Place the schematic specified by schematic (see: Schematic specifier) at `pos`. + * `rotation` can equal `"0"`, `"90"`, `"180"`, `"270"`, or `"random"`. + * If the `rotation` parameter is omitted, the schematic is not rotated. + * `replacements` = `{["old_name"] = "convert_to", ...}` + * `force_placement` is a boolean indicating whether nodes other than `air` and + `ignore` are replaced by the schematic + * Returns nil if the schematic could not be loaded. + +* `minetest.place_schematic_on_vmanip(vmanip, pos, schematic, rotation, replacement, force_placement)`: + * This function is analagous to minetest.place_schematic, but places a schematic onto the + specified VoxelManip object `vmanip` instead of the whole map. + * Returns false if any part of the schematic was cut-off due to the VoxelManip not + containing the full area required, and true if the whole schematic was able to fit. + * Returns nil if the schematic could not be loaded. + * After execution, any external copies of the VoxelManip contents are invalidated. + +* `minetest.serialize_schematic(schematic, format, options)` + * Return the serialized schematic specified by schematic (see: Schematic specifier) + * in the `format` of either "mts" or "lua". + * "mts" - a string containing the binary MTS data used in the MTS file format + * "lua" - a string containing Lua code representing the schematic in table format + * `options` is a table containing the following optional parameters: + * If `lua_use_comments` is true and `format` is "lua", the Lua code generated will have (X, Z) + * position comments for every X row generated in the schematic data for easier reading. + * If `lua_num_indent_spaces` is a nonzero number and `format` is "lua", the Lua code generated + * will use that number of spaces as indentation instead of a tab character. + +### HTTP Requests: +* `minetest.request_http_api()`: + * returns `HTTPApiTable` containing http functions if the calling mod has been granted + access by being listed in the `secure.http_mods` or `secure.trusted_mods` setting, + otherwise returns `nil`. + * The returned table contains the functions `fetch`, `fetch_async` and `fetch_async_get` + described below. + * Only works at init time and must be called from the mod's main scope (not from a function). + * Function only exists if minetest server was built with cURL support. + * **DO NOT ALLOW ANY OTHER MODS TO ACCESS THE RETURNED TABLE, STORE IT IN + A LOCAL VARIABLE!** +* `HTTPApiTable.fetch(HTTPRequest req, callback)` + * Performs given request asynchronously and calls callback upon completion + * callback: `function(HTTPRequestResult res)` + * Use this HTTP function if you are unsure, the others are for advanced use. +* `HTTPApiTable.fetch_async(HTTPRequest req)`: returns handle + * Performs given request asynchronously and returns handle for `HTTPApiTable.fetch_async_get` +* `HTTPApiTable.fetch_async_get(handle)`: returns HTTPRequestResult + * Return response data for given asynchronous HTTP request + +### Storage API: +* `minetest.get_mod_storage()`: + * returns reference to mod private `StorageRef` + * must be called during mod load time + +## Misc. (minetest.player_exists(name)) +* `minetest.get_connected_players()`: returns list of `ObjectRefs` +* `minetest.player_exists(name)`: boolean, whether player exists (regardless of online status) +* `minetest.hud_replace_builtin(name, hud_definition)` + * Replaces definition of a builtin hud element + * `name`: `"breath"` or `"health"` + * `hud_definition`: definition to replace builtin definition +* `minetest.hash_node_position({x=,y=,z=})`: returns an 48-bit integer + * Gives a unique hash number for a node position (16+16+16=48bit) +* `minetest.get_position_from_hash(hash)`: returns a position + * Inverse transform of `minetest.hash_node_position` +* `minetest.get_item_group(name, group)`: returns a rating + * Get rating of a group of an item. (`0` means: not in group) +* `minetest.get_node_group(name, group)`: returns a rating + * Deprecated: An alias for the former. +* `minetest.raillike_group(name)`: returns a rating + * Returns rating of the connect_to_raillike group corresponding to name + * If name is not yet the name of a connect_to_raillike group, a new group id + * is created, with that name +* `minetest.get_content_id(name)`: returns an integer + * Gets the internal content ID of `name` +* `minetest.get_name_from_content_id(content_id)`: returns a string + * Gets the name of the content with that content ID +* `minetest.parse_json(string[, nullvalue])`: returns something + * 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}}` +* `minetest.write_json(data[, styled])`: returns a string or `nil` and an error message + * 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 will cause an error. + * **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}]"` +* `minetest.serialize(table)`: returns a string + * 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" }'` +* `minetest.deserialize(string)`: returns a table + * 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)` +* `minetest.compress(data, method, ...)`: returns `compressed_data` + * 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`. +* `minetest.decompress(compressed_data, method, ...)`: returns data + * 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. +* `minetest.encode_base64(string)`: returns string encoded in base64 + * Encodes a string in base64. +* `minetest.decode_base64(string)`: returns string + * Decodes a string encoded in base64. +* `minetest.is_protected(pos, name)`: returns boolean + * Returns true, if player `name` shouldn't be abled to dig at `pos` or do other + actions, defineable by mods, due to some mod-defined ownership-like concept. + Returns false or nil, if the player is allowed to do such actions. + * This function should be overridden by protection mods and should be used to + check if a player can interact at a position. + * This function should call the old version of itself if the position is not + protected by the mod. + * Example: + + local old_is_protected = minetest.is_protected + function minetest.is_protected(pos, name) + if mymod:position_protected_from(pos, name) then + return true + end + return old_is_protected(pos, name) + end +* `minetest.record_protection_violation(pos, name)` + * This function calls functions registered with + `minetest.register_on_protection_violation`. +* `minetest.rotate_and_place(itemstack, placer, pointed_thing, infinitestacks, orient_flags)` + * Attempt to predict the desired orientation of the facedir-capable node + defined by `itemstack`, and place it accordingly (on-wall, on the floor, or + hanging from the ceiling). Stacks are handled normally if the `infinitestacks` + field is false or omitted (else, the itemstack is not changed). `orient_flags` + is an optional table containing extra tweaks to the placement code: + * `invert_wall`: if `true`, place wall-orientation on the ground and ground- + orientation on the wall. + * `force_wall` : if `true`, always place the node in wall orientation. + * `force_ceiling`: if `true`, always place on the ceiling. + * `force_floor`: if `true`, always place the node on the floor. + * `force_facedir`: if `true`, forcefully reset the facedir to north when placing on + the floor or ceiling + * The first four options are mutually-exclusive; the last in the list takes + precedence over the first. +* `minetest.rotate_node(itemstack, placer, pointed_thing)` + * calls `rotate_and_place()` with infinitestacks set according to the state of + the creative mode setting, and checks for "sneak" to set the `invert_wall` + parameter. + +* `minetest.forceload_block(pos[, transient])` + * forceloads the position `pos`. + * returns `true` if area could be forceloaded + * If `transient` is `false` or absent, the forceload will be persistent + (saved between server runs). If `true`, the forceload will be transient + (not saved between server runs). + +* `minetest.forceload_free_block(pos[, transient])` + * stops forceloading the position `pos` + * If `transient` is `false` or absent, frees a persistent forceload. + If `true`, frees a transient forceload. + +* `minetest.request_insecure_environment()`: returns an environment containing + insecure functions if the calling mod has been listed as trusted in the + `secure.trusted_mods` setting or security is disabled, otherwise returns `nil`. + * Only works at init time and must be called from the mod's main scope (not from a function). + * **DO NOT ALLOW ANY OTHER MODS TO ACCESS THE RETURNED ENVIRONMENT, STORE IT IN + A LOCAL VARIABLE!** + +* `minetest.global_exists(name)` + * Checks if a global variable has been set, without triggering a warning. + +### Global objects +* `minetest.env`: `EnvRef` of the server environment and world. + * Any function in the minetest namespace can be called using the syntax + `minetest.env:somefunction(somearguments)` + instead of `minetest.somefunction(somearguments)` + * Deprecated, but support is not to be dropped soon + +### Global tables +* `minetest.registered_items` + * Map of registered items, indexed by name +* `minetest.registered_nodes` + * Map of registered node definitions, indexed by name +* `minetest.registered_craftitems` + * Map of registered craft item definitions, indexed by name +* `minetest.registered_tools` + * Map of registered tool definitions, indexed by name +* `minetest.registered_entities` + * Map of registered entity prototypes, indexed by name +* `minetest.object_refs` + * Map of object references, indexed by active object id +* `minetest.luaentities` + * Map of Lua entities, indexed by active object id +* `minetest.registered_chatcommands` + * Map of registered chat command definitions, indexed by name +* `minetest.registered_ores` + * List of registered ore definitions. +* `minetest.registered_biomes` + * List of registered biome definitions. +* `minetest.registered_decorations` + * List of registered decoration definitions. + +Class reference +--------------- + +## `MetaDataRef` +See `StorageRef`, `NodeMetaRef` and `ItemStackMetaRef`. + +#### Methods +* `set_string(name, value)` +* `get_string(name)` +* `set_int(name, value)` +* `get_int(name)` +* `set_float(name, value)` +* `get_float(name)` +* `to_table()`: returns `nil` or a table with keys: + * `fields`: key-value storage + * `inventory`: `{list1 = {}, ...}}` (NodeMetaRef only) +* `from_table(nil or {})` + * Any non-table value will clear the metadata + * See "Node Metadata" for an example + * returns `true` on success +* `equals(other)` + * returns `true` if this metadata has the same key-value pairs as `other` + +### `NodeMetaRef` +Node metadata: reference extra data and functionality stored in a node. +Can be obtained via `minetest.get_meta(pos)`. + +#### Methods +* All methods in MetaDataRef +* `get_inventory()`: returns `InvRef` +* `mark_as_private(name or {name1, name2, ...})`: Mark specific vars as private + This will prevent them from being sent to the client. Note that the "private" + status will only be remembered if an associated key-value pair exists, meaning + it's best to call this when initializing all other meta (e.g. `on_construct`). + +### `ItemStackMetaRef` +ItemStack metadata: reference extra data and functionality stored in a stack. +Can be obtained via `item:get_meta()`. + +#### Methods +* All methods in MetaDataRef + +### `StorageRef` +Mod metadata: per mod metadata, saved automatically. +Can be obtained via `minetest.get_mod_storage()` during load time. + +#### Methods +* All methods in MetaDataRef + +### `NodeTimerRef` +Node Timers: a high resolution persistent per-node timer. +Can be gotten via `minetest.get_node_timer(pos)`. + +#### Methods +* `set(timeout,elapsed)` + * set a timer's state + * `timeout` is in seconds, and supports fractional values (0.1 etc) + * `elapsed` is in seconds, and supports fractional values (0.1 etc) + * will trigger the node's `on_timer` function after `(timeout - elapsed)` seconds +* `start(timeout)` + * start a timer + * equivalent to `set(timeout,0)` +* `stop()` + * stops the timer +* `get_timeout()`: returns current timeout in seconds + * if `timeout` equals `0`, timer is inactive +* `get_elapsed()`: returns current elapsed time in seconds + * the node's `on_timer` function will be called after `(timeout - elapsed)` seconds +* `is_started()`: returns boolean state of timer + * returns `true` if timer is started, otherwise `false` + +## `ObjectRef` +Moving things in the game are generally these. + +This is basically a reference to a C++ `ServerActiveObject` + +#### Methods +* `remove()`: remove object (after returning from Lua) + * Note: Doesn't work on players, use `minetest.kick_player` instead +* `get_pos()`: returns `{x=num, y=num, z=num}` +* `set_pos(pos)`; `pos`=`{x=num, y=num, z=num}` +* `move_to(pos, continuous=false)`: interpolated move +* `punch(puncher, time_from_last_punch, tool_capabilities, direction)` + * `puncher` = another `ObjectRef`, + * `time_from_last_punch` = time since last punch action of the puncher + * `direction`: can be `nil` +* `right_click(clicker)`; `clicker` is another `ObjectRef` +* `get_hp()`: returns number of hitpoints (2 * number of hearts) +* `set_hp(hp)`: set number of hitpoints (2 * number of hearts) +* `get_inventory()`: returns an `InvRef` +* `get_wield_list()`: returns the name of the inventory list the wielded item is in +* `get_wield_index()`: returns the index of the wielded item +* `get_wielded_item()`: returns an `ItemStack` +* `set_wielded_item(item)`: replaces the wielded item, returns `true` if successful +* `set_armor_groups({group1=rating, group2=rating, ...})` +* `get_armor_groups()`: returns a table with the armor group ratings +* `set_animation({x=1,y=1}, frame_speed=15, frame_blend=0, frame_loop=true)` +* `get_animation()`: returns `range`, `frame_speed`, `frame_blend` and `frame_loop` +* `set_attach(parent, bone, position, rotation)` + * `bone`: string + * `position`: `{x=num, y=num, z=num}` (relative) + * `rotation`: `{x=num, y=num, z=num}` +* `get_attach()`: returns parent, bone, position, rotation or nil if it isn't attached +* `set_detach()` +* `set_bone_position(bone, position, rotation)` + * `bone`: string + * `position`: `{x=num, y=num, z=num}` (relative) + * `rotation`: `{x=num, y=num, z=num}` +* `get_bone_position(bone)`: returns position and rotation of the bone +* `set_properties(object property table)` +* `get_properties()`: returns object property table +* `is_player()`: returns true for players, false otherwise +* `get_nametag_attributes()` + * returns a table with the attributes of the nametag of an object + * { + color = {a=0..255, r=0..255, g=0..255, b=0..255}, + text = "", + } +* `set_nametag_attributes(attributes)` + * sets the attributes of the nametag of an object + * `attributes`: + { + color = ColorSpec, + text = "My Nametag", + } + +## LuaEntitySAO-only (no-op for other objects) +* `set_velocity({x=num, y=num, z=num})` +* `get_velocity()`: returns `{x=num, y=num, z=num}` +* `set_acceleration({x=num, y=num, z=num})` +* `get_acceleration()`: returns `{x=num, y=num, z=num}` +* `set_yaw(radians)` +* `get_yaw()`: returns number in radians +* `set_texture_mod(mod)` +* `get_texture_mod()` returns current texture modifier +* `set_sprite(p={x=0,y=0}, num_frames=1, framelength=0.2, + select_horiz_by_yawpitch=false)` + * Select sprite from spritesheet with optional animation and DM-style + texture selection based on yaw relative to camera +* `get_entity_name()` (**Deprecated**: Will be removed in a future version) +* `get_luaentity()` + +## Player-only (no-op for other objects) +* `get_player_name()`: returns `""` if is not a player +* `get_player_velocity()`: returns `nil` if is not a player, otherwise a + table {x, y, z} representing the player's instantaneous velocity in nodes/s +* `get_look_dir()`: get camera direction as a unit vector +* `get_look_vertical()`: pitch in radians + * Angle ranges between -pi/2 and pi/2, which are straight up and down respectively. +* `get_look_horizontal()`: yaw in radians + * Angle is counter-clockwise from the +z direction. +* `set_look_vertical(radians)`: sets look pitch + * radians - Angle from looking forward, where positive is downwards. +* `set_look_horizontal(radians)`: sets look yaw + * radians - Angle from the +z direction, where positive is counter-clockwise. +* `get_look_pitch()`: pitch in radians - Deprecated as broken. Use `get_look_vertical`. + * Angle ranges between -pi/2 and pi/2, which are straight down and up respectively. +* `get_look_yaw()`: yaw in radians - Deprecated as broken. Use `get_look_horizontal`. + * Angle is counter-clockwise from the +x direction. +* `set_look_pitch(radians)`: sets look pitch - Deprecated. Use `set_look_vertical`. +* `set_look_yaw(radians)`: sets look yaw - Deprecated. Use `set_look_horizontal`. +* `get_breath()`: returns players breath +* `set_breath(value)`: sets players breath + * values: + * `0`: player is drowning, + * `1`-`10`: remaining number of bubbles + * `11`: bubbles bar is not shown +* `set_attribute(attribute, value)`: + * Sets an extra attribute with value on player. + * `value` must be a string. + * If `value` is `nil`, remove attribute from player. +* `get_attribute(attribute)`: + * Returns value (a string) for extra attribute. + * Returns `nil` if no attribute found. +* `set_inventory_formspec(formspec)` + * Redefine player's inventory form + * Should usually be called in `on_joinplayer` +* `get_inventory_formspec()`: returns a formspec string +* `get_player_control()`: returns table with player pressed keys + * `{jump=bool,right=bool,left=bool,LMB=bool,RMB=bool,sneak=bool,aux1=bool,down=bool,up=bool}` +* `get_player_control_bits()`: returns integer with bit packed player pressed keys + * bit nr/meaning: 0/up ,1/down ,2/left ,3/right ,4/jump ,5/aux1 ,6/sneak ,7/LMB ,8/RMB +* `set_physics_override(override_table)` + * `override_table` is a table with the following fields: + * `speed`: multiplier to default walking speed value (default: `1`) + * `jump`: multiplier to default jump value (default: `1`) + * `gravity`: multiplier to default gravity value (default: `1`) + * `sneak`: whether player can sneak (default: `true`) + * `sneak_glitch`: whether player can use the new move code replications + of the old sneak side-effects: sneak ladders and 2 node sneak jump + (default: `false`) + * `new_move`: use new move/sneak code. When `false` the exact old code + is used for the specific old sneak behaviour (default: `true`) +* `get_physics_override()`: returns the table given to `set_physics_override` +* `hud_add(hud definition)`: add a HUD element described by HUD def, returns ID + number on success +* `hud_remove(id)`: remove the HUD element of the specified id +* `hud_change(id, stat, value)`: change a value of a previously added HUD element + * element `stat` values: `position`, `name`, `scale`, `text`, `number`, `item`, `dir` +* `hud_get(id)`: gets the HUD element definition structure of the specified ID +* `hud_set_flags(flags)`: sets specified HUD flags to `true`/`false` + * `flags`: (is visible) `hotbar`, `healthbar`, `crosshair`, `wielditem`, `minimap` + * pass a table containing a `true`/`false` value of each flag to be set or unset + * if a flag equals `nil`, the flag is not modified + * note that setting `minimap` modifies the client's permission to view the minimap - + * the client may locally elect to not view the minimap +* `hud_get_flags()`: returns a table containing status of hud flags + * returns `{ hotbar=true, healthbar=true, crosshair=true, wielditem=true, breathbar=true, minimap=true }` +* `hud_set_hotbar_itemcount(count)`: sets number of items in builtin hotbar + * `count`: number of items, must be between `1` and `23` +* `hud_get_hotbar_itemcount`: returns number of visible items +* `hud_set_hotbar_image(texturename)` + * sets background image for hotbar +* `hud_get_hotbar_image`: returns texturename +* `hud_set_hotbar_selected_image(texturename)` + * sets image for selected item of hotbar +* `hud_get_hotbar_selected_image`: returns texturename +* `set_sky(bgcolor, type, {texture names}, clouds)` + * `bgcolor`: ColorSpec, defaults to white + * `type`: Available types: + * `"regular"`: Uses 0 textures, `bgcolor` ignored + * `"skybox"`: Uses 6 textures, `bgcolor` used + * `"plain"`: Uses 0 textures, `bgcolor` used + * `clouds`: Boolean for whether clouds appear in front of `"skybox"` or + `"plain"` custom skyboxes (default: `true`) +* `get_sky()`: returns bgcolor, type, table of textures, clouds +* `set_clouds(parameters)`: set cloud parameters + * `parameters` is a table with the following optional fields: + * `density`: from `0` (no clouds) to `1` (full clouds) (default `0.4`) + * `color`: basic cloud color, with alpha channel (default `#fff0f0e5`) + * `ambient`: cloud color lower bound, use for a "glow at night" effect (default `#000000`) + * `height`: cloud height, i.e. y of cloud base (default per conf, usually `120`) + * `thickness`: cloud thickness in nodes (default `16`) + * `speed`: 2D cloud speed + direction in nodes per second (default `{x=0, y=-2}`) +* `get_clouds()`: returns a table with the current cloud parameters as in `set_clouds` +* `override_day_night_ratio(ratio or nil)` + * `0`...`1`: Overrides day-night ratio, controlling sunlight to a specific amount + * `nil`: Disables override, defaulting to sunlight based on day-night cycle +* `get_day_night_ratio()`: returns the ratio or nil if it isn't overridden +* `set_local_animation(stand/idle, walk, dig, walk+dig, frame_speed=frame_speed)` + + set animation for player model in third person view + + set_local_animation({x=0, y=79}, -- < stand/idle animation key frames + {x=168, y=187}, -- < walk animation key frames + {x=189, y=198}, -- < dig animation key frames + {x=200, y=219}, -- < walk+dig animation key frames + frame_speed=30): -- < animation frame speed +* `get_local_animation()`: returns stand, walk, dig, dig+walk tables and `frame_speed` +* `set_eye_offset({x=0,y=0,z=0},{x=0,y=0,z=0})`: defines offset value for camera per player + * in first person view + * in third person view (max. values `{x=-10/10,y=-10,15,z=-5/5}`) +* `get_eye_offset()`: returns `offset_first` and `offset_third` + +### `InvRef` +An `InvRef` is a reference to an inventory. + +#### Methods +* `is_empty(listname)`: return `true` if list is empty +* `get_size(listname)`: get size of a list +* `set_size(listname, size)`: set size of a list + * returns `false` on error (e.g. invalid `listname` or `size`) +* `get_width(listname)`: get width of a list +* `set_width(listname, width)`: set width of list; currently used for crafting +* `get_stack(listname, i)`: get a copy of stack index `i` in list +* `set_stack(listname, i, stack)`: copy `stack` to index `i` in list +* `get_list(listname)`: return full list +* `set_list(listname, list)`: set full list (size will not change) +* `get_lists()`: returns list of inventory lists +* `set_lists(lists)`: sets inventory lists (size will not change) +* `add_item(listname, stack)`: add item somewhere in list, returns leftover `ItemStack` +* `room_for_item(listname, stack):` returns `true` if the stack of items + can be fully added to the list +* `contains_item(listname, stack)`: returns `true` if the stack of items + can be fully taken from the list +* `remove_item(listname, stack)`: take as many items as specified from the list, + returns the items that were actually removed (as an `ItemStack`) -- note that + any item metadata is ignored, so attempting to remove a specific unique + item this way will likely remove the wrong one -- to do that use `set_stack` + with an empty `ItemStack` +* `get_location()`: returns a location compatible to `minetest.get_inventory(location)` + * returns `{type="undefined"}` in case location is not known + +### `AreaStore` +A fast access data structure to store areas, and find areas near a given position or area. +Every area has a `data` string attribute to store additional information. +You can create an empty `AreaStore` by calling `AreaStore()`, or `AreaStore(type_name)`. +If you chose the parameter-less constructor, a fast implementation will be automatically +chosen for you. + +#### Methods +* `get_area(id, include_borders, include_data)`: returns the area with the id `id`. + (optional) Boolean values `include_borders` and `include_data` control what's copied. + Returns nil if specified area id does not exist. +* `get_areas_for_pos(pos, include_borders, include_data)`: returns all areas that contain + the position `pos`. (optional) Boolean values `include_borders` and `include_data` control + what's copied. +* `get_areas_in_area(edge1, edge2, accept_overlap, include_borders, include_data)`: + returns all areas that contain all nodes inside the area specified by `edge1` and `edge2` (inclusive). + If `accept_overlap` is true, also areas are returned that have nodes in common with the specified area. + (optional) Boolean values `include_borders` and `include_data` control what's copied. +* `insert_area(edge1, edge2, data, [id])`: inserts an area into the store. Returns the new area's ID, + or nil if the insertion failed. The (inclusive) positions `edge1` and `edge2` describe the area. + `data` is a string stored with the area. If passed, `id` will be used as the internal area ID, + it must be a unique number between 0 and 2^32-2. If you use the `id` parameter you must always use it, + or insertions are likely to fail due to conflicts. +* `reserve(count)`: reserves resources for at most `count` many contained areas. + Only needed for efficiency, and only some implementations profit. +* `remove_area(id)`: removes the area with the given id from the store, returns success. +* `set_cache_params(params)`: sets params for the included prefiltering cache. + Calling invalidates the cache, so that its elements have to be newly generated. + * `params`: + { + enabled = boolean, -- whether to enable, default true + block_radius = number, -- the radius (in nodes) of the areas the cache generates + prefiltered lists for, minimum 16, default 64 + limit = number, -- the cache's size, minimum 20, default 1000 + } +* `to_string()`: Experimental. Returns area store serialized as a (binary) string. +* `to_file(filename)`: Experimental. Like `to_string()`, but writes the data to a file. +* `from_string(str)`: Experimental. Deserializes string and loads it into the AreaStore. + Returns success and, optionally, an error message. +* `from_file(filename)`: Experimental. Like `from_string()`, but reads the data from a file. + +### `ItemStack` +An `ItemStack` is a stack of items. + +It can be created via `ItemStack(x)`, where x is an `ItemStack`, +an itemstring, a table or `nil`. + +#### Methods +* `is_empty()`: Returns `true` if stack is empty. +* `get_name()`: Returns item name (e.g. `"default:stone"`). +* `set_name(item_name)`: Returns boolean whether item was cleared +* `get_count()`: Returns number of items on the stack. +* `set_count(count)`: Returns boolean whether item was cleared +* `get_wear()`: Returns tool wear (`0`-`65535`), `0` for non-tools. +* `set_wear(wear)`: Returns boolean whether item was cleared +* `get_meta()`: Returns ItemStackMetaRef. See section for more details +* `get_metadata()`: (DEPRECATED) Returns metadata (a string attached to an item stack). +* `set_metadata(metadata)`: (DEPRECATED) Returns true. +* `clear()`: removes all items from the stack, making it empty. +* `replace(item)`: replace the contents of this stack. + * `item` can also be an itemstring or table. +* `to_string()`: Returns the stack in itemstring form. +* `to_table()`: Returns the stack in Lua table form. +* `get_stack_max()`: Returns the maximum size of the stack (depends on the item). +* `get_free_space()`: Returns `get_stack_max() - get_count()`. +* `is_known()`: Returns `true` if the item name refers to a defined item type. +* `get_definition()`: Returns the item definition table. +* `get_tool_capabilities()`: Returns the digging properties of the item, + or those of the hand if none are defined for this item type +* `add_wear(amount)`: Increases wear by `amount` if the item is a tool. +* `add_item(item)`: Put some item or stack onto this stack. + Returns leftover `ItemStack`. +* `item_fits(item)`: Returns `true` if item or stack can be fully added to + this one. +* `take_item(n=1)`: Take (and remove) up to `n` items from this stack. + Returns taken `ItemStack`. +* `peek_item(n=1)`: copy (don't remove) up to `n` items from this stack. + Returns taken `ItemStack`. + +### `PseudoRandom` +A 16-bit pseudorandom number generator. +Uses a well-known LCG algorithm introduced by K&R. + +It can be created via `PseudoRandom(seed)`. + +#### Methods +* `next()`: return next integer random number [`0`...`32767`] +* `next(min, max)`: return next integer random number [`min`...`max`] + * `((max - min) == 32767) or ((max-min) <= 6553))` must be true + due to the simple implementation making bad distribution otherwise. + +### `PcgRandom` +A 32-bit pseudorandom number generator. +Uses PCG32, an algorithm of the permuted congruential generator family, offering very strong randomness. + +It can be created via `PcgRandom(seed)` or `PcgRandom(seed, sequence)`. + +#### Methods +* `next()`: return next integer random number [`-2147483648`...`2147483647`] +* `next(min, max)`: return next integer random number [`min`...`max`] +* `rand_normal_dist(min, max, num_trials=6)`: return normally distributed random number [`min`...`max`] + * This is only a rough approximation of a normal distribution with: + * `mean = (max - min) / 2`, and + * `variance = (((max - min + 1) ^ 2) - 1) / (12 * num_trials)` + * Increasing `num_trials` improves accuracy of the approximation + +### `SecureRandom` +Interface for the operating system's crypto-secure PRNG. + +It can be created via `SecureRandom()`. The constructor returns nil if a secure random device cannot be +be found on the system. + +#### Methods +* `next_bytes([count])`: return next `count` (default 1, capped at 2048) many random bytes, as a string. + +### `PerlinNoise` +A perlin noise generator. +It can be created via `PerlinNoise(seed, octaves, persistence, scale)` +or `PerlinNoise(noiseparams)`. +Alternatively with `minetest.get_perlin(seeddiff, octaves, persistence, scale)` +or `minetest.get_perlin(noiseparams)`. + +#### Methods +* `get2d(pos)`: returns 2D noise value at `pos={x=,y=}` +* `get3d(pos)`: returns 3D noise value at `pos={x=,y=,z=}` + +### `PerlinNoiseMap` +A fast, bulk perlin noise generator. + +It can be created via `PerlinNoiseMap(noiseparams, size)` or +`minetest.get_perlin_map(noiseparams, size)`. + +Format of `size` is `{x=dimx, y=dimy, z=dimz}`. The `z` conponent is ommitted +for 2D noise, and it must be must be larger than 1 for 3D noise (otherwise +`nil` is returned). + +For each of the functions with an optional `buffer` parameter: If `buffer` is not +nil, this table will be used to store the result instead of creating a new table. + + +#### Methods +* `get2dMap(pos)`: returns a `<size.x>` times `<size.y>` 2D array of 2D noise + with values starting at `pos={x=,y=}` +* `get3dMap(pos)`: returns a `<size.x>` times `<size.y>` times `<size.z>` 3D array + of 3D noise with values starting at `pos={x=,y=,z=}` +* `get2dMap_flat(pos, buffer)`: returns a flat `<size.x * size.y>` element array of 2D noise + with values starting at `pos={x=,y=}` +* `get3dMap_flat(pos, buffer)`: Same as `get2dMap_flat`, but 3D noise +* `calc2dMap(pos)`: Calculates the 2d noise map starting at `pos`. The result is stored internally. +* `calc3dMap(pos)`: Calculates the 3d noise map starting at `pos`. The result is stored internally. +* `getMapSlice(slice_offset, slice_size, buffer)`: In the form of an array, returns a slice of the + most recently computed noise results. The result slice begins at coordinates `slice_offset` and + takes a chunk of `slice_size`. + E.g. to grab a 2-slice high horizontal 2d plane of noise starting at buffer offset y = 20: + `noisevals = noise:getMapSlice({y=20}, {y=2})` + It is important to note that `slice_offset` offset coordinates begin at 1, and are relative to + the starting position of the most recently calculated noise. + To grab a single vertical column of noise starting at map coordinates x = 1023, y=1000, z = 1000: + `noise:calc3dMap({x=1000, y=1000, z=1000})` + `noisevals = noise:getMapSlice({x=24, z=1}, {x=1, z=1})` + +### `VoxelManip` + +#### About VoxelManip +VoxelManip is a scripting interface to the internal 'Map Voxel Manipulator' facility. The purpose of +this object is for fast, low-level, bulk access to reading and writing Map content. As such, setting +map nodes through VoxelManip will lack many of the higher level features and concepts you may be used +to with other methods of setting nodes. For example, nodes will not have their construction and +destruction callbacks run, and no rollback information is logged. + +It is important to note that VoxelManip is designed for speed, and *not* ease of use or flexibility. +If your mod requires a map manipulation facility that will handle 100% of all edge cases, or the use +of high level node placement features, perhaps `minetest.set_node()` is better suited for the job. + +In addition, VoxelManip might not be faster, or could even be slower, for your specific use case. +VoxelManip is most effective when setting very large areas of map at once - for example, if only +setting a 5x5x5 node area, a `minetest.set_node()` loop may be more optimal. Always profile code +using both methods of map manipulation to determine which is most appropriate for your usage. + +#### Using VoxelManip +A VoxelManip object can be created any time using either: +`VoxelManip([p1, p2])`, or `minetest.get_voxel_manip([p1, p2])`. + +If the optional position parameters are present for either of these routines, the specified region +will be pre-loaded into the VoxelManip object on creation. Otherwise, the area of map you wish to +manipulate must first be loaded into the VoxelManip object using `VoxelManip:read_from_map()`. + +Note that `VoxelManip:read_from_map()` returns two position vectors. The region formed by these +positions indicate the minimum and maximum (respectively) positions of the area actually loaded in +the VoxelManip, which may be larger than the area requested. For convenience, the loaded area +coordinates can also be queried any time after loading map data with `VoxelManip:get_emerged_area()`. + +Now that the VoxelManip object is populated with map data, your mod can fetch a copy of this data +using either of two methods. `VoxelManip:get_node_at()`, which retrieves an individual node in a +MapNode formatted table at the position requested is the simplest method to use, but also the slowest. + +Nodes in a VoxelManip object may also be read in bulk to a flat array table using: +`VoxelManip:get_data()` for node content (in Content ID form, see section 'Content IDs'), +`VoxelManip:get_light_data()` for node light levels, and +`VoxelManip:get_param2_data()` for the node type-dependent "param2" values. + +See section 'Flat array format' for more details. + +It is very important to understand that the tables returned by any of the above three functions +represent a snapshot of the VoxelManip's internal state at the time of the call. This copy of the +data will *not* magically update itself if another function modifies the internal VoxelManip state. +Any functions that modify a VoxelManip's contents work on the VoxelManip's internal state unless +otherwise explicitly stated. + +Once the bulk data has been edited to your liking, the internal VoxelManip state can be set using: +`VoxelManip:set_data()` for node content (in Content ID form, see section 'Content IDs'), +`VoxelManip:set_light_data()` for node light levels, and +`VoxelManip:set_param2_data()` for the node type-dependent `param2` values. + +The parameter to each of the above three functions can use any table at all in the same flat array +format as produced by `get_data()` et al. and is *not required* to be a table retrieved from `get_data()`. + +Once the internal VoxelManip state has been modified to your liking, the changes can be committed back +to the map by calling `VoxelManip:write_to_map()`. + + +##### Flat array format +Let + `Nx = p2.X - p1.X + 1`, + `Ny = p2.Y - p1.Y + 1`, and + `Nz = p2.Z - p1.Z + 1`. + +Then, for a loaded region of p1..p2, this array ranges from `1` up to and including the value of +the expression `Nx * Ny * Nz`. + +Positions offset from p1 are present in the array with the format of: + +``` +[ + (0, 0, 0), (1, 0, 0), (2, 0, 0), ... (Nx, 0, 0), + (0, 1, 0), (1, 1, 0), (2, 1, 0), ... (Nx, 1, 0), + ... + (0, Ny, 0), (1, Ny, 0), (2, Ny, 0), ... (Nx, Ny, 0), + (0, 0, 1), (1, 0, 1), (2, 0, 1), ... (Nx, 0, 1), + ... + (0, Ny, 2), (1, Ny, 2), (2, Ny, 2), ... (Nx, Ny, 2), + ... + (0, Ny, Nz), (1, Ny, Nz), (2, Ny, Nz), ... (Nx, Ny, Nz) +] +``` + +and the array index for a position p contained completely in p1..p2 is: + +`(p.Z - p1.Z) * Ny * Nx + (p.Y - p1.Y) * Nx + (p.X - p1.X) + 1` + +Note that this is the same "flat 3D array" format as `PerlinNoiseMap:get3dMap_flat()`. +VoxelArea objects (see section 'VoxelArea') can be used to simplify calculation of the index +for a single point in a flat VoxelManip array. + +##### Content IDs +A Content ID is a unique integer identifier for a specific node type. These IDs are used by VoxelManip +in place of the node name string for `VoxelManip:get_data()` and `VoxelManip:set_data()`. You can use +`minetest.get_content_id()` to look up the Content ID for the specified node name, and +`minetest.get_name_from_content_id()` to look up the node name string for a given Content ID. +After registration of a node, its Content ID will remain the same throughout execution of the mod. +Note that the node being queried needs to have already been been registered. + +The following builtin node types have their Content IDs defined as constants: + +* `minetest.CONTENT_UNKNOWN`: ID for "unknown" nodes +* `minetest.CONTENT_AIR`: ID for "air" nodes +* `minetest.CONTENT_IGNORE`: ID for "ignore" nodes + +##### Mapgen VoxelManip objects +Inside of `on_generated()` callbacks, it is possible to retrieve the same VoxelManip object used by the +core's Map Generator (commonly abbreviated Mapgen). Most of the rules previously described still apply +but with a few differences: + +* The Mapgen VoxelManip object is retrieved using: `minetest.get_mapgen_object("voxelmanip")` +* This VoxelManip object already has the region of map just generated loaded into it; it's not necessary + to call `VoxelManip:read_from_map()` before using a Mapgen VoxelManip. +* The `on_generated()` callbacks of some mods may place individual nodes in the generated area using + non-VoxelManip map modification methods. Because the same Mapgen VoxelManip object is passed through + each `on_generated()` callback, it becomes necessary for the Mapgen VoxelManip object to maintain + consistency with the current map state. For this reason, calling any of the following functions: + `minetest.add_node()`, `minetest.set_node()`, or `minetest.swap_node()` + will also update the Mapgen VoxelManip object's internal state active on the current thread. +* After modifying the Mapgen VoxelManip object's internal buffer, it may be necessary to update lighting + information using either: `VoxelManip:calc_lighting()` or `VoxelManip:set_lighting()`. + +##### Other API functions operating on a VoxelManip +If any VoxelManip contents were set to a liquid node, `VoxelManip:update_liquids()` must be called +for these liquid nodes to begin flowing. It is recommended to call this function only after having +written all buffered data back to the VoxelManip object, save for special situations where the modder +desires to only have certain liquid nodes begin flowing. + +The functions `minetest.generate_ores()` and `minetest.generate_decorations()` will generate all +registered decorations and ores throughout the full area inside of the specified VoxelManip object. + +`minetest.place_schematic_on_vmanip()` is otherwise identical to `minetest.place_schematic()`, +except instead of placing the specified schematic directly on the map at the specified position, it +will place the schematic inside of the VoxelManip. + +##### Notes +* Attempting to read data from a VoxelManip object before map is read will result in a zero-length + array table for `VoxelManip:get_data()`, and an "ignore" node at any position for + `VoxelManip:get_node_at()`. +* If either a region of map has not yet been generated or is out-of-bounds of the map, that region is + filled with "ignore" nodes. +* Other mods, or the core itself, could possibly modify the area of map currently loaded into a VoxelManip + object. With the exception of Mapgen VoxelManips (see above section), the internal buffers are not + updated. For this reason, it is strongly encouraged to complete the usage of a particular VoxelManip + object in the same callback it had been created. +* If a VoxelManip object will be used often, such as in an `on_generated()` callback, consider passing + a file-scoped table as the optional parameter to `VoxelManip:get_data()`, which serves as a static + buffer the function can use to write map data to instead of returning a new table each call. This + greatly enhances performance by avoiding unnecessary memory allocations. + +#### Methods +* `read_from_map(p1, p2)`: Loads a chunk of map into the VoxelManip object containing + the region formed by `p1` and `p2`. + * returns actual emerged `pmin`, actual emerged `pmax` +* `write_to_map([light])`: Writes the data loaded from the `VoxelManip` back to the map. + * **important**: data must be set using `VoxelManip:set_data()` before calling this + * if `light` is true, then lighting is automatically recalculated. + The default value is true. + If `light` is false, no light calculations happen, and you should correct + all modified blocks with `minetest.fix_light()` as soon as possible. + Keep in mind that modifying the map where light is incorrect can cause + more lighting bugs. +* `get_node_at(pos)`: Returns a `MapNode` table of the node currently loaded in + the `VoxelManip` at that position +* `set_node_at(pos, node)`: Sets a specific `MapNode` in the `VoxelManip` at that position +* `get_data([buffer])`: Retrieves the node content data loaded into the `VoxelManip` object + * returns raw node data in the form of an array of node content IDs + * if the param `buffer` is present, this table will be used to store the result instead +* `set_data(data)`: Sets the data contents of the `VoxelManip` object +* `update_map()`: Does nothing, kept for compatibility. +* `set_lighting(light, [p1, p2])`: Set the lighting within the `VoxelManip` to a uniform value + * `light` is a table, `{day=<0...15>, night=<0...15>}` + * To be used only by a `VoxelManip` object from `minetest.get_mapgen_object` + * (`p1`, `p2`) is the area in which lighting is set; + defaults to the whole area if left out +* `get_light_data()`: Gets the light data read into the `VoxelManip` object + * Returns an array (indices 1 to volume) of integers ranging from `0` to `255` + * Each value is the bitwise combination of day and night light values (`0` to `15` each) + * `light = day + (night * 16)` +* `set_light_data(light_data)`: Sets the `param1` (light) contents of each node + in the `VoxelManip` + * expects lighting data in the same format that `get_light_data()` returns +* `get_param2_data([buffer])`: Gets the raw `param2` data read into the `VoxelManip` object + * Returns an array (indices 1 to volume) of integers ranging from `0` to `255` + * If the param `buffer` is present, this table will be used to store the result instead +* `set_param2_data(param2_data)`: Sets the `param2` contents of each node in the `VoxelManip` +* `calc_lighting([p1, p2], [propagate_shadow])`: Calculate lighting within the `VoxelManip` + * To be used only by a `VoxelManip` object from `minetest.get_mapgen_object` + * (`p1`, `p2`) is the area in which lighting is set; defaults to the whole area + if left out or nil + * `propagate_shadow` is an optional boolean deciding whether shadows in a generated + mapchunk above are propagated down into the mapchunk; defaults to `true` if left out +* `update_liquids()`: Update liquid flow +* `was_modified()`: Returns `true` or `false` if the data in the voxel manipulator + had been modified since the last read from map, due to a call to + `minetest.set_data()` on the loaded area elsewhere +* `get_emerged_area()`: Returns actual emerged minimum and maximum positions. + +### `VoxelArea` +A helper class for voxel areas. +It can be created via `VoxelArea:new{MinEdge=pmin, MaxEdge=pmax}`. +The coordinates are *inclusive*, like most other things in Minetest. + +#### Methods +* `getExtent()`: returns a 3D vector containing the size of the area formed by + `MinEdge` and `MaxEdge` +* `getVolume()`: returns the volume of the area formed by `MinEdge` and `MaxEdge` +* `index(x, y, z)`: returns the index of an absolute position in a flat array starting at `1` + * useful for things like `VoxelManip`, raw Schematic specifiers, + `PerlinNoiseMap:get2d`/`3dMap`, and so on +* `indexp(p)`: same as above, except takes a vector +* `position(i)`: returns the absolute position vector corresponding to index `i` +* `contains(x, y, z)`: check if (`x`,`y`,`z`) is inside area formed by `MinEdge` and `MaxEdge` +* `containsp(p)`: same as above, except takes a vector +* `containsi(i)`: same as above, except takes an index `i` +* `iter(minx, miny, minz, maxx, maxy, maxz)`: returns an iterator that returns indices + * from (`minx`,`miny`,`minz`) to (`maxx`,`maxy`,`maxz`) in the order of `[z [y [x]]]` +* `iterp(minp, maxp)`: same as above, except takes a vector + +### `Settings` +An interface to read config files in the format of `minetest.conf`. + +It can be created via `Settings(filename)`. + +#### Methods +* `get(key)`: returns a value +* `get_bool(key)`: returns a boolean +* `set(key, value)` + * Setting names can't contain whitespace or any of `="{}#`. + * Setting values can't contain the sequence `\n"""`. + * Setting names starting with "secure." can't be set on the main settings object (`minetest.settings`). +* `set_bool(key, value)` + * See documentation for set() above. +* `remove(key)`: returns a boolean (`true` for success) +* `get_names()`: returns `{key1,...}` +* `write()`: returns a boolean (`true` for success) + * Writes changes to file. +* `to_table()`: returns `{[key1]=value1,...}` + +Mapgen objects +-------------- +A mapgen object is a construct used in map generation. Mapgen objects can be used +by an `on_generate` callback to speed up operations by avoiding unnecessary +recalculations; these can be retrieved using the `minetest.get_mapgen_object()` +function. If the requested Mapgen object is unavailable, or `get_mapgen_object()` +was called outside of an `on_generate()` callback, `nil` is returned. + +The following Mapgen objects are currently available: + +### `voxelmanip` +This returns three values; the `VoxelManip` object to be used, minimum and maximum +emerged position, in that order. All mapgens support this object. + +### `heightmap` +Returns an array containing the y coordinates of the ground levels of nodes in +the most recently generated chunk by the current mapgen. + +### `biomemap` +Returns an array containing the biome IDs of nodes in the most recently +generated chunk by the current mapgen. + +### `heatmap` +Returns an array containing the temperature values of nodes in the most +recently generated chunk by the current mapgen. + +### `humiditymap` +Returns an array containing the humidity values of nodes in the most recently +generated chunk by the current mapgen. + +### `gennotify` +Returns a table mapping requested generation notification types to arrays of +positions at which the corresponding generated structures are located at within +the current chunk. To set the capture of positions of interest to be recorded +on generate, use `minetest.set_gen_notify()`. + +Possible fields of the table returned are: + +* `dungeon` +* `temple` +* `cave_begin` +* `cave_end` +* `large_cave_begin` +* `large_cave_end` +* `decoration` + +Decorations have a key in the format of `"decoration#id"`, where `id` is the +numeric unique decoration ID. + +Registered entities +------------------- +* Functions receive a "luaentity" as `self`: + * It has the member `.name`, which is the registered name `("mod:thing")` + * It has the member `.object`, which is an `ObjectRef` pointing to the object + * The original prototype stuff is visible directly via a metatable +* Callbacks: + * `on_activate(self, staticdata, dtime_s)` + * Called when the object is instantiated. + * `dtime_s` is the time passed since the object was unloaded, which can + be used for updating the entity state. + * `on_step(self, dtime)` + * Called on every server tick, after movement and collision processing. + `dtime` is usually 0.1 seconds, as per the `dedicated_server_step` setting + `in minetest.conf`. + * `on_punch(self, puncher, time_from_last_punch, tool_capabilities, dir)` + * Called when somebody punches the object. + * Note that you probably want to handle most punches using the + automatic armor group system. + * `puncher`: an `ObjectRef` (can be `nil`) + * `time_from_last_punch`: Meant for disallowing spamming of clicks (can be `nil`) + * `tool_capabilities`: capability table of used tool (can be `nil`) + * `dir`: unit vector of direction of punch. Always defined. Points from + the puncher to the punched. + * `on_rightclick(self, clicker)` + * `get_staticdata(self)` + * Should return a string that will be passed to `on_activate` when + the object is instantiated the next time. + +L-system trees +-------------- +**Warning** +L-system generation currently creates lighting bugs in the form of mapblock-sized shadows. +Often these bugs appear as subtle shadows in water. + +### Tree definition + + treedef={ + axiom, --string initial tree axiom + rules_a, --string rules set A + rules_b, --string rules set B + rules_c, --string rules set C + rules_d, --string rules set D + trunk, --string trunk node name + leaves, --string leaves node name + leaves2, --string secondary leaves node name + leaves2_chance,--num chance (0-100) to replace leaves with leaves2 + angle, --num angle in deg + iterations, --num max # of iterations, usually 2 -5 + random_level, --num factor to lower nr of iterations, usually 0 - 3 + trunk_type, --string single/double/crossed) type of trunk: 1 node, + -- 2x2 nodes or 3x3 in cross shape + thin_branches, --boolean true -> use thin (1 node) branches + fruit, --string fruit node name + fruit_chance, --num chance (0-100) to replace leaves with fruit node + seed, --num random seed; if no seed is provided, the engine will create one + } + +### Key for Special L-System Symbols used in Axioms + +* `G`: move forward one unit with the pen up +* `F`: move forward one unit with the pen down drawing trunks and branches +* `f`: move forward one unit with the pen down drawing leaves (100% chance) +* `T`: move forward one unit with the pen down drawing trunks only +* `R`: move forward one unit with the pen down placing fruit +* `A`: replace with rules set A +* `B`: replace with rules set B +* `C`: replace with rules set C +* `D`: replace with rules set D +* `a`: replace with rules set A, chance 90% +* `b`: replace with rules set B, chance 80% +* `c`: replace with rules set C, chance 70% +* `d`: replace with rules set D, chance 60% +* `+`: yaw the turtle right by `angle` parameter +* `-`: yaw the turtle left by `angle` parameter +* `&`: pitch the turtle down by `angle` parameter +* `^`: pitch the turtle up by `angle` parameter +* `/`: roll the turtle to the right by `angle` parameter +* `*`: roll the turtle to the left by `angle` parameter +* `[`: save in stack current state info +* `]`: recover from stack state info + +### Example +Spawn a small apple tree: + + pos = {x=230,y=20,z=4} + apple_tree={ + axiom="FFFFFAFFBF", + rules_a="[&&&FFFFF&&FFFF][&&&++++FFFFF&&FFFF][&&&----FFFFF&&FFFF]", + rules_b="[&&&++FFFFF&&FFFF][&&&--FFFFF&&FFFF][&&&------FFFFF&&FFFF]", + trunk="default:tree", + leaves="default:leaves", + angle=30, + iterations=2, + random_level=0, + trunk_type="single", + thin_branches=true, + fruit_chance=10, + fruit="default:apple" + } + minetest.spawn_tree(pos,apple_tree) + +Definition tables +----------------- + +## Object Properties + + { + hp_max = 1, + physical = true, + collide_with_objects = true, -- collide with other objects if physical = true + weight = 5, + collisionbox = {-0.5, 0.0, -0.5, 0.5, 1.0, 0.5}, + visual = "cube" / "sprite" / "upright_sprite" / "mesh" / "wielditem", + visual_size = {x = 1, y = 1}, + mesh = "model", + textures = {}, -- number of required textures depends on visual + colors = {}, -- number of required colors depends on visual + spritediv = {x = 1, y = 1}, + initial_sprite_basepos = {x = 0, y = 0}, + is_visible = true, + makes_footstep_sound = false, + automatic_rotate = false, + stepheight = 0, + automatic_face_movement_dir = 0.0, + -- ^ Automatically set yaw to movement direction, offset in degrees, + -- 'false' to disable. + automatic_face_movement_max_rotation_per_sec = -1, + -- ^ Limit automatic rotation to this value in degrees per second, + -- value < 0 no limit. + backface_culling = true, -- false to disable backface_culling for model + nametag = "", -- by default empty, for players their name is shown if empty + nametag_color = <color>, -- sets color of nametag as ColorSpec + infotext = "", -- by default empty, text to be shown when pointed at object + } + +## Entity definition (`register_entity`) + + { + -- Deprecated: Everything in object properties is read directly from here + + initial_properties = --[[<initial object properties>]], + + on_activate = function(self, staticdata, dtime_s), + on_step = function(self, dtime), + on_punch = function(self, puncher, time_from_last_punch, tool_capabilities, dir), + on_rightclick = function(self, clicker), + get_staticdata = function(self), + -- ^ Called sometimes; the string returned is passed to on_activate when + -- the entity is re-activated from static state + + -- Also you can define arbitrary member variables here (see item definition for + -- more info) + _custom_field = whatever, + } + +### ABM (ActiveBlockModifier) definition (`register_abm`) + + { + label = "Lava cooling", + -- ^ Descriptive label for profiling purposes (optional). + -- Definitions with identical labels will be listed as one. + -- In the following two fields, also group:groupname will work. + nodenames = {"default:lava_source"}, + neighbors = {"default:water_source", "default:water_flowing"}, -- Any of these --[[ + ^ If left out or empty, any neighbor will do ]] + interval = 1.0, -- Operation interval in seconds + chance = 1, -- Chance of trigger per-node per-interval is 1.0 / this + catch_up = true, -- If true, catch-up behaviour is enabled --[[ + ^ The chance value is temporarily reduced when returning to + an area to simulate time lost by the area being unattended. + ^ Note chance value can often be reduced to 1 ]] + action = func(pos, node, active_object_count, active_object_count_wider), + } + +### LBM (LoadingBlockModifier) definition (`register_lbm`) + + { + label = "Upgrade legacy doors", + -- ^ Descriptive label for profiling purposes (optional). + -- Definitions with identical labels will be listed as one. + name = "modname:replace_legacy_door", + nodenames = {"default:lava_source"}, + -- ^ List of node names to trigger the LBM on. + -- Also non-registered nodes will work. + -- Groups (as of group:groupname) will work as well. + run_at_every_load = false, + -- ^ Whether to run the LBM's action every time a block gets loaded, + -- and not just for blocks that were saved last time before LBMs were + -- introduced to the world. + action = func(pos, node), + } + +## Item definition (`register_node`, `register_craftitem`, `register_tool`) + + { + description = "Steel Axe", + groups = {}, -- key = name, value = rating; rating = 1..3. + if rating not applicable, use 1. + e.g. {wool = 1, fluffy = 3} + {soil = 2, outerspace = 1, crumbly = 1} + {bendy = 2, snappy = 1}, + {hard = 1, metal = 1, spikes = 1} + inventory_image = "default_tool_steelaxe.png", + wield_image = "", + palette = "", + --[[ + ^ An image file containing the palette of a node. + ^ You can set the currently used color as the + ^ "palette_index" field of the item stack metadata. + ^ The palette is always stretched to fit indices + ^ between 0 and 255, to ensure compatibility with + ^ "colorfacedir" and "colorwallmounted" nodes. + ]] + color = "0xFFFFFFFF", + --[[ + ^ The color of the item. The palette overrides this. + ]] + wield_scale = {x = 1, y = 1, z = 1}, + stack_max = 99, + range = 4.0, + liquids_pointable = false, + tool_capabilities = { + full_punch_interval = 1.0, + max_drop_level = 0, + groupcaps = { + -- For example: + choppy = {times = {[1] = 2.50, [2] = 1.40, [3] = 1.00}, uses = 20, maxlevel = 2}, + }, + damage_groups = {groupname = damage}, + }, + node_placement_prediction = nil, + --[[ + ^ If nil and item is node, prediction is made automatically + ^ If nil and item is not a node, no prediction is made + ^ If "" and item is anything, no prediction is made + ^ Otherwise should be name of node which the client immediately places + on ground when the player places the item. Server will always update + actual result to client in a short moment. + ]] + sound = { + breaks = "default_tool_break", -- tools only + place = --[[<SimpleSoundSpec>]], + }, + + on_place = func(itemstack, placer, pointed_thing), + --[[ + ^ Shall place item and return the leftover itemstack + ^ The placer may be any ObjectRef or nil. + ^ default: minetest.item_place ]] + on_secondary_use = func(itemstack, user, pointed_thing), + --[[ + ^ Same as on_place but called when pointing at nothing. + ^ The user may be any ObjectRef or nil. + ^ pointed_thing : always { type = "nothing" } + ]] + on_drop = func(itemstack, dropper, pos), + --[[ + ^ Shall drop item and return the leftover itemstack + ^ The dropper may be any ObjectRef or nil. + ^ default: minetest.item_drop ]] + on_use = func(itemstack, user, pointed_thing), + --[[ + ^ default: nil + ^ Function must return either nil if no item shall be removed from + inventory, or an itemstack to replace the original itemstack. + e.g. itemstack:take_item(); return itemstack + ^ Otherwise, the function is free to do what it wants. + ^ The user may be any ObjectRef or nil. + ^ The default functions handle regular use cases. + ]] + after_use = func(itemstack, user, node, digparams), + --[[ + ^ default: nil + ^ If defined, should return an itemstack and will be called instead of + wearing out the tool. If returns nil, does nothing. + If after_use doesn't exist, it is the same as: + function(itemstack, user, node, digparams) + itemstack:add_wear(digparams.wear) + return itemstack + end + ^ The user may be any ObjectRef or nil. + ]] + _custom_field = whatever, + --[[ + ^ Add your own custom fields. By convention, all custom field names + should start with `_` to avoid naming collisions with future engine + usage. + ]] + } + +### Tile definition +* `"image.png"` +* `{name="image.png", animation={Tile Animation definition}}` +* `{name="image.png", backface_culling=bool, tileable_vertical=bool, + tileable_horizontal=bool}` + * backface culling enabled by default for most nodes + * tileable flags are info for shaders, how they should treat texture + when displacement mapping is used + Directions are from the point of view of the tile texture, + not the node it's on +* `{name="image.png", color=ColorSpec}` + * the texture's color will be multiplied with this color. + * the tile's color overrides the owning node's color in all cases. +* deprecated, yet still supported field names: + * `image` (name) + +### Tile animation definition + + { + type = "vertical_frames", + aspect_w = 16, + -- ^ specify width of a frame in pixels + aspect_h = 16, + -- ^ specify height of a frame in pixels + length = 3.0, + -- ^ specify full loop length + } + + { + type = "sheet_2d", + frames_w = 5, + -- ^ specify width in number of frames + frames_h = 3, + -- ^ specify height in number of frames + frame_length = 0.5, + -- ^ specify length of a single frame + } + +## Node definition (`register_node`) + + { + -- <all fields allowed in item definitions>, + + drawtype = "normal", -- See "Node drawtypes" + visual_scale = 1.0, --[[ + ^ Supported for drawtypes "plantlike", "signlike", "torchlike", + ^ "firelike", "mesh". + ^ For plantlike and firelike, the image will start at the bottom of the + ^ node, for the other drawtypes the image will be centered on the node. + ^ Note that positioning for "torchlike" may still change. ]] + tiles = {tile definition 1, def2, def3, def4, def5, def6}, --[[ + ^ Textures of node; +Y, -Y, +X, -X, +Z, -Z (old field name: tile_images) + ^ List can be shortened to needed length ]] + overlay_tiles = {tile definition 1, def2, def3, def4, def5, def6}, --[[ + ^ Same as `tiles`, but these textures are drawn on top of the + ^ base tiles. You can use this to colorize only specific parts of + ^ your texture. If the texture name is an empty string, that + ^ overlay is not drawn. Since such tiles are drawn twice, it + ^ is not recommended to use overlays on very common nodes. + special_tiles = {tile definition 1, Tile definition 2}, --[[ + ^ Special textures of node; used rarely (old field name: special_materials) + ^ List can be shortened to needed length ]] + color = ColorSpec, --[[ + ^ The node's original color will be multiplied with this color. + ^ If the node has a palette, then this setting only has an effect + ^ in the inventory and on the wield item. ]] + use_texture_alpha = false, -- Use texture's alpha channel + palette = "palette.png", --[[ + ^ The node's `param2` is used to select a pixel from the image + ^ (pixels are arranged from left to right and from top to bottom). + ^ The node's color will be multiplied with the selected pixel's + ^ color. Tiles can override this behavior. + ^ Only when `paramtype2` supports palettes. ]] + post_effect_color = "green#0F", -- If player is inside node, see "ColorSpec" + paramtype = "none", -- See "Nodes" --[[ + ^ paramtype = "light" allows light to propagate from or through the node with light value + ^ falling by 1 per node. This line is essential for a light source node to spread its light. ]] + paramtype2 = "none", -- See "Nodes" + place_param2 = nil, -- Force value for param2 when player places node + is_ground_content = true, -- If false, the cave generator will not carve through this + sunlight_propagates = false, -- If true, sunlight will go infinitely through this + walkable = true, -- If true, objects collide with node + pointable = true, -- If true, can be pointed at + diggable = true, -- If false, can never be dug + climbable = false, -- If true, can be climbed on (ladder) + buildable_to = false, -- If true, placed nodes can replace this node + floodable = false, --[[ + ^ If true, liquids flow into and replace this node. + ^ Warning: making a liquid node 'floodable' does not work and may cause problems. ]] + liquidtype = "none", -- "none"/"source"/"flowing" + liquid_alternative_flowing = "", -- Flowing version of source liquid + liquid_alternative_source = "", -- Source version of flowing liquid + liquid_viscosity = 0, -- Higher viscosity = slower flow (max. 7) + liquid_renewable = true, --[[ + ^ If true, a new liquid source can be created by placing two or more sources nearby ]] + leveled = 0, --[[ + ^ Block contains level in param2. Value is default level, used for snow. + ^ Don't forget to use "leveled" type nodebox. ]] + liquid_range = 8, -- number of flowing nodes around source (max. 8) + drowning = 0, -- Player will take this amount of damage if no bubbles are left + light_source = 0, --[[ + ^ Amount of light emitted by node. + ^ To set the maximum (currently 14), use the value 'minetest.LIGHT_MAX'. + ^ A value outside the range 0 to minetest.LIGHT_MAX causes undefined behavior.]] + damage_per_second = 0, -- If player is inside node, this damage is caused + node_box = {type="regular"}, -- See "Node boxes" + connects_to = nodenames, --[[ + * Used for nodebox nodes with the type == "connected" + * Specifies to what neighboring nodes connections will be drawn + * e.g. `{"group:fence", "default:wood"}` or `"default:stone"` ]] + connect_sides = { "top", "bottom", "front", "left", "back", "right" }, --[[ + ^ Tells connected nodebox nodes to connect only to these sides of this node. ]] + mesh = "model", + selection_box = {type="regular"}, -- See "Node boxes" --[[ + ^ If drawtype "nodebox" is used and selection_box is nil, then node_box is used. ]] + legacy_facedir_simple = false, -- Support maps made in and before January 2012 + legacy_wallmounted = false, -- Support maps made in and before January 2012 + waving = 0, --[[ valid for mesh, nodebox, plantlike, allfaces_optional nodes + ^ 1 - wave node like plants (top of node moves, bottom is fixed) + ^ 2 - wave node like leaves (whole node moves side-to-side synchronously) + ^ caveats: not all models will properly wave + ^ plantlike drawtype nodes can only wave like plants + ^ allfaces_optional drawtype nodes can only wave like leaves --]] + sounds = { + footstep = <SimpleSoundSpec>, + dig = <SimpleSoundSpec>, -- "__group" = group-based sound (default) + dug = <SimpleSoundSpec>, + place = <SimpleSoundSpec>, + place_failed = <SimpleSoundSpec>, + }, + drop = "", -- Name of dropped node when dug. Default is the node itself. + -- Alternatively: + drop = { + max_items = 1, -- Maximum number of items to drop. + items = { -- Choose max_items randomly from this list. + { + items = {"foo:bar", "baz:frob"}, -- Items to drop. + rarity = 1, -- Probability of dropping is 1 / rarity. + }, + }, + }, + + on_construct = func(pos), --[[ + ^ Node constructor; called after adding node + ^ Can set up metadata and stuff like that + ^ Not called for bulk node placement (i.e. schematics and VoxelManip) + ^ default: nil ]] + on_destruct = func(pos), --[[ + ^ Node destructor; called before removing node + ^ Not called for bulk node placement (i.e. schematics and VoxelManip) + ^ default: nil ]] + after_destruct = func(pos, oldnode), --[[ + ^ Node destructor; called after removing node + ^ Not called for bulk node placement (i.e. schematics and VoxelManip) + ^ default: nil ]] + on_flood = func(pos, oldnode, newnode), --[[ + ^ Called when a liquid (newnode) is about to flood oldnode, if + ^ it has `floodable = true` in the nodedef. Not called for bulk + ^ node placement (i.e. schematics and VoxelManip) or air nodes. If + ^ return true the node is not flooded, but on_flood callback will + ^ most likely be called over and over again every liquid update + ^ interval. Default: nil. + ^ Warning: making a liquid node 'floodable' does not work and may cause problems. ]] + + after_place_node = func(pos, placer, itemstack, pointed_thing) --[[ + ^ Called after constructing node when node was placed using + minetest.item_place_node / minetest.place_node + ^ If return true no item is taken from itemstack + ^ default: nil ]] + after_dig_node = func(pos, oldnode, oldmetadata, digger), --[[ + ^ oldmetadata is in table format + ^ Called after destructing node when node was dug using + minetest.node_dig / minetest.dig_node + ^ default: nil ]] + can_dig = function(pos, [player]) --[[ + ^ returns true if node can be dug, or false if not + ^ default: nil ]] + + on_punch = func(pos, node, puncher, pointed_thing), --[[ + ^ default: minetest.node_punch + ^ By default: Calls minetest.register_on_punchnode callbacks ]] + on_rightclick = func(pos, node, clicker, itemstack, pointed_thing), --[[ + ^ default: nil + ^ if defined, itemstack will hold clicker's wielded item + ^ Shall return the leftover itemstack + ^ Note: pointed_thing can be nil, if a mod calls this function ]] + + on_dig = func(pos, node, digger), --[[ + ^ default: minetest.node_dig + ^ By default: checks privileges, wears out tool and removes node ]] + + on_timer = function(pos,elapsed), --[[ + ^ default: nil + ^ called by NodeTimers, see minetest.get_node_timer and NodeTimerRef + ^ elapsed is the total time passed since the timer was started + ^ return true to run the timer for another cycle with the same timeout value ]] + + on_receive_fields = func(pos, formname, fields, sender), --[[ + ^ fields = {name1 = value1, name2 = value2, ...} + ^ Called when an UI form (e.g. sign text input) returns data + ^ default: nil ]] + + allow_metadata_inventory_move = func(pos, from_list, from_index, + to_list, to_index, count, player), --[[ + ^ Called when a player wants to move items inside the inventory + ^ Return value: number of items allowed to move ]] + + allow_metadata_inventory_put = func(pos, listname, index, stack, player), --[[ + ^ Called when a player wants to put something into the inventory + ^ Return value: number of items allowed to put + ^ Return value: -1: Allow and don't modify item count in inventory ]] + + allow_metadata_inventory_take = func(pos, listname, index, stack, player), --[[ + ^ Called when a player wants to take something out of the inventory + ^ Return value: number of items allowed to take + ^ Return value: -1: Allow and don't modify item count in inventory ]] + + on_metadata_inventory_move = func(pos, from_list, from_index, + to_list, to_index, count, player), + on_metadata_inventory_put = func(pos, listname, index, stack, player), + on_metadata_inventory_take = func(pos, listname, index, stack, player), --[[ + ^ Called after the actual action has happened, according to what was allowed. + ^ No return value ]] + + on_blast = func(pos, intensity), --[[ + ^ intensity: 1.0 = mid range of regular TNT + ^ If defined, called when an explosion touches the node, instead of + removing the node ]] + } + +### Recipe for `register_craft` (shaped) + + { + output = 'default:pick_stone', + recipe = { + {'default:cobble', 'default:cobble', 'default:cobble'}, + {'', 'default:stick', ''}, + {'', 'default:stick', ''}, -- Also groups; e.g. 'group:crumbly' + }, + replacements = --[[<optional list of item pairs, + replace one input item with another item on crafting>]] + } + +### Recipe for `register_craft` (shapeless) + + { + type = "shapeless", + output = 'mushrooms:mushroom_stew', + recipe = { + "mushrooms:bowl", + "mushrooms:mushroom_brown", + "mushrooms:mushroom_red", + }, + replacements = --[[<optional list of item pairs, + replace one input item with another item on crafting>]] + } + +### Recipe for `register_craft` (tool repair) + + { + type = "toolrepair", + additional_wear = -0.02, + } + +### Recipe for `register_craft` (cooking) + + { + type = "cooking", + output = "default:glass", + recipe = "default:sand", + cooktime = 3, + } + +### Recipe for `register_craft` (furnace fuel) + + { + type = "fuel", + recipe = "default:leaves", + burntime = 1, + } + +### Ore definition (`register_ore`) + + { + ore_type = "scatter", -- See "Ore types" + ore = "default:stone_with_coal", + wherein = "default:stone", + -- ^ a list of nodenames is supported too + clust_scarcity = 8*8*8, + -- ^ Ore has a 1 out of clust_scarcity chance of spawning in a node + -- ^ This value should be *MUCH* higher than your intuition might tell you! + clust_num_ores = 8, + -- ^ Number of ores in a cluster + clust_size = 3, + -- ^ Size of the bounding box of the cluster + -- ^ In this example, there is a 3x3x3 cluster where 8 out of the 27 nodes are coal ore + y_min = -31000, + y_max = 64, + flags = "", + -- ^ Attributes for this ore generation + noise_threshold = 0.5, + -- ^ If noise is above this threshold, ore is placed. Not needed for a uniform distribution + noise_params = {offset=0, scale=1, spread={x=100, y=100, z=100}, seed=23, octaves=3, persist=0.70} + -- ^ NoiseParams structure describing the perlin noise used for ore distribution. + -- ^ Needed for sheet ore_type. Omit from scatter ore_type for a uniform ore distribution + random_factor = 1.0, + -- ^ Multiplier of the randomness contribution to the noise value at any + -- given point to decide if ore should be placed. Set to 0 for solid veins. + -- ^ This parameter is only valid for ore_type == "vein". + biomes = {"desert", "rainforest"} + -- ^ List of biomes in which this decoration occurs. Occurs in all biomes if this is omitted, + -- ^ and ignored if the Mapgen being used does not support biomes. + -- ^ Can be a list of (or a single) biome names, IDs, or definitions. + } + +### Biome definition (`register_biome`) + +**Note** +The Biome API is still in an experimental phase and subject to change. + + { + name = "tundra", + node_dust = "default:snow", + -- ^ Node dropped onto upper surface after all else is generated. + node_top = "default:dirt_with_snow", + depth_top = 1, + -- ^ Node forming surface layer of biome and thickness of this layer. + node_filler = "default:permafrost", + depth_filler = 3, + -- ^ Node forming lower layer of biome and thickness of this layer. + node_stone = "default:bluestone", + -- ^ Node that replaces all stone nodes between roughly y_min and y_max. + node_water_top = "default:ice", + depth_water_top = 10, + -- ^ Node forming a surface layer in seawater with the defined thickness. + node_water = "", + -- ^ Node that replaces all seawater nodes not in the defined surface layer. + node_river_water = "default:ice", + -- ^ Node that replaces river water in mapgens that use default:river_water. + node_riverbed = "default:gravel", + depth_riverbed = 2, + -- ^ Node placed under river water and thickness of this layer. + y_min = 1, + y_max = 31000, + -- ^ Lower and upper limits for biome. + -- ^ Because biome is not recalculated for every node in a node column + -- ^ some biome materials can exceed their limits, especially stone. + -- ^ For each node column in a mapchunk, biome is only recalculated at column + -- ^ top and at each of these surfaces: + -- ^ Ground below air, water below air, ground below water. + -- ^ The selected biome then stays in effect for all nodes below until + -- ^ column base or the next biome recalculation. + heat_point = 0, + humidity_point = 50, + -- ^ Characteristic average temperature and humidity for the biome. + -- ^ These values create 'biome points' on a voronoi diagram that has heat + -- ^ and humidity as axes. The resulting voronoi cells determine which + -- ^ heat/humidity points belong to which biome, and therefore determine + -- ^ the area and location of each biome in the world. + -- ^ The biome points need to be carefully and evenly spaced on the voronoi + -- ^ diagram to result in roughly equal size biomes. + -- ^ Heat and humidity have average values of 50, vary mostly between + -- ^ 0 and 100 but also often exceed these values. + -- ^ Heat is not in degrees celcius, both values are abstract. + } + +### Decoration definition (`register_decoration`) + + { + deco_type = "simple", -- See "Decoration types" + place_on = "default:dirt_with_grass", + -- ^ Node (or list of nodes) that the decoration can be placed on + sidelen = 8, + -- ^ Size of divisions made in the chunk being generated. + -- ^ If the chunk size is not evenly divisible by sidelen, sidelen is made equal to the chunk size. + fill_ratio = 0.02, + -- ^ Ratio of the area to be uniformly filled by the decoration. + -- ^ Used only if noise_params is not specified. + noise_params = {offset=0, scale=.45, spread={x=100, y=100, z=100}, seed=354, octaves=3, persist=0.7}, + -- ^ NoiseParams structure describing the perlin noise used for decoration distribution. + -- ^ The result of this is multiplied by the 2d area of the division being decorated. + biomes = {"Oceanside", "Hills", "Plains"}, + -- ^ List of biomes in which this decoration occurs. Occurs in all biomes if this is omitted, + -- ^ and ignored if the Mapgen being used does not support biomes. + -- ^ Can be a list of (or a single) biome names, IDs, or definitions. + y_min = -31000 + y_max = 31000 + -- ^ Minimum and maximum `y` positions these decorations can be generated at. + -- ^ This parameter refers to the `y` position of the decoration base, so + -- the actual maximum height would be `height_max + size.Y`. + spawn_by = "default:water", + -- ^ Node (or list of nodes) that the decoration only spawns next to. + -- ^ Checks two horizontal planes of neighbouring nodes (including diagonal neighbours), + -- ^ one plane at Y = surface and one plane at Y = surface = + 1. + num_spawn_by = 1, + -- ^ Number of spawn_by nodes that must be surrounding the decoration position to occur. + -- ^ If absent or -1, decorations occur next to any nodes. + flags = "liquid_surface, force_placement", + -- ^ Flags for all decoration types. + -- ^ "liquid_surface": Instead of placement on the highest solid surface + -- ^ in a mapchunk column, placement is on the highest liquid surface. + -- ^ Placement is disabled if solid nodes are found above the liquid surface. + -- ^ "force_placement": Nodes other than "air" and "ignore" are replaced by the decoration. + + ----- Simple-type parameters + decoration = "default:grass", + -- ^ The node name used as the decoration. + -- ^ If instead a list of strings, a randomly selected node from the list is placed as the decoration. + height = 1, + -- ^ Number of nodes high the decoration is made. + -- ^ If height_max is not 0, this is the lower bound of the randomly selected height. + height_max = 0, + -- ^ Number of nodes the decoration can be at maximum. + -- ^ If absent, the parameter 'height' is used as a constant. + param2 = 0, + -- ^ Param2 value of placed decoration node. + + ----- Schematic-type parameters + schematic = "foobar.mts", + -- ^ If schematic is a string, it is the filepath relative to the current working directory of the + -- ^ specified Minetest schematic file. + -- ^ - OR -, could be the ID of a previously registered schematic + -- ^ - OR -, could instead be a table containing two mandatory fields, size and data, + -- ^ and an optional table yslice_prob: + schematic = { + size = {x=4, y=6, z=4}, + data = { + {name="default:cobble", param1=255, param2=0}, + {name="default:dirt_with_grass", param1=255, param2=0}, + {name="ignore", param1=255, param2=0}, + {name="air", param1=255, param2=0}, + ... + }, + yslice_prob = { + {ypos=2, prob=128}, + {ypos=5, prob=64}, + ... + }, + }, + -- ^ See 'Schematic specifier' for details. + replacements = {["oldname"] = "convert_to", ...}, + flags = "place_center_x, place_center_y, place_center_z", + -- ^ Flags for schematic decorations. See 'Schematic attributes'. + rotation = "90" -- rotate schematic 90 degrees on placement + -- ^ Rotation can be "0", "90", "180", "270", or "random". + } + +### Chat command definition (`register_chatcommand`) + + { + params = "<name> <privilege>", -- Short parameter description + description = "Remove privilege from player", -- Full description + privs = {privs=true}, -- Require the "privs" privilege to run + func = function(name, param), -- Called when command is run. + -- Returns boolean success and text output. + } + +### Detached inventory callbacks + + { + allow_move = func(inv, from_list, from_index, to_list, to_index, count, player), + -- ^ Called when a player wants to move items inside the inventory + -- ^ Return value: number of items allowed to move + + allow_put = func(inv, listname, index, stack, player), + -- ^ Called when a player wants to put something into the inventory + -- ^ Return value: number of items allowed to put + -- ^ Return value: -1: Allow and don't modify item count in inventory + + allow_take = func(inv, listname, index, stack, player), + -- ^ Called when a player wants to take something out of the inventory + -- ^ Return value: number of items allowed to take + -- ^ Return value: -1: Allow and don't modify item count in inventory + + on_move = func(inv, from_list, from_index, to_list, to_index, count, player), + on_put = func(inv, listname, index, stack, player), + on_take = func(inv, listname, index, stack, player), + -- ^ Called after the actual action has happened, according to what was allowed. + -- ^ No return value + } + +### HUD Definition (`hud_add`, `hud_get`) + + { + hud_elem_type = "image", -- see HUD element types + -- ^ 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 + name = "<name>", + scale = {x=2, y=2}, + text = "<text>", + number = 2, + item = 3, + -- ^ Selected item in inventory. 0 for no item selected. + direction = 0, + -- ^ Direction: 0: left-right, 1: right-left, 2: top-bottom, 3: bottom-top + alignment = {x=0, y=0}, + -- ^ See "HUD Element Types" + offset = {x=0, y=0}, + -- ^ See "HUD Element Types" + size = { x=100, y=100 }, + -- ^ Size of element in pixels + } + +### 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) + playername = "singleplayer", + -- ^ optional, if specified spawns particle only on the player's client + 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 + attached = ObjectRef, + -- ^ attached: if defined, particle positions, velocities and accelerations + -- ^ are relative to this object's position and yaw. + vertical = false, + -- ^ vertical: if true faces player using y axis only + texture = "image.png", + -- ^ Uses texture (string) + playername = "singleplayer" + -- ^ Playername is optional, if specified spawns particle only on the player's client + } + +### `HTTPRequest` definition (`HTTPApiTable.fetch_async`, `HTTPApiTable.fetch_async`) + + { + url = "http://example.org", + timeout = 10, + -- ^ Timeout for connection in seconds. Default is 3 seconds. + post_data = "Raw POST request data string" OR { field1 = "data1", field2 = "data2" }, + -- ^ Optional, if specified a POST request with post_data is performed. + -- ^ Accepts both a string and a table. If a table is specified, encodes table + -- ^ as x-www-form-urlencoded key-value pairs. + -- ^ If post_data ist not specified, a GET request is performed instead. + user_agent = "ExampleUserAgent", + -- ^ Optional, if specified replaces the default minetest user agent with given string + extra_headers = { "Accept-Language: en-us", "Accept-Charset: utf-8" }, + -- ^ Optional, if specified adds additional headers to the HTTP request. You must make sure + -- ^ that the header strings follow HTTP specification ("Key: Value"). + multipart = boolean + -- ^ Optional, if true performs a multipart HTTP request. Default is false. + } + +### `HTTPRequestResult` definition (`HTTPApiTable.fetch` callback, `HTTPApiTable.fetch_async_get`) + + { + completed = true, + -- ^ If true, the request has finished (either succeeded, failed or timed out) + succeeded = true, + -- ^ If true, the request was succesful + timeout = false, + -- ^ If true, the request timed out + code = 200, + -- ^ HTTP status code + data = "response" + } |