Module `api`

Mobs Redo API (11th August 2017).

Configuration Settings Used by this Mod

enable_damage	Enable damage to players.
only_peaceful_mobs	Peaceful mobs only.
mobs_disable_blood	Disable blood effects.
mobs_spawn_protected	Spawn in protected areas.
remove_far_mobs	Remove far mobs.
<prefix>:<name>	Mob spawn rate & count.
mob_difficulty	Mobs difficulty.
mob_show_health	Show mobs' health bars.

Functions

mobs:register_mob (name, def)	Registers a mob entity.
mobs:register_spawn (name, nodes, max_light, min_light, chance, active_object_count, max_height, day_toggle)	Registers spawning behavior of mob.
mobs:spawn_specific (name, nodes, neighbors, min_light, max_light, interval, chance, active_object_count, min_height, max_height, day_toggle, on_spawn)	Registers spawning behavior of mob.
mobs:spawn (def)	Registers spawning behavior of mob.
mobs:register_arrow (name, def)	Registers an item that mob can use for ranged attack.
mobs:register_egg (name, description, background, addegg, no_creative)	Registers a mob spawning egg.
mobs:boom (self, pos, radius)	Generates a self-destruct explosion from mob.
mobs:explosion (pos, radius)	Generates a self-destruct explosion from mob.
mobs:capture_mob (self, clicker, chance_hand, chance_net, chance_lasso, force_take, replacewith)	Attempts to capture a mob & place in inventory.
mobs:feed_tame (table, clicker, feed_count, breed, tame)	Feed & tame mobs.
mobs:protect (self, clicker)	Protects mobs from being attacked by other players.
mobs:attach (self, player)	Attaches a player to the mob so it can be ridden.
mobs:detach (player, offset)	Detaches player from riding mob.
mobs:drive (self, move_animation, stand_animation, can_fly, dtime)	Controls mob movement with player riding.
mobs:fly (self, dtime, speed, can_shoot, arrow_entity, move_animation, stand_animation)	Controls mob flight with player riding.
mobs:set_animation (self, name)	Sets current animation for mob.

Function Definition Tables

mobs:register_mob.def	Definition table for mobs:register_mob.
mobs:register_arrow.def	Definition table for mobs:register_arrow.

Configuration Settings Used by this Mod

enable_damage

Enable damage to players.

If true, monsters will attack players.

Type: bool
Default: true

only_peaceful_mobs

Peaceful mobs only.

If true, only animals will spawn in game.

Type: bool
Default: false

mobs_disable_blood

Disable blood effects.

If true, blood splatters will not appear when mob is hit.

Type: bool
Default: false

mobs_spawn_protected

Spawn in protected areas.

If set to 1, mobs will not spawn in protected areas.

Type: int
Default: 0

remove_far_mobs

Remove far mobs.

If true, mobs that are outside players visual range will be removed.

Type: bool
Default: false

<prefix>:<name>

Mob spawn rate & count.

Can change specific mob spawn chance & count (0 to disable).

Usage: <prefix>:<name> = chance,count

mintest.conf Example:

# First number specifies “chance”, second is max spawns
# allowed within a section of the map at one time.
mobs_animal:cow = 1000,5

mob_difficulty

Mobs difficulty.

Sets difficulty level (health & hit damage multiplied by this number).

Type: float
Default: 1.0

mob_show_health

Show mobs' health bars.

If false then punching mob will not show health status.

Type: bool
Default: true

Functions

mobs:register_mob (name, def)

Registers a mob entity.

Parameters:

name string Name of the mob.
def table Definition table (see: mobs:register_mob.def).

mobs:register_spawn (name, nodes, max_light, min_light, chance, active_object_count, max_height, day_toggle)

Registers spawning behavior of mob.

See: mobs:spawn_specific for parameter descriptions.

Parameters:

name string
nodes table
max_light int
min_light int
chance int
active_object_count int
max_height int
day_toggle bool

mobs:spawn_specific (name, nodes, neighbors, min_light, max_light, interval, chance, active_object_count, min_height, max_height, day_toggle, on_spawn)

