Merge 0.4.15 changes into stable-0.4

0.4.15 release!

6 files changed, 554 insertions, 647 deletions

diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 593e0c438..34c64b8df 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -1,4 +1,4 @@
-Minetest Lua Modding API Reference 0.4.14
+Minetest Lua Modding API Reference 0.4.15
 =========================================
 * More information at <http://www.minetest.net/>
 * Developer Wiki: <http://dev.minetest.net/>
@@ -65,15 +65,19 @@ e.g.
 The game directory can contain the file minetest.conf, which will be used
 to set default settings when running the particular game.
 It can also contain a settingtypes.txt in the same format as the one in builtin.
-This settingtypes.txt will be parsed by the menu and the settings will be displayed in the "Games" category in the settings tab.
+This settingtypes.txt will be parsed by the menu and the settings will be displayed
+in the "Games" category in the settings tab.
 
 ### Menu images
 
-Games can provide custom main menu images. They are put inside a `menu` directory inside the game directory.
+Games can provide custom main menu images. They are put inside a `menu` directory
+inside the game directory.
 
-The images are named `$identifier.png`, where `$identifier` is one of `overlay,background,footer,header`.
-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.
+The images are named `$identifier.png`, where `$identifier` is
+one of `overlay,background,footer,header`.
+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.
 
 
 Mod load path
@@ -153,7 +157,8 @@ to a single modname. Their meaning is that if the specified mod
 is missing, that does not prevent this mod from being loaded.
 
 ### `screenshot.png`
-A screenshot shown in modmanager within mainmenu.
+A screenshot shown in the mod manager within the main menu. It should
+have an aspect ratio of 3:2 and a minimum size of 300×200 pixels.
 
 ### `description.txt`
 A File containing description to be shown within mainmenu.
@@ -203,11 +208,17 @@ when registering it.
 The `:` prefix can also be used for maintaining backwards compatibility.
 
 ### Aliases
