2 Mobs Redo: MineClone 2 Edition
4 ==============================
6 Welcome to the world of mobs in Minetest and hopefully an easy guide to defining
7 your own mobs and having them appear in your worlds.
13 To register a mob and have it ready for use requires the following function:
15 mobs:register_mob(name, definition)
17 The 'name' of a mob usually starts with the mod name it's running from followed
20 "mobs_monster:sand_monster" or "mymod:totally_awesome_beast"
22 ... and the 'definition' is a table which holds all of the settings and
23 functions needed for the mob to work properly which contains the following:
25 'nametag' contains the name which is shown above mob.
26 'type' holds the type of mob that inhabits your world e.g.
27 "animal" usually docile and walking around.
28 "monster" attacks player or npc on sight.
29 "npc" walk around and will defend themselves if hit first, they
31 'hp_min' has the minimum health value the mob can spawn with.
32 'hp_max' has the maximum health value the mob can spawn with.
33 'armor' holds strength of mob, 100 is normal, lower is more powerful
34 and needs more hits and better weapons to kill.
35 'passive' when true allows animals to defend themselves when hit,
36 otherwise they amble onwards.
37 'walk_velocity' is the speed that your mob can walk around.
38 'run_velocity' is the speed your mob can run with, usually when attacking.
39 'walk_chance' has a 0-100 chance value your mob will walk from standing,
40 set to 0 for jumping mobs only.
41 'jump' when true allows your mob to jump updwards.
42 'jump_height' holds the height your mob can jump, 0 to disable jumping.
43 'stepheight' height of a block that your mob can easily walk up onto,
45 'fly' when true allows your mob to fly around instead of walking.
46 'fly_in' holds the node name that the mob flies (or swims) around
47 in e.g. "air" or "default:water_source".
48 'runaway' if true causes animals to turn and run away when hit.
49 'view_range' how many nodes in distance the mob can see a player.
50 'damage' how many health points the mob does to a player or another
51 mob when melee attacking.
52 'knock_back' when true has mobs falling backwards when hit, the greater
53 the damage the more they move back.
54 'fear_height' is how high a cliff or edge has to be before the mob stops
55 walking, 0 to turn off height fear.
56 'fall_speed' has the maximum speed the mob can fall at, default is -10.
57 'fall_damage' when true causes falling to inflict damage.
58 'water_damage' holds the damage per second infliced to mobs when standing in
60 'lava_damage' holds the damage per second inflicted to mobs when standing
62 'light_damage' holds the damage per second inflicted to mobs when it's too
63 bright (above 13 light).
64 'suffocation' when true causes mobs to suffocate inside solid blocks.
65 'floats' when set to 1 mob will float in water, 0 has them sink.
66 'follow' mobs follow player when holding any of the items which appear
67 on this table, the same items can be fed to a mob to tame or
68 breed e.g. {"farming:wheat", "default:apple"}
70 'reach' is how far the mob can attack player when standing
71 nearby, default is 3 nodes.
72 'docile_by_day' when true has mobs wandering around during daylight
73 hours and only attacking player at night or when
75 'attacks_monsters' when true has npc's attacking monsters or not.
76 'attack_animals' when true will have monsters attacking animals.
77 'owner_loyal' when true will have tamed mobs attack anything player
79 'group_attack' when true has same mob type grouping together to attack
81 'attack_type' tells the api what a mob does when attacking the player
83 'dogfight' is a melee attack when player is within mob reach.
84 'shoot' has mob shoot pre-defined arrows at player when inside
86 'dogshoot' has melee attack when inside reach and shoot attack
87 when inside view_range.
88 'explode' causes mob to stop and explode when inside reach.
89 'explosion_radius' the radius of explosion node destruction,
91 'explosion_damage_radius' the radius of explosion entity & player damage,
92 defaults to explosion_radius * 2
93 'explosion_timer' number of seconds before mob explodes while its target
94 is still inside reach or explosion_damage_radius,
96 'allow_fuse_reset' Allow 'explode' attack_type to reset fuse and resume
97 chasing if target leaves the blast radius or line of
98 sight. Defaults to true.
99 'stop_to_explode' When set to true (default), mob must stop and wait for
100 explosion_timer in order to explode. If false, mob will
102 'arrow' holds the pre-defined arrow object to shoot when
104 'dogshoot_switch' allows switching between attack types by using timers
105 (1 for shoot, 2 for dogfight)
106 'dogshoot_count_max' contains how many seconds before switching from
108 'dogshoot_count2_max' contains how many seconds before switching from shoot
110 'shoot_interval' has the number of seconds between shots.
111 'shoot_offset' holds the y position added as to where the
112 arrow/fireball appears on mob.
113 'specific_attack' has a table of entity names that mob can also attack
114 e.g. {"player", "mobs_animal:chicken"}.
115 'runaway_from' contains a table with mob names to run away from, add
116 "player" to list to runaway from player also.
117 'blood_amount' contains the number of blood droplets to appear when
119 'blood_texture' has the texture name to use for droplets e.g.
120 "mobs_blood.png", or table {"blood1.png", "blood2.png"}
121 'pathfinding' set to 1 for mobs to use pathfinder feature to locate
122 player, set to 2 so they can build/break also (only
123 works with dogfight attack and when 'mobs_griefing'
124 in minetest.conf is not false).
125 'immune_to' is a table that holds specific damage when being hit by
127 {"default:sword_wood", 0} -- causes no damage.
128 {"default:gold_lump", -10} -- heals by 10 health points.
129 {"default:coal_block", 20} -- 20 damage when hit on head with coal blocks.
131 'makes_footstep_sound' when true you can hear mobs walking.
132 'sounds' this is a table with sounds of the mob
133 'distance' maximum distance sounds can be heard, default is 10.
134 'random' played randomly from time to time.
135 also played when mob is frustrated for not finding the path.
136 also played for overfeeding animal.
137 'war_cry' what you hear when mob starts to attack player.
138 'attack' what you hear when being attacked.
139 'shoot_attack' sound played when mob shoots.
140 'damage' sound heard when mob is hurt.
141 'death' played when mob is killed.
142 'jump' played when mob jumps. There's a built-in cooloff timer to avoid sound spam
143 'fuse' sound played when mob explode timer starts.
144 'explode' sound played when mob explodes.
146 'drops' table of items that are dropped when mob is killed, fields are:
147 'name' name of item to drop.
148 'chance' chance of drop, 1 for always, 2 for 1-in-2 chance etc.
149 'min' minimum number of items dropped.
150 'max' maximum number of items dropped.
152 'visual' holds the look of the mob you wish to create:
153 'cube' looks like a normal node
154 'sprite' sprite which looks same from all angles.
155 'upright_sprite' flat model standing upright.
156 'wielditem' how it looks when player holds it in hand.
157 'mesh' uses separate object file to define mob.
158 'visual_size' has the size of the mob, defaults to {x = 1, y = 1}
159 'collisionbox' has the box in which mob can be interacted with the
160 world e.g. {-0.5, -0.5, -0.5, 0.5, 0.5, 0.5}
161 'selectionbox' has the box in which player can interact with mob
162 'textures' holds a table list of textures to be used for mob, or you
163 could use multiple lists inside another table for random
164 selection e.g. { {"texture1.png"}, {"texture2.png"} }
165 'child_texture' holds the texture table for when baby mobs are used.
166 'gotten_texture' holds the texture table for when self.gotten value is
167 true, used for milking cows or shearing sheep.
168 'mesh' holds the name of the external object used for mob model
170 'gotten_mesh" holds the name of the external object used for when
171 self.gotten is true for mobs.
172 'rotate' custom model rotation, 0 = front, 90 = side, 180 = back,
174 'double_melee_attack' when true has the api choose between 'punch' and
177 'animation' holds a table containing animation names and settings for use with mesh models:
178 'stand_start' start frame for when mob stands still.
179 'stand_end' end frame of stand animation.
180 'stand_speed' speed of animation in frames per second.
181 'walk_start' when mob is walking around.
184 'run_start' when a mob runs or attacks.
187 'fly_start' when a mob is flying.
190 'punch_start' when a mob melee attacks.
193 'punch2_start' alternative melee attack animation.
196 'shoot_start' shooting animation.
199 'die_start' death animation
202 'die_loop' when set to false stops the animation looping.
204 Using '_loop = false' setting will stop any of the above animations from
207 'speed_normal' is used for animation speed for compatibility with some
211 MineClone 2 extensions:
213 'ignores_nametag' if true, mob cannot be named by nametag
214 'rain_damage' damage per second if mob is standing in rain (default: 0)
215 'sunlight_damage' holds the damage per second inflicted to mobs when they
216 are in direct sunlight
221 Mobs can look around for specific nodes as they walk and replace them to mimic
224 'replace_what' group of items to replace e.g.
225 {"farming:wheat_8", "farming:carrot_8"}
226 or you can use the specific options of what, with and
227 y offset by using this instead:
229 {"group:grass", "air", 0},
230 {"default:dirt_with_grass", "default:dirt", -1}
232 'replace_with' replace with what e.g. "air" or in chickens case "mobs:egg"
233 'replace_rate' how random should the replace rate be (typically 10)
234 'replace_offset' +/- value to check specific node to replace
236 'on_replace(self, pos, oldnode, newnode)' is called when mob is about to
238 'self' ObjectRef of mob
239 'pos' Position of node to replace
240 'oldnode' Current node
241 'newnode' What the node will become after replacing
243 If false is returned, the mob will not replace the node.
245 By default, replacing sets self.gotten to true and resets the object
249 Custom Definition Functions
250 ---------------------------
252 Along with the above mob registry settings we can also use custom functions to
253 enhance mob functionality and have them do many interesting things:
255 'on_die' a function that is called when the mob is killed the
256 parameters are (self, pos)
257 'on_rightclick' its same as in minetest.register_entity()
258 'on_blast' is called when an explosion happens near mob when using TNT
259 functions, parameters are (object, damage) and returns
260 (do_damage, do_knockback, drops)
261 'on_spawn' is a custom function that runs on mob spawn with 'self' as
262 variable, return true at end of function to run only once.
263 'after_activate' is a custom function that runs once mob has been activated
264 with these paramaters (self, staticdata, def, dtime)
265 'on_breed' called when two similar mobs breed, paramaters are
266 (parent1, parent2) objects, return false to stop child from
267 being resized and owner/tamed flags and child textures being
268 applied. Function itself must spawn new child mob.
269 'on_grown' is called when a child mob has grown up, only paramater is
271 'do_punch' called when mob is punched with paramaters (self, hitter,
272 time_from_last_punch, tool_capabilities, direction), return
273 false to stop punch damage and knockback from taking place.
274 'custom_attack' when set this function is called instead of the normal mob
275 melee attack, parameters are (self, to_attack).
276 'on_die' a function that is called when mob is killed (self, pos)
277 'do_custom' a custom function that is called every tick while mob is
278 active and which has access to all of the self.* variables
279 e.g. (self.health for health or self.standing_in for node
280 status), return with 'false' to skip remainder of mob API.
286 The mob api also has some preset variables and functions that it will remember
289 'self.health' contains current health of mob (cannot exceed
291 'self.texture_list' contains list of all mob textures
292 'self.child_texture' contains mob child texture when growing up
293 'self.base_texture' contains current skin texture which was randomly
294 selected from textures list
295 'self.gotten' this is used for obtaining milk from cow and wool from
297 'self.horny' when animal fed enough it is set to true and animal can
298 breed with same animal
299 'self.hornytimer' background timer that controls breeding functions and
300 mob childhood timings
301 'self.child' used for when breeding animals have child, will use
302 child_texture and be half size
303 'self.owner' string used to set owner of npc mobs, typically used for
305 'self.order' set to "follow" or "stand" so that npc will follow owner
307 'self.nametag' contains the name of the mob which it can show above
310 Spawning Mobs in World
311 ----------------------
313 mobs:register_spawn(name, nodes, max_light, min_light, chance,
314 active_object_count, max_height, day_toggle)
316 mobs:spawn_specfic(name, nodes, neighbors, min_light, max_light, interval,
317 chance, active_object_count, min_height, max_height, day_toggle, on_spawn)
319 These functions register a spawn algorithm for the mob. Without this function
320 the call the mobs won't spawn.
322 'name' is the name of the animal/monster
323 'nodes' is a list of nodenames on that the animal/monster can
325 'neighbors' is a list of nodenames on that the animal/monster will
326 spawn beside (default is {"air"} for
328 'max_light' is the maximum of light
329 'min_light' is the minimum of light
330 'interval' is same as in register_abm() (default is 30 for
332 'chance' is same as in register_abm()
333 'active_object_count' number of this type of mob to spawn at one time inside
335 'min_height' is the minimum height the mob can spawn
336 'max_height' is the maximum height the mob can spawn
337 'day_toggle' true for day spawning, false for night or nil for
339 'on_spawn' is a custom function which runs after mob has spawned
340 and gives self and pos values.
342 A simpler way to handle mob spawns has been added with the mobs:spawn(def)
343 command which uses above names to make settings clearer:
345 mobs:spawn({name = "mobs_monster:tree_monster",
346 nodes = {"group:leaves"},
351 For each mob that spawns with this function is a field in mobs.spawning_mobs.
352 It tells if the mob should spawn or not. Default is true. So other mods can
353 only use the API of this mod by disabling the spawning of the default mobs in
357 mobs:spawn_abm_check(pos, node, name)
359 This global function can be changed to contain additional checks for mobs to
360 spawn e.g. mobs that spawn only in specific areas and the like. By returning
361 true the mob will not spawn.
363 'pos' holds the position of the spawning mob
364 'node' contains the node the mob is spawning on top of
365 'name' is the name of the animal/monster
368 MineClone 2 extensions
369 ----------------------
371 mobs:spawn_child(pos, mob_type)
373 This function spawns a mob as a child. The parameter mob_type is the
374 entitystring of the new mob.
375 This function returns the mob on success and nil otherwise.
381 mobs:register_arrow(name, definition)
383 This function registers a arrow for mobs with the attack type shoot.
385 'name' is the name of the arrow
386 'definition' is a table with the following values:
387 'visual' same is in minetest.register_entity()
388 'visual_size' same is in minetest.register_entity()
389 'textures' same is in minetest.register_entity()
390 'velocity' the velocity of the arrow
391 'drop' if set to true any arrows hitting a node will drop as item
392 'hit_player' a function that is called when the arrow hits a player;
393 this function should hurt the player, the parameters are
395 'hit_mob' a function that is called when the arrow hits a mob;
396 this function should hurt the mob, the parameters are
398 'hit_node' a function that is called when the arrow hits a node, the
399 parameters are (self, pos, node)
400 'tail' when set to 1 adds a trail or tail to mob arrows
401 'tail_texture' texture string used for above effect
402 'tail_size' has size for above texture (defaults to between 5 and 10)
403 'expire' contains float value for how long tail appears for
405 'glow' has value for how brightly tail glows 1 to 10 (default is
407 'rotate' integer value in degrees to rotate arrow
408 'on_step' is a custom function when arrow is active, nil for
415 mobs:register_egg(name, description, background, addegg, no_creative)
417 This function registers a spawn egg which can be used by admin to properly spawn in a mob.
419 'name' this is the name of your new mob to spawn e.g. "mob:sheep"
420 'description' the name of the new egg you are creating e.g. "Spawn Sheep"
421 'background' the texture displayed for the egg in inventory
422 'addegg' would you like an egg image in front of your texture (1 = yes,
424 'no_creative' when set to true this stops spawn egg appearing in creative
425 mode for destructive mobs like Dungeon Masters.
431 mobs:explosion(pos, radius) -- DEPRECATED!!! use mobs:boom() instead
433 mobs:boom(self, pos, radius)
435 'pos' centre position of explosion
436 'radius' radius of explosion (typically set to 3)
438 This function generates an explosion which removes nodes in a specific radius
439 and damages any entity caught inside the blast radius. Protection will limit
440 node destruction but not entity damage.
446 mobs:capture_mob(...)
448 Does nothing and returns false.
450 This function is provided for compability with Mobs Redo for an attempt to
452 Mobs cannot be captured in MineClone 2.
454 In Mobs Redo, this is generally called inside the on_rightclick section of the mob
455 api code, it provides a chance of capturing the mob. See Mobs Redo documentation
458 Feeding and Taming/Breeding
459 ---------------------------
461 mobs:feed_tame(self, clicker, feed_count, breed, tame)
463 This function allows the mob to be fed the item inside self.follow be it apple,
464 wheat or whatever a set number of times and be tamed or bred as a result.
465 Will return true when mob is fed with item it likes.
467 'self' mob information
468 'clicker' player information
469 'feed_count' number of times mob must be fed to tame or breed
470 'breed' true or false stating if mob can be bred and a child created
472 'tame' true or false stating if mob can be tamed so player can pick
479 mobs:protect(self, clicker)
481 This function can be used to right-click any tamed mob with mobs:protector item,
482 this will protect the mob from harm inside of a protected area from other
483 players. Will return true when mob right-clicked with mobs:protector item.
485 'self' mob information
486 'clicker' player information
492 Mobs can now be ridden by players and the following shows its functions and
496 mobs:attach(self, player)
498 This function attaches a player to the mob so it can be ridden.
500 'self' mob information
501 'player' player information
504 mobs:detach(player, offset)
506 This function will detach the player currently riding a mob to an offset
509 'player' player information
510 'offset' position table containing offset values
513 mobs:drive(self, move_animation, stand_animation, can_fly, dtime)
515 This function allows an attached player to move the mob around and animate it at
518 'self' mob information
519 'move_animation' string containing movement animation e.g. "walk"
520 'stand_animation' string containing standing animation e.g. "stand"
521 'can_fly' if true then jump and sneak controls will allow mob to fly
523 'dtime' tick time used inside drive function
526 mobs:fly(self, dtime, speed, can_shoot, arrow_entity, move_animation, stand_animation)
528 This function allows an attached player to fly the mob around using directional
531 'self' mob information
532 'dtime' tick time used inside fly function
533 'speed' speed of flight
534 'can_shoot' true if mob can fire arrow (sneak and left mouse button
536 'arrow_entity' name of arrow entity used for firing
537 'move_animation' string containing name of pre-defined animation e.g. "walk"
539 'stand_animation' string containing name of pre-defined animation e.g.
540 "stand" or "blink" etc.
542 Note: animation names above are from the pre-defined animation lists inside mob
543 registry without extensions.
546 mobs:set_animation(self, name)
548 This function sets the current animation for mob, defaulting to "stand" if not
551 'self' mob information
552 'name' name of animation
555 Certain variables need to be set before using the above functions:
557 'self.v2' toggle switch used to define below values for the
559 'self.max_speed_forward' max speed mob can move forward
560 'self.max_speed_reverse' max speed mob can move backwards
561 'self.accel' acceleration speed
562 'self.terrain_type' integer containing terrain mob can walk on
563 (1 = water, 2 or 3 = land)
564 'self.driver_attach_at' position offset for attaching player to mob
565 'self.driver_eye_offset' position offset for attached player view
566 'self.driver_scale' sets driver scale for mobs larger than {x=1, y=1}
569 External Settings for "minetest.conf"
570 ------------------------------------
572 'enable_damage' if true monsters will attack players (default is true)
573 'only_peaceful_mobs' if true only animals will spawn in game (default is
575 'mobs_disable_blood' if false blood effects appear when mob is hit (default
577 'mobs_spawn_protected' if set to false then mobs will not spawn in protected
578 areas (default is true)
579 'remove_far_mobs' if true then untamed mobs that are outside players
580 visual range will be removed (default is true)
581 'mobname' can change specific mob chance rate (0 to disable) and
582 spawn number e.g. mobs_animal:cow = 1000,5
583 'mob_difficulty' sets difficulty level (health and hit damage
584 multiplied by this number), defaults to 1.0.
585 'mob_show_health' if false then punching mob will not show health status
587 'mob_chance_multiplier' multiplies chance of all mobs spawning and can be set
588 to 0.5 to have mobs spawn more or 2.0 to spawn less.
589 e.g. 1 in 7000 * 0.5 = 1 in 3500 so better odds of
591 'mobs_spawn' if false then mobs no longer spawn without spawner or
593 'mobs_drop_items' when false mobs no longer drop items when they die.
594 'mobs_griefing' when false mobs cannot break blocks when using either
595 pathfinding level 2, replace functions or mobs:boom
598 Players can override the spawn chance for each mob registered by adding a line
599 to their minetest.conf file with a new value, the lower the value the more each
602 mobs_animal:sheep_chance 11000
603 mobs_monster:sand_monster_chance 100
606 Rideable Horse Example Mob
607 --------------------------
609 mobs:register_mob("mob_horse:horse", {
612 visual_size = {x = 1.20, y = 1.20},
613 mesh = "mobs_horse.x",
614 collisionbox = {-0.4, -0.01, -0.4, 0.4, 1.25, 0.4},
627 {"mobs_horsepeg.png"},
628 {"mobs_horseara.png"}
635 follow = {"farming:wheat"},
643 makes_footstep_sound = true,
645 {name = "mobs:meat_raw", chance = 1, min = 2, max = 3}
648 random = "horse_neigh.ogg",
649 damage = "horse_whinney.ogg",
652 do_custom = function(self, dtime)
654 -- set needed values if not already present
657 self.max_speed_forward = 6
658 self.max_speed_reverse = 2
660 self.terrain_type = 3
661 self.driver_attach_at = {x = 0, y = 20, z = -2}
662 self.driver_eye_offset = {x = 0, y = 3, z = 0}
663 self.driver_scale = {x = 1, y = 1}
666 -- if driver present allow control of horse
669 mobs.drive(self, "walk", "stand", false, dtime)
671 return false -- skip rest of mob functions
677 on_die = function(self, pos)
679 -- drop saddle when horse is killed while riding
680 -- also detach from horse properly
682 minetest.add_item(pos, "mobs:saddle")
683 mobs.detach(self.driver, {x = 1, y = 0, z = 1})
688 on_rightclick = function(self, clicker)
690 -- make sure player is clicking
691 if not clicker or not clicker:is_player() then
695 -- feed, tame or heal horse
696 if mobs:feed_tame(self, clicker, 10, true, true) then
700 -- make sure tamed horse is being clicked by owner only
701 if self.tamed and self.owner == clicker:get_player_name() then
703 local inv = clicker:get_inventory()
705 -- detatch player already riding horse
706 if self.driver and clicker == self.driver then
708 mobs.detach(clicker, {x = 1, y = 0, z = 1})
710 -- add saddle back to inventory
711 if inv:room_for_item("main", "mobs:saddle") then
712 inv:add_item("main", "mobs:saddle")
714 minetest.add_item(clicker.getpos(), "mobs:saddle")
717 -- attach player to horse
718 elseif not self.driver
719 and clicker:get_wielded_item():get_name() == "mobs:saddle" then
721 self.object:set_properties({stepheight = 1.1})
722 mobs.attach(self, clicker)
724 -- take saddle from inventory
725 inv:remove_item("main", "mobs:saddle")
729 -- used to capture horse with magic lasso
730 mobs:capture_mob(self, clicker, 0, 0, 80, false, nil)