diff options
Diffstat (limited to 'doc/lua_api.txt')
| -rw-r--r-- | doc/lua_api.txt | 7828 |
1 files changed, 0 insertions, 7828 deletions
diff --git a/doc/lua_api.txt b/doc/lua_api.txt deleted file mode 100644 index 86e8d6575..000000000 --- a/doc/lua_api.txt +++ /dev/null @@ -1,7828 +0,0 @@ -Minetest Lua Modding API Reference -================================== - -* More information at <http://www.minetest.net/> -* Developer Wiki: <http://dev.minetest.net/> -* (Unofficial) Minetest Modding Book by rubenwardy: <https://rubenwardy.com/minetest_modding_book/> - -Introduction ------------- - -Content and functionality can be added to Minetest using Lua scripting -in run-time loaded mods. - -A mod is a self-contained bunch of scripts, textures and other related -things, which 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, and to document it here. - -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`: `<build directory>` - * `$path_share`: `<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 can contain the following files: - -* `game.conf`, with the following keys: - * `name`: Required, human readable name e.g. `name = Minetest` - * `description`: Short description to be shown in the content tab - * `disallowed_mapgens = <comma-separated mapgens>` - e.g. `disallowed_mapgens = v5,v6,flat` - These mapgens are removed from the list of mapgens for the game. -* `minetest.conf`: - Used to set default settings when running this game. -* `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 advanced settings tab. -* If the game contains a folder called `textures` the server will load it as a - texturepack, overriding mod textures. - Any server texturepack will override mod textures and the game texturepack. - -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. - - - - -Mods -==== - -Mod load path -------------- - -Paths are relative to the directories listed in the [Paths] section above. - -* `games/<gameid>/mods/` -* `mods/` -* `worlds/<worldname>/worldmods/` - -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 and happens if the `<worldname>/game/` -directory exists. - -Mods should then be placed in `<worldname>/game/mods/`. - -Modpacks --------- - -Mods can be put in a subdirectory, if the parent directory, which otherwise -should be a mod, contains a file named `modpack.conf`. -The file is a key-value store of modpack details. - -* `name`: The modpack name. -* `description`: Description of mod to be shown in the Mods tab of the main - menu. - -Note: to support 0.4.x, please also create an empty modpack.txt file. - -Mod directory structure ------------------------ - - mods - ├── modname - │ ├── mod.conf - │ ├── screenshot.png - │ ├── settingtypes.txt - │ ├── init.lua - │ ├── models - │ ├── textures - │ │ ├── modname_stuff.png - │ │ └── modname_something_else.png - │ ├── sounds - │ ├── media - │ ├── locale - │ └── <custom data> - └── another - -### modname - -The location of this directory can be fetched by using -`minetest.get_modpath(modname)`. - -### mod.conf - -A `Settings` file that provides meta information about the mod. - -* `name`: The mod name. Allows Minetest to determine the mod name even if the - folder is wrongly named. -* `description`: Description of mod to be shown in the Mods tab of the main - menu. -* `depends`: A comma separated list of dependencies. These are mods that must be - loaded before this mod. -* `optional_depends`: A comma separated list of optional dependencies. - Like a dependency, but no error if the mod doesn't exist. - -Note: to support 0.4.x, please also provide depends.txt. - -### `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. - -### `depends.txt` - -**Deprecated:** you should use mod.conf instead. - -This file is used if there are no dependencies in mod.conf. - -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. This means that if the specified mod -is missing, it does not prevent this mod from being loaded. - -### `description.txt` - -**Deprecated:** you should use mod.conf instead. - -This file is used if there is no description in mod.conf. - -A file containing a description to be shown in the Mods tab of the main menu. - -### `settingtypes.txt` - -The format is documented in `builtin/settingtypes.txt`. -It is parsed by the main menu settings dialogue to list mod-specific -settings 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. - -### `locale` - -Translation files for the clients. (See [Translations]) - -Naming conventions ------------------- - -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. - -Registered names can be overridden by prefixing the name with `:`. This can -be used for overriding the registrations of some other mod. - -The `:` prefix can also be used for maintaining backwards compatibility. - -### Example - -In the mod `experimental`, there is the ideal item/node/entity name `tnt`. -So the name should be `experimental:tnt`. - -Any mod can redefine `experimental:tnt` by using the name - - :experimental:tnt - -when registering it. That mod is required to have `experimental` as a -dependency. - - - - -Aliases -======= - -Aliases of itemnames can be added by using -`minetest.register_alias(alias, original_name)` or -`minetest.register_alias_force(alias, original_name)`. - -This adds an alias `alias` for the item called `original_name`. -From now on, you can use `alias` to refer to the item `original_name`. - -The only difference between `minetest.register_alias` and -`minetest.register_alias_force` is that if an item named `alias` already 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 also set 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`. - -Mapgen aliases --------------- - -In a game, a certain number of these must be set to tell core mapgens which -of the game's nodes are to be used for core mapgen generation. For example: - - minetest.register_alias("mapgen_stone", "default:stone") - -### Aliases for non-V6 mapgens - -#### Essential aliases - -* mapgen_stone -* mapgen_water_source -* mapgen_river_water_source - -`mapgen_river_water_source` is required for mapgens with sloping rivers where -it is necessary to have a river liquid node with a short `liquid_range` and -`liquid_renewable = false` to avoid flooding. - -#### Optional aliases - -* mapgen_lava_source - -Fallback lava node used if cave liquids are not defined in biome definitions. -Deprecated for non-V6 mapgens, define cave liquids in biome definitions instead. - -* mapgen_cobble - -Fallback node used if dungeon nodes are not defined in biome definitions. -Deprecated for non-V6 mapgens, define dungeon nodes in biome definitions instead. - -### Aliases needed for Mapgen V6 - -* mapgen_stone -* mapgen_water_source -* mapgen_lava_source -* mapgen_dirt -* mapgen_dirt_with_grass -* mapgen_sand -* mapgen_gravel -* mapgen_desert_stone -* mapgen_desert_sand -* mapgen_dirt_with_snow -* mapgen_snowblock -* mapgen_snow -* mapgen_ice - -* mapgen_tree -* mapgen_leaves -* mapgen_apple -* mapgen_jungletree -* mapgen_jungleleaves -* mapgen_junglegrass -* mapgen_pine_tree -* mapgen_pine_needles - -* mapgen_cobble -* mapgen_stair_cobble -* mapgen_mossycobble -* mapgen_stair_desert_stone - -### Setting the node used in Mapgen Singlenode - -By default the world is filled with air nodes. To set a different node use, for -example: - - minetest.register_alias("mapgen_singlenode", "default:stone") - - - - -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 overlaid 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 - -* `[crack:<n>:<p>` -* `[cracko:<n>:<p>` -* `[crack:<t>:<n>:<p>` -* `[cracko:<t>:<n>:<p>` - -Parameters: - -* `<t>`: tile count (in each direction) -* `<n>`: animation frame count -* `<p>`: current animation frame - -Draw a step of the crack animation on the texture. -`crack` draws it normally, while `cracko` lays it over, keeping transparent -pixels intact. - -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 (transparent) and 255 (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 method. 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) x 4 (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 `paramtype2`: - -* `paramtype2 = "color"` for nodes which use their full `param2` for - palette indexing. These nodes can have 256 different colors. - The palette should contain 256 pixels. -* `paramtype2 = "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` - paramtype2. 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. -* `paramtype2 = "colorfacedir"` for nodes which use the first - three bits of `param2` for palette indexing. The remaining - five bits are describing rotation, as in `facedir` paramtype2. - 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 paramtype2). - -### Conversion between nodes in the inventory and 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, it is -automatically transferred between node and item forms by the engine, -when a player digs or places a colored node. -You can disable this feature by setting the `drop` field of the node -to itself (without metadata). -To transfer the color to a special drop, you need a drop table. - -Example: - - minetest.register_node("mod:stone", { - description = "Stone", - tiles = {"default_stone.png"}, - paramtype2 = "color", - palette = "palette.png", - drop = { - items = { - -- assume that mod:cobblestone also has the same palette - {items = {"mod:cobblestone"}, inherit_color = true }, - } - } - }) - -### Colored items in craft recipes - -Craft recipes only support item strings, but fortunately item strings -can also contain metadata. Example craft recipe registration: - - minetest.register_craft({ - output = minetest.itemstring_with_palette("wool:block", 3), - type = "shapeless", - recipe = { - "wool:block", - "dye:red", - }, - }) - -To set the `color` field, you can use `minetest.itemstring_with_color`. - -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. - -For inventory and wield images you can specify overlays which -hardware coloring does not modify. You have to set `inventory_overlay` -and `wield_overlay` fields to an image name. - -To define a node 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 - pitch = 1.0, -- default - } - -- 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 - pitch = 1.0, -- default - } - -- Play locationless to one player, looped - { - to_player = name, - gain = 1.0, -- default - loop = true, - } - -- Play at 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, - } - -- Play at a location, heard by anyone *but* the given player - { - pos = {x = 32, y = 0, z = 100}, - max_hear_distance = 40, - exclude_player = name, - } - -Looped sounds must either be connected to an object or played locationless to -one player using `to_player = name`. - -A positional sound will only be heard by players that are within -`max_hear_distance` of the sound position, at the start of the sound. - -`exclude_player = name` can be applied to locationless, positional and object- -bound sounds to exclude a single player from hearing them. - -`SimpleSoundSpec` ------------------ - -Specifies a sound name, gain (=volume) and pitch. -This is either a string or a table. - -In string form, you just specify the sound name or -the empty string for no sound. - -Table form has the following fields: - -* `name`: Sound name -* `gain`: Volume (`1.0` = 100%) -* `pitch`: Pitch (`1.0` = 100%) - -`gain` and `pitch` are optional and default to `1.0`. - -Examples: - -* `""`: No sound -* `{}`: No sound -* `"default_place_node"`: Play e.g. `default_place_node.ogg` -* `{name = "default_place_node"}`: Same as above -* `{name = "default_place_node", gain = 0.5}`: 50% volume -* `{name = "default_place_node", gain = 0.9, pitch = 1.1}`: 90% volume, 110% pitch - -Special sound files -------------------- - -These sound files are played back by the engine if provided. - - * `player_damage`: Played when the local player takes damage (gain = 0.5) - * `player_falling_damage`: Played when the local player takes - damage by falling (gain = 0.5) - * `default_dig_<groupname>`: Default node digging sound - (see node sound definition for details) - -Registered definitions -====================== - -Anything added using certain [Registration functions] gets added to one or more -of the global [Registered definition tables]. - -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: - -All nodes register with `minetest.register_node` get added to the table -`minetest.registered_nodes`. - -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") - - - - -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 using - - minetest.registered_nodes[node.name] - -See [Registered definitions]. - -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. - -Node paramtypes ---------------- - -The functions of `param1` and `param2` are determined by certain fields in the -node definition. - -The function of `param1` is determined by `paramtype` in 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. - * Required by a light source node to enable spreading its light. - * Required by the following drawtypes as they determine their visual - brightness from their internal light value: - * torchlike - * signlike - * firelike - * fencelike - * raillike - * nodebox - * mesh - * plantlike - * plantlike_rooted -* `paramtype = "none"` - * `param1` will not be used by the engine and can be used to store - an arbitrary value - -The function of `param2` is determined by `paramtype2` in node definition. -`param2` is reserved for the engine when `paramtype2 != "none"`. - -* `paramtype2 = "flowingliquid"` - * Used by `drawtype = "flowingliquid"` and `liquidtype = "flowing"` - * The liquid level and a flag of the liquid are stored in `param2` - * Bits 0-2: Liquid level (0-7). The higher, the more liquid is in this node - * Bit 3: If set, liquid is flowing downwards (no graphical effect) -* `paramtype2 = "wallmounted"` - * Supported drawtypes: "torchlike", "signlike", "normal", "nodebox", "mesh" - * The rotation of the node is stored in `param2` - * You can make this value by using `minetest.dir_to_wallmounted()` - * Values range 0 - 5 - * The value denotes at which direction the node is "mounted": - 0 = y+, 1 = y-, 2 = x+, 3 = x-, 4 = z+, 5 = z- -* `paramtype2 = "facedir"` - * Supported drawtypes: "normal", "nodebox", "mesh" - * 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"` - * Only valid for "nodebox" with 'type = "leveled"', and "plantlike_rooted". - * Leveled nodebox: - * The level of the top face of the nodebox is stored in `param2`. - * The other faces are defined by 'fixed = {}' like 'type = "fixed"' - nodeboxes. - * The nodebox height is (`param2` / 64) nodes. - * The maximum accepted value of `param2` is 127. - * Rooted plantlike: - * The height of the 'plantlike' section is stored in `param2`. - * The height is (`param2` / 16) nodes. -* `paramtype2 = "degrotate"` - * Only valid for "plantlike" drawtype. The rotation of the node is stored in - `param2`. - * Values range 0 - 179. The value stored in `param2` is multiplied by two to - get the actual rotation in degrees of the node. -* `paramtype2 = "meshoptions"` - * Only valid for "plantlike" drawtype. 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` values 0-63 define 64 levels of internal liquid, 0 being empty - and 63 being full. - * Liquid texture is defined using `special_tiles = {"modname_tilename.png"}` -* `paramtype2 = "none"` - * `param2` will not be used by the engine and can be used to store - an arbitrary value - -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` - * A node-sized cube. -* `airlike` - * Invisible, uses no texture. -* `liquid` - * The cubic source node for a liquid. -* `flowingliquid` - * The flowing version of a liquid, appears with various heights and slopes. -* `glasslike` - * Often used for partially-transparent nodes. - * Only external sides of textures are visible. -* `glasslike_framed` - * All face-connected nodes are drawn as one volume within a surrounding - frame. - * The frame appearance is generated from the edges of the first texture - specified in `tiles`. The width of the edges used are 1/16th of texture - size: 1 pixel for 16x16, 2 pixels for 32x32 etc. - * The glass 'shine' (or other desired detail) on each node face is supplied - by the second texture specified in `tiles`. -* `glasslike_framed_optional` - * This switches between the above 2 drawtypes according to the menu setting - 'Connected Glass'. -* `allfaces` - * Often used for partially-transparent nodes. - * External and internal sides of textures are visible. -* `allfaces_optional` - * Often used for leaves nodes. - * This switches between `normal`, `glasslike` and `allfaces` according to - the menu setting: Opaque Leaves / Simple Leaves / Fancy Leaves. - * With 'Simple Leaves' selected, the texture specified in `special_tiles` - is used instead, if present. This allows a visually thicker texture to be - used to compensate for how `glasslike` reduces visual thickness. -* `torchlike` - * A single vertical texture. - * If placed on top of a node, uses the first texture specified in `tiles`. - * If placed against the underside of a node, uses the second texture - specified in `tiles`. - * If placed on the side of a node, uses the third texture specified in - `tiles` and is perpendicular to that node. -* `signlike` - * A single texture parallel to, and mounted against, the top, underside or - side of a node. -* `plantlike` - * Two vertical and diagonal textures at right-angles to each other. - * See `paramtype2 = "meshoptions"` above for other options. -* `firelike` - * When above a flat surface, appears as 6 textures, the central 2 as - `plantlike` plus 4 more surrounding those. - * If not above a surface the central 2 do not appear, but the texture - appears against the faces of surrounding nodes if they are present. -* `fencelike` - * A 3D model suitable for a wooden fence. - * One placed node appears as a single vertical post. - * Adjacently-placed nodes cause horizontal bars to appear between them. -* `raillike` - * Often used for tracks for mining carts. - * Requires 4 textures to be specified in `tiles`, in order: Straight, - curved, t-junction, crossing. - * Each placed node automatically switches to a suitable rotated texture - determined by the adjacent `raillike` nodes, in order to create a - continuous track network. - * Becomes a sloping node if placed against stepped nodes. -* `nodebox` - * Often used for stairs and slabs. - * Allows defining nodes consisting of an arbitrary number of boxes. - * See [Node boxes] below for more information. -* `mesh` - * Uses models for nodes. - * Tiles should hold model materials textures. - * Only static meshes are implemented. - * For supported model formats see Irrlicht engine documentation. -* `plantlike_rooted` - * Enables underwater `plantlike` without air bubbles around the nodes. - * Consists of a base cube at the co-ordinates of the node plus a - `plantlike` extension above with a height of `param2 / 16` nodes. - * The `plantlike` extension visually passes through any nodes above the - base cube without affecting them. - * The base cube texture tiles are defined as normal, the `plantlike` - extension uses the defined special tile, for example: - `special_tiles = {{name = "default_papyrus.png", tileable_vertical = true}},` - -`*_optional` drawtypes need less rendering time if deactivated -(always client-side). - -Node boxes ----------- - -Node selection boxes are defined using "node boxes". - -A nodebox is defined as any of: - - { - -- A normal cube; the default in most things - type = "regular" - } - { - -- A fixed box (or boxes) (facedir param2 is used, if applicable) - type = "fixed", - fixed = box OR {box1, box2, ...} - } - { - -- A variable height box (or boxes) with the top face position defined - -- by the node parameter 'leveled = ', or if 'paramtype2 == "leveled"' - -- by param2. - -- Other faces are defined by 'fixed = {}' as with 'type = "fixed"'. - type = "leveled", - 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, ...} - -- The following `disconnected_*` boxes are the opposites of the - -- `connect_*` ones above, i.e. when a node has no suitable neighbour - -- on the respective side, the corresponding disconnected box is drawn. - disconnected_top = box OR {box1, box2, ...} - disconnected_bottom = box OR {box1, box2, ...} - disconnected_front = box OR {box1, box2, ...} - disconnected_left = box OR {box1, box2, ...} - disconnected_back = box OR {box1, box2, ...} - disconnected_right = box OR {box1, box2, ...} - disconnected = box OR {box1, box2, ...} -- when there is *no* neighbour - disconnected_sides = box OR {box1, box2, ...} -- when there are *no* - -- neighbours to the sides - } - -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}, - - - - -Map terminology and coordinates -=============================== - -Nodes, mapblocks, mapchunks ---------------------------- - -A 'node' is the fundamental cubic unit of a world and appears to a player as -roughly 1x1x1 meters in size. - -A 'mapblock' (often abbreviated to 'block') is 16x16x16 nodes and is the -fundamental region of a world that is stored in the world database, sent to -clients and handled by many parts of the engine. -'mapblock' is preferred terminology to 'block' to help avoid confusion with -'node', however 'block' often appears in the API. - -A 'mapchunk' (sometimes abbreviated to 'chunk') is usually 5x5x5 mapblocks -(80x80x80 nodes) and is the volume of world generated in one operation by -the map generator. -The size in mapblocks has been chosen to optimise map generation. - -Coordinates ------------ - -### Orientation of axes - -For node and mapblock coordinates, +X is East, +Y is up, +Z is North. - -### Node coordinates - -Almost all positions used in the API use node coordinates. - -### Mapblock coordinates - -Occasionally the API uses 'blockpos' which refers to mapblock coordinates that -specify a particular mapblock. -For example blockpos (0,0,0) specifies the mapblock that extends from -node position (0,0,0) to node position (15,15,15). - -#### Converting node position to the containing blockpos - -To calculate the blockpos of the mapblock that contains the node at 'nodepos', -for each axis: - -* blockpos = math.floor(nodepos / 16) - -#### Converting blockpos to min/max node positions - -To calculate the min/max node positions contained in the mapblock at 'blockpos', -for each axis: - -* Minimum: - nodepos = blockpos * 16 -* Maximum: - nodepos = blockpos * 16 + 15 - - - - -HUD -=== - -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 is a table -where `x` and `y` range from `-1` to `1`, with `0` being central. `-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! - -The `z_index` field specifies the order of HUD elements from back to front. -Lower z-index elements are displayed behind higher z-index elements. Elements -with same z-index are displayed in an arbitrary order. Default 0. -Supports negative values. - -Below are the specific uses for fields in each type; fields not listed for that -type are ignored. - -### `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 [Spatial Vectors]. - -`pointed_thing` ---------------- - -* `{type="nothing"}` -* `{type="node", under=pos, above=pos}` - * Indicates a pointed node selection box. - * `under` refers to the node position behind the pointed face. - * `above` refers to the node position in front of the pointed face. -* `{type="object", ref=ObjectRef}` - -Exact pointing location (currently only `Raycast` supports these fields): - -* `pointed_thing.intersection_point`: The absolute world coordinates of the - point on the selection box which is pointed at. May be in the selection box - if the pointer is in the box too. -* `pointed_thing.box_id`: The ID of the pointed selection box (counting starts - from 1). -* `pointed_thing.intersection_normal`: Unit vector, points outwards of the - selected selection box. This specifies which face is pointed at. - Is a null vector `{x = 0, y = 0, z = 0}` when the pointer is inside the - selection box. - - - - -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: Can be placed in the world's voxel grid -* Tool: Has a wear property but cannot be stacked. The default use action is to - dig nodes or hit objects according to its tool capabilities. -* Craftitem: Cannot dig nodes or be placed - -Amount and wear ---------------- - -All item stacks have an amount between 0 and 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 is used 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`. - -When an item must be passed to a function, it can usually be in any of -these formats. - -### 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. - - - - -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. Group ratings are integer values within the -range [-32767, 32767]. For example: - - -- Default dirt - groups = {crumbly=3, soil=1} - - -- A more special dirt-kind of thing - groups = {crumbly=2, soil=1, level=2, outerspace=1} - -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 --------------- - -The asterisk `(*)` after a group name describes that there is no engine -functionality bound to it, and implementation is left up as a suggestion -to games. - -### Node, item and tool groups - -* `not_in_creative_inventory`: (*) Special group for inventory mods to indicate - that the item should be hidden in item lists. - - -### Node-only groups - -* `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. -* `bouncy`: value is bounce speed in percent -* `connect_to_raillike`: makes nodes of raillike drawtype with same group value - connect to each other -* `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)` -* `falling_node`: if there is no walkable block under the node it will fall -* `float`: the node will not fall through liquids -* `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 - * See also: `leveldiff` in [Tools] -* `slippery`: Players and items will slide on the node. - Slipperiness rises steadily with `slippery` value, starting at 1. - - -### Tool-only groups - -* `disable_repair`: If set to 1 for a tool, it cannot be repaired using the - `"toolrepair"` crafting recipe - - -### `ObjectRef` groups - -* `immortal`: Skips all damage and breath handling for an object. This group - will also hide the integrated HUD status bars for players, and is - automatically set to all players when damage is disabled on the server. -* `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. - - - -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 -===== - -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`. -`leveldiff` is the difference of the tool's `maxlevel` `groupcaps` and the -node's `level` group. The node cannot be dug if `leveldiff` is less than zero. - -* `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 determine 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`. - - - - -Metadata -======== - -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: - - 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: - - local meta = stack:get_meta() - meta:set_string("key", "value") - print(dump(meta:to_table())) - - - - -Formspec -======== - -Formspec defines a menu. This supports inventories and some of the -typical widgets like buttons, checkboxes, text input fields, etc. -It is a string, with a somewhat strange format. - -A formspec is made out of formspec elements, which includes widgets -like buttons but also can be used to set stuff like background color. - -Many formspec elements have a `name`, which is a unique identifier which -is used when the server receives user input. You must not use the name -"quit" for formspec elements. - -Spaces and newlines can be inserted between the blocks, as is used in the -examples. - -Position and size units are inventory slots unless the new coordinate system -is enabled. `X` and `Y` position the formspec element relative to the top left -of the menu or container. `W` and `H` are its width and height values. - -If the new system is enabled, all elements have unified coordinates for all -elements with no padding or spacing in between. This is highly recommended -for new forms. See `real_coordinates[<bool>]` and `Migrating to Real -Coordinates`. - -Inventories with a `player:<name>` inventory location are only sent to the -player named `<name>`. - -When displaying text which can contain formspec code, e.g. text set by a player, -use `minetest.formspec_escape`. -For coloured text you can use `minetest.colorize`. - -Since formspec version 3, elements drawn in the order they are defined. All -background elements are drawn before all other elements. - -**WARNING**: do _not_ use a element name starting with `key_`; those names are -reserved to pass key press events to formspec! - -**WARNING**: Minetest allows you to add elements to every single formspec instance -using `player:set_formspec_prepend()`, which may be the reason backgrounds are -appearing when you don't expect them to, or why things are styled differently -to normal. See [`no_prepend[]`] and [Styling Formspecs]. - -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 --------- - -### `formspec_version[<version>]` - -* Set the formspec version to a certain number. If not specified, - version 1 is assumed. -* Must be specified before `size` element. -* Clients older than this version can neither show newer elements nor display - elements with new arguments correctly. -* Available since feature `formspec_version_element`. - -### `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>]` - -* Must be used after `size` element. -* Defines the position on the game window of the formspec's `anchor` point. -* For X and Y, 0.0 and 1.0 represent opposite edges of the game window, - for example: - * [0.0, 0.0] sets the position to the top left corner of the game window. - * [1.0, 1.0] sets the position to the bottom right of the game window. -* Defaults to the center of the game window [0.5, 0.5]. - -### `anchor[<X>,<Y>]` - -* Must be used after both `size` and `position` (if present) elements. -* Defines the location of the anchor point within the formspec. -* For X and Y, 0.0 and 1.0 represent opposite edges of the formspec, - for example: - * [0.0, 1.0] sets the anchor to the bottom left corner of the formspec. - * [1.0, 0.0] sets the anchor to the top right of the formspec. -* Defaults to the center of the formspec [0.5, 0.5]. - -* `position` and `anchor` elements need suitable values to avoid a formspec - extending off the game window due to particular game window sizes. - -### `no_prepend[]` - -* Must be used after the `size`, `position`, and `anchor` elements (if present). -* Disables player:set_formspec_prepend() from applying to this formspec. - -### `real_coordinates[<bool>]` - -* INFORMATION: Enable it automatically using `formspec_version` version 2 or newer. -* When set to true, all following formspec elements will use the new coordinate system. -* If used immediately after `size`, `position`, `anchor`, and `no_prepend` elements - (if present), the form size will use the new coordinate system. -* **Note**: Formspec prepends are not affected by the coordinates in the main form. - They must enable it explicitly. -* For information on converting forms to the new coordinate system, see `Migrating - to Real Coordinates`. - -### `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 if it has been sent to the client. Nothing will - be shown if the inventory list is of size 0. -* **Note**: With the new coordinate system, the spacing between inventory - slots is one-fourth the size of an inventory slot. - -### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]` - -* Show an inventory list if it has been sent to the client. Nothing will - be shown if the inventory list is of size 0. -* **Note**: With the new coordinate system, the spacing between inventory - slots is one-fourth the size of an inventory slot. - -### `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) - -### `tooltip[<X>,<Y>;<W>,<H>;<tooltip_text>;<bgcolor>;<fontcolor>]` - -* Adds tooltip for an area. Other tooltips will take priority when present. -* `bgcolor` tooltip background color as `ColorString` (optional) -* `fontcolor` tooltip font color as `ColorString` (optional) - -### `image[<X>,<Y>;<W>,<H>;<texture name>]` - -* Show an image - -### `animated_image[<X>,<Y>;<W>,<H>;<name>;<texture name>;<frame count>;<frame duration>;<frame start>]` - -* Show an animated image. The image is drawn like a "vertical_frames" tile - animation (See [Tile animation definition]), but uses a frame count/duration - for simplicity -* `name`: Element name to send when an event occurs. The event value is the index of the current frame. -* `texture name`: The image to use. -* `frame count`: The number of frames animating the image. -* `frame duration`: Milliseconds between each frame. `0` means the frames don't advance. -* `frame start` (Optional): The index of the frame to start on. Default `1`. - -### `item_image[<X>,<Y>;<W>,<H>;<item name>]` - -* Show an inventory image of registered item/node - -### `bgcolor[<bgcolor>;<fullscreen>;<fbgcolor>]` - -* Sets background color of formspec. -* `bgcolor` and `fbgcolor` (optional) are `ColorString`s, they define the color - of the non-fullscreen and the fullscreen background. -* `fullscreen` (optional) can be one of the following: - * `false`: Only the non-fullscreen background color is drawn. (default) - * `true`: Only the fullscreen background color is drawn. - * `both`: The non-fullscreen and the fullscreen background color are drawn. - * `neither`: No background color is drawn. -* Note: Leave a parameter empty to not modify the value. -* Note: `fbgcolor`, leaving parameters empty and values for `fullscreen` that - are not bools are only available since formspec version 3. - -### `background[<X>,<Y>;<W>,<H>;<texture name>]` - -* 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>]` - -* Example for formspec 8x4 in 16x resolution: - image shall be sized 8 times 16px times 4 times 16px -* If `auto_clip` is `true`, the background is clipped to the formspec size - (`x` and `y` are used as offset values, `w` and `h` are ignored) - -### `background9[<X>,<Y>;<W>,<H>;<texture name>;<auto_clip>;<middle>]` - -* 9-sliced background. See https://en.wikipedia.org/wiki/9-slice_scaling -* Middle is a rect which defines the middle of the 9-slice. - * `x` - The middle will be x pixels from all sides. - * `x,y` - The middle will be x pixels from the horizontal and y from the vertical. - * `x,y,x2,y2` - The middle will start at x,y, and end at x2, y2. Negative x2 and y2 values - will be added to the width and height of the texture, allowing it to be used as the - distance from the far end. - * All numbers in middle are integers. -* Example for formspec 8x4 in 16x resolution: - image shall be sized 8 times 16px times 4 times 16px -* If `auto_clip` is `true`, the background is clipped to the formspec size - (`x` and `y` are used as offset values, `w` and `h` are ignored) -* Available since formspec version 2 - -### `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. -* With the old coordinate system, fields are a set height, but will be vertically - centred on `H`. With the new coordinate system, `H` will modify the height. -* `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. -* With the old coordinate system, fields are a set height, but will be vertically - centred on `H`. With the new coordinate system, `H` will modify the height. -* `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 -* If the text overflows, a vertical scrollbar is added. -* If the name is empty, the textarea is read-only and - the background is not shown, which corresponds to a multi-line label. - -### `label[<X>,<Y>;<label>]` - -* The label formspec element displays the text set in `label` - at the specified position. -* **Note**: If the new coordinate system is enabled, labels are - positioned from the center of the text, not the top. -* The text is displayed directly without automatic line breaking, - so label should not be used for big text chunks. Newlines can be - used to make labels multiline. -* **Note**: With the new coordinate system, newlines are spaced with - half a coordinate. With the old system, newlines are spaced 2/5 of - an inventory slot. - -### `hypertext[<X>,<Y>;<W>,<H>;<name>;<text>]` -* Displays a static formatted text with hyperlinks. -* **Note**: This element is currently unstable and subject to change. -* `x`, `y`, `w` and `h` work as per field -* `name` is the name of the field as returned in fields to `on_receive_fields` in case of action in text. -* `text` is the formatted text using `Markup Language` described below. - -### `vertlabel[<X>,<Y>;<label>]` -* Textual label drawn vertically -* `label` is the text on the label -* **Note**: If the new coordinate system is enabled, vertlabels are - positioned from the center of the text, not the left. - -### `button[<X>,<Y>;<W>,<H>;<name>;<label>]` - -* Clickable button. When clicked, fields will be sent. -* With the old coordinate system, buttons are a set height, but will be vertically - centred on `H`. With the new coordinate system, `H` will modify the height. -* `label` is the text on the button - -### `image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]` - -* `texture name` is the filename of an image -* **Note**: Height is supported on both the old and new coordinate systems - for image_buttons. - -### `image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>;<noclip>;<drawborder>;<pressed texture name>]` - -* `texture name` is the filename of an image -* `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>]` - -* `item name` is the registered name of an item/node -* The item description will be used as the tooltip. This can be overridden with - a tooltip element. - -### `button_exit[<X>,<Y>;<W>,<H>;<name>;<label>]` - -* When clicked, fields will be sent and the form will quit. -* Same as `button` in all other respects. - -### `image_button_exit[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]` - -* When clicked, fields will be sent and the form will quit. -* Same as `image_button` in all other respects. - -### `textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>]` - -* Scrollable item list showing arbitrary text elements -* `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 -* `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: `core.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 of the tabheader -* *Note*: Width and height are automatically chosen with this syntax -* `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 - -### `tabheader[<X>,<Y>;<H>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]` - -* Show a tab**header** at specific position (ignores formsize) -* **Important note**: This syntax for tabheaders can only be used with the - new coordinate system. -* `X` and `Y`: position of the tabheader -* `H`: height of the tabheader. Width is automatically determined with this syntax. -* `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 - -### `tabheader[<X>,<Y>;<W>,<H>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]` - -* Show a tab**header** at specific position (ignores formsize) -* **Important note**: This syntax for tabheaders can only be used with the - new coordinate system. -* `X` and `Y`: position of the tabheader -* `W` and `H`: width and height of the tabheader -* `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 box -* `color` is color specified as a `ColorString`. - If the alpha component is left blank, the box will be semitransparent. - -### `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 the dropdown -* `W`: width of the dropdown. Height is automatically chosen with this syntax. -* Fieldname data is transferred to Lua -* Items to be shown in dropdown -* Index of currently selected dropdown item - -### `dropdown[<X>,<Y>;<W>,<H>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>]` - -* Show a dropdown field -* **Important note**: This syntax for dropdowns can only be used with the - new coordinate system. -* **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 the dropdown -* `W` and `H`: width and height of the 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 -* `name` fieldname data is transferred to Lua -* `label` to be shown left of checkbox -* `selected` (optional): `true`/`false` -* **Note**: If the new coordinate system is enabled, checkboxes are - positioned from the center of the checkbox, not the top. - -### `scrollbar[<X>,<Y>;<W>,<H>;<orientation>;<name>;<value>]` - -* Show a scrollbar using options defined by the previous `scrollbaroptions[]` -* 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) -* `orientation`: `vertical`/`horizontal` -* Fieldname data is transferred to Lua -* Value of this trackbar is set to (`0`-`1000`) by default -* See also `minetest.explode_scrollbar_event` - (main menu: `core.explode_scrollbar_event`). - -### `scrollbaroptions[opt1;opt2;...]` -* Sets options for all following `scrollbar[]` elements -* `min=<int>` - * Sets scrollbar minimum value, defaults to `0`. -* `max=<int>` - * Sets scrollbar maximum value, defaults to `1000`. - If the max is equal to the min, the scrollbar will be disabled. -* `smallstep=<int>` - * Sets scrollbar step value when the arrows are clicked or the mouse wheel is - scrolled. - * If this is set to a negative number, the value will be reset to `10`. -* `largestep=<int>` - * Sets scrollbar step value used by page up and page down. - * If this is set to a negative number, the value will be reset to `100`. -* `thumbsize=<int>` - * Sets size of the thumb on the scrollbar. Size is calculated in the number of - units the thumb spans out of the range of the scrollbar values. - * Example: If a scrollbar has a `min` of 1 and a `max` of 100, a thumbsize of 10 - would span a tenth of the scrollbar space. - * If this is set to zero or less, the value will be reset to `1`. -* `arrows=<show/hide/default>` - * Whether to show the arrow buttons on the scrollbar. `default` hides the arrows - when the scrollbar gets too small, but shows them otherwise. - -### `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[]` -* `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: `core.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). - -### `style[<name 1>,<name 2>,...;<prop1>;<prop2>;...]` - -* Set the style for the named element(s) `name`. -* Note: this **must** be before the element is defined. -* See [Styling Formspecs]. - - -### `style_type[<type 1>,<type 2>,...;<prop1>;<prop2>;...]` - -* Sets the style for all elements of type(s) `type` which appear after this element. -* See [Styling Formspecs]. - -Migrating to Real Coordinates ------------------------------ - -In the old system, positions included padding and spacing. Padding is a gap between -the formspec window edges and content, and spacing is the gaps between items. For -example, two `1x1` elements at `0,0` and `1,1` would have a spacing of `5/4` between them, -and a padding of `3/8` from the formspec edge. It may be easiest to recreate old layouts -in the new coordinate system from scratch. - -To recreate an old layout with padding, you'll need to pass the positions and sizes -through the following formula to re-introduce padding: - -``` -pos = (oldpos + 1)*spacing + padding -where - padding = 3/8 - spacing = 5/4 -``` - -You'll need to change the `size[]` tag like this: - -``` -size = (oldsize-1)*spacing + padding*2 + 1 -``` - -A few elements had random offsets in the old system. Here is a table which shows these -offsets when migrating: - -| Element | Position | Size | Notes -|---------|------------|---------|------- -| box | +0.3, +0.1 | 0, -0.4 | -| button | | | Buttons now support height, so set h = 2 * 15/13 * 0.35, and reposition if h ~= 15/13 * 0.35 before -| list | | | Spacing is now 0.25 for both directions, meaning lists will be taller in height -| label | 0, +0.3 | | The first line of text is now positioned centered exactly at the position specified - -Styling Formspecs ------------------ - -Formspec elements can be themed using the style elements: - - style[<name 1>,<name 2>,...;<prop1>;<prop2>;...] - style_type[<type 1>,<type 2>,...;<prop1>;<prop2>;...] - -Where a prop is: - - property_name=property_value - -A name/type can optionally be a comma separated list of names/types, like so: - - world_delete,world_create,world_configure - button,image_button - -For example: - - style_type[button;bgcolor=#006699] - style[world_delete;bgcolor=red;textcolor=yellow] - button[4,3.95;2.6,1;world_delete;Delete] - -Setting a property to nothing will reset it to the default value. For example: - - style_type[button;bgimg=button.png;bgimg_pressed=button_pressed.png;border=false] - style[btn_exit;bgimg=;bgimg_pressed=;border=;bgcolor=red] - - -### Supported Element Types - -Some types may inherit styles from parent types. - -* animated_image, inherits from image -* button -* button_exit, inherits from button -* checkbox -* scrollbar -* table -* textlist -* dropdown -* field -* pwdfield, inherits from field -* textarea -* label -* vertlabel, inherits from field -* image_button -* item_image_button -* tabheader - - -### Valid Properties - -* animated_image - * noclip - boolean, set to true to allow the element to exceed formspec bounds. -* box - * noclip - boolean, set to true to allow the element to exceed formspec bounds. - * Default to false in formspec_version version 3 or higher -* button, button_exit, image_button, item_image_button - * alpha - boolean, whether to draw alpha in bgimg. Default true. - * bgcolor - color, sets button tint. - * bgcolor_hovered - color when hovered. Defaults to a lighter bgcolor when not provided. - * bgcolor_pressed - color when pressed. Defaults to a darker bgcolor when not provided. - * bgimg - standard background image. Defaults to none. - * bgimg_hovered - background image when hovered. Defaults to bgimg when not provided. - * bgimg_middle - Makes the bgimg textures render in 9-sliced mode and defines the middle rect. - See background9[] documentation for more details - * bgimg_pressed - background image when pressed. Defaults to bgimg when not provided. - * border - boolean, draw border. Set to false to hide the bevelled button pane. Default true. - * noclip - boolean, set to true to allow the element to exceed formspec bounds. - * textcolor - color, default white. -* checkbox - * noclip - boolean, set to true to allow the element to exceed formspec bounds. -* scrollbar - * noclip - boolean, set to true to allow the element to exceed formspec bounds. -* table, textlist - * noclip - boolean, set to true to allow the element to exceed formspec bounds. -* dropdown - * noclip - boolean, set to true to allow the element to exceed formspec bounds. -* field, pwdfield, textarea - * border - set to false to hide the textbox background and border. Default true. - * noclip - boolean, set to true to allow the element to exceed formspec bounds. - * textcolor - color. Default white. -* image - * noclip - boolean, set to true to allow the element to exceed formspec bounds. - * Default to false in formspec_version version 3 or higher -* item_image - * noclip - boolean, set to true to allow the element to exceed formspec bounds. Default to false. -* label, vertlabel - * noclip - boolean, set to true to allow the element to exceed formspec bounds. -* image_button (additional properties) - * fgimg - standard image. Defaults to none. - * fgimg_hovered - image when hovered. Defaults to fgimg when not provided. - * fgimg_pressed - image when pressed. Defaults to fgimg when not provided. - * NOTE: The parameters of any given image_button will take precedence over fgimg/fgimg_pressed -* tabheader - * noclip - boolean, set to true to allow the element to exceed formspec bounds. - * textcolor - color. Default white. - -Markup Language ---------------- - -Markup language used in `hypertext[]` elements uses tags that look like HTML tags. -The markup language is currently unstable and subject to change. Use with caution. -Some tags can enclose text, they open with `<tagname>` and close with `</tagname>`. -Tags can have attributes, in that case, attributes are in the opening tag in -form of a key/value separated with equal signs. Attribute values should not be quoted. - -These are the technically basic tags but see below for usual tags. Base tags are: - -`<style color=... font=... size=...>...</style>` - -Changes the style of the text. - -* `color`: Text color. Given color is a `colorspec`. -* `size`: Text size. -* `font`: Text font (`mono` or `normal`). - -`<global background=... margin=... valign=... color=... hovercolor=... size=... font=... halign=... >` - -Sets global style. - -Global only styles: -* `background`: Text background, a `colorspec` or `none`. -* `margin`: Page margins in pixel. -* `valign`: Text vertical alignment (`top`, `middle`, `bottom`). - -Inheriting styles (affects child elements): -* `color`: Default text color. Given color is a `colorspec`. -* `hovercolor`: Color of <action> tags when mouse is over. -* `size`: Default text size. -* `font`: Default text font (`mono` or `normal`). -* `halign`: Default text horizontal alignment (`left`, `right`, `center`, `justify`). - -This tag needs to be placed only once as it changes the global settings of the -text. Anyway, if several tags are placed, each changed will be made in the order -tags appear. - -`<tag name=... color=... hovercolor=... font=... size=...>` - -Defines or redefines tag style. This can be used to define new tags. -* `name`: Name of the tag to define or change. -* `color`: Text color. Given color is a `colorspec`. -* `hovercolor`: Text color when element hovered (only for `action` tags). Given color is a `colorspec`. -* `size`: Text size. -* `font`: Text font (`mono` or `normal`). - -Following tags are the usual tags for text layout. They are defined by default. -Other tags can be added using `<tag ...>` tag. - -`<normal>...</normal>`: Normal size text - -`<big>...</big>`: Big text - -`<bigger>...</bigger>`: Bigger text - -`<center>...</center>`: Centered text - -`<left>...</left>`: Left-aligned text - -`<right>...</right>`: Right-aligned text - -`<justify>...</justify>`: Justified text - -`<mono>...</mono>`: Monospaced font - -`<b>...</b>`, `<i>...</i>`, `<u>...</u>`: Bold, italic, underline styles. - -`<action name=...>...</action>` - -Make that text a clickable text triggering an action. - -* `name`: Name of the action (mandatory). - -When clicked, the formspec is send to the server. The value of the text field -sent to `on_player_receive_fields` will be "action:" concatenated to the action -name. - -`<img name=... float=... width=... height=...>` - -Draws an image which is present in the client media cache. - -* `name`: Name of the texture (mandatory). -* `float`: If present, makes the image floating (`left` or `right`). -* `width`: Force image width instead of taking texture width. -* `height`: Force image height instead of taking texture height. - -If only width or height given, texture aspect is kept. - -`<item name=... float=... width=... height=... rotate=...>` - -Draws an item image. - -* `name`: Item string of the item to draw (mandatory). -* `float`: If present, makes the image floating (`left` or `right`). -* `width`: Item image width. -* `height`: Item image height. -* `rotate`: Rotate item image if set to `yes` or `X,Y,Z`. X, Y and Z being -rotation speeds in percent of standard speed (-1000 to 1000). Works only if -`inventory_items_animations` is set to true. -* `angle`: Angle in which the item image is shown. Value has `X,Y,Z` form. -X, Y and Z being angles around each three axes. Works only if -`inventory_items_animations` is set to true. - -Inventory -========= - -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 prediction -* `craftresult`: list containing the crafted output -* `hand`: list containing an override for the empty hand - * Is not created automatically, use `InvRef:set_size` - * Is only used to enhance the empty hand's tool capabilities - -Colors -====== - -`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 any of the following -forms: - -* 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` -* 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")` -* `minetest.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. -* `minetest.strip_foreground_colors(str)` - * Removes foreground colors added by `get_color_escape_sequence`. -* `minetest.strip_background_colors(str)` - * Removes background colors added by `get_background_escape_sequence`. -* `minetest.strip_colors(str)` - * Removes all color escape sequences. - - - - -Spatial Vectors -=============== -A spatial vector is similar to a position, but instead using -absolute world coordinates, it uses *relative* coordinates, relative to -no particular point. - -Internally, it is implemented as a table with the 3 fields -`x`, `y` and `z`. Example: `{x = 0, y = 1, z = 0}`. - -For the following functions, `v`, `v1`, `v2` are vectors, -`p1`, `p2` are positions: - -* `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 of `a`, `b`, `c` are defined numbers. -* `vector.direction(p1, p2)`: - * Returns a vector of length 1 with direction `p1` to `p2`. - * If `p1` and `p2` are identical, returns `{x = 0, y = 0, z = 0}`. -* `vector.distance(p1, p2)`: - * Returns zero or a positive number, the distance between `p1` and `p2`. -* `vector.length(v)`: - * Returns zero or a positive number, the length of vector `v`. -* `vector.normalize(v)`: - * Returns a vector of length 1 with direction of vector `v`. - * If `v` has zero length, returns `{x = 0, y = 0, z = 0}`. -* `vector.floor(v)`: - * Returns a vector, each dimension rounded down. -* `vector.round(v)`: - * Returns a vector, each dimension rounded to nearest integer. -* `vector.apply(v, func)`: - * Returns a vector where the function `func` has been applied to each - component. -* `vector.equals(v1, v2)`: - * Returns a boolean, `true` if the vectors are identical. -* `vector.sort(v1, v2)`: - * Returns in order minp, maxp vectors of the cuboid defined by `v1`, `v2`. -* `vector.angle(v1, v2)`: - * Returns the angle between `v1` and `v2` in radians. -* `vector.dot(v1, v2)` - * Returns the dot product of `v1` and `v2` -* `vector.cross(v1, v2)` - * Returns the cross product of `v1` and `v2` - -For the following functions `x` can be either a vector or a number: - -* `vector.add(v, x)`: - * Returns a vector. - * If `x` is a vector: Returns the sum of `v` and `x`. - * If `x` is a number: Adds `x` to each component of `v`. -* `vector.subtract(v, x)`: - * Returns a vector. - * If `x` is a vector: Returns the difference of `v` subtracted by `x`. - * If `x` is a number: Subtracts `x` from each component of `v`. -* `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)`: returns a string which makes `obj` - human-readable, handles reference loops. - * `obj`: arbitrary variable - * `name`: string, default: `"_"` - * `dumped`: table, default: `{}` -* `dump(obj, dumped)`: returns a string which makes `obj` human-readable - * `obj`: arbitrary variable - * `dumped`: table, default: `{}` -* `math.hypot(x, y)` - * Get the hypotenuse of a triangle with legs x and y. - Useful for distance calculation. -* `math.sign(x, tolerance)`: returns `-1`, `0` or `1` - * Get the sign of a number. - * tolerance: number, default: `0.0` - * If the absolute value of `x` is within the `tolerance` or `x` is NaN, - `0` is returned. -* `math.factorial(x)`: returns the factorial of `x` -* `string.split(str, separator, include_empty, max_splits, sep_is_pattern)` - * `separator`: string, default: `","` - * `include_empty`: boolean, default: `false` - * `max_splits`: number, if it's negative, splits aren't limited, - default: `-1` - * `sep_is_pattern`: boolean, it specifies whether separator is a plain - string or a pattern (regex), default: `false` - * e.g. `"a,b":split","` returns `{"a","b"}` -* `string:trim()`: returns the string without whitespace pre- and suffixes - * e.g. `"\n \t\tfoo bar\t ":trim()` returns `"foo bar"` -* `minetest.wrap_text(str, limit, as_table)`: returns a string or table - * Adds newlines to the string to keep it within the specified character - limit - * Note that the returned lines may be longer than the limit since it only - splits at word borders. - * `limit`: number, maximal amount of characters in one line - * `as_table`: boolean, if set to true, a table of lines instead of a string - is returned, default: `false` -* `minetest.pos_to_string(pos, decimal_places)`: returns string `"(X,Y,Z)"` - * `pos`: table {x=X, y=Y, z=Z} - * Converts the position `pos` to a human-readable, printable string - * `decimal_places`: number, if specified, the x, y and z values of - the position are rounded to the given decimal place. -* `minetest.string_to_pos(string)`: returns a position or `nil` - * Same but in reverse. - * If the string can't be parsed to a position, nothing is returned. -* `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.is_nan(arg)` - * returns true when the passed number represents NaN. -* `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` -* `table.indexof(list, val)`: returns the smallest numerical index containing - the value `val` in the table `list`. Non-numerical indices are ignored. - If `val` could not be found, `-1` is returned. `list` must not have - negative indices. -* `table.insert_all(table, other_table)`: - * Appends all values in `other_table` to `table` - uses `#table + 1` to - find new indices. -* `table.key_value_swap(t)`: returns a table with keys and values swapped - * If multiple keys in `t` map to the same value, the result is undefined. -* `table.shuffle(table, [from], [to], [random_func])`: - * Shuffles elements `from` to `to` in `table` in place - * `from` defaults to `1` - * `to` defaults to `#table` - * `random_func` defaults to `math.random`. This function receives two - integers as arguments and should return a random integer inclusively - between them. -* `minetest.pointed_thing_to_face_pos(placer, pointed_thing)`: returns a - position. - * returns the exact position on the surface of a pointed node -* `minetest.get_dig_params(groups, tool_capabilities)`: Simulates a tool - that digs a node. - Returns a table with the following fields: - * `diggable`: `true` if node can be dug, `false` otherwise. - * `time`: Time it would take to dig the node. - * `wear`: How much wear would be added to the tool. - `time` and `wear` are meaningless if node's not diggable - Parameters: - * `groups`: Table of the node groups of the node that would be dug - * `tool_capabilities`: Tool capabilities table of the tool -* `minetest.get_hit_params(groups, tool_capabilities [, time_from_last_punch])`: - Simulates an item that punches an object. - Returns a table with the following fields: - * `hp`: How much damage the punch would cause. - * `wear`: How much wear would be added to the tool. - Parameters: - * `groups`: Damage groups of the object - * `tool_capabilities`: Tool capabilities table of the item - * `time_from_last_punch`: time in seconds since last punch action - - - - -Translations -============ - -Texts can be translated client-side with the help of `minetest.translate` and -translation files. - -Translating a string --------------------- - -Two functions are provided to translate strings: `minetest.translate` and -`minetest.get_translator`. - -* `minetest.get_translator(textdomain)` is a simple wrapper around - `minetest.translate`, and `minetest.get_translator(textdomain)(str, ...)` is - equivalent to `minetest.translate(textdomain, str, ...)`. - It is intended to be used in the following way, so that it avoids verbose - repetitions of `minetest.translate`: - - local S = minetest.get_translator(textdomain) - S(str, ...) - - As an extra commodity, if `textdomain` is nil, it is assumed to be "" instead. - -* `minetest.translate(textdomain, str, ...)` translates the string `str` with - the given `textdomain` for disambiguation. The textdomain must match the - textdomain specified in the translation file in order to get the string - translated. This can be used so that a string is translated differently in - different contexts. - It is advised to use the name of the mod as textdomain whenever possible, to - avoid clashes with other mods. - This function must be given a number of arguments equal to the number of - arguments the translated string expects. - Arguments are literal strings -- they will not be translated, so if you want - them to be, they need to come as outputs of `minetest.translate` as well. - - For instance, suppose we want to translate "@1 Wool" with "@1" being replaced - by the translation of "Red". We can do the following: - - local S = minetest.get_translator() - S("@1 Wool", S("Red")) - - This will be displayed as "Red Wool" on old clients and on clients that do - not have localization enabled. However, if we have for instance a translation - file named `wool.fr.tr` containing the following: - - @1 Wool=Laine @1 - Red=Rouge - - this will be displayed as "Laine Rouge" on clients with a French locale. - -Operations on translated strings --------------------------------- - -The output of `minetest.translate` is a string, with escape sequences adding -additional information to that string so that it can be translated on the -different clients. In particular, you can't expect operations like string.length -to work on them like you would expect them to, or string.gsub to work in the -expected manner. However, string concatenation will still work as expected -(note that you should only use this for things like formspecs; do not translate -sentences by breaking them into parts; arguments should be used instead), and -operations such as `minetest.colorize` which are also concatenation. - -Translation file format ------------------------ - -A translation file has the suffix `.[lang].tr`, where `[lang]` is the language -it corresponds to. It must be put into the `locale` subdirectory of the mod. -The file should be a text file, with the following format: - -* Lines beginning with `# textdomain:` (the space is significant) can be used - to specify the text domain of all following translations in the file. -* All other empty lines or lines beginning with `#` are ignored. -* Other lines should be in the format `original=translated`. Both `original` - and `translated` can contain escape sequences beginning with `@` to insert - arguments, literal `@`, `=` or newline (See [Escapes] below). - There must be no extraneous whitespace around the `=` or at the beginning or - the end of the line. - -Escapes -------- - -Strings that need to be translated can contain several escapes, preceded by `@`. - -* `@@` acts as a literal `@`. -* `@n`, where `n` is a digit between 1 and 9, is an argument for the translated - string that will be inlined when translated. Due to how translations are - implemented, the original translation string **must** have its arguments in - increasing order, without gaps or repetitions, starting from 1. -* `@=` acts as a literal `=`. It is not required in strings given to - `minetest.translate`, but is in translation files to avoid being confused - with the `=` separating the original from the translation. -* `@\n` (where the `\n` is a literal newline) acts as a literal newline. - As with `@=`, this escape is not required in strings given to - `minetest.translate`, but is in translation files. -* `@n` acts as a literal newline as well. - - - - -Perlin noise -============ - -Perlin noise creates a continuously-varying value depending on the input values. -Usually in Minetest the input values are either 2D or 3D co-ordinates in nodes. -The result is used during map generation to create the terrain shape, vary heat -and humidity to distribute biomes, vary the density of decorations or vary the -structure of ores. - -Structure of perlin noise -------------------------- - -An 'octave' is a simple noise generator that outputs a value between -1 and 1. -The smooth wavy noise it generates has a single characteristic scale, almost -like a 'wavelength', so on its own does not create fine detail. -Due to this perlin noise combines several octaves to create variation on -multiple scales. Each additional octave has a smaller 'wavelength' than the -previous. - -This combination results in noise varying very roughly between -2.0 and 2.0 and -with an average value of 0.0, so `scale` and `offset` are then used to multiply -and offset the noise variation. - -The final perlin noise variation is created as follows: - -noise = offset + scale * (octave1 + - octave2 * persistence + - octave3 * persistence ^ 2 + - octave4 * persistence ^ 3 + - ...) - -Noise Parameters ----------------- - -Noise Parameters are commonly called `NoiseParams`. - -### `offset` - -After the multiplication by `scale` this is added to the result and is the final -step in creating the noise value. -Can be positive or negative. - -### `scale` - -Once all octaves have been combined, the result is multiplied by this. -Can be positive or negative. - -### `spread` - -For octave1, this is roughly the change of input value needed for a very large -variation in the noise value generated by octave1. It is almost like a -'wavelength' for the wavy noise variation. -Each additional octave has a 'wavelength' that is smaller than the previous -octave, to create finer detail. `spread` will therefore roughly be the typical -size of the largest structures in the final noise variation. - -`spread` is a vector with values for x, y, z to allow the noise variation to be -stretched or compressed in the desired axes. -Values are positive numbers. - -### `seed` - -This is a whole number that determines the entire pattern of the noise -variation. Altering it enables different noise patterns to be created. -With other parameters equal, different seeds produce different noise patterns -and identical seeds produce identical noise patterns. - -For this parameter you can randomly choose any whole number. Usually it is -preferable for this to be different from other seeds, but sometimes it is useful -to be able to create identical noise patterns. - -When used in mapgen this is actually a 'seed offset', it is added to the -'world seed' to create the seed used by the noise, to ensure the noise has a -different pattern in different worlds. - -### `octaves` - -The number of simple noise generators that are combined. -A whole number, 1 or more. -Each additional octave adds finer detail to the noise but also increases the -noise calculation load. -3 is a typical minimum for a high quality, complex and natural-looking noise -variation. 1 octave has a slight 'gridlike' appearence. - -Choose the number of octaves according to the `spread` and `lacunarity`, and the -size of the finest detail you require. For example: -if `spread` is 512 nodes, `lacunarity` is 2.0 and finest detail required is 16 -nodes, octaves will be 6 because the 'wavelengths' of the octaves will be -512, 256, 128, 64, 32, 16 nodes. -Warning: If the 'wavelength' of any octave falls below 1 an error will occur. - -### `persistence` - -Each additional octave has an amplitude that is the amplitude of the previous -octave multiplied by `persistence`, to reduce the amplitude of finer details, -as is often helpful and natural to do so. -Since this controls the balance of fine detail to large-scale detail -`persistence` can be thought of as the 'roughness' of the noise. - -A positive or negative non-zero number, often between 0.3 and 1.0. -A common medium value is 0.5, such that each octave has half the amplitude of -the previous octave. -This may need to be tuned when altering `lacunarity`; when doing so consider -that a common medium value is 1 / lacunarity. - -### `lacunarity` - -Each additional octave has a 'wavelength' that is the 'wavelength' of the -previous octave multiplied by 1 / lacunarity, to create finer detail. -'lacunarity' is often 2.0 so 'wavelength' often halves per octave. - -A positive number no smaller than 1.0. -Values below 2.0 create higher quality noise at the expense of requiring more -octaves to cover a paticular range of 'wavelengths'. - -### `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 with a slightly gridded -appearence. -If no flags are specified (or defaults is), 2D noise is eased and 3D noise is -not eased. -Easing a 3D noise significantly increases the noise calculation load, so use -with restraint. - -#### `absvalue` - -The absolute value of each octave's noise variation is used when combining the -octaves. The final perlin noise variation is created as follows: - -noise = offset + scale * (abs(octave1) + - abs(octave2) * persistence + - abs(octave3) * persistence ^ 2 + - abs(octave4) * persistence ^ 3 + - ...) - -### 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", - } - -For 2D noise the Z component of `spread` is still defined but is ignored. -A single noise parameter table can be used for 2D or 3D noise. - - - - -Ores -==== - -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 emanates 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 different 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, - lacunarity = 2.0, - flags = "eased", - }, - noise_threshold = 1.6 - -**WARNING**: Use this ore type *very* sparingly since it is ~200x more -computationally expensive than any other ore. - -### `stratum` - -Creates a single undulating ore stratum that is continuous across mapchunk -borders and horizontally spans the world. - -The 2D perlin noise described by `noise_params` defines the Y co-ordinate of -the stratum midpoint. The 2D perlin noise described by `np_stratum_thickness` -defines the stratum's vertical thickness (in units of nodes). Due to being -continuous across mapchunk borders the stratum's vertical thickness is -unlimited. - -If the noise parameter `noise_params` is omitted the ore will occur from y_min -to y_max in a simple horizontal stratum. - -A parameter `stratum_thickness` can be provided instead of the noise parameter -`np_stratum_thickness`, to create a constant thickness. - -Leaving out one or both noise parameters makes the ore generation less -intensive, useful when adding multiple strata. - -`y_min` and `y_max` define the limits of the ore generation and for performance -reasons should be set as close together as possible but without clipping the -stratum's Y variation. - -Each node in the stratum has a 1-in-`clust_scarcity` chance of being ore, so a -solid-ore stratum would require a `clust_scarcity` of 1. - -The parameters `clust_num_ores`, `clust_size`, `noise_threshold` and -`random_factor` are ignored by this ore type. - -Ore attributes --------------- - -See section [Flag Specifier Format]. - -Currently supported flags: -`puff_cliffs`, `puff_additive_composition`. - -### `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. - - - - -Schematics -========== - -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 field) -* The `yslice_prob` field is a table of {ypos, prob} slice tables. A slice table - sets the probability of a particular horizontal slice of the schematic being - placed. (optional field) - `ypos` = 0 for the lowest horizontal slice of a schematic. - The default of `prob` is 255. -* The `data` field is a flat table of MapNode tables making up the schematic, - in the order of `[z [y [x]]]`. (required field) - 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. - - - - -Lua Voxel Manipulator -===================== - -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 large areas of map -at once - for example, if only setting a 3x3x3 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. - -A recent simple test of setting cubic areas showed that `minetest.set_node()` -is faster than a VoxelManip for a 3x3x3 node cube or smaller. - -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()` etc. 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 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. For almost all uses these should be left out - or nil to use the default. - * `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`. - * `x`, `y` and `z` must be integers to avoid an incorrect index result. - * The position (x, y, z) is not checked for being inside the area volume, - being outside can cause an incorrect index result. - * Useful for things like `VoxelManip`, raw Schematic specifiers, - `PerlinNoiseMap:get2d`/`3dMap`, and so on. -* `indexp(p)`: same functionality as `index(x, y, z)` but takes a vector. - * As with `index(x, y, z)`, the components of `p` must be integers, and `p` - is not checked for being inside the area volume. -* `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 - -### Y stride and z stride of a flat array - -For a particular position in a voxel area, whose flat array index is known, -it is often useful to know the index of a neighboring or nearby position. -The table below shows the changes of index required for 1 node movements along -the axes in a voxel area: - - Movement Change of index - +x +1 - -x -1 - +y +ystride - -y -ystride - +z +zstride - -z -zstride - -If, for example: - - local area = VoxelArea:new{MinEdge = emin, MaxEdge = emax} - -The values of `ystride` and `zstride` can be obtained using `area.ystride` and -`area.zstride`. - - - - -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 within -the current chunk. To set the capture of positions of interest to be recorded -on generate, use `minetest.set_gen_notify()`. -For decorations, the returned positions are the ground surface 'place_on' -nodes, not the decorations themselves. A 'simple' type decoration is often 1 -node above the returned position and possibly displaced by 'place_offset_y'. - -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 as returned by `minetest.get_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, damage)` - * 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. - * `damage`: damage that will be done to entity. - * Can return `true` to prevent the default damage mechanism. -* `on_death(self, killer)` - * Called when the object dies. - * `killer`: an `ObjectRef` (can be `nil`) -* `on_rightclick(self, clicker)` -* `on_attach_child(self, child)` - * `child`: an `ObjectRef` of the child that attaches -* `on_detach_child(self, child)` - * `child`: an `ObjectRef` of the child that detaches -* `on_detach(self, parent)` - * `parent`: an `ObjectRef` (can be `nil`) from where it got detached - * This happens before the parent object is removed from the world -* `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 -============== - -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) - - - - -'minetest' namespace reference -============================== - -Utilities ---------- - -* `minetest.get_current_modname()`: returns the currently loading mod's name, - when 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, -- 0.4.7 - nodebox_as_selectionbox = true, -- 0.4.7 - get_all_craft_recipes_works = true, -- 0.4.7 - -- The transparency channel of textures can optionally be used on - -- nodes (0.4.7) - use_texture_alpha = true, - -- Tree and grass ABMs are no longer done from C++ (0.4.8) - no_legacy_abms = true, - -- Texture grouping is possible using parentheses (0.4.11) - texture_names_parens = true, - -- Unique Area ID for AreaStore:insert_area (0.4.14) - area_store_custom_ids = true, - -- add_entity supports passing initial staticdata to on_activate - -- (0.4.16) - add_entity_with_staticdata = true, - -- Chat messages are no longer predicted (0.4.16) - no_chat_message_prediction = true, - -- The transparency channel of textures can optionally be used on - -- objects (ie: players and lua entities) (5.0.0) - object_use_texture_alpha = true, - -- Object selectionbox is settable independently from collisionbox - -- (5.0.0) - object_independent_selectionbox = true, - -- Specifies whether binary data can be uploaded or downloaded using - -- the HTTP API (5.1.0) - httpfetch_binary_data = true, - -- Whether formspec_version[<version>] may be used (5.1.0) - formspec_version_element = true, - -- Whether AreaStore's IDs are kept on save/load (5.1.0) - area_store_persistent_ids = true, - -- Whether minetest.find_path is functional (5.2.0) - pathfinder_works = true, - } - -* `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)`: 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 - protocol_version = 32, -- protocol version used by client - formspec_version = 2, -- supported formspec version - -- 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.safe_file_write(path, content)`: returns boolean indicating success - * Replaces contents of file at path with new contents in a safe (atomic) - way. Use this instead of below code when writing e.g. database files: - `local f = io.open(path, "wb"); f:write(content); f:close()` -* `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 verifiable. Compatible forks will have a different name and - version entirely. To check for the presence of engine features, test - whether the functions exported by the wanted features exist. For example: - `if minetest.check_for_falling then ... end`. -* `minetest.sha1(data, [raw])`: returns the sha1 hash of data - * `data`: string of data to hash - * `raw`: return raw bytes instead of hex digits, default: false - -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! - -### Environment - -* `minetest.register_node(name, node definition)` -* `minetest.register_craftitem(name, item definition)` -* `minetest.register_tool(name, item 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=minetest.LIGHT_MAX})` -* `minetest.unregister_item(name)` - * Unregisters the item from the 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_entity(name, entity definition)` -* `minetest.register_abm(abm definition)` -* `minetest.register_lbm(lbm definition)` -* `minetest.register_alias(alias, original_name)` - * Also use this to set the 'mapgen aliases' needed in a game for the core - mapgens. See [Mapgen aliases] section above. -* `minetest.register_alias_force(alias, original_name)` -* `minetest.register_ore(ore definition)` - * Returns an integer object handle uniquely identifying the registered - ore on success. - * The order of ore registrations determines the order of ore generation. -* `minetest.register_biome(biome definition)` - * Returns an integer object handle uniquely identifying the registered - biome on success. To get the biome ID, use `minetest.get_biome_id`. -* `minetest.unregister_biome(name)` - * Unregisters the biome from the engine, and deletes the entry with key - `name` from `minetest.registered_biomes`. - * Warning: This alters the biome to biome ID correspondences, so any - decorations or ores using the 'biomes' field must afterwards be cleared - and re-registered. -* `minetest.register_decoration(decoration definition)` - * Returns an integer object handle uniquely identifying the registered - decoration on success. To get the decoration ID, use - `minetest.get_decoration_id`. - * The order of decoration registrations determines the order of decoration - generation. -* `minetest.register_schematic(schematic definition)` - * Returns an integer object handle uniquely identifying the registered - schematic on success. - * If the schematic is loaded from a file, the `name` field is set to the - filename. - * If the function is called when loading the mod, and `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. - * Warning: Clearing and re-registering biomes alters the biome to biome ID - correspondences, so any decorations or ores using the 'biomes' field must - afterwards be cleared and re-registered. -* `minetest.clear_registered_decorations()` - * Clears all decorations currently registered. -* `minetest.clear_registered_ores()` - * Clears all ores currently registered. -* `minetest.clear_registered_schematics()` - * Clears all schematics currently registered. - -### Gameplay - -* `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. - * Returns false if no erase candidate could be found, otherwise returns true. - * **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_chatcommand(cmd, chatcommand definition)` -* `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` can be a description or a definition table (see [Privilege - definition]). - * If it is a description, the priv will be granted to singleplayer and admin - by default. - * To allow players with `basic_privs` to grant, see the `basic_privs` - minetest.conf setting. -* `minetest.register_authentication_handler(authentication handler definition)` - * Registers an auth handler that overrides the builtin one. - * This function can be called by a single mod once only. - -Global callback registration functions --------------------------------------- - -Call these functions only at load time! - -* `minetest.register_globalstep(function(dtime))` - * Called every server step, usually interval of 0.1s -* `minetest.register_on_mods_loaded(function())` - * Called after mods have finished loading and before the media is cached or the - aliases handled. -* `minetest.register_on_shutdown(function())` - * 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(function(pos, newnode, placer, oldnode, itemstack, pointed_thing))` - * Called when a node has been placed - * If return `true` no item is taken from `itemstack` - * `placer` may be any valid ObjectRef or nil. - * **Not recommended**; use `on_construct` or `after_place_node` in node - definition whenever possible. -* `minetest.register_on_dignode(function(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(function(pos, node, puncher, pointed_thing))` - * Called when a node is punched -* `minetest.register_on_generated(function(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(function(ObjectRef))` - * Called after a new player has been created -* `minetest.register_on_punchplayer(function(player, hitter, time_from_last_punch, tool_capabilities, dir, damage))` - * Called when a player is punched - * Note: This callback is invoked even if the punched player is dead. - * `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(function(player, hp_change, reason), 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. - * `reason`: a PlayerHPChangeReason table. - * The `type` field will have one of the following values: - * `set_hp`: A mod or the engine called `set_hp` without - giving a type - use this for custom damage types. - * `punch`: Was punched. `reason.object` will hold the puncher, or nil if none. - * `fall` - * `node_damage`: `damage_per_second` from a neighbouring node. - `reason.node` will hold the node name or nil. - * `drown` - * `respawn` - * Any of the above types may have additional fields from mods. - * `reason.from` will be `mod` or `engine`. - * `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_dieplayer(function(ObjectRef, reason))` - * Called when a player dies - * `reason`: a PlayerHPChangeReason table, see register_on_player_hpchange -* `minetest.register_on_respawnplayer(function(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(function(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(function(ObjectRef))` - * Called when a player joins the game -* `minetest.register_on_leaveplayer(function(ObjectRef, timed_out))` - * Called when a player leaves the game - * `timed_out`: True for timeout, false for other reasons. -* `minetest.register_on_auth_fail(function(name, ip))` - * Called when a client attempts to log into an account but supplies the - wrong password. - * `ip`: The IP address of the client. - * `name`: The account the client attempted to log into. -* `minetest.register_on_cheat(function(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(function(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(function(player, formname, fields))` - * Called when the server received input from `player` in a formspec with - the given `formname`. Specifically, this is called on any of the - following events: - * a button was pressed, - * Enter was pressed while the focus was on a text field - * a checkbox was toggled, - * something was selecteed in a drop-down list, - * a different tab was selected, - * selection was changed in a textlist or table, - * an entry was double-clicked in a textlist or table, - * a scrollbar was moved, or - * the form was actively closed by the player. - * Fields are sent for formspec elements which define a field. `fields` - is a table containing each formspecs element value (as string), with - the `name` parameter as index for each. The value depends on the - formspec element type: - * `animated_image`: Returns the index of the current frame. - * `button` and variants: If pressed, contains the user-facing button - text as value. If not pressed, is `nil` - * `field`, `textarea` and variants: Text in the field - * `dropdown`: Text of selected item - * `tabheader`: Tab index, starting with `"1"` (only if tab changed) - * `checkbox`: `"true"` if checked, `"false"` if unchecked - * `textlist`: See `minetest.explode_textlist_event` - * `table`: See `minetest.explode_table_event` - * `scrollbar`: See `minetest.explode_scrollbar_event` - * Special case: `["quit"]="true"` is sent when the user actively - closed the form by mouse click, keypress or through a button_exit[] - element. - * Special case: `["key_enter"]="true"` is sent when the user pressed - the Enter key and the focus was either nowhere (causing the formspec - to be closed) or on a button. If the focus was on a text field, - additionally, the index `key_enter_field` contains the name of the - text field. See also: `field_close_on_enter`. - * Newest functions are called first - * If function returns `true`, remaining functions are not called -* `minetest.register_on_craft(function(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(function(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_allow_player_inventory_action(function(player, action, inventory, inventory_info))` - * Determinates how much of a stack may be taken, put or moved to a - player inventory. - * `player` (type `ObjectRef`) is the player who modified the inventory - `inventory` (type `InvRef`). - * List of possible `action` (string) values and their - `inventory_info` (table) contents: - * `move`: `{from_list=string, to_list=string, from_index=number, to_index=number, count=number}` - * `put`: `{listname=string, index=number, stack=ItemStack}` - * `take`: Same as `put` - * Return a numeric value to limit the amount of items to be taken, put or - moved. A value of `-1` for `take` will make the source stack infinite. -* `minetest.register_on_player_inventory_action(function(player, action, inventory, inventory_info))` - * Called after a take, put or move event from/to/in a player inventory - * Function arguments: see `minetest.register_allow_player_inventory_action` - * Does not accept or handle any return value. -* `minetest.register_on_protection_violation(function(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(function(hp_change, replace_with_item, itemstack, user, pointed_thing))` - * Called when an item is eaten, by `minetest.item_eat` - * Return `itemstack` to cancel the default item eat response (i.e.: hp increase). -* `minetest.register_on_priv_grant(function(name, granter, priv))` - * Called when `granter` grants the priv `priv` to `name`. - * Note that the callback will be called twice if it's done by a player, - once with granter being the player name, and again with granter being nil. -* `minetest.register_on_priv_revoke(function(name, revoker, priv))` - * Called when `revoker` revokes the priv `priv` from `name`. - * Note that the callback will be called twice if it's done by a player, - once with revoker being the player name, and again with revoker being nil. -* `minetest.register_can_bypass_userlimit(function(name, ip))` - * Called when `name` user connects with `ip`. - * Return `true` to by pass the player limit -* `minetest.register_on_modchannel_message(function(channel_name, sender, message))` - * Called when an incoming mod channel message is received - * You should have joined some channels to receive events. - * If message comes from a server mod, `sender` field is an empty string. - -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.string_to_privs(str[, delim])`: - * Converts string representation of privs into table form - * `delim`: String separating the privs. Defaults to `","`. - * Returns `{ priv1 = true, ... }` -* `minetest.privs_to_string(privs[, delim])`: - * Returns the string representation of `privs` - * `delim`: String to delimit privs. Defaults to `","`. -* `minetest.get_player_privs(name) -> {priv1=true,...}` -* `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.check_password_entry(name, entry, password)` - * Returns true if the "password entry" for a player with name matches given - password, false otherwise. - * The "password entry" is the password representation generated by the - engine as returned as part of a `get_auth()` call on the auth handler. - * Only use this function for making it possible to log in via password from - external protocols such as IRC, other uses 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.get_player_ip(name)`: returns an IP address string for the player - `name`. - * The player needs to be online for this to be successful. - -* `minetest.get_auth_handler()`: Return the currently active auth handler - * See the [Authentication handler definition] - * Use this to e.g. get the authentication data for a player: - `local auth_data = minetest.get_auth_handler().get_auth(playername)` -* `minetest.notify_authentication_modified(name)` - * Must be called by the authentication handler for privilege changes. - * `name`: string; if omitted, all auth data should be considered modified -* `minetest.set_player_password(name, password_hash)`: Set password hash of - player `name`. -* `minetest.set_player_privs(name, {priv1=true,...})`: Set privileges of player - `name`. -* `minetest.auth_reload()` - * See `reload()` in authentication handler definition - -`minetest.set_player_password`, `minetest.set_player_privs`, -`minetest.get_player_privs` and `minetest.auth_reload` call the authentication -handler. - -Chat ----- - -* `minetest.chat_send_all(text)` -* `minetest.chat_send_player(name, text)` -* `minetest.format_chat_message(name, message)` - * Used by the server to format a chat message, based on the setting `chat_message_format`. - Refer to the documentation of the setting for a list of valid placeholders. - * Takes player name and message, and returns the formatted string to be sent to players. - * Can be redefined by mods if required, for things like colored names or messages. - * **Only** the first occurrence of each placeholder will be replaced. - -Environment access ------------------- - -* `minetest.set_node(pos, node)` -* `minetest.add_node(pos, node)`: alias to `minetest.set_node` - * Set node at position `pos` - * `node`: table `{name=string, param1=number, param2=number}` - * If param1 or param2 is omitted, it's set to `0`. - * e.g. `minetest.set_node({x=0, y=10, z=0}, {name="default:wood"})` -* `minetest.bulk_set_node({pos1, pos2, pos3, ...}, node)` - * Set node on all positions set in the first argument. - * e.g. `minetest.bulk_set_node({{x=0, y=1, z=1}, {x=1, y=2, z=2}}, {name="default:stone"})` - * For node specification or position syntax see `minetest.set_node` call - * Faster than set_node due to single call, but still considerably slower - than Lua Voxel Manipulators (LVM) for large numbers of nodes. - Unlike LVMs, this will call node callbacks. It also allows setting nodes - in spread out positions which would cause LVMs to waste memory. - For setting a cube, this is 1.3x faster than set_node whereas LVM is 20 - times faster. -* `minetest.swap_node(pos, node)` - * Set node at position, but don't remove metadata -* `minetest.remove_node(pos)` - * By default it does the same as `minetest.set_node(pos, {name="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)`: returns a list of - ObjectRefs. - * `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. - * accounts 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(pos1, pos2, nodenames)`: returns a list of - positions. - * `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"` - * First return value: Table with all node positions - * Second return value: Table with the count of each node with the node name - as index. - * Area volume is limited to 4,096,000 nodes -* `minetest.find_nodes_in_area_under_air(pos1, pos2, nodenames)`: returns a - list of positions. - * `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"` - * Return value: Table with all node positions with a node air above - * Area volume is limited to 4,096,000 nodes -* `minetest.get_perlin(noiseparams)` -* `minetest.get_perlin(seeddiff, octaves, persistence, spread)` - * 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. -* `minetest.get_gen_notify()` - * Returns a flagstring and a table with the `deco_id`s. -* `minetest.get_decoration_id(decoration_name)` - * Returns the decoration ID number for the provided decoration name string, - or `nil` on failure. -* `minetest.get_mapgen_object(objectname)` - * Return requested mapgen object if available (see [Mapgen objects]) -* `minetest.get_heat(pos)` - * Returns the heat at the position, or `nil` on failure. -* `minetest.get_humidity(pos)` - * Returns the humidity at the position, or `nil` on failure. -* `minetest.get_biome_data(pos)` - * Returns a table containing: - * `biome` the biome id of the biome at that position - * `heat` the heat at the position - * `humidity` the humidity at the position - * Or returns `nil` on failure. -* `minetest.get_biome_id(biome_name)` - * Returns the biome id, as used in the biomemap Mapgen object and returned - by `minetest.get_biome_data(pos)`, for a given biome_name string. -* `minetest.get_biome_name(biome_id)` - * Returns the biome name string for the provided biome id, or `nil` on - failure. - * If no biomes have been registered, such as in mgv6, returns `default`. -* `minetest.get_mapgen_params()` - * Deprecated: use `minetest.get_mapgen_setting(name)` instead. - * Returns a table containing: - * `mgname` - * `seed` - * `chunksize` - * `water_level` - * `flags` -* `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` - * `chunksize` - * `water_level` - * `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.load_area(pos1[, pos2])` - * Load the mapblocks containing the area from `pos1` to `pos2`. - `pos2` defaults to `pos1` if not specified. - * This function does not trigger map generation. -* `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)`: returns `boolean, pos` - * Checks if there is anything other than air between pos1 and pos2. - * Returns false if something is blocking the sight. - * Returns the position of the blocking node when `false` - * `pos1`: First position - * `pos2`: Second position -* `minetest.raycast(pos1, pos2, objects, liquids)`: returns `Raycast` - * Creates a `Raycast` object. - * `pos1`: start of the ray - * `pos2`: end of the ray - * `objects`: if false, only nodes will be returned. Default is `true`. - * `liquids`: if false, liquid nodes won't be returned. Default is `false`. -* `minetest.find_path(pos1,pos2,searchdistance,max_jump,max_drop,algorithm)` - * returns table containing path that can be walked on - * returns a table of 3D points representing a path from `pos1` to `pos2` or - `nil` on failure. - * Reasons for failure: - * No path exists at all - * No path exists within `searchdistance` (see below) - * Start or end pos is buried in land - * `pos1`: start position - * `pos2`: end position - * `searchdistance`: maximum distance from the search positions to search in. - In detail: Path must be completely inside a cuboid. The minimum - `searchdistance` of 1 will confine search between `pos1` and `pos2`. - Larger values will increase the size of this cuboid in all directions - * `max_jump`: maximum height difference to consider walkable - * `max_drop`: maximum height difference to consider droppable - * `algorithm`: One of `"A*_noprefetch"` (default), `"A*"`, `"Dijkstra"`. - Difference between `"A*"` and `"A*_noprefetch"` is that - `"A*"` will pre-calculate the cost-data, the other will calculate it - on-the-fly -* `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. -* `minetest.get_spawn_level(x, z)` - * Returns a player spawn y co-ordinate for the provided (x, z) - co-ordinates, or `nil` for an unsuitable spawn point. - * For most mapgens a 'suitable spawn point' is one with y between - `water_level` and `water_level + 16`, and in mgv7 well away from rivers, - so `nil` will be returned for many (x, z) co-ordinates. - * The spawn level returned is for a player spawn in unmodified terrain. - * The spawn level is intentionally above terrain level to cope with - full-node biome 'dust' nodes. - -Mod channels ------------- - -You can find mod channels communication scheme in `doc/mod_channels.png`. - -* `minetest.mod_channel_join(channel_name)` - * Server joins channel `channel_name`, and creates it if necessary. You - should listen for incoming messages with - `minetest.register_on_modchannel_message` - -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.remove_detached_inventory(name)` - * Returns a `boolean` indicating whether the removal succeeded. -* `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)` - * Returns the position of a `pointed_thing` or `nil` if the `pointed_thing` - does not refer to a node or entity. - * If the optional `above` parameter is true and the `pointed_thing` refers - to a node, then it will return the `above` position of the `pointed_thing`. -* `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.is_colored_paramtype(ptype)` - * Returns a boolean. Returns `true` if the given `paramtype2` contains - color information (`color`, `colorwallmounted` or `colorfacedir`). -* `minetest.strip_param2_color(param2, paramtype2)` - * Removes everything but the color information from the - given `param2` value. - * Returns `nil` if the given `paramtype2` does not contain color - information. -* `minetest.get_node_drops(node, toolname)` - * Returns list of itemstrings that are dropped by `node` when dug - with `toolname`. - * `node`: node as table or node name - * `toolname`: name of the tool item (can be `nil`) -* `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 replacement `ItemStack`s that couldn't be - placed in `decremented_input.items`. Replacements can be placed in - `decremented_input` if the stack of the replaced item has a count of 1. - * `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]={method = "cooking", width = 3, output = "default:gold_ingot", - items = {1 = "default:gold_lump"}}, - [2]={method = "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) -* `minetest.itemstring_with_palette(item, palette_index)`: returns an item - string. - * Creates an item string which contains palette index information - for hardware colorization. You can use the returned string - as an output in a craft recipe. - * `item`: the item stack which becomes colored. Can be in string, - table and native form. - * `palette_index`: this index is added to the item stack -* `minetest.itemstring_with_color(item, colorstring)`: returns an item string - * Creates an item string which contains static color information - for hardware colorization. Use this method if you wish to colorize - an item that does not own a palette. You can use the returned string - as an output in a craft recipe. - * `item`: the item stack which becomes colored. Can be in string, - table and native form. - * `colorstring`: the new color of the item stack - -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_place` and `on_drop` item definition functions -------------------------------------------------------------------- - -* `minetest.item_place_node(itemstack, placer, pointed_thing[, param2, prevent_after_place])` - * Place item as a node - * `param2` overrides `facedir` and wallmounted `param2` - * `prevent_after_place`: if set to `true`, `after_place_node` is not called - for the newly placed node to prevent a callback and placement loop - * returns `itemstack, position` - * `position`: the location the node was placed to. `nil` if nothing was placed. -* `minetest.item_place_object(itemstack, placer, pointed_thing)` - * Place item as-is - * returns the leftover itemstack - * **Note**: This function is deprecated and will never be called. -* `minetest.item_place(itemstack, placer, pointed_thing[, param2])` - * Wrapper that calls `minetest.item_place_node` if appropriate - * 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, position` - * `position`: the location the node was placed to. `nil` if nothing was placed. -* `minetest.item_drop(itemstack, dropper, pos)` - * Drop the item - * returns the leftover itemstack -* `minetest.item_eat(hp_change[, replace_with_item])` - * Returns `function(itemstack, user, pointed_thing)` as a - function wrapper for `minetest.do_item_eat`. - * `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. - -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, [ephemeral])`: returns a handle - * `spec` is a `SimpleSoundSpec` - * `parameters` is a sound parameter table - * `ephemeral` is a boolean (default: false) - Ephemeral sounds will not return a handle and can't be stopped or faded. - It is recommend to use this for short sounds that happen in response to - player actions (e.g. door closing). -* `minetest.sound_stop(handle)` - * `handle` is a handle returned by `minetest.sound_play` -* `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(name, joined)` - * Returns the server status string when a player joins or when the command - `/status` is called. Returns `nil` or an empty string when the message is - disabled. - * `joined`: Boolean value, indicates whether the function was called when - a player joined. - * This function may be overwritten by mods to customize the status message. -* `minetest.get_server_uptime()`: returns the server uptime in seconds -* `minetest.remove_player(name)`: remove player from database (if they are not - connected). - * As auth data is not removed, minetest.player_exists will continue to - return true. Call the below method as well if you want to remove auth - data too. - * Returns a code (0: successful, 1: no such player, 2: player is connected) -* `minetest.remove_player_auth(name)`: remove player authentication data - * Returns boolean indicating success (false if player nonexistant) - -Bans ----- - -* `minetest.get_ban_list()`: returns a list of all bans formatted as string -* `minetest.get_ban_description(ip_or_name)`: returns list of bans matching - IP address or name formatted as string -* `minetest.ban_player(name)`: ban the IP of a currently connected player - * Returns boolean indicating success -* `minetest.unban_player_or_ip(ip_or_name)`: remove ban record matching - IP address or name -* `minetest.kick_player(name, [reason])`: disconnect a player with an optional - reason. - * Returns boolean indicating success (false if player nonexistant) - -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 and per-node force-place to the specified - nodes according to the `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 an integer value from `0` to `255` that encodes - probability and per-node force-place. Probability has levels - 0-127, then 128 may be added to encode per-node force-place. - For probability stated as 0-255, divide by 2 and round down to - get values 0-127, then add 128 to apply per-node force-place. - * 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. - * Apply the specified probability to the specified horizontal slices - according to the `slice_prob_list`. - * `slice_prob_list` is an array of tables containing two fields, `ypos` - and `prob`. - * `ypos` indicates the y position of the slice with a probability - applied, the lowest slice being `ypos = 0`. - * 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, flags)` - * 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. - * **Warning**: Once you have loaded a schematic from a file, it will be - cached. Future calls will always use the cached version and the - replacement list defined for it, regardless of whether the file or the - replacement list parameter have changed. The only way to load the file - anew is to restart the server. - * `flags` is a flag field with the available flags: - * place_center_x - * place_center_y - * place_center_z - -* `minetest.place_schematic_on_vmanip(vmanip, pos, schematic, rotation, replacement, force_placement, flags)`: - * This function is analogous to minetest.place_schematic, but places a - schematic onto the specified VoxelManip object `vmanip` instead of the - 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. - * `flags` is a flag field with the available flags: - * place_center_x - * place_center_y - * place_center_z - -* `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. - -* `minetest.read_schematic(schematic, options)` - * Returns a Lua table representing the schematic (see: [Schematic specifier]) - * `schematic` is the schematic to read (see: [Schematic specifier]) - * `options` is a table containing the following optional parameters: - * `write_yslice_prob`: string value: - * `none`: no `write_yslice_prob` table is inserted, - * `low`: only probabilities that are not 254 or 255 are written in - the `write_ylisce_prob` table, - * `all`: write all probabilities to the `write_yslice_prob` table. - * The default for this option is `all`. - * Any invalid value will be interpreted as `all`. - -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.get_connected_players()`: returns list of `ObjectRefs` -* `minetest.is_player(obj)`: boolean, whether `obj` is a player -* `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.send_join_message(player_name)` - * This function can be overridden by mods to change the join message. -* `minetest.send_leave_message(player_name, timed_out)` - * This function can be overridden by mods to change the leave message. -* `minetest.hash_node_position(pos)`: returns an 48-bit integer - * `pos`: table {x=number, y=number, z=number}, - * 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[, safe])`: returns a table - * Convert a string returned by `minetest.serialize` into a table - * `string` is loaded in an empty sandbox environment. - * Will load functions if safe is false or omitted. Although these functions - cannot directly access the global environment, they could bypass this - restriction with maliciously crafted Lua bytecode if mod security is - disabled. - * This function should not be used on untrusted data, regardless of the - value of `safe`. It is fine to serialize then deserialize user-provided - data, but directly providing user input to deserialize is always unsafe. - * Example: `deserialize('return { ["foo"] = "bar" }')`, - returns `{foo='bar'}` - * Example: `deserialize('print("foo")')`, returns `nil` - (function call fails), returns - `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. - * `...` indicates method-specific arguments. Currently, no methods use this -* `minetest.rgba(red, green, blue[, alpha])`: returns a string - * Each argument is a 8 Bit unsigned integer - * Returns the ColorString from rgb or rgba values - * Example: `minetest.rgba(10, 20, 30, 40)`, returns `"#0A141E28"` -* `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 - * Returning `true` restricts the player `name` from modifying (i.e. digging, - placing) the node at position `pos`. - * `name` will be `""` for non-players or unknown players. - * This function should be overridden by protection mods. It is highly - recommended to grant access to players with the `protection_bypass` privilege. - * Cache and call the old version of this function if the position is - not protected by the mod. This will allow using multiple protection mods. - * 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.is_area_protected(pos1, pos2, player_name, interval)` - * Returns the position of the first node that `player_name` may not modify - in the specified cuboid between `pos1` and `pos2`. - * Returns `false` if no protections were found. - * Applies `is_protected()` to a 3D lattice of points in the defined volume. - The points are spaced evenly throughout the volume and have a spacing - similar to, but no larger than, `interval`. - * All corners and edges of the defined volume are checked. - * `interval` defaults to 4. - * `interval` should be carefully chosen and maximised to avoid an excessive - number of points being checked. - * Like `minetest.is_protected`, this function may be extended or - overwritten by mods to provide a faster implementation to check the - cuboid for intersections. -* `minetest.rotate_and_place(itemstack, placer, pointed_thing[, infinitestacks, - orient_flags, prevent_after_place])` - * 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). - * `infinitestacks`: if `true`, the itemstack is not changed. Otherwise the - stacks are handled normally. - * `orient_flags`: 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. - * `prevent_after_place` is directly passed to `minetest.item_place_node` - * Returns the new itemstack after placement -* `minetest.rotate_node(itemstack, placer, pointed_thing)` - * calls `rotate_and_place()` with `infinitestacks` set according to the state - of the creative mode setting, checks for "sneak" to set the `invert_wall` - parameter and `prevent_after_place` set to `true`. - -* `minetest.calculate_knockback(player, hitter, time_from_last_punch, - tool_capabilities, dir, distance, damage)` - * Returns the amount of knockback applied on the punched player. - * Arguments are equivalent to `register_on_punchplayer`, except the following: - * `distance`: distance between puncher and punched player - * This function can be overriden by mods that wish to modify this behaviour. - * You may want to cache and call the old function to allow multiple mods to - change knockback behaviour. - -* `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 -------------- - -### Registered definition 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_abms` - * List of ABM definitions -* `minetest.registered_lbms` - * List of LBM definitions -* `minetest.registered_aliases` - * Map of registered aliases, indexed by name -* `minetest.registered_ores` - * Map of registered ore definitions, indexed by the `name` field. - * If `name` is nil, the key is the object handle returned by - `minetest.register_ore`. -* `minetest.registered_biomes` - * Map of registered biome definitions, indexed by the `name` field. - * If `name` is nil, the key is the object handle returned by - `minetest.register_biome`. -* `minetest.registered_decorations` - * Map of registered decoration definitions, indexed by the `name` field. - * If `name` is nil, the key is the object handle returned by - `minetest.register_decoration`. -* `minetest.registered_schematics` - * Map of registered schematic definitions, indexed by the `name` field. - * If `name` is nil, the key is the object handle returned by - `minetest.register_schematic`. -* `minetest.registered_chatcommands` - * Map of registered chat command definitions, indexed by name -* `minetest.registered_privileges` - * Map of registered privilege definitions, indexed by name - -### Registered callback tables - -All callbacks registered with [Global callback registration functions] are added -to corresponding `minetest.registered_*` tables. - - - - -Class reference -=============== - -Sorted alphabetically. - -`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)`. The mod decides where to save and load AreaStore. -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 information about the specified ID. - * Returned values are either of these: - - nil -- Area not found - true -- Without `include_borders` and `include_data` - { - min = pos, max = pos -- `include_borders == true` - data = string -- `include_data == true` - } - -* `get_areas_for_pos(pos, include_borders, include_data)` - * Returns all areas as table, indexed by the area ID. - * Table values: see `get_area`. -* `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). - * `accept_overlap`: if `true`, areas are returned that have nodes in - common (intersect) with the specified area. - * Returns the same values as `get_areas_for_pos`. -* `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. - * `id` (optional): will be used as the internal area ID if it is an unique - number between 0 and 2^32-2. -* `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` is a table with the following fields: - - enabled = boolean, -- Whether to enable, default true - block_radius = int, -- The radius (in nodes) of the areas the cache - -- generates prefiltered lists for, minimum 16, - -- default 64 - limit = int, -- The cache 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. - -`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, [match_meta])`: returns `true` if - the stack of items can be fully taken from the list. - If `match_meta` is false, only the items' names are compared - (default: `false`). -* `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 - -`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 a boolean indicating whether the item was - cleared. -* `get_count()`: Returns number of items on the stack. -* `set_count(count)`: returns a boolean indicating whether the item was cleared - * `count`: number, unsigned 16 bit integer -* `get_wear()`: returns tool wear (`0`-`65535`), `0` for non-tools. -* `set_wear(wear)`: returns boolean indicating whether item was cleared - * `wear`: number, unsigned 16 bit integer -* `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. -* `get_description()`: returns the description shown in inventory list tooltips. -* `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 - * `amount`: number, integer -* `add_item(item)`: returns leftover `ItemStack` - * Put some item or stack onto this stack -* `item_fits(item)`: returns `true` if item or stack can be fully added to - this one. -* `take_item(n)`: returns taken `ItemStack` - * Take (and remove) up to `n` items from this stack - * `n`: number, default: `1` -* `peek_item(n)`: returns taken `ItemStack` - * Copy (don't remove) up to `n` items from this stack - * `n`: number, default: `1` - -`ItemStackMetaRef` ------------------- - -ItemStack metadata: reference extra data and functionality stored in a stack. -Can be obtained via `item:get_meta()`. - -### Methods - -* All methods in MetaDataRef -* `set_tool_capabilities([tool_capabilities])` - * Overrides the item's tool capabilities - * A nil value will clear the override data and restore the original - behavior. - -`MetaDataRef` -------------- - -Base class used by [`StorageRef`], [`NodeMetaRef`], [`ItemStackMetaRef`], -and [`PlayerMetaRef`]. - -### Methods - -* `contains(key)`: Returns true if key present, otherwise false. - * Returns `nil` when the MetaData is inexistent. -* `get(key)`: Returns `nil` if key not present, else the stored string. -* `set_string(key, value)`: Value of `""` will delete the key. -* `get_string(key)`: Returns `""` if key not present. -* `set_int(key, value)` -* `get_int(key)`: Returns `0` if key not present. -* `set_float(key, value)` -* `get_float(key)`: Returns `0` if key not present. -* `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` - -`ModChannel` ------------- - -An interface to use mod channels on client and server - -### Methods - -* `leave()`: leave the mod channel. - * Server leaves channel `channel_name`. - * No more incoming or outgoing messages can be sent to this channel from - server mods. - * This invalidate all future object usage. - * Ensure you set mod_channel to nil after that to free Lua resources. -* `is_writeable()`: returns true if channel is writeable and mod can send over - it. -* `send_all(message)`: Send `message` though the mod channel. - * If mod channel is not writeable or invalid, message will be dropped. - * Message size is limited to 65535 characters by protocol. - -`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`). - -`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`. - -### Advice on handling `ObjectRefs` - -When you receive an `ObjectRef` as a callback argument or from another API -function, it is possible to store the reference somewhere and keep it around. -It will keep functioning until the object is unloaded or removed. - -However, doing this is **NOT** recommended as there is (intentionally) no method -to test if a previously acquired `ObjectRef` is still valid. -Instead, `ObjectRefs` should be "let go" of as soon as control is returned from -Lua back to the engine. -Doing so is much less error-prone and you will never need to wonder if the -object you are working with still exists. - - -### Methods - -* `get_pos()`: returns `{x=num, y=num, z=num}` -* `set_pos(pos)`: `pos`=`{x=num, y=num, z=num}` -* `move_to(pos, continuous=false)` - * Does an interpolated move for Lua entities for visually smooth transitions. - * If `continuous` is true, the Lua entity will not be moved to the current - position before starting the interpolated move. - * For players this does the same as `set_pos`,`continuous` is ignored. -* `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, reason)`: set number of hitpoints (2 * number of hearts). - * See reason in register_on_player_hpchange - * Is limited to the range of 0 ... 65535 (2^16 - 1) - * For players: HP are also limited by `hp_max` specified in the player's - object properties -* `get_inventory()`: returns an `InvRef` for players, otherwise returns `nil` -* `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(frame_range, frame_speed, frame_blend, frame_loop)` - * `frame_range`: table {x=num, y=num}, default: `{x=1, y=1}` - * `frame_speed`: number, default: `15.0` - * `frame_blend`: number, default: `0.0` - * `frame_loop`: boolean, default: `true` -* `get_animation()`: returns `range`, `frame_speed`, `frame_blend` and - `frame_loop`. -* `set_animation_frame_speed(frame_speed)` - * `frame_speed`: number, default: `15.0` -* `set_attach(parent, bone, position, rotation)` - * `bone`: string - * `position`: `{x=num, y=num, z=num}` (relative) - * `rotation`: `{x=num, y=num, z=num}` = Rotation on each axis, in degrees -* `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", - } - -#### Lua entity only (no-op for other objects) - -* `remove()`: remove object - * The object is removed after returning from Lua. However the `ObjectRef` - itself instantly becomes unusable with all further method calls having - no effect and returning `nil`. -* `set_velocity(vel)` - * `vel` is a vector, e.g. `{x=0.0, y=2.3, z=1.0}` -* `add_velocity(vel)` - * `vel` is a vector, e.g. `{x=0.0, y=2.3, z=1.0}` - * In comparison to using get_velocity, adding the velocity and then using - set_velocity, add_velocity is supposed to avoid synchronization problems. -* `get_velocity()`: returns the velocity, a vector -* `set_acceleration(acc)` - * `acc` is a vector -* `get_acceleration()`: returns the acceleration, a vector -* `set_rotation(rot)` - * `rot` is a vector (radians). X is pitch (elevation), Y is yaw (heading) - and Z is roll (bank). -* `get_rotation()`: returns the rotation, a vector (radians) -* `set_yaw(radians)`: sets the yaw (heading). -* `get_yaw()`: returns number in radians -* `set_texture_mod(mod)` -* `get_texture_mod()` returns current texture modifier -* `set_sprite(p, num_frames, framelength, select_horiz_by_yawpitch)` - * Select sprite from spritesheet with optional animation and Dungeon Master - style texture selection based on yaw relative to camera - * `p`: {x=number, y=number}, the coordinate of the first frame - (x: column, y: row), default: `{x=0, y=0}` - * `num_frames`: number, default: `1` - * `framelength`: number, default: `0.2` - * `select_horiz_by_yawpitch`: boolean, this was once used for the Dungeon - Master mob, default: `false` -* `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 -* `add_player_velocity(vel)` - * Adds to player velocity, this happens client-side and only once. - * Does not apply during free_move. - * Note that since the player speed is normalized at each move step, - increasing e.g. Y velocity beyond what would usually be achieved - (see: physics overrides) will cause existing X/Z velocity to be reduced. - * Example: `add_player_velocity({x=0, y=6.5, z=0})` is equivalent to - pressing the jump key (assuming default settings) -* `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 player's breath -* `set_breath(value)`: sets player's breath - * values: - * `0`: player is drowning - * max: bubbles bar is not shown - * See [Object properties] for more information - * Is limited to range 0 ... 65535 (2^16 - 1) -* `set_fov(fov, is_multiplier)`: Sets player's FOV - * `fov`: FOV value. - * `is_multiplier`: Set to `true` if the FOV value is a multiplier. - Defaults to `false`. - * Set to 0 to clear FOV override. -* `get_fov()`: - * Returns player's FOV override in degrees, and a boolean depending on whether - the value is a multiplier. - * Returns 0 as first value if player's FOV hasn't been overridden. -* `set_attribute(attribute, value)`: DEPRECATED, use get_meta() instead - * Sets an extra attribute with value on player. - * `value` must be a string, or a number which will be converted to a - string. - * If `value` is `nil`, remove attribute from player. -* `get_attribute(attribute)`: DEPRECATED, use get_meta() instead - * Returns value (a string) for extra attribute. - * Returns `nil` if no attribute found. -* `get_meta()`: Returns a PlayerMetaRef. -* `set_inventory_formspec(formspec)` - * Redefine player's inventory form - * Should usually be called in `on_joinplayer` -* `get_inventory_formspec()`: returns a formspec string -* `set_formspec_prepend(formspec)`: - * the formspec string will be added to every formspec shown to the user, - except for those with a no_prepend[] tag. - * This should be used to set style elements such as background[] and - bgcolor[], any non-style elements (eg: label) may result in weird behaviour. - * Only affects formspecs shown after this is called. -* `get_formspec_prepend(formspec)`: returns a formspec string. -* `get_player_control()`: returns table with player pressed keys - * The table consists of fields with boolean value representing the pressed - keys, the fields are jump, right, left, LMB, RMB, sneak, aux1, down, up. - * example: `{jump=false, right=true, left=false, LMB=false, RMB=false, - sneak=true, aux1=false, down=false, up=false}` -* `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 of player. - * `flags`: A table with the following fields set to boolean values - * hotbar - * healthbar - * crosshair - * wielditem - * breathbar - * minimap - * minimap_radar - * If a flag equals `nil`, the flag is not modified - * `minimap`: Modifies the client's permission to view the minimap. - The client may locally elect to not view the minimap. - * `minimap_radar` is only usable when `minimap` is true -* `hud_get_flags()`: returns a table of player HUD flags with boolean values. - * See `hud_set_flags` for a list of flags that can be toggled. -* `hud_set_hotbar_itemcount(count)`: sets number of items in builtin hotbar - * `count`: number of items, must be between `1` and `32` -* `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(parameters)` - * `parameters` is a table with the following optional fields: - * `base_color`: ColorSpec, changes fog in "skybox" and "plain". - * `type`: Available types: - * `"regular"`: Uses 0 textures, `base_color` ignored - * `"skybox"`: Uses 6 textures, `base_color` used as fog. - * `"plain"`: Uses 0 textures, `base_color` used as both fog and sky. - * `textures`: A table containing up to six textures in the following - order: Y+ (top), Y- (bottom), X- (west), X+ (east), Z+ (north), Z- (south). - * `clouds`: Boolean for whether clouds appear. (default: `true`) - * `sky_color`: A table containing the following values, alpha is ignored: - * `day_sky`: ColorSpec, for the top half of the `"regular"` - skybox during the day. (default: `#8cbafa`) - * `day_horizon`: ColorSpec, for the bottom half of the - `"regular"` skybox during the day. (default: `#9bc1f0`) - * `dawn_sky`: ColorSpec, for the top half of the `"regular"` - skybox during dawn/sunset. (default: `#b4bafa`) - * `dawn_horizon`: ColorSpec, for the bottom half of the `"regular"` - skybox during dawn/sunset. (default: `#bac1f0`) - * `night_sky`: ColorSpec, for the top half of the `"regular"` - skybox during the night. (default: `#006aff`) - * `night_horizon`: ColorSpec, for the bottom half of the `"regular"` - skybox during the night. (default: `#4090ff`) - * `indoors`: ColorSpec, for when you're either indoors or - underground. Only applies to the `"regular"` skybox. - (default: `#646464`) - * `fog_sun_tint`: ColorSpec, changes the fog tinting for the sun - at sunrise and sunset. - * `fog_moon_tint`: ColorSpec, changes the fog tinting for the moon - at sunrise and sunset. - * `fog_tint_type`: string, changes which mode the directional fog - abides by, `"custom"` uses `sun_tint` and `moon_tint`, while - `"default"` uses the classic Minetest sun and moon tinting. - Will use tonemaps, if set to `"default"`. (default: `"default"`) -* `get_sky()`: returns base_color, type, table of textures, clouds. -* `get_sky_color()`: returns a table with the `sky_color` parameters as in - `set_sky`. -* `set_sun(parameters)`: - * `parameters` is a table with the following optional fields: - * `visible`: Boolean for whether the sun is visible. - (default: `true`) - * `texture`: A regular texture for the sun. Setting to `""` - will re-enable the mesh sun. (default: `"sun.png"`) - * `tonemap`: A 512x1 texture containing the tonemap for the sun - (default: `"sun_tonemap.png"`) - * `sunrise`: A regular texture for the sunrise texture. - (default: `"sunrisebg.png"`) - * `sunrise_visible`: Boolean for whether the sunrise texture is visible. - (default: `true`) - * `scale`: Float controlling the overall size of the sun. (default: `1`) -* `get_sun()`: returns a table with the current sun parameters as in - `set_sun`. -* `set_moon(parameters)`: - * `parameters` is a table with the following optional fields: - * `visible`: Boolean for whether the moon is visible. - (default: `true`) - * `texture`: A regular texture for the moon. Setting to `""` - will re-enable the mesh moon. (default: `"moon.png"`) - * `tonemap`: A 512x1 texture containing the tonemap for the moon - (default: `"moon_tonemap.png"`) - * `scale`: Float controlling the overall size of the moon (default: `1`) -* `get_moon()`: returns a table with the current moon parameters as in - `set_moon`. -* `set_stars(parameters)`: - * `parameters` is a table with the following optional fields: - * `visible`: Boolean for whether the stars are visible. - (default: `true`) - * `count`: Integer number to set the number of stars in - the skybox. Only applies to `"skybox"` and `"regular"` skyboxes. - (default: `1000`) - * `star_color`: ColorSpec, sets the colors of the stars, - alpha channel is used to set overall star brightness. - (default: `#ebebff69`) - * `scale`: Float controlling the overall size of the stars (default: `1`) -* `get_stars()`: returns a table with the current stars parameters as in - `set_stars`. -* `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, ColorSpec - (default `#fff0f0e5`). - * `ambient`: cloud color lower bound, use for a "glow at night" effect. - ColorSpec (alpha ignored, 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, z=-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` -* `send_mapblock(blockpos)`: - * Sends a server-side loaded mapblock to the player. - * Returns `false` if failed. - * Resource intensive - use sparsely - * To get blockpos, integer divide pos by 16 - -`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 - -`PerlinNoise` -------------- - -A perlin noise generator. -It can be created via `PerlinNoise(seed, octaves, persistence, spread)` -or `PerlinNoise(noiseparams)`. -Alternatively with `minetest.get_perlin(seeddiff, octaves, persistence, spread)` -or `minetest.get_perlin(noiseparams)`. - -### Methods - -* `get_2d(pos)`: returns 2D noise value at `pos={x=,y=}` -* `get_3d(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` component is omitted -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 - -* `get_2d_map(pos)`: returns a `<size.x>` times `<size.y>` 2D array of 2D noise - with values starting at `pos={x=,y=}` -* `get_3d_map(pos)`: returns a `<size.x>` times `<size.y>` times `<size.z>` - 3D array of 3D noise with values starting at `pos={x=,y=,z=}`. -* `get_2d_map_flat(pos, buffer)`: returns a flat `<size.x * size.y>` element - array of 2D noise with values starting at `pos={x=,y=}` -* `get_3d_map_flat(pos, buffer)`: Same as `get2dMap_flat`, but 3D noise -* `calc_2d_map(pos)`: Calculates the 2d noise map starting at `pos`. The result - is stored internally. -* `calc_3d_map(pos)`: Calculates the 3d noise map starting at `pos`. The result - is stored internally. -* `get_map_slice(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:get_map_slice({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:calc_3d_map({x=1000, y=1000, z=1000})` - `noisevals = noise:get_map_slice({x=24, z=1}, {x=1, z=1})` - -`PlayerMetaRef` ---------------- - -Player metadata. -Uses the same method of storage as the deprecated player attribute API, so -data there will also be in player meta. -Can be obtained using `player:get_meta()`. - -### Methods - -* All methods in MetaDataRef - -`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. - -`Raycast` ---------- - -A raycast on the map. It works with selection boxes. -Can be used as an iterator in a for loop as: - - local ray = Raycast(...) - for pointed_thing in ray do - ... - end - -The map is loaded as the ray advances. If the map is modified after the -`Raycast` is created, the changes may or may not have an effect on the object. - -It can be created via `Raycast(pos1, pos2, objects, liquids)` or -`minetest.raycast(pos1, pos2, objects, liquids)` where: - -* `pos1`: start of the ray -* `pos2`: end of the ray -* `objects`: if false, only nodes will be returned. Default is true. -* `liquids`: if false, liquid nodes won't be returned. Default is false. - -### Methods - -* `next()`: returns a `pointed_thing` with exact pointing location - * Returns the next thing pointed by the ray or nil. - -`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 found on the system. - -### Methods - -* `next_bytes([count])`: return next `count` (default 1, capped at 2048) many - random bytes, as a string. - -`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, [default])`: returns a boolean - * `default` is the value returned if `key` is not found. - * Returns `nil` if `key` is not found and `default` not specified. -* `get_np_group(key)`: returns a NoiseParams table -* `get_flags(key)`: - * Returns `{flag = true/false, ...}` according to the set flags. - * Is currently limited to mapgen flags `mg_flags` and mapgen-specific - flags like `mgv5_spflags`. -* `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. -* `set_np_group(key, value)` - * `value` is a NoiseParams table. - * Also, 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,...}` - -### Format - -The settings have the format `key = value`. Example: - - foo = example text - bar = """ - Multiline - value - """ - - -`StorageRef` ------------- - -Mod metadata: per mod metadata, saved automatically. -Can be obtained via `minetest.get_mod_storage()` during load time. - -WARNING: This storage backend is incaptable to save raw binary data due -to restrictions of JSON. - -### Methods - -* All methods in MetaDataRef - - - - -Definition tables -================= - -Object properties ------------------ - -Used by `ObjectRef` methods. Part of an Entity definition. -These properties are not persistent, but are applied automatically to the -corresponding Lua entity using the given registration fields. -Player properties need to be saved manually. - - { - hp_max = 1, - -- For players only. Defaults to `minetest.PLAYER_MAX_HP_DEFAULT`. - - breath_max = 0, - -- For players only. Defaults to `minetest.PLAYER_MAX_BREATH_DEFAULT`. - - zoom_fov = 0.0, - -- For players only. Zoom FOV in degrees. - -- Note that zoom loads and/or generates world beyond the server's - -- maximum send and generate distances, so acts like a telescope. - -- Smaller zoom_fov values increase the distance loaded/generated. - -- Defaults to 15 in creative mode, 0 in survival mode. - -- zoom_fov = 0 disables zooming for the player. - - eye_height = 1.625, - -- For players only. Camera height above feet position in nodes. - -- Defaults to 1.625. - - physical = true, - -- Collide with `walkable` nodes. - - collide_with_objects = true, - -- Collide with other objects if physical = true - - collisionbox = {-0.5, 0.0, -0.5, 0.5, 1.0, 0.5}, -- Default - selectionbox = {-0.5, 0.0, -0.5, 0.5, 1.0, 0.5}, - -- Selection box uses collision box dimensions when not set. - -- For both boxes: {xmin, ymin, zmin, xmax, ymax, zmax} in nodes from - -- object position. - - pointable = true, - -- Overrides selection box when false - - visual = "cube" / "sprite" / "upright_sprite" / "mesh" / "wielditem" / "item", - -- "cube" is a node-sized cube. - -- "sprite" is a flat texture always facing the player. - -- "upright_sprite" is a vertical flat texture. - -- "mesh" uses the defined mesh model. - -- "wielditem" is used for dropped items. - -- (see builtin/game/item_entity.lua). - -- For this use 'wield_item = itemname' (Deprecated: 'textures = {itemname}'). - -- If the item has a 'wield_image' the object will be an extrusion of - -- that, otherwise: - -- If 'itemname' is a cubic node or nodebox the object will appear - -- identical to 'itemname'. - -- If 'itemname' is a plantlike node the object will be an extrusion - -- of its texture. - -- Otherwise for non-node items, the object will be an extrusion of - -- 'inventory_image'. - -- If 'itemname' contains a ColorString or palette index (e.g. from - -- `minetest.itemstring_with_palette()`), the entity will inherit the color. - -- "item" is similar to "wielditem" but ignores the 'wield_image' parameter. - - visual_size = {x = 1, y = 1, z = 1}, - -- Multipliers for the visual size. If `z` is not specified, `x` will be used - -- to scale the entity along both horizontal axes. - - mesh = "model.obj", - -- File name of mesh when using "mesh" visual - - textures = {}, - -- Number of required textures depends on visual. - -- "cube" uses 6 textures just like a node, but all 6 must be defined. - -- "sprite" uses 1 texture. - -- "upright_sprite" uses 2 textures: {front, back}. - -- "wielditem" expects 'textures = {itemname}' (see 'visual' above). - - colors = {}, - -- Number of required colors depends on visual - - use_texture_alpha = false, - -- Use texture's alpha channel. - -- Excludes "upright_sprite" and "wielditem". - -- Note: currently causes visual issues when viewed through other - -- semi-transparent materials such as water. - - spritediv = {x = 1, y = 1}, - -- Used with spritesheet textures for animation and/or frame selection - -- according to position relative to player. - -- Defines the number of columns and rows in the spritesheet: - -- {columns, rows}. - - initial_sprite_basepos = {x = 0, y = 0}, - -- Used with spritesheet textures. - -- Defines the {column, row} position of the initially used frame in the - -- spritesheet. - - is_visible = true, - -- If false, object is invisible and can't be pointed. - - makes_footstep_sound = false, - -- If true, is able to make footstep sounds of nodes - -- (see node sound definition for details). - - automatic_rotate = 0, - -- Set constant rotation in radians per second, positive or negative. - -- Set to 0 to disable constant rotation. - - stepheight = 0, - -- If positive number, object will climb upwards when it moves - -- horizontally against a `walkable` node, if the height difference - -- is within `stepheight`. - - 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. - -- No limit if value <= 0. - - backface_culling = true, - -- Set to false to disable backface_culling for model - - glow = 0, - -- Add this much extra lighting when calculating texture color. - -- Value < 0 disables light's effect on texture color. - -- For faking self-lighting, UI style entities, or programmatic coloring - -- in mods. - - nametag = "", - -- By default empty, for players their name is shown if empty - - nametag_color = <ColorSpec>, - -- Sets color of nametag - - infotext = "", - -- By default empty, text to be shown when pointed at object - - static_save = true, - -- If false, never save this object statically. It will simply be - -- deleted when the block gets unloaded. - -- The get_staticdata() callback is never called then. - -- Defaults to 'true'. - } - -Entity definition ------------------ - -Used by `minetest.register_entity`. - - { - initial_properties = { - visual = "mesh", - mesh = "boats_boat.obj", - ..., - }, - -- A table of object properties, see the `Object properties` section. - -- Object properties being read directly from the entity definition - -- table is deprecated. Define object properties in this - -- `initial_properties` table instead. - - 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 - - _custom_field = whatever, - -- You can define arbitrary member variables here (see Item definition - -- for more info) by using a '_' prefix - } - -ABM (ActiveBlockModifier) definition ------------------------------------- - -Used by `minetest.register_abm`. - - { - label = "Lava cooling", - -- Descriptive label for profiling purposes (optional). - -- Definitions with identical labels will be listed as one. - - nodenames = {"default:lava_source"}, - -- Apply `action` function to these nodes. - -- `group:groupname` can also be used here. - - neighbors = {"default:water_source", "default:water_flowing"}, - -- Only apply `action` to nodes that have one of, or any - -- combination of, these neighbors. - -- If left out or empty, any neighbor will do. - -- `group:groupname` can also be used here. - - interval = 1.0, - -- Operation interval in seconds - - chance = 1, - -- Chance of triggering `action` per-node per-interval is 1.0 / this - -- value - - 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 that the `chance` value can often - -- be reduced to 1. - - action = function(pos, node, active_object_count, active_object_count_wider), - -- Function triggered for each qualifying node. - -- `active_object_count` is number of active objects in the node's - -- mapblock. - -- `active_object_count_wider` is number of active objects in the node's - -- mapblock plus all 26 neighboring mapblocks. If any neighboring - -- mapblocks are unloaded an estmate is calculated for them based on - -- loaded mapblocks. - } - -LBM (LoadingBlockModifier) definition -------------------------------------- - -Used by `minetest.register_lbm`. - -A loading block modifier (LBM) is used to define a function that is called for -specific nodes (defined by `nodenames`) when a mapblock which contains such nodes -gets loaded. - - { - 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 only the first time the block gets loaded after the LBM - -- was introduced. - - action = function(pos, node), - } - -Tile definition ---------------- - -* `"image.png"` -* `{name="image.png", animation={Tile Animation definition}}` -* `{name="image.png", backface_culling=bool, tileable_vertical=bool, - tileable_horizontal=bool, align_style="node"/"world"/"user", scale=int}` - * 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. - * align style determines whether the texture will be rotated with the node - or kept aligned with its surroundings. "user" means that client - setting will be used, similar to `glasslike_framed_optional`. - Note: supported by solid nodes and nodeboxes only. - * scale is used to make texture span several (exactly `scale`) nodes, - instead of just one, in each direction. Works for world-aligned - textures only. - Note that as the effect is applied on per-mapblock basis, `16` should - be equally divisible by `scale` or you may get wrong results. -* `{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, - -- Width of a frame in pixels - - aspect_h = 16, - -- Height of a frame in pixels - - length = 3.0, - -- Full loop length - } - - { - type = "sheet_2d", - - frames_w = 5, - -- Width in number of frames - - frames_h = 3, - -- Height in number of frames - - frame_length = 0.5, - -- Length of a single frame - } - -Item definition ---------------- - -Used by `minetest.register_node`, `minetest.register_craftitem`, and -`minetest.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", - - inventory_overlay = "overlay.png", - -- An overlay which does not get colorized - - wield_image = "", - - wield_overlay = "", - - 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, - - -- See "Tools" section for an example including explanation - 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}, - -- Damage values must be between -32768 and 32767 (2^15) - - punch_attack_uses = nil, - -- Amount of uses this tool has for attacking players and entities - -- by punching them (0 = infinite uses). - -- For compatibility, this is automatically set from the first - -- suitable groupcap using the forumla "uses * 3^(maxlevel - 1)". - -- It is recommend to set this explicitly instead of relying on the - -- fallback behavior. - }, - - 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. - - node_dig_prediction = "air", - -- if "", no prediction is made. - -- if "air", node is removed. - -- Otherwise should be name of node which the client immediately places - -- upon digging. Server will always update actual result shortly. - - sound = { - -- Definition of items sounds to be played at various events. - -- All fields in this table are optional. - - breaks = <SimpleSoundSpec>, - -- When tool breaks due to wear. Ignored for non-tools - - eat = <SimpleSoundSpec>, - -- When item is eaten with `minetest.do_item_eat` - }, - - on_place = function(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 = function(itemstack, user, pointed_thing), - -- Same as on_place but called when not pointing at a node. - -- The user may be any ObjectRef or nil. - -- default: nil - - on_drop = function(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 = function(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 = function(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. - } - -Node definition ---------------- - -Used by `minetest.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 torchlike, the image will start at the surface to which the - -- node "attaches". For the other drawtypes the image will be centered - -- on the node. - - tiles = {tile definition 1, def2, def3, def4, def5, def6}, - -- Textures of node; +Y, -Y, +X, -X, +Z, -Z - -- Old field name was '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 was '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", - -- Screen tint if player is inside node, see "ColorSpec" - - paramtype = "none", -- See "Nodes" - - paramtype2 = "none", -- See "Nodes" - - place_param2 = nil, -- Force value for param2 when player places node - - is_ground_content = true, - -- If false, the cave generator and dungeon generator will not carve - -- through this node. - -- Specifically, this stops mod-added nodes being removed by caves and - -- dungeons when those generate in a neighbor mapchunk and extend out - -- beyond the edge of that mapchunk. - - sunlight_propagates = false, - -- If true, sunlight will go infinitely through this node - - 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' will 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 = 16, - -- Only valid for "nodebox" drawtype with 'type = "leveled"'. - -- Allows defining the nodebox height without using param2. - -- The nodebox height is 'leveled' / 64 nodes. - -- The maximum value of 'leveled' is 127. - - 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 (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.obj", - -- File name of mesh when using "mesh" drawtype - - selection_box = { - type = "fixed", - fixed = { - {-2 / 16, -0.5, -2 / 16, 2 / 16, 3 / 16, 2 / 16}, - }, - }, - -- Custom selection box definition. Multiple boxes can be defined. - -- If "nodebox" drawtype is used and selection_box is nil, then node_box - -- definition is used for the selection box. - - collision_box = { - type = "fixed", - fixed = { - {-2 / 16, -0.5, -2 / 16, 2 / 16, 3 / 16, 2 / 16}, - }, - }, - -- Custom collision box definition. Multiple boxes can be defined. - -- If "nodebox" drawtype is used and collision_box is nil, then node_box - -- definition is used for the collision box. - -- Both of the boxes above are defined as: - -- {xmin, ymin, zmin, xmax, ymax, zmax} in nodes from node center. - - -- Support maps made in and before January 2012 - legacy_facedir_simple = false, - legacy_wallmounted = false, - - waving = 0, - -- Valid for drawtypes: - -- mesh, nodebox, plantlike, allfaces_optional, liquid, flowingliquid. - -- 1 - wave node like plants (node top moves side-to-side, bottom is fixed) - -- 2 - wave node like leaves (whole node moves side-to-side) - -- 3 - wave node like liquids (whole node moves up and down) - -- Not all models will properly wave. - -- plantlike drawtype can only wave like plants. - -- allfaces_optional drawtype can only wave like leaves. - -- liquid, flowingliquid drawtypes can only wave like liquids. - - sounds = { - -- Definition of node sounds to be played at various events. - -- All fields in this table are optional. - - footstep = <SimpleSoundSpec>, - -- If walkable, played when object walks on it. If node is - -- climbable or a liquid, played when object moves through it - - dig = <SimpleSoundSpec> or "__group", - -- While digging node. - -- If `"__group"`, then the sound will be - -- `default_dig_<groupname>`, where `<groupname>` is the - -- name of the tool's digging group with the fastest digging time. - -- In case of a tie, one of the sounds will be played (but we - -- cannot predict which one) - -- Default value: `"__group"` - - dug = <SimpleSoundSpec>, - -- Node was dug - - place = <SimpleSoundSpec>, - -- Node was placed. Also played after falling - - place_failed = <SimpleSoundSpec>, - -- When node placement failed - - fall = <SimpleSoundSpec>, - -- When node starts to fall - }, - - drop = "", - -- Name of dropped item when dug. - -- Default dropped item is the node itself. - -- Using a table allows multiple items, drop chances and tool filtering. - -- Tool filtering was undocumented until recently, tool filtering by string - -- matching is deprecated. - drop = { - max_items = 1, - -- Maximum number of item lists to drop. - -- The entries in 'items' are processed in order. For each: - -- Tool filtering is applied, chance of drop is applied, if both are - -- successful the entire item list is dropped. - -- Entry processing continues until the number of dropped item lists - -- equals 'max_items'. - -- Therefore, entries should progress from low to high drop chance. - items = { - -- Entry examples. - { - -- 1 in 1000 chance of dropping a diamond. - -- Default rarity is '1'. - rarity = 1000, - items = {"default:diamond"}, - }, - { - -- Only drop if using a tool whose name is identical to one - -- of these. - tools = {"default:shovel_mese", "default:shovel_diamond"}, - rarity = 5, - items = {"default:dirt"}, - -- Whether all items in the dropped item list inherit the - -- hardware coloring palette color from the dug node. - -- Default is 'false'. - inherit_color = true, - }, - { - -- Only drop if using a tool whose name contains - -- "default:shovel_" (this tool filtering by string matching - -- is deprecated). - tools = {"~default:shovel_"}, - rarity = 2, - -- The item list dropped. - items = {"default:sand", "default:desert_sand"}, - }, - }, - }, - - on_construct = function(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 = function(pos), - -- Node destructor; called before removing node. - -- Not called for bulk node placement. - -- default: nil - - after_destruct = function(pos, oldnode), - -- Node destructor; called after removing node. - -- Not called for bulk node placement. - -- default: nil - - on_flood = function(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' will cause problems. - - preserve_metadata = function(pos, oldnode, oldmeta, drops), - -- Called when oldnode is about be converted to an item, but before the - -- node is deleted from the world or the drops are added. This is - -- generally the result of either the node being dug or an attached node - -- becoming detached. - -- drops is a table of ItemStacks, so any metadata to be preserved can - -- be added directly to one or more of the dropped items. See - -- "ItemStackMetaRef". - -- default: nil - - after_place_node = function(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. - -- `placer` may be any valid ObjectRef or nil. - -- default: nil - - after_dig_node = function(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 = function(pos, node, puncher, pointed_thing), - -- default: minetest.node_punch - -- By default calls minetest.register_on_punchnode callbacks. - - on_rightclick = function(pos, node, clicker, itemstack, pointed_thing), - -- default: nil - -- itemstack will hold clicker's wielded item. - -- Shall return the leftover itemstack. - -- Note: pointed_thing can be nil, if a mod calls this function. - -- This function does not get triggered by clients <=0.4.16 if the - -- "formspec" node metadata field is set. - - on_dig = function(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 = function(pos, formname, fields, sender), - -- fields = {name1 = value1, name2 = value2, ...} - -- Called when an UI form (e.g. sign text input) returns data. - -- See minetest.register_on_player_receive_fields for more info. - -- default: nil - - allow_metadata_inventory_move = function(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 = function(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 = function(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 = function(pos, from_list, from_index, to_list, to_index, count, player), - on_metadata_inventory_put = function(pos, listname, index, stack, player), - on_metadata_inventory_take = function(pos, listname, index, stack, player), - -- Called after the actual action has happened, according to what was - -- allowed. - -- No return value. - - on_blast = function(pos, intensity), - -- intensity: 1.0 = mid range of regular TNT. - -- If defined, called when an explosion touches the node, instead of - -- removing the node. - } - -Crafting recipes ----------------- - -Used by `minetest.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 = <list of item pairs>, - -- replacements: replace one input item with another item on crafting - -- (optional). - } - -### Shapeless - - { - type = "shapeless", - output = 'mushrooms:mushroom_stew', - recipe = { - "mushrooms:bowl", - "mushrooms:mushroom_brown", - "mushrooms:mushroom_red", - }, - replacements = <list of item pairs>, - } - -### Tool repair - - { - type = "toolrepair", - additional_wear = -0.02, - } - -Note: Tools with group `disable_repair=1` will not repairable by this recipe. - -### Cooking - - { - type = "cooking", - output = "default:glass", - recipe = "default:sand", - cooktime = 3, - } - -### Furnace fuel - - { - type = "fuel", - recipe = "bucket:bucket_lava", - burntime = 60, - replacements = {{"bucket:bucket_lava", "bucket:bucket_empty"}}, - } - -Ore definition --------------- - -Used by `minetest.register_ore`. - -See [Ores] section above for essential information. - - { - ore_type = "scatter", - - ore = "default:stone_with_coal", - - ore_param2 = 3, - -- Facedir rotation. Default is 0 (unchanged rotation) - - 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. - -- If the desired average distance between ores is 'd', set this to - -- d * d * d. - - 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 3 * 3 * 3 cluster where 8 out of the 27 - -- nodes are coal ore. - - y_min = -31000, - y_max = 64, - -- Lower and upper limits for ore - - flags = "", - -- Attributes for the ore generation, see 'Ore attributes' section above - - 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.7 - }, - -- NoiseParams structure describing one of the perlin noises used for - -- ore distribution. - -- Needed by "sheet", "puff", "blob" and "vein" ores. - -- Omit from "scatter" ore for a uniform ore distribution. - -- Omit from "stratum" ore for a simple horizontal strata from y_min to - -- y_max. - - biomes = {"desert", "rainforest"}, - -- List of biomes in which this ore 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. - - -- Type-specific parameters - - -- sheet - column_height_min = 1, - column_height_max = 16, - column_midpoint_factor = 0.5, - - -- puff - np_puff_top = { - offset = 4, - scale = 2, - spread = {x = 100, y = 100, z = 100}, - seed = 47, - octaves = 3, - persist = 0.7 - }, - np_puff_bottom = { - offset = 4, - scale = 2, - spread = {x = 100, y = 100, z = 100}, - seed = 11, - octaves = 3, - persist = 0.7 - }, - - -- vein - random_factor = 1.0, - - -- stratum - np_stratum_thickness = { - offset = 8, - scale = 4, - spread = {x = 100, y = 100, z = 100}, - seed = 17, - octaves = 3, - persist = 0.7 - }, - stratum_thickness = 8, - } - -Biome definition ----------------- - -Used by `minetest.register_biome`. - - { - 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 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 - - node_cave_liquid = "default:lava_source", - node_cave_liquid = {"default:water_source", "default:lava_source"}, - -- Nodes placed inside 50% of the medium size caves. - -- Multiple nodes can be specified, each cave will use a randomly - -- chosen node from the list. - -- If this field is left out or 'nil', cave liquids fall back to - -- classic behaviour of lava and water distributed using 3D noise. - -- For no cave liquid, specify "air". - - node_dungeon = "default:cobble", - -- Node used for primary dungeon structure. - -- If absent, dungeon nodes fall back to the 'mapgen_cobble' mapgen - -- alias, if that is also absent, dungeon nodes fall back to the biome - -- 'node_stone'. - -- If present, the following two nodes are also used. - - node_dungeon_alt = "default:mossycobble", - -- Node used for randomly-distributed alternative structure nodes. - -- If alternative structure nodes are not wanted leave this absent for - -- performance reasons. - - node_dungeon_stair = "stairs:stair_cobble", - -- Node used for dungeon stairs. - -- If absent, stairs fall back to 'node_dungeon'. - - y_max = 31000, - y_min = 1, - -- Upper and lower limits for biome. - -- Alternatively you can use xyz limits as shown below. - - max_pos = {x = 31000, y = 128, z = 31000}, - min_pos = {x = -31000, y = 9, z = -31000}, - -- xyz limits for biome, an alternative to using 'y_min' and 'y_max'. - -- Biome is limited to a cuboid defined by these positions. - -- Any x, y or z field left undefined defaults to -31000 in 'min_pos' or - -- 31000 in 'max_pos'. - - vertical_blend = 8, - -- Vertical distance in nodes above 'y_max' over which the biome will - -- blend with the biome above. - -- Set to 0 for no vertical blend. Defaults to 0. - - heat_point = 0, - humidity_point = 50, - -- Characteristic temperature and humidity for the biome. - -- These values create 'biome points' on a voronoi diagram with heat and - -- humidity as axes. The resulting voronoi cells determine the - -- distribution of the biomes. - -- Heat and humidity have average values of 50, vary mostly between - -- 0 and 100 but can exceed these values. - } - -Decoration definition ---------------------- - -See [Decoration types]. Used by `minetest.register_decoration`. - - { - deco_type = "simple", - - place_on = "default:dirt_with_grass", - -- Node (or list of nodes) that the decoration can be placed on - - sidelen = 8, - -- Size of the square divisions of the mapchunk being generated. - -- Determines the resolution of noise variation if used. - -- If the chunk size is not evenly divisible by sidelen, sidelen is made - -- equal to the chunk size. - - fill_ratio = 0.02, - -- The value determines 'decorations per surface node'. - -- Used only if noise_params is not specified. - -- If >= 10.0 complete coverage is enabled and decoration placement uses - -- a different and much faster method. - - noise_params = { - offset = 0, - scale = 0.45, - spread = {x = 100, y = 100, z = 100}, - seed = 354, - octaves = 3, - persist = 0.7, - lacunarity = 2.0, - flags = "absvalue" - }, - -- NoiseParams structure describing the perlin noise used for decoration - -- distribution. - -- A noise value is calculated for each square division and determines - -- 'decorations per surface node' within each division. - -- If the noise value >= 10.0 complete coverage is enabled and - -- decoration placement uses a different and much faster method. - - 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, - -- Lower and upper limits for decoration. - -- These parameters refer to the Y co-ordinate of the 'place_on' node. - - spawn_by = "default:water", - -- Node (or list of nodes) that the decoration only spawns next to. - -- Checks two horizontal planes of 8 neighbouring nodes (including - -- diagonal neighbours), one plane level with the 'place_on' node and a - -- plane one node above that. - - 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, all_floors, all_ceilings", - -- 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. - -- "all_floors", "all_ceilings": Instead of placement on the highest - -- surface in a mapchunk the decoration is placed on all floor and/or - -- ceiling surfaces, for example in caves and dungeons. - -- Ceiling decorations act as an inversion of floor decorations so the - -- effect of 'place_offset_y' is inverted. - -- Y-slice probabilities do not function correctly for ceiling - -- schematic decorations as the behaviour is unchanged. - -- If a single decoration registration has both flags the floor and - -- ceiling decorations will be aligned vertically. - - ----- 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, - -- Decoration height in nodes. - -- If height_max is not 0, this is the lower limit of a randomly - -- selected height. - - height_max = 0, - -- Upper limit of the randomly selected height. - -- If absent, the parameter 'height' is used as a constant. - - param2 = 0, - -- Param2 value of decoration nodes. - -- If param2_max is not 0, this is the lower limit of a randomly - -- selected param2. - - param2_max = 0, - -- Upper limit of the randomly selected param2. - -- If absent, the parameter 'param2' is used as a constant. - - place_offset_y = 0, - -- Y offset of the decoration base node relative to the standard base - -- node position. - -- Can be positive or negative. Default is 0. - -- Effect is inverted for "all_ceilings" decorations. - -- Ignored by 'y_min', 'y_max' and 'spawn_by' checks, which always refer - -- to the 'place_on' 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. - -- Could also be the ID of a previously registered schematic. - - 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 = "air", param1 = 255, param2 = 0}, - ... - }, - yslice_prob = { - {ypos = 2, prob = 128}, - {ypos = 5, prob = 64}, - ... - }, - }, - -- Alternative schematic specification by supplying a table. The fields - -- size and data are mandatory whereas yslice_prob is optional. - -- 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", - -- Rotation can be "0", "90", "180", "270", or "random" - - place_offset_y = 0, - -- If the flag 'place_center_y' is set this parameter is ignored. - -- Y offset of the schematic base node layer relative to the 'place_on' - -- node. - -- Can be positive or negative. Default is 0. - -- Effect is inverted for "all_ceilings" decorations. - -- Ignored by 'y_min', 'y_max' and 'spawn_by' checks, which always refer - -- to the 'place_on' node. - } - -Chat command definition ------------------------ - -Used by `minetest.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. - } - -Note that in params, use of symbols is as follows: - -* `<>` signifies a placeholder to be replaced when the command is used. For - example, when a player name is needed: `<name>` -* `[]` signifies param is optional and not required when the command is used. - For example, if you require param1 but param2 is optional: - `<param1> [<param2>]` -* `|` signifies exclusive or. The command requires one param from the options - provided. For example: `<param1> | <param2>` -* `()` signifies grouping. For example, when param1 and param2 are both - required, or only param3 is required: `(<param1> <param2>) | <param3>` - -Privilege definition --------------------- - -Used by `minetest.register_privilege`. - - { - description = "", - -- Privilege description - - give_to_singleplayer = true, - -- Whether to grant the privilege to singleplayer. - - give_to_admin = true, - -- Whether to grant the privilege to the server admin. - -- Uses value of 'give_to_singleplayer' by default. - - on_grant = function(name, granter_name), - -- Called when given to player 'name' by 'granter_name'. - -- 'granter_name' will be nil if the priv was granted by a mod. - - on_revoke = function(name, revoker_name), - -- Called when taken from player 'name' by 'revoker_name'. - -- 'revoker_name' will be nil if the priv was revoked by a mod. - - -- Note that the above two callbacks will be called twice if a player is - -- responsible, once with the player name, and then with a nil player - -- name. - -- Return true in the above callbacks to stop register_on_priv_grant or - -- revoke being called. - } - -Detached inventory callbacks ----------------------------- - -Used by `minetest.create_detached_inventory`. - - { - allow_move = function(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 = function(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 = function(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 = function(inv, from_list, from_index, to_list, to_index, count, player), - on_put = function(inv, listname, index, stack, player), - on_take = function(inv, listname, index, stack, player), - -- Called after the actual action has happened, according to what was - -- allowed. - -- No return value. - } - -HUD Definition --------------- - -See [HUD] section. - -Used by `Player:hud_add`. Returned by `Player:hud_get`. - - { - hud_elem_type = "image", -- See HUD element types - -- Type of element, can be "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}, - - offset = {x=0, y=0}, - - size = { x=100, y=100 }, - -- Size of element in pixels - - z_index = 0, - -- Z index : lower z-index HUDs are displayed behind higher z-index HUDs - } - -Particle definition -------------------- - -Used by `minetest.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, - -- Scales the visual size of the particle texture. - - collisiondetection = false, - -- If true collides with `walkable` nodes and, depending on the - -- `object_collision` field, objects too. - - collision_removal = false, - -- If true particle is removed when it collides. - -- Requires collisiondetection = true to have any effect. - - object_collision = false, - -- If true particle collides with objects that are defined as - -- `physical = true,` and `collide_with_objects = true,`. - -- Requires collisiondetection = true to have any effect. - - vertical = false, - -- If true faces player using y axis only - - texture = "image.png", - - 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. - -- Values 0-14. - } - - -`ParticleSpawner` definition ----------------------------- - -Used by `minetest.add_particlespawner`. - - { - amount = 1, - -- Number of particles spawned over the time period `time`. - - time = 1, - -- Lifespan of spawner in seconds. - -- If time is 0 spawner has infinite lifespan and spawns the `amount` on - -- a per-second basis. - - 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 particles' properties are random values between the min and max - -- values. - -- pos, velocity, acceleration, expirationtime, size - - collisiondetection = false, - -- If true collide with `walkable` nodes and, depending on the - -- `object_collision` field, objects too. - - collision_removal = false, - -- If true particles are removed when they collide. - -- Requires collisiondetection = true to have any effect. - - object_collision = false, - -- If true particles collide with objects that are defined as - -- `physical = true,` and `collide_with_objects = true,`. - -- Requires collisiondetection = true to have any effect. - - attached = ObjectRef, - -- If defined, particle positions, velocities and accelerations are - -- relative to this object's position and yaw - - vertical = false, - -- If true face player using y axis only - - texture = "image.png", - - playername = "singleplayer", - -- Optional, if specified spawns particles only on the player's client - - animation = {Tile Animation definition}, - -- Optional, specifies how to animate the particles' texture - - glow = 0 - -- Optional, specify particle self-luminescence in darkness. - -- Values 0-14. - } - -`HTTPRequest` definition ------------------------- - -Used by `HTTPApiTable.fetch` and `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 is 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 ------------------------------- - -Passed to `HTTPApiTable.fetch` callback. Returned by -`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 successful - - timeout = false, - -- If true, the request timed out - - code = 200, - -- HTTP status code - - data = "response" - } - -Authentication handler definition ---------------------------------- - -Used by `minetest.register_authentication_handler`. - - { - get_auth = function(name), - -- Get authentication data for existing player `name` (`nil` if player - -- doesn't exist). - -- Returns following structure: - -- `{password=<string>, privileges=<table>, last_login=<number or nil>}` - - create_auth = function(name, password), - -- Create new auth data for player `name`. - -- Note that `password` is not plain-text but an arbitrary - -- representation decided by the engine. - - delete_auth = function(name), - -- Delete auth data of player `name`. - -- Returns boolean indicating success (false if player is nonexistent). - - set_password = function(name, password), - -- Set password of player `name` to `password`. - -- Auth data should be created if not present. - - set_privileges = function(name, privileges), - -- Set privileges of player `name`. - -- `privileges` is in table form, auth data should be created if not - -- present. - - reload = function(), - -- Reload authentication data from the storage location. - -- Returns boolean indicating success. - - record_login = function(name), - -- Called when player joins, used for keeping track of last_login - - iterate = function(), - -- Returns an iterator (use with `for` loops) for all player names - -- currently in the auth database - } |