Merge branch 'master' of https://github.com/minetest/minetest

1 files changed, 328 insertions, 116 deletions

diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 7104af3e7..a9bcc1707 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -77,8 +77,16 @@ The game directory can contain the following files:
       `disallowed_mapgens`.
     * `disallowed_mapgen_settings= <comma-separated mapgen settings>`
       e.g. `disallowed_mapgen_settings = mgv5_spflags`
-      These settings are hidden for this game in the world creation
+      These mapgen settings are hidden for this game in the world creation
       dialog and game start menu.
+    * `disabled_settings = <comma-separated settings>`
+      e.g. `disabled_settings = enable_damage, creative_mode`
+      These settings are hidden for this game in the "Start game" tab
+      and will be initialized as `false` when the game is started.
+      Prepend a setting name with an exclamation mark to initialize it to `true`
+      (this does not work for `enable_server`).
+      Only these settings are supported:
+          `enable_damage`, `creative_mode`, `enable_server`.
     * `author`: The author of the game. It only appears when downloaded from
                 ContentDB.
     * `release`: Ignore this: Should only ever be set by ContentDB, as it is
@@ -247,7 +255,7 @@ Media files (textures, sounds, whatever) that will be transferred to the
 client and will be available for use by the mod and translation files for
 the clients (see [Translations]).
 
-It is suggested to use the folders for the purpous they are thought for,
+It is suggested to use the folders for the purpose they are thought for,
 eg. put textures into `textures`, translation files into `locale`,
 models for entities or meshnodes into `models` et cetera.
 
@@ -1022,7 +1030,8 @@ The function of `param2` is determined by `paramtype2` in node definition.
       to access/manipulate the content of this field
     * Bit 3: If set, liquid is flowing downwards (no graphical effect)
 * `paramtype2 = "wallmounted"`
-    * Supported drawtypes: "torchlike", "signlike", "normal", "nodebox", "mesh"
+    * Supported drawtypes: "torchlike", "signlike", "plantlike",
+      "plantlike_rooted", "normal", "nodebox", "mesh"
     * The rotation of the node is stored in `param2`
     * You can make this value by using `minetest.dir_to_wallmounted()`
     * Values range 0 - 5
@@ -1084,9 +1093,14 @@ The function of `param2` is determined by `paramtype2` in node definition.
       palette. The palette should have 32 pixels.
 * `paramtype2 = "glasslikeliquidlevel"`
     * Only valid for "glasslike_framed" or "glasslike_framed_optional"
-      drawtypes.
-    * `param2` values 0-63 define 64 levels of internal liquid, 0 being empty
-      and 63 being full.
+      drawtypes. "glasslike_framed_optional" nodes are only affected if the
+      "Connected Glass" setting is enabled.
+    * Bits 0-5 define 64 levels of internal liquid, 0 being empty and 63 being
+      full.
+    * Bits 6 and 7 modify the appearance of the frame and node faces. One or
+      both of these values may be added to `param2`:
+        * 64  - Makes the node not connect with neighbors above or below it.
+        * 128 - Makes the node not connect with neighbors to its sides.
     * Liquid texture is defined using `special_tiles = {"modname_tilename.png"}`
 * `paramtype2 = "colordegrotate"`
     * Same as `degrotate`, but with colors.
@@ -1198,7 +1212,12 @@ Look for examples in `games/devtest` or `games/minetest_game`.
 * `plantlike_rooted`
     * Enables underwater `plantlike` without air bubbles around the nodes.
     * Consists of a base cube at the co-ordinates of the node plus a
