From Minetest Developer Wiki
Jump to: navigation, search
Mbox warning.png This page contains unofficial Lua API documentation and is likely to be outdated or wrong.
For the official and up-to-date documentation, refer to lua_api.txt found in your Minetest installation directory under doc.
Mbox warning.png This page has been proposed for deletion for the following reason: "Contains unofficial and potentially outdated, redundant and inconsistent Lua API information"
If you don't think that this page should be deleted, please explain why on the talk page.

These are non-player moving things in the game. It inherits all the properties of ObjectRef.

New entity types are registered using minetest.register_entity(...) and the prototype definitions indexed using minetest.registered_entities["name"]. Instances are created using minetest.add_entity(...) and may be indexed using minetest.luaentities[objectID]



  • remove() — remove object (after returning from Lua)
  • set_velocity({x=num, y=num, z=num})
  • add_velocity({x=num, y=num, z=num})
  • In comparison to using get_velocity, adding the velocity and then using set_velocity, add_velocity is supposed to avoid synchronization problems.
  • get_velocity(){x=num, y=num, z=num}
  • set_acceleration({x=num, y=num, z=num})
  • get_acceleration(){x=num, y=num, z=num}
  • set_rotation(rot)
  • get_rotation() — returns a rotation
  • set_yaw(radians) — sets the yaw (heading).
  • get_yaw() — returns yaw in radians
  • set_texture_mod(mod)
  • get_texture_mod() — returns current texture modifier
  • set_sprite(p={x=0,y=0}, num_frames=1, framelength=0.2, select_horiz_by_yawpitch=false) — Select sprite from spritesheet with optional animation and DM-style texture selection based on yaw relative to camera
  • get_entity_name() DEPRECATED: Will be removed in a future version
  • get_luaentity()

Inherited from ObjectRef

  • get_pos() — returns {x=num, y=num, z=num}.
  • set_pos(pos)
  • move_to(pos, continuous=false) — interpolated move
  • punch(puncher, time_from_last_punch, tool_capabilities, direction)
  • puncher — an another ObjectRef
  • time_from_last_punch — time since last punch action of the puncher
  • direction: can be nil
  • clicker — another ObjectRef
  • get_hp() — returns number of hitpoints (maximal 20 by default).
  • set_hp(hp) — set number of hitpoints (2 * number of hearts)
  • get_inventory() — returns the InvRef of the object.
  • get_wield_list() — returns the name of the inventory list the wielded item is in
  • get_wield_index() — returns the index of the wielded item
  • get_wielded_item() — returns the wielded item (ItemStack). This is essentially just a pseudonym for object:get_inventory():get_stack(object:get_wield_list(), object:get_wield_index()) so please note the caveats for inventory manipulation (changes will need to be "committed" by calling object:set_wielded_item(modifiedStack) after modifying the stack unless they are done in the context of a callback that implicitly modifies the stack; see minetest.register_node#on_use).
  • set_wielded_item(item) — replaces the wielded item, returns true if successful
  • set_armor_groups({group1=rating, group2=rating, ...})
  • get_armor_groups() - Returns {group1=rating, group2=rating, ...})
  • set_animation({x=1,y=1}, frame_speed=15, frame_blend=0)
  • get_animation() - Returns frames, frame_speed, frame_blend, frame_loop.
  • frames - {x=int,y=int}
  • frame_speed - integer
  • frame_blend - integer
  • frame_loop - true if the animation is looping
  • set_animation_frame_speed(frame_speed)
  • frame_speed - number, default: 15.0
  • set_attach(parent, "", {x=0,y=0,z=0}, {x=0,y=0,z=0})
  • get_attach() — returns nil when not attached or multiple values:
  • parentObjectRef
  • bonestring of the bone name
  • position: attachment position offset
  • rotation: fixed child attachment rotation
  • set_detach()
  • set_bone_position(bone = "", position = {x=0,y=0,z=0}, rotation = {x=0,y=0,z=0})
  • get_bone_position(bone) - returns position and rotation of bone
  • set_properties({object property table})
  • get_properties() - returns object property table
  • is_player() - returns true for players, false otherwise
  • get_nametag_attributes() - returns table with attributes
  • set_nametag_attributes(attributes)
  • sets attributes of nametag of the object
  • attributes: {color = ColorSpec, text = string}

