Improve documentation of tools (#11128)

1 files changed, 122 insertions, 62 deletions

diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 71dc1eaa8..bb94829a5 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -1586,15 +1586,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
 ---------------
@@ -1605,7 +1627,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
 ------------
@@ -1659,8 +1683,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
@@ -1701,17 +1725,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
 --------------------------
@@ -1743,7 +1767,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.
@@ -1779,7 +1803,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.
 
@@ -1810,8 +1834,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.
@@ -1820,7 +1844,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
@@ -1846,50 +1870,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
@@ -1901,9 +1937,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
@@ -1912,7 +1950,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.
 
@@ -1924,8 +1962,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,
@@ -1936,7 +1985,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`
@@ -3394,21 +3443,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
@@ -4334,7 +4383,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.
@@ -4706,7 +4755,7 @@ 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
@@ -5396,9 +5445,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`
@@ -6200,7 +6249,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
@@ -7372,7 +7421,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,
@@ -7445,7 +7494,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)
@@ -7658,7 +7707,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"`
@@ -7682,14 +7731,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'.
@@ -7703,7 +7751,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,
@@ -7714,8 +7762,8 @@ 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
+                    -- Only drop if using a item whose name contains
+                    -- "default:shovel_" (this item filtering by string matching
                     -- is deprecated).
                     tools = {"~default:shovel_"},
                     rarity = 2,
@@ -7796,7 +7844,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.
 
@@ -7883,10 +7931,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