-      `plantlike` extension above with a height of `param2 / 16` nodes.
+      `plantlike` extension above
+    * If `paramtype2="leveled", the `plantlike` extension has a height
+      of `param2 / 16` nodes, otherwise it's the height of 1 node
+    * If `paramtype2="wallmounted"`, the `plantlike` extension
+      will be at one of the corresponding 6 sides of the base cube.
+      Also, the base cube rotates like a `normal` cube would
     * The `plantlike` extension visually passes through any nodes above the
       base cube without affecting them.
     * The base cube texture tiles are defined as normal, the `plantlike`
@@ -1505,6 +1524,9 @@ Position/vector
 
     {x=num, y=num, z=num}
 
+    Note: it is highly recommended to construct a vector using the helper function:
+    vector.new(num, num, num)
+
 For helper functions see [Spatial Vectors].
 
 `pointed_thing`
@@ -1572,15 +1594,37 @@ since, by default, no schematic attributes are set.
 Items
 =====
 
+Items are things that can be held by players, dropped in the map and
+stored in inventories.
+Items come in the form of item stacks, which are collections of equal
+items that occupy a single inventory slot.
+
 Item types
 ----------
 
 There are three kinds of items: nodes, tools and craftitems.
 
-* Node: Can be placed in the world's voxel grid
-* Tool: Has a wear property but cannot be stacked. The default use action is to
-  dig nodes or hit objects according to its tool capabilities.
-* Craftitem: Cannot dig nodes or be placed
+* Node: Placeable item form of a node in the world's voxel grid
+* Tool: Has a changable wear property but cannot be stacked
+* Craftitem: Has no special properties
+
+Every registered node (the voxel in the world) has a corresponding
+item form (the thing in your inventory) that comes along with it.
+This item form can be placed which will create a node in the
+world (by default).
+Both the 'actual' node and its item form share the same identifier.
+For all practical purposes, you can treat the node and its item form
+interchangeably. We usually just say 'node' to the item form of
+the node as well.
+
+Note the definition of tools is purely technical. The only really
+unique thing about tools is their wear, and that's basically it.
+Beyond that, you can't make any gameplay-relevant assumptions
+about tools or non-tools. It is perfectly valid to register something
+that acts as tool in a gameplay sense as a craftitem, and vice-versa.
+
+Craftitems can be used for items that neither need to be a node
+nor a tool.
 
 Amount and wear
 ---------------
@@ -1591,7 +1635,9 @@ default. Tool item stacks can not have an amount greater than 1.
 Tools use a wear (damage) value ranging from 0 to 65535. The
 value 0 is the default and is used for unworn tools. The values
 1 to 65535 are used for worn tools, where a higher value stands for
-a higher wear. Non-tools always have a wear value of 0.
+a higher wear. Non-tools technically also have a wear property,
+but it is always 0. There is also a special 'toolrepair' crafting
+recipe that is only available to tools.
 
 Item formats
 ------------
@@ -1645,8 +1691,8 @@ Groups
 ======
 
 In a number of places, there is a group table. Groups define the
-properties of a thing (item, node, armor of entity, capabilities of
-tool) in such a way that the engine and other mods can can interact with
+properties of a thing (item, node, armor of entity, tool capabilities)
+in such a way that the engine and other mods can can interact with
 the thing without actually knowing what the thing is.
 
 Usage
@@ -1687,17 +1733,17 @@ Groups of entities
 ------------------
 
 For entities, groups are, as of now, used only for calculating damage.
-The rating is the percentage of damage caused by tools with this damage group.
+The rating is the percentage of damage caused by items with this damage group.
 See [Entity damage mechanism].
 
     object.get_armor_groups() --> a group-rating table (e.g. {fleshy=100})
     object.set_armor_groups({fleshy=30, cracky=80})
 
-Groups of tools
----------------
+Groups of tool capabilities
+---------------------------
 
-Groups in tools define which groups of nodes and entities they are
-effective towards.
+Groups in tool capabilities define which groups of nodes and entities they
+are effective towards.
 
 Groups in crafting recipes
 --------------------------
@@ -1729,7 +1775,7 @@ The asterisk `(*)` after a group name describes that there is no engine
 functionality bound to it, and implementation is left up as a suggestion
 to games.
 
-### Node, item and tool groups
+### Node and item groups
 
 * `not_in_creative_inventory`: (*) Special group for inventory mods to indicate
   that the item should be hidden in item lists.
@@ -1765,7 +1811,7 @@ to games.
        from destroyed nodes.
      * `0` is something that is directly accessible at the start of gameplay
      * There is no upper limit
-     * See also: `leveldiff` in [Tools]
+     * See also: `leveldiff` in [Tool Capabilities]
 * `slippery`: Players and items will slide on the node.
   Slipperiness rises steadily with `slippery` value, starting at 1.
 
@@ -1796,8 +1842,8 @@ Known damage and digging time defining groups
 
 * `crumbly`: dirt, sand
 * `cracky`: tough but crackable stuff like stone.
-* `snappy`: something that can be cut using fine tools; e.g. leaves, small
-  plants, wire, sheets of metal
+* `snappy`: something that can be cut using things like scissors, shears,
+  bolt cutters and the like, e.g. leaves, small plants, wire, sheets of metal
 * `choppy`: something that can be cut using force; e.g. trees, wooden planks
 * `fleshy`: Living things like animals and the player. This could imply
   some blood effects when hitting.
@@ -1806,7 +1852,7 @@ Known damage and digging time defining groups
    Can be added to nodes that shouldn't logically be breakable by the
    hand but are. Somewhat similar to `dig_immediate`, but times are more
    like `{[1]=3.50,[2]=2.00,[3]=0.70}` and this does not override the
-   speed of a tool if the tool can dig at a faster speed than this
+   digging speed of an item if it can dig at a faster speed than this
    suggests for the hand.
 
 Examples of custom groups
@@ -1832,50 +1878,62 @@ Groups such as `crumbly`, `cracky` and `snappy` are used for this
 purpose. Rating is `1`, `2` or `3`. A higher rating for such a group implies
 faster digging time.
 
-The `level` group is used to limit the toughness of nodes a tool can dig
-and to scale the digging times / damage to a greater extent.
+The `level` group is used to limit the toughness of nodes an item capable
+of digging can dig and to scale the digging times / damage to a greater extent.
 
 **Please do understand this**, otherwise you cannot use the system to it's
 full potential.
 
-Tools define their properties by a list of parameters for groups. They
+Items define their properties by a list of parameters for groups. They
 cannot dig other groups; thus it is important to use a standard bunch of
-groups to enable interaction with tools.
+groups to enable interaction with items.
 
 
 
 
-Tools
-=====
+Tool Capabilities
+=================
 
-Tools definition
-----------------
+'Tool capabilities' is a property of items that defines two things:
 
-Tools define:
+1) Which nodes it can dig and how fast
+2) Which objects it can hurt by punching and by how much
+
+Tool capabilities are available for all items, not just tools.
+But only tools can receive wear from digging and punching.
+
+Missing or incomplete tool capabilities will default to the
+player's hand.
+
+Tool capabilities definition
+----------------------------
+
+Tool capabilities define:
 
 * Full punch interval
 * Maximum drop level
-* For an arbitrary list of groups:
+* For an arbitrary list of node groups:
     * Uses (until the tool breaks)
-        * Maximum level (usually `0`, `1`, `2` or `3`)
-        * Digging times
-        * Damage groups
+    * Maximum level (usually `0`, `1`, `2` or `3`)
+    * Digging times
+* Damage groups
+* Punch attack uses (until the tool breaks)
 
 ### Full punch interval
 
-When used as a weapon, the tool will do full damage if this time is spent
-between punches. If e.g. half the time is spent, the tool will do half
+When used as a weapon, the item will do full damage if this time is spent
+between punches. If e.g. half the time is spent, the item will do half
 damage.
 
 ### Maximum drop level
 
-Suggests the maximum level of node, when dug with the tool, that will drop
-it's useful item. (e.g. iron ore to drop a lump of iron).
+Suggests the maximum level of node, when dug with the item, that will drop
+its useful item. (e.g. iron ore to drop a lump of iron).
 
 This is not automated; it is the responsibility of the node definition
 to implement this.
 
-### Uses
+### Uses (tools only)
 
 Determines how many uses the tool has when it is used for digging a node,
 of this group, of the maximum level. For lower leveled nodes, the use count
@@ -1887,9 +1945,11 @@ node's `level` group. The node cannot be dug if `leveldiff` is less than zero.
 * `uses=10, leveldiff=1`: actual uses: 30
 * `uses=10, leveldiff=2`: actual uses: 90
 
+For non-tools, this has no effect.
+
 ### Maximum level
 
-Tells what is the maximum level of a node of this group that the tool will
+Tells what is the maximum level of a node of this group that the item will
 be able to dig.
 
 ### Digging times
@@ -1898,7 +1958,7 @@ List of digging times for different ratings of the group, for nodes of the
 maximum level.
 
 For example, as a Lua table, `times={2=2.00, 3=0.70}`. This would
-result in the tool to be able to dig nodes that have a rating of `2` or `3`
+result in the item to be able to dig nodes that have a rating of `2` or `3`
 for this group, and unable to dig the rating `1`, which is the toughest.
 Unless there is a matching group that enables digging otherwise.
 
@@ -1910,8 +1970,19 @@ i.e. players can more quickly click the nodes away instead of holding LMB.
 
 List of damage for groups of entities. See [Entity damage mechanism].
 
-Example definition of the capabilities of a tool
-------------------------------------------------
+### Punch attack uses (tools only)
+
+Determines how many uses (before breaking) the tool has when dealing damage
+to an object, when the full punch interval (see above) was always
+waited out fully.
+
+Wear received by the tool is proportional to the time spent, scaled by
+the full punch interval.
+
+For non-tools, this has no effect.
+
+Example definition of the capabilities of an item
+-------------------------------------------------
 
     tool_capabilities = {
         full_punch_interval=1.5,
@@ -1922,7 +1993,7 @@ Example definition of the capabilities of a tool
         damage_groups = {fleshy=2},
     }
 
-This makes the tool be able to dig nodes that fulfil both of these:
+This makes the item capable of digging nodes that fulfil both of these:
 
 * Have the `crumbly` group
 * Have a `level` group less or equal to `2`
@@ -2026,8 +2097,12 @@ Node metadata contains two things:
 
 Some of the values in the key-value store are handled specially:
 
-* `formspec`: Defines a right-click inventory menu. See [Formspec].
-* `infotext`: Text shown on the screen when the node is pointed at
+* `formspec`: Defines an inventory menu that is opened with the
+              'place/use' key. Only works if no `on_rightclick` was
+              defined for the node. See also [Formspec].
+* `infotext`: Text shown on the screen when the node is pointed at.
+              Line-breaks will be applied automatically.
+              If the infotext is very long, it will be truncated.
 
 Example:
 
@@ -2977,6 +3052,9 @@ Some tags can enclose text, they open with `<tagname>` and close with `</tagname
 Tags can have attributes, in that case, attributes are in the opening tag in
 form of a key/value separated with equal signs. Attribute values should not be quoted.
 
