Registered entities¶

Functions receive a "luaentity" table as self:

• It has the member name, which is the registered name ("mod:thing")
• It has the member object, which is an ObjectRef pointing to the object
• The original prototype is visible directly via a metatable

Callbacks:

• on_activate(self, staticdata, dtime_s)
  • Called when the object is instantiated.
  • dtime_s is the time passed since the object was unloaded, which can be used for updating the entity state.
• on_deactivate(self, removal)
  • Called when the object is about to get removed or unloaded.
  • removal: boolean indicating whether the object is about to get removed. Calling object:remove() on an active object will call this with removal=true. The mapblock the entity resides in being unloaded will call this with removal=false.
  • Note that this won't be called if the object hasn't been activated in the first place. In particular, core.clear_objects({mode = "full"}) won't call this, whereas core.clear_objects({mode = "quick"}) might call this.
• on_step(self, dtime, moveresult)
  • Called on every server tick, after movement and collision processing.
  • dtime: elapsed time since last call
  • moveresult: table with collision info (only available if physical=true)
• on_punch(self, puncher, time_from_last_punch, tool_capabilities, dir, damage)
  • Called when somebody punches the object.
  • Note that you probably want to handle most punches using the automatic armor group system.
  • 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 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.
  • Can return true to prevent the default damage mechanism.
• on_death(self, killer)
  • Called when the object dies.
  • killer: an ObjectRef (can be nil)
• on_rightclick(self, clicker)
  • Called when clicker pressed the 'place/use' key while pointing to the object (not necessarily an actual rightclick)
  • clicker: an ObjectRef (may or may not be a player)
• on_attach_child(self, child)
  • Called after another object is attached to this object.
  • child: an ObjectRef of the child
• on_detach_child(self, child)
  • Called after another object has detached from this object.
  • child: an ObjectRef of the child
• on_detach(self, parent)
  • Called after detaching from another object.
  • parent: an ObjectRef from where it got detached
  • Note: this is also called before removal from the world.
• get_staticdata(self)
  • Should return a string that will be passed to on_activate when the object is instantiated the next time.

Collision info passed to on_step (moveresult argument):

{
    touching_ground = boolean,
    -- Note that touching_ground is only true if the entity was moving and
    -- collided with ground.

    collides = boolean,
    standing_on_object = boolean,

    collisions = {
        {
            type = string, -- "node" or "object",
            axis = string, -- "x", "y" or "z"
            node_pos = vector, -- if type is "node"
            object = ObjectRef, -- if type is "object"
            -- The position of the entity when the collision occurred.
            -- Available since feature "moveresult_new_pos".
            new_pos = vector,
            old_velocity = vector,
            new_velocity = vector,
        },
        ...
    }
    -- `collisions` does not contain data of unloaded mapblock collisions
    -- or when the velocity changes are negligibly small
}