diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index d6cdd80a1..5e26921eb 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -4,8 +4,6 @@ Minetest Lua Modding API Reference
* Developer Wiki:
-
-
Introduction
============
@@ -34,14 +32,10 @@ the `init.lua` scripts in a shared environment.
Paths
-----
* `RUN_IN_PLACE=1` (Windows release, local build)
- * `$path_user`:
- * Linux: ``
- * Windows: ``
- * `$path_share`
- * Linux: ``
- * Windows: ``
+ * `$path_user`: ``
+ * `$path_share`: ``
* `RUN_IN_PLACE=0`: (Linux release)
- * `$path_share`
+ * `$path_share`:
* Linux: `/usr/share/minetest`
* Windows: `/minetest-0.4.x`
* `$path_user`:
@@ -79,7 +73,8 @@ 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.
@@ -129,7 +124,7 @@ This happens if the following directory exists:
$world/game/
-Mods should be then be placed in:
+Mods should then be placed in:
$world/game/mods/
@@ -143,20 +138,20 @@ Mod directory structure
-----------------------
mods
- |-- modname
- | |-- mod.conf
- | |-- screenshot.png
- | |-- settingtypes.txt
- | |-- init.lua
- | |-- models
- | |-- textures
- | | |-- modname_stuff.png
- | | `-- modname_something_else.png
- | |-- sounds
- | |-- media
- | |-- locale
- | `--
- `-- another
+ ├── modname
+ │ ├── mod.conf
+ │ ├── screenshot.png
+ │ ├── settingtypes.txt
+ │ ├── init.lua
+ │ ├── models
+ │ ├── textures
+ │ │ ├── modname_stuff.png
+ │ │ └── modname_something_else.png
+ │ ├── sounds
+ │ ├── media
+ │ ├── locale
+ │ └──
+ └── another
### modname
The location of this directory can be fetched by using
@@ -284,65 +279,64 @@ of the game's nodes are to be used by the core mapgens. For example:
### Aliases needed for all mapgens except Mapgen v6
-Base terrain:
+#### Base terrain
+* mapgen_stone
+* mapgen_water_source
+* mapgen_river_water_source
-"mapgen_stone"
-"mapgen_water_source"
-"mapgen_river_water_source"
-
-Caves:
-
-"mapgen_lava_source"
-
-Dungeons:
+#### Caves
+* mapgen_lava_source
+#### Dungeons
Only needed for registered biomes where 'node_stone' is stone:
-"mapgen_cobble"
-"mapgen_stair_cobble"
-"mapgen_mossycobble"
+
+* mapgen_cobble
+* mapgen_stair_cobble
+* mapgen_mossycobble
+
Only needed for registered biomes where 'node_stone' is desert stone:
-"mapgen_desert_stone"
-"mapgen_stair_desert_stone"
+
+* mapgen_desert_stone
+* mapgen_stair_desert_stone
+
Only needed for registered biomes where 'node_stone' is sandstone:
-"mapgen_sandstone"
-"mapgen_sandstonebrick"
-"mapgen_stair_sandstone_block"
+
+* mapgen_sandstone
+* mapgen_sandstonebrick
+* mapgen_stair_sandstone_block
### Aliases needed for Mapgen v6
-Terrain and biomes:
+#### Terrain and biomes
+* mapgen_stone
+* mapgen_water_source
+* mapgen_lava_source
+* mapgen_dirt
+* mapgen_dirt_with_grass
+* mapgen_sand
+* mapgen_gravel
+* mapgen_desert_stone
+* mapgen_desert_sand
+* mapgen_dirt_with_snow
+* mapgen_snowblock
+* mapgen_snow
+* mapgen_ice
-"mapgen_stone"
-"mapgen_water_source"
-"mapgen_lava_source"
-"mapgen_dirt"
-"mapgen_dirt_with_grass"
-"mapgen_sand"
-"mapgen_gravel"
-"mapgen_desert_stone"
-"mapgen_desert_sand"
-"mapgen_dirt_with_snow"
-"mapgen_snowblock"
-"mapgen_snow"
-"mapgen_ice"
+#### Flora
+* mapgen_tree
+* mapgen_leaves
+* mapgen_apple
+* mapgen_jungletree
+* mapgen_jungleleaves
+* mapgen_junglegrass
+* mapgen_pine_tree
+* mapgen_pine_needles
-Flora:
-
-"mapgen_tree"
-"mapgen_leaves"
-"mapgen_apple"
-"mapgen_jungletree"
-"mapgen_jungleleaves"
-"mapgen_junglegrass"
-"mapgen_pine_tree"
-"mapgen_pine_needles"
-
-Dungeons:
-
-"mapgen_cobble"
-"mapgen_stair_cobble"
-"mapgen_mossycobble"
-"mapgen_stair_desert_stone"
+#### Dungeons
+* mapgen_cobble
+* mapgen_stair_cobble
+* mapgen_mossycobble
+* mapgen_stair_desert_stone
@@ -404,6 +398,7 @@ on top of `cobble.png`.
* `[cracko:::
`
Parameters:
+
* `` = tile count (in each direction)
* `` = animation frame count
* `
` = current animation frame
@@ -537,7 +532,6 @@ The mask is applied using binary AND.
Retrieves a tile at position x,y from the base image
which it assumes to be a tilesheet with dimensions w,h.
-
#### `[colorize::`
Colorize the textures with the given color.
`` is specified as a `ColorString`.
@@ -573,12 +567,12 @@ the same texture, in different colors, each in a new node/item definition.
When you register an item or node, set its `color` field (which accepts a
`ColorSpec`) to the desired color.
-An `ItemStack`s static color can be overwritten by the `color` metadata
+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
Each tile may have an individual static color, which overwrites every
-other coloring methods. To disable the coloring of a face,
+other coloring method. To disable the coloring of a face,
set its color to white (because multiplying with white does nothing).
You can set the `color` property of the tiles in the node's definition
if the tile is in table format.
@@ -808,7 +802,8 @@ Examples of sound parameter tables:
Looped sounds must either be connected to an object or played locationless to
one player using `to_player = name,`
-### `SimpleSoundSpec`
+`SimpleSoundSpec`
+-----------------
* e.g. `""`
* e.g. `"default_place_node"`
* e.g. `{}`
@@ -819,10 +814,10 @@ one player using `to_player = name,`
-Registered definitions of stuff
-===============================
+Registered definitions
+======================
-Anything added using certain `minetest.register_*` functions get added to
+Anything added using certain `minetest.register_*` functions gets added to
the global `minetest.registered_*` tables.
* `minetest.register_entity(name, prototype table)`
@@ -919,11 +914,11 @@ 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
are quite static.
-The definition of a node is stored and can be accessed by name in
+The definition of a node is stored and can be accessed by using
minetest.registered_nodes[node.name]
-See "Registered definitions of stuff".
+See "Registered definitions".
Nodes are passed by value between Lua and the engine.
They are represented by a table:
@@ -1270,13 +1265,15 @@ Displays distance to selected world position.
Representations of simple things
================================
-### Position/vector
+Position/vector
+---------------
{x=num, y=num, z=num}
For helper functions see "Spatial Vectors".
-### `pointed_thing`
+`pointed_thing`
+---------------
* `{type="nothing"}`
* `{type="node", under=pos, above=pos}`
* `{type="object", ref=ObjectRef}`
@@ -1324,7 +1321,8 @@ since, by default, no schematic attributes are set.
Items
=====
-### Item types
+Item types
+----------
There are three kinds of items: nodes, tools and craftitems.
* Node (`register_node`): A node from the world.
@@ -1332,7 +1330,8 @@ There are three kinds of items: nodes, tools and craftitems.
things according to `tool_capabilities`.
* Craftitem (`register_craftitem`): A miscellaneous item.
-### Amount and wear
+Amount and wear
+---------------
All item stacks have an amount between 0 to 65535. It is 1 by
default. Tool item stacks can not have an amount greater than 1.
@@ -1341,11 +1340,12 @@ value 0 is the default and used is for unworn tools. The values
1 to 65535 are used for worn tools, where a higher value stands for
a higher wear. Non-tools always have a wear value of 0.
-### Item formats
+Item formats
+------------
Items and item stacks can exist in three formats: Serializes, table format
and `ItemStack`.
-#### Serialized
+### Serialized
This is called "stackstring" or "itemstring". It is a simple string with
1-3 components: the full item identifier, an optional amount and an optional
wear value. Syntax:
@@ -1359,7 +1359,7 @@ Examples:
* `'default:pick_stone'`: a new stone pickaxe
* `'default:pick_wood 1 21323'`: a wooden pickaxe, ca. 1/3 worn out
-#### Table format
+### Table format
Examples:
5 dirt nodes:
@@ -1374,7 +1374,7 @@ An apple:
{name="default:apple", count=1, wear=0, metadata=""}
-#### `ItemStack`
+### `ItemStack`
A native C++ format with many helper methods. Useful for converting
between formats. See the Class reference section for details.
@@ -1392,7 +1392,8 @@ properties of a thing (item, node, armor of entity, capabilities of
tool) in such a way that the engine and other mods can can interact with
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. For example:
@@ -1412,14 +1413,17 @@ 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 tools with this damage group.
See "Entity damage mechanism".
@@ -1427,11 +1431,13 @@ See "Entity damage mechanism".
object.get_armor_groups() --> a group-rating table (e.g. {fleshy=100})
object.set_armor_groups({fleshy=30, cracky=80})
-### Groups of tools
+Groups of tools
+---------------
Groups in tools define which groups of nodes and entities they are
effective towards.
-### Groups in crafting recipes
+Groups in crafting recipes
+--------------------------
An example: Make meat soup from any meat, any water and any bowl:
{
@@ -1452,7 +1458,8 @@ Another example: Make red wool from white wool and red dye:
recipe = {'wool:white', 'group:dye,basecolor_red'},
}
-### Special groups
+Special groups
+--------------
* `immortal`: Disables the group damage system for an entity
* `punch_operable`: For entities; disables the regular damage mechanism for
players punching it by hand or a non-tool item, so that it can do something
@@ -1480,7 +1487,8 @@ Another example: Make red wool from white wool and red dye:
Slipperiness rises steadily with `slippery` value, starting at 1.
-### Known damage and digging time defining groups
+Known damage and digging time defining groups
+---------------------------------------------
* `crumbly`: dirt, sand
* `cracky`: tough but crackable stuff like stone.
* `snappy`: something that can be cut using fine tools; e.g. leaves, small
@@ -1496,7 +1504,8 @@ Another example: Make red wool from white wool and red dye:
speed of a tool if the tool 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_.
* `meat`: any meat-kind of a thing (rating might define the size or healing
@@ -1510,7 +1519,8 @@ 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
faster digging time.
@@ -1531,7 +1541,8 @@ groups to enable interaction with tools.
Tools
=====
-#### Tools definition
+Tools definition
+----------------
Tools define:
* Full punch interval
@@ -1542,19 +1553,22 @@ Tools define:
* Digging times
* Damage groups
-#### Full punch interval
+### Full punch interval
+
When used as a weapon, the tool will do full damage if this time is spent
between punches. If e.g. half the time is spent, the tool will do half
damage.
-#### Maximum drop level
+### Maximum drop level
+
Suggests the maximum level of node, when dug with the tool, that will drop
it's useful item. (e.g. iron ore to drop a lump of iron).
This is not automated; it is the responsibility of the node definition
to implement this.
-#### Uses
+### Uses
+
Determines how many uses the tool has when it is used for digging a node,
of this group, of the maximum level. For lower leveled nodes, the use count
is multiplied by `3^leveldiff`.
@@ -1563,11 +1577,13 @@ is multiplied by `3^leveldiff`.
* `uses=10, leveldiff=1`: actual uses: 30
* `uses=10, leveldiff=2`: actual uses: 90
-#### Maximum level
+### Maximum level
+
Tells what is the maximum level of a node of this group that the tool will
be able to dig.
-#### Digging times
+### Digging times
+
List of digging times for different ratings of the group, for nodes of the
maximum level.
@@ -1580,10 +1596,12 @@ 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".
-#### Example definition of the capabilities of a tool
+Example definition of the capabilities of a tool
+------------------------------------------------
tool_capabilities = {
full_punch_interval=1.5,
@@ -1763,15 +1781,16 @@ 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. See `no_prepend[]`
-### Examples
+Examples
+--------
-#### Chest
+### Chest
size[8,9]
list[context;main;0,0;8,4;]
list[current_player;main;0,5;8,4;]
-#### Furnace
+### Furnace
size[8,9]
list[context;fuel;2,3;1,1;]
@@ -1779,7 +1798,7 @@ appearing when you don't expect them to. See `no_prepend[]`
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]
@@ -1787,14 +1806,15 @@ appearing when you don't expect them to. See `no_prepend[]`
list[current_player;craft;3,0;3,3;]
list[current_player;craftpreview;7,1;1,1;]
-### Elements
+Elements
+--------
-#### `size[,,]`
+### `size[,,]`
* Define the size of the menu in inventory slots
* `fixed_size`: `true`/`false` (optional)
* deprecated: `invsize[,;]`
-#### `position[,]`
+### `position[,]`
* 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,
@@ -1803,7 +1823,7 @@ appearing when you don't expect them to. See `no_prepend[]`
* [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].
-#### `anchor[,]`
+### `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,
@@ -1815,79 +1835,79 @@ appearing when you don't expect them to. See `no_prepend[]`
* `position` and `anchor` elements need suitable values to avoid a formspec
extending off the game window due to particular game window sizes.
-#### `no_prepend[]`
+### `no_prepend[]`
* Must be used after the `size`, `position`, and `anchor` elements (if present).
* Disables player:set_formspec_prepend() from applying to this formspec.
-#### `container[,]`
+### `container[,]`
* Start of a container block, moves all physical elements in the container by
(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)
-#### `container_end[]`
+### `container_end[]`
* End of a container, following elements are no longer relative to this
container.
-#### `list[;;,;,;]`
+### `list[;;,;,;]`
* Show an inventory list
-#### `list[;;,;,;]`
+### `list[;;,;,;]`
* Show an inventory list
-#### `listring[;]`
+### `listring[;]`
* Allows to create a ring of inventory lists
* Shift-clicking on items in one element of the ring
will send them to the next inventory list inside the ring
* The first occurrence of an element inside the ring will
determine the inventory where items will be sent to
-#### `listring[]`
+### `listring[]`
* Shorthand for doing `listring[;]`
for the last two inventory lists added by list[...]
-#### `listcolors[;]`
+### `listcolors[;]`
* Sets background color of slots as `ColorString`
* Sets background color of slots on mouse hovering
-#### `listcolors[;;]`
+### `listcolors[;;]`
* Sets background color of slots as `ColorString`
* Sets background color of slots on mouse hovering
* Sets color of slots border
-#### `listcolors[;;;;]`
+### `listcolors[;;;;]`
* Sets background color of slots as `ColorString`
* Sets background color of slots on mouse hovering
* Sets color of slots border
* Sets default background color of tooltips
* Sets default font color of tooltips
-#### `tooltip[;;;]`
+### `tooltip[;;;]`
* Adds tooltip for an element
* `` tooltip background color as `ColorString` (optional)
* `` tooltip font color as `ColorString` (optional)
-#### `image[,;,;]`
+### `image[,;,;]`
* Show an image
* Position and size units are inventory slots
-#### `item_image[,;,;]`
+### `item_image[,;,;]`
* Show an inventory image of registered item/node
* Position and size units are inventory slots
-#### `bgcolor[;]`
+### `bgcolor[;]`
* Sets background color of formspec as `ColorString`
* If `true`, the background color is drawn fullscreen (does not effect the size
of the formspec).
-#### `background[,;,;]`
+### `background[,;,;]`
* Use a background. Inventory rectangles are not drawn then.
* Position and size units are inventory slots
* Example for formspec 8x4 in 16x resolution: image shall be sized
8 times 16px times 4 times 16px.
-#### `background[,;,;;]`
+### `background[,;,;;]`
* Use a background. Inventory rectangles are not drawn then.
* Position and size units are inventory slots
* Example for formspec 8x4 in 16x resolution:
@@ -1895,7 +1915,7 @@ appearing when you don't expect them to. See `no_prepend[]`
* If `true` the background is clipped to formspec size
(`x` and `y` are used as offset values, `w` and `h` are ignored)
-#### `pwdfield[,;,;;