diff options
| -rw-r--r-- | lua_api.dtxt2 | 4676 |
1 files changed, 0 insertions, 4676 deletions
diff --git a/lua_api.dtxt2 b/lua_api.dtxt2 deleted file mode 100644 index 975fd64..0000000 --- a/lua_api.dtxt2 +++ /dev/null @@ -1,4676 +0,0 @@ -# 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" - } |