Minetest API

• Getting Started
• Methods
• Types
• Paths
• Naming
• Registry
• Nodes
• Items
• Formspec

Items

Item Types

• Node register_node A node from the world
• Tool register_tool A tool/weapon that can dig and damage things according to tool_capabilities
• Craftitem register_craftitem A miscellaneous item

Item Formats

Items and item stacks can exist in three formats. When an item must be passed to a function, it can usually be in any of these formats.

• Serialized This is called stackstring or itemstring. eg. default:dirt 5 default:pick_wood 21323 default:apple
• Table
  • 5 dirt nodes - {name="default:dirt", count=5, wear=0, metadata=""}
  • a wooden pick about 1/3 weared out - {name="default:pick_wood", count=1, wear=21323, metadata=""}
  • an apple - {name="default:apple", count=1, wear=0, metadata=""}
• ItemStack C++ native format with many helper methods. Useful for converting between formats. See the Class reference section for details.

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 the thing without actually knowing what the thing is.

Usage:

• Groups are stored in a table, having the group names with keys and the group ratings as values. For example:

groups = {crumbly=3, soil=1} Default dirt (soil group actually currently not defined; TODO)

groups = {crumbly=2, soil=1, level=2, outerspace=1} A more special dirt-kind of thing

• Groups always have a rating associated with them. If there is no useful meaning for a rating for an enabled group, it shall be 1.
• When not defined, the rating of a group defaults to 0. Thus when you read groups, you must interpret nil and 0 as the same value, 0.

You can read the rating of a group for an item or a node by using [minetest.get_item_group](minetest.get_item_group)(itemname, groupname)

Groups of items

Groups of items can define what kind of an item it is (eg. dye).

Groups of nodes

In addition to the general item things, groups are used to define whether a node is destroyable and how long it takes to destroy by a tool.

Groups of entities

For entities, groups are, as of now, used only for calculating damage.

object.get_armor_groups() --> a group-rating table (eg. {fleshy=3})
object.set_armor_groups({level=2, fleshy=2, cracky=2})

Groups of tools

Groups in tools define which groups of nodes and entities they are effective towards.

Groups in crafting recipes

An example: Make meat soup from any meat, any water and any bowl

{
	output = 'food:meat_soup_raw',
	recipe = {
		{'group:meat'},
		{'group:water'},
		{'group:bowl'},
	},
	-- preserve = {'group:bowl'}, -- Not implemented yet (TODO)
}

An another example: Make red wool from white wool and red dye

{
	type = 'shapeless',
	output = 'wool:red',
	recipe = {'wool:white', 'group:dye,basecolor_red'},
}

Special groups

• immortal Disables the group damage system for an entity.
• level Can be used to give an additional sense of progression in the game.
  • A larger level will cause eg. a weapon of a lower level make much less damage, and get weared out much faster, or not be able to get drops from destroyed nodes.
  • 0 is something that is directly accessible at the start of gameplay
  • There is no upper limit
• dig_immediate (player can always pick up node without tool wear)
  • 2: node is removed without tool wear after 0.5 seconds or so (rail, sign)
  • 3: node is removed without tool wear immediately (torch)
• disable_jump Player (and possibly other things) cannot jump from node
• fall_damage_add_percent damage speed = speed * (1 + value/100)
• bouncy value is bounce speed in percent
• not_in_creative_inventory Prevents the item from appearing in the creative inventory.

Known damage and digging time defining groups

Valid ratings for these are 0, 1, 2 and 3, unless otherwise stated.

• crumbly dirt, sand
• cracky tough but crackable stuff like stone.
• snappy something that can be cut using fine tools; eg. leaves, small plants, wire, sheets of metal
• choppy something that can be cut using force; eg. trees, wooden planks
• fleshy Living things like animals and the player. This could imply some blood effects when hitting.
• explody Especially prone to explosions
• oddly_breakable_by_hand 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 suggests for the hand.

Examples of custom groups

Item groups are often used for defining, well, groups of items.

• meat any meat-kind of a thing (rating might define the size or healing ability or be irrelevant - it is not defined as of yet)
• eatable anything that can be eaten. Rating might define HP gain in half hearts.
• flammable can be set on fire. Rating might define the intensity of the fire, affecting eg. the speed of the spreading of an open fire.
• wool any wool (any origin, any color)
• metal any metal
• weapon any weapon
• heavy anything considerably heavy

Digging time calculation specifics

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.

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 cannot dig other groups; thus it is important to use a standard bunch of groups to enable interaction with tools.

Tools define:

• Full punch interval When used as a weapon, the tool will do full damage if this time is spent between punches. If eg. 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. (eg. iron ore to drop a lump of iron). This is not automated; it is the responsibility of the node definition to implement this.
• For an arbitrary list of groups:
  • Uses (until the tool breaks) 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.
    • uses=10, leveldiff=0 -> actual uses: 10
    • uses=10, leveldiff=1 -> actual uses: 30
    • uses=10, leveldiff=2 -> actual uses: 90
  • Maximum level (usually 0, 1, 2 or 3) 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.
    • For entities, damage equals the amount of nodes dug in the time spent between hits, with a maximum time of full_punch_interval`.

Example definition of the capabilities of a tool

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

• Have the crumbly group

• Have a level group less or equal to 2

  tool_capabilities = { full_punch_interval=1.5, max_drop_level=1, groupcaps={ crumbly={maxlevel=2, uses=20, times={[1]=1.60, [2]=1.20, [3]=0.80}} } }

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

Notes:

• 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

Entity damage mechanism

Damage calculation:

• Take the time spent after the last hit
• Limit time to full_punch_interval
• Take the damage groups and imagine a bunch of nodes that have them
• Damage in HP is the amount of nodes destroyed in this time.

Client predicts damage based on damage groups. Because of this, it is able to give an immediate response when an entity is damaged or dies; the response is pre-defined somehow (eg. by defining a sprite animation) (not implemented; TODO). Currently a smoke puff will appear when an entity dies.

The group immortal completely disables normal damage.

Entities can define a special armor group, which is punch_operable. This group disables the regular damage mechanism for players punching it by hand or a non-tool item, so that it can do something else than take damage.

On the Lua side, every punch calls entity:on_punch(puncher, time_from_last_punch, tool_capabilities, direction). This should never be called directly, because damage is usually not handled by the entity itself.

• puncher is the object performing the punch. Can be nil. Should never be accessed unless absolutely required, to encourage interoperability.
• time_from_last_punch is time from last punch (by puncher) or nil.
• tool_capabilities can be nil.
• direction is a unit vector, pointing from the source of the punch to the punched object.

To punch an entity/object in Lua, call object:punch(puncher, time_from_last_punch, tool_capabilities, direction).

• Return value is tool wear.
• Parameters are equal to the above callback.
• If direction is nil and puncher is not nil, direction will be automatically filled in based on the location of puncher.

Afterword

Minetest Links

• Minetest
• Forum
• Github
• Gamewiki

Lua Links

• Lua Manual
• Learning Lua

We're Social

• Facebook
• Twitter
• Google +

Chat with us

There are developers, modders, themers, server admins and players on IRC at freenode on the channel #minetest (chatlogs)

Webchat