+If you want to insert a literal greater-than sign or a backslash into the text,
+you must escape it by preceding it with a backslash.
+
 These are the technically basic tags but see below for usual tags. Base tags are:
 
 `<style color=... font=... size=...>...</style>`
@@ -3170,15 +3248,38 @@ no particular point.
 
 Internally, it is implemented as a table with the 3 fields
 `x`, `y` and `z`. Example: `{x = 0, y = 1, z = 0}`.
+However, one should *never* create a vector manually as above, such misbehavior
+is deprecated. The vector helpers set a metatable for the created vectors which
+allows indexing with numbers, calling functions directly on vectors and using
+operators (like `+`). Furthermore, the internal implementation might change in
+the future.
+Old code might still use vectors without metatables, be aware of this!
+
+All these forms of addressing a vector `v` are valid:
+`v[1]`, `v[3]`, `v.x`, `v[1] = 42`, `v.y = 13`
+
+Where `v` is a vector and `foo` stands for any function name, `v:foo(...)` does
+the same as `vector.foo(v, ...)`, apart from deprecated functionality.
+
+The metatable that is used for vectors can be accessed via `vector.metatable`.
+Do not modify it!
+
+All `vector.*` functions allow vectors `{x = X, y = Y, z = Z}` without metatables.
+Returned vectors always have a metatable set.
 
 For the following functions, `v`, `v1`, `v2` are vectors,
 `p1`, `p2` are positions,