Registers spawning behavior of mob.

Parameters:

name string Name of the animal/monster.
nodes table A list of nodes on top of which the mob can spawn.
neighbors table
- A list of nodes of which must be adjacent for the mob to spawn.
- Default: {“air”}
min_light int The minimum light value of node for spawn to occur.
max_light int The maximum light value of node for spawn to occur.
interval int Same as in minetest.register_abm (default: 30).
chance int Same as in minetest.register_abm.
active_object_count int
- Mob is only spawned if active_object_count_wider of ABM is <= this.
min_height int Minimum height at which mob will spawn.
max_height int Maximum height at which mob will spawn.
day_toggle bool
- Value descriptions:
  - true: Mob will spawn during daytime.
  - false: Mob will spawn during nighttime.
  - nil: Mob will spawn anytime.
on_spawn callback
- Called after mob has spawned.
- Usage: on_spawn = function(self, pos)

mobs:spawn (def)

Registers spawning behavior of mob.

Parameters:

def table See: mobs:spawn_specific, where parameters = table definition fields here.

mobs:register_arrow (name, def)

Registers an item that mob can use for ranged attack.

Parameters:

name string Name of throwable item.
def table See: mobs:register_rrow.def

mobs:register_egg (name, description, background, addegg, no_creative)

Registers a mob spawning egg.

The “egg” is an item that is held in inventory when a mob is captured/tamed.

Parameters:

name string Name of the mob to be spawned (e.g. “mob:sheep”).
description string name of the egg displayed in inventory (e.g. “Spawn Sheep”).
background string Texture displayed for egg in inventory.
addegg int Adds an egg image in front of your texture (1=yes, 0=no).
no_creative bool
- If true, spawn egg is not available in creative mode.
- Useful for destructive mobs like Dungeon Master.

mobs:boom (self, pos, radius)

Generates a self-destruct explosion from mob.

Explosion removes nodes in a specific radius & damages any entity caught inside the blast radius. Protection will limit node destruction but not entity damage.

Parameters:

self The mob entity.
pos table Position of explosion centre.
radius int Radius of explosion reach (typically set to 3).

mobs:explosion (pos, radius)

Generates a self-destruct explosion from mob.

DEPRECATED: Use mobs:boom.

Parameters:

pos table Same as mobs:boom.
radius int Same as mobs:boom.

mobs:capture_mob (self, clicker, chance_hand, chance_net, chance_lasso, force_take, replacewith)

Attempts to capture a mob & place in inventory.

This function is generally called inside the on_rightclick section of the mob api code. It provides a chance of capturing the mob by hand, or by using the net or magic lasso items. It can also have the player take the mob by force, even if tamed, & replace it with another item entirely.

Parameters:

self Mob information.
clicker Player information.
chance_hand int
- Chance of capturing mob by hand (0 to disable).
- Min: 0
- Max: 100
chance_net int
- Chance of capturing mob with net (0 to disable).
- Min: 0
- Max: 100
chance_lasso int
- Chance of capturing mob with magic lasso (0 to disable).
- Min: 0
- Max: 100
force_take bool If true, takes mob by force even if tamed by another player.
replacewith string On capture, place this item in inventory instead of mob (overrides new mob eggs with saved information).

mobs:feed_tame (table, clicker, feed_count, breed, tame)

Feed & tame mobs.

This function allows the mob to be fed the item(s) inside the self.follow table a set number of times in order to be tamed or bred as a result. Returns true when mob is fed with item it likes.

Parameters:

table self Mob information.
clicker Player information.
feed_count int Number of times mob must be fed to tame or breed.
breed bool If true, mob can be bred & a child created afterwards.
tame bool If true, mob can be tamed so player can pick them up.

Returns:

bool

true

mobs:protect (self, clicker)

Protects mobs from being attacked by other players.

This function can be used to right-click any tamed mob with mobs:protector item. This will protect the mob from harm inside a protected area from other players.

Parameters:

self Mob information.
clicker Player information.

Returns:

bool

