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[;