-`s` is a scalar (a number):
-
-* `vector.new(a[, b, c])`:
-    * Returns a vector.
-    * A copy of `a` if `a` is a vector.
-    * `{x = a, y = b, z = c}`, if all of `a`, `b`, `c` are defined numbers.
+`s` is a scalar (a number),
+vectors are written like this: `(x, y, z)`:
+
+* `vector.new([a[, b, c]])`:
+    * Returns a new vector `(a, b, c)`.
+    * Deprecated: `vector.new()` does the same as `vector.zero()` and
+      `vector.new(v)` does the same as `vector.copy(v)`
+* `vector.zero()`:
+    * Returns a new vector `(0, 0, 0)`.
+* `vector.copy(v)`:
+    * Returns a copy of the vector `v`.
 * `vector.from_string(s[, init])`:
     * Returns `v, np`, where `v` is a vector read from the given string `s` and
       `np` is the next position in the string after the vector.
@@ -3191,14 +3292,14 @@ For the following functions, `v`, `v1`, `v2` are vectors,
     * Returns a string of the form `"(x, y, z)"`.
 * `vector.direction(p1, p2)`:
     * Returns a vector of length 1 with direction `p1` to `p2`.
-    * If `p1` and `p2` are identical, returns `{x = 0, y = 0, z = 0}`.
+    * If `p1` and `p2` are identical, returns `(0, 0, 0)`.
 * `vector.distance(p1, p2)`:
     * Returns zero or a positive number, the distance between `p1` and `p2`.
 * `vector.length(v)`:
     * Returns zero or a positive number, the length of vector `v`.
 * `vector.normalize(v)`:
     * Returns a vector of length 1 with direction of vector `v`.
-    * If `v` has zero length, returns `{x = 0, y = 0, z = 0}`.
+    * If `v` has zero length, returns `(0, 0, 0)`.
 * `vector.floor(v)`:
     * Returns a vector, each dimension rounded down.
 * `vector.round(v)`:
@@ -3218,7 +3319,11 @@ For the following functions, `v`, `v1`, `v2` are vectors,
 * `vector.cross(v1, v2)`:
     * Returns the cross product of `v1` and `v2`.
 * `vector.offset(v, x, y, z)`:
-    * Returns the sum of the vectors `v` and `{x = x, y = y, z = z}`.
+    * Returns the sum of the vectors `v` and `(x, y, z)`.
+* `vector.check()`:
+    * Returns a boolean value indicating whether `v` is a real vector, eg. created
+      by a `vector.*` function.
+    * Returns `false` for anything else, including tables like `{x=3,y=1,z=4}`.
 
 For the following functions `x` can be either a vector or a number:
 
@@ -3237,14 +3342,30 @@ For the following functions `x` can be either a vector or a number:
     * Returns a scaled vector.
     * Deprecated: If `s` is a vector: Returns the Schur quotient.
 
+Operators can be used if all of the involved vectors have metatables:
+* `v1 == v2`:
+    * Returns whether `v1` and `v2` are identical.
+* `-v`:
+    * Returns the additive inverse of v.
+* `v1 + v2`:
+    * Returns the sum of both vectors.
+    * Note: `+` can not be used together with scalars.
+* `v1 - v2`:
+    * Returns the difference of `v1` subtracted by `v2`.
+    * Note: `-` can not be used together with scalars.
+* `v * s` or `s * v`:
+    * Returns `v` scaled by `s`.
+* `v / s`:
+    * Returns `v` scaled by `1 / s`.
+
 For the following functions `a` is an angle in radians and `r` is a rotation
 vector ({x = <pitch>, y = <yaw>, z = <roll>}) where pitch, yaw and roll are
 angles in radians.
 
 * `vector.rotate(v, r)`:
     * Applies the rotation `r` to `v` and returns the result.
-    * `vector.rotate({x = 0, y = 0, z = 1}, r)` and
-      `vector.rotate({x = 0, y = 1, z = 0}, r)` return vectors pointing
+    * `vector.rotate(vector.new(0, 0, 1), r)` and
+      `vector.rotate(vector.new(0, 1, 0), r)` return vectors pointing
       forward and up relative to an entity's rotation `r`.
 * `vector.rotate_around_axis(v1, v2, a)`:
     * Returns `v1` rotated around axis `v2` by `a` radians according to
@@ -3339,21 +3460,21 @@ Helper functions
 * `minetest.pointed_thing_to_face_pos(placer, pointed_thing)`: returns a
   position.
     * returns the exact position on the surface of a pointed node
-* `minetest.get_dig_params(groups, tool_capabilities)`: Simulates a tool
+* `minetest.get_dig_params(groups, tool_capabilities)`: Simulates an item
     that digs a node.
     Returns a table with the following fields:
     * `diggable`: `true` if node can be dug, `false` otherwise.
     * `time`: Time it would take to dig the node.
-    * `wear`: How much wear would be added to the tool.
+    * `wear`: How much wear would be added to the tool (ignored for non-tools).
     `time` and `wear` are meaningless if node's not diggable
     Parameters:
     * `groups`: Table of the node groups of the node that would be dug
-    * `tool_capabilities`: Tool capabilities table of the tool
+    * `tool_capabilities`: Tool capabilities table of the item
 * `minetest.get_hit_params(groups, tool_capabilities [, time_from_last_punch])`:
     Simulates an item that punches an object.
     Returns a table with the following fields:
     * `hp`: How much damage the punch would cause.
-    * `wear`: How much wear would be added to the tool.
+    * `wear`: How much wear would be added to the tool (ignored for non-tools).
     Parameters:
     * `groups`: Damage groups of the object
     * `tool_capabilities`: Tool capabilities table of the item
@@ -3557,7 +3678,7 @@ A whole number, 1 or more.
 Each additional octave adds finer detail to the noise but also increases the
 noise calculation load.
 3 is a typical minimum for a high quality, complex and natural-looking noise