true

mobs:protector

mobs:attach (self, player)

Attaches a player to the mob so it can be ridden.

Parameters:

self Mob information.
player Player information.

mobs:detach (player, offset)

Detaches player from riding mob.

Detaches the player currently riding a mob to an offset position.

Parameters:

player Player information.
offset table Position table containing offset values.

mobs:drive (self, move_animation, stand_animation, can_fly, dtime)

Controls mob movement with player riding.

Allows an attached player to move the mob around & animate it at same time.

NOTE: Animation names are from the pre-defined animation lists inside mob registry without extensions.

Parameters:

self Mob information.
move_animation string Pre-defined movement state animation (e.g. “walk”, “fly”, etc.).
stand_animation string Pre-defined standing state animation (e.g. “stand”, “blink”, etc.).
can_fly bool If true, jump & sneak controls will allow mob to fly up & down.
dtime Tick time used inside function.

mobs:fly (self, dtime, speed, can_shoot, arrow_entity, move_animation, stand_animation)

Controls mob flight with player riding.

Allows the attached player to fly the mob around using directional controls.

Parameters:

self Mob information.
dtime Tick time used inside function.
speed int Speed at which mob moves in flight.
can_shoot bool If true, player can fire arrow with mob (sneak & left mouse button fires).
arrow_entity string Name of item used for firing ranged attack.
move_animation string Pre-defined movement state animation (e.g. “walk”, “fly”, etc.).
stand_animation string Pre-defined standing state animation (e.g. “stand”, “blink”, etc.).

Parameters:

self Mob information.
name string
- Name of animation (e.g. “stand”, “walk”, “fly”, etc.).
- Default: “stand”

Function Definition Tables

mobs:register_mob.def

Definition table for mobs:register_mob.

Fields:

type string
- The type of mob.
- Possible values:
  - monster: Attacks players & other mob types.
  - animal: Tend to wander around & can attack when hit first.
  - npc: Behaviour is similar to animal.
hp_min int Minimum health.
hp_max int Maximum health (health is randomly selected between hp_min & hp_max).
physical bool Same as in minetest.register_entity.
collisionbox table Same as in minetest.register_entity.
visual string Same as in minetest.register_entity.
visual_size table Same as in minetest.register_entity.
rotate int Sets mob rotation (0=front, 90=side, 180=back, 270=other side).
drawtype string “front” or “side” (DEPRECATED: replaced with rotate).

GRAPHICS
textures table Same as in minetest.register_entity. Although, you can add multiple lines for random textures (e.g. {{“texture1.png”},{“texture2.png”}}).
gotten_texture Alternative texture for when self.gotten value is set to true (used for shearing sheep).
child_texture Texture of mod for when self.child is set to true.
mesh string Same as in minetest.register_entity.
gotten_mesh Alternative mesh for when self.gotten is true (used for sheep).
blood_amount int Number of blood droplets that appear when hit.
blood_texture string
- Texture of blood droplets.
- Default: “mobs_blood.png”
SOUND
makes_footstep_sound bool Same as in minetest.register_entity.
sounds table
- Sounds that will be heard from mob.
- Fields:
  - random: Random sounds during gameplay.
  - war_cry: Played when starting to attack player.
  - attack: Played while attacking player.
  - shoot_attack: Played while attacking player from range.
  - damage: Played when mob is hit.
  - death: Played when mob dies.
  - jump: Played when jumping.
  - explode: Played when explodes.
  - distance: (int) Maximum distance sounds are heard from (default: 10).
