ldoc

Contents

• Types
• Callback Registration
• Querying
• Health-related
• Components
• Unique Ids
• Implementation: event notification
• Implementation: components
• Implementation: health

Modules

• cmi

Module cmi

The Common Mob Interface

Info:

• Author: raymoo

Types

Id	Object Identifiers.
PunchCallback (mob, hitter, time_from_last_punch, tool_capabilities, dir, damage, attacker)	Punch callbacks.
DeathCause	Reasons a mob could die.
DeathCallback (mob, cause)	Death callbacks.
ActivationCallback (mob, dtime)	Activation callbacks.
StepCallback (mob, dtime)	Step callbacks.
ComponentDef	Component definitions.

Callback Registration

register_on_punchmob (func)	Register a callback to be run when a mob is punched.
register_on_diemob (func)	Register a callback to be run when a mob dies.
register_on_activatemob (func)	Register a callback to be run when a mob is activated.
register_on_stepmob (func)	Register a callback to be run on mob step.

Querying

is_mob (object)	Checks if an object is a mob.
get_mob_description (object)	Gets a player-readable mob name.

Health-related

attack (mob, puncher, time_from_last_punch, tool_capabilities, direction, attacker)	Attack a mob.
damage_calculator (mob, puncher, time_from_last_punch, tool_capabilities, direction, attacker)	Punch damage calculator.

Components

register_component (component_def)	Register a mob component.
get_mob_component (ObjectRef, component_name)	Get a component from a mob.
set_mob_component (ObjectRef, component_name, new_value)	Set a component in a mob.

Unique Ids

get_uid (mob)

Get the unique ID of a mob.

Implementation: event notification

notify_punch (mob, hitter, time_from_last_punch, tool_capabilities, dir, damage, attacker)	Notify CMI that your mob has been punched.
notify_die (mob, cause)	Notify CMI that your mob has died.
notify_activate (mob, dtime)	Notify CMI that your mob has been activated.
notify_step (mob, dtime)	Notify CMI that your mob is taking a step.

Implementation: components

activate_components (serialized_data)	Activates component data.
serialize_components (component_data)	Serialized component data.

Implementation: health

calculate_damage (mob, puncher, time_from_last_punch, tool_capabilities, direction, attacker)

Calculate damage.

Types

The various data structures used in the API.

Id

Object Identifiers.

Fields:

• type string Either "player" or "mob"
• identifier string For players, is a player name. For mobs, is a unique ID.

PunchCallback (mob, hitter, time_from_last_punch, tool_capabilities, dir, damage, attacker)

Punch callbacks.

Parameters:

• mob ObjectRef
• hitter optional ObjectRef
• time_from_last_punch number
• tool_capabilities tab
• dir optional vector
• damage number
• attacker optional Id Any indirect owner of the punch, for example a player who fired an arrow.

DeathCause

Reasons a mob could die. The type field determines what kind of cause a DeathCause is. It can be one of those specified here, or a custom one provided by a mod. For custom types, the fields should be specified by the mod introducing it.

Fields:

• type string The predefined types are "punch" and "environment".
• puncher optional ObjectRef If type == "punch", contains the puncher. The puncher can be nil.
• attacker optional Id If type == "punch", contains the attacker if it exists and is known.
• pos optional vector If type == "environment", is the position of the damaging node.
• node optional node If type == "environment", describes the damaging node.

DeathCallback (mob, cause)

Death callbacks.

Parameters:

• mob ObjectRef the dying mob
• cause DeathCause cause of death

ActivationCallback (mob, dtime)

Activation callbacks.

Parameters:

• mob ObjectRef the mob being activated
• dtime number the time since the mob was unloaded

StepCallback (mob, dtime)

Step callbacks.

Parameters:

• mob ObjectRef
• dtime number

ComponentDef

Component definitions.

Fields:

• name string a unique name for the component, prefixed with the mod name
• initialize func a function taking no arguments and returning a new instance of the data
• serialize func a function taking your component's data as an input and returning it serialized as a string
• deserialize func a function taking the serialized form of your data and turning it back into the original data

Callback Registration

Functions for registering mob callbacks.

register_on_punchmob (func)

Register a callback to be run when a mob is punched.

Parameters:

• func PunchCallback

register_on_diemob (func)

Register a callback to be run when a mob dies.

Parameters:

• func DeathCallback

register_on_activatemob (func)

Register a callback to be run when a mob is activated.

Parameters:

• func ActivationCallback

register_on_stepmob (func)

Register a callback to be run on mob step.

Parameters:

• func StepCallback

Querying

Functions for getting information about mobs.

is_mob (object)

Checks if an object is a mob.

Parameters:

• object ObjectRef or luaentity

Returns:

bool true if the object is a mob, otherwise returns a falsey value

get_mob_description (object)

Gets a player-readable mob name.

Parameters:

• object ObjectRef or luaentity

Returns:

string

Health-related

Functions related to hurting or healing mobs.

attack (mob, puncher, time_from_last_punch, tool_capabilities, direction, attacker)

Attack a mob. Functions like the punch method of ObjectRef, but takes an additional optional argument for an indirect attacker. Also works on non-mob entities that define an appropriate _cmi_attack method.

Parameters:

• mob ObjectRef or luaentity
• puncher ObjectRef
• time_from_last_punch number
• tool_capabilities tab
• direction vector
• attacker optional Id An indirect owner of the punch. For example, the player who fired an arrow that punches the mob.

damage_calculator (mob, puncher, time_from_last_punch, tool_capabilities, direction, attacker)

Punch damage calculator. By default, this just calculates damage in the vanilla way. Switch it out for something else to change the default damage mechanism for mobs.

Parameters:

• mob ObjectRef
• puncher optional ObjectRef
• time_from_last_punch number
• tool_capabilities table
• direction optional vector
• attacker optional Id

Returns:

number The calculated damage

Components

Components are data stored in a mob, that every mob is guaranteed to contain. You can use them in conjunction with callbacks to extend mobs with new functionality, without explicit support from mob mods.

register_component (component_def)

Register a mob component.

Parameters:

• component_def ComponentDef

get_mob_component (ObjectRef, component_name)

Get a component from a mob.

Parameters:

• ObjectRef mob |luaentity mob
• component_name string

Returns:

The requested component, or nil if it doesn't exist

set_mob_component (ObjectRef, component_name, new_value)

Set a component in a mob.

Parameters:

• ObjectRef mob |luaentity mob
• component_name string
• new_value

Unique Ids

Every mob gets a unique ID when they are created. This feature is implemented as a component, so you can use it as an example.

get_uid (mob)

Get the unique ID of a mob.

Parameters:

• mob ObjectRef or luaentity

Returns:

string

Implementation: event notification

Functions used to notify CMI when things happen to your mob. Only necessary when you are implementing the interface.

notify_punch (mob, hitter, time_from_last_punch, tool_capabilities, dir, damage, attacker)

Notify CMI that your mob has been punched. Call this before doing any punch handling that is not "read-only".

Parameters:

• mob ObjectRef
• hitter optional ObjectRef
• time_from_last_punch number
• tool_capabilities tab
• dir optional vector
• damage number
• attacker optional Id unknown.

Returns:

Returns true if punch handling should be aborted.

notify_die (mob, cause)

Notify CMI that your mob has died. Call this right before calling remove.

Parameters:

• mob ObjectRef the dying mob
• cause DeathCause cause of death

notify_activate (mob, dtime)

Notify CMI that your mob has been activated. Call this after all other mob initialization.

Parameters:

• mob ObjectRef the mob being activated
• dtime number the time since the mob was unloaded

notify_step (mob, dtime)

Notify CMI that your mob is taking a step. Call this on every step. It is suggested to call it before or after all other processing, to avoid logic errors caused by callbacks handling the same state as your entity's normal step logic.

Parameters:

• mob ObjectRef
• dtime number

Implementation: components

Functions related to implementing entity components. Only necessary when you are implementing the interface.

activate_components (serialized_data)

Activates component data. On mob activation, call this and put the result in the _cmi_components field of its luaentity.

Parameters:

• serialized_data optional string the serialized form of the string, if available. If the mob has never had component data, do not pass this argument.

Returns:

component data

serialize_components (component_data)

Serialized component data. When serializing your mob data, call this and put the result somewhere safe, where it can be retrieved on activation to be passed to #{activate_components}.

Parameters:

• component_data

Returns:

string

Implementation: health

Functions related to health that are needed for implementation of the interface. Only necessary if you are implementing the interface.

calculate_damage (mob, puncher, time_from_last_punch, tool_capabilities, direction, attacker)

Calculate damage. Use this function when you want to calculate the "default" damage. If you are a modder who wants to switch out the damage mechanism, do not replace this function. Replace #{damage_calculator} instead.

Parameters:

• mob ObjectRef
• puncher optional ObjectRef
• time_from_last_punch number
• tool_capabilities table
• direction optional vector
• attacker optional Id

Returns:

number