-variation. 1 octave has a slight 'gridlike' appearence.
+variation. 1 octave has a slight 'gridlike' appearance.
 
 Choose the number of octaves according to the `spread` and `lacunarity`, and the
 size of the finest detail you require. For example:
@@ -3632,7 +3753,7 @@ For 2D or 3D perlin noise or perlin noise maps:
         spread = {x = 500, y = 500, z = 500},
         seed = 571347,
         octaves = 5,
-        persist = 0.63,
+        persistence = 0.63,
         lacunarity = 2.0,
         flags = "defaults, absvalue",
     }
@@ -3722,7 +3843,7 @@ The following is a decent set of parameters to work from:
         spread  = {x=200, y=200, z=200},
         seed    = 5390,
         octaves = 4,
-        persist = 0.5,
+        persistence = 0.5,
         lacunarity = 2.0,
         flags = "eased",
     },
@@ -4279,7 +4400,7 @@ Callbacks:
     * `puncher`: an `ObjectRef` (can be `nil`)
     * `time_from_last_punch`: Meant for disallowing spamming of clicks
       (can be `nil`).
-    * `tool_capabilities`: capability table of used tool (can be `nil`)
+    * `tool_capabilities`: capability table of used item (can be `nil`)
     * `dir`: unit vector of direction of punch. Always defined. Points from the
       puncher to the punched.
     * `damage`: damage that will be done to entity.
@@ -4288,6 +4409,9 @@ Callbacks:
     * Called when the object dies.
     * `killer`: an `ObjectRef` (can be `nil`)
 * `on_rightclick(self, clicker)`
+    * Called when `clicker` pressed the 'place/use' key while pointing
+      to the object (not neccessarily an actual rightclick)
+    * `clicker`: an `ObjectRef` (may or may not be a player)
 * `on_attach_child(self, child)`
     * `child`: an `ObjectRef` of the child that attaches
 * `on_detach_child(self, child)`
@@ -4443,6 +4567,10 @@ Utilities
           -- degrotate param2 rotates in units of 1.5° instead of 2°
           -- thus changing the range of values from 0-179 to 0-240 (5.5.0)
           degrotate_240_steps = true,
+          -- ABM supports min_y and max_y fields in definition (5.5.0)
+          abm_min_max_y = true,
+          -- dynamic_add_media supports passing a table with options (5.5.0)
+          dynamic_add_media_table = true,
       }
 
 * `minetest.has_feature(arg)`: returns `boolean, missing_features`
@@ -4505,6 +4633,23 @@ Utilities
 * `minetest.colorspec_to_colorstring(colorspec)`: Converts a ColorSpec to a
   ColorString. If the ColorSpec is invalid, returns `nil`.
     * `colorspec`: The ColorSpec to convert
+* `minetest.colorspec_to_bytes(colorspec)`: Converts a ColorSpec to a raw
+  string of four bytes in an RGBA layout, returned as a string.
+  * `colorspec`: The ColorSpec to convert
+* `minetest.encode_png(width, height, data, [compression])`: Encode a PNG
+  image and return it in string form.
+    * `width`: Width of the image
+    * `height`: Height of the image
+    * `data`: Image data, one of:
+        * array table of ColorSpec, length must be width*height
+        * string with raw RGBA pixels, length must be width*height*4
+    * `compression`: Optional zlib compression level, number in range 0 to 9.
+  The data is one-dimensional, starting in the upper left corner of the image
+  and laid out in scanlines going from left to right, then top to bottom.
+  Please note that it's not safe to use string.char to generate raw data,
+  use `colorspec_to_bytes` to generate raw RGBA values in a predictable way.
+  The resulting PNG image is always 32-bit. Palettes are not supported at the moment.
+  You may use this to procedurally generate textures during server init.
 
 Logging
 -------
@@ -4649,15 +4794,16 @@ Call these functions only at load time!
     * `hitter`: ObjectRef - Player that hit
     * `time_from_last_punch`: Meant for disallowing spamming of clicks
       (can be nil).
-    * `tool_capabilities`: Capability table of used tool (can be nil)
+    * `tool_capabilities`: Capability table of used item (can be nil)
     * `dir`: Unit vector of direction of punch. Always defined. Points from
       the puncher to the punched.
     * `damage`: Number that represents the damage calculated by the engine
     * should return `true` to prevent the default damage mechanism
 * `minetest.register_on_rightclickplayer(function(player, clicker))`
-    * Called when a player is right-clicked
-    * `player`: ObjectRef - Player that was right-clicked
-    * `clicker`: ObjectRef - Object that right-clicked, may or may not be a player
+    * Called when the 'place/use' key was used while pointing a player
+      (not neccessarily an actual rightclick)
+    * `player`: ObjectRef - Player that is acted upon
+    * `clicker`: ObjectRef - Object that acted upon `player`, may or may not be a player
 * `minetest.register_on_player_hpchange(function(player, hp_change, reason), modifier)`
     * Called when the player gets damaged or healed
     * `player`: ObjectRef of the player
@@ -4813,6 +4959,12 @@ Call these functions only at load time!
     * Called when an incoming mod channel message is received
     * You should have joined some channels to receive events.
     * If message comes from a server mod, `sender` field is an empty string.
+* `minetest.register_on_liquid_transformed(function(pos_list, node_list))`
+    * Called after liquid nodes are modified by the engine's liquid transformation
+      process.
+    * `pos_list` is an array of all modified positions.
+    * `node_list` is an array of the old node that was previously at the position
+      with the corresponding index in pos_list.
 
 Setting-related
 ---------------