BEHAVIOUR
follow Items that, when held, will cause mob to follow player. Can be single string (e.g. “default:apple”) or a table (e.g. {“default:apple”, “default:diamond”}). These can also be used to feed & tame mob.
view_range int The range at which mob will follow or attack player or other entities.
walk_chance int
- Chance of mob walking around (Set to 0 for jumping mob only).
- Min: 0
- Max: 100
walk_velocity Speed of mob when walking around.
run_velocity Speed of mob when running or attacking another entity.
stepheight float Minimum node height mob can walk onto without jumping (default: 0.6).
jump bool If true, mob can jump.
jump_height int
- Height mob can jump (Set to 0 to disable jump).
- Default: 6
fly bool If true, mob can fly through designated node types from fly_in (used for swimming mobs as well).
fly_in Node name in which mob can fly (e.g. “air” for birds, & “default:water_source” for fish).
water_damage Damage per second mob incurs while in water.
lava_damage Damage per second mob incurs while in lava.
light_damage Damage per second mob incurs while in light.
suffocation Health value mob loses when inside a solid node.
fall_damage bool If true, mob will sustain damage when falling from heights.
fall_speed int
- Maximum falling velocity of mob.
- Max: -2
- Default: -10
fear_height int
- Any drop over this value will make mob turn back (set to 0 to disable).
- Default: 0
on_die callback
- Called when mob dies.
- Usage: on_die = function(self, pos)
- Parameters:
  - self:
  - pos:
floats int Set to 1 to float in water, 0 to sink.
on_rightclick callback Same as in minetest.register_entity.
pathfinding int
- Use pathfinder feature.
- Options:
  - 0: Disable.
  - 1: Use pathfinder to locate player.
  - 2: Additionaly allow build/break (only works with dogfight attack).
COMBAT
passive bool Mob will not defend itself (set to false to attack).
docile_by_day bool When true, mob will not attack during daylight hours unless provoked.
attacks_monsters bool Will attack nearby monsters (usually used for NPCs).
group_attack bool If true, Will defend nearby mobs of same type from attack.
owner_loyal bool If true, owned mobs will attack any monsters you punch.
attack_animals bool If true, will attack animals as well as players & NPCs.
specific_attack table Table of entity names that monsters can attack (e.g. {“player”, “mobs_animal:chicken”}).
runaway bool If true, mob will retreat when punched.
damage The damage mob inflicts per melee attack.
recovery_time float
- How much time, in seconds, from when mob is hit until it recovers.
- Default: 0.5
knock_back int
- Strength of knock-back when mob is hit.
- Default: 3

immune_to table

A table holding special tool/item names & damage they incur.

Example:

immune_to = {
   {“default:sword_wood”, 0},  -- immune to sword
   {“default:gold_lump”, -10},  -- gold lump heals
}

drops table
- List of tables with the following fields:
  - name: (string) Item name (e.g. “default:stone”).
  - chance: (int) The inverted chance (same as in abm) to get the item.
  - min: (int) Minimum number of items dropped at one time.
  - max: (int) Maximum number of items dropped at one time.
- Example:
```
drops = {
   {name=‘default:stone’, chance=2, min=5, max=5},
   {name=‘default:mese_crystal’, chance=100, min=1, max=3},
   {name=‘mobs:meat’, chance=1, min=2, max=5},
}
```
armor int Armor strength (100 being normal). Lower numbers mean stronger armor while higher numbers make it weaker (weird, I know. But compatible with simple mobs).
attack_type string
- The attack type of a mob.
- Options:
  - dogfight: Follows player in range & attacks when in reach.
  - shoot: Shoots defined arrows when player is within range.
  - explode: Follows player & will flash & explode when in reach.
  - dogshoot: Shoots arrows when in range & one on one attack when in reach.
dogshoot_switch Allows switching between shoot & dogfight modes inside dogshoot using timer (1 = shoot, 2 = dogfight).
dogshoot_count_max int Number of seconds before switching to dogfight mode.
dogshoot_count2_max int Number of seconds before switching back to shoot mode.
custom_attack callback
- When set, this function is called instead of the normal mob melee attack.
- Usage: custom_attack = function(self, to_attack)
- Parameters:
  - self:
  - to_attack:
double_melee_attack bool If false, API will choose randomly between punch & punch2 attack animations.
on_blast callback
- Called when an explosion happens near mob using TNT functions.
- Usage: on_blast = function(object, damage)
- Parameters:
  - object:
  - damage:
