LuaEntitySAO

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. Instances are created using minetest.add_entity(...) and may be indexed using

Methods

 * — remove object (after returning from Lua)
 * In comparison to using get_velocity, adding the velocity and then using set_velocity, add_velocity is supposed to avoid synchronization problems.
 * In comparison to using get_velocity, adding the velocity and then using set_velocity, add_velocity is supposed to avoid synchronization problems.
 * In comparison to using get_velocity, adding the velocity and then using set_velocity, add_velocity is supposed to avoid synchronization problems.


 * rot is a vector containing euler angles (radians), also see https://en.wikipedia.org/wiki/Euler_angles
 * These angles describe a right-handed, extrinsic rotation about axes z, x, y (in that order).
 * rot is a vector containing euler angles (radians), also see https://en.wikipedia.org/wiki/Euler_angles
 * These angles describe a right-handed, extrinsic rotation about axes z, x, y (in that order).
 * rot is a vector containing euler angles (radians), also see https://en.wikipedia.org/wiki/Euler_angles
 * These angles describe a right-handed, extrinsic rotation about axes z, x, y (in that order).


 * — returns a rotation
 * — sets the yaw (heading).
 * — returns yaw in radians
 * — returns current texture modifier
 * — Select sprite from spritesheet with optional animation and DM-style texture selection based on yaw relative to camera
 * DEPRECATED: Will be removed in a future version
 * DEPRECATED: Will be removed in a future version

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:


 * name — The registered name passed to minetest.register_entity(...).
 * object — Reference back to the LuaEntitySAO object.

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

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  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 values for the ObjectRef properties (hp_max, physical, etc.).
 * — 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  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  ).
 * — Callback method called every server tick.
 * dtime — time since last call (usually 0.05 seconds)
 * — 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 ).
 * 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.
 * — Callback method called when entity is right-clicked by player.
 * — Used to serialize the entity state when the entity is being deactivated. It must return a string, and this string will be passed to   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  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. This ties in with the automatic damage mechanism and entity  callback, whereas a simple HP adjustment using   does not.

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

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