@@ -5333,9 +5485,9 @@ Item handling
       information.
 * `minetest.get_node_drops(node, toolname)`
     * Returns list of itemstrings that are dropped by `node` when dug
-      with `toolname`.
+      with the item `toolname` (not limited to tools).
     * `node`: node as table or node name
-    * `toolname`: name of the tool item (can be `nil`)
+    * `toolname`: name of the item used to dig (can be `nil`)
 * `minetest.get_craft_result(input)`: returns `output, decremented_input`
     * `input.method` = `"normal"` or `"cooking"` or `"fuel"`
     * `input.width` = for example `3`
@@ -5504,22 +5656,33 @@ Server
     * Returns a code (0: successful, 1: no such player, 2: player is connected)
 * `minetest.remove_player_auth(name)`: remove player authentication data
     * Returns boolean indicating success (false if player nonexistant)
-* `minetest.dynamic_add_media(filepath, callback)`
-    * `filepath`: path to a media file on the filesystem
-    * `callback`: function with arguments `name`, where name is a player name
-      (previously there was no callback argument; omitting it is deprecated)
-    * Adds the file to the media sent to clients by the server on startup
-      and also pushes this file to already connected clients.
-      The file must be a supported image, sound or model format. It must not be
-      modified, deleted, moved or renamed after calling this function.
-      The list of dynamically added media is not persisted.
+* `minetest.dynamic_add_media(options, callback)`
+    * `options`: table containing the following parameters
+        * `filepath`: path to a media file on the filesystem
+        * `to_player`: name of the player the media should be sent to instead of
+                       all players (optional)
+        * `ephemeral`: boolean that marks the media as ephemeral,
+                       it will not be cached on the client (optional, default false)
+    * `callback`: function with arguments `name`, which is a player name
+    * Pushes the specified media file to client(s). (details below)
+      The file must be a supported image, sound or model format.
+      Dynamically added media is not persisted between server restarts.
     * Returns false on error, true if the request was accepted
     * The given callback will be called for every player as soon as the
       media is available on the client.
