X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=doc%2Flua_api.txt;h=bb94829a5af3baccdaa2b03e0c6132e8052a1cce;hb=216728cc5e83ff6c4f13a52821ff3c24b1e315e9;hp=e0c895c97c7c75e1b2b3fdd53546ecba096edba1;hpb=4b4513a67d9fc426d0f33798d0810a3a0594baaf;p=dragonfireclient.git diff --git a/doc/lua_api.txt b/doc/lua_api.txt index e0c895c97..bb94829a5 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -62,12 +62,12 @@ Where `` 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` + * `name`: Required, a human readable title to address the game, e.g. `name = Minetest`. * `description`: Short description to be shown in the content tab * `allowed_mapgens = ` e.g. `allowed_mapgens = v5,v6,flat` - Mapgens not in this list are removed from the list of mapgens for - the game. + Mapgens not in this list are removed from the list of mapgens for the + game. If not specified, all mapgens are allowed. * `disallowed_mapgens = ` e.g. `disallowed_mapgens = v5,v6,flat` @@ -79,6 +79,10 @@ The game directory can contain the following files: e.g. `disallowed_mapgen_settings = mgv5_spflags` These settings are hidden for this game in the world creation dialog and game start menu. + * `author`: The author of the game. It only appears when downloaded from + ContentDB. + * `release`: Ignore this: Should only ever be set by ContentDB, as it is + an internal ID used to track versions. * `minetest.conf`: Used to set default settings when running this game. * `settingtypes.txt`: @@ -134,9 +138,15 @@ 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. +* `name`: The modpack name. Allows Minetest to determine the modpack name even + if the folder is wrongly named. * `description`: Description of mod to be shown in the Mods tab of the main menu. +* `author`: The author of the modpack. It only appears when downloaded from + ContentDB. +* `release`: Ignore this: Should only ever be set by ContentDB, as it is an + internal ID used to track versions. +* `title`: A human-readable title to address the modpack. Note: to support 0.4.x, please also create an empty modpack.txt file. @@ -152,7 +162,12 @@ Mod directory structure │   ├── models │   ├── textures │   │   ├── modname_stuff.png - │   │   └── modname_something_else.png + │   │   ├── modname_stuff_normal.png + │   │   ├── modname_something_else.png + │   │   ├── subfolder_foo + │   │   │ ├── modname_more_stuff.png + │   │   │ └── another_subfolder + │   │   └── bar_subfolder │   ├── sounds │   ├── media │   ├── locale @@ -176,6 +191,11 @@ A `Settings` file that provides meta information about the mod. 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. +* `author`: The author of the mod. It only appears when downloaded from + ContentDB. +* `release`: Ignore this: Should only ever be set by ContentDB, as it is an + internal ID used to track versions. +* `title`: A human-readable title to address the mod. Note: to support 0.4.x, please also provide depends.txt. @@ -221,18 +241,23 @@ 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` +### `textures`, `sounds`, `media`, `models`, `locale` Media files (textures, sounds, whatever) that will be transferred to the -client and will be available for use by the mod. +client and will be available for use by the mod and translation files for +the clients (see [Translations]). -### `locale` +It is suggested to use the folders for the purpose they are thought for, +eg. put textures into `textures`, translation files into `locale`, +models for entities or meshnodes into `models` et cetera. -Translation files for the clients. (See [Translations]) +These folders and subfolders can contain subfolders. +Subfolders with names starting with `_` or `.` are ignored. +If a subfolder contains a media file with the same name as a media file +in one of its parents, the parent's file is used. + +Although it is discouraged, a mod can overwrite a media file of any mod that it +depends on by supplying a file with an equal name. Naming conventions ------------------ @@ -378,11 +403,14 @@ 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. +to let the client generate textures on-the-fly. +The modifiers are applied directly in sRGB colorspace, +i.e. without gamma-correction. ### Texture overlaying @@ -780,7 +808,7 @@ Example (colored grass block): -- 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}}, + {name = "default_grass_side.png"}}, -- Global color, used in inventory color = "green", -- Palette in the world @@ -989,10 +1017,13 @@ The function of `param2` is determined by `paramtype2` in node definition. * `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 + * Bits 0-2: Liquid level (0-7). The higher, the more liquid is in this node; + see `minetest.get_node_level`, `minetest.set_node_level` and `minetest.add_node_level` + to access/manipulate the content of this field * Bit 3: If set, liquid is flowing downwards (no graphical effect) * `paramtype2 = "wallmounted"` - * Supported drawtypes: "torchlike", "signlike", "normal", "nodebox", "mesh" + * Supported drawtypes: "torchlike", "signlike", "plantlike", + "plantlike_rooted", "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 @@ -1018,9 +1049,9 @@ The function of `param2` is determined by `paramtype2` in node definition. * 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 + * Valid for `plantlike` and `mesh` drawtypes. The rotation of the node is + stored in `param2`. + * Values range 0–239. The value stored in `param2` is multiplied by 1.5 to get the actual rotation in degrees of the node. * `paramtype2 = "meshoptions"` * Only valid for "plantlike" drawtype. `param2` encodes the shape and @@ -1054,10 +1085,20 @@ The function of `param2` is determined by `paramtype2` in node definition. 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. + drawtypes. "glasslike_framed_optional" nodes are only affected if the + "Connected Glass" setting is enabled. + * Bits 0-5 define 64 levels of internal liquid, 0 being empty and 63 being + full. + * Bits 6 and 7 modify the appearance of the frame and node faces. One or + both of these values may be added to `param2`: + * 64 - Makes the node not connect with neighbors above or below it. + * 128 - Makes the node not connect with neighbors to its sides. * Liquid texture is defined using `special_tiles = {"modname_tilename.png"}` +* `paramtype2 = "colordegrotate"` + * Same as `degrotate`, but with colors. + * The first (most-significant) three bits of `param2` tells which color + is picked from the palette. The palette should have 8 pixels. + * Remaining 5 bits store rotation in range 0–23 (i.e. in 15° steps) * `paramtype2 = "none"` * `param2` will not be used by the engine and can be used to store an arbitrary value @@ -1077,8 +1118,20 @@ Look for examples in `games/devtest` or `games/minetest_game`. * Invisible, uses no texture. * `liquid` * The cubic source node for a liquid. + * Faces bordering to the same node are never rendered. + * Connects to node specified in `liquid_alternative_flowing`. + * Use `backface_culling = false` for the tiles you want to make + visible when inside the node. * `flowingliquid` * The flowing version of a liquid, appears with various heights and slopes. + * Faces bordering to the same node are never rendered. + * Connects to node specified in `liquid_alternative_source`. + * Node textures are defined with `special_tiles` where the first tile + is for the top and bottom faces and the second tile is for the side + faces. + * `tiles` is used for the item/inventory/wield image rendering. + * Use `backface_culling = false` for the special tiles you want to make + visible when inside the node * `glasslike` * Often used for partially-transparent nodes. * Only external sides of textures are visible. @@ -1105,14 +1158,20 @@ Look for examples in `games/devtest` or `games/minetest_game`. 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. + * If `paramtype2="[color]wallmounted": + * 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. + * If `paramtype2="none"`: + * Will be rendered as if placed on top of a node (see + above) and only the first texture is used. * `signlike` * A single texture parallel to, and mounted against, the top, underside or side of a node. + * If `paramtype2="[color]wallmounted", it rotates according to `param2` + * If `paramtype2="none"`, it will always be on the floor. * `plantlike` * Two vertical and diagonal textures at right-angles to each other. * See `paramtype2 = "meshoptions"` above for other options. @@ -1145,12 +1204,17 @@ Look for examples in `games/devtest` or `games/minetest_game`. * `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. + `plantlike` extension above + * If `paramtype2="leveled", the `plantlike` extension has a height + of `param2 / 16` nodes, otherwise it's the height of 1 node + * If `paramtype2="wallmounted"`, the `plantlike` extension + will be at one of the corresponding 6 sides of the base cube. + Also, the base cube rotates like a `normal` cube would * 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}},` + `special_tiles = {{name = "default_papyrus.png"}},` `*_optional` drawtypes need less rendering time if deactivated (always client-side). @@ -1220,6 +1284,9 @@ A box of a regular node would look like: {-0.5, -0.5, -0.5, 0.5, 0.5, 0.5}, +To avoid collision issues, keep each value within the range of +/- 1.45. +This also applies to leveled nodeboxes, where the final height shall not +exceed this soft limit. @@ -1414,7 +1481,32 @@ Same as `image`, but does not accept a `position`; the position is instead deter * `world_pos`: World position of the waypoint. * `offset`: offset in pixels from position. +### `compass` + +Displays an image oriented or translated according to current heading direction. + +* `size`: The size of this element. Negative values represent percentage + of the screen; e.g. `x=-100` means 100% (width). +* `scale`: Scale of the translated image (used only for dir = 2 or dir = 3). +* `text`: The name of the texture to use. +* `alignment`: The alignment of the image. +* `offset`: Offset in pixels from position. +* `dir`: How the image is rotated/translated: + * 0 - Rotate as heading direction + * 1 - Rotate in reverse direction + * 2 - Translate as landscape direction + * 3 - Translate in reverse direction + +If translation is chosen, texture is repeated horizontally to fill the whole element. + +### `minimap` +Displays a minimap on the HUD. + +* `size`: Size of the minimap to display. Minimap should be a square to avoid + distortion. +* `alignment`: The alignment of the minimap. +* `offset`: offset in pixels from position. Representations of simple things ================================ @@ -1424,6 +1516,9 @@ Position/vector {x=num, y=num, z=num} + Note: it is highly recommended to construct a vector using the helper function: + vector.new(num, num, num) + For helper functions see [Spatial Vectors]. `pointed_thing` @@ -1491,15 +1586,37 @@ since, by default, no schematic attributes are set. Items ===== +Items are things that can be held by players, dropped in the map and +stored in inventories. +Items come in the form of item stacks, which are collections of equal +items that occupy a single inventory slot. + 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 +* Node: Placeable item form of a node in the world's voxel grid +* Tool: Has a changable wear property but cannot be stacked +* Craftitem: Has no special properties + +Every registered node (the voxel in the world) has a corresponding +item form (the thing in your inventory) that comes along with it. +This item form can be placed which will create a node in the +world (by default). +Both the 'actual' node and its item form share the same identifier. +For all practical purposes, you can treat the node and its item form +interchangeably. We usually just say 'node' to the item form of +the node as well. + +Note the definition of tools is purely technical. The only really +unique thing about tools is their wear, and that's basically it. +Beyond that, you can't make any gameplay-relevant assumptions +about tools or non-tools. It is perfectly valid to register something +that acts as tool in a gameplay sense as a craftitem, and vice-versa. + +Craftitems can be used for items that neither need to be a node +nor a tool. Amount and wear --------------- @@ -1510,7 +1627,9 @@ 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. +a higher wear. Non-tools technically also have a wear property, +but it is always 0. There is also a special 'toolrepair' crafting +recipe that is only available to tools. Item formats ------------ @@ -1564,8 +1683,8 @@ 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 +properties of a thing (item, node, armor of entity, tool capabilities) +in such a way that the engine and other mods can can interact with the thing without actually knowing what the thing is. Usage @@ -1606,17 +1725,17 @@ 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. +The rating is the percentage of damage caused by items 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 of tool capabilities +--------------------------- -Groups in tools define which groups of nodes and entities they are -effective towards. +Groups in tool capabilities define which groups of nodes and entities they +are effective towards. Groups in crafting recipes -------------------------- @@ -1648,7 +1767,7 @@ 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 +### Node and item groups * `not_in_creative_inventory`: (*) Special group for inventory mods to indicate that the item should be hidden in item lists. @@ -1667,7 +1786,15 @@ to games. * `3`: the node always gets the digging time 0 seconds (torch) * `disable_jump`: Player (and possibly other things) cannot jump from node or if their feet are in the node. Note: not supported for `new_move = false` -* `fall_damage_add_percent`: damage speed = `speed * (1 + value/100)` +* `fall_damage_add_percent`: modifies the fall damage suffered when hitting + the top of this node. There's also an armor group with the same name. + The final player damage is determined by the following formula: + damage = + collision speed + * ((node_fall_damage_add_percent + 100) / 100) -- node group + * ((player_fall_damage_add_percent + 100) / 100) -- player armor group + - (14) -- constant tolerance + Negative damage values are discarded as no damage. * `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. @@ -1676,7 +1803,7 @@ to games. 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] + * See also: `leveldiff` in [Tool Capabilities] * `slippery`: Players and items will slide on the node. Slipperiness rises steadily with `slippery` value, starting at 1. @@ -1687,11 +1814,15 @@ to games. `"toolrepair"` crafting recipe -### `ObjectRef` groups +### `ObjectRef` armor 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. + will also hide the integrated HUD status bars for players. It is + automatically set to all players when damage is disabled on the server and + cannot be reset (subject to change). +* `fall_damage_add_percent`: Modifies the fall damage suffered by players + when they hit the ground. It is analog to the node group with the same + name. See the node group above for the exact calculation. * `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. @@ -1703,8 +1834,8 @@ 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 +* `snappy`: something that can be cut using things like scissors, shears, + bolt cutters and the like, 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. @@ -1713,7 +1844,7 @@ Known damage and digging time defining groups 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 + digging speed of an item if it can dig at a faster speed than this suggests for the hand. Examples of custom groups @@ -1739,50 +1870,62 @@ 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. +The `level` group is used to limit the toughness of nodes an item capable +of digging 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 +Items 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. +groups to enable interaction with items. -Tools -===== +Tool Capabilities +================= -Tools definition ----------------- +'Tool capabilities' is a property of items that defines two things: + +1) Which nodes it can dig and how fast +2) Which objects it can hurt by punching and by how much + +Tool capabilities are available for all items, not just tools. +But only tools can receive wear from digging and punching. -Tools define: +Missing or incomplete tool capabilities will default to the +player's hand. + +Tool capabilities definition +---------------------------- + +Tool capabilities define: * Full punch interval * Maximum drop level -* For an arbitrary list of groups: +* For an arbitrary list of node groups: * Uses (until the tool breaks) - * Maximum level (usually `0`, `1`, `2` or `3`) - * Digging times - * Damage groups + * Maximum level (usually `0`, `1`, `2` or `3`) + * Digging times +* Damage groups +* Punch attack uses (until the tool breaks) ### 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 +When used as a weapon, the item will do full damage if this time is spent +between punches. If e.g. half the time is spent, the item 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). +Suggests the maximum level of node, when dug with the item, that will drop +its 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 +### Uses (tools only) 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 @@ -1794,9 +1937,11 @@ node's `level` group. The node cannot be dug if `leveldiff` is less than zero. * `uses=10, leveldiff=1`: actual uses: 30 * `uses=10, leveldiff=2`: actual uses: 90 +For non-tools, this has no effect. + ### Maximum level -Tells what is the maximum level of a node of this group that the tool will +Tells what is the maximum level of a node of this group that the item will be able to dig. ### Digging times @@ -1805,7 +1950,7 @@ 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` +result in the item 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. @@ -1817,8 +1962,19 @@ i.e. players can more quickly click the nodes away instead of holding LMB. List of damage for groups of entities. See [Entity damage mechanism]. -Example definition of the capabilities of a tool ------------------------------------------------- +### Punch attack uses (tools only) + +Determines how many uses (before breaking) the tool has when dealing damage +to an object, when the full punch interval (see above) was always +waited out fully. + +Wear received by the tool is proportional to the time spent, scaled by +the full punch interval. + +For non-tools, this has no effect. + +Example definition of the capabilities of an item +------------------------------------------------- tool_capabilities = { full_punch_interval=1.5, @@ -1829,7 +1985,7 @@ Example definition of the capabilities of a tool damage_groups = {fleshy=2}, } -This makes the tool be able to dig nodes that fulfil both of these: +This makes the item capable of digging nodes that fulfil both of these: * Have the `crumbly` group * Have a `level` group less or equal to `2` @@ -1973,8 +2129,10 @@ 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`. +* `description`: Set the item stack's description. + See also: `get_description` in [`ItemStack`] +* `short_description`: Set the item stack's short description. + See also: `get_short_description` in [`ItemStack`] * `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. @@ -2057,6 +2215,22 @@ Examples list[current_player;craft;3,0;3,3;] list[current_player;craftpreview;7,1;1,1;] +Version History +--------------- + +* FORMSPEC VERSION 1: + * (too much) +* FORMSPEC VERSION 2: + * Forced real coordinates + * background9[]: 9-slice scaling parameters +* FORMSPEC VERSION 3: + * Formspec elements are drawn in the order of definition + * bgcolor[]: use 3 parameters (bgcolor, formspec (now an enum), fbgcolor) + * box[] and image[] elements enable clipping by default + * new element: scroll_container[] +* FORMSPEC VERSION 4: + * Allow dropdown indexing events + Elements -------- @@ -2068,6 +2242,7 @@ Elements * Clients older than this version can neither show newer elements nor display elements with new arguments correctly. * Available since feature `formspec_version_element`. +* See also: [Version History] ### `size[,,]` @@ -2152,7 +2327,8 @@ Elements * 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. + slots is one-fourth the size of an inventory slot by default. Also see + [Styling Formspecs] for changing the size of slots and spacing. ### `list[;;,;,;]` @@ -2220,6 +2396,22 @@ Elements * `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`. +### `model[,;,;;;;;;;;]` + +* Show a mesh model. +* `name`: Element name that can be used for styling +* `mesh`: The mesh model to use. +* `textures`: The mesh textures to use according to the mesh materials. + Texture names must be separated by commas. +* `rotation {X,Y}` (Optional): Initial rotation of the camera. + The axes are euler angles in degrees. +* `continuous` (Optional): Whether the rotation is continuous. Default `false`. +* `mouse control` (Optional): Whether the model can be controlled with the mouse. Default `true`. +* `frame loop range` (Optional): Range of the animation frames. + * Defaults to the full range of all available frames. + * Syntax: `,` +* `animation speed` (Optional): Sets the animation speed. Default 0 FPS. + ### `item_image[,;,;]` * Show an inventory image of registered item/node @@ -2442,6 +2634,8 @@ Elements * Simple colored box * `color` is color specified as a `ColorString`. If the alpha component is left blank, the box will be semitransparent. + If the color is not specified, the box will use the options specified by + its style. If the color is specified, all styling options will be ignored. ### `dropdown[,;;;,, ...,;;]` @@ -2582,7 +2776,7 @@ Elements * `span=`: number of following columns to affect (default: infinite). -### `style[,;;;...]` +### `style[,,...;;;...]` * Set the style for the element(s) matching `selector` by name. * `selector` can be one of: @@ -2595,7 +2789,7 @@ Elements * See [Styling Formspecs]. -### `style_type[,;;;...]` +### `style_type[,,...;;;...]` * Set the style for the element(s) matching `selector` by type. * `selector` can be one of: @@ -2668,10 +2862,10 @@ Styling Formspecs Formspec elements can be themed using the style elements: - style[,;;;...] - style[:,:;;;...] - style_type[,;;;...] - style_type[:,:;;;...] + style[,,...;;;...] + style[:,:,...;;;...] + style_type[,,...;;;...] + style_type[:,:,...;;;...] Where a prop is: @@ -2708,21 +2902,25 @@ 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 +* box * button * button_exit, inherits from button * checkbox -* scrollbar -* table -* textlist * dropdown * field -* pwdfield, inherits from field -* textarea -* label -* vertlabel, inherits from field +* image * image_button * item_image_button +* label +* list +* model +* pwdfield, inherits from field +* scrollbar * tabheader +* table +* textarea +* textlist +* vertlabel, inherits from label ### Valid Properties @@ -2731,7 +2929,18 @@ Some types may inherit styles from parent types. * 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 + * Defaults to false in formspec_version version 3 or higher + * **Note**: `colors`, `bordercolors`, and `borderwidths` accept multiple input types: + * Single value (e.g. `#FF0`): All corners/borders. + * Two values (e.g. `red,#FFAAFF`): top-left and bottom-right,top-right and bottom-left/ + top and bottom,left and right. + * Four values (e.g. `blue,#A0F,green,#FFFA`): top-left/top and rotates clockwise. + * These work similarly to CSS borders. + * colors - `ColorString`. Sets the color(s) of the box corners. Default `black`. + * bordercolors - `ColorString`. Sets the color(s) of the borders. Default `black`. + * borderwidths - Integer. Sets the width(s) of the borders in pixels. If the width is + negative, the border will extend inside the box, whereas positive extends outside + the box. A width of zero results in no border; this is default. * button, button_exit, image_button, item_image_button * alpha - boolean, whether to draw alpha in bgimg. Default true. * bgcolor - color, sets button tint. @@ -2764,23 +2973,24 @@ Some types may inherit styles from parent types. * noclip - boolean, set to true to allow the element to exceed formspec bounds. * padding - rect, adds space between the edges of the button and the content. This value is relative to bgimg_middle. + * sound - a sound to be played when triggered. * 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 - * font - Sets font type. See button `font` property for more information. - * font_size - Sets font size. See button `font_size` property for more information. - * noclip - boolean, set to true to allow the element to exceed formspec bounds. + * sound - a sound to be played when triggered. * dropdown * noclip - boolean, set to true to allow the element to exceed formspec bounds. + * sound - a sound to be played when the entry is changed. * field, pwdfield, textarea * border - set to false to hide the textbox background and border. Default true. * font - Sets font type. See button `font` property for more information. * font_size - Sets font size. See button `font_size` property for more information. * noclip - boolean, set to true to allow the element to exceed formspec bounds. * textcolor - color. Default white. +* model + * bgcolor - color, sets background color. + * noclip - boolean, set to true to allow the element to exceed formspec bounds. + * Default to false in formspec_version version 3 or higher * image * noclip - boolean, set to true to allow the element to exceed formspec bounds. * Default to false in formspec_version version 3 or higher @@ -2790,6 +3000,10 @@ Some types may inherit styles from parent types. * font - Sets font type. See button `font` property for more information. * font_size - Sets font size. See button `font_size` property for more information. * noclip - boolean, set to true to allow the element to exceed formspec bounds. +* list + * noclip - boolean, set to true to allow the element to exceed formspec bounds. + * size - 2d vector, sets the size of inventory slots in coordinates. + * spacing - 2d vector, sets the space between inventory slots in coordinates. * image_button (additional properties) * fgimg - standard image. Defaults to none. * fgimg_hovered - image when hovered. Defaults to fgimg when not provided. @@ -2797,9 +3011,17 @@ Some types may inherit styles from parent types. * fgimg_pressed - image when pressed. Defaults to fgimg when not provided. * This is deprecated, use states instead. * NOTE: The parameters of any given image_button will take precedence over fgimg/fgimg_pressed + * sound - a sound to be played when triggered. +* scrollbar + * noclip - boolean, set to true to allow the element to exceed formspec bounds. * tabheader * noclip - boolean, set to true to allow the element to exceed formspec bounds. + * sound - a sound to be played when a different tab is selected. * textcolor - color. Default white. +* table, textlist + * font - Sets font type. See button `font` property for more information. + * font_size - Sets font size. See button `font_size` property for more information. + * noclip - boolean, set to true to allow the element to exceed formspec bounds. ### Valid States @@ -2818,6 +3040,9 @@ Some tags can enclose text, they open with `` and close with `...` @@ -2953,9 +3178,8 @@ Colors 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. +To specify the value of the alpha channel, append `#A` or `#AA` to the end of +the color name (e.g. `colorname#08`). `ColorSpec` ----------- @@ -3010,28 +3234,60 @@ 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}`. +However, one should *never* create a vector manually as above, such misbehavior +is deprecated. The vector helpers set a metatable for the created vectors which +allows indexing with numbers, calling functions directly on vectors and using +operators (like `+`). Furthermore, the internal implementation might change in +the future. +Old code might still use vectors without metatables, be aware of this! + +All these forms of addressing a vector `v` are valid: +`v[1]`, `v[3]`, `v.x`, `v[1] = 42`, `v.y = 13` + +Where `v` is a vector and `foo` stands for any function name, `v:foo(...)` does +the same as `vector.foo(v, ...)`, apart from deprecated functionality. + +The metatable that is used for vectors can be accessed via `vector.metatable`. +Do not modify it! + +All `vector.*` functions allow vectors `{x = X, y = Y, z = Z}` without metatables. +Returned vectors always have a metatable set. For the following functions, `v`, `v1`, `v2` are vectors, -`p1`, `p2` are positions: +`p1`, `p2` are positions, +`s` is a scalar (a number), +vectors are written like this: `(x, y, z)`: -* `vector.new(a[, b, c])`: +* `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. + * `(a, b, c)`, if all of `a`, `b`, `c` are defined numbers. + * `(0, 0, 0)`, if no arguments are given. +* `vector.from_string(s[, init])`: + * Returns `v, np`, where `v` is a vector read from the given string `s` and + `np` is the next position in the string after the vector. + * Returns `nil` on failure. + * `s`: Has to begin with a substring of the form `"(x, y, z)"`. Additional + spaces, leaving away commas and adding an additional comma to the end + is allowed. + * `init`: If given starts looking for the vector at this string index. +* `vector.to_string(v)`: + * Returns a string of the form `"(x, y, z)"`. * `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}`. + * If `p1` and `p2` are identical, returns `(0, 0, 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}`. + * If `v` has zero length, returns `(0, 0, 0)`. * `vector.floor(v)`: * Returns a vector, each dimension rounded down. * `vector.round(v)`: * Returns a vector, each dimension rounded to nearest integer. + * At a multiple of 0.5, rounds away from zero. * `vector.apply(v, func)`: * Returns a vector where the function `func` has been applied to each component. @@ -3041,10 +3297,16 @@ For the following functions, `v`, `v1`, `v2` are vectors, * 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` +* `vector.dot(v1, v2)`: + * Returns the dot product of `v1` and `v2`. +* `vector.cross(v1, v2)`: + * Returns the cross product of `v1` and `v2`. +* `vector.offset(v, x, y, z)`: + * Returns the sum of the vectors `v` and `(x, y, z)`. +* `vector.check()`: + * Returns a boolean value indicating whether `v` is a real vector, eg. created + by a `vector.*` function. + * Returns `false` for anything else, including tables like `{x=3,y=1,z=4}`. For the following functions `x` can be either a vector or a number: @@ -3056,10 +3318,28 @@ For the following functions `x` can be either a vector or a number: * 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. +* `vector.multiply(v, s)`: + * Returns a scaled vector. + * Deprecated: If `s` is a vector: Returns the Schur product. +* `vector.divide(v, s)`: + * Returns a scaled vector. + * Deprecated: If `s` is a vector: Returns the Schur quotient. + +Operators can be used if all of the involved vectors have metatables: +* `v1 == v2`: + * Returns whether `v1` and `v2` are identical. +* `-v`: + * Returns the additive inverse of v. +* `v1 + v2`: + * Returns the sum of both vectors. + * Note: `+` can not be used together with scalars. +* `v1 - v2`: + * Returns the difference of `v1` subtracted by `v2`. + * Note: `-` can not be used together with scalars. +* `v * s` or `s * v`: + * Returns `v` scaled by `s`. +* `v / s`: + * Returns `v` scaled by `1 / s`. For the following functions `a` is an angle in radians and `r` is a rotation vector ({x = , y = , z = }) where pitch, yaw and roll are @@ -3067,8 +3347,8 @@ angles in radians. * `vector.rotate(v, r)`: * Applies the rotation `r` to `v` and returns the result. - * `vector.rotate({x = 0, y = 0, z = 1}, r)` and - `vector.rotate({x = 0, y = 1, z = 0}, r)` return vectors pointing + * `vector.rotate(vector.new(0, 0, 1), r)` and + `vector.rotate(vector.new(0, 1, 0), r)` return vectors pointing forward and up relative to an entity's rotation `r`. * `vector.rotate_around_axis(v1, v2, a)`: * Returns `v1` rotated around axis `v2` by `a` radians according to @@ -3102,6 +3382,8 @@ Helper functions * 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` +* `math.round(x)`: Returns `x` rounded to the nearest integer. + * At a multiple of 0.5, rounds away from zero. * `string.split(str, separator, include_empty, max_splits, sep_is_pattern)` * `separator`: string, default: `","` * `include_empty`: boolean, default: `false` @@ -3149,7 +3431,8 @@ Helper functions * 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. + * If multiple keys in `t` map to the same value, it is unspecified which + value maps to that key. * `table.shuffle(table, [from], [to], [random_func])`: * Shuffles elements `from` to `to` in `table` in place * `from` defaults to `1` @@ -3160,21 +3443,21 @@ Helper functions * `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 +* `minetest.get_dig_params(groups, tool_capabilities)`: Simulates an item 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. + * `wear`: How much wear would be added to the tool (ignored for non-tools). `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 + * `tool_capabilities`: Tool capabilities table of the item * `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. + * `wear`: How much wear would be added to the tool (ignored for non-tools). Parameters: * `groups`: Damage groups of the object * `tool_capabilities`: Tool capabilities table of the item @@ -3378,7 +3661,7 @@ 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. +variation. 1 octave has a slight 'gridlike' appearance. Choose the number of octaves according to the `spread` and `lacunarity`, and the size of the finest detail you require. For example: @@ -3453,7 +3736,7 @@ For 2D or 3D perlin noise or perlin noise maps: spread = {x = 500, y = 500, z = 500}, seed = 571347, octaves = 5, - persist = 0.63, + persistence = 0.63, lacunarity = 2.0, flags = "defaults, absvalue", } @@ -3543,7 +3826,7 @@ The following is a decent set of parameters to work from: spread = {x=200, y=200, z=200}, seed = 5390, octaves = 4, - persist = 0.5, + persistence = 0.5, lacunarity = 2.0, flags = "eased", }, @@ -4087,6 +4370,8 @@ Callbacks: * 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_deactivate(self) + * Called when the object is about to get removed or unloaded. * `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 @@ -4098,7 +4383,7 @@ Callbacks: * `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`) + * `tool_capabilities`: capability table of used item (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. @@ -4207,11 +4492,14 @@ 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_modpath(modname)`: returns the directory path for a mod, + e.g. `"/home/user/.minetest/usermods/modname"`. + * Returns nil if the mod is not enabled or does not exist (not installed). + * Works regardless of whether the mod has been loaded yet. + * Useful for loading additional `.lua` modules or static data from a mod, + or checking if a mod is enabled. +* `minetest.get_modnames()`: returns a list of enabled mods, sorted alphabetically. + * Does not include disabled mods, even if they are installed. * `minetest.get_worldpath()`: returns e.g. `"/home/user/.minetest/world"` * Useful for storing custom data * `minetest.is_singleplayer()` @@ -4252,6 +4540,15 @@ Utilities pathfinder_works = true, -- Whether Collision info is available to an objects' on_step (5.3.0) object_step_has_moveresult = true, + -- Whether get_velocity() and add_velocity() can be used on players (5.4.0) + direct_velocity_on_players = true, + -- nodedef's use_texture_alpha accepts new string modes (5.4.0) + use_texture_alpha_string_modes = true, + -- degrotate param2 rotates in units of 1.5° instead of 2° + -- thus changing the range of values from 0-179 to 0-240 (5.5.0) + degrotate_240_steps = true, + -- ABM supports min_y and max_y fields in definition (5.5.0) + abm_min_max_y = true, } * `minetest.has_feature(arg)`: returns `boolean, missing_features` @@ -4311,6 +4608,9 @@ Utilities * `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.colorspec_to_colorstring(colorspec)`: Converts a ColorSpec to a + ColorString. If the ColorSpec is invalid, returns `nil`. + * `colorspec`: The ColorSpec to convert Logging ------- @@ -4455,11 +4755,15 @@ Call these functions only at load time! * `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) + * `tool_capabilities`: Capability table of used item (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_rightclickplayer(function(player, clicker))` + * Called when a player is right-clicked + * `player`: ObjectRef - Player that was right-clicked + * `clicker`: ObjectRef - Object that right-clicked, may or may not be a player * `minetest.register_on_player_hpchange(function(player, hp_change, reason), modifier)` * Called when the player gets damaged or healed * `player`: ObjectRef of the player @@ -4510,6 +4814,7 @@ Call these functions only at load time! * `cheat`: `{type=}`, where `` is one of: * `moved_too_fast` * `interacted_too_far` + * `interacted_with_self` * `interacted_while_dead` * `finished_unknown_dig` * `dug_unbreakable` @@ -4518,6 +4823,11 @@ Call these functions only at load time! * 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_chatcommand(function(name, command, params))` + * Called always when a chatcommand is triggered, before `minetest.registered_chatcommands` + is checked to see if the command exists, but after the input is parsed. + * Return `true` to mark the command as handled, which means that the default + handlers will be prevented. * `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 @@ -4609,6 +4919,12 @@ Call these functions only at load time! * 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. +* `minetest.register_on_liquid_transformed(function(pos_list, node_list))` + * Called after liquid nodes are modified by the engine's liquid transformation + process. + * `pos_list` is an array of all modified positions. + * `node_list` is an array of the old node that was previously at the position + with the corresponding index in pos_list. Setting-related --------------- @@ -4720,6 +5036,22 @@ Environment access * `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` + * `nil` is returned e.g. when the map isn't loaded at `pos` +* `minetest.get_natural_light(pos[, timeofday])` + * Figures out the sunlight (or moonlight) value at pos at the given time of + day. + * `pos`: The position of the node + * `timeofday`: `nil` for current time, `0` for night, `0.5` for day + * Returns a number between `0` and `15` or `nil` + * This function tests 203 nodes in the worst case, which happens very + unlikely +* `minetest.get_artificial_light(param1)` + * Calculates the artificial light (light from e.g. torches) value from the + `param1` value. + * `param1`: The param1 value of a `paramtype = "light"` node. + * Returns a number between `0` and `15` + * Currently it's the same as `math.floor(param1 / 16)`, except that it + ensures compatibility. * `minetest.place_node(pos, node)` * Place node with the same effects that a player would cause * `minetest.dig_node(pos)` @@ -4729,7 +5061,7 @@ Environment access * 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 + * Returns `true` and the ObjectRef of the spawned entity 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 @@ -4748,6 +5080,9 @@ Environment access * `minetest.get_objects_inside_radius(pos, radius)`: returns a list of ObjectRefs. * `radius`: using an euclidean metric +* `minetest.get_objects_in_area(pos1, pos2)`: returns a list of + ObjectRefs. + * `pos1` and `pos2` are the min and max positions of the area to search. * `minetest.set_timeofday(val)` * `val` is between `0` and `1`; `0` for midnight, `0.5` for midday * `minetest.get_timeofday()` @@ -5110,9 +5445,9 @@ Item handling information. * `minetest.get_node_drops(node, toolname)` * Returns list of itemstrings that are dropped by `node` when dug - with `toolname`. + with the item `toolname` (not limited to tools). * `node`: node as table or node name - * `toolname`: name of the tool item (can be `nil`) + * `toolname`: name of the item used to dig (can be `nil`) * `minetest.get_craft_result(input)`: returns `output, decremented_input` * `input.method` = `"normal"` or `"cooking"` or `"fuel"` * `input.width` = for example `3` @@ -5238,17 +5573,23 @@ Sounds * `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. + The gain will change by this much per second, + until it reaches the target gain. + Note: Older versions used a signed step. This is deprecated, but old + code will still work. (the client uses abs(step) to correct it) * `gain` the target gain for the fade. + Fading to zero will delete the sound. Timing ------ -* `minetest.after(time, func, ...)` +* `minetest.after(time, func, ...)` : returns job table to use as below. * Call the function `func` after `time` seconds, may be fractional * Optional: Variable number of arguments that are passed to `func` +* `job:cancel()` + * Cancels the job function from being called + Server ------ @@ -5275,20 +5616,22 @@ Server * 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) -* `minetest.dynamic_add_media(filepath)` - * Adds the file at the given path to the media sent to clients by the server - on startup and also pushes this file to already connected clients. +* `minetest.dynamic_add_media(filepath, callback)` + * `filepath`: path to a media file on the filesystem + * `callback`: function with arguments `name`, where name is a player name + (previously there was no callback argument; omitting it is deprecated) + * Adds the file to the media sent to clients by the server on startup + and also pushes this file to already connected clients. The file must be a supported image, sound or model format. It must not be modified, deleted, moved or renamed after calling this function. The list of dynamically added media is not persisted. - * Returns boolean indicating success (duplicate files count as error) - * The media will be ready to use (in e.g. entity textures, sound_play) - immediately after calling this function. + * Returns false on error, true if the request was accepted + * The given callback will be called for every player as soon as the + media is available on the client. Old clients that lack support for this feature will not see the media - unless they reconnect to the server. - * Since media transferred this way does not use client caching or HTTP - transfers, dynamic media should not be used with big files or performance - will suffer. + unless they reconnect to the server. (callback won't be called) + * Since media transferred this way currently does not use client caching + or HTTP transfers, dynamic media should not be used with big files. Bans ---- @@ -5544,7 +5887,9 @@ Misc. * 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 or nil for invalid base64 +* `minetest.decode_base64(string)`: returns string or nil on failure + * Padding characters are only supported starting at version 5.4.0, where + 5.5.0 and newer perform proper checks. * Decodes a string encoded in base64. * `minetest.is_protected(pos, name)`: returns boolean * Returning `true` restricts the player `name` from modifying (i.e. digging, @@ -5632,6 +5977,19 @@ Misc. * If `transient` is `false` or absent, frees a persistent forceload. If `true`, frees a transient forceload. +* `minetest.compare_block_status(pos, condition)` + * Checks whether the mapblock at positition `pos` is in the wanted condition. + * `condition` may be one of the following values: + * `"unknown"`: not in memory + * `"emerging"`: in the queue for loading from disk or generating + * `"loaded"`: in memory but inactive (no ABMs are executed) + * `"active"`: in memory and active + * Other values are reserved for future functionality extensions + * Return value, the comparison status: + * `false`: Mapblock does not fulfil the wanted condition + * `true`: Mapblock meets the requirement + * `nil`: Unsupported `condition` value + * `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 @@ -5668,6 +6026,9 @@ Global tables * Map of registered tool definitions, indexed by name * `minetest.registered_entities` * Map of registered entity prototypes, indexed by name + * Values in this table may be modified directly. + Note: changes to initial properties will only affect entities spawned afterwards, + as they are only read when spawning. * `minetest.object_refs` * Map of object references, indexed by active object id * `minetest.luaentities` @@ -5698,6 +6059,7 @@ Global tables * Map of registered chat command definitions, indexed by name * `minetest.registered_privileges` * Map of registered privilege definitions, indexed by name + * Registered privileges can be modified directly in this table. ### Registered callback tables @@ -5812,6 +6174,31 @@ An `InvRef` is a reference to an inventory. `minetest.get_inventory(location)`. * returns `{type="undefined"}` in case location is not known +### Callbacks + +Detached & nodemeta inventories provide the following callbacks for move actions: + +#### Before + +The `allow_*` callbacks return how many items can be moved. + +* `allow_move`/`allow_metadata_inventory_move`: Moving items in the inventory +* `allow_take`/`allow_metadata_inventory_take`: Taking items from the inventory +* `allow_put`/`allow_metadata_inventory_put`: Putting items to the inventory + +#### After + +The `on_*` callbacks are called after the items have been placed in the inventories. + +* `on_move`/`on_metadata_inventory_move`: Moving items in the inventory +* `on_take`/`on_metadata_inventory_take`: Taking items from the inventory +* `on_put`/`on_metadata_inventory_put`: Putting items to the inventory + +#### Swapping + +When a player tries to put an item to a place where another item is, the items are *swapped*. +This means that all callbacks will be called twice (once for each action). + `ItemStack` ----------- @@ -5837,6 +6224,18 @@ an itemstring, a table or `nil`. stack). * `set_metadata(metadata)`: (DEPRECATED) Returns true. * `get_description()`: returns the description shown in inventory list tooltips. + * The engine uses this when showing item descriptions in tooltips. + * Fields for finding the description, in order: + * `description` in item metadata (See [Item Metadata].) + * `description` in item definition + * item name +* `get_short_description()`: returns the short description or nil. + * Unlike the description, this does not include new lines. + * Fields for finding the short description, in order: + * `short_description` in item metadata (See [Item Metadata].) + * `short_description` in item definition + * first line of the description (From item meta or def, see `get_description()`.) + * Returns nil if none of the above are set * `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. @@ -5850,7 +6249,7 @@ an itemstring, a table or `nil`. * `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 + * Increases wear by `amount` if the item is a tool, otherwise does nothing * `amount`: number, integer * `add_item(item)`: returns leftover `ItemStack` * Put some item or stack onto this stack @@ -5990,6 +6389,19 @@ object you are working with still exists. * `get_pos()`: returns `{x=num, y=num, z=num}` * `set_pos(pos)`: `pos`=`{x=num, y=num, z=num}` +* `get_velocity()`: returns the velocity, a vector. +* `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. + Additionally, players also do not support set_velocity. + * If a player: + * 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_velocity({x=0, y=6.5, z=0})` is equivalent to + pressing the jump key (assuming default settings) * `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 @@ -6000,8 +6412,8 @@ object you are working with still exists. * `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). +* `get_hp()`: returns number of health points +* `set_hp(hp, reason)`: set number of health points * 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 @@ -6024,17 +6436,24 @@ object you are working with still exists. `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_attach(parent[, bone, position, rotation, forced_visible])` + * `bone`: string. Default is `""`, the root bone + * `position`: `{x=num, y=num, z=num}`, relative, default `{x=0, y=0, z=0}` + * `rotation`: `{x=num, y=num, z=num}` = Rotation on each axis, in degrees. + Default `{x=0, y=0, z=0}` + * `forced_visible`: Boolean to control whether the attached entity + should appear in first person. Default `false`. + * This command may fail silently (do nothing) when it would result + in circular attachments. +* `get_attach()`: returns parent, bone, position, rotation, forced_visible, + or nil if it isn't attached. +* `get_children()`: returns a list of ObjectRefs that are attached to the + object. * `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}` +* `set_bone_position([bone, position, rotation])` + * `bone`: string. Default is `""`, the root bone + * `position`: `{x=num, y=num, z=num}`, relative, `default {x=0, y=0, z=0}` + * `rotation`: `{x=num, y=num, z=num}`, default `{x=0, y=0, z=0}` * `get_bone_position(bone)`: returns position and rotation of the bone * `set_properties(object property table)` * `get_properties()`: returns object property table @@ -6042,15 +6461,21 @@ object you are working with still exists. * `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 = "", + color = {a=0..255, r=0..255, g=0..255, b=0..255}, + bgcolor = {a=0..255, r=0..255, g=0..255, b=0..255}, } * `set_nametag_attributes(attributes)` * sets the attributes of the nametag of an object * `attributes`: { - color = ColorSpec, text = "My Nametag", + color = ColorSpec, + -- ^ Text color + bgcolor = ColorSpec or false, + -- ^ Sets background color of nametag + -- `false` will cause the background to be set automatically based on user settings + -- Default: false } #### Lua entity only (no-op for other objects) @@ -6061,11 +6486,6 @@ object you are working with still exists. 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 @@ -6073,35 +6493,37 @@ object you are working with still exists. * `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). +* `set_yaw(yaw)`: sets the yaw in radians (heading). * `get_yaw()`: returns number in radians * `set_texture_mod(mod)` + * Set a texture modifier to the base texture, for sprites and meshes. + * When calling `set_texture_mod` again, the previous one is discarded. + * `mod` the texture modifier. See [Texture modifiers]. * `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` +* `set_sprite(start_frame, num_frames, framelength, select_x_by_camera)` + * Specifies and starts a sprite animation + * Animations iterate along the frame `y` position. + * `start_frame`: {x=column number, y=row number}, the coordinate of the + first frame, default: `{x=0, y=0}` + * `num_frames`: Total frames in the texture, default: `1` + * `framelength`: Time per animated frame in seconds, default: `0.2` + * `select_x_by_camera`: Only for visual = `sprite`. Changes the frame `x` + position according to the view direction. default: `false`. + * First column: subject facing the camera + * Second column: subject looking to the left + * Third column: subject backing the camera + * Fourth column: subject looking to the right + * Fifth column: subject viewed from above + * Sixth column: subject viewed from below * `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 +* `get_player_velocity()`: **DEPRECATED**, use get_velocity() instead. 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) +* `add_player_velocity(vel)`: **DEPRECATED**, use add_velocity(vel) instead. * `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 @@ -6163,15 +6585,23 @@ object you are working with still exists. * 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, zoom. - * example: `{jump=false, right=true, left=false, LMB=false, RMB=false, - sneak=true, aux1=false, down=false, up=false, zoom=false}` - * The `zoom` field is available since 5.3 + * The table consists of fields with the following boolean values + representing the pressed keys: `up`, `down`, `left`, `right`, `jump`, + `aux1`, `sneak`, `dig`, `place`, `LMB`, `RMB`, and `zoom`. + * The fields `LMB` and `RMB` are equal to `dig` and `place` respectively, + and exist only to preserve backwards compatibility. * `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, 9/zoom (zoom available since 5.3) + keys. Bits: + * 0 - up + * 1 - down + * 2 - left + * 3 - right + * 4 - jump + * 5 - aux1 + * 6 - sneak + * 7 - dig + * 8 - place + * 9 - zoom * `set_physics_override(override_table)` * `override_table` is a table with the following fields: * `speed`: multiplier to default walking speed value (default: `1`) @@ -6216,8 +6646,31 @@ object you are working with still exists. * `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: +* `set_minimap_modes({mode, mode, ...}, selected_mode)` + * Overrides the available minimap modes (and toggle order), and changes the + selected mode. + * `mode` is a table consisting of up to four fields: + * `type`: Available type: + * `off`: Minimap off + * `surface`: Minimap in surface mode + * `radar`: Minimap in radar mode + * `texture`: Texture to be displayed instead of terrain map + (texture is centered around 0,0 and can be scaled). + Texture size is limited to 512 x 512 pixel. + * `label`: Optional label to display on minimap mode toggle + The translation must be handled within the mod. + * `size`: Sidelength or diameter, in number of nodes, of the terrain + displayed in minimap + * `texture`: Only for texture type, name of the texture to display + * `scale`: Only for texture type, scale of the texture map in nodes per + pixel (for example a `scale` of 2 means each pixel represents a 2x2 + nodes square) + * `selected_mode` is the mode index to be selected after modes have been changed + (0 is the first mode). +* `set_sky(sky_parameters)` + * The presence of the function `set_sun`, `set_moon` or `set_stars` indicates + whether `set_sky` accepts this format. Check the legacy format otherwise. + * `sky_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 @@ -6228,9 +6681,9 @@ object you are working with still exists. * `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`) + sky during the day. (default: `#61b5f5`) * `day_horizon`: ColorSpec, for the bottom half of the - `"regular"` sky during the day. (default: `#9bc1f0`) + `"regular"` sky during the day. (default: `#90d3f6`) * `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. @@ -6240,7 +6693,7 @@ object you are working with still exists. 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`) + sky during the night. (default: `#006bff`) 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"` @@ -6258,11 +6711,20 @@ object you are working with still exists. 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"`) +* `set_sky(base_color, type, {texture names}, clouds)` + * Deprecated. Use `set_sky(sky_parameters)` + * `base_color`: 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 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: +* `set_sun(sun_parameters)`: + * `sun_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 `""` @@ -6276,8 +6738,8 @@ object you are working with still exists. * `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: +* `set_moon(moon_parameters)`: + * `moon_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 `""` @@ -6287,8 +6749,8 @@ object you are working with still exists. * `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: +* `set_stars(star_parameters)`: + * `star_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 @@ -6300,8 +6762,8 @@ object you are working with still exists. * `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: +* `set_clouds(cloud_parameters)`: set cloud parameters + * `cloud_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`). @@ -6319,21 +6781,17 @@ object you are working with still exists. 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 +* `set_local_animation(idle, walk, dig, walk_while_dig, frame_speed)`: + set animation for player model in third person view. + * Every animation equals to a `{x=starting frame, y=ending frame}` table. + * `frame_speed` sets the animations frame speed. Default is 30. +* `get_local_animation()`: returns idle, walk, dig, walk_while_dig 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. +* `set_eye_offset([firstperson, thirdperson])`: defines offset vectors for + camera per player. An argument defaults to `{x=0, y=0, z=0}` if unspecified. * 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` +* `get_eye_offset()`: returns first and third person offsets. * `send_mapblock(blockpos)`: * Sends a server-side loaded mapblock to the player. * Returns `false` if failed. @@ -6686,10 +7144,18 @@ Player properties need to be saved manually. -- in mods. nametag = "", - -- By default empty, for players their name is shown if empty + -- The name to display on the head of the object. By default empty. + -- If the object is a player, a nil or empty nametag is replaced by the player's name. + -- For all other objects, a nil or empty string removes the nametag. + -- To hide a nametag, set its color alpha to zero. That will disable it entirely. nametag_color = , - -- Sets color of nametag + -- Sets text color of nametag + + nametag_bgcolor = , + -- Sets background color of nametag + -- `false` will cause the background to be set automatically based on user settings. + -- Default: false infotext = "", -- By default empty, text to be shown when pointed at object @@ -6705,6 +7171,10 @@ Player properties need to be saved manually. shaded = true, -- Setting this to 'false' disables diffuse lighting of entity + + show_on_minimap = false, + -- Defaults to true for players, false for other entities. + -- If set to true the entity will show as a marker on the minimap. } Entity definition @@ -6789,6 +7259,11 @@ Used by `minetest.register_abm`. -- Chance of triggering `action` per-node per-interval is 1.0 / this -- value + min_y = -32768, + max_y = 32767, + -- min and max height levels where ABM will be processed + -- can be used to reduce CPU usage + 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 @@ -6839,13 +7314,8 @@ 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}` +* `{name="image.png", backface_culling=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`. @@ -6898,6 +7368,14 @@ Used by `minetest.register_node`, `minetest.register_craftitem`, and { description = "Steel Axe", + -- Can contain new lines. "\n" has to be used as new line character. + -- See also: `get_description` in [`ItemStack`] + + short_description = "Steel Axe", + -- Must not contain new lines. + -- Defaults to nil. + -- Use an [`ItemStack`] to get the short description, eg: + -- ItemStack(itemname):get_short_description() groups = {}, -- key = name, value = rating; rating = 1..3. @@ -6936,7 +7414,14 @@ Used by `minetest.register_node`, `minetest.register_craftitem`, and liquids_pointable = false, - -- See "Tools" section for an example including explanation + light_source = 0, + -- When used for nodes: Defines amount of light emitted by node. + -- Otherwise: Defines texture glow when viewed as a dropped item + -- To set the maximum (14), use the value 'minetest.LIGHT_MAX'. + -- A value outside the range 0 to minetest.LIGHT_MAX causes undefined + -- behavior. + + -- See "Tool Capabilities" section for an example including explanation tool_capabilities = { full_punch_interval = 1.0, max_drop_level = 0, @@ -7009,7 +7494,7 @@ Used by `minetest.register_node`, `minetest.register_craftitem`, and 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. + -- wearing out the item (if 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) @@ -7063,8 +7548,18 @@ Used by `minetest.register_node`. -- 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 + use_texture_alpha = ..., + -- Specifies how the texture's alpha channel will be used for rendering. + -- possible values: + -- * "opaque": Node is rendered opaque regardless of alpha channel + -- * "clip": A given pixel is either fully see-through or opaque + -- depending on the alpha channel being below/above 50% in value + -- * "blend": The alpha channel specifies how transparent a given pixel + -- of the rendered node is + -- The default is "opaque" for drawtypes normal, liquid and flowingliquid; + -- "clip" otherwise. + -- If set to a boolean value (deprecated): true either sets it to blend + -- or clip, false sets it to clip or opaque mode depending on the drawtype. palette = "palette.png", -- The node's `param2` is used to select a pixel from the image. @@ -7106,7 +7601,16 @@ Used by `minetest.register_node`. -- If true, liquids flow into and replace this node. -- Warning: making a liquid node 'floodable' will cause problems. - liquidtype = "none", -- "none" / "source" / "flowing" + liquidtype = "none", -- specifies liquid physics + -- * "none": no liquid physics + -- * "source": spawns flowing liquid nodes at all 4 sides and below; + -- recommended drawtype: "liquid". + -- * "flowing": spawned from source, spawns more flowing liquid nodes + -- around it until `liquid_range` is reached; + -- will drain out without a source; + -- recommended drawtype: "flowingliquid". + -- If it's "source" or "flowing" and `liquid_range > 0`, then + -- both `liquid_alternative_*` fields must be specified liquid_alternative_flowing = "", -- Flowing version of source liquid @@ -7127,18 +7631,16 @@ Used by `minetest.register_node`. leveled_max = 127, -- Maximum value for `leveled` (0-127), enforced in -- `minetest.set_node_level` and `minetest.add_node_level`. + -- Values above 124 might causes collision detection issues. - liquid_range = 8, -- Number of flowing nodes around source (max. 8) + liquid_range = 8, + -- Maximum distance that flowing liquid nodes can spread around + -- source on flat land; + -- maximum = 8; set to 0 to disable liquid flow 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 @@ -7160,6 +7662,7 @@ Used by `minetest.register_node`. type = "fixed", fixed = { {-2 / 16, -0.5, -2 / 16, 2 / 16, 3 / 16, 2 / 16}, + -- Node box format: see [Node boxes] }, }, -- Custom selection box definition. Multiple boxes can be defined. @@ -7170,13 +7673,12 @@ Used by `minetest.register_node`. type = "fixed", fixed = { {-2 / 16, -0.5, -2 / 16, 2 / 16, 3 / 16, 2 / 16}, + -- Node box format: see [Node boxes] }, }, -- 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, @@ -7205,7 +7707,7 @@ Used by `minetest.register_node`. -- While digging node. -- If `"__group"`, then the sound will be -- `default_dig_`, where `` is the - -- name of the tool's digging group with the fastest digging time. + -- name of the item'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"` @@ -7217,23 +7719,25 @@ Used by `minetest.register_node`. -- Node was placed. Also played after falling place_failed = , - -- When node placement failed + -- When node placement failed. + -- Note: This happens if the _built-in_ node placement failed. + -- This sound will still be played if the node is placed in the + -- `on_place` callback manually. fall = , - -- When node starts to fall + -- When node starts to fall or is detached }, 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. + -- Using a table allows multiple items, drop chances and item filtering. + -- Item 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 + -- Item 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'. @@ -7247,7 +7751,7 @@ Used by `minetest.register_node`. items = {"default:diamond"}, }, { - -- Only drop if using a tool whose name is identical to one + -- Only drop if using an item whose name is identical to one -- of these. tools = {"default:shovel_mese", "default:shovel_diamond"}, rarity = 5, @@ -7258,8 +7762,8 @@ Used by `minetest.register_node`. inherit_color = true, }, { - -- Only drop if using a tool whose name contains - -- "default:shovel_" (this tool filtering by string matching + -- Only drop if using a item whose name contains + -- "default:shovel_" (this item filtering by string matching -- is deprecated). tools = {"~default:shovel_"}, rarity = 2, @@ -7340,7 +7844,9 @@ Used by `minetest.register_node`. on_dig = function(pos, node, digger), -- default: minetest.node_dig - -- By default checks privileges, wears out tool and removes node. + -- By default checks privileges, wears out item (if tool) and removes node. + -- return true if the node was dug successfully, false otherwise. + -- Deprecated: returning nil is the same as returning true. on_timer = function(pos, elapsed), -- default: nil @@ -7380,6 +7886,13 @@ Used by `minetest.register_node`. -- intensity: 1.0 = mid range of regular TNT. -- If defined, called when an explosion touches the node, instead of -- removing the node. + + mod_origin = "modname", + -- stores which mod actually registered a node + -- if it can not find a source, returns "??" + -- useful for getting what mod truly registered something + -- example: if a node is registered as ":othermodname:nodename", + -- nodename will show "othermodname", but mod_orgin will say "modname" } Crafting recipes @@ -7418,10 +7931,22 @@ Used by `minetest.register_craft`. { type = "toolrepair", - additional_wear = -0.02, + additional_wear = -0.02, -- multiplier of 65536 } -Note: Tools with group `disable_repair=1` will not repairable by this recipe. +Adds a shapeless recipe for *every* tool that doesn't have the `disable_repair=1` +group. Player can put 2 equal tools in the craft grid to get one "repaired" tool +back. +The wear of the output is determined by the wear of both tools, plus a +'repair bonus' given by `additional_wear`. To reduce the wear (i.e. 'repair'), +you want `additional_wear` to be negative. + +The formula used to calculate the resulting wear is: + + 65536 - ( (65536 - tool_1_wear) + (65536 - tool_2_wear) + 65536 * additional_wear ) + +The result is rounded and can't be lower than 0. If the result is 65536 or higher, +no crafting is possible. ### Cooking @@ -7489,7 +8014,7 @@ See [Ores] section above for essential information. spread = {x = 100, y = 100, z = 100}, seed = 23, octaves = 3, - persist = 0.7 + persistence = 0.7 }, -- NoiseParams structure describing one of the perlin noises used for -- ore distribution. @@ -7518,7 +8043,7 @@ See [Ores] section above for essential information. spread = {x = 100, y = 100, z = 100}, seed = 47, octaves = 3, - persist = 0.7 + persistence = 0.7 }, np_puff_bottom = { offset = 4, @@ -7526,7 +8051,7 @@ See [Ores] section above for essential information. spread = {x = 100, y = 100, z = 100}, seed = 11, octaves = 3, - persist = 0.7 + persistence = 0.7 }, -- vein @@ -7539,7 +8064,7 @@ See [Ores] section above for essential information. spread = {x = 100, y = 100, z = 100}, seed = 17, octaves = 3, - persist = 0.7 + persistence = 0.7 }, stratum_thickness = 8, } @@ -7666,7 +8191,7 @@ See [Decoration types]. Used by `minetest.register_decoration`. spread = {x = 100, y = 100, z = 100}, seed = 354, octaves = 3, - persist = 0.7, + persistence = 0.7, lacunarity = 2.0, flags = "absvalue" }, @@ -7807,6 +8332,8 @@ Used by `minetest.register_chatcommand`. func = function(name, param), -- Called when command is run. Returns boolean success and text output. + -- Special case: The help message is shown to the player if `func` + -- returns false without a text output. } Note that in params, use of symbols is as follows: @@ -7889,7 +8416,8 @@ 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" + -- Type of element, can be "image", "text", "statbar", "inventory", + -- "compass" or "minimap" position = {x=0.5, y=0.5}, -- Left corner position of element @@ -8066,13 +8594,15 @@ Used by `HTTPApiTable.fetch` and `HTTPApiTable.fetch_async`. url = "http://example.org", timeout = 10, - -- Timeout for connection in seconds. Default is 3 seconds. + -- Timeout for request to be completed in seconds. Default depends on engine settings. - post_data = "Raw POST request data string" OR {field1 = "data1", field2 = "data2"}, - -- Optional, if specified a POST request with post_data is performed. + method = "GET", "POST", "PUT" or "DELETE" + -- The http method to use. Defaults to "GET". + + data = "Raw request data string" OR {field1 = "data1", field2 = "data2"}, + -- Data for the POST, PUT or DELETE request. -- 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 @@ -8086,6 +8616,10 @@ Used by `HTTPApiTable.fetch` and `HTTPApiTable.fetch_async`. multipart = boolean -- Optional, if true performs a multipart HTTP request. -- Default is false. + -- Post only, data must be array + + post_data = "Raw POST request data string" OR {field1 = "data1", field2 = "data2"}, + -- Deprecated, use `data` instead. Forces `method = "POST"`. } `HTTPRequestResult` definition