+
+
Module cmi
+
The Common Mob Interface
+
+
Info:
+
+
+
+
+
+
+
+
+
+
+
+
+ | 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. |
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
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:
+
+
+
+
+
+
+
+ -
+
+ register_on_diemob (func)
+
+ -
+ Register a callback to be run when a mob dies.
+
+
+
Parameters:
+
+
+
+
+
+
+
+ -
+
+ register_on_activatemob (func)
+
+ -
+ Register a callback to be run when a mob is activated.
+
+
+
Parameters:
+
+
+
+
+
+
+
+ -
+
+ register_on_stepmob (func)
+
+ -
+ Register a callback to be run on mob step.
+
+
+
Parameters:
+
+
+
+
+
+
+
+
+
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:
+
+
+
+
+
+
+
+ -
+
+ 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:
+
+
+ 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
+
+
+
+
+
+
+
+
+
+
+