-      Old clients that lack support for this feature will not see the media
-      unless they reconnect to the server. (callback won't be called)
-    * Since media transferred this way currently does not use client caching
-       or HTTP transfers, dynamic media should not be used with big files.
+    * Details/Notes:
+      * If `ephemeral`=false and `to_player` is unset the file is added to the media
+        sent to clients on startup, this means the media will appear even on
+        old clients if they rejoin the server.
+      * If `ephemeral`=false the file must not be modified, deleted, moved or
+        renamed after calling this function.
+      * Regardless of any use of `ephemeral`, adding media files with the same
+        name twice is not possible/guaranteed to work. An exception to this is the
+        use of `to_player` to send the same, already existent file to multiple
+        chosen players.
+    * Clients will attempt to fetch files added this way via remote media,
+      this can make transfer of bigger files painless (if set up). Nevertheless
+      it is advised not to use dynamic media for big media files.
 
 Bans
 ----
@@ -5775,7 +5938,9 @@ Misc.
     * Example: `minetest.rgba(10, 20, 30, 40)`, returns `"#0A141E28"`
 * `minetest.encode_base64(string)`: returns string encoded in base64
     * Encodes a string in base64.
-* `minetest.decode_base64(string)`: returns string or nil for invalid base64
+* `minetest.decode_base64(string)`: returns string or nil on failure
+    * Padding characters are only supported starting at version 5.4.0, where
+      5.5.0 and newer perform proper checks.
     * Decodes a string encoded in base64.
 * `minetest.is_protected(pos, name)`: returns boolean
     * Returning `true` restricts the player `name` from modifying (i.e. digging,
@@ -5863,6 +6028,19 @@ Misc.
     * If `transient` is `false` or absent, frees a persistent forceload.
       If `true`, frees a transient forceload.
 
+* `minetest.compare_block_status(pos, condition)`
+    * Checks whether the mapblock at positition `pos` is in the wanted condition.
+    * `condition` may be one of the following values:
+        * `"unknown"`: not in memory
+        * `"emerging"`: in the queue for loading from disk or generating
+        * `"loaded"`: in memory but inactive (no ABMs are executed)
+        * `"active"`: in memory and active
+        * Other values are reserved for future functionality extensions
+    * Return value, the comparison status:
+        * `false`: Mapblock does not fulfil the wanted condition
+        * `true`: Mapblock meets the requirement
+        * `nil`: Unsupported `condition` value
+
 * `minetest.request_insecure_environment()`: returns an environment containing
   insecure functions if the calling mod has been listed as trusted in the
   `secure.trusted_mods` setting or security is disabled, otherwise returns
@@ -6122,7 +6300,7 @@ an itemstring, a table or `nil`.
 * `get_tool_capabilities()`: returns the digging properties of the item,
   or those of the hand if none are defined for this item type
 * `add_wear(amount)`
-    * Increases wear by `amount` if the item is a tool
+    * Increases wear by `amount` if the item is a tool, otherwise does nothing
     * `amount`: number, integer
 * `add_item(item)`: returns leftover `ItemStack`
     * Put some item or stack onto this stack
@@ -6316,6 +6494,8 @@ object you are working with still exists.
       Default `{x=0, y=0, z=0}`
     * `forced_visible`: Boolean to control whether the attached entity
        should appear in first person. Default `false`.
+    * This command may fail silently (do nothing) when it would result
+      in circular attachments.
 * `get_attach()`: returns parent, bone, position, rotation, forced_visible,
     or nil if it isn't attached.
 * `get_children()`: returns a list of ObjectRefs that are attached to the
@@ -6552,9 +6732,9 @@ object you are working with still exists.
         * `clouds`: Boolean for whether clouds appear. (default: `true`)
         * `sky_color`: A table containing the following values, alpha is ignored:
             * `day_sky`: ColorSpec, for the top half of the `"regular"`
-              sky during the day. (default: `#8cbafa`)
+              sky during the day. (default: `#61b5f5`)
             * `day_horizon`: ColorSpec, for the bottom half of the
-              `"regular"` sky during the day. (default: `#9bc1f0`)
+              `"regular"` sky during the day. (default: `#90d3f6`)
             * `dawn_sky`: ColorSpec, for the top half of the `"regular"`
               sky during dawn/sunset. (default: `#b4bafa`)
               The resulting sky color will be a darkened version of the ColorSpec.
@@ -6564,7 +6744,7 @@ object you are working with still exists.
               The resulting sky color will be a darkened version of the ColorSpec.
               Warning: The darkening of the ColorSpec is subject to change.
             * `night_sky`: ColorSpec, for the top half of the `"regular"`
-              sky during the night. (default: `#006aff`)
+              sky during the night. (default: `#006bff`)
               The resulting sky color will be a dark version of the ColorSpec.
               Warning: The darkening of the ColorSpec is subject to change.
             * `night_horizon`: ColorSpec, for the bottom half of the `"regular"`
@@ -7029,7 +7209,7 @@ Player properties need to be saved manually.
         -- Default: false
 
         infotext = "",
-        -- By default empty, text to be shown when pointed at object
+        -- Same as infotext for nodes. Empty by default
 
         static_save = true,
         -- If false, never save this object statically. It will simply be
@@ -7130,6 +7310,11 @@ Used by `minetest.register_abm`.
         -- Chance of triggering `action` per-node per-interval is 1.0 / this
         -- value
 
+        min_y = -32768,
+        max_y = 32767,
+        -- min and max height levels where ABM will be processed
+        -- can be used to reduce CPU usage
+
         catch_up = true,
         -- If true, catch-up behaviour is enabled: The `chance` value is
         -- temporarily reduced when returning to an area to simulate time lost
@@ -7287,7 +7472,7 @@ Used by `minetest.register_node`, `minetest.register_craftitem`, and
         -- A value outside the range 0 to minetest.LIGHT_MAX causes undefined
         -- behavior.
 
-        -- See "Tools" section for an example including explanation
+        -- See "Tool Capabilities" section for an example including explanation
         tool_capabilities = {
             full_punch_interval = 1.0,
             max_drop_level = 0,
@@ -7334,6 +7519,8 @@ Used by `minetest.register_node`, `minetest.register_craftitem`, and
         },
 
         on_place = function(itemstack, placer, pointed_thing),
+        -- When the 'place' key was pressed with the item in hand
+        -- and a node was pointed at.
         -- Shall place item and return the leftover itemstack.
         -- The placer may be any ObjectRef or nil.
         -- default: minetest.item_place
@@ -7350,6 +7537,7 @@ Used by `minetest.register_node`, `minetest.register_craftitem`, and
 
         on_use = function(itemstack, user, pointed_thing),
         -- default: nil
+        -- When user pressed the 'punch/mine' key with the item in hand.
         -- Function must return either nil if no item shall be removed from
         -- inventory, or an itemstack to replace the original itemstack.
         -- e.g. itemstack:take_item(); return itemstack
@@ -7360,7 +7548,7 @@ Used by `minetest.register_node`, `minetest.register_craftitem`, and
         after_use = function(itemstack, user, node, digparams),
         -- default: nil
         -- If defined, should return an itemstack and will be called instead of
-        -- wearing out the tool. If returns nil, does nothing.
+        -- wearing out the item (if tool). If returns nil, does nothing.
         -- If after_use doesn't exist, it is the same as:
         --   function(itemstack, user, node, digparams)
         --     itemstack:add_wear(digparams.wear)
@@ -7497,7 +7685,7 @@ Used by `minetest.register_node`.
         leveled_max = 127,
         -- Maximum value for `leveled` (0-127), enforced in
         -- `minetest.set_node_level` and `minetest.add_node_level`.
-		-- Values above 124 might causes collision detection issues.
+        -- Values above 124 might causes collision detection issues.
 
         liquid_range = 8,
         -- Maximum distance that flowing liquid nodes can spread around
@@ -7573,7 +7761,7 @@ Used by `minetest.register_node`.
             -- While digging node.
             -- If `"__group"`, then the sound will be
             -- `default_dig_<groupname>`, where `<groupname>` is the
-            -- name of the tool's digging group with the fastest digging time.
+            -- name of the item's digging group with the fastest digging time.
             -- In case of a tie, one of the sounds will be played (but we
             -- cannot predict which one)
             -- Default value: `"__group"`
@@ -7597,14 +7785,13 @@ Used by `minetest.register_node`.
         drop = "",
         -- Name of dropped item when dug.
         -- Default dropped item is the node itself.
-        -- Using a table allows multiple items, drop chances and tool filtering.
-        -- Tool filtering was undocumented until recently, tool filtering by string
-        -- matching is deprecated.
+        -- Using a table allows multiple items, drop chances and item filtering.
+        -- Item filtering by string matching is deprecated.
         drop = {
             max_items = 1,
             -- Maximum number of item lists to drop.
             -- The entries in 'items' are processed in order. For each:
-            -- Tool filtering is applied, chance of drop is applied, if both are
+            -- Item filtering is applied, chance of drop is applied, if both are
             -- successful the entire item list is dropped.
             -- Entry processing continues until the number of dropped item lists
             -- equals 'max_items'.
@@ -7618,7 +7805,7 @@ Used by `minetest.register_node`.
                     items = {"default:diamond"},
                 },
                 {
-                    -- Only drop if using a tool whose name is identical to one
+                    -- Only drop if using an item whose name is identical to one
                     -- of these.
                     tools = {"default:shovel_mese", "default:shovel_diamond"},
                     rarity = 5,
@@ -7629,14 +7816,24 @@ Used by `minetest.register_node`.
                     inherit_color = true,
                 },
                 {
-                    -- Only drop if using a tool whose name contains
-                    -- "default:shovel_" (this tool filtering by string matching
-                    -- is deprecated).
+                    -- Only drop if using an item whose name contains
+                    -- "default:shovel_" (this item filtering by string matching
+                    -- is deprecated, use tool_groups instead).
                     tools = {"~default:shovel_"},
                     rarity = 2,
                     -- The item list dropped.
                     items = {"default:sand", "default:desert_sand"},
                 },
+                {
+                    -- Only drop if using an item in the "magicwand" group, or 
+                    -- an item that is in both the "pickaxe" and the "lucky"
+                    -- groups.
+                    tool_groups = {
+                        "magicwand",
+                        {"pickaxe", "lucky"}
+                    },
+                    items = {"default:coal_lump"},
+                },
             },
         },
 