-Aliases can be added by using `minetest.register_alias(name, convert_to)`.
+Aliases can be added by using `minetest.register_alias(name, convert_to)` or
+`minetest.register_alias_force(name, convert_to).
 
 This will make Minetest to convert things called name to things called
 `convert_to`.
 
+The only difference between `minetest.register_alias` and
+`minetest.register_alias_force` is that if an item called `name` exists,
+`minetest.register_alias` will do nothing while
+`minetest.register_alias_force` will unregister it.
+
 This can be used for maintaining backwards compatibility.
 
 This can be also used for setting quick access names for things, e.g. if
@@ -243,7 +254,8 @@ Example:
     default_dirt.png^default_grass_side.png
 
 `default_grass_side.png` is overlayed over `default_dirt.png`.
-The texture with the lower resolution will be automatically upscaled to the higher resolution texture.
+The texture with the lower resolution will be automatically upscaled to
+the higher resolution texture.
 
 ### Texture grouping
 Textures can be grouped together by enclosing them in `(` and `)`.
@@ -251,7 +263,17 @@ Textures can be grouped together by enclosing them in `(` and `)`.
 Example: `cobble.png^(thing1.png^thing2.png)`
 
 A texture for `thing1.png^thing2.png` is created and the resulting
-texture is overlaid over `cobble.png`.
+texture is overlaid on top of `cobble.png`.
+
+### Escaping
+Modifiers that accept texture names (e.g. `[combine`) accept escaping to allow
+passing complex texture names as arguments. Escaping is done with backslash and
+is required for `^` and `:`.
+
+Example: `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
 
@@ -286,6 +308,25 @@ Example:
 
     default_sandstone.png^[resize:16x16
 
+#### `[opacity:<r>`
+    Makes the base image transparent according to the given ratio.
+    r must be between 0 and 255.
+    0 means totally transparent.
+    255 means totally opaque.
+
+Example:
+
+    default_sandstone.png^[opacity:127
+
+#### `[invert:<mode>`
+Inverts the given channels of the base image.
+Mode may contain the characters "r", "g", "b", "a".
+Only the channels that are mentioned in the mode string will be inverted.
+
+Example:
+
+	default_apple.png^[invert:rgb
+
 #### `[brighten`
 Brightens the texture.
 
@@ -329,7 +370,7 @@ Example:
     default_stone.png^[transformFXR90
 
 #### `[inventorycube{<top>{<left>{<right>`
-`^` is replaced by `&` in texture names.
+Escaping does not apply here and `^` is replaced by `&` in texture names instead.
 
 Create an inventory cube texture using the side textures.
 
@@ -400,18 +441,24 @@ from the available ones of the following files:
 
 Examples of sound parameter tables:
 
-    -- Play location-less on all clients
+    -- Play locationless on all clients
     {
         gain = 1.0, -- default
     }
-    -- Play location-less to a player
+    -- Play locationless to one player
+    {
+        to_player = name,
+        gain = 1.0, -- default
+    }
+    -- Play locationless to one player, looped
     {
         to_player = name,
         gain = 1.0, -- default
+        loop = true,
     }
     -- Play in a location
     {
-        pos = {x=1,y=2,z=3},
+        pos = {x = 1, y = 2, z = 3},
         gain = 1.0, -- default
         max_hear_distance = 32, -- default, uses an euclidean metric
     }
@@ -420,15 +467,18 @@ Examples of sound parameter tables:
         object = <an ObjectRef>,
         gain = 1.0, -- default
         max_hear_distance = 32, -- default, uses an euclidean metric
-        loop = true, -- only sounds connected to objects can be looped
+        loop = true,
     }
 
+Looped sounds must either be connected to an object or played locationless to
+one player using `to_player = name,`
+
 ### `SimpleSoundSpec`
 * e.g. `""`
 * e.g. `"default_place_node"`
 * e.g. `{}`
-* e.g. `{name="default_place_node"}`
-* e.g. `{name="default_place_node", gain=1.0}`
+* e.g. `{name = "default_place_node"}`
+* e.g. `{name = "default_place_node", gain = 1.0}`
 
 Registered definitions of stuff
 -------------------------------
@@ -448,6 +498,11 @@ the global `minetest.registered_*` tables.
 * `minetest.register_craftitem(name, item definition)`
     * added to `minetest.registered_items[name]`
 
+* `minetest.unregister_item(name)`
+    * Unregisters the item name from engine, and deletes the entry with key
+    * `name` from `minetest.registered_items` and from the associated item
+    * table according to its nature: minetest.registered_nodes[] etc
+
 * `minetest.register_biome(biome definition)`
     * returns an integer uniquely identifying the registered biome
     * added to `minetest.registered_biome` with the key of `biome.name`
@@ -468,8 +523,8 @@ the global `minetest.registered_*` tables.
     * added to `minetest.registered_schematic` with the key of `schematic.name`
     * if `schematic.name` is nil, the key is the returned ID
     * if the schematic is loaded from a file, schematic.name is set to the filename
-    * if the function is called when loading the mod, and schematic.name is a relative path,
-    * then the current mod path will be prepended to the schematic filename
+    * if the function is called when loading the mod, and schematic.name is a relative
+      path, then the current mod path will be prepended to the schematic filename
 
 * `minetest.clear_registered_biomes()`
     * clears all biomes currently registered
@@ -562,6 +617,22 @@ node definition:
     ^ The rotation of this node is stored in param2. Plants are rotated this way.
       Values range 0 - 179. The value stored in param2 is multiplied by two to
       get the actual rotation of the node.
+    paramtype2 == "meshoptions"
+    ^ Only valid for "plantlike". The value of param2 becomes a bitfield which can
+      be used to change how the client draws plantlike nodes. Bits 0, 1 and 2 form
+      a mesh selector. Currently the following meshes are choosable:
+        0 = a "x" shaped plant (ordinary plant)
+        1 = a "+" shaped plant (just rotated 45 degrees)
+        2 = a "*" shaped plant with 3 faces instead of 2
+        3 = a "#" shaped plant with 4 faces instead of 2
+        4 = a "#" shaped plant with 4 faces that lean outwards
+        5-7 are unused and reserved for future meshes.
+      Bits 3 through 7 are optional flags that can be combined and give these
+      effects:
+        bit 3 (0x08) - Makes the plant slightly vary placement horizontally
+        bit 4 (0x10) - Makes the plant mesh 1.4x larger
+        bit 5 (0x20) - Moves each face randomly a small bit down (1/8 max)
+        bits 6-7 are reserved for future use.
     collision_box = {
       type = "fixed",
       fixed = {
@@ -1407,6 +1478,15 @@ examples.
 * `fixed_size`: `true`/`false` (optional)
 * deprecated: `invsize[<W>,<H>;]`
 
+#### `container[<X>,<Y>]`
+* 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[]`
+* End of a container, following elements are no longer relative to this container
+
 #### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]`
 * Show an inventory list
 
@@ -1416,13 +1496,13 @@ examples.
 #### `listring[<inventory location>;<list name>]`
 * 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
+  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
+  determine the inventory where items will be sent to
 
 #### `listring[]`
 * Shorthand for doing `listring[<inventory location>;<list name>]`
-* for the last two inventory lists added by list[...]
+  for the last two inventory lists added by list[...]
 
 #### `listcolors[<slot_bg_normal>;<slot_bg_hover>]`
 * Sets background color of slots as `ColorString`
@@ -1473,18 +1553,23 @@ examples.
 
 #### `pwdfield[<X>,<Y>;<W>,<H>;<name>;<label>]`
 * Textual password style field; will be sent to server when a button is clicked
+* When enter is pressed in field, fields.key_enter_field will be sent with the name
+  of this field.
 * `x` and `y` position the field relative to the top left of the menu
 * `w` and `h` are the size of the field
-* fields are a set height, but will be vertically centred on `h`
+* Fields are a set height, but will be vertically centred on `h`
 * Position and size units are inventory slots
 * `name` is the name of the field as returned in fields to `on_receive_fields`
 * `label`, if not blank, will be text printed on the top left above the field
+* See field_close_on_enter to stop enter closing the formspec
 
 #### `field[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`
 * Textual field; will be sent to server when a button is clicked
+* When enter is pressed in field, fields.key_enter_field will be sent with the name
+  of this field.
 * `x` and `y` position the field relative to the top left of the menu
 * `w` and `h` are the size of the field
-* fields are a set height, but will be vertically centred on `h`
+* Fields are a set height, but will be vertically centred on `h`
 * Position and size units are inventory slots
 * `name` is the name of the field as returned in fields to `on_receive_fields`
 * `label`, if not blank, will be text printed on the top left above the field
@@ -1492,15 +1577,24 @@ examples.
     * `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.
+* See field_close_on_enter to stop enter closing the formspec
 
 #### `field[<name>;<label>;<default>]`
-* as above, but without position/size units
-* special field for creating simple forms, such as sign text input
-* must be used without a `size[]` element
-* a "Proceed" button will be added automatically
+* As above, but without position/size units
+* When enter is pressed in field, fields.key_enter_field will be sent with the name
+  of this field.
+* Special field for creating simple forms, such as sign text input
+* Must be used without a `size[]` element
+* A "Proceed" button will be added automatically
+* See field_close_on_enter to stop enter closing the formspec
+
+#### `field_close_on_enter[<name>;<close_on_enter>]`
+* <name> is the name of the field
+* if <close_on_enter> is false, pressing enter in the field will submit the form but not close it
+* defaults to true when not specified (ie: no tag for a field)
 
 #### `textarea[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`
-* same as fields above, but with multi-line input
+* Same as fields above, but with multi-line input
 
 #### `label[<X>,<Y>;<label>]`
 * `x` and `y` work as per field
@@ -1561,12 +1655,12 @@ examples.
 * `name` fieldname sent to server on doubleclick value is current selected element
 * `listelements` can be prepended by #RRGGBB (only) in hexadecimal format
      * if you want a listelement to start with "#" write "##"
-* index to be selected within textlist
+* Index to be selected within textlist
 * `true`/`false`: draw transparent background
-* see also `minetest.explode_textlist_event` (main menu: `engine.explode_textlist_event`)
+* See also `minetest.explode_textlist_event` (main menu: `engine.explode_textlist_event`)
 
 #### `tabheader[<X>,<Y>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]`
-* show a tab**header** at specific position (ignores formsize)
+* Show a tab**header** at specific position (ignores formsize)
 * `x` and `y` position the itemlist relative to the top left of the menu
 * `name` fieldname data is transferred to Lua
 * `caption 1`...: name shown on top of tab
@@ -1575,54 +1669,53 @@ examples.
 * `draw_border` (optional): draw border
 
 #### `box[<X>,<Y>;<W>,<H>;<color>]`
-* simple colored semitransparent box
+* Simple colored semitransparent box
 * `x` and `y` position the box relative to the top left of the menu
 * `w` and `h` are the size of box
 * `color` is color specified as a `ColorString`
 
 #### `dropdown[<X>,<Y>;<W>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>]`
-* show a dropdown field
+* Show a dropdown field
 * **Important note**: There are two different operation modes:
      1. handle directly on change (only changed dropdown is submitted)
      2. read the value on pressing a button (all dropdown values are available)
 * `x` and `y` position of dropdown
-* width of dropdown
-* fieldname data is transferred to Lua
-* items to be shown in dropdown
-* index of currently selected dropdown item
+* Width of dropdown
+* Fieldname data is transferred to Lua
+* Items to be shown in dropdown
+* Index of currently selected dropdown item
 
-#### `checkbox[<X>,<Y>;<name>;<label>;<selected>;<tooltip>]`
-* show a checkbox
+#### `checkbox[<X>,<Y>;<name>;<label>;<selected>]`
+* Show a checkbox
 * `x` and `y`: position of checkbox
 * `name` fieldname data is transferred to Lua
 * `label` to be shown left of checkbox
 * `selected` (optional): `true`/`false`
-* `tooltip` (optional)
 
 #### `scrollbar[<X>,<Y>;<W>,<H>;<orientation>;<name>;<value>]`
-* show a scrollbar
-* there are two ways to use it:
+* Show a scrollbar
+* There are two ways to use it:
      1. handle the changed event (only changed scrollbar is available)
      2. read the value on pressing a button (all scrollbars are available)
 * `x` and `y`: position of trackbar
 * `w` and `h`: width and height
 * `orientation`:  `vertical`/`horizontal`
-* fieldname data is transferred to Lua
-* value this trackbar is set to (`0`-`1000`)
-* see also `minetest.explode_scrollbar_event` (main menu: `engine.explode_scrollbar_event`)
+* Fieldname data is transferred to Lua
+* Value this trackbar is set to (`0`-`1000`)
+* See also `minetest.explode_scrollbar_event` (main menu: `engine.explode_scrollbar_event`)
 
 #### `table[<X>,<Y>;<W>,<H>;<name>;<cell 1>,<cell 2>,...,<cell n>;<selected idx>]`
-* show scrollable table using options defined by the previous `tableoptions[]`
-* displays cells as defined by the previous `tablecolumns[]`
+* Show scrollable table using options defined by the previous `tableoptions[]`
+* Displays cells as defined by the previous `tablecolumns[]`
 * `x` and `y`: position the itemlist relative to the top left of the menu
 * `w` and `h` are the size of the itemlist
 * `name`: fieldname sent to server on row select or doubleclick
 * `cell 1`...`cell n`: cell contents given in row-major order
 * `selected idx`: index of row to be selected within table (first row = `1`)
-* see also `minetest.explode_table_event` (main menu: `engine.explode_table_event`)
+* See also `minetest.explode_table_event` (main menu: `engine.explode_table_event`)
 
 #### `tableoptions[<opt 1>;<opt 2>;...]`
-* sets options for `table[]`
+* Sets options for `table[]`
 * `color=#RRGGBB`
      * default text color (`ColorString`), defaults to `#FFFFFF`
 * `background=#RRGGBB`
@@ -1638,14 +1731,14 @@ examples.
      * only useful when there is a column of type "tree"
 
 #### `tablecolumns[<type 1>,<opt 1a>,<opt 1b>,...;<type 2>,<opt 2a>,<opt 2b>;...]`
-* sets columns for `table[]`
-* types: `text`, `image`, `color`, `indent`, `tree`
+* Sets columns for `table[]`
+* Types: `text`, `image`, `color`, `indent`, `tree`
     * `text`:   show cell contents as text
     * `image`:  cell contents are an image index, use column options to define images
     * `color`:   cell contents are a ColorString and define color of following cell
     * `indent`: cell contents are a number and define indentation of following cell
     * `tree`:   same as indent, but user can open and close subtrees (treeview-like)
-* column options:
+* Column options:
     * `align=<value>`
         * for `text` and `image`: content alignment within cells.
           Available values: `left` (default), `center`, `right`, `inline`
@@ -1675,6 +1768,13 @@ Inventory locations
 * `"nodemeta:<X>,<Y>,<Z>"`: Any node metadata
 * `"detached:<name>"`: A detached inventory
 
+Player Inventory lists
+----------------------
+* `main`: list containing the default inventory
+* `craft`: list containing the craft input
+* `craftpreview`: list containing the craft output
+* `hand`: list containing an override for the empty hand
+
 `ColorString`
 -------------
 `#RGB` defines a color in hexadecimal format.
@@ -1701,6 +1801,24 @@ numerical form, the raw integer value of an ARGB8 quad:
 or string form, a ColorString (defined above):
     `colorspec = "green"`
 
+Escape sequences
+----------------
+Most text can contain escape sequences, that can for example color the text.
+There are a few exceptions: tab headers, dropdowns and vertical labels can't.
+The following functions provide escape sequences:
+* `core.get_color_escape_sequence(color)`:
+    * `color` is a ColorString
+    * The escape sequence sets the text color to `color`
+* `core.colorize(color, message)`:
+    * Equivalent to:
+      `core.get_color_escape_sequence(color) ..
+       message ..
+       core.get_color_escape_sequence("#ffffff")`
+* `color.get_background_escape_sequence(color)`
+    * `color` is a ColorString
+    * The escape sequence sets the background of the whole text element to
+      `color`. Only defined for item descriptions and tooltips.
+
 Spatial Vectors
 ---------------
 * `vector.new(a[, b, c])`: returns a vector:
@@ -1710,7 +1828,8 @@ Spatial Vectors
 * `vector.distance(p1, p2)`: returns a number
 * `vector.length(v)`: returns a number
 * `vector.normalize(v)`: returns a vector
-* `vector.round(v)`: returns a vector, each dimension rounded to floor
+* `vector.floor(v)`: returns a vector, each dimension rounded down
+* `vector.round(v)`: returns a vector, each dimension rounded to nearest int
 * `vector.apply(v, func)`: returns a vector
 * `vector.equals(v1, v2)`: returns a boolean
 
@@ -1805,6 +1924,17 @@ Helper functions
       * nil: return all entries,
       * true: return only subdirectory names, or
       * false: return only file names.
+* `minetest.get_version()`: returns a table containing components of the
+   engine version.  Components:
+    * `project`: Name of the project, eg, "Minetest"
+    * `string`: Simple version, eg, "1.2.3-dev"
+    * `hash`: Full git version (only set if available), eg, "1.2.3-dev-01234567-dirty"
+  Use this for informational purposes only. The information in the returned
+  table does not represent the capabilities of the engine, nor is it
+  reliable or verifyable. Compatible forks will have a different name and
+  version entirely. To check for the presence of engine features, test
+  whether the functions exported by the wanted features exist. For example:
+  `if core.nodeupdate then ... end`.
 
 ### Logging
 * `minetest.debug(...)`
@@ -1822,16 +1952,27 @@ Call these functions only at load time!
 * `minetest.register_node(name, node definition)`
 * `minetest.register_tool(name, item definition)`
 * `minetest.register_craftitem(name, item definition)`
+* `minetest.unregister_item(name)`
 * `minetest.register_alias(name, convert_to)`
+* `minetest.register_alias_force(name, convert_to)`
 * `minetest.register_craft(recipe)`
+    * Check recipe table syntax for different types below.
+* `minetest.clear_craft(recipe)`
+    * Will erase existing craft based either on output item or on input recipe.
+    * Specify either output or input only. If you specify both, input will be ignored. For input use the same recipe table
+      syntax as for `minetest.register_craft(recipe)`. For output specify only the item, without a quantity.
+    * If no erase candidate could be found, Lua exception will be thrown.
+    * Warning! The type field ("shaped","cooking" or any other) will be ignored if the recipe
+      contains output. Erasing is then done independently from the crafting method.
 * `minetest.register_ore(ore definition)`
+* `minetest.register_biome(biome definition)`
 * `minetest.register_decoration(decoration definition)`
 * `minetest.override_item(name, redefinition)`
     * Overrides fields of an item registered with register_node/tool/craftitem.
     * Note: Item must already be defined, (opt)depend on the mod defining it.
     * Example: `minetest.override_item("default:mese", {light_source=LIGHT_MAX})`
-
 * `minetest.clear_registered_ores()`
+* `minetest.clear_registered_biomes()`
 * `minetest.clear_registered_decorations()`
 
 ### Global callback registration functions
@@ -1889,8 +2030,9 @@ Call these functions only at load time!
      * If it returns a string, the player is disconnected with that string as reason
 * `minetest.register_on_joinplayer(func(ObjectRef))`
     * Called when a player joins the game
-* `minetest.register_on_leaveplayer(func(ObjectRef))`
+* `minetest.register_on_leaveplayer(func(ObjectRef, timed_out))`
     * Called when a player leaves the game
+    * `timed_out`: True for timeout, false for other reasons.
 * `minetest.register_on_cheat(func(ObjectRef, cheat))`
     * Called when a player cheats
     * `cheat`: `{type=<cheat_type>}`, where `<cheat_type>` is one of:
@@ -1930,7 +2072,8 @@ Call these functions only at load time!
 * `minetest.register_chatcommand(cmd, chatcommand definition)`
 * `minetest.register_privilege(name, definition)`
     * `definition`: `"description text"`
-    * `definition`: `{ description = "description text", give_to_singleplayer = boolean, -- default: true }`
+    * `definition`: `{ description = "description text", give_to_singleplayer = boolean}`
+      the default of `give_to_singleplayer` is true
     * To allow players with basic_privs to grant, see basic_privs minetest.conf setting.
 * `minetest.register_authentication_handler(handler)`
     * See `minetest.builtin_auth_handler` in `builtin.lua` for reference
@@ -1951,12 +2094,21 @@ Call these functions only at load time!
 * `minetest.notify_authentication_modified(name)`
     * Should be called by the authentication handler if privileges changes.
     * To report everybody, set `name=nil`.
+* `minetest.check_password_entry(name, entry, password)`
+    * Returns true if the "db entry" for a player with name matches given
+    * password, false otherwise.
+    * The "db entry" is the usually player-individual value that is derived
+    * from the player's chosen password and stored on the server in order to allow
+    * authentication whenever the player desires to log in.
+    * Only use this function for making it possible to log in via the password from
+    * via protocols like IRC, other uses for inside the game are frowned upon.
 * `minetest.get_password_hash(name, raw_password)`
     * Convert a name-password pair to a password hash that Minetest can use.
     * The returned value alone is not a good basis for password checks based
     * on comparing the password hash in the database with the password hash
     * from the function, with an externally provided password, as the hash
     * in the db might use the new SRP verifier format.
+    * For this purpose, use minetest.check_password_entry instead.
 * `minetest.string_to_privs(str)`: returns `{priv1=true,...}`
 * `minetest.privs_to_string(privs)`: returns `"priv1,priv2,..."`
     * Convert between two privilege representations
@@ -1982,7 +2134,7 @@ and `minetest.auth_reload` call the authetification handler.
 * `minetest.set_node(pos, node)`
 * `minetest.add_node(pos, node): alias set_node(pos, node)`
     * Set node at position (`node = {name="foo", param1=0, param2=0}`)
-* `minetest.swap_node(pos, node`
+* `minetest.swap_node(pos, node)`
     * Set node at position, but don't remove metadata
 * `minetest.remove_node(pos)`
     * Equivalent to `set_node(pos, "air")`
@@ -2055,7 +2207,9 @@ and `minetest.auth_reload` call the authetification handler.
       given biome_name string.
 * `minetest.get_mapgen_params()` Returns mapgen parameters, a table containing
   `mgname`, `seed`, `chunksize`, `water_level`, and `flags`.
+  * Deprecated: use minetest.get_mapgen_setting(name) instead
 * `minetest.set_mapgen_params(MapgenParams)`
+    * Deprecated: use minetest.set_mapgen_setting(name, value, override) instead
     * Set map generation parameters
     * Function cannot be called after the registration period; only initialization
       and `on_mapgen_init`
@@ -2065,6 +2219,24 @@ and `minetest.auth_reload` call the authetification handler.
         * `flags` contains a comma-delimited string of flags to set,
           or if the prefix `"no"` is attached, clears instead.
         * `flags` is in the same format and has the same options as `mg_flags` in `minetest.conf`
+* `minetest.get_mapgen_setting(name)`
+    * Gets the *active* mapgen setting (or nil if none exists) in string format with the following
+      order of precedence:
+        1) Settings loaded from map_meta.txt or overrides set during mod execution
+        2) Settings set by mods without a metafile override
+        3) Settings explicitly set in the user config file, minetest.conf
+        4) Settings set as the user config default
+* `minetest.get_mapgen_setting_noiseparams(name)`
+    * Same as above, but returns the value as a NoiseParams table if the setting `name` exists
+      and is a valid NoiseParams
+* `minetest.set_mapgen_setting(name, value, [override_meta])`
+   * Sets a mapgen param to `value`, and will take effect if the corresponding mapgen setting
+     is not already present in map_meta.txt.
+   * `override_meta` is an optional boolean (default: `false`). If this is set to true,
+     the setting will become the active setting regardless of the map metafile contents.
+   * Note: to set the seed, use "seed", not "fixed_map_seed"
+* `minetest.set_mapgen_setting_noiseparams(name, value, [override_meta])`
+   * Same as above, except value is a NoiseParams table.
 * `minetest.set_noiseparams(name, noiseparams, set_default)`
     * Sets the noiseparams setting of `name` to the noiseparams table specified in `noiseparams`.
     * `set_default` is an optional boolean (default: `true`) that specifies whether the setting
@@ -2130,6 +2302,15 @@ and `minetest.auth_reload` call the authetification handler.
     * increase level of leveled node by level, default `level` equals `1`
     * if `totallevel > maxlevel`, returns rest (`total-max`)
     * can be negative for decreasing
+* `core.check_single_for_falling(pos)`
+    * causes an unsupported `group:falling_node` node to fall and causes an
+      unattached `group:attached_node` node to fall.
+    * does not spread these updates to neighbours.
+* `core.check_for_falling(pos)`
+    * causes an unsupported `group:falling_node` node to fall and causes an
+      unattached `group:attached_node` node to fall.
+    * spread these updates to neighbours and can cause a cascade
+      of nodes to fall.
 
 ### Inventory
 `minetest.get_inventory(location)`: returns an `InvRef`
@@ -2138,8 +2319,11 @@ and `minetest.auth_reload` call the authetification handler.
     * `{type="player", name="celeron55"}`
     * `{type="node", pos={x=, y=, z=}}`
     * `{type="detached", name="creative"}`
-* `minetest.create_detached_inventory(name, callbacks)`: returns an `InvRef`
+* `minetest.create_detached_inventory(name, callbacks, [player_name])`: returns an `InvRef`
     * callbacks: See "Detached inventory callbacks"
+    * player_name: Make detached inventory available to one player exclusively,
+      by default they will be sent to every player (even if not used).
+      Note that this parameter is mostly just a workaround and will be removed in future releases.
     * Creates a detached inventory. If it already exists, it is cleared.
 * `minetest.do_item_eat(hp_change, replace_with_item, itemstack, user, pointed_thing)`:
    returns left over ItemStack
@@ -2151,6 +2335,13 @@ and `minetest.auth_reload` call the authetification handler.
     * `formname`: name passed to `on_player_receive_fields` callbacks.
       It should follow the `"modname:<whatever>"` naming convention
     * `formspec`: formspec to display
+* `minetest.close_formspec(playername, formname)`
+    * `playername`: name of player to close formspec
+    * `formname`: has to exactly match the one given in show_formspec, or the formspec will
+       not close.
+    * calling show_formspec(playername, formname, "") is equal to this expression
+    * to close a formspec regardless of the formname, call
+      minetest.close_formspec(playername, ""). USE THIS ONLY WHEN ABSOLUTELY NECESSARY!
 * `minetest.formspec_escape(string)`: returns a string
     * escapes the characters "[", "]", "\", "," and ";", which can not be used in formspecs
 * `minetest.explode_table_event(string)`: returns a table
@@ -2287,6 +2478,7 @@ These functions return the leftover itemstack.
 * `minetest.request_shutdown([message],[reconnect])`: request for server shutdown. Will display `message` to clients,
     and `reconnect` == true displays a reconnect button.
 * `minetest.get_server_status()`: returns server status string
+* `minetest.get_server_uptime()`: returns the server uptime in seconds
 
 ### Bans
 * `minetest.get_ban_list()`: returns the ban list (same as `minetest.get_ban_description("")`)
@@ -2378,12 +2570,16 @@ These functions return the leftover itemstack.
     * callback: `function(HTTPRequestResult res)`
     * Use this HTTP function if you are unsure, the others are for advanced use.
 * `HTTPApiTable.fetch_async(HTTPRequest req)`: returns handle
-    * Performs given request asynchronously and returns handle for `minetest.http_fetch_async_get`
+    * Performs given request asynchronously and returns handle for `HTTPApiTable.fetch_async_get`
 * `HTTPApiTable.fetch_async_get(handle)`: returns HTTPRequestResult
     * Return response data for given asynchronous HTTP request
 
 ### Misc.
 * `minetest.get_connected_players()`: returns list of `ObjectRefs`
+* `minetest.hud_replace_builtin(name, hud_definition)`
+    * Replaces definition of a builtin hud element
+    * `name`: `"breath"` or `"health"`
+    * `hud_definition`: definition to replace builtin definition
 * `minetest.hash_node_position({x=,y=,z=})`: returns an 48-bit integer
     * Gives a unique hash number for a node position (16+16+16=48bit)
 * `minetest.get_position_from_hash(hash)`: returns a position
@@ -2438,6 +2634,10 @@ These functions return the leftover itemstack.
     * See documentation on `minetest.compress()` for supported compression methods.
     * currently supported.
     * `...` indicates method-specific arguments. Currently, no methods use this.
+* `minetest.encode_base64(string)`: returns string encoded in base64
+    * Encodes a string in base64.
+* `minetest.decode_base64(string)`: returns string
+    * Decodes a string encoded in base64.
 * `minetest.is_protected(pos, name)`: returns boolean
     * Returns true, if player `name` shouldn't be abled to dig at `pos` or do other
       actions, defineable by mods, due to some mod-defined ownership-like concept.
@@ -2478,13 +2678,17 @@ These functions return the leftover itemstack.
        the creative mode setting, and checks for "sneak" to set the `invert_wall`
        parameter.
 
-* `minetest.forceload_block(pos)`
+* `minetest.forceload_block(pos[, transient])`
     * forceloads the position `pos`.
     * returns `true` if area could be forceloaded
-    * Please note that forceloaded areas are saved when the server restarts.
+    * If `transient` is `false` or absent, the forceload will be persistent
+      (saved between server runs). If `true`, the forceload will be transient
+      (not saved between server runs).
 
-* `minetest.forceload_free_block(pos)`
+* `minetest.forceload_free_block(pos[, transient])`
     * stops forceloading the position `pos`
+    * If `transient` is `false` or absent, frees a persistent forceload.
+      If `true`, frees a transient forceload.
 
 * `minetest.request_insecure_environment()`: returns an environment containing
   insecure functions if the calling mod has been listed as trusted in the
@@ -2542,6 +2746,7 @@ Can be gotten via `minetest.get_meta(pos)`.
 * `get_inventory()`: returns `InvRef`
 * `to_table()`: returns `nil` or `{fields = {...}, inventory = {list1 = {}, ...}}`
 * `from_table(nil or {})`
+    * to clear metadata, use from_table(nil)
     * See "Node Metadata"
 
 ### `NodeTimerRef`
@@ -2638,12 +2843,23 @@ This is basically a reference to a C++ `ServerActiveObject`
 
 ##### Player-only (no-op for other objects)
 * `get_player_name()`: returns `""` if is not a player
-* `get_player_velocity()`: returns `nil` if is not a player otherwise a table {x, y, z} representing the player's instantaneous velocity in nodes/s
+* `get_player_velocity()`: returns `nil` if is not a player, otherwise a
+  table {x, y, z} representing the player's instantaneous velocity in nodes/s
 * `get_look_dir()`: get camera direction as a unit vector
-* `get_look_pitch()`: pitch in radians
-* `get_look_yaw()`: yaw in radians (wraps around pretty randomly as of now)
-* `set_look_pitch(radians)`: sets look pitch
-* `set_look_yaw(radians)`: sets look yaw
+* `get_look_vertical()`: pitch in radians
+     * Angle ranges between -pi/2 and pi/2, which are straight up and down respectively.
+* `get_look_horizontal()`: yaw in radians
+     * Angle is counter-clockwise from the +z direction.
+* `set_look_vertical(radians)`: sets look pitch
+     * radians - Angle from looking forward, where positive is downwards.
+* `set_look_horizontal(radians)`: sets look yaw
+     * radians - Angle from the +z direction, where positive is counter-clockwise.
+* `get_look_pitch()`: pitch in radians - Deprecated as broken. Use get_look_vertical.
+     * Angle ranges between -pi/2 and pi/2, which are straight down and up respectively.
+* `get_look_yaw()`: yaw in radians - Deprecated as broken. Use get_look_horizontal.
+     * Angle is counter-clockwise from the +x direction.
+* `set_look_pitch(radians)`: sets look pitch - Deprecated. Use set_look_vertical.
+* `set_look_yaw(radians)`: sets look yaw - Deprecated. Use set_look_horizontal.
 * `get_breath()`: returns players breath
 * `set_breath(value)`: sets players breath
      * values:
@@ -2689,10 +2905,6 @@ This is basically a reference to a C++ `ServerActiveObject`
 * `hud_set_hotbar_selected_image(texturename)`
     * sets image for selected item of hotbar
 * `hud_get_hotbar_selected_image`: returns texturename
-* `hud_replace_builtin(name, hud_definition)`
-    * replace definition of a builtin hud element
-    * `name`: `"breath"` or `"health"`
-    * `hud_definition`: definition to replace builtin definition
 * `set_sky(bgcolor, type, {texture names})`
     * `bgcolor`: ColorSpec, defaults to white
     * Available types:
@@ -2752,25 +2964,41 @@ An `InvRef` is a reference to an inventory.
 A fast access data structure to store areas, and find areas near a given position or area.
 Every area has a `data` string attribute to store additional information.
 You can create an empty `AreaStore` by calling `AreaStore()`, or `AreaStore(type_name)`.
-If you chose the parameter-less constructor, a fast implementation will be automatically chosen for you.
+If you chose the parameter-less constructor, a fast implementation will be automatically
+chosen for you.
 
 #### Methods
-* `get_area(id, include_borders, include_data)`: returns the area with the id `id`. (optional) Boolean values `include_borders` and `include_data` control what's copied.
-* `get_areas_for_pos(pos, include_borders, include_data)`: returns all areas that contain the position `pos`. (optional) Boolean values `include_borders` and `include_data` control what's copied.
-* `get_areas_in_area(edge1, edge2, accept_overlap, include_borders, include_data)`: returns all areas that contain all nodes inside the area specified by `edge1` and `edge2` (inclusive). If `accept_overlap` is true, also areas are returned that have nodes in common with the specified area. (optional) Boolean values `include_borders` and `include_data` control what's copied.
-* `insert_area(edge1, edge2, data, [id])`: inserts an area into the store. Returns the new area's ID, or nil if the insertion failed. The (inclusive) positions `edge1` and `edge2` describe the area. `data` is a string stored with the area.  If passed, `id` will be used as the internal area ID, it must be a unique number between 0 and 2^32-2. If you use the `id` parameter you must always use it, or insertions are likely to fail due to conflicts.
-* `reserve(count)`: reserves resources for at most `count` many contained areas. Only needed for efficiency, and only some implementations profit.
+* `get_area(id, include_borders, include_data)`: returns the area with the id `id`.
+  (optional) Boolean values `include_borders` and `include_data` control what's copied.
+  Returns nil if specified area id does not exist.
+* `get_areas_for_pos(pos, include_borders, include_data)`: returns all areas that contain
+  the position `pos`. (optional) Boolean values `include_borders` and `include_data` control
+  what's copied.
+* `get_areas_in_area(edge1, edge2, accept_overlap, include_borders, include_data)`:
+  returns all areas that contain all nodes inside the area specified by `edge1` and `edge2` (inclusive).
+  If `accept_overlap` is true, also areas are returned that have nodes in common with the specified area.
+  (optional) Boolean values `include_borders` and `include_data` control what's copied.
+* `insert_area(edge1, edge2, data, [id])`: inserts an area into the store. Returns the new area's ID,
+  or nil if the insertion failed. The (inclusive) positions `edge1` and `edge2` describe the area.
+  `data` is a string stored with the area.  If passed, `id` will be used as the internal area ID,
+  it must be a unique number between 0 and 2^32-2. If you use the `id` parameter you must always use it,
+  or insertions are likely to fail due to conflicts.
+* `reserve(count)`: reserves resources for at most `count` many contained areas.
+  Only needed for efficiency, and only some implementations profit.
 * `remove_area(id)`: removes the area with the given id from the store, returns success.
-* `set_cache_params(params)`: sets params for the included prefiltering cache. Calling invalidates the cache, so that its elements have to be newly generated.
+* `set_cache_params(params)`: sets params for the included prefiltering cache.
+  Calling invalidates the cache, so that its elements have to be newly generated.
     * `params`:
       {
         enabled = boolean, -- whether to enable, default true
-        block_radius = number, -- the radius (in nodes) of the areas the cache generates prefiltered lists for, minimum 16, default 64
+        block_radius = number, -- the radius (in nodes) of the areas the cache generates
+                                  prefiltered lists for, minimum 16, default 64
         limit = number, -- the cache's size, minimum 20, default 1000
       }
 * `to_string()`: Experimental. Returns area store serialized as a (binary) string.
 * `to_file(filename)`: Experimental. Like `to_string()`, but writes the data to a file.
-* `from_string(str)`: Experimental. Deserializes string and loads it into the AreaStore.  Returns success and, optionally, an error message.
+* `from_string(str)`: Experimental. Deserializes string and loads it into the AreaStore.
+  Returns success and, optionally, an error message.
 * `from_file(filename)`: Experimental. Like `from_string()`, but reads the data from a file.
 
 ### `ItemStack`
@@ -2782,13 +3010,11 @@ an itemstring, a table or `nil`.
 #### Methods
 * `is_empty()`: Returns `true` if stack is empty.
 * `get_name()`: Returns item name (e.g. `"default:stone"`).
-* `set_name(item_name)`: Returns boolean success.
-  Clears item on failure.
+* `set_name(item_name)`: Returns boolean whether item was cleared
 * `get_count()`: Returns number of items on the stack.
-* `set_count(count)`
+* `set_count(count)`: Returns boolean whether item was cleared
 * `get_wear()`: Returns tool wear (`0`-`65535`), `0` for non-tools.
-* `set_wear(wear)`: Returns boolean success.
-  Clears item on failure.
+* `set_wear(wear)`: Returns boolean whether item was cleared
 * `get_metadata()`: Returns metadata (a string attached to an item stack).
 * `set_metadata(metadata)`: Returns true.
 * `clear()`: removes all items from the stack, making it empty.
@@ -2834,7 +3060,9 @@ It can be created via `PcgRandom(seed)` or `PcgRandom(seed, sequence)`.
 * `next()`: return next integer random number [`-2147483648`...`2147483647`]
 * `next(min, max)`: return next integer random number [`min`...`max`]
 * `rand_normal_dist(min, max, num_trials=6)`: return normally distributed random number [`min`...`max`]
-    * This is only a rough approximation of a normal distribution with mean=(max-min)/2 and variance=1
+    * This is only a rough approximation of a normal distribution with:
+    *   mean = (max - min) / 2, and
+    *   variance = (((max - min + 1) ^ 2) - 1) / (12 * num_trials)
     * Increasing num_trials improves accuracy of the approximation
 
 ### `SecureRandom`
@@ -3077,7 +3305,9 @@ will place the schematic inside of the VoxelManip.
 * `set_light_data(light_data)`: Sets the `param1` (light) contents of each node
   in the `VoxelManip`
     * expects lighting data in the same format that `get_light_data()` returns
-* `get_param2_data()`: Gets the raw `param2` data read into the `VoxelManip` object
+* `get_param2_data([buffer])`: Gets the raw `param2` data read into the `VoxelManip` object
+    * Returns an array (indices 1 to volume) of integers ranging from `0` to `255`
+    * If the param `buffer` is present, this table will be used to store the result instead
 * `set_param2_data(param2_data)`: Sets the `param2` contents of each node in the `VoxelManip`
 * `calc_lighting([p1, p2], [propagate_shadow])`:  Calculate lighting within the `VoxelManip`
     * To be used only by a `VoxelManip` object from `minetest.get_mapgen_object`
@@ -3183,13 +3413,15 @@ Registered entities
     * It has the member `.object`, which is an `ObjectRef` pointing to the object
     * The original prototype stuff is visible directly via a metatable
 * Callbacks:
-    * `on_activate(self, staticdata)`
+    * `on_activate(self, staticdata, dtime_s)`
         * Called when the object is instantiated.
+        * `dtime_s` is the time passed since the object was unloaded, which can
+          be used for updating the entity state.
     * `on_step(self, dtime)`
         * Called on every server tick, after movement and collision processing.
           `dtime` is usually 0.1 seconds, as per the `dedicated_server_step` setting
           `in minetest.conf`.
-    * `on_punch(self, puncher, time_from_last_punch, tool_capabilities, dir`
+    * `on_punch(self, puncher, time_from_last_punch, tool_capabilities, dir)`
         * Called when somebody punches the object.
         * Note that you probably want to handle most punches using the
           automatic armor group system.
@@ -3317,19 +3549,23 @@ Definition tables
 
         on_activate = function(self, staticdata, dtime_s),
         on_step = function(self, dtime),
-        on_punch = function(self, hitter),
+        on_punch = function(self, puncher, time_from_last_punch, tool_capabilities, dir),
         on_rightclick = function(self, clicker),
         get_staticdata = function(self),
     --  ^ Called sometimes; the string returned is passed to on_activate when
     --    the entity is re-activated from static state
 
-        -- Also you can define arbitrary member variables here
-        myvariable = whatever,
+        -- Also you can define arbitrary member variables here (see item definition for
+        -- more info)
+        _custom_field = whatever,
     }
 
 ### ABM (ActiveBlockModifier) definition (`register_abm`)
 
     {
+        label = "Lava cooling",
+    --  ^ Descriptive label for profiling purposes (optional).
+    --    Definitions with identical labels will be listed as one.
     --  In the following two fields, also group:groupname will work.
         nodenames = {"default:lava_source"},
         neighbors = {"default:water_source", "default:water_flowing"}, -- Any of these --[[
@@ -3346,6 +3582,9 @@ Definition tables
 ### LBM (LoadingBlockModifier) definition (`register_lbm`)
 
     {
+        label = "Upgrade legacy doors",
+    --  ^ Descriptive label for profiling purposes (optional).
+    --    Definitions with identical labels will be listed as one.
         name = "modname:replace_legacy_door",
         nodenames = {"default:lava_source"},
     --  ^ List of node names to trigger the LBM on.
@@ -3362,27 +3601,26 @@ Definition tables
 
     {
         description = "Steel Axe",
-        groups = {}, -- key=name, value=rating; rating=1..3.
+        groups = {}, -- key = name, value = rating; rating = 1..3.
                         if rating not applicable, use 1.
-                        e.g. {wool=1, fluffy=3}
-                            {soil=2, outerspace=1, crumbly=1}
-                            {bendy=2, snappy=1},
-                            {hard=1, metal=1, spikes=1}
+                        e.g. {wool = 1, fluffy = 3}
+                            {soil = 2, outerspace = 1, crumbly = 1}
+                            {bendy = 2, snappy = 1},
+                            {hard = 1, metal = 1, spikes = 1}
         inventory_image = "default_tool_steelaxe.png",
         wield_image = "",
-        wield_scale = {x=1,y=1,z=1},
+        wield_scale = {x = 1, y = 1, z = 1},
         stack_max = 99,
         range = 4.0,
         liquids_pointable = false,
         tool_capabilities = {
             full_punch_interval = 1.0,
-            max_drop_level=0,
-            groupcaps={
+            max_drop_level = 0,
+            groupcaps = {
                 -- For example:
-                snappy={times={[2]=0.80, [3]=0.40}, maxwear=0.05, maxlevel=1},
-                choppy={times={[3]=0.90}, maxwear=0.05, maxlevel=0}
+                choppy = {times = {[1] = 2.50, [2] = 1.40, [3] = 1.00}, uses = 20, maxlevel = 2},
             },
-            damage_groups = {groupname=damage},
+            damage_groups = {groupname = damage},
         },
         node_placement_prediction = nil,
         --[[
@@ -3394,21 +3632,25 @@ Definition tables
           actual result to client in a short moment.
         ]]
         sound = {
+            breaks = "default_tool_break", -- tools only
             place = --[[<SimpleSoundSpec>]],
         },
 
         on_place = func(itemstack, placer, pointed_thing),
         --[[
         ^ Shall place item and return the leftover itemstack
+        ^ The placer may be any ObjectRef or nil.
         ^ default: minetest.item_place ]]
         on_secondary_use = func(itemstack, user, pointed_thing),
         --[[
         ^ Same as on_place but called when pointing at nothing.
+        ^ The user may be any ObjectRef or nil.
         ^ pointed_thing : always { type = "nothing" }
         ]]
         on_drop = func(itemstack, dropper, pos),
         --[[
         ^ Shall drop item and return the leftover itemstack
+        ^ The dropper may be any ObjectRef or nil.
         ^ default: minetest.item_drop ]]
         on_use = func(itemstack, user, pointed_thing),
         --[[
@@ -3417,6 +3659,7 @@ Definition tables
           inventory, or an itemstack to replace the original itemstack.
             e.g. itemstack:take_item(); return itemstack
         ^ Otherwise, the function is free to do what it wants.
+        ^ The user may be any ObjectRef or nil.
         ^ The default functions handle regular use cases.
         ]]
         after_use = func(itemstack, user, node, digparams),
@@ -3429,6 +3672,13 @@ Definition tables
               itemstack:add_wear(digparams.wear)
               return itemstack
             end
+        ^ The user may be any ObjectRef or nil.
+        ]]
+        _custom_field = whatever,
+        --[[
+        ^ Add your own custom fields. By convention, all custom field names
+          should start with `_` to avoid naming collisions with future engine
+          usage.
         ]]
     }
 
@@ -3472,6 +3722,7 @@ Definition tables
         ^ paramtype = "light" allows light to propagate from or through the node with light value
         ^ falling by 1 per node. This line is essential for a light source node to spread its light. ]]
         paramtype2 = "none", -- See "Nodes"
+        place_param2 = nil, -- Force value for param2 when player places node
         is_ground_content = true, -- If false, the cave generator will not carve through this
         sunlight_propagates = false, -- If true, sunlight will go infinitely through this
         walkable = true, -- If true, objects collide with node
@@ -3484,13 +3735,17 @@ Definition tables
         liquid_alternative_flowing = "", -- Flowing version of source liquid
         liquid_alternative_source = "", -- Source version of flowing liquid
         liquid_viscosity = 0, -- Higher viscosity = slower flow (max. 7)
-        liquid_renewable = true, -- Can new liquid source be created by placing two or more sources nearby?
+        liquid_renewable = true, --[[
+        ^ If true, a new liquid source can be created by placing two or more sources nearby ]]
         leveled = 0, --[[
         ^ Block contains level in param2. Value is default level, used for snow.
         ^ Don't forget to use "leveled" type nodebox. ]]
         liquid_range = 8, -- number of flowing nodes around source (max. 8)
         drowning = 0, -- Player will take this amount of damage if no bubbles are left
-        light_source = 0, -- Amount of light emitted by node
+        light_source = 0, --[[
+        ^ Amount of light emitted by node.
+        ^ To set the maximum (currently 14), use the value 'minetest.LIGHT_MAX'.
+        ^ A value outside the range 0 to minetest.LIGHT_MAX causes undefined behavior.]]
         damage_per_second = 0, -- If player is inside node, this damage is caused
         node_box = {type="regular"}, -- See "Node boxes"
         connects_to = nodenames, --[[
@@ -3517,8 +3772,8 @@ Definition tables
             max_items = 1,  -- Maximum number of items to drop.
             items = { -- Choose max_items randomly from this list.
                 {
-                    items = {"foo:bar", "baz:frob"},  -- Choose one item randomly from this list.
-                    rarity = 1,  -- Probability of getting is 1 / rarity.
+                    items = {"foo:bar", "baz:frob"},  -- Items to drop.
+                    rarity = 1,  -- Probability of dropping is 1 / rarity.
                 },
             },
         },
@@ -3690,6 +3945,9 @@ Definition tables
 
 ### Biome definition (`register_biome`)
 
+**Note**
+The Biome API is still in an experimental phase and subject to change.
+
     {
         name = "tundra",
         node_dust = "default:snow",
@@ -3709,6 +3967,9 @@ Definition tables
     --  ^ Node that replaces all seawater nodes not in the defined surface layer.
         node_river_water = "default:ice",
     --  ^ Node that replaces river water in mapgens that use default:river_water.
+        node_riverbed = "default:gravel",
+        depth_riverbed = 2,
+    --  ^ Node placed under river water and thickness of this layer.
         y_min = 1,
         y_max = 31000,
     --  ^ Lower and upper limits for biome.
@@ -3738,7 +3999,7 @@ Definition tables
     {
         deco_type = "simple", -- See "Decoration types"
         place_on = "default:dirt_with_grass",
-    --  ^ Node that decoration can be placed on
+    --  ^ Node (or list of nodes) that the decoration can be placed on
         sidelen = 8,
     --  ^ Size of divisions made in the chunk being generated.
     --  ^ If the chunk size is not evenly divisible by sidelen, sidelen is made equal to the chunk size.
@@ -3757,6 +4018,13 @@ Definition tables
     -- ^ Minimum and maximum `y` positions these decorations can be generated at.
     -- ^ This parameter refers to the `y` position of the decoration base, so
     --   the actual maximum height would be `height_max + size.Y`.
+        spawn_by = "default:water",
+    --  ^ Node (or list of nodes) that the decoration only spawns next to.
+    --  ^ Checks two horizontal planes of neighbouring nodes (including diagonal neighbours),
+    --  ^ one plane at Y = surface and one plane at Y = surface = + 1.
+        num_spawn_by = 1,
+    --  ^ Number of spawn_by nodes that must be surrounding the decoration position to occur.
+    --  ^ If absent or -1, decorations occur next to any nodes.
         flags = "liquid_surface, force_placement",
     --  ^ Flags for all decoration types.
     --  ^ "liquid_surface": Instead of placement on the highest solid surface
@@ -3772,15 +4040,10 @@ Definition tables
     --  ^ Number of nodes high the decoration is made.
     --  ^ If height_max is not 0, this is the lower bound of the randomly selected height.
         height_max = 0,
-    --      ^ Number of nodes the decoration can be at maximum.
+    --  ^ Number of nodes the decoration can be at maximum.
     --  ^ If absent, the parameter 'height' is used as a constant.
-        spawn_by = "default:water",
-    --  ^ Node that the decoration only spawns next to.
-    --  ^ The neighbours checked are the 8 nodes horizontally surrounding the lowest node of the
-    --  ^ decoration, and the 8 nodes horizontally surrounding the ground node below the decoration.
-        num_spawn_by = 1,
-    --  ^ Number of spawn_by nodes that must be surrounding the decoration position to occur.
-    --  ^ If absent or -1, decorations occur next to any nodes.
+        param2 = 0,
+    --  ^ Param2 value of placed decoration node.
 
         ----- Schematic-type parameters
         schematic = "foobar.mts",
@@ -3881,6 +4144,9 @@ Definition tables
         size = 1,
         collisiondetection = false,
     --  ^ collisiondetection: if true collides with physical objects
+        collision_removal = false,
+    --  ^ collision_removal: if true then particle is removed when it collides,
+    --  ^ requires collisiondetection = true to have any effect
         vertical = false,
     --  ^ vertical: if true faces player using y axis only
         texture = "image.png",
@@ -3910,6 +4176,12 @@ Definition tables
     --  ^ minsize/maxsize, minexptime/maxexptime (expirationtime)
         collisiondetection = false,
     --  ^ collisiondetection: if true uses collision detection
+        collision_removal = false,
+    --  ^ collision_removal: if true then particle is removed when it collides,
+    --  ^ requires collisiondetection = true to have any effect
+        attached = ObjectRef,
+    --  ^ attached: if defined, particle positions, velocities and accelerations
+    --  ^ are relative to this object's position and yaw.
         vertical = false,
     --  ^ vertical: if true faces player using y axis only
         texture = "image.png",
@@ -3918,7 +4190,7 @@ Definition tables
     --  ^ Playername is optional, if specified spawns particle only on the player's client
     }
 
-### `HTTPRequest` definition (`http_fetch`, `http_fetch_async`)
+### `HTTPRequest` definition (`HTTPApiTable.fetch_async`, `HTTPApiTable.fetch_async`)
 
     {
         url = "http://example.org",
@@ -3938,7 +4210,7 @@ Definition tables
      -- ^ Optional, if true performs a multipart HTTP request. Default is false.
     }
 
-### `HTTPRequestResult` definition (`http_fetch` callback, `http_fetch_async_get`)
+### `HTTPRequestResult` definition (`HTTPApiTable.fetch` callback, `HTTPApiTable.fetch_async_get`)
 
     {
         completed = true,
diff --git a/doc/menu_lua_api.txt b/doc/menu_lua_api.txt
index ac8713a32..423b8bb9c 100644
--- a/doc/menu_lua_api.txt
+++ b/doc/menu_lua_api.txt
@@ -1,4 +1,4 @@
-Minetest Lua Mainmenu API Reference 0.4.14
+Minetest Lua Mainmenu API Reference 0.4.15
 ========================================
 
 Introduction
@@ -210,6 +210,10 @@ string:trim()
 ^ eg. string.trim("\n \t\tfoo bar\t ") == "foo bar"
 core.is_yes(arg) (possible in async calls)
 ^ returns whether arg can be interpreted as yes
+minetest.encode_base64(string) (possible in async calls)
+^ Encodes a string in base64.
+minetest.decode_base64(string) (possible in async calls)
+^ Decodes a string encoded in base64.
 
 Version compat:
 core.get_min_supp_proto()
diff --git a/doc/old/ancient_main_comment.txt b/doc/old/ancient_main_comment.txt
deleted file mode 100644
index d7b0e307f..000000000
--- a/doc/old/ancient_main_comment.txt
+++ /dev/null
@@ -1,345 +0,0 @@
-------------------------------------------------------------------
-The ancient comment from the beginning of main.cpp is stored here.
-------------------------------------------------------------------
-
-/*
-=============================== NOTES ==============================
-NOTE: Things starting with TODO are sometimes only suggestions.
-
-NOTE: iostream.imbue(std::locale("C")) is very slow
-NOTE: Global locale is now set at initialization
-
-NOTE: If VBO (EHM_STATIC) is used, remember to explicitly free the
-      hardware buffer (it is not freed automatically)
-
-NOTE: A random to-do list saved here as documentation:
-A list of "active blocks" in which stuff happens. (+=done)
-	+ Add a never-resetted game timer to the server
-	+ Add a timestamp value to blocks
-	+ The simple rule: All blocks near some player are "active"
-	- Do stuff in real time in active blocks
-		+ Handle objects
-		- Grow grass, delete leaves without a tree
-		- Spawn some mobs based on some rules
-		- Transform cobble to mossy cobble near water
-		- Run a custom script
-		- ...And all kinds of other dynamic stuff
-	+ Keep track of when a block becomes active and becomes inactive
-	+ When a block goes inactive:
-		+ Store objects statically to block
-		+ Store timer value as the timestamp
-	+ When a block goes active:
-		+ Create active objects out of static objects
-		- Simulate the results of what would have happened if it would have
-		  been active for all the time
-		  	- Grow a lot of grass and so on
-	+ Initially it is fine to send information about every active object
-	  to every player. Eventually it should be modified to only send info
-	  about the nearest ones.
-	  	+ This was left to be done by the old system and it sends only the
-		  nearest ones.
-
-NOTE: Seeds in 1260:6c77e7dbfd29:
-5721858502589302589:
-	Spawns you on a small sand island with a surface dungeon
-2983455799928051958:
-	Enormous jungle + a surface dungeon at ~(250,0,0)
-
-Old, wild and random suggestions that probably won't be done:
--------------------------------------------------------------
-
-SUGG: If player is on ground, mainly fetch ground-level blocks
-
-SUGG: Expose Connection's seqnums and ACKs to server and client.
-      - This enables saving many packets and making a faster connection
-	  - This also enables server to check if client has received the
-	    most recent block sent, for example.
-SUGG: Add a sane bandwidth throttling system to Connection
-
-SUGG: More fine-grained control of client's dumping of blocks from
-      memory
-	  - ...What does this mean in the first place?
-
-SUGG: A map editing mode (similar to dedicated server mode)
-
-SUGG: Transfer more blocks in a single packet
-SUGG: A blockdata combiner class, to which blocks are added and at
-      destruction it sends all the stuff in as few packets as possible.
-SUGG: Make a PACKET_COMBINED which contains many subpackets. Utilize
-      it by sending more stuff in a single packet.
-	  - Add a packet queue to RemoteClient, from which packets will be
-	    combined with object data packets
-		- This is not exactly trivial: the object data packets are
-		  sometimes very big by themselves
-	  - This might not give much network performance gain though.
-
-SUGG: Precalculate lighting translation table at runtime (at startup)
-      - This is not doable because it is currently hand-made and not
-	    based on some mathematical function.
-		- Note: This has been changing lately
-
-SUGG: A version number to blocks, which increments when the block is
-      modified (node add/remove, water update, lighting update)
-	  - This can then be used to make sure the most recent version of
-	    a block has been sent to client, for example
-
-SUGG: Make the amount of blocks sending to client and the total
-	  amount of blocks dynamically limited. Transferring blocks is the
-	  main network eater of this system, so it is the one that has
-	  to be throttled so that RTTs stay low.
-
-SUGG: Meshes of blocks could be split into 6 meshes facing into
-      different directions and then only those drawn that need to be
-
-SUGG: Background music based on cellular automata?
-      http://www.earslap.com/projectslab/otomata
-
-SUGG: Simple light color information to air
-
-SUGG: Server-side objects could be moved based on nodes to enable very
-      lightweight operation and simple AI
-	- Not practical; client would still need to show smooth movement.
-
-SUGG: Make a system for pregenerating quick information for mapblocks, so
-	  that the client can show them as cubes before they are actually sent
-	  or even generated.
-
-SUGG: Erosion simulation at map generation time
-    - This might be plausible if larger areas of map were pregenerated
-	  without lighting (which is slow)
-	- Simulate water flows, which would carve out dirt fast and
-	  then turn stone into gravel and sand and relocate it.
-	- How about relocating minerals, too? Coal and gold in
-	  downstream sand and gravel would be kind of cool
-	  - This would need a better way of handling minerals, mainly
-		to have mineral content as a separate field. the first
-		parameter field is free for this.
-	- Simulate rock falling from cliffs when water has removed
-	  enough solid rock from the bottom
-
-SUGG: For non-mapgen FarMesh: Add a per-sector database to store surface
-      stuff as simple flags/values
-      - Light?
-	  - A building?
-	  And at some point make the server send this data to the client too,
-	  instead of referring to the noise functions
-	  - Ground height
-	  - Surface ground type
-	  - Trees?
-
-Gaming ideas:
--------------
-
-- Aim for something like controlling a single dwarf in Dwarf Fortress
-- The player could go faster by a crafting a boat, or riding an animal
-- Random NPC traders. what else?
-
-Game content:
--------------
-
-- When furnace is destroyed, move items to player's inventory
-- Add lots of stuff
-- Glass blocks
-- Growing grass, decaying leaves
-	- This can be done in the active blocks I guess.
-	- Lots of stuff can be done in the active blocks.
-	- Uh, is there an active block list somewhere? I think not. Add it.
-- Breaking weak structures
-	- This can probably be accomplished in the same way as grass
-- Player health points
-	- When player dies, throw items on map (needs better item-on-map
-	  implementation)
-- Cobble to get mossy if near water
-- More slots in furnace source list, so that multiple ingredients
-  are possible.
-- Keys to chests?
-
-- The Treasure Guard; a big monster with a hammer
-	- The hammer does great damage, shakes the ground and removes a block
-	- You can drop on top of it, and have some time to attack there
-	  before he shakes you off
-
-- Maybe the difficulty could come from monsters getting tougher in
-  far-away places, and the player starting to need something from
-  there when time goes by.
-  - The player would have some of that stuff at the beginning, and
-    would need new supplies of it when it runs out
-
-- A bomb
-- A spread-items-on-map routine for the bomb, and for dying players
-
-- Fighting:
-  - Proper sword swing simulation
-  - Player should get damage from colliding to a wall at high speed
-
-Documentation:
---------------
-
-Build system / running:
------------------------
-
-Networking and serialization:
------------------------------
-
-SUGG: Fix address to be ipv6 compatible
-
-User Interface:
----------------
-
-Graphics:
----------
-
-SUGG: Combine MapBlock's face caches to so big pieces that VBO
-      can be used
-      - That is >500 vertices
-	  - This is not easy; all the MapBlocks close to the player would
-	    still need to be drawn separately and combining the blocks
-		would have to happen in a background thread
-
-SUGG: Make fetching sector's blocks more efficient when rendering
-      sectors that have very large amounts of blocks (on client)
-	  - Is this necessary at all?
-
-SUGG: Draw cubes in inventory directly with 3D drawing commands, so that
-      animating them is easier.
-
-SUGG: Option for enabling proper alpha channel for textures
-
-TODO: Flowing water animation
-
-TODO: A setting for enabling bilinear filtering for textures
-
-TODO: Better control of draw_control.wanted_max_blocks
-
-TODO: Further investigate the use of GPU lighting in addition to the
-      current one
-
-TODO: Artificial (night) light could be more yellow colored than sunlight.
-      - This is technically doable.
-	  - Also the actual colors of the textures could be made less colorful
-	    in the dark but it's a bit more difficult.
-
-SUGG: Somehow make the night less colorful
-
-TODO: Occlusion culling
-      - At the same time, move some of the renderMap() block choosing code
-        to the same place as where the new culling happens.
-      - Shoot some rays per frame and when ready, make a new list of
-	    blocks for usage of renderMap and give it a new pointer to it.
-
-Configuration:
---------------
-
-Client:
--------
-
-TODO: Untie client network operations from framerate
-      - Needs some input queues or something
-	  - This won't give much performance boost because calculating block
-	    meshes takes so long
-
-SUGG: Make morning and evening transition more smooth and maybe shorter
-
-TODO: Don't update all meshes always on single node changes, but
-      check which ones should be updated
-	  - implement Map::updateNodeMeshes() and the usage of it
-	  - It will give almost always a 4x boost in mesh update performance.
-
-- A weapon engine
-
-- Tool/weapon visualization
-
-FIXME: When disconnected to the menu, memory is not freed properly
-
-TODO: Investigate how much the mesh generator thread gets used when
-      transferring map data
-
-Server:
--------
-
-SUGG: Make an option to the server to disable building and digging near
-      the starting position
-
-FIXME: Server sometimes goes into some infinite PeerNotFoundException loop
-
-* Fix the problem with the server constantly saving one or a few
-  blocks? List the first saved block, maybe it explains.
-  - It is probably caused by oscillating water
-  - TODO: Investigate if this still happens (this is a very old one)
-* Make a small history check to transformLiquids to detect and log
-  continuous oscillations, in such detail that they can be fixed.
-
-FIXME: The new optimized map sending doesn't sometimes send enough blocks
-       from big caves and such
-FIXME: Block send distance configuration does not take effect for some reason
-
-Environment:
-------------
-
-TODO: Add proper hooks to when adding and removing active blocks
-
-TODO: Finish the ActiveBlockModifier stuff and use it for something
-
-Objects:
---------
-
-TODO: Get rid of MapBlockObjects and use only ActiveObjects
-	- Skipping the MapBlockObject data is nasty - there is no "total
-	  length" stored; have to make a SkipMBOs function which contains
-	  enough of the current code to skip them properly.
-
-SUGG: MovingObject::move and Player::move are basically the same.
-      combine them.
-	- NOTE: This is a bit tricky because player has the sneaking ability
-	- NOTE: Player::move is more up-to-date.
-	- NOTE: There is a simple move implementation now in collision.{h,cpp}
-	- NOTE: MovingObject will be deleted (MapBlockObject)
-
-TODO: Add a long step function to objects that is called with the time
-      difference when block activates
-
-Map:
-----
-
-TODO: Flowing water to actually contain flow direction information
-      - There is a space for this - it just has to be implemented.
-
-TODO: Consider smoothening cave floors after generating them
-
-TODO: Fix make_tree, make_* to use seed-position-consistent pseudorandom
-	  - delta also
-
-Misc. stuff:
-------------
-TODO: Make sure server handles removing grass when a block is placed (etc)
-      - The client should not do it by itself
-	  - NOTE: I think nobody does it currently...
-TODO: Block cube placement around player's head
-TODO: Protocol version field
-TODO: Think about using same bits for material for fences and doors, for
-	  example
-
-SUGG: Restart irrlicht completely when coming back to main menu from game.
-	- This gets rid of everything that is stored in irrlicht's caches.
-	- This might be needed for texture pack selection in menu
-
-TODO: Merge bahamada's audio stuff (clean patch available)
-
-Making it more portable:
-------------------------
- 
-Stuff to do before release:
----------------------------
-
-Fixes to the current release:
------------------------------
-
-Stuff to do after release:
----------------------------
-
-Doing currently:
-----------------
-
-======================================================================
-
-*/
diff --git a/doc/old/changelog.txt b/doc/old/changelog.txt
deleted file mode 100644
index 1750d71d1..000000000
--- a/doc/old/changelog.txt
+++ /dev/null
@@ -1,147 +0,0 @@
-Minetest changelog
-----------------------
-This should contain all the major changes.
-For minor stuff, refer to the commit log of the repository.
-
-0.3.1: (released on 2011-11-09)
-- Fix frustum culling (previous versions have rendered too much stuff that is not actually visible (about 180 degrees, while should have been more like 100.))
-- Add occlusion culling (improves performance a lot)
-- Add “3d clouds” on/off checkbox in main menu
-- Add “opaque water” on/off checkbox
-- Fix some random minor stuff
-- Turn mipmapping off (This makes far-away textures a bit noisier but better looking)
-- Add Command-line signal handler for Windows (contributed by SpeedProg)
-- Fix network layer segmentation fault introduced in 0.3.dev-20111021
-- Fix water-glass and water-lava and lava-glass surfaces
-
-0.3.0: (released on 2011-11-01)
-- Some small fixes
-0.3.dev-20111021:
-- Modify dungeon masters to only try to shoot players
-- Fix object duplication bug at block load/unload bug
-- Improve network layer
-0.3.dev-20111016:
-- Locked chest (contributed)
-- Server user limit setting (max_users)
-- Wielded tool is shown in HUD (contributed)
-- View bobbing (contributed)
-- Saplings that drop from leaf blocks and when placed on ground will grow to trees (contributed)
-- Optimized map saving (does not re-save everything all the time)
-- New mob system and new mob: dungeon master
-- Death/respawn screen
-
-0.2.20110922_3:
-- Fix the build for MSVC2010; also released for windows using MSVC2010.
-
-0.2.20110922_1:
-- Make client report a newer version number to the server than 2011-07-31 does and make server disallow old clients
-
-0.2.20110922:
-- Map is saved in an SQLite database file (by Queatz)
-- Ladders (MarkTraceur)
-- Lava
-- Apple trees (sfan5)
-- Slightly better looking inventory with transparency
-- /me chat command (Oblomov)
-- Using chosen map seed possible through fixed_map_seed configuration option (kahrl)
-- Fix the long-existed PeerNotFound loop bug
-- Some translations and localization-related fixes
-- Lots of small fixes
-
-2011-07-31_3:
-- Fixes a bug that made the server to deny non-empty passwords from players connecting the first time
-
-2011-07-31_2:
-- Fixes a bug that caused the server to always read an empty password from the client when a client connected.
-
-2011-07-31:
-- A number of small fixes, build system stuff and such (refer to version control log)
-- Map generator no longer crashes at generation limit
-- Fixed mapgen producing lots of cut-down trees
-- Some minor tweaks in map generator (some contributed)
-- Volumetric clouds (contributed)
-- Icon added (graphic contributed)
-- Key configuration menu (contributed)
-- Decorative blocks and items: bookshelf, sandstone, cactus, clay, brick, papyrus, rail, paper, book (contributed)
-- Jungles!
-- Hotbar is a bit smaller
-- Health is now enabled by default; You can now eat cooked rats to heal yourself.
-- Finally added sword textures, altough sword is still of no use
-- Creative mode now preserves normal mode inventory
-
-2011-07-04:
-- Many small fixes
-- Code reorganizing to aid further development
-- Renewed map generator
-
-2011-06-02:
-- Password crash on windows fixed
-- Optimized server CPU usage a lot
-- Furnaces now work also while players are not near to them
-
-2011-05-29:
-- Optimized smooth lighting
-- A number of small fixes
-- Added clouds and simple skyboxes
-- The glass block added
-- Added key configuration to config file
-- Player privileges on server
-- Slightly updated map format
-- Player passwords
-- All textures first searched from texture_path
-- Map directory ("map") has been renamed to "world" (just rename it to load an old world)
-- Mouse inversion (invert_mouse)
-- Grass doesn't grow immediately anymore
-- Fence added
-
-2011-04-24:
-- Smooth lighting with simple ambient occlusion
-- Updated main menu
-
-2011-04-23_0_test:
-- Small bug fixes
-- Item drop multiplication fixed
-- HP added
-- Added A simple monster which spawns to dark places at map generation time
-- Some code refactoring and cleaning (possibly new bugs)
-
-2011-04-11:
-- Fixed crafting a bit
-
-2011-04-10_0:
-- Asynchronous map generation
-- New object system
-
-2011-04-06:
-- Mesh update of node addition/removal is now done asynchronously on client, removing frametime spike
-- Node addition/removal is sent directly only to clients that are closer than 100 nodes to the modification. For the others, the modified blocks are set unsent. (and are re-sent when applicable)
-
-2011-04-05:
-- Made furnace usable
-- Added cobblestone
-- Added wood, stone and steel tools: pickaxes, shovels and axes
-- Incremented to version 0.0.2
-
-2011-04-04:
-- Cleaned client to be completely synchronous, except for the mesh calculation, which is now done with queues in a separate thread.
-- Added node metadata support
-- Added chests
-
-2011-02-17:
-- Added better handling of textures. Now many file extensions are searched. Also too large textures are not put on the texture atlas, and the construction of the texture atlas is stopped when it is full.
-
-2011-02-16:
-- Better handling of Ctrl-C on POSIX systems
-
-2011-02-15:
-- Fixed a problem of not saving and loading the "lighting expired" value of MapBlocks properly. This caused high server CPU usage.
-- Ctrl-C handling on POSIX systems
-- Added simple command support to server
-- Added settings enable_texture_atlas and texture_path
-
-2011-02-14:
-- Created changelog.txt
-- Added sneaking/crouching
-- Modified the looks of the hotbar and cleaned code
-- Added code to allow generating 3D cube images for inventory
-
diff --git a/doc/texture_overrides.txt b/doc/texture_overrides.txt
deleted file mode 100644
index 1a4e11a3c..000000000
--- a/doc/texture_overrides.txt
+++ /dev/null
@@ -1,35 +0,0 @@
-Texture Overrides
-=================
-
-You can override the textures of a node from a texture pack using
-texture overrides. To do this, create a file in a texture pack
-called override.txt
-
-Basic Format
-------------
-
-Each line in an override.txt file is a rule. It consists of
-
-	nodename face-selector texture
-
-For example,
-
-	default:dirt_with_grass sides default_stone.png
-
-You can use ^ operators as usual:
-
-	default:dirt_with_grass sides default_stone.png^[brighten
-
-Face Selectors
---------------
-
-| face-selector | behavior                                          |
-|---------------|---------------------------------------------------|
-| left          | x-                                                |
-| right         | x+                                                |
-| front         | z-                                                |
-| back          | z+                                                |
-| top           | y+                                                |
-| bottom        | y-                                                |
-| sides         | x-, x+, z-, z+                                    |
-| all           | All faces. You can also use '*' instead of 'all'. |
diff --git a/doc/texture_packs.txt b/doc/texture_packs.txt
new file mode 100644
index 000000000..5c535a9f1
--- /dev/null
+++ b/doc/texture_packs.txt
@@ -0,0 +1,158 @@
+Minetest Texture Pack Reference
+===============================
+
+Texture packs allow you to replace textures provided by a mod with your own
+textures.
+
+Texture pack directory structure
+--------------------------------
+
+    textures
+    |-- Texture Pack
+    |   |-- screenshot.png
+    |   |-- description.txt
+    |   |-- override.txt
+    |   |-- your_texture_1.png
+    |   |-- your_texture_2.png
+    `-- Another Texture Pack
+
+### Texture Pack
+This is a directory containing the entire contents of a single texture pack.
+It can be chosen more or less freely and will also become the name of the
+texture pack. The name must not be “base”.
+
+### `description.txt`
+A file containing a short description of the texture pack to be shown in the
+texture packs tab.
+
+### `screenshot.png`
+A preview image showing an in-game screenshot of this texture pack; it will be
+shown in the texture packs tab. It should have an aspect ratio of 3:2 and a
+minimum size of 300×200 pixels.
+
+### `your_texture_1.png`, `your_texture_2.png`, etc.
+Any other PNG files will be interpreted as textures. They must have the same
+names as the textures they are supposed to override. For example, to override
+the apple texture of Minetest Game, add a PNG file named `default_apple.png`.
+
+The custom textures do not necceessarily require the same size as their
+originals, but this might be required for a few particular textures. When
+unsure, just test your texture pack in-game.
+
+Texture modifiers
+-----------------
+
+See lua_api.txt for texture modifiers
+
+Special textures
+----------------
+
+These texture names are hardcoded into the engine but can also be overwritten
+by texture packs. All existing fallback textures can be found in the directory
+`textures/base/pack`.
+
+### Gameplay textures
+
+* `bubble.png`: the bubble texture when the player is drowning
+
+* `crack_anylength.png`: node overlay texture when digging
+
+* `crosshair.png`
+    * the crosshair texture in the center of the screen. The settings
+      `crosshair_color` and `crosshair_alpha` are used to create a cross
+      when no texture was found
+
+* `halo.png`: used for the node highlighting mesh
+
+* `heart.png`: used to display the health points of the player
+
+* `minimap_mask_round.png`: round minimap mask, white gets replaced by the map
+* `minimap_mask_square.png`: mask used for the square minimap
+* `minimap_overlay_round.png`: overlay texture for the round minimap
+* `minimap_overlay_square.png`: overlay texture for the square minimap
+* `object_marker_red.png`: texture for players on the minimap
+* `player_marker.png`: texture for the own player on the square minimap
+
+* `player.png`: front texture of the 2D upright sprite player
+* `player_back.png`: back texture of the 2D upright sprite player
+
+* `moon.png`: texture of the moon. Default texture is generated by Minetest
+* `moon_tonemap.png`: tonemap to be used when `moon.png` was found
+* `sun.png`: texture of the sun. Default texture is generated by Minetest
+* `sun_tonemap.png`: tonemap to be used when `sun.png` was found
+* `sunrisebg.png`: shown sky texture when the sun rises
+
+* `smoke_puff.png`: texture used when an object died by punching
+
+* `unknown_item.png`: shown texture when an item definition was not found
+* `unknown_node.png`: shown texture when a node definition was not found
+* `unknown_object.png`: shown texture when an entity definition was not found
+
+* `wieldhand.png`: texture of the wieldhand
+
+### Mainmenu textures
+
+* `menu_bg.png`: used as mainmenu background when the clouds are disabled
+* `menu_header.png`: header texture when no texture pack is selected
+
+* `no_screenshot.png`
+    * texture when no screenshot was found for a texture pack or mod
+
+* `server_flags_creative.png`: icon for creative servers
+* `server_flags_damage.png`: icon for enabled damage on servers
+* `server_flags_favorite.png`: icon for your favorite servers
+* `server_flags_pvp.png`: icon for enabled PvP on servers
+
+### Android textures
+
+* `down_arrow.png`
+* `left_arrow.png`
+* `right_arrow.png`
+* `up_arrow.png`
+
+* `drop_btn.png`
+* `fast_btn.png`
+* `fly_btn.png`
+* `jump_btn.png`
+* `noclip_btn.png`
+
+* `camera_btn.png`
+* `chat_btn.png`
+* `inventory_btn.png`
+* `rangeview_btn.png`
+
+* `debug_btn.png`
+* `gear_icon.png`
+* `rare_controls.png`
+
+Texture Overrides
+-----------------
+
+You can override the textures of a node from a texture pack using
+texture overrides. To do this, create a file in a texture pack
+called override.txt
+
+Each line in an override.txt file is a rule. It consists of
+
+	nodename face-selector texture
+
+For example,
+
+	default:dirt_with_grass sides default_stone.png
+
+You can use ^ operators as usual:
+
+	default:dirt_with_grass sides default_stone.png^[brighten
+
+Here are face selectors you can choose from:
+
+| face-selector | behavior                                          |
+|---------------|---------------------------------------------------|
+| left          | x-                                                |
+| right         | x+                                                |
+| front         | z-                                                |
+| back          | z+                                                |
+| top           | y+                                                |
+| bottom        | y-                                                |
+| sides         | x-, x+, z-, z+                                    |
+| all           | All faces. You can also use '*' instead of 'all'. |