Tools definition

Tools define:

  • Full punch interval
  • Maximum drop level
  • For an arbitrary list of groups:
    • Uses (until the tool breaks)
      • Maximum level (usually 0, 1, 2 or 3)
      • Digging times
      • Damage groups

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 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).

This is not automated; it is the responsibility of the node definition to implement this.


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 is multiplied by 3^leveldiff. leveldiff is the difference of the tool's maxlevel groupcaps and the node's level group. The node cannot be dug if leveldiff is less than zero.

  • uses=10, leveldiff=0: actual uses: 10
  • uses=10, leveldiff=1: actual uses: 30
  • uses=10, leveldiff=2: actual uses: 90

Maximum level

Tells what is the maximum level of a node of this group that the tool will be able to dig.

Digging times

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 for this group, and unable to dig the rating 1, which is the toughest. Unless there is a matching group that enables digging otherwise.

If the result digging time is 0, a delay of 0.15 seconds is added between digging nodes; If the player releases LMB after digging, this delay is set to 0, i.e. players can more quickly click the nodes away instead of holding LMB.

Damage groups

List of damage for groups of entities. See [Entity damage mechanism].

Example definition of the capabilities of a tool

tool_capabilities = {
        crumbly={maxlevel=2, uses=20, times={[1]=1.60, [2]=1.20, [3]=0.80}}
    damage_groups = {fleshy=2},

This makes the tool be able to dig nodes that fulfil both of these:

  • Have the crumbly group
  • Have a level group less or equal to 2

Table of resulting digging times:

crumbly        0     1     2     3     4  <- level
     ->  0     -     -     -     -     -
         1  0.80  1.60  1.60     -     -
         2  0.60  1.20  1.20     -     -
         3  0.40  0.80  0.80     -     -

level diff:    2     1     0    -1    -2

Table of resulting tool uses:

->  0     -     -     -     -     -
    1   180    60    20     -     -
    2   180    60    20     -     -
    3   180    60    20     -     -


  • At crumbly==0, the node is not diggable.
  • At crumbly==3, the level difference digging time divider kicks in and makes easy nodes to be quickly breakable.
  • At level > 2, the node is not diggable, because it's level > maxlevel