minetest
/
minetest
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve documentation of tools (#11128)

master
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

184
doc/lua_api.txt
View File

@ -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