- Returns: (do_damage, do_knockback, drops)
explosion_radius int Radius of explosion attack (default: 1).
arrow string If attack_type is “shoot” or “dogshoot”, then the entity name of a pre-defined arrow is required (see mobs:register_arrow).
shoot_interval The minimum shoot interval.
shoot_offset +/- value to position arrow/fireball when fired.
reach int
- Range at which mob will shoot (default: 3).
EATING

Mobs can look for specific nodes as they walk & replace them to mimic eating.
on_replace callback
- Called when mob is about to replace a node.
- Usage: on_replace(self, pos, oldnode, newnode)
- Parameters:
  - self: ObjectRef of mob.
  - pos: Position of node to replace.
  - oldnode: Current node.
  - newnode: What the node will become after replacing.
- Returns: (bool) If false is returned, the mob will not replace the node.
- By default, replacing sets self.gotten to true & resets the object properties.
replace_what table
- Group if items to replace (e.g. {“farming:wheat_8”, “farming:carrot_8”}).
- Updated to use tables for what, with an y_offset. Example:
```
replace_what = {
   {“group:grass”, “air”, 0}, {“default:dirt_with_grass”, “default:dirt”, -1},
}
```
replace_with string Replace with what (e.g. “air”, or in the case of chickens “mobs:egg”).
replace_rate int How random should the replace rate be (typically 10).
replace_offset +/- value to check specific node to replace.

ANIMATION

Mob animation comes in three parts; start_frame, end_frame, & frame_speed, which can be added to the mob definition under pre-defined mob animation names like:

“*_loop” bool value to determine if any set animation loops (e.g. die_loop = false). •

Defaults to true if not set. •

Also “speed_normal” for compatibility with older mobs for animation speed (DEPRECATED). •
animation table
- Animation ranges & speed of the model.
- Fields:
  - stand_start, stand_end, stand_speed: When mob stands still.
  - walk_start, walk_end, walk_speed: When mob walks.
  - run_start, run_end, run_speed: When mob runs.
  - fly_start, fly_end, fly_speed: When mob flies.
  - punch_start, punch_end, punch_speed: When mob attacks.
  - punch2_start, punch2_end, punch2_speed: When mob attacks (alternative).
  - die_start, die_end, die_speed: When mob dies.

mobs:register_arrow.def

Definition table for mobs:register_arrow.

Fields:

visual string Same as in minetest.register_entity
visual_size size Same as in minetest.register_entity
textures table Same as in minetest.register_entity
velocity Velocity of the arrow.
drop bool If true, any arrows hitting a node will drop as item.
hit_player callback
- Called when the arrow hits a player (should hurt the player).
- Usage: hit_player = function(self, player)
- Parameters:
  - self:
  - player
hit_mob callback
- Called when the arrow hits a mob (should hurt the mob).
- Usage: hit_mobs(self, player)
- Parameters:
  - self:
  - player:
hit_node callback
- Called when the arrow hits a node.
- Usage: hit_node = function(self, pos, node)
- Parameters:
  - self:
  - pos:
  - node:
tail int When set to 1 adds a trail or tail to mob arrows.
tail_texture string Texture used for tail effect.
tail_size int Has size for tail texture (default: between 5 & 10).
expire float How long tail appears for (default: 0.25).
glow int
- Value for how brightly tail glows.
- Min: 0
- Max: 10
- Default: 0
rotate int Degrees to rotate arrow.
on_step callback
- A custom function when arrow is active.
- Default: nil

Notes

Variables

Required variables.

These variables need to be set before using the mobs functions:

self.v2: Toggle switch used to define following values for the first time.
self.max_speed_forward: Max speed mob can move forward.
self.max_speed_reverse: Max speed mob can move backwards.
self.accel: Acceleration speed.
self.terrain_type: Integer containing terrain mob can walk on:
- 1: water
- 2: water/land???
- 3: land
self.driver_attach_at: Position offset for attaching player to mob.
self.driver_eye_offset: Position offset for attached player view.
self.driver_scale: Sets driver scale for mobs larger than {x=1, y=1}.

Examples

Horse

Rideable horse.

