diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/client_lua_api.txt | 125 | ||||
| -rw-r--r-- | doc/lua_api.txt | 664 | ||||
| -rw-r--r-- | doc/menu_lua_api.txt | 10 | ||||
| -rw-r--r-- | doc/texture_packs.txt | 5 | ||||
| -rw-r--r-- | doc/world_format.txt | 118 |
5 files changed, 661 insertions, 261 deletions
diff --git a/doc/client_lua_api.txt b/doc/client_lua_api.txt index 4bb53f403..c24de8d85 100644 --- a/doc/client_lua_api.txt +++ b/doc/client_lua_api.txt @@ -1,4 +1,4 @@ -Minetest Lua Client Modding API Reference 5.1.0 +Minetest Lua Client Modding API Reference 5.2.0 ================================================ * More information at <http://www.minetest.net/> * Developer Wiki: <http://dev.minetest.net/> @@ -30,7 +30,7 @@ Startup Mods are loaded during client startup from the mod load paths by running the `init.lua` scripts in a shared environment. -In order to load client-side mods in a world, the following conditions need to be satisfied: +In order to load client-side mods, the following conditions need to be satisfied: 1) `$path_user/minetest.conf` contains the setting `enable_client_modding = true` @@ -43,14 +43,10 @@ be loaded or have limited functionality. See setting `csm_restriction_flags` for Paths ----- * `RUN_IN_PLACE=1` (Windows release, local build) - * `$path_user`: - * Linux: `<build directory>` - * Windows: `<build directory>` - * `$path_share` - * Linux: `<build directory>` - * Windows: `<build directory>` + * `$path_user`: `<build directory>` + * `$path_share`: `<build directory>` * `RUN_IN_PLACE=0`: (Linux release) - * `$path_share` + * `$path_share`: * Linux: `/usr/share/minetest` * Windows: `<install directory>/minetest-0.4.x` * `$path_user`: @@ -75,7 +71,6 @@ On an installed version on Linux: Modpack support ---------------- -**NOTE: Not implemented yet.** Mods can be put in a subdirectory, if the parent directory, which otherwise should be a mod, contains a file named `modpack.conf`. @@ -90,30 +85,36 @@ Mod directory structure clientmods ├── modname - | ├── depends.txt - | ├── init.lua + │ ├── mod.conf + │ ├── init.lua └── another ### modname + The location of this directory. -### depends.txt -List of mods that have to be loaded before loading this mod. +### mod.conf + +An (optional) settings file that provides meta information about the mod. -A single line contains a single modname. +* `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. -Optional dependencies can be defined by appending a question mark -to a single modname. Their meaning is that if the specified mod -is missing, that does not prevent this mod from being loaded. +### `init.lua` -### 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. -### `sounds` -Media files (sounds) that will be transferred to the -client and will be available for use by the mod. +**NOTE**: Client mods currently can't provide and textures, sounds or models by +themselves. Any media referenced in function calls must already be loaded +(provided by mods that exist on the server). Naming convention for registered textual names ---------------------------------------------- @@ -142,7 +143,7 @@ The `:` prefix can also be used for maintaining backwards compatibility. Sounds ------ -**NOTE: max_hear_distance and connecting to objects is not implemented.** +**NOTE: Connecting sounds to objects is not implemented.** Only Ogg Vorbis files are supported. @@ -182,13 +183,11 @@ Examples of sound parameter tables: { 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, } @@ -631,7 +630,13 @@ Minetest namespace reference ### Utilities * `minetest.get_current_modname()`: returns the currently loading mod's name, when we are loading a mod -* `minetest.get_language()`: returns the currently set gettext language. +* `minetest.get_modpath(modname)`: returns virtual path of given mod including + the trailing separator. This is useful to load additional Lua files + contained in your mod: + e.g. `dofile(minetest.get_modpath(minetest.get_current_modname()) .. "stuff.lua")` +* `minetest.get_language()`: returns two strings + * the current gettext locale + * the current language code (the same as used for client-side translations) * `minetest.get_version()`: returns a table containing components of the engine version. Components: * `project`: Name of the project, eg, "Minetest" @@ -646,6 +651,11 @@ Minetest namespace reference * `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 +* `minetest.get_csm_restrictions()`: returns a table of `Flags` indicating the + restrictions applied to the current mod. + * If a flag in this table is set to true, the feature is RESTRICTED. + * Possible flags: `load_client_mods`, `chat_messages`, `read_itemdefs`, + `read_nodedefs`, `lookup_nodes`, `read_playerinfo` ### Logging * `minetest.debug(...)` @@ -731,8 +741,6 @@ Call these functions only at load time! * Optional: Variable number of arguments that are passed to `func` * `minetest.get_us_time()` * Returns time with microsecond precision. May not return wall time. -* `minetest.get_day_count()` - * Returns number days elapsed since world was created, accounting for time changes. * `minetest.get_timeofday()` * Returns the time of day: `0` for midnight, `0.5` for midday @@ -741,11 +749,46 @@ Call these functions only at load time! * Returns the node at the given position as table in the format `{name="node_name", param1=0, param2=0}`, returns `nil` for unloaded areas or flavor limited areas. +* `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.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.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_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_level(pos)` @@ -1072,6 +1115,32 @@ Can be obtained via `minetest.get_meta(pos)`. * `fields`: key-value storage * `inventory`: `{list1 = {}, ...}}` +### `Raycast` + +A raycast on the map. It works with selection boxes. +Can be used as an iterator in a for loop as: + + local ray = Raycast(...) + for pointed_thing in ray do + ... + end + +The map is loaded as the ray advances. If the map is modified after the +`Raycast` is created, the changes may or may not have an effect on the object. + +It can be created via `Raycast(pos1, pos2, objects, liquids)` or +`minetest.raycast(pos1, pos2, objects, liquids)` where: + +* `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. + ----------------- ### Definitions * `minetest.get_node_def(nodename)` diff --git a/doc/lua_api.txt b/doc/lua_api.txt index 907f47e73..bd95062a5 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -826,7 +826,7 @@ Examples of sound parameter tables: gain = 1.0, -- default loop = true, } - -- Play in a location + -- Play at a location { pos = {x = 1, y = 2, z = 3}, gain = 1.0, -- default @@ -839,34 +839,58 @@ Examples of sound parameter tables: 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,`. +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` ----------------- -* e.g. `""` -* e.g. `"default_place_node"` -* e.g. `{}` -* e.g. `{name = "default_place_node"}` -* e.g. `{name = "default_place_node", gain = 1.0}` -* e.g. `{name = "default_place_node", gain = 1.0, pitch = 1.0}` +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. - * `main_menu`: Looped sound in the main menu (gain = 1.0) * `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 ====================== @@ -924,7 +948,8 @@ Node paramtypes The functions of `param1` and `param2` are determined by certain fields in the node definition. -`param1` is reserved for the engine when `paramtype != "none"`: +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 @@ -941,19 +966,27 @@ node definition. * mesh * plantlike * plantlike_rooted - -`param2` is reserved for the engine when any of these are used: - -* `liquidtype = "flowing"` - * The level and some flags of the liquid is stored in `param2` -* `drawtype = "flowingliquid"` - * The drawn liquid level is read from `param2` -* `drawtype = "torchlike"` -* `drawtype = "signlike"` +* `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"` - * The rotation of the node is stored in `param2`. You can make this value - by using `minetest.dir_to_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 @@ -972,13 +1005,13 @@ node definition. * The height of the 'plantlike' section is stored in `param2`. * The height is (`param2` / 16) nodes. * `paramtype2 = "degrotate"` - * Only valid for "plantlike". The rotation of the node is stored in + * 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". The value of `param2` becomes a bitfield which - can be used to change how the client draws plantlike nodes. + * 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) @@ -1010,6 +1043,9 @@ node definition. * `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]. @@ -1260,6 +1296,11 @@ 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. @@ -1476,7 +1517,8 @@ Usage ----- Groups are stored in a table, having the group names with keys and the -group ratings as values. For example: +group ratings as values. Group ratings are integer values within the +range [-32767, 32767]. For example: -- Default dirt groups = {crumbly=3, soil=1} @@ -1923,6 +1965,9 @@ 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! @@ -2075,28 +2120,47 @@ Elements ### `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) +* `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) +* `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[<color>;<fullscreen>]` +### `bgcolor[<bgcolor>;<fullscreen>;<fbgcolor>]` -* Sets background color of formspec as `ColorString` -* If `true`, a fullscreen background is drawn and the color is ignored - (does not affect the size of the formspec) +* 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>]` @@ -2189,8 +2253,14 @@ Elements half a coordinate. With the old system, newlines are spaced 2/5 of an inventory slot. -### `vertlabel[<X>,<Y>;<label>]` +### `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 @@ -2334,16 +2404,40 @@ Elements ### `scrollbar[<X>,<Y>;<W>,<H>;<orientation>;<name>;<value>]` -* Show a scrollbar +* 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 this trackbar is set to (`0`-`1000`) +* 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[]` @@ -2404,16 +2498,16 @@ Elements * `span=<value>`: number of following columns to affect (default: infinite). -### `style[<name>;<prop1>;<prop2>;...]` +### `style[<name 1>,<name 2>,...;<prop1>;<prop2>;...]` -* Set the style for the named element `name`. +* Set the style for the named element(s) `name`. * Note: this **must** be before the element is defined. * See [Styling Formspecs]. -### `style_type[<type>;<prop1>;<prop2>;...]` +### `style_type[<type 1>,<type 2>,...;<prop1>;<prop2>;...]` -* Sets the style for all elements of type `type` which appear after this element. +* Sets the style for all elements of type(s) `type` which appear after this element. * See [Styling Formspecs]. Migrating to Real Coordinates @@ -2456,13 +2550,18 @@ Styling Formspecs Formspec elements can be themed using the style elements: - style[<name>;<prop1>;<prop2>;...] - style_type[<type>;<prop1>;<prop2>;...] + 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] @@ -2479,6 +2578,7 @@ Setting a property to nothing will reset it to the default value. For example: Some types may inherit styles from parent types. +* animated_image, inherits from image * button * button_exit, inherits from button * checkbox @@ -2492,17 +2592,27 @@ Some types may inherit styles from parent types. * label * vertlabel, inherits from field * image_button -* item_image_button, inherits from image_button +* item_image_button * tabheader ### Valid Properties -* button, button_exit +* 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. - * bgimg - standard image. Defaults to none. - * bgimg_pressed - image when pressed. Defaults to bgimg when not provided. + * 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. @@ -2518,19 +2628,127 @@ Some types may inherit styles from parent types. * 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. -* label, vertlabel +* image * noclip - boolean, set to true to allow the element to exceed formspec bounds. -* image_button - * alpha - boolean, whether to draw alpha in bgimg. Default true. - * border - boolean, draw border. Set to false to hide the bevelled button pane. Default false. - * noclip - boolean, set to true to allow the element to exceed formspec bounds. -* item_image_button - * border - boolean, draw border. Set to false to hide the bevelled button pane. Default false. + * 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 ========= @@ -2554,7 +2772,6 @@ Player Inventory lists * Is not created automatically, use `InvRef:set_size` * Is only used to enhance the empty hand's tool capabilities - Colors ====== @@ -2748,6 +2965,15 @@ Helper functions * `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 @@ -3530,7 +3756,7 @@ Methods ----------- A helper class for voxel areas. -It can be created via `VoxelArea:new{MinEdge=pmin, MaxEdge=pmax}`. +It can be created via `VoxelArea:new{MinEdge = pmin, MaxEdge = pmax}`. The coordinates are *inclusive*, like most other things in Minetest. ### Methods @@ -3561,6 +3787,28 @@ The coordinates are *inclusive*, like most other things in Minetest. `[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`. + @@ -3657,6 +3905,7 @@ Callbacks: * `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`) @@ -3802,6 +4051,8 @@ Utilities 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` @@ -3905,6 +4156,9 @@ Call these functions only at load time! * `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 @@ -3919,12 +4173,15 @@ Call these functions only at load time! * 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_ores()` - * Clears all ores currently registered. * `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. @@ -4073,6 +4330,7 @@ Call these functions only at load time! 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 @@ -4157,9 +4415,13 @@ Setting-related Authentication -------------- -* `minetest.string_to_privs(str)`: returns `{priv1=true,...}` -* `minetest.privs_to_string(privs)`: returns `"priv1,priv2,..."` - * Convert between two privilege representations +* `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` @@ -4200,8 +4462,8 @@ Authentication * `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 +`minetest.set_player_password`, `minetest.set_player_privs`, +`minetest.get_player_privs` and `minetest.auth_reload` call the authentication handler. Chat @@ -4456,16 +4718,25 @@ Environment access * `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 + * returns table containing path that can be walked on * returns a table of 3D points representing a path from `pos1` to `pos2` or - `nil`. + `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`: number of blocks to search in each direction using a - maximum metric. + * `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"` + * `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)` @@ -4625,9 +4896,11 @@ Item handling given `param2` value. * Returns `nil` if the given `paramtype2` does not contain color information. -* `minetest.get_node_drops(nodename, toolname)` - * Returns list of item names. - * **Note**: This will be removed or modified in a future version. +* `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` @@ -4635,8 +4908,9 @@ Item handling `{stack1, stack2, stack3, stack4, stack 5, stack 6, stack 7, stack 8, stack 9}` * `output.item` = `ItemStack`, if unsuccessful: empty `ItemStack` * `output.time` = a number, if unsuccessful: `0` - * `output.replacements` = list of `ItemStack`s that couldn't be placed in - `decremented_input.items` + * `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) @@ -4697,33 +4971,36 @@ Rollback * Revert latest actions of someone * `actor`: `"player:<name>"`, also `"liquid"`. -Defaults for the `on_*` item definition functions -------------------------------------------------- - -These functions return the leftover itemstack. +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, success` + * 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 -* `minetest.item_place(itemstack, placer, pointed_thing, param2)` - * Use one of the above based on what the item 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, success` + * `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 -* `minetest.item_eat(hp_change, replace_with_item)` - * Eat 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. Can be `nil` - * See `minetest.do_item_eat` + different spot. Defaults for the `on_punch` and `on_dig` node definition callbacks ------------------------------------------------------------------ @@ -4737,10 +5014,15 @@ Defaults for the `on_punch` and `on_dig` node definition callbacks Sounds ------ -* `minetest.sound_play(spec, parameters)`: returns a handle +* `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. @@ -4785,13 +5067,16 @@ Server Bans ---- -* `minetest.get_ban_list()`: returns the ban list - (same as `minetest.get_ban_description("")`). -* `minetest.get_ban_description(ip_or_name)`: returns ban description (string) -* `minetest.ban_player(name)`: ban a player -* `minetest.unban_player_or_ip(name)`: unban player or IP address -* `minetest.kick_player(name, [reason])`: disconnect a player with a optional +* `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 --------- @@ -4999,10 +5284,16 @@ Misc. * Convert a table containing tables, strings, numbers, booleans and `nil`s into string form readable by `minetest.deserialize` * Example: `serialize({foo='bar'})`, returns `'return { ["foo"] = "bar" }'` -* `minetest.deserialize(string)`: returns a table - * Convert a string returned by `minetest.deserialize` into a table +* `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, but they cannot access the global 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` @@ -5446,8 +5737,21 @@ Can be gotten via `minetest.get_node_timer(pos)`. ----------- 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. -This is basically a reference to a C++ `ServerActiveObject` ### Methods @@ -5466,6 +5770,9 @@ This is basically a reference to a C++ `ServerActiveObject` * `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. @@ -5515,7 +5822,10 @@ This is basically a reference to a C++ `ServerActiveObject` #### Lua entity only (no-op for other objects) -* `remove()`: remove object (after returning from Lua) +* `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)` @@ -5586,6 +5896,7 @@ This is basically a reference to a C++ `ServerActiveObject` * `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. @@ -5668,15 +5979,90 @@ This is basically a reference to a C++ `ServerActiveObject` * `hud_set_hotbar_selected_image(texturename)` * sets image for selected item of hotbar * `hud_get_hotbar_selected_image`: returns texturename -* `set_sky(bgcolor, type, {texture names}, clouds)` - * `bgcolor`: ColorSpec, defaults to white - * `type`: Available types: - * `"regular"`: Uses 0 textures, `bgcolor` ignored - * `"skybox"`: Uses 6 textures, `bgcolor` used - * `"plain"`: Uses 0 textures, `bgcolor` used - * `clouds`: Boolean for whether clouds appear in front of `"skybox"` or - `"plain"` custom skyboxes (default: `true`) -* `get_sky()`: returns bgcolor, type, table of textures, clouds +* `set_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"` + sky during the day. (default: `#8cbafa`) + * `day_horizon`: ColorSpec, for the bottom half of the + `"regular"` sky during the day. (default: `#9bc1f0`) + * `dawn_sky`: ColorSpec, for the top half of the `"regular"` + sky during dawn/sunset. (default: `#b4bafa`) + The resulting sky color will be a darkened version of the ColorSpec. + Warning: The darkening of the ColorSpec is subject to change. + * `dawn_horizon`: ColorSpec, for the bottom half of the `"regular"` + sky during dawn/sunset. (default: `#bac1f0`) + The resulting sky color will be a darkened version of the ColorSpec. + Warning: The darkening of the ColorSpec is subject to change. + * `night_sky`: ColorSpec, for the top half of the `"regular"` + sky during the night. (default: `#006aff`) + The resulting sky color will be a dark version of the ColorSpec. + Warning: The darkening of the ColorSpec is subject to change. + * `night_horizon`: ColorSpec, for the bottom half of the `"regular"` + sky during the night. (default: `#4090ff`) + The resulting sky color will be a dark version of the ColorSpec. + Warning: The darkening of the ColorSpec is subject to change. + * `indoors`: ColorSpec, for when you're either indoors or + underground. Only applies to the `"regular"` sky. + (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"` sky types. + (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`) @@ -5875,6 +6261,10 @@ It can be created via `Settings(filename)`. * `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"""`. @@ -5949,12 +6339,11 @@ Player properties need to be saved manually. -- Defaults to 1.625. physical = true, + -- Collide with `walkable` nodes. collide_with_objects = true, -- Collide with other objects if physical = true - weight = 5, - collisionbox = {-0.5, 0.0, -0.5, 0.5, 1.0, 0.5}, -- Default selectionbox = {-0.5, 0.0, -0.5, 0.5, 1.0, 0.5}, -- Selection box uses collision box dimensions when not set. @@ -5988,7 +6377,8 @@ Player properties need to be saved manually. -- Multipliers for the visual size. If `z` is not specified, `x` will be used -- to scale the entity along both horizontal axes. - mesh = "model", + mesh = "model.obj", + -- File name of mesh when using "mesh" visual textures = {}, -- Number of required textures depends on visual. @@ -6018,14 +6408,20 @@ Player properties need to be saved manually. -- 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. @@ -6275,6 +6671,7 @@ Used by `minetest.register_node`, `minetest.register_craftitem`, and 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 @@ -6300,9 +6697,14 @@ Used by `minetest.register_node`, `minetest.register_craftitem`, and -- upon digging. Server will always update actual result shortly. sound = { - breaks = "default_tool_break", -- tools only - place = <SimpleSoundSpec>, + -- 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), @@ -6311,9 +6713,9 @@ Used by `minetest.register_node`, `minetest.register_craftitem`, and -- default: minetest.item_place on_secondary_use = function(itemstack, user, pointed_thing), - -- Same as on_place but called when pointing at nothing. + -- Same as on_place but called when not pointing at a node. -- The user may be any ObjectRef or nil. - -- pointed_thing: always { type = "nothing" } + -- default: nil on_drop = function(itemstack, dropper, pos), -- Shall drop item and return the leftover itemstack. @@ -6360,8 +6762,9 @@ Used by `minetest.register_node`. -- Supported for drawtypes "plantlike", "signlike", "torchlike", -- "firelike", "mesh". -- For plantlike and firelike, the image will start at the bottom of the - -- node, for the other drawtypes the image will be centered on the node. - -- Note that positioning for "torchlike" may still change. + -- 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 @@ -6471,7 +6874,8 @@ Used by `minetest.register_node`. -- Tells connected nodebox nodes to connect only to these sides of this -- node - mesh = "model", + mesh = "model.obj", + -- File name of mesh when using "mesh" drawtype selection_box = { type = "fixed", @@ -6511,12 +6915,33 @@ Used by `minetest.register_node`. -- 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>, - dig = <SimpleSoundSpec>, -- "__group" = group-based sound (default) + -- 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 = "", @@ -7201,6 +7626,9 @@ Used by `Player:hud_add`. Returned by `Player:hud_get`. 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 diff --git a/doc/menu_lua_api.txt b/doc/menu_lua_api.txt index a2f9c3f5b..4861ed0d9 100644 --- a/doc/menu_lua_api.txt +++ b/doc/menu_lua_api.txt @@ -1,4 +1,4 @@ -Minetest Lua Mainmenu API Reference 5.1.0 +Minetest Lua Mainmenu API Reference 5.2.0 ========================================= Introduction @@ -244,3 +244,11 @@ Limitations of Async operations -Limited set of available functions e.g. No access to functions modifying menu like core.start,core.close, core.show_path_select_dialog + +Background music +---------------- +The main menu supports background music. +It looks for a `main_menu` sound in `$USER_PATH/sounds`. The same naming +conventions as for normal sounds apply. +This means the player can add a custom sound. +It will be played in the main menu (gain = 1.0), looped. diff --git a/doc/texture_packs.txt b/doc/texture_packs.txt index 40fdf2eeb..7ab0aca94 100644 --- a/doc/texture_packs.txt +++ b/doc/texture_packs.txt @@ -63,6 +63,7 @@ by texture packs. All existing fallback textures can be found in the directory ### Gameplay textures * `bubble.png`: the bubble texture when the player is drowning + (default size: 12×12) * `crack_anylength.png`: node overlay texture when digging @@ -74,6 +75,7 @@ by texture packs. All existing fallback textures can be found in the directory * `halo.png`: used for the node highlighting mesh * `heart.png`: used to display the health points of the player + (default size: 12×12) * `minimap_mask_round.png`: round minimap mask, white gets replaced by the map * `minimap_mask_square.png`: mask used for the square minimap @@ -102,6 +104,9 @@ by texture packs. All existing fallback textures can be found in the directory * `wieldhand.png`: texture of the wieldhand +Note: The default textures of `player.png`, `player_back.png` and `wieldhand.png` +are placeholders intended to be overwritten by the game. + ### Mainmenu textures * `menu_bg.png`: used as mainmenu background when the clouds are disabled diff --git a/doc/world_format.txt b/doc/world_format.txt index 7cbf13af6..73a03e5ee 100644 --- a/doc/world_format.txt +++ b/doc/world_format.txt @@ -13,12 +13,6 @@ The block serialization version does not fully specify every aspect of this format; if compliance with this format is to be checked, it needs to be done by detecting if the files and data indeed follows it. -Legacy stuff -============= -Data can, in theory, be contained in the flat file directory structure -described below in Version 17, but it is not officially supported. Also you -may stumble upon all kinds of oddities in not-so-recent formats. - Files ====== Everything is contained in a directory, the name of which is freeform, but @@ -500,10 +494,10 @@ Static objects are persistent freely moving objects in the world. Object types: 1: Test object 2: Item -3: Rat (deprecated) -4: Oerkki (deprecated) -5: Firefly (deprecated) -6: MobV2 (deprecated) +3: Rat (obsolete) +4: Oerkki (obsolete) +5: Firefly (obsolete) +6: MobV2 (obsolete) 7: LuaEntity 1: Item: @@ -568,107 +562,3 @@ Empty EndInventoryList EndInventory --- - -============================================== -Minetest World Format used as of 2011-05 or so -============================================== - -Map data serialization format version 17. - -0.3.1 does not use this format, but a more recent one. This exists here for -historical reasons. - -Directory structure: -sectors/XXXXZZZZ or sectors2/XXX/ZZZ -XXXX, ZZZZ, XXX and ZZZ being the hexadecimal X and Z coordinates. -Under these, the block files are stored, called YYYY. - -There also exists files map_meta.txt and chunk_meta, that are used by the -generator. If they are not found or invalid, the generator will currently -behave quite strangely. - -The MapBlock file format (sectors2/XXX/ZZZ/YYYY): -------------------------------------------------- - -NOTE: Byte order is MSB first. - -u8 version -- map format version number, this one is version 17 - -u8 flags -- Flag bitmasks: - - 0x01: is_underground: Should be set to 0 if there will be no light - obstructions above the block. If/when sunlight of a block is updated and - there is no block above it, this value is checked for determining whether - sunlight comes from the top. - - 0x02: day_night_differs: Whether the lighting of the block is different on - day and night. Only blocks that have this bit set are updated when day - transforms to night. - - 0x04: lighting_expired: If true, lighting is invalid and should be updated. - If you can't calculate lighting in your generator properly, you could try - setting this 1 to everything and setting the uppermost block in every - sector as is_underground=0. I am quite sure it doesn't work properly, - though. - -zlib-compressed map data: -- content: - u8[4096]: content types - u8[4096]: param1 values - u8[4096]: param2 values - -zlib-compressed node metadata -- content: - u16 version (=1) - u16 count of metadata - foreach count: - u16 position (= p.Z*MAP_BLOCKSIZE*MAP_BLOCKSIZE + p.Y*MAP_BLOCKSIZE + p.X) - u16 type_id - u16 content_size - u8[content_size] misc. stuff contained in the metadata - -u16 mapblockobject_count -- always write as 0. -- if read != 0, just fail. - -foreach mapblockobject_count: - - deprecated, should not be used. Length of this data can only be known by - properly parsing it. Just hope not to run into any of this. - -u8 static object version: -- currently 0 - -u16 static_object_count - -foreach static_object_count: - u8 type (object type-id) - s32 pos_x * 1000 - s32 pos_y * 1000 - s32 pos_z * 1000 - u16 data_size - u8[data_size] data - -u32 timestamp -- Timestamp when last saved, as seconds from starting the game. -- 0xffffffff = invalid/unknown timestamp, nothing will be done with the time - difference when loaded (recommended) - -Node metadata format: ---------------------- - -Sign metadata: - u16 string_len - u8[string_len] string - -Furnace metadata: - TBD - -Chest metadata: - TBD - -Locking Chest metadata: - u16 string_len - u8[string_len] string - TBD - -// END - |