BRNSystems/minetest
1
0
Fork 0
forked from Mirrorlandia_minetest/minetest
Code Pull Requests 1 Activity

Improve documentation of tools (#11128)

Browse Source
This commit is contained in:
Wuzzy 2021-07-27 17:09:14 +00:00 committed by GitHub
parent 9c145ba0d8
commit 216728cc5e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 122 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

178
doc/lua_api.txt
View File

@ -1586,15 +1586,37 @@ since, by default, no schematic attributes are set.
Items 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 Item types
---------- ----------
There are three kinds of items: nodes, tools and craftitems. There are three kinds of items: nodes, tools and craftitems.
* Node: Can be placed in the world's voxel grid * Node: Placeable item form of a node in the world's voxel grid
* Tool: Has a wear property but cannot be stacked. The default use action is to * Tool: Has a changable wear property but cannot be stacked
dig nodes or hit objects according to its tool capabilities. * Craftitem: Has no special properties
* Craftitem: Cannot dig nodes or be placed
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 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 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 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 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 Item formats
------------ ------------
@ -1659,8 +1683,8 @@ Groups
====== ======
In a number of places, there is a group table. Groups define the In a number of places, there is a group table. Groups define the
properties of a thing (item, node, armor of entity, capabilities of properties of a thing (item, node, armor of entity, tool capabilities)
tool) in such a way that the engine and other mods can can interact with in such a way that the engine and other mods can can interact with
the thing without actually knowing what the thing is. the thing without actually knowing what the thing is.
Usage Usage
@ -1701,17 +1725,17 @@ Groups of entities
------------------ ------------------
For entities, groups are, as of now, used only for calculating damage. 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]. See [Entity damage mechanism].
object.get_armor_groups() --> a group-rating table (e.g. {fleshy=100}) object.get_armor_groups() --> a group-rating table (e.g. {fleshy=100})
object.set_armor_groups({fleshy=30, cracky=80}) 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 Groups in tool capabilities define which groups of nodes and entities they
effective towards. are effective towards.
Groups in crafting recipes 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 functionality bound to it, and implementation is left up as a suggestion
to games. to games.
### Node, item and tool groups ### Node and item groups
* `not_in_creative_inventory`: (*) Special group for inventory mods to indicate * `not_in_creative_inventory`: (*) Special group for inventory mods to indicate
that the item should be hidden in item lists. that the item should be hidden in item lists.
@ -1779,7 +1803,7 @@ to games.
from destroyed nodes. from destroyed nodes.
* `0` is something that is directly accessible at the start of gameplay * `0` is something that is directly accessible at the start of gameplay
* There is no upper limit * 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. * `slippery`: Players and items will slide on the node.
Slipperiness rises steadily with `slippery` value, starting at 1. Slipperiness rises steadily with `slippery` value, starting at 1.
@ -1810,8 +1834,8 @@ Known damage and digging time defining groups
* `crumbly`: dirt, sand * `crumbly`: dirt, sand
* `cracky`: tough but crackable stuff like stone. * `cracky`: tough but crackable stuff like stone.
* `snappy`: something that can be cut using fine tools; e.g. leaves, small * `snappy`: something that can be cut using things like scissors, shears,
plants, wire, sheets of metal 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 * `choppy`: something that can be cut using force; e.g. trees, wooden planks
* `fleshy`: Living things like animals and the player. This could imply * `fleshy`: Living things like animals and the player. This could imply
some blood effects when hitting. 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 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 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 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. suggests for the hand.
Examples of custom groups 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 purpose. Rating is `1`, `2` or `3`. A higher rating for such a group implies
faster digging time. faster digging time.
The `level` group is used to limit the toughness of nodes a tool can dig The `level` group is used to limit the toughness of nodes an item capable
and to scale the digging times / damage to a greater extent. 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 **Please do understand this**, otherwise you cannot use the system to it's
full potential. 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 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 * Full punch interval
* Maximum drop level * Maximum drop level
* For an arbitrary list of groups: * For an arbitrary list of node groups:
* Uses (until the tool breaks) * Uses (until the tool breaks)
* Maximum level (usually `0`, `1`, `2` or `3`) * Maximum level (usually `0`, `1`, `2` or `3`)
* Digging times * Digging times
* Damage groups * Damage groups
* Punch attack uses (until the tool breaks)
### Full punch interval ### Full punch interval
When used as a weapon, the tool will do full damage if this time is spent 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 tool will do half between punches. If e.g. half the time is spent, the item will do half
damage. damage.
### Maximum drop level ### Maximum drop level
Suggests the maximum level of node, when dug with the tool, that will drop Suggests the maximum level of node, when dug with the item, that will drop
it's useful item. (e.g. iron ore to drop a lump of iron). 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 This is not automated; it is the responsibility of the node definition
to implement this. to implement this.
### Uses ### Uses (tools only)
Determines how many uses the tool has when it is used for digging a node, 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 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=1`: actual uses: 30
* `uses=10, leveldiff=2`: actual uses: 90 * `uses=10, leveldiff=2`: actual uses: 90
For non-tools, this has no effect.
### Maximum level ### 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. be able to dig.
### Digging times ### Digging times
@ -1912,7 +1950,7 @@ List of digging times for different ratings of the group, for nodes of the
maximum level. maximum level.
For example, as a Lua table, `times={2=2.00, 3=0.70}`. This would 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. for this group, and unable to dig the rating `1`, which is the toughest.
Unless there is a matching group that enables digging otherwise. 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]. 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 = { tool_capabilities = {
full_punch_interval=1.5, full_punch_interval=1.5,
@ -1936,7 +1985,7 @@ Example definition of the capabilities of a tool
damage_groups = {fleshy=2}, 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 the `crumbly` group
* Have a `level` group less or equal to `2` * 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 * `minetest.pointed_thing_to_face_pos(placer, pointed_thing)`: returns a
position. position.
* returns the exact position on the surface of a pointed node * 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. that digs a node.
Returns a table with the following fields: Returns a table with the following fields:
* `diggable`: `true` if node can be dug, `false` otherwise. * `diggable`: `true` if node can be dug, `false` otherwise.
* `time`: Time it would take to dig the node. * `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 `time` and `wear` are meaningless if node's not diggable
Parameters: Parameters:
* `groups`: Table of the node groups of the node that would be dug * `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])`: * `minetest.get_hit_params(groups, tool_capabilities [, time_from_last_punch])`:
Simulates an item that punches an object. Simulates an item that punches an object.
Returns a table with the following fields: Returns a table with the following fields:
* `hp`: How much damage the punch would cause. * `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: Parameters:
* `groups`: Damage groups of the object * `groups`: Damage groups of the object
* `tool_capabilities`: Tool capabilities table of the item * `tool_capabilities`: Tool capabilities table of the item
@ -4334,7 +4383,7 @@ Callbacks:
* `puncher`: an `ObjectRef` (can be `nil`) * `puncher`: an `ObjectRef` (can be `nil`)
* `time_from_last_punch`: Meant for disallowing spamming of clicks * `time_from_last_punch`: Meant for disallowing spamming of clicks
(can be `nil`). (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 * `dir`: unit vector of direction of punch. Always defined. Points from the
puncher to the punched. puncher to the punched.
* `damage`: damage that will be done to entity. * `damage`: damage that will be done to entity.
@ -4706,7 +4755,7 @@ Call these functions only at load time!
* `hitter`: ObjectRef - Player that hit * `hitter`: ObjectRef - Player that hit
* `time_from_last_punch`: Meant for disallowing spamming of clicks * `time_from_last_punch`: Meant for disallowing spamming of clicks
(can be nil). (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 * `dir`: Unit vector of direction of punch. Always defined. Points from
the puncher to the punched. the puncher to the punched.
* `damage`: Number that represents the damage calculated by the engine * `damage`: Number that represents the damage calculated by the engine
@ -5396,9 +5445,9 @@ Item handling
information. information.
* `minetest.get_node_drops(node, toolname)` * `minetest.get_node_drops(node, toolname)`
* Returns list of itemstrings that are dropped by `node` when dug * 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 * `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` * `minetest.get_craft_result(input)`: returns `output, decremented_input`
* `input.method` = `"normal"` or `"cooking"` or `"fuel"` * `input.method` = `"normal"` or `"cooking"` or `"fuel"`
* `input.width` = for example `3` * `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, * `get_tool_capabilities()`: returns the digging properties of the item,
or those of the hand if none are defined for this item type or those of the hand if none are defined for this item type
* `add_wear(amount)` * `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 * `amount`: number, integer
* `add_item(item)`: returns leftover `ItemStack` * `add_item(item)`: returns leftover `ItemStack`
* Put some item or stack onto this stack * 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 -- A value outside the range 0 to minetest.LIGHT_MAX causes undefined
-- behavior. -- behavior.
-- See "Tools" section for an example including explanation -- See "Tool Capabilities" section for an example including explanation
tool_capabilities = { tool_capabilities = {
full_punch_interval = 1.0, full_punch_interval = 1.0,
max_drop_level = 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), after_use = function(itemstack, user, node, digparams),
-- default: nil -- default: nil
-- If defined, should return an itemstack and will be called instead of -- 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: -- If after_use doesn't exist, it is the same as:
-- function(itemstack, user, node, digparams) -- function(itemstack, user, node, digparams)
-- itemstack:add_wear(digparams.wear) -- itemstack:add_wear(digparams.wear)
@ -7658,7 +7707,7 @@ Used by `minetest.register_node`.
-- While digging node. -- While digging node.
-- If `"__group"`, then the sound will be -- If `"__group"`, then the sound will be
-- `default_dig_<groupname>`, where `<groupname>` is the -- `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 -- In case of a tie, one of the sounds will be played (but we
-- cannot predict which one) -- cannot predict which one)
-- Default value: `"__group"` -- Default value: `"__group"`
@ -7682,14 +7731,13 @@ Used by `minetest.register_node`.
drop = "", drop = "",
-- Name of dropped item when dug. -- Name of dropped item when dug.
-- Default dropped item is the node itself. -- Default dropped item is the node itself.
-- Using a table allows multiple items, drop chances and tool filtering. -- Using a table allows multiple items, drop chances and item filtering.
-- Tool filtering was undocumented until recently, tool filtering by string -- Item filtering by string matching is deprecated.
-- matching is deprecated.
drop = { drop = {
max_items = 1, max_items = 1,
-- Maximum number of item lists to drop. -- Maximum number of item lists to drop.
-- The entries in 'items' are processed in order. For each: -- 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. -- successful the entire item list is dropped.
-- Entry processing continues until the number of dropped item lists -- Entry processing continues until the number of dropped item lists
-- equals 'max_items'. -- equals 'max_items'.
@ -7703,7 +7751,7 @@ Used by `minetest.register_node`.
items = {"default:diamond"}, 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. -- of these.
tools = {"default:shovel_mese", "default:shovel_diamond"}, tools = {"default:shovel_mese", "default:shovel_diamond"},
rarity = 5, rarity = 5,
@ -7714,8 +7762,8 @@ Used by `minetest.register_node`.
inherit_color = true, inherit_color = true,
}, },
{ {
-- Only drop if using a tool whose name contains -- Only drop if using a item whose name contains
-- "default:shovel_" (this tool filtering by string matching -- "default:shovel_" (this item filtering by string matching
-- is deprecated). -- is deprecated).
tools = {"~default:shovel_"}, tools = {"~default:shovel_"},
rarity = 2, rarity = 2,
@ -7796,7 +7844,7 @@ Used by `minetest.register_node`.
on_dig = function(pos, node, digger), on_dig = function(pos, node, digger),
-- default: minetest.node_dig -- 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. -- return true if the node was dug successfully, false otherwise.
-- Deprecated: returning nil is the same as returning true. -- Deprecated: returning nil is the same as returning true.
@ -7883,10 +7931,22 @@ Used by `minetest.register_craft`.
{ {
type = "toolrepair", 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 ### Cooking