From a64af4e9143faf41319d8f9882be951c4f31b420 Mon Sep 17 00:00:00 2001 From: Bradley Pierce Date: Sat, 20 Jan 2024 08:14:01 -0500 Subject: [PATCH] Refactor lua_api.md --- doc/lua_api.md | 1687 +++++++++++++++++++++--------------------------- 1 file changed, 744 insertions(+), 943 deletions(-) diff --git a/doc/lua_api.md b/doc/lua_api.md index 1f62e46a01..b8b3c2243a 100644 --- a/doc/lua_api.md +++ b/doc/lua_api.md @@ -1,12 +1,10 @@ -Minetest Lua Modding API Reference -================================== +# Minetest Lua Modding API Reference -* More information at -* Developer Wiki: +* More information at +* Developer Wiki: * (Unofficial) Minetest Modding Book by rubenwardy: -Introduction ------------- +## Introduction Content and functionality can be added to Minetest using Lua scripting in run-time loaded mods. @@ -20,20 +18,17 @@ files are automatically transferred to the client. If you see a deficiency in the API, feel free to attempt to add the functionality in the engine and API, and to document it here. -Programming in Lua ------------------- +## Programming in Lua If you have any difficulty in understanding this, please read [Programming in Lua](http://www.lua.org/pil/). -Startup -------- +## Startup Mods are loaded during server startup from the mod load paths by running the `init.lua` scripts in a shared environment. -Paths ------ +## Paths Minetest keeps and looks for files mostly in two paths. `path_share` or `path_user`. @@ -46,8 +41,9 @@ the build directory. For system-wide builds on Linux the share path is usually a `/usr/share/minetest` while the user path resides in `.minetest` in the home directory. Paths on other operating systems will differ. -Games -===== + + +# Games Games are looked up from: @@ -101,8 +97,7 @@ The game directory can contain the following files: texturepack, overriding mod textures. Any server texturepack will override mod textures and the game texturepack. -Menu images ------------ +## Menu Images Games can provide custom main menu images. They are put inside a `menu` directory inside the game directory. @@ -113,8 +108,7 @@ 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 ------------ +## Menu Music Games can provide custom main menu music. They are put inside a `menu` directory inside the game directory. @@ -124,11 +118,11 @@ 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 -==== -Mod load path -------------- + +# Mods + +## Mod Load Path Paths are relative to the directories listed in the [Paths] section above. @@ -136,8 +130,7 @@ Paths are relative to the directories listed in the [Paths] section above. * `mods/` * `worlds//worldmods/` -World-specific games --------------------- +## World-Specific Games It is possible to include a game in a world; in this case, no mods or games are loaded or checked from anywhere else. @@ -147,8 +140,7 @@ directory exists. Mods should then be placed in `/game/mods/`. -Modpacks --------- +## Modpacks Mods can be put in a subdirectory, if the parent directory, which otherwise should be a mod, contains a file named `modpack.conf`. @@ -166,36 +158,35 @@ The file is a key-value store of modpack details. Note: to support 0.4.x, please also create an empty modpack.txt file. -Mod directory structure ------------------------ +## Mod Directory Structure mods ├── modname - │   ├── mod.conf - │   ├── screenshot.png - │   ├── settingtypes.txt - │   ├── init.lua - │   ├── models - │   ├── textures - │   │   ├── modname_stuff.png - │   │   ├── modname_stuff_normal.png - │   │   ├── modname_something_else.png - │   │   ├── subfolder_foo - │   │   │ ├── modname_more_stuff.png - │   │   │ └── another_subfolder - │   │   └── bar_subfolder - │   ├── sounds - │   ├── media - │   ├── locale - │   └── + │ ├── mod.conf + │ ├── screenshot.png + │ ├── settingtypes.txt + │ ├── init.lua + │ ├── models + │ ├── textures + │ │ ├── modname_stuff.png + │ │ ├── modname_stuff_normal.png + │ │ ├── modname_something_else.png + │ │ ├── subfolder_foo + │ │ │ ├── modname_more_stuff.png + │ │ │ └── another_subfolder + │ │ └── bar_subfolder + │ ├── sounds + │ ├── media + │ ├── locale + │ └── └── another -### modname +### `modname` The location of this directory can be fetched by using `minetest.get_modpath(modname)`. -### mod.conf +### `mod.conf` A `Settings` file that provides meta information about the mod. @@ -246,15 +237,15 @@ The format is documented in `builtin/settingtypes.txt`. It is parsed by the main menu settings dialogue to list mod-specific settings in the "Mods" category. -`minetest.settings` can be used to read custom or engine settings. -See [`Settings`]. - ### `init.lua` The main Lua script. Running this script should register everything it wants to register. Subsequent execution depends on Minetest calling the registered callbacks. +`minetest.settings` can be used to read custom or existing settings at load +time, if necessary. (See [`Settings`]) + ### `textures`, `sounds`, `media`, `models`, `locale` Media files (textures, sounds, whatever) that will be transferred to the @@ -284,8 +275,7 @@ 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 ------------------- +## Naming Conventions Registered names should generally be in this format: @@ -317,9 +307,7 @@ when registering it. For this to work correctly, that mod must have - -Aliases -======= +# Aliases Aliases of itemnames can be added by using `minetest.register_alias(alias, original_name)` or @@ -338,21 +326,24 @@ This can be used for maintaining backwards compatibility. This can also set quick access names for things, e.g. if you have an item called `epiclylongmodname:stuff`, you could do - minetest.register_alias("stuff", "epiclylongmodname:stuff") +```lua +minetest.register_alias("stuff", "epiclylongmodname:stuff") +``` and be able to use `/giveme stuff`. -Mapgen aliases --------------- +## Mapgen Aliases In a game, a certain number of these must be set to tell core mapgens which of the game's nodes are to be used for core mapgen generation. For example: - minetest.register_alias("mapgen_stone", "default:stone") +```lua +minetest.register_alias("mapgen_stone", "default:stone") +``` -### Aliases for non-V6 mapgens +### Aliases for Non-V6 Mapgens -#### Essential aliases +#### Essential Aliases * `mapgen_stone` * `mapgen_water_source` @@ -362,7 +353,7 @@ of the game's nodes are to be used for core mapgen generation. For example: it is necessary to have a river liquid node with a short `liquid_range` and `liquid_renewable = false` to avoid flooding. -#### Optional aliases +#### Optional Aliases * `mapgen_lava_source` @@ -411,17 +402,17 @@ Deprecated, define dungeon nodes in biome definitions instead. * `mapgen_mossycobble` (falls back to cobble) * `mapgen_stair_desert_stone` (falls back to desert_stone) -### Setting the node used in Mapgen Singlenode +### Setting the Node Used in Mapgen Singlenode By default the world is filled with air nodes. To set a different node use e.g.: - minetest.register_alias("mapgen_singlenode", "default:stone") +```lua +minetest.register_alias("mapgen_singlenode", "default:stone") +``` - -Textures -======== +# Textures Mods should generally prefix their textures with `modname_`, e.g. given the mod name `foomod`, a texture could be called: @@ -438,15 +429,14 @@ Supported texture formats are PNG (`.png`), JPEG (`.jpg`), Bitmap (`.bmp`) and Targa (`.tga`). Since better alternatives exist, the latter two may be removed in the future. -Texture modifiers ------------------ +## Texture Modifiers There are various texture modifiers that can be used to let the client generate textures on-the-fly. The modifiers are applied directly in sRGB colorspace, i.e. without gamma-correction. -### Texture overlaying +### Texture Overlaying Textures can be overlaid by putting a `^` between them. @@ -458,7 +448,7 @@ Example: The texture with the lower resolution will be automatically upscaled to the higher resolution texture. -### Texture grouping +### Texture Grouping Textures can be grouped together by enclosing them in `(` and `)`. @@ -479,7 +469,7 @@ Or as a Lua string: `"cobble.png^[lowpart:50:color.png\\^[mask\\:trans.png"` The lower 50 percent of `color.png^[mask:trans.png` are overlaid on top of `cobble.png`. -### Advanced texture modifiers +### Advanced Texture Modifiers #### Crack @@ -578,14 +568,16 @@ Rotates and/or flips the image. `` can be a number (between 0 and 7) or a transform name. Rotations are counter-clockwise. - 0 I identity - 1 R90 rotate by 90 degrees - 2 R180 rotate by 180 degrees - 3 R270 rotate by 270 degrees - 4 FX flip X - 5 FXR90 flip X then rotate by 90 degrees - 6 FY flip Y - 7 FYR90 flip Y then rotate by 90 degrees +| t | transform name | action | +|---|----------------|----------------------------------| +| 0 | I | identity | +| 1 | R90 | rotate by 90 degrees | +| 2 | R180 | rotate by 180 degrees | +| 3 | R270 | rotate by 270 degrees | +| 4 | FX | flip X | +| 5 | FXR90 | flip X then rotate by 90 degrees | +| 6 | FY | flip Y | +| 7 | FYR90 | flip Y then rotate by 90 degrees | Example: @@ -665,7 +657,7 @@ Colorize the textures with the given color. `` is an int ranging from 0 to 255 or the word "`alpha`". If it is an int, then it specifies how far to interpolate between the colors where 0 is only the texture color and 255 is only ``. If -omitted, the alpha of `` will be used as the ratio. If it is +omitted, the alpha of `` will be used as the ratio. If it is the word "`alpha`", then each texture pixel will contain the RGB of `` and the alpha of `` multiplied by the alpha of the texture pixel. @@ -775,15 +767,13 @@ 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. +> [!WARNING] 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 ------------------ +## Hardware Coloring The goal of hardware coloring is to simplify the creation of colorful nodes. If your textures use the same pattern, and they only @@ -792,12 +782,12 @@ coloring instead of creating and managing many texture files. All of these methods use color multiplication (so a white-black texture with red coloring will result in red-black color). -### Static coloring +### Static Coloring This method is useful if you wish to create nodes/items with the same texture, in different colors, each in a new node/item definition. -#### Global color +#### Global Color When you register an item or node, set its `color` field (which accepts a `ColorSpec`) to the desired color. @@ -805,7 +795,7 @@ When you register an item or node, set its `color` field (which accepts a An `ItemStack`'s static color can be overwritten by the `color` metadata field. If you set that field to a `ColorString`, that color will be used. -#### Tile color +#### Tile Color Each tile may have an individual static color, which overwrites every other coloring method. To disable the coloring of a face, @@ -820,7 +810,7 @@ suitable. A palette is a texture, which can contain up to 256 pixels. Each pixel is one possible color for the node/item. You can register one node/item, which can have up to 256 colors. -#### Palette indexing +#### Palette Indexing When using palettes, you always provide a pixel index for the given node or `ItemStack`. The palette is read from left to right and from @@ -841,7 +831,7 @@ Examples: * 2x4 palette, index = 63: the top right corner * 2x4 palette, index = 64: the pixel below the top left corner -#### Using palettes with items +#### Using Palettes with Items When registering an item, set the item definition's `palette` field to a texture. You can also use texture modifiers. @@ -850,7 +840,7 @@ The `ItemStack`'s color depends on the `palette_index` field of the stack's metadata. `palette_index` is an integer, which specifies the index of the pixel to use. -#### Linking palettes with nodes +#### Linking Palettes with Nodes When registering a node, set the item definition's `palette` field to a texture. You can also use texture modifiers. @@ -897,7 +887,7 @@ appropriate `paramtype2`: To colorize a node on the map, set its `param2` value (according to the node's paramtype2). -### Conversion between nodes in the inventory and on the map +### Conversion Between Nodes in the Inventory and on the Map Static coloring is the same for both cases, there is no need for conversion. @@ -923,13 +913,13 @@ minetest.register_node("mod:stone", { drop = { items = { -- assume that mod:cobblestone also has the same palette - {items = {"mod:cobblestone"}, inherit_color = true }, + {items = {"mod:cobblestone"}, inherit_color = true}, } } }) ``` -### Colored items in craft recipes +### Colored Items in Craft Recipes Craft recipes only support item strings, but fortunately item strings can also contain metadata. Example craft recipe registration: @@ -950,8 +940,7 @@ To set the `color` field, you can use `minetest.itemstring_with_color`. Metadata field filtering in the `recipe` field are not supported yet, so the craft output is independent of the color of the ingredients. -Soft texture overlay --------------------- +## Soft Texture Overlay Sometimes hardware coloring is not enough, because it affects the whole tile. Soft texture overlays were added to Minetest to allow @@ -986,7 +975,8 @@ minetest.register_node("default:dirt_with_grass", { -- Overlay tiles: define them in the same style -- The top and bottom tile does not have overlay overlay_tiles = {"", "", - {name = "default_grass_side.png"}}, + {name = "default_grass_side.png"} + }, -- Global color, used in inventory color = "green", -- Palette in the world @@ -997,8 +987,7 @@ minetest.register_node("default:dirt_with_grass", { -Sounds -====== +# Sounds Only Ogg Vorbis files are supported. @@ -1006,17 +995,18 @@ For positional playing of sounds, only single-channel (mono) files are supported. Otherwise OpenAL will play them non-positionally. Mods should generally prefix their sound files with `modname_`, e.g. given -the mod name "`foomod`", a sound could be called: +the mod name `foomod`, a sound could be called: foomod_foosound.ogg -Sound group ------------ +## Sound Group A sound group is the set of all sound files, whose filenames are of the following format: -`[.].ogg` -When a sound-group is played, one the files in the group is chosen at random. + + [.].ogg + +When a sound group is played, one the files in the group is chosen at random. Sound files can only be referred to by their sound-group name. Example: When playing the sound `foomod_foosound`, the sound is chosen randomly @@ -1028,10 +1018,9 @@ from the available ones of the following files: * (...) * `foomod_foosound.9.ogg` -`SimpleSoundSpec` ------------------ +## `SimpleSoundSpec` -Specifies a sound name, gain (=volume), pitch and fade. +Specifies a sound name, gain (volume), pitch and fade. This is either a string or a table. In string form, you just specify the sound name or @@ -1040,7 +1029,7 @@ the empty string for no sound. Table form has the following fields: * `name`: - Sound-group name. + Sound group name. If == `""`, no sound is played. * `gain`: Volume (`1.0` = 100%), must be non-negative. @@ -1068,8 +1057,7 @@ Examples: * `{name = "default_place_node", gain = 0.5}`: 50% volume * `{name = "default_place_node", gain = 0.9, pitch = 1.1}`: 90% volume, 110% pitch -Sound parameter table ---------------------- +## Sound Parameter Table Table used to specify how a sound is played: @@ -1164,20 +1152,20 @@ Examples: } ``` -Special sound-groups --------------------- +## Special Sound Groups -These sound-groups are played back by the engine if provided. +These sound groups are played back by the engine if provided. - * `player_damage`: Played when the local player takes damage (gain = 0.5) - * `player_falling_damage`: Played when the local player takes +* `player_damage`: Played when the local player takes damage (gain = 0.5) +* `player_falling_damage`: Played when the local player takes damage by falling (gain = 0.5) - * `player_jump`: Played when the local player jumps - * `default_dig_`: Default node digging sound (gain = 0.5) +* `player_jump`: Played when the local player jumps +* `default_dig_`: Default node digging sound (gain = 0.5) (see node sound definition for details) -Registered definitions -====================== + + +# Registered Definitions Anything added using certain [Registration functions] gets added to one or more of the global [Registered definition tables]. @@ -1200,8 +1188,7 @@ local drawtype = def and def.drawtype -Nodes -===== +# Nodes Nodes are the bulk data of the world: cubes and other things that take the space of a cube. Huge amounts of them are handled efficiently, but they @@ -1226,8 +1213,7 @@ They are represented by a table: them for certain automated functions. If you don't use these functions, you can use them to store arbitrary values. -Node paramtypes ---------------- +## Node `paramtype`s The functions of `param1` and `param2` are determined by certain fields in the node definition. @@ -1377,8 +1363,7 @@ The function of `param2` is determined by `paramtype2` in node definition. Nodes can also contain extra data. See [Node Metadata]. -Node drawtypes --------------- +## Node `drawtype`s There are a bunch of different looking node types. @@ -1493,8 +1478,7 @@ Look for examples in `games/devtest` or `games/minetest_game`. `*_optional` drawtypes need less rendering time if deactivated (always client-side). -Node boxes ----------- +## Node Boxes Node selection boxes are defined using "node boxes". @@ -1561,7 +1545,7 @@ A `box` is defined as: A box of a regular node would look like: ```lua -{-0.5, -0.5, -0.5, 0.5, 0.5, 0.5}, +{-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. @@ -1570,11 +1554,9 @@ exceed this soft limit. -Map terminology and coordinates -=============================== +# Map Terminology and Coordinates -Nodes, mapblocks, mapchunks ---------------------------- +## Nodes, Mapblocks, and Mapchunks A 'node' is the fundamental cubic unit of a world and appears to a player as roughly 1x1x1 meters in size. @@ -1590,32 +1572,31 @@ A 'mapchunk' (sometimes abbreviated to 'chunk') is usually 5x5x5 mapblocks the map generator. The size in mapblocks has been chosen to optimize map generation. -Coordinates ------------ +## Coordinates -### Orientation of axes +### Orientation of Axes For node and mapblock coordinates, +X is East, +Y is up, +Z is North. -### Node coordinates +### Node Coordinates Almost all positions used in the API use node coordinates. -### Mapblock coordinates +### Mapblock Coordinates Occasionally the API uses 'blockpos' which refers to mapblock coordinates that specify a particular mapblock. For example blockpos (0,0,0) specifies the mapblock that extends from node position (0,0,0) to node position (15,15,15). -#### Converting node position to the containing blockpos +#### Converting Node Position to the Containing `blockpos` To calculate the blockpos of the mapblock that contains the node at 'nodepos', for each axis: * blockpos = math.floor(nodepos / 16) -#### Converting blockpos to min/max node positions +#### Converting `blockpos` to Minimum/Maximum Node Positions To calculate the min/max node positions contained in the mapblock at 'blockpos', for each axis: @@ -1627,12 +1608,9 @@ for each axis: +# HUD -HUD -=== - -HUD element types ------------------ +## HUD Element Types The `position` field is used for all element types. To account for differing resolutions, the position coordinates are the @@ -1654,8 +1632,7 @@ The `offset` field specifies a pixel offset from the position. Contrary to position, the offset is not scaled to screen size. This allows for some precisely positioned items in the HUD. -**Note**: `offset` _will_ adapt to screen DPI as well as user defined scaling -factor! +> [!NOTE] `offset` _will_ adapt to screen DPI as well as the user defined scaling factor! The `z_index` field specifies the order of HUD elements from back to front. Lower z-index elements are displayed behind higher z-index elements. Elements @@ -1792,11 +1769,11 @@ Displays a minimap on the HUD. * `alignment`: The alignment of the minimap. * `offset`: offset in pixels from position. -Representations of simple things -================================ -Vector (ie. a position) ------------------------ + +# Representations of Simple Things + +## Vector (ie. a Position) ```lua vector.new(x, y, z) @@ -1804,8 +1781,7 @@ vector.new(x, y, z) See [Spatial Vectors] for details. -`pointed_thing` ---------------- +## `pointed_thing` * `{type="nothing"}` * `{type="node", under=pos, above=pos}` @@ -1829,9 +1805,7 @@ Exact pointing location (currently only `Raycast` supports these fields): - -Flag Specifier Format -===================== +# Flag Specifier Format Flags using the standardized flag specifier format can be specified in either of two ways, by string or table. @@ -1874,17 +1848,14 @@ since, by default, no schematic attributes are set. - -Items -===== +# 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 ----------- +## Item Types There are three kinds of items: nodes, tools and craftitems. @@ -1910,8 +1881,7 @@ 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 ---------------- +## Amount and Wear All item stacks have an amount between 0 and 65535. It is 1 by default. Tool item stacks cannot have an amount greater than 1. @@ -1923,8 +1893,7 @@ 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 ------------- +## Item Formats Items and item stacks can exist in three formats: Serializes, table format and `ItemStack`. @@ -1964,16 +1933,18 @@ You should ideally use the `ItemStack` format to build complex item strings (especially if they use item metadata) without relying on the serialization format. Example: - local stack = ItemStack("default:pick_wood") - stack:set_wear(21323) - stack:get_meta():set_string("description", "My worn out pick") - local itemstring = stack:to_string() +```lua +local stack = ItemStack("default:pick_wood") +stack:set_wear(21323) +stack:get_meta():set_string("description", "My worn out pick") +local itemstring = stack:to_string() +``` Additionally the methods `minetest.itemstring_with_palette(item, palette_index)` and `minetest.itemstring_with_color(item, colorstring)` may be used to create item strings encoding color information in their metadata. -### Table format +### Table Format Examples: @@ -2002,17 +1973,14 @@ between formats. See the [Class reference] section for details. - -Groups -====== +# Groups In a number of places, there is a group table. Groups define the 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 ------ +## Usage Groups are stored in a table, having the group names with keys and the group ratings as values. Group ratings are integer values within the @@ -2038,19 +2006,16 @@ You can read the rating of a group for an item or a node by using minetest.get_item_group(itemname, groupname) ``` -Groups of items ---------------- +## Groups of Items Groups of items can define what kind of an item it is (e.g. wool). -Groups of nodes ---------------- +## Groups of Nodes In addition to the general item things, groups are used to define whether a node is destroyable and how long it takes to destroy by a tool. -Groups of entities ------------------- +## Groups of Entities For entities, groups are, as of now, used only for calculating damage. The rating is the percentage of damage caused by items with this damage group. @@ -2061,14 +2026,12 @@ object:get_armor_groups() --> a group-rating table (e.g. {fleshy=100}) object:set_armor_groups({fleshy=30, cracky=80}) ``` -Groups of tool capabilities ---------------------------- +## Groups of Tool Capabilities Groups in tool capabilities define which groups of nodes and entities they are effective towards. -Groups in crafting recipes --------------------------- +## Groups in Crafting Recipes In crafting recipes, you can specify a group as an input item. This means that any item in that group will be accepted as input. @@ -2100,7 +2063,7 @@ An example recipe: Craft a raw meat soup from any meat, any water and any bowl: {"group:meat"}, {"group:water"}, {"group:bowl"}, - }, + } } ``` @@ -2116,20 +2079,18 @@ Another example: Craft red wool from white wool and red dye } ``` -Special groups --------------- +## Special Groups The asterisk `(*)` after a group name describes that there is no engine functionality bound to it, and implementation is left up as a suggestion to games. -### Node and item 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. - -### Node-only groups +### Node-Only Groups * `attached_node`: the node is 'attached' to a neighboring node. It checks whether the node it is attached to is walkable. If it @@ -2177,14 +2138,12 @@ to games. * `slippery`: Players and items will slide on the node. Slipperiness rises steadily with `slippery` value, starting at 1. - -### Tool-only groups +### Tool-Only Groups * `disable_repair`: If set to 1 for a tool, it cannot be repaired using the `"toolrepair"` crafting recipe - -### `ObjectRef` armor 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 @@ -2197,10 +2156,7 @@ to games. players punching it by hand or a non-tool item, so that it can do something else than take damage. - - -Known damage and digging time defining groups ---------------------------------------------- +## Known Damage and Digging Time Defining Groups * `crumbly`: dirt, sand * `cracky`: tough but crackable stuff like stone. @@ -2217,8 +2173,7 @@ Known damage and digging time defining groups digging speed of an item if it can dig at a faster speed than this suggests for the hand. -Examples of custom groups -------------------------- +## Examples of Custom Groups Item groups are often used for defining, well, _groups of items_. @@ -2233,8 +2188,7 @@ Item groups are often used for defining, well, _groups of items_. * `weapon`: any weapon * `heavy`: anything considerably heavy -Digging time calculation specifics ----------------------------------- +## Digging Time Calculation Specifics Groups such as `crumbly`, `cracky` and `snappy` are used for this purpose. Rating is `1`, `2` or `3`. A higher rating for such a group implies @@ -2252,9 +2206,7 @@ groups to enable interaction with items. - -Tool Capabilities -================= +# Tool Capabilities 'Tool capabilities' is a property of items that defines two things: @@ -2267,8 +2219,7 @@ 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 Definition Tool capabilities define: @@ -2281,13 +2232,13 @@ Tool capabilities define: * Damage groups * Punch attack uses (until the tool breaks) -### Full punch interval `full_punch_interval` +### `full_punch_interval` 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 `max_drop_level` +### `max_drop_level` 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). @@ -2295,7 +2246,7 @@ its useful item. (e.g. iron ore to drop a lump of iron). This value is not used in the engine; it is the responsibility of the game/mod code to implement this. -### Uses `uses` (tools only) +### `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. The maximum supported number of @@ -2310,12 +2261,12 @@ node's `level` group. The node cannot be dug if `leveldiff` is less than zero. For non-tools, this has no effect. -### Maximum level `maxlevel` +### `maxlevel` Tells what is the maximum level of a node of this group that the item will be able to dig. -### Digging times `times` +### `times` List of digging times for different ratings of the group, for nodes of the maximum level. @@ -2329,11 +2280,11 @@ If the result digging time is 0, a delay of 0.15 seconds is added between digging nodes; If the player releases LMB after digging, this delay is set to 0, i.e. players can more quickly click the nodes away instead of holding LMB. -### Damage groups +### Damage Groups List of damage for groups of entities. See [Entity damage mechanism]. -### Punch attack uses (tools only) +### 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 @@ -2344,8 +2295,7 @@ the full punch interval. For non-tools, this has no effect. -Example definition of the capabilities of an item -------------------------------------------------- +## Example Definition of the Capabilities of an Item ```lua tool_capabilities = { @@ -2358,7 +2308,7 @@ tool_capabilities = { This makes the item capable of digging nodes that fulfill both of these: * Have the `crumbly` group -* Have a `level` group less or equal to `2` +* Have a `level` group less or equal to `2`\n [a-z] Table of resulting digging times: @@ -2377,28 +2327,29 @@ Table of resulting tool uses: 2 180 60 20 - - 3 180 60 20 - - -**Notes**: - -* At `crumbly==0`, the node is not diggable. -* At `crumbly==3`, the level difference digging time divider kicks in and makes - easy nodes to be quickly breakable. -* At `level > 2`, the node is not diggable, because it's `level > maxlevel` +> [!NOTE] +> * At `crumbly==0`, the node is not diggable. +> * At `crumbly==3`, the level difference digging time divider kicks in and makes +> easy nodes to be quickly breakable. +> * At `level > 2`, the node is not diggable, because it's `level > maxlevel` - -Entity damage mechanism -======================= +# Entity Damage Mechanism Damage calculation: - damage = 0 - foreach group in cap.damage_groups: - damage += cap.damage_groups[group] - * limit(actual_interval / cap.full_punch_interval, 0.0, 1.0) - * (object.armor_groups[group] / 100.0) - -- Where object.armor_groups[group] is 0 for inexistent values - return damage +```lua +damage = 0 +for group in cap.damage_groups do + armor = object.armor_groups[group] or 0 + damage = damage + + cap.damage_groups[group] + * limit(actual_interval / cap.full_punch_interval, 0.0, 1.0) + * (armor / 100.0) +end +return damage +``` Client predicts damage based on damage groups. Because of this, it is able to give an immediate response when an entity is damaged or dies; the response is @@ -2445,12 +2396,9 @@ object:punch(puncher, time_from_last_punch, tool_capabilities, direction) +# Metadata -Metadata -======== - -Node Metadata -------------- +## Node Metadata The instance of a node in the world normally only contains the three values mentioned in [Nodes]. However, it is possible to insert extra data into a node. @@ -2510,8 +2458,7 @@ meta:from_table({ }) ``` -Item Metadata -------------- +## Item Metadata Item stacks can store metadata too. See [`ItemStackMetaRef`]. @@ -2566,8 +2513,8 @@ print(ItemStack("mod:item_with_no_desc"):get_description()) --> mod:item_with_no ``` -Formspec -======== + +# Formspec Formspec defines a menu. This supports inventories and some of the typical widgets like buttons, checkboxes, text input fields, etc. @@ -2578,7 +2525,7 @@ like buttons but also can be used to set stuff like background color. Many formspec elements have a `name`, which is a unique identifier which is used when the server receives user input. You must not use the name -"quit" for formspec elements. +`quit` for formspec elements. Spaces and newlines can be inserted between the blocks, as is used in the examples. @@ -2589,8 +2536,8 @@ of the menu or container. `W` and `H` are its width and height values. If the new system is enabled, all elements have unified coordinates for all elements with no padding or spacing in between. This is highly recommended -for new forms. See `real_coordinates[]` and `Migrating to Real -Coordinates`. +for new forms. See `real_coordinates[]` and [Migrating to Real +Coordinates]. Inventories with a `player:` inventory location are only sent to the player named ``. @@ -2602,16 +2549,15 @@ For colored text you can use `minetest.colorize`. Since formspec version 3, elements drawn in the order they are defined. All background elements are drawn before all other elements. -**WARNING**: do _not_ use an element name starting with `key_`; those names are -reserved to pass key press events to formspec! +> [!WARNING] Do _not_ use an element name starting with `key_`; those names are + reserved to pass key press events to formspec! -**WARNING**: Minetest allows you to add elements to every single formspec instance -using `player:set_formspec_prepend()`, which may be the reason backgrounds are -appearing when you don't expect them to, or why things are styled differently -to normal. See [`no_prepend[]`] and [Styling Formspecs]. +> [!WARNING] Minetest allows you to add elements to every single formspec instance + using `player:set_formspec_prepend`, which may be the reason backgrounds are + appearing when you don't expect them to, or why things are styled differently + to normal. See [`no_prepend[]`] and [Styling Formspecs]. -Examples --------- +## Examples ### Chest @@ -2627,7 +2573,7 @@ Examples list[context;dst;5,1;2,2;] list[current_player;main;0,5;8,4;] -### Minecraft-like player inventory +### Minecraft-Like Player Inventory size[8,7.5] image[1,0.6;1,2;player.png] @@ -2635,36 +2581,34 @@ Examples list[current_player;craft;3,0;3,3;] list[current_player;craftpreview;7,1;1,1;] -Version History ---------------- +## Version History * Formspec version 1 (pre-5.1.0): * (too much) * Formspec version 2 (5.1.0): * Forced real coordinates - * background9[]: 9-slice scaling parameters + * `background9[]`: 9-slice scaling parameters * 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[] + * `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 (5.4.0): * Allow dropdown indexing events * Formspec version 5 (5.5.0): - * Added padding[] element + * Added `padding[]` element * Formspec version 6 (5.6.0): - * Add nine-slice images, animated_image, and fgimg_middle + * Add nine-slice images, `animated_image`, and `fgimg_middle` * Formspec version 7 (5.8.0): - * style[]: Add focused state for buttons - * Add field_enter_after_edit[] (experimental) + * `style[]`: Add focused state for buttons + * Add `field_enter_after_edit[]` (experimental) -Elements --------- +## Elements ### `formspec_version[]` -* Set the formspec version to a certain number. If not specified, - version 1 is assumed. +* Set the formspec version to a certain number. If not specified, version 1 + is assumed. * Must be specified before `size` element. * Clients older than this version can neither show newer elements nor display elements with new arguments correctly. @@ -2681,21 +2625,21 @@ Elements * Must be used after `size` element. * Defines the position on the game window of the formspec's `anchor` point. -* For X and Y, 0.0 and 1.0 represent opposite edges of the game window, +* For X and Y, `0.0` and `1.0` represent opposite edges of the game window, for example: - * [0.0, 0.0] sets the position to the top left corner of the game window. - * [1.0, 1.0] sets the position to the bottom right of the game window. -* Defaults to the center of the game window [0.5, 0.5]. + * `[0.0, 0.0]` sets the position to the top left corner of the game window. + * `[1.0, 1.0]` sets the position to the bottom right of the game window. +* Defaults to `[0.5, 0.5]`, the center of the game window. ### `anchor[,]` * Must be used after both `size` and `position` (if present) elements. * Defines the location of the anchor point within the formspec. -* For X and Y, 0.0 and 1.0 represent opposite edges of the formspec, +* For X and Y, `0.0` and `1.0` represent opposite edges of the formspec, for example: - * [0.0, 1.0] sets the anchor to the bottom left corner of the formspec. - * [1.0, 0.0] sets the anchor to the top right of the formspec. -* Defaults to the center of the formspec [0.5, 0.5]. + * `[0.0, 1.0]` sets the anchor to the bottom left corner of the formspec. + * `[1.0, 0.0]` sets the anchor to the top right of the formspec. +* Defaults to `[0.5, 0.5]`, the center of the formspec. * `position` and `anchor` elements need suitable values to avoid a formspec extending off the game window due to particular game window sizes. @@ -2705,35 +2649,35 @@ Elements * 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]. +* 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. +* Disables `player:set_formspec_prepend` from applying to this formspec. ### `real_coordinates[]` -* INFORMATION: Enable it automatically using `formspec_version` version 2 or newer. +> [!NOTE] Enable it automatically using formspec version 2 or higher. * When set to true, all following formspec elements will use the new coordinate system. * If used immediately after `size`, `position`, `anchor`, and `no_prepend` elements (if present), the form size will use the new coordinate system. -* **Note**: Formspec prepends are not affected by the coordinates in the main form. - They must enable it explicitly. + * Formspec prepends are not affected by the coordinates in the main form. + They must enable it explicitly. * For information on converting forms to the new coordinate system, see `Migrating - to Real Coordinates`. + to Real Coordinates`. ### `container[,]` * Start of a container block, moves all physical elements in the container by - (X, Y). + `(X, Y)`. * Must have matching `container_end` -* Containers can be nested, in which case the offsets are added - (child containers are relative to parent containers) +* Containers can be nested, in which case the offsets are added (child containers are + relative to parent containers) ### `container_end[]` @@ -2742,22 +2686,22 @@ Elements ### `scroll_container[,;,;;;]` -* Start of a scroll_container block. All contained elements will ... - * take the scroll_container coordinate as position origin, - * be additionally moved by the current value of the scrollbar with the name +* Start of a scroll_container block. All contained elements will: + * Take the scroll_container coordinate as position origin, + * Be additionally moved by the current value of the scrollbar with the name `scrollbar name` times `scroll factor` along the orientation `orientation` and - * be clipped to the rectangle defined by `X`, `Y`, `W` and `H`. + * Be clipped to the rectangle defined by `X`, `Y`, `W` and `H`. * `orientation`: possible values are `vertical` and `horizontal`. * `scroll factor`: optional, defaults to `0.1`. * Nesting is possible. -* Some elements might work a little different if they are in a scroll_container. -* Note: If you want the scroll_container to actually work, you also need to add a +* Some elements might work a little different if they are in a `scroll_container`. +* Note: If you want the `scroll_container` to actually work, you also need to add a scrollbar element with the specified name. Furthermore, it is highly recommended - to use a scrollbaroptions element on this scrollbar. + to use a `scrollbaroptions` element on this scrollbar. ### `scroll_container_end[]` -* End of a scroll_container, following elements are no longer bound to this +* End of a `scroll_container`, following elements are no longer bound to this container. ### `list[;;,;,;]` @@ -2773,9 +2717,9 @@ Elements Indices start at `0`. Default is `0`. * The number of shown slots is the minimum of `W*H` and the inventory list's size minus `starting item index`. -* **Note**: With the new coordinate system, the spacing between inventory - slots is one-fourth the size of an inventory slot by default. Also see - [Styling Formspecs] for changing the size of slots and spacing. + > [!NOTE] With the new coordinate system, the spacing between inventory slots is 1/4 the + size of an inventory slot by default. Also see [Styling Formspecs] for changing the + size of slots and spacing. ### `listring[;]` @@ -2830,7 +2774,7 @@ Elements ### `animated_image[,;,;;;;;;]` -* Show an animated image. The image is drawn like a "vertical_frames" tile +* Show an animated image. The image is drawn like a `vertical_frames` tile animation (See [Tile animation definition]), but uses a frame count/duration for simplicity * `name`: Element name to send when an event occurs. The event value is the index of the current frame. * `texture name`: The image to use. @@ -2855,7 +2799,7 @@ Elements * `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. +* `animation speed` (Optional): Sets the animation speed. Default `0` FPS. ### `item_image[,;,;]` @@ -2867,7 +2811,7 @@ Elements * `bgcolor` and `fbgcolor` (optional) are `ColorString`s, they define the color of the non-fullscreen and the fullscreen background. * `fullscreen` (optional) can be one of the following: - * `false`: Only the non-fullscreen background color is drawn. (default) + * `false`: Default, only the non-fullscreen background color is drawn. * `true`: Only the fullscreen background color is drawn. * `both`: The non-fullscreen and the fullscreen background color are drawn. * `neither`: No background color is drawn. @@ -2878,12 +2822,12 @@ Elements ### `background[,;,;]` * Example for formspec 8x4 in 16x resolution: image shall be sized - 8 times 16px times 4 times 16px. + `(8 * 16px) * (4 * 16px)` ### `background[,;,;;]` -* Example for formspec 8x4 in 16x resolution: - image shall be sized 8 times 16px times 4 times 16px +* Example for formspec 8x4 in 16x resolution: image shall be sized + `(8 * 16px) * (4 * 16px)` * If `auto_clip` is `true`, the background is clipped to the formspec size (`x` and `y` are used as offset values, `w` and `h` are ignored) @@ -2891,11 +2835,11 @@ Elements * 9-sliced background. See https://en.wikipedia.org/wiki/9-slice_scaling * Middle is a rect which defines the middle of the 9-slice. - * `x` - The middle will be x pixels from all sides. - * `x,y` - The middle will be x pixels from the horizontal and y from the vertical. - * `x,y,x2,y2` - The middle will start at x,y, and end at x2, y2. Negative x2 and y2 values - will be added to the width and height of the texture, allowing it to be used as the - distance from the far end. + * `x` - The middle will be `x` pixels from all sides. + * `x,y` - The middle will be `x` pixels from the horizontal and `y` from the vertical. + * `x,y,x2,y2` - The middle will start at `(x, y)` and end at `(x2, y2)`. Negative `x2` + and `y2` values will be added to the width and height of the texture, allowing it to + be used as the distance from the far end. * All numbers in middle are integers. * If `auto_clip` is `true`, the background is clipped to the formspec size (`x` and `y` are used as offset values, `w` and `h` are ignored) @@ -2924,7 +2868,7 @@ Elements * `default` is the default value of the field * `default` may contain variable references such as `${text}` which will fill the value from the metadata value `text` - * **Note**: no extra text or more than a single variable is supported ATM. + > [!NOTE] No extra text or more than a single variable is supported at the moment. * See `field_close_on_enter` to stop enter closing the formspec ### `field[;