Example of how to register a rideable horse:

 mobs:register_mob(“mob_horse:horse”, {
     type = “animal”,
     visual = “mesh”,
     visual_size = {x = 1.20, y = 1.20},
     mesh = “mobs_horse.x”,
     collisionbox = {-0.4, -0.01, -0.4, 0.4, 1.25, 0.4},
     animation = {
         speed_normal = 15,
         speed_run = 30,
         stand_start = 25,
         stand_end = 75,
         walk_start = 75,
         walk_end = 100,
         run_start = 75,
         run_end = 100,
     },
     textures = {
         {“mobs_horse.png”},
         {“mobs_horsepeg.png”},
         {“mobs_horseara.png”}
     },
     fear_height = 3,
     runaway = true,
     fly = false,
     walk_chance = 60,
     view_range = 5,
     follow = {“farming:wheat”},
     passive = true,
     hp_min = 12,
     hp_max = 16,
     armor = 200,
     lava_damage = 5,
     fall_damage = 5,
     water_damage = 1,
     makes_footstep_sound = true,
     drops = {
         {name = “mobs:meat_raw”, chance = 1, min = 2, max = 3}
     },
     do_custom = function(self, dtime)
         -- set needed values if not already present
         if not self.v2 then
         -- elf.v2 = 0
             self.max_speed_forward = 6
             self.max_speed_reverse = 2
             self.accel = 6
             self.terrain_type = 3
             self.driver_attach_at = {x = 0, y = 20, z = -2}
             self.driver_eye_offset = {x = 0, y = 3, z = 0}
             self.driver_scale = {x = 1, y = 1}
         end
         -- if driver present allow control of horse
         if self.driver then
             mobs.drive(self, “walk”, “stand”, false, dtime)
            return false -- skip rest of mob functions
         end
          return true
     end,
     on_die = function(self, pos)
         -- drop saddle when horse is killed while riding
         -- also detach from horse properly
         if self.driver then
             minetest.add_item(pos, “mobs:saddle”)
             mobs.detach(self.driver, {x = 1, y = 0, z = 1})
         end
     end,
     on_rightclick = function(self, clicker)
         -- make sure player is clicking
         if not clicker or not clicker:is_player() then
             return
         end
         -- feed, tame or heal horse
         if mobs:feed_tame(self, clicker, 10, true, true) then
             return
         end
         -- make sure tamed horse is being clicked by owner only
         if self.tamed & self.owner == clicker:get_player_name() then
             local inv = clicker:get_inventory()
             -- detatch player already riding horse
             if self.driver & clicker == self.driver then
                 mobs.detach(clicker, {x = 1, y = 0, z = 1})
                 -- add saddle back to inventory
                 if inv:room_for_item(“main”, “mobs:saddle”) then
                     inv:add_item(“main”, “mobs:saddle”)
                 else
                     minetest.add_item(clicker.getpos(), “mobs:saddle”)
                 end
             -- attach player to horse
             elseif not self.driver
             & clicker:get_wielded_item():get_name() == “mobs:saddle” then
                 self.object:set_properties({stepheight = 1.1})
                 mobs.attach(self, clicker)
                 -- take saddle from inventory
                 inv:remove_item(“main”, “mobs:saddle”)
             end
         end
         -- used to capture horse with magic lasso
         mobs:capture_mob(self, clicker, 0, 0, 80, false, nil)
     end
 })

Mobs Redo

Contents

Modules

Module `api`

Configuration Settings Used by this Mod

Functions

Function Definition Tables

Notes

Examples

Configuration Settings Used by this Mod

Functions

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Parameters:

Parameters:

Parameters:

See also:

Parameters:

Function Definition Tables

Fields:

Fields:

Notes

Examples

Mobs Redo

Contents

Modules

Module api

Configuration Settings Used by this Mod

Functions

Function Definition Tables

Notes

Examples

Configuration Settings Used by this Mod

Functions

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Parameters:

Parameters:

Parameters:

See also:

Parameters:

Function Definition Tables

Fields:

Fields:

Notes

Examples

Module `api`