diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Doxyfile.in | 1 | ||||
| -rw-r--r-- | doc/client_lua_api.txt | 23 | ||||
| -rw-r--r-- | doc/direction.md | 69 | ||||
| -rw-r--r-- | doc/lua_api.txt | 776 | ||||
| -rw-r--r-- | doc/menu_lua_api.txt | 17 | ||||
| -rw-r--r-- | doc/minetest.6 | 7 | ||||
| -rw-r--r-- | doc/texture_packs.txt | 3 | ||||
| -rw-r--r-- | doc/world_format.txt | 91 |
8 files changed, 746 insertions, 241 deletions
diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index d7816f0e4..ae36fd6bf 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -16,7 +16,6 @@ PREDEFINED = "USE_SPATIAL=1" \ "USE_REDIS=1" \ "USE_SOUND=1" \ "USE_CURL=1" \ - "USE_FREETYPE=1" \ "USE_GETTEXT=1" # Input diff --git a/doc/client_lua_api.txt b/doc/client_lua_api.txt index 098596481..32be8c849 100644 --- a/doc/client_lua_api.txt +++ b/doc/client_lua_api.txt @@ -1,4 +1,4 @@ -Minetest Lua Client Modding API Reference 5.4.0 +Minetest Lua Client Modding API Reference 5.5.0 ================================================ * More information at <http://www.minetest.net/> * Developer Wiki: <http://dev.minetest.net/> @@ -651,6 +651,9 @@ 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.colorspec_to_colorstring(colorspec)`: Converts a ColorSpec to a + ColorString. If the ColorSpec is invalid, returns `nil`. + * `colorspec`: The ColorSpec to convert * `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. @@ -907,7 +910,9 @@ Call these functions only at load time! * 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 +* `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.gettext(string)` : returns string * look up the translation of a string in the gettext message catalog @@ -1025,8 +1030,8 @@ Methods: * returns true if player is in a liquid (This oscillates so that the player jumps a bit above the surface) * `is_in_liquid_stable()` * returns true if player is in a stable liquid (This is more stable and defines the maximum speed of the player) -* `get_liquid_viscosity()` - * returns liquid viscosity (Gets the viscosity of liquid to calculate friction) +* `get_move_resistance()` + * returns move resistance of current node, the higher the slower the player moves * `is_climbing()` * returns true if player is climbing * `swimming_vertical()` @@ -1228,7 +1233,7 @@ It can be created via `Raycast(pos1, pos2, objects, liquids)` or liquid_type = <string>, -- A string containing "none", "flowing", or "source" *May not exist* liquid_alternative_flowing = <string>, -- Alternative node for liquid *May not exist* liquid_alternative_source = <string>, -- Alternative node for liquid *May not exist* - liquid_viscosity = <number>, -- How fast the liquid flows *May not exist* + liquid_viscosity = <number>, -- How slow the liquid flows *May not exist* liquid_renewable = <boolean>, -- Whether the liquid makes an infinite source *May not exist* liquid_range = <number>, -- How far the liquid flows *May not exist* drowning = bool, -- Whether the player will drown in the node @@ -1243,6 +1248,7 @@ It can be created via `Raycast(pos1, pos2, objects, liquids)` or }, legacy_facedir_simple = bool, -- Whether to use old facedir legacy_wallmounted = bool -- Whether to use old wallmounted + move_resistance = <number>, -- How slow players can move through the node *May not exist* } ``` @@ -1309,6 +1315,8 @@ It can be created via `Raycast(pos1, pos2, objects, liquids)` or -- ^ See "HUD Element Types" size = { x=100, y=100 }, -- default {x=0, y=0} -- ^ Size of element in pixels + style = 0, + -- ^ For "text" elements sets font style: bitfield with 1 = bold, 2 = italic, 4 = monospace } ``` @@ -1348,9 +1356,8 @@ The following functions provide escape sequences: 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`). `Color` ------------- diff --git a/doc/direction.md b/doc/direction.md new file mode 100644 index 000000000..826dd47b3 --- /dev/null +++ b/doc/direction.md @@ -0,0 +1,69 @@ +# Minetest Direction Document + +## 1. Long-term Roadmap + +The long-term roadmaps, aims, and guiding philosophies are set out using the +following documents: + +* [What is Minetest?](http://c55.me/blog/?p=1491) +* [celeron55's roadmap](https://forum.minetest.net/viewtopic.php?t=9177) +* [celeron55's comment in "A clear mission statement for Minetest is missing"](https://github.com/minetest/minetest/issues/3476#issuecomment-167399287) +* [Core developer to-do/wish lists](https://forum.minetest.net/viewforum.php?f=7) + +## 2. Medium-term Roadmap + +These are the current medium-term goals for Minetest development, in no +particular order. + +These goals were created from the top points in a +[roadmap brainstorm](https://github.com/minetest/minetest/issues/10461). +This should be reviewed approximately yearly, or when goals are achieved. + +Pull requests that address one of these goals will be labelled as "Roadmap". +PRs that are not on the roadmap will be closed unless they receive a concept +approval within a week, issues can be used for preapproval. +Bug fixes are exempt for this, and are always accepted and prioritised. +See [CONTRIBUTING.md](../.github/CONTRIBUTING.md) for more info. + +### 2.1 Rendering/Graphics improvements + +The priority is fixing the issues, performance, and general correctness. +Once that is done, fancier features can be worked on, such as water shaders, +shadows, and improved lighting. + +Examples include +[transparency sorting](https://github.com/minetest/minetest/issues/95), +[particle performance](https://github.com/minetest/minetest/issues/1414), +[general view distance](https://github.com/minetest/minetest/issues/7222). + +This includes work on maintaining +[our Irrlicht fork](https://github.com/minetest/irrlicht), and switching to +alternative libraries to replace Irrlicht functionality as needed + +### 2.2 Internal code refactoring + +To ensure sustainable development, Minetest's code needs to be +[refactored and improved](https://github.com/minetest/minetest/pulls?q=is%3Aopen+sort%3Aupdated-desc+label%3A%22Code+quality%22+). +This will remove code rot and allow for more efficient development. + +### 2.3 UI Improvements + +A [formspec replacement](https://github.com/minetest/minetest/issues/6527) is +needed to make GUIs better and easier to create. This replacement could also +be a replacement for HUDs, allowing for a unified API. + +A [new mainmenu](https://github.com/minetest/minetest/issues/6733) is needed to +improve user experience. First impressions matter, and the current main menu +doesn't do a very good job at selling Minetest or explaining what it is. +A new main menu should promote games to users, allowing Minetest Game to no +longer be bundled by default. + +The UI code is undergoing rapid changes, so it is especially important to make +an issue for any large changes before spending lots of time. + +### 2.4 Object and entity improvements + +There are still a significant number of issues with objects. +Collisions, +[performance](https://github.com/minetest/minetest/issues/6453), +API convenience, and discrepancies between players and entities. diff --git a/doc/lua_api.txt b/doc/lua_api.txt index 790ab32f4..faaed55e1 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -77,8 +77,16 @@ The game directory can contain the following files: `disallowed_mapgens`. * `disallowed_mapgen_settings= <comma-separated mapgen settings>` e.g. `disallowed_mapgen_settings = mgv5_spflags` - These settings are hidden for this game in the world creation + These mapgen settings are hidden for this game in the world creation dialog and game start menu. + * `disabled_settings = <comma-separated settings>` + e.g. `disabled_settings = enable_damage, creative_mode` + These settings are hidden for this game in the "Start game" tab + and will be initialized as `false` when the game is started. + Prepend a setting name with an exclamation mark to initialize it to `true` + (this does not work for `enable_server`). + Only these settings are supported: + `enable_damage`, `creative_mode`, `enable_server`. * `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 @@ -105,8 +113,16 @@ If you want to specify multiple images for one identifier, add additional images named like `$identifier.$n.png`, with an ascending number $n starting with 1, and a random image will be chosen from the provided ones. +Menu music +----------- +Games can provide custom main menu music. They are put inside a `menu` +directory inside the game directory. +The music files are named `theme.ogg`. +If you want to specify multiple music files for one game, add additional +images named like `theme.$n.ogg`, with an ascending number $n starting +with 1 (max 10), and a random music file will be chosen from the provided ones. Mods ==== @@ -247,7 +263,7 @@ Media files (textures, sounds, whatever) that will be transferred to the client and will be available for use by the mod and translation files for the clients (see [Translations]). -It is suggested to use the folders for the purpous they are thought for, +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. @@ -620,6 +636,23 @@ Result is more like what you'd expect if you put a color on top of another color, meaning white surfaces get a lot of your new color while black parts don't change very much. +#### `[png:<base64>` + +Embed a base64 encoded PNG image in the texture string. +You can produce a valid string for this by calling +`minetest.encode_base64(minetest.encode_png(tex))`, +refer to the documentation of these functions for details. +You can use this to send disposable images such as captchas +to individual clients, or render things that would be too +expensive to compose with `[combine:`. + +IMPORTANT: Avoid sending large images this way. +This is not a replacement for asset files, do not use it to do anything +that you could instead achieve by just using a file. +In particular consider `minetest.dynamic_add_media` and test whether +using other texture modifiers could result in a shorter string than +embedding a whole image, this may vary by use case. + Hardware coloring ----------------- @@ -993,7 +1026,7 @@ 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 + * The value stores light with and without sun in its lower and upper 4 bits respectively. * Required by a light source node to enable spreading its light. * Required by the following drawtypes as they determine their visual @@ -1022,7 +1055,8 @@ The function of `param2` is determined by `paramtype2` in node definition. 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 @@ -1048,9 +1082,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 @@ -1084,10 +1118,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 @@ -1107,8 +1151,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. @@ -1135,14 +1191,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. @@ -1175,7 +1237,12 @@ 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` @@ -1482,6 +1549,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` @@ -1549,15 +1619,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 --------------- @@ -1568,7 +1660,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 ------------ @@ -1622,8 +1716,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 @@ -1664,17 +1758,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 -------------------------- @@ -1706,7 +1800,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. @@ -1725,16 +1819,24 @@ 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 +* `float`: the node will not fall through liquids (`liquidtype ~= "none"`) * `level`: Can be used to give an additional sense of progression in the game. * A larger level will cause e.g. a weapon of a lower level make much less damage, and get worn out much faster, or not be able to get drops from destroyed nodes. * `0` is something that is directly accessible at the start of gameplay * There is no upper limit - * See also: `leveldiff` in [Tools] + * See also: `leveldiff` in [Tool Capabilities] * `slippery`: Players and items will slide on the node. Slipperiness rises steadily with `slippery` value, starting at 1. @@ -1745,12 +1847,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. 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. @@ -1762,8 +1867,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. @@ -1772,7 +1877,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 @@ -1798,54 +1903,67 @@ 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: -Tools define: +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. + +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 -is multiplied by `3^leveldiff`. +of this group, of the maximum level. The maximum supported number of +uses is 65535. The special number 0 is used for infinite uses. +For lower leveled nodes, the use count is multiplied by `3^leveldiff`. `leveldiff` is the difference of the tool's `maxlevel` `groupcaps` and the node's `level` group. The node cannot be dug if `leveldiff` is less than zero. @@ -1853,9 +1971,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 @@ -1864,7 +1984,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. @@ -1876,8 +1996,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, @@ -1888,7 +2019,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` @@ -1992,8 +2123,12 @@ Node metadata contains two things: Some of the values in the key-value store are handled specially: -* `formspec`: Defines a right-click inventory menu. See [Formspec]. -* `infotext`: Text shown on the screen when the node is pointed at +* `formspec`: Defines an inventory menu that is opened with the + 'place/use' key. Only works if no `on_rightclick` was + defined for the node. See also [Formspec]. +* `infotext`: Text shown on the screen when the node is pointed at. + Line-breaks will be applied automatically. + If the infotext is very long, it will be truncated. Example: @@ -2046,6 +2181,21 @@ Example: meta:set_string("key", "value") print(dump(meta:to_table())) +Example manipulations of "description" and expected output behaviors: + + print(ItemStack("default:pick_steel"):get_description()) --> Steel Pickaxe + print(ItemStack("foobar"):get_description()) --> Unknown Item + + local stack = ItemStack("default:stone") + stack:get_meta():set_string("description", "Custom description\nAnother line") + print(stack:get_description()) --> Custom description\nAnother line + print(stack:get_short_description()) --> Custom description + + stack:get_meta():set_string("short_description", "Short") + print(stack:get_description()) --> Custom description\nAnother line + print(stack:get_short_description()) --> Short + + print(ItemStack("mod:item_with_no_desc"):get_description()) --> mod:item_with_no_desc @@ -2121,18 +2271,20 @@ Examples Version History --------------- -* FORMSPEC VERSION 1: +* Formspec version 1 (pre-5.1.0): * (too much) -* FORMSPEC VERSION 2: +* Formspec version 2 (5.1.0): * Forced real coordinates * background9[]: 9-slice scaling parameters -* FORMSPEC VERSION 3: +* Formspec version 3 (5.2.0): * 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: +* Formspec version 4 (5.4.0): * Allow dropdown indexing events +* Formspec version 5 (5.5.0): + * Added padding[] element Elements -------- @@ -2176,9 +2328,20 @@ Elements * `position` and `anchor` elements need suitable values to avoid a formspec extending off the game window due to particular game window sizes. -### `no_prepend[]` +### `padding[<X>,<Y>]` * Must be used after the `size`, `position`, and `anchor` elements (if present). +* Defines how much space is padded around the formspec if the formspec tries to + increase past the size of the screen and coordinates have to be shrunk. +* For X and Y, 0.0 represents no padding (the formspec can touch the edge of the + screen), and 0.5 represents half the screen (which forces the coordinate size + to 0). If negative, the formspec can extend off the edge of the screen. +* Defaults to [0.05, 0.05]. + +### `no_prepend[]` + +* Must be used after the `size`, `position`, `anchor`, and `padding` elements + (if present). * Disables player:set_formspec_prepend() from applying to this formspec. ### `real_coordinates[<bool>]` @@ -2299,7 +2462,7 @@ 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[<X>,<Y>;<W>,<H>;<name>;<mesh>;<textures>;<rotation X,Y>;<continuous>;<mouse control>;<frame loop range>]` +### `model[<X>,<Y>;<W>,<H>;<name>;<mesh>;<textures>;<rotation X,Y>;<continuous>;<mouse control>;<frame loop range>;<animation speed>]` * Show a mesh model. * `name`: Element name that can be used for styling @@ -2313,6 +2476,7 @@ Elements * `frame loop range` (Optional): Range of the animation frames. * Defaults to the full range of all available frames. * Syntax: `<begin>,<end>` +* `animation speed` (Optional): Sets the animation speed. Default 0 FPS. ### `item_image[<X>,<Y>;<W>,<H>;<item name>]` @@ -2678,7 +2842,7 @@ Elements * `span=<value>`: number of following columns to affect (default: infinite). -### `style[<selector 1>,<selector 2>;<prop1>;<prop2>;...]` +### `style[<selector 1>,<selector 2>,...;<prop1>;<prop2>;...]` * Set the style for the element(s) matching `selector` by name. * `selector` can be one of: @@ -2691,7 +2855,7 @@ Elements * See [Styling Formspecs]. -### `style_type[<selector 1>,<selector 2>;<prop1>;<prop2>;...]` +### `style_type[<selector 1>,<selector 2>,...;<prop1>;<prop2>;...]` * Set the style for the element(s) matching `selector` by type. * `selector` can be one of: @@ -2764,10 +2928,10 @@ Styling Formspecs Formspec elements can be themed using the style elements: - style[<name 1>,<name 2>;<prop1>;<prop2>;...] - style[<name 1>:<state>,<name 2>:<state>;<prop1>;<prop2>;...] - style_type[<type 1>,<type 2>;<prop1>;<prop2>;...] - style_type[<type 1>:<state>,<type 2>:<state>;<prop1>;<prop2>;...] + style[<name 1>,<name 2>,...;<prop1>;<prop2>;...] + style[<name 1>:<state>,<name 2>:<state>,...;<prop1>;<prop2>;...] + style_type[<type 1>,<type 2>,...;<prop1>;<prop2>;...] + style_type[<type 1>:<state>,<type 2>:<state>,...;<prop1>;<prop2>;...] Where a prop is: @@ -2942,6 +3106,9 @@ 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. +If you want to insert a literal greater-than sign or a backslash into the text, +you must escape it by preceding it with a backslash. + These are the technically basic tags but see below for usual tags. Base tags are: `<style color=... font=... size=...>...</style>` @@ -3077,9 +3244,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` ----------- @@ -3134,29 +3300,63 @@ 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, -`s` is a scalar (a number): - -* `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. +`s` is a scalar (a number), +vectors are written like this: `(x, y, z)`: + +* `vector.new([a[, b, c]])`: + * Returns a new vector `(a, b, c)`. + * Deprecated: `vector.new()` does the same as `vector.zero()` and + `vector.new(v)` does the same as `vector.copy(v)` +* `vector.zero()`: + * Returns a new vector `(0, 0, 0)`. +* `vector.copy(v)`: + * Returns a copy of the vector `v`. +* `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. @@ -3171,7 +3371,11 @@ For the following functions, `v`, `v1`, `v2` are vectors, * `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 = x, y = y, z = 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: @@ -3190,14 +3394,30 @@ For the following functions `x` can be either a vector or a number: * 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 = <pitch>, y = <yaw>, z = <roll>}) where pitch, yaw and roll are 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 @@ -3231,6 +3451,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` @@ -3268,7 +3490,6 @@ Helper functions * returns true when the passed number represents NaN. * `minetest.get_us_time()` * returns time with microsecond precision. May not return wall time. - * This value might overflow on certain 32-bit systems! * `table.copy(table)`: returns a table * returns a deep copy of `table` * `table.indexof(list, val)`: returns the smallest numerical index containing @@ -3291,25 +3512,27 @@ 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 - that digs a node. +* `minetest.get_dig_params(groups, tool_capabilities [, wear])`: + 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 -* `minetest.get_hit_params(groups, tool_capabilities [, time_from_last_punch])`: + * `tool_capabilities`: Tool capabilities table of the item + * `wear`: Amount of wear the tool starts with (default: 0) +* `minetest.get_hit_params(groups, tool_capabilities [, time_from_last_punch [, wear]])`: 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. + * `hp`: How much damage the punch would cause (between -65535 and 65535). + * `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 * `time_from_last_punch`: time in seconds since last punch action + * `wear`: Amount of wear the item starts with (default: 0) @@ -3509,7 +3732,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: @@ -3584,7 +3807,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", } @@ -3674,7 +3897,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", }, @@ -3980,7 +4203,7 @@ differences: ### Other API functions operating on a VoxelManip -If any VoxelManip contents were set to a liquid node, +If any VoxelManip contents were set to a liquid node (`liquidtype ~= "none"`), `VoxelManip:update_liquids()` must be called for these liquid nodes to begin flowing. It is recommended to call this function only after having written all buffered data back to the VoxelManip object, save for special situations where @@ -4231,7 +4454,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. @@ -4240,6 +4463,9 @@ Callbacks: * Called when the object dies. * `killer`: an `ObjectRef` (can be `nil`) * `on_rightclick(self, clicker)` + * Called when `clicker` pressed the 'place/use' key while pointing + to the object (not neccessarily an actual rightclick) + * `clicker`: an `ObjectRef` (may or may not be a player) * `on_attach_child(self, child)` * `child`: an `ObjectRef` of the child that attaches * `on_detach_child(self, child)` @@ -4392,6 +4618,13 @@ Utilities 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, + -- dynamic_add_media supports passing a table with options (5.5.0) + dynamic_add_media_table = true, } * `minetest.has_feature(arg)`: returns `boolean, missing_features` @@ -4427,6 +4660,19 @@ Utilities * `minetest.mkdir(path)`: returns success. * Creates a directory specified by `path`, creating parent directories if they don't exist. +* `minetest.rmdir(path, recursive)`: returns success. + * Removes a directory specified by `path`. + * If `recursive` is set to `true`, the directory is recursively removed. + Otherwise, the directory will only be removed if it is empty. + * Returns true on success, false on failure. +* `minetest.cpdir(source, destination)`: returns success. + * Copies a directory specified by `path` to `destination` + * Any files in `destination` will be overwritten if they already exist. + * Returns true on success, false on failure. +* `minetest.mvdir(source, destination)`: returns success. + * Moves a directory specified by `path` to `destination`. + * If the `destination` is a non-empty directory, then the move will fail. + * Returns true on success, false on failure. * `minetest.get_dir_list(path, [is_dir])`: returns list of entry names * is_dir is one of: * nil: return all entries, @@ -4451,6 +4697,26 @@ 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 +* `minetest.colorspec_to_bytes(colorspec)`: Converts a ColorSpec to a raw + string of four bytes in an RGBA layout, returned as a string. + * `colorspec`: The ColorSpec to convert +* `minetest.encode_png(width, height, data, [compression])`: Encode a PNG + image and return it in string form. + * `width`: Width of the image + * `height`: Height of the image + * `data`: Image data, one of: + * array table of ColorSpec, length must be width*height + * string with raw RGBA pixels, length must be width*height*4 + * `compression`: Optional zlib compression level, number in range 0 to 9. + The data is one-dimensional, starting in the upper left corner of the image + and laid out in scanlines going from left to right, then top to bottom. + Please note that it's not safe to use string.char to generate raw data, + use `colorspec_to_bytes` to generate raw RGBA values in a predictable way. + The resulting PNG image is always 32-bit. Palettes are not supported at the moment. + You may use this to procedurally generate textures during server init. Logging ------- @@ -4595,15 +4861,16 @@ 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 + * Called when the 'place/use' key was used while pointing a player + (not neccessarily an actual rightclick) + * `player`: ObjectRef - Player that is acted upon + * `clicker`: ObjectRef - Object that acted upon `player`, 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 @@ -4759,6 +5026,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 (`liquidtype ~= "none"`) 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 --------------- @@ -4895,7 +5168,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 @@ -5097,7 +5370,8 @@ Environment access * `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`. + * `liquids`: if false, liquid nodes (`liquidtype ~= "none"`) won't be + returned. Default is `false`. * `minetest.find_path(pos1,pos2,searchdistance,max_jump,max_drop,algorithm)` * returns table containing path that can be walked on * returns a table of 3D points representing a path from `pos1` to `pos2` or @@ -5121,7 +5395,7 @@ Environment access * `minetest.spawn_tree (pos, {treedef})` * spawns L-system tree at given `pos` with definition in `treedef` table * `minetest.transforming_liquid_add(pos)` - * add node to liquid update queue + * add node to liquid flow update queue * `minetest.get_node_max_level(pos)` * get max available level for leveled node * `minetest.get_node_level(pos)` @@ -5199,7 +5473,7 @@ Inventory * `minetest.remove_detached_inventory(name)` * Returns a `boolean` indicating whether the removal succeeded. * `minetest.do_item_eat(hp_change, replace_with_item, itemstack, user, pointed_thing)`: - returns left over ItemStack. + returns leftover ItemStack or nil to indicate no inventory change * See `minetest.item_eat` and `minetest.register_on_item_eat` Formspec @@ -5279,9 +5553,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` @@ -5442,6 +5716,8 @@ Server a player joined. * This function may be overwritten by mods to customize the status message. * `minetest.get_server_uptime()`: returns the server uptime in seconds +* `minetest.get_server_max_lag()`: returns the current maximum lag + of the server in seconds or nil if server is not fully loaded yet * `minetest.remove_player(name)`: remove player from database (if they are not connected). * As auth data is not removed, minetest.player_exists will continue to @@ -5450,22 +5726,33 @@ 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, 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. +* `minetest.dynamic_add_media(options, callback)` + * `options`: table containing the following parameters + * `filepath`: path to a media file on the filesystem + * `to_player`: name of the player the media should be sent to instead of + all players (optional) + * `ephemeral`: boolean that marks the media as ephemeral, + it will not be cached on the client (optional, default false) + * `callback`: function with arguments `name`, which is a player name + * Pushes the specified media file to client(s). (details below) + The file must be a supported image, sound or model format. + Dynamically added media is not persisted between server restarts. * 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. (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. + * Details/Notes: + * If `ephemeral`=false and `to_player` is unset the file is added to the media + sent to clients on startup, this means the media will appear even on + old clients if they rejoin the server. + * If `ephemeral`=false the file must not be modified, deleted, moved or + renamed after calling this function. + * Regardless of any use of `ephemeral`, adding media files with the same + name twice is not possible/guaranteed to work. An exception to this is the + use of `to_player` to send the same, already existent file to multiple + chosen players. + * Clients will attempt to fetch files added this way via remote media, + this can make transfer of bigger files painless (if set up). Nevertheless + it is advised not to use dynamic media for big media files. Bans ---- @@ -5480,6 +5767,10 @@ Bans * `minetest.kick_player(name, [reason])`: disconnect a player with an optional reason. * Returns boolean indicating success (false if player nonexistant) +* `minetest.disconnect_player(name, [reason])`: disconnect a player with an + optional reason, this will not prefix with 'Kicked: ' like kick_player. + If no reason is given, it will default to 'Disconnected.' + * Returns boolean indicating success (false if player nonexistant) Particles --------- @@ -5721,7 +6012,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, @@ -5809,6 +6102,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 @@ -6068,7 +6374,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 @@ -6262,6 +6568,8 @@ object you are working with still exists. 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 @@ -6393,6 +6701,7 @@ object you are working with still exists. * `set_inventory_formspec(formspec)` * Redefine player's inventory form * Should usually be called in `on_joinplayer` + * If `formspec` is `""`, the player's inventory is disabled. * `get_inventory_formspec()`: returns a formspec string * `set_formspec_prepend(formspec)`: * the formspec string will be added to every formspec shown to the user, @@ -6407,18 +6716,21 @@ object you are working with still exists. `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. + * Returns an empty table `{}` if the object is not a player. * `get_player_control_bits()`: returns integer with bit packed player pressed - keys. Bits: - * 0 - up - * 1 - down - * 2 - left - * 3 - right - * 4 - jump - * 5 - aux1 - * 6 - sneak - * 7 - dig - * 8 - place - * 9 - zoom + keys. + * Bits: + * 0 - up + * 1 - down + * 2 - left + * 3 - right + * 4 - jump + * 5 - aux1 + * 6 - sneak + * 7 - dig + * 8 - place + * 9 - zoom + * Returns `0` (no bits set) if the object is not a player. * `set_physics_override(override_table)` * `override_table` is a table with the following fields: * `speed`: multiplier to default walking speed value (default: `1`) @@ -6487,43 +6799,46 @@ object you are working with still exists. * `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. + * Passing no arguments resets the sky to its default values. * `sky_parameters` is a table with the following optional fields: * `base_color`: ColorSpec, changes fog in "skybox" and "plain". + (default: `#ffffff`) * `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. + (default: `"regular"`) * `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`) + * `sky_color`: A table used in `"regular"` type only, containing the + following values (alpha is ignored): + * `day_sky`: ColorSpec, for the top half of the sky during the day. + (default: `#61b5f5`) + * `day_horizon`: ColorSpec, for the bottom half of the sky during the day. + (default: `#90d3f6`) + * `dawn_sky`: ColorSpec, for the top half of the 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`) + * `dawn_horizon`: ColorSpec, for the bottom half of the 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`) + * `night_sky`: ColorSpec, for the top half of the 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"` - sky during the night. (default: `#4090ff`) + * `night_horizon`: ColorSpec, for the bottom half of the 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. + * `indoors`: ColorSpec, for when you're either indoors or underground. (default: `#646464`) * `fog_sun_tint`: ColorSpec, changes the fog tinting for the sun - at sunrise and sunset. + at sunrise and sunset. (default: `#f47d1d`) * `fog_moon_tint`: ColorSpec, changes the fog tinting for the moon - at sunrise and sunset. + at sunrise and sunset. (default: `#7f99cc`) * `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. @@ -6541,11 +6856,12 @@ object you are working with still exists. * `get_sky_color()`: returns a table with the `sky_color` parameters as in `set_sky`. * `set_sun(sun_parameters)`: + * Passing no arguments resets the sun to its default values. * `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 `""` - will re-enable the mesh sun. (default: `"sun.png"`) + will re-enable the mesh sun. (default: "sun.png", if it exists) * `tonemap`: A 512x1 texture containing the tonemap for the sun (default: `"sun_tonemap.png"`) * `sunrise`: A regular texture for the sunrise texture. @@ -6556,17 +6872,19 @@ object you are working with still exists. * `get_sun()`: returns a table with the current sun parameters as in `set_sun`. * `set_moon(moon_parameters)`: + * Passing no arguments resets the moon to its default values. * `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 `""` - will re-enable the mesh moon. (default: `"moon.png"`) + will re-enable the mesh moon. (default: "moon.png", if it exists) * `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(star_parameters)`: + * Passing no arguments resets stars to their default values. * `star_parameters` is a table with the following optional fields: * `visible`: Boolean for whether the stars are visible. (default: `true`) @@ -6580,6 +6898,7 @@ object you are working with still exists. * `get_stars()`: returns a table with the current stars parameters as in `set_stars`. * `set_clouds(cloud_parameters)`: set cloud parameters + * Passing no arguments resets clouds to their default values. * `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 @@ -6746,7 +7065,8 @@ It can be created via `Raycast(pos1, pos2, objects, liquids)` or * `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. +* `liquids`: if false, liquid nodes (`liquidtype ~= "none"`) won't be + returned. Default is false. ### Methods @@ -6905,6 +7225,7 @@ Player properties need to be saved manually. -- "sprite" uses 1 texture. -- "upright_sprite" uses 2 textures: {front, back}. -- "wielditem" expects 'textures = {itemname}' (see 'visual' above). + -- "mesh" requires one texture for each mesh buffer/material (in order) colors = {}, -- Number of required colors depends on visual @@ -6975,7 +7296,7 @@ Player properties need to be saved manually. -- Default: false infotext = "", - -- By default empty, text to be shown when pointed at object + -- Same as infotext for nodes. Empty by default static_save = true, -- If false, never save this object statically. It will simply be @@ -7076,6 +7397,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 @@ -7225,6 +7551,8 @@ Used by `minetest.register_node`, `minetest.register_craftitem`, and range = 4.0, liquids_pointable = false, + -- If true, item points to all liquid nodes (`liquidtype ~= "none"`), + -- even those for which `pointable = false` light_source = 0, -- When used for nodes: Defines amount of light emitted by node. @@ -7233,7 +7561,7 @@ Used by `minetest.register_node`, `minetest.register_craftitem`, and -- A value outside the range 0 to minetest.LIGHT_MAX causes undefined -- behavior. - -- See "Tools" section for an example including explanation + -- See "Tool Capabilities" section for an example including explanation tool_capabilities = { full_punch_interval = 1.0, max_drop_level = 0, @@ -7280,12 +7608,17 @@ Used by `minetest.register_node`, `minetest.register_craftitem`, and }, on_place = function(itemstack, placer, pointed_thing), - -- Shall place item and return the leftover itemstack. + -- When the 'place' key was pressed with the item in hand + -- and a node was pointed at. + -- Shall place item and return the leftover itemstack + -- or nil to not modify the inventory. -- The placer may be any ObjectRef or nil. -- default: minetest.item_place on_secondary_use = function(itemstack, user, pointed_thing), -- Same as on_place but called when not pointing at a node. + -- Function must return either nil if inventory shall not be modified, + -- or an itemstack to replace the original itemstack. -- The user may be any ObjectRef or nil. -- default: nil @@ -7296,8 +7629,9 @@ Used by `minetest.register_node`, `minetest.register_craftitem`, and on_use = function(itemstack, user, pointed_thing), -- default: nil - -- Function must return either nil if no item shall be removed from - -- inventory, or an itemstack to replace the original itemstack. + -- When user pressed the 'punch/mine' key with the item in hand. + -- Function must return either nil if inventory shall not be modified, + -- or an itemstack to replace the original itemstack. -- e.g. itemstack:take_item(); return itemstack -- Otherwise, the function is free to do what it wants. -- The user may be any ObjectRef or nil. @@ -7306,7 +7640,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) @@ -7407,24 +7741,54 @@ Used by `minetest.register_node`. climbable = false, -- If true, can be climbed on (ladder) + move_resistance = 0, + -- Slows down movement of players through this node (max. 7). + -- If this is nil, it will be equal to liquid_viscosity. + -- Note: If liquid movement physics apply to the node + -- (see `liquid_move_physics`), the movement speed will also be + -- affected by the `movement_liquid_*` settings. + buildable_to = false, -- If true, placed nodes can replace this node floodable = false, -- If true, liquids flow into and replace this node. -- Warning: making a liquid node 'floodable' will cause problems. - liquidtype = "none", -- "none" / "source" / "flowing" + liquidtype = "none", -- specifies liquid flowing physics + -- * "none": no liquid flowing 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 liquid_alternative_source = "", -- Source version of flowing liquid - liquid_viscosity = 0, -- Higher viscosity = slower flow (max. 7) + liquid_viscosity = 0, + -- Controls speed at which the liquid spreads/flows (max. 7). + -- 0 is fastest, 7 is slowest. + -- By default, this also slows down movement of players inside the node + -- (can be overridden using `move_resistance`) liquid_renewable = true, -- If true, a new liquid source can be created by placing two or more -- sources nearby + liquid_move_physics = nil, -- specifies movement physics if inside node + -- * false: No liquid movement physics apply. + -- * true: Enables liquid movement physics. Enables things like + -- ability to "swim" up/down, sinking slowly if not moving, + -- smoother speed change when falling into, etc. The `movement_liquid_*` + -- settings apply. + -- * nil: Will be treated as true if `liquidype ~= "none"` + -- and as false otherwise. + -- Default: nil + leveled = 0, -- Only valid for "nodebox" drawtype with 'type = "leveled"'. -- Allows defining the nodebox height without using param2. @@ -7434,9 +7798,12 @@ 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. + -- 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 @@ -7507,7 +7874,7 @@ Used by `minetest.register_node`. -- 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. + -- 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"` @@ -7531,14 +7898,13 @@ Used by `minetest.register_node`. 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'. @@ -7552,7 +7918,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, @@ -7563,14 +7929,24 @@ 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 - -- is deprecated). + -- Only drop if using an item whose name contains + -- "default:shovel_" (this item filtering by string matching + -- is deprecated, use tool_groups instead). tools = {"~default:shovel_"}, rarity = 2, -- The item list dropped. items = {"default:sand", "default:desert_sand"}, }, + { + -- Only drop if using an item in the "magicwand" group, or + -- an item that is in both the "pickaxe" and the "lucky" + -- groups. + tool_groups = { + "magicwand", + {"pickaxe", "lucky"} + }, + items = {"default:coal_lump"}, + }, }, }, @@ -7634,9 +8010,9 @@ Used by `minetest.register_node`. on_rightclick = function(pos, node, clicker, itemstack, pointed_thing), -- default: nil - -- Called when clicker (an ObjectRef) "rightclicks" - -- ("rightclick" here stands for the placement key) while pointing at - -- the node at pos with 'node' being the node table. + -- Called when clicker (an ObjectRef) used the 'place/build' key + -- (not neccessarily an actual rightclick) + -- while pointing at the node at pos with 'node' being the node table. -- itemstack will hold clicker's wielded item. -- Shall return the leftover itemstack. -- Note: pointed_thing can be nil, if a mod calls this function. @@ -7645,7 +8021,7 @@ 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. @@ -7732,10 +8108,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 @@ -7803,7 +8191,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. @@ -7832,7 +8220,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, @@ -7840,7 +8228,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 @@ -7853,7 +8241,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, } @@ -7980,7 +8368,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" }, @@ -8236,6 +8624,9 @@ Used by `Player:hud_add`. Returned by `Player:hud_get`. z_index = 0, -- Z index : lower z-index HUDs are displayed behind higher z-index HUDs + + style = 0, + -- For "text" elements sets font style: bitfield with 1 = bold, 2 = italic, 4 = monospace } Particle definition @@ -8383,7 +8774,7 @@ 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. method = "GET", "POST", "PUT" or "DELETE" -- The http method to use. Defaults to "GET". @@ -8475,3 +8866,10 @@ Used by `minetest.register_authentication_handler`. -- Returns an iterator (use with `for` loops) for all player names -- currently in the auth database } + +Bit Library +----------- + +Functions: bit.tobit, bit.tohex, bit.bnot, bit.band, bit.bor, bit.bxor, bit.lshift, bit.rshift, bit.arshift, bit.rol, bit.ror, bit.bswap + +See http://bitop.luajit.org/ for advanced information. diff --git a/doc/menu_lua_api.txt b/doc/menu_lua_api.txt index b3975bc1d..9bc0c46bd 100644 --- a/doc/menu_lua_api.txt +++ b/doc/menu_lua_api.txt @@ -1,4 +1,4 @@ -Minetest Lua Mainmenu API Reference 5.4.0 +Minetest Lua Mainmenu API Reference 5.5.0 ========================================= Introduction @@ -85,7 +85,9 @@ core.get_video_drivers() core.get_mapgen_names([include_hidden=false]) -> table of map generator algorithms registered in the core (possible in async calls) core.get_cache_path() -> path of cache -core.get_temp_path() -> path of temp folder +core.get_temp_path([param]) (possible in async calls) +^ param=true: returns path to a temporary file +^ otherwise: returns path to the temporary folder HTTP Requests @@ -204,7 +206,8 @@ core.get_screen_info() display_width = <width of display>, display_height = <height of display>, window_width = <current window width>, - window_height = <current window height> + window_height = <current window height>, + render_info = <active render information> } @@ -218,7 +221,13 @@ Package - content which is downloadable from the content db, may or may not be i * returns path to global user data, the directory that contains user-provided mods, worlds, games, and texture packs. * core.get_modpath() (possible in async calls) - * returns path to global modpath + * returns path to global modpath, where mods can be installed +* core.get_modpaths() (possible in async calls) + * returns list of paths to global modpaths, where mods have been installed + + The difference with "core.get_modpath" is that no mods should be installed in these + directories by Minetest -- they might be read-only. + * core.get_clientmodpath() (possible in async calls) * returns path to global client-side modpath * core.get_gamepath() (possible in async calls) diff --git a/doc/minetest.6 b/doc/minetest.6 index bac70fe1a..6a3601f80 100644 --- a/doc/minetest.6 +++ b/doc/minetest.6 @@ -112,6 +112,10 @@ leveldb, and files. Migrate from current players backend to another. Possible values are sqlite3, leveldb, postgresql, dummy, and files. .TP +.B \-\-migrate-mod-storage <value> +Migrate from current mod storage backend to another. Possible values are +sqlite3, dummy, and files. +.TP .B \-\-terminal Display an interactive terminal over ncurses during execution. @@ -119,6 +123,9 @@ Display an interactive terminal over ncurses during execution. .TP .B MINETEST_SUBGAME_PATH Colon delimited list of directories to search for games. +.TP +.B MINETEST_MOD_PATH +Colon delimited list of directories to search for mods. .SH BUGS Please report all bugs at https://github.com/minetest/minetest/issues. diff --git a/doc/texture_packs.txt b/doc/texture_packs.txt index 8af2cbad6..f738032b6 100644 --- a/doc/texture_packs.txt +++ b/doc/texture_packs.txt @@ -90,9 +90,10 @@ by texture packs. All existing fallback textures can be found in the directory * `minimap_mask_square.png`: mask used for the square minimap * `minimap_overlay_round.png`: overlay texture for the round minimap * `minimap_overlay_square.png`: overlay texture for the square minimap -* `no_texture_airlike.png`: fallback inventory image for airlike nodes * `object_marker_red.png`: texture for players on the minimap * `player_marker.png`: texture for the own player on the square minimap +* `no_texture_airlike.png`: fallback inventory image for airlike nodes +* `no_texture.png`: fallback image for unspecified textures * `player.png`: front texture of the 2D upright sprite player * `player_back.png`: back texture of the 2D upright sprite player diff --git a/doc/world_format.txt b/doc/world_format.txt index a8a9e463e..eb1d7f728 100644 --- a/doc/world_format.txt +++ b/doc/world_format.txt @@ -1,5 +1,5 @@ ============================= -Minetest World Format 22...27 +Minetest World Format 22...29 ============================= This applies to a world format carrying the block serialization version @@ -8,6 +8,7 @@ This applies to a world format carrying the block serialization version - 0.4.0 (23) - 24 was never released as stable and existed for ~2 days - 27 was added in 0.4.15-dev +- 29 was added in 5.5.0-dev 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 @@ -281,6 +282,8 @@ MapBlock serialization format NOTE: Byte order is MSB first (big-endian). NOTE: Zlib data is in such a format that Python's zlib at least can directly decompress. +NOTE: Since version 29 zstd is used instead of zlib. In addition the entire + block is first serialized and then compressed (except the version byte). u8 version - map format version number, see serialisation.h for the latest number @@ -324,6 +327,20 @@ u16 lighting_complete then Minetest will correct lighting in the day light bank when the block at (1, 0, 0) is also loaded. +if map format version >= 29: + u32 timestamp + - Timestamp when last saved, as seconds from starting the game. + - 0xffffffff = invalid/unknown timestamp, nothing should be done with the time + difference when loaded + + u16 num_name_id_mappings + foreach num_name_id_mappings + u16 id + u16 name_len + u8[name_len] name +if map format version < 29: + -- Nothing right here, timpstamp and node id mappings are serialized later + u8 content_width - Number of bytes in the content (param0) fields of nodes if map format version <= 23: @@ -335,7 +352,7 @@ u8 params_width - Number of bytes used for parameters per node - Always 2 -zlib-compressed node data: +node data (zlib-compressed if version < 29): if content_width == 1: - content: u8[4096]: param0 fields @@ -348,31 +365,31 @@ if content_width == 2: u8[4096]: param2 fields - The location of a node in each of those arrays is (z*16*16 + y*16 + x). -zlib-compressed node metadata list +node metadata list (zlib-compressed if version < 29): - content: -if map format version <= 22: - 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] content of metadata. Format depends on type_id, see below. -if map format version >= 23: - u8 version -- Note: type was u16 for map format version <= 22 - -- = 1 for map format version < 28 - -- = 2 since map format version 28 - u16 count of metadata - foreach count: - u16 position (p.Z*MAP_BLOCKSIZE*MAP_BLOCKSIZE + p.Y*MAP_BLOCKSIZE + p.X) - u32 num_vars - foreach num_vars: - u16 key_len - u8[key_len] key - u32 val_len - u8[val_len] value - u8 is_private -- only for version >= 2. 0 = not private, 1 = private - serialized inventory + if map format version <= 22: + 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] content of metadata. Format depends on type_id, see below. + if map format version >= 23: + u8 version -- Note: type was u16 for map format version <= 22 + -- = 1 for map format version < 28 + -- = 2 since map format version 28 + u16 count of metadata + foreach count: + u16 position (p.Z*MAP_BLOCKSIZE*MAP_BLOCKSIZE + p.Y*MAP_BLOCKSIZE + p.X) + u32 num_vars + foreach num_vars: + u16 key_len + u8[key_len] key + u32 val_len + u8[val_len] value + u8 is_private -- only for version >= 2. 0 = not private, 1 = private + serialized inventory - Node timers if map format version == 23: @@ -403,20 +420,18 @@ foreach static_object_count: u16 data_size u8[data_size] data -u32 timestamp -- Timestamp when last saved, as seconds from starting the game. -- 0xffffffff = invalid/unknown timestamp, nothing should be done with the time - difference when loaded - -u8 name-id-mapping version -- Always 0 +if map format version < 29: + u32 timestamp + - Same meaning as the timestamp further up -u16 num_name_id_mappings + u8 name-id-mapping version + - Always 0 -foreach num_name_id_mappings - u16 id - u16 name_len - u8[name_len] name + u16 num_name_id_mappings + foreach num_name_id_mappings + u16 id + u16 name_len + u8[name_len] name - Node timers if map format version == 25: |