summaryrefslogtreecommitdiff
path: root/doc/lua_api.txt
diff options
context:
space:
mode:
authorWuzzy <wuzzy2@mail.ru>2021-07-27 17:09:14 +0000
committerGitHub <noreply@github.com>2021-07-27 19:09:14 +0200
commit216728cc5e83ff6c4f13a52821ff3c24b1e315e9 (patch)
tree0ee1fee829124d7ecd520691b2b4c2fbb0cc8cfb /doc/lua_api.txt
parent9c145ba0d8baeea57914c62fcc07c06bc6a0257a (diff)
downloadminetest-216728cc5e83ff6c4f13a52821ff3c24b1e315e9.tar.gz
minetest-216728cc5e83ff6c4f13a52821ff3c24b1e315e9.tar.bz2
minetest-216728cc5e83ff6c4f13a52821ff3c24b1e315e9.zip
Improve documentation of tools (#11128)
Diffstat (limited to 'doc/lua_api.txt')
-rw-r--r--doc/lua_api.txt184
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