@@ -7700,9 +7897,9 @@ Used by `minetest.register_node`.
 
         on_rightclick = function(pos, node, clicker, itemstack, pointed_thing),
         -- default: nil
-        -- Called when clicker (an ObjectRef) "rightclicks"
-        -- ("rightclick" here stands for the placement key) while pointing at
-        -- the node at pos with 'node' being the node table.
+        -- Called when clicker (an ObjectRef) used the 'place/build' key
+        -- (not neccessarily an actual rightclick)
+        -- while pointing at the node at pos with 'node' being the node table.
         -- itemstack will hold clicker's wielded item.
         -- Shall return the leftover itemstack.
         -- Note: pointed_thing can be nil, if a mod calls this function.
@@ -7711,7 +7908,7 @@ Used by `minetest.register_node`.
 
         on_dig = function(pos, node, digger),
         -- default: minetest.node_dig
-        -- By default checks privileges, wears out tool and removes node.
+        -- By default checks privileges, wears out item (if tool) and removes node.
         -- return true if the node was dug successfully, false otherwise.
         -- Deprecated: returning nil is the same as returning true.
 
@@ -7798,10 +7995,22 @@ Used by `minetest.register_craft`.
 
     {
         type = "toolrepair",
-        additional_wear = -0.02,
+        additional_wear = -0.02, -- multiplier of 65536
     }
 
-Note: Tools with group `disable_repair=1` will not repairable by this recipe.
+Adds a shapeless recipe for *every* tool that doesn't have the `disable_repair=1`
+group. Player can put 2 equal tools in the craft grid to get one "repaired" tool
+back.
+The wear of the output is determined by the wear of both tools, plus a
+'repair bonus' given by `additional_wear`. To reduce the wear (i.e. 'repair'),
+you want `additional_wear` to be negative.
+
+The formula used to calculate the resulting wear is:
+
+    65536 - ( (65536 - tool_1_wear) + (65536 - tool_2_wear) + 65536 * additional_wear )
+
+The result is rounded and can't be lower than 0. If the result is 65536 or higher,
+no crafting is possible.
 
 ### Cooking
 
@@ -7869,7 +8078,7 @@ See [Ores] section above for essential information.
             spread = {x = 100, y = 100, z = 100},
             seed = 23,
             octaves = 3,
-            persist = 0.7
+            persistence = 0.7
         },
         -- NoiseParams structure describing one of the perlin noises used for
         -- ore distribution.
@@ -7898,7 +8107,7 @@ See [Ores] section above for essential information.
             spread = {x = 100, y = 100, z = 100},
             seed = 47,
             octaves = 3,
-            persist = 0.7
+            persistence = 0.7
         },
         np_puff_bottom = {
             offset = 4,
@@ -7906,7 +8115,7 @@ See [Ores] section above for essential information.
             spread = {x = 100, y = 100, z = 100},
             seed = 11,
             octaves = 3,
-            persist = 0.7
+            persistence = 0.7
         },
 
         -- vein
@@ -7919,7 +8128,7 @@ See [Ores] section above for essential information.
             spread = {x = 100, y = 100, z = 100},
             seed = 17,
             octaves = 3,
-            persist = 0.7
+            persistence = 0.7
         },
         stratum_thickness = 8,
     }
@@ -8046,7 +8255,7 @@ See [Decoration types]. Used by `minetest.register_decoration`.
             spread = {x = 100, y = 100, z = 100},
             seed = 354,
             octaves = 3,
-            persist = 0.7,
+            persistence = 0.7,
             lacunarity = 2.0,
             flags = "absvalue"
         },
@@ -8302,6 +8511,9 @@ Used by `Player:hud_add`. Returned by `Player:hud_get`.
 
         z_index = 0,
         -- Z index : lower z-index HUDs are displayed behind higher z-index HUDs
+
+        style = 0,
+        -- For "text" elements sets font style: bitfield with 1 = bold, 2 = italic, 4 = monospace
     }
 
 Particle definition