Lua Entity

Each LuaEntitySAO object is backed by a Lua entity copied from the prototype definition given to minetest.register_entity(...). This Lua entity is the place where a mod should store the data and methods it uses to implement custom entities.

The Lua entity's properties are initialized from the prototype's properties. In addition it has the following added properties:

The Lua entity object may be obtained from the LuaEntitySAO using get_luaentity().

Lua Entity Properties

User code may include arbitrary fields and methods in the Lua entity by adding them to the prototype. Runtime values may then be set for each instance individually inside the on_activate(self, staticdata) callback (see below) or by the code causing the entity to be spawned. The following properties are treated specially by the engine if included:

  • initial_properties — Initial values for the ObjectRef properties (hp_max, physical, etc.).
  • on_activate(self, staticdata) — Callback method called by the engine when a new entity is instantiated (spawned) using minetest.add_entity(...) or re-instantiated after the object is deactivated.
    • staticdata — String obtained from get_staticdata() when the entity is saved for later re-instantiation. For a newly created entity (i.e. created using minetest.add_entity(...)), this is the empty string (not nil).
  • on_step(self, dtime) — Callback method called every server tick.
    • dtime — time since last call (usually 0.05 seconds)
  • on_punch(self, puncher, time_from_last_punch, tool_capabilities, dir) — Called by the engine when somebody punches the object. Note that you probably want to handle most punches using the automatic armor group system (See #Entity Damage).
    • puncher — An ObjectRef or nil.
    • time_from_last_punch — Can be used to calculate damage. Can be nil.
    • tool_capabilities — Capability table of used tool. Can be nil.
    • dir — Unit vector in the direction of the punch. Points from the puncher to the entity, and is always defined.
  • on_rightclick(self, clicker) — Callback method called when entity is right-clicked by player.
  • get_staticdata(self) — Used to serialize the entity state when the entity is being deactivated. It must return a string, and this string will be passed to on_activate(self, staticdata) when the entity is re-instantiated.

Entity Damage

By default damage to entities is handled automatically by the engine in a way that is designed to be generic enough to mix use of tools both to dig nodes and act as weapons against entities. This relies heavily on the Groups mechanism. For a tool to damage an entity, the tool's capabilities must specify that it can damage things belonging to a group that the entity has a rating for (the armor_groups field). For example, in the default game living things usually have a rating from 1 to 3 in the "fleshy" group, and a weapon will specify that it can damage "fleshy" things, whereas a shovel can only dig/damage "crumbly" things.

The way the amount of damage is actually determined is by calculating how many nodes with the matching group the tool could dig in the time between swings (with the initial and maximum time being the tool's "full punch interval"), and applying this directly as hit point loss (TODO: figure out what happens when MULTIPLE groups match; is the best one taken, or are results added, or...?). This calculation is done based on the entity's rating in the matching group, with lower values representing the toughest/least damaged nodes/entities. It is also influenced by some special group ratings for the entity:

  • immortal — If the entity belongs to this group (has a rating greater than 0) it is not damaged at all by the default damage mechanism.
  • level — Used to give both entities and tools a progression in the game, with ratings starting at 0 and increasing for tougher, more powerful things. A tool cannot damage an entity with a level over its specified maximum level for a matching group, and can damage the entity more/faster if the tool's maximum level exceeds the entity's level.
  • punch_operable — Special armor group for an entity which disables the damage mechanism for players punching by hand or with a non-tool item, so that it can do something other than taking damage in this circumstance.

To punch an entity or object programmatically, call ObjectRef:punch(...). This ties in with the automatic damage mechanism and entity on_punch(...) callback, whereas a simple HP adjustment using ObjectRef:set_hp(...) does not.

For details about the automatic damage and dig time calculations, see the "lua_api.txt" file included with the game's documentation.


For example Lua entity code see the "item_entity.lua" file included with the game. This file implements the "__builtin:item" entity type, which is used by the game for items dropped on the ground (e.g. when leaves drop saplings or a player drops an item instead of using it to build a node).

Personal tools