api.txt 35 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820
  1. Mobs Redo API
  2. =============
  3. Welcome to the world of mobs in minetest and hopefully an easy guide to defining
  4. your own mobs and having them appear in your worlds.
  5. Registering Mobs
  6. ----------------
  7. To register a mob and have it ready for use requires the following function:
  8. mobs:register_mob(name, definition)
  9. The 'name' of a mob usually starts with the mod name it's running from followed
  10. by it's own name e.g.
  11. "mobs_monster:sand_monster" or "mymod:totally_awesome_beast"
  12. ... and the 'definition' is a table which holds all of the settings and
  13. functions needed for the mob to work properly which contains the following:
  14. 'nametag' contains the name which is shown above mob.
  15. 'type' holds the type of mob that inhabits your world e.g.
  16. "animal" usually docile and walking around.
  17. "monster" attacks player or npc on sight.
  18. "npc" walk around and will defend themselves if hit first, they
  19. kill monsters.
  20. 'hp_min' has the minimum health value the mob can spawn with.
  21. 'hp_max' has the maximum health value the mob can spawn with.
  22. 'armor' holds strength of mob, 100 is normal, lower is more powerful
  23. and needs more hits and better weapons to kill.
  24. 'passive' when true allows animals to defend themselves when hit,
  25. otherwise they amble onwards.
  26. 'walk_velocity' is the speed that your mob can walk around.
  27. 'run_velocity' is the speed your mob can run with, usually when attacking.
  28. 'stand_chance' has a 0-100 chance value your mob will stand from walking.
  29. 'walk_chance' has a 0-100 chance value your mob will walk from standing,
  30. set to 0 for jumping mobs only.
  31. 'jump' when true allows your mob to jump updwards.
  32. 'jump_height' holds the height your mob can jump, 0 to disable jumping.
  33. 'stepheight' height of a block that your mob can easily walk up onto,
  34. defaults to 1.1.
  35. 'fly' when true allows your mob to fly around instead of walking.
  36. 'fly_in' holds the node name that the mob flies (or swims) around
  37. in e.g. "air" or "default:water_source".
  38. 'keep_flying' when true mobs like birds no longer stop and stand.
  39. 'stay_near' when set allows mobs the chance to stay around certain nodes.
  40. 'nodes' string or table of nodes to stay nearby e.g. "farming:straw"
  41. 'chance' chance of searching for above node(s), default is 10.
  42. 'runaway' if true causes animals to turn and run away when hit.
  43. 'pushable' when true mobs can be pushed by player or other mobs.
  44. 'view_range' how many nodes in distance the mob can see a player.
  45. 'damage' how many health points the mob does to a player or another
  46. mob when melee attacking.
  47. 'knock_back' when true has mobs falling backwards when hit, the greater
  48. the damage the more they move back.
  49. 'fear_height' is how high a cliff or edge has to be before the mob stops
  50. walking, 0 to turn off height fear.
  51. 'fall_speed' has the maximum speed the mob can fall at, default is -10.
  52. 'fall_damage' when true causes falling to inflict damage.
  53. 'water_damage' holds the damage per second infliced to mobs when standing in
  54. water.
  55. 'lava_damage' holds the damage per second inflicted to mobs when standing
  56. in lava or fire or an ignition source.
  57. 'light_damage' holds the damage per second inflicted to mobs when light
  58. level is between the min and max values below
  59. 'light_damage_min' minimum light value when mob is affected (default: 14)
  60. 'light_damage_max' maximum light value when mob is affected (default: 15)
  61. 'suffocation' when > 0 mobs will suffocate inside solid blocks and will be
  62. hurt by the value given every second (0 to disable).
  63. 'floats' when set to 1 mob will float in water, 0 has them sink.
  64. 'follow' mobs follow player when holding any of the items which appear
  65. on this table, the same items can be fed to a mob to tame or
  66. breed e.g. {"farming:wheat", "default:apple"}
  67. 'reach' is how far the mob can attack player when standing
  68. nearby, default is 3 nodes.
  69. 'docile_by_day' when true has mobs wandering around during daylight
  70. hours and only attacking player at night or when
  71. provoked.
  72. 'attack_chance' 0 to 100 chance the mob will attack (default is 5).
  73. 'attack_monsters' when true mob will attack monsters.
  74. 'attack_animals' when true mob will attack animals.
  75. 'attack_npcs' when true mob will attack npcs within range.
  76. 'attack_players' when true mob will attack players nearby.
  77. 'owner_loyal' when true non-docile tamed mobs attack anything player
  78. punches when nearby.
  79. 'group_attack' when true has same mob type grouping together to attack
  80. offender.
  81. 'group_helper' string containing mob name that attacks alongside
  82. current mob when group attacking.
  83. mob is attacking in groups.
  84. 'attack_type' tells the api what a mob does when attacking the player
  85. or another mob:
  86. 'dogfight' is a melee attack when player is within mob reach.
  87. 'shoot' has mob shoot pre-defined arrows at player when inside
  88. view_range.
  89. 'dogshoot' has melee attack when inside reach and shoot attack
  90. when inside view_range.
  91. 'explode' causes mob to stop and explode when inside reach.
  92. 'explosion_radius' the radius of explosion node destruction,
  93. defaults to 1
  94. 'explosion_damage_radius' the radius of explosion entity & player damage,
  95. defaults to explosion_radius * 2
  96. 'explosion_timer' number of seconds before mob explodes while its target
  97. is still inside reach or explosion_damage_radius,
  98. defaults to 3.
  99. 'allow_fuse_reset' Allow 'explode' attack_type to reset fuse and resume
  100. chasing if target leaves the blast radius or line of
  101. sight. Defaults to true.
  102. 'stop_to_explode' When set to true (default), mob must stop and wait for
  103. explosion_timer in order to explode. If false, mob will
  104. continue chasing.
  105. 'arrow' holds the pre-defined arrow object to shoot when
  106. attacking.
  107. 'dogshoot_switch' allows switching between attack types by using timers
  108. (1 for shoot, 2 for dogfight)
  109. 'dogshoot_count_max' contains how many seconds before switching from
  110. dogfight to shoot.
  111. 'dogshoot_count2_max' contains how many seconds before switching from shoot
  112. to dogfight.
  113. 'shoot_interval' has the number of seconds between shots.
  114. 'shoot_offset' holds the y position added as to where the
  115. arrow/fireball appears on mob.
  116. 'specific_attack' has a table of entity names that mob can also attack
  117. e.g. {"player", "mobs_animal:chicken"}.
  118. 'runaway_from' contains a table with mob names to run away from, add
  119. "player" to list to runaway from player also.
  120. 'blood_amount' contains the number of blood droplets to appear when
  121. mob is hit.
  122. 'blood_texture' has the texture name to use for droplets e.g.
  123. "mobs_blood.png", or table {"blood1.png", "blood2.png"}
  124. 'pathfinding' set to 1 for mobs to use pathfinder feature to locate
  125. player, set to 2 so they can build/break also (only
  126. works with dogfight attack and when 'mobs_griefing'
  127. in minetest.conf is not false). Adding {unbreakable=1}
  128. to node groups stops them being broken by mobs.
  129. 'immune_to' is a table that holds specific damage when being hit by
  130. certain items e.g.
  131. {"default:sword_wood", 0} -- causes no damage.
  132. {"default:gold_lump", -10} -- heals by 10 health points.
  133. {"default:coal_block", 20} -- 20 damage when hit on head with coal blocks.
  134. {"all"} -- stops all weapons causing damage apart from those on list.
  135. 'makes_footstep_sound' when true you can hear mobs walking.
  136. 'sounds' this is a table with sounds of the mob
  137. 'distance' maximum distance sounds can be heard, default is 10.
  138. 'random' random sound that plays during gameplay.
  139. 'war_cry' what you hear when mob starts to attack player.
  140. 'attack' what you hear when being attacked.
  141. 'shoot_attack' sound played when mob shoots.
  142. 'damage' sound heard when mob is hurt.
  143. 'death' played when mob is killed.
  144. 'jump' played when mob jumps.
  145. 'fuse' sound played when mob explode timer starts.
  146. 'explode' sound played when mob explodes.
  147. 'drops' table of items that are dropped when mob is killed, fields are:
  148. 'name' name of item to drop.
  149. 'chance' chance of drop, 1 for always, 2 for 1-in-2 chance etc.
  150. 'min' minimum number of items dropped, set to 0 for rare drops.
  151. 'max' maximum number of items dropped.
  152. Note: If weapon has {fire=1} damage group set then cooked items will drop.
  153. Note2: A function can now be passed which can also return drops table, e.g.
  154. drops = function(pos)
  155. -- do something
  156. return { {name = "farming:bread"}, {name = "default:dirt", chance = 2} }
  157. end
  158. 'visual' holds the look of the mob you wish to create:
  159. 'cube' looks like a normal node
  160. 'sprite' sprite which looks same from all angles.
  161. 'upright_sprite' flat model standing upright.
  162. 'wielditem' how it looks when player holds it in hand.
  163. 'mesh' uses separate object file to define mob.
  164. 'visual_size' has the size of the mob, defaults to {x = 1, y = 1}
  165. 'collisionbox' has the box in which mob can be interacted with the
  166. world e.g. {-0.5, -0.5, -0.5, 0.5, 0.5, 0.5}
  167. 'selectionbox' has the box in which player can interact with mob
  168. 'textures' holds a table list of textures to be used for mob, or you
  169. could use multiple lists inside another table for random
  170. selection e.g. { {"texture1.png"}, {"texture2.png"} }
  171. 'child_texture' holds the texture table for when baby mobs are used.
  172. 'gotten_texture' holds the texture table for when self.gotten value is
  173. true, used for milking cows or shearing sheep.
  174. 'texture_mods' holds a string which overlays a texture on top of the
  175. mob texture e.g. "^saddle.png"
  176. 'mesh' holds the name of the external object used for mob model
  177. e.g. "mobs_cow.b3d"
  178. 'gotten_mesh" holds the name of the external object used for when
  179. self.gotten is true for mobs.
  180. 'rotate' custom model rotation, 0 = front, 90 = side, 180 = back,
  181. 270 = other side.
  182. 'glow' has mob glow without light source, 0 to 15 or nil to disable
  183. 'double_melee_attack' when true has the api choose between 'punch' and
  184. 'punch2' animations. [DEPRECATED]
  185. 'animation' holds a table containing animation names and settings for use with mesh models:
  186. 'stand_start' start frame for when mob stands still.
  187. 'stand_end' end frame of stand animation.
  188. 'stand_speed' speed of animation in frames per second.
  189. 'walk_start' when mob is walking around.
  190. 'walk_end'
  191. 'walk_speed'
  192. 'run_start' when a mob runs or attacks.
  193. 'run_end'
  194. 'run_speed'
  195. 'fly_start' when a mob is flying.
  196. 'fly_end'
  197. 'fly_speed'
  198. 'punch_start' when a mob melee attacks.
  199. 'punch_end'
  200. 'punch_speed'
  201. 'punch2_start' alternative melee attack animation.
  202. 'punch2_end'
  203. 'punch2_speed'
  204. 'shoot_start' shooting animation.
  205. 'shoot_end'
  206. 'shoot_speed'
  207. 'die_start' death animation
  208. 'die_end'
  209. 'die_speed'
  210. 'die_loop' when set to false stops the animation looping.
  211. Using '_loop = false' setting will stop any of the above animations from
  212. looping.
  213. 'speed_normal' is used for animation speed for compatibility with some
  214. older mobs.
  215. Note: Up to 5 different animations can be used per action e.g.
  216. stand_start, stand_end, stand1_start, stand1_end .. up to stand4_start
  217. Node Replacement
  218. ----------------
  219. Mobs can look around for specific nodes as they walk and replace them to mimic
  220. eating.
  221. 'replace_what' group of items to replace e.g.
  222. {"farming:wheat_8", "farming:carrot_8"}
  223. or you can use the specific options of what, with and
  224. y offset by using this instead:
  225. {
  226. {"group:grass", "air", 0},
  227. {"default:dirt_with_grass", "default:dirt", -1}
  228. }
  229. 'replace_with' replace with what e.g. "air" or in chickens case "mobs:egg"
  230. 'replace_rate' how random should the replace rate be (typically 10)
  231. 'replace_offset' +/- value to check specific node to replace
  232. 'on_replace(self, pos, oldnode, newnode)' is called when mob is about to
  233. replace a node.
  234. 'self' ObjectRef of mob
  235. 'pos' Position of node to replace
  236. 'oldnode' Current node
  237. 'newnode' What the node will become after replacing
  238. If false is returned, the mob will not replace the node.
  239. By default, replacing sets self.gotten to true and resets the object
  240. properties. (DEPRECATED, use on_replace to make changes).
  241. Custom Definition Functions
  242. ---------------------------
  243. Along with the above mob registry settings we can also use custom functions to
  244. enhance mob functionality and have them do many interesting things:
  245. 'on_die' a function that is called when the mob is killed the
  246. parameters are (self, pos)
  247. 'on_rightclick' its same as in minetest.register_entity()
  248. 'on_blast' is called when an explosion happens near mob when using TNT
  249. functions, parameters are (object, damage) and returns
  250. (do_damage, do_knockback, drops)
  251. 'on_spawn' is a custom function that runs on mob spawn with 'self' as
  252. variable, return true at end of function to run only once.
  253. 'after_activate' is a custom function that runs once mob has been activated
  254. with these paramaters (self, staticdata, def, dtime)
  255. 'on_breed' called when two similar mobs breed, paramaters are
  256. (parent1, parent2) objects, return false to stop child from
  257. being resized and owner/tamed flags and child textures being
  258. applied. Function itself must spawn new child mob.
  259. 'on_grown' is called when a child mob has grown up, only paramater is
  260. (self).
  261. 'do_punch' called when mob is punched with paramaters (self, hitter,
  262. time_from_last_punch, tool_capabilities, direction), return
  263. false to stop punch damage and knockback from taking place.
  264. 'custom_attack' when set this function is called instead of the normal mob
  265. melee attack, parameters are (self, to_attack) and if true
  266. is returned normal attack function continued.
  267. 'on_die' a function that is called when mob is killed (self, pos), also
  268. has access to self.cause_of_death table.
  269. 'do_custom' a custom function that is called every tick while mob is
  270. active and which has access to all of the self.* variables
  271. e.g. (self.health for health or self.standing_in for node
  272. status), return with 'false' to skip remainder of mob API.
  273. Internal Variables
  274. ------------------
  275. The mob api also has some preset variables and functions that it will remember
  276. for each mob.
  277. 'self.health' contains current health of mob (cannot exceed
  278. self.hp_max)
  279. 'self.texture_list' contains list of all mob textures
  280. 'self.child_texture' contains mob child texture when growing up
  281. 'self.base_texture' contains current skin texture which was randomly
  282. selected from textures list
  283. 'self.gotten' this is used for obtaining milk from cow and wool from
  284. sheep
  285. 'self.horny' when animal fed enough it is set to true and animal can
  286. breed with same animal
  287. 'self.hornytimer' background timer that controls breeding functions and
  288. mob childhood timings
  289. 'self.child' used for when breeding animals have child, will use
  290. child_texture and be half size
  291. 'self.owner' string used to set owner of npc mobs, typically used for
  292. dogs
  293. 'self.order' set to "follow" or "stand" so that npc will follow owner
  294. or stand it's ground
  295. 'self.nametag' contains the name of the mob which it can show above
  296. Adding Mobs in World
  297. --------------------
  298. mobs:add_mob(pos, {
  299. name = "mobs_animal:chicken",
  300. child = true,
  301. owner = "singleplayer",
  302. nametag = "Bessy",
  303. ignore_count = true -- ignores mob count per map area
  304. })
  305. Returns false if mob could not be added, returns mob object if spawned ok.
  306. Spawning Mobs in World
  307. ----------------------
  308. mobs:spawn({
  309. name = "mobs_monster:tree_monster",
  310. nodes = {"group:leaves"},
  311. max_light = 7,
  312. })
  313. Spawn functions require the following settings, some of which already have a
  314. default setting and can be omitted:
  315. 'name' is the name of the animal/monster
  316. 'nodes' is a list of nodenames on that the animal/monster can
  317. spawn on top of (defaults to {"group:dirt", "group:stone"}
  318. 'neighbors' is a list of nodenames on that the animal/monster will
  319. spawn beside (default is {"air"})
  320. 'interval' is same as in register_abm() (default is 30)
  321. 'chance' is same as in register_abm() (default is 5000)
  322. 'min_light' is the minimum light level (default is 0)
  323. 'max_light' is the maximum light (default is 15)
  324. 'min_height' is the minimum height a mob can spawn (default: -31000)
  325. 'max_height' is the maximum height a mob can spawn (default is 31000)
  326. 'active_object_count' number of this type of mob to spawn at one time inside
  327. map area (default is 1)
  328. 'day_toggle' true for day spawning, false for night or nil for
  329. anytime
  330. 'on_spawn' is a custom function which runs after mob has spawned
  331. and gives self and pos values.
  332. The older spawn functions are still active and working but have no defaults like
  333. the mobs:spawn, so it is recommended to use the above instead.
  334. mobs:register_spawn(name, nodes, max_light, min_light, chance,
  335. active_object_count, max_height, day_toggle)
  336. mobs:spawn_specfic(name, nodes, neighbors, min_light, max_light, interval,
  337. chance, active_object_count, min_height, max_height, day_toggle, on_spawn)
  338. A simpler way to handle mob spawns has been added with the mobs:spawn(def)
  339. command which uses above names to make settings clearer:
  340. For each mob that spawns with this function is a field in mobs.spawning_mobs.
  341. It tells if the mob should spawn or not. Default is true. So other mods can
  342. only use the API of this mod by disabling the spawning of the default mobs in
  343. this mod.
  344. mobs:spawn_abm_check(pos, node, name)
  345. This global function can be changed to contain additional checks for mobs to
  346. spawn e.g. mobs that spawn only in specific areas and the like. By returning
  347. true the mob will not spawn.
  348. 'pos' holds the position of the spawning mob
  349. 'node' contains the node the mob is spawning on top of
  350. 'name' is the name of the animal/monster
  351. Particle Effects
  352. ----------------
  353. mobs:effect(pos, amount, texture, min_size, max_size, radius, gravity, glow, fall)
  354. This function provides a quick way to spawn particles as an effect.
  355. 'pos' center position of particle effect.
  356. 'amount' how many particles.
  357. 'texture' texture filename to use for effect.
  358. 'min_size' smallest particle size.
  359. 'max_size' largest particle size.
  360. 'radius' how far particles spread outward from center.
  361. 'gravity' gravity applied to particles once they spawn.
  362. 'glow' number between 1 and 15 for glowing particles.
  363. 'fall' when true particles fall, false has them rising, nil has them scatter.
  364. Making Arrows
  365. -------------
  366. mobs:register_arrow(name, definition)
  367. This function registers a arrow for mobs with the attack type shoot.
  368. 'name' is the name of the arrow
  369. 'definition' is a table with the following values:
  370. 'visual' same is in minetest.register_entity()
  371. 'visual_size' same is in minetest.register_entity()
  372. 'textures' same is in minetest.register_entity()
  373. 'velocity' the velocity of the arrow
  374. 'drop' if set to true any arrows hitting a node will drop as item
  375. 'hit_player' a function that is called when the arrow hits a player;
  376. this function should hurt the player, the parameters are
  377. (self, player)
  378. 'hit_mob' a function that is called when the arrow hits a mob;
  379. this function should hurt the mob, the parameters are
  380. (self, player)
  381. 'hit_object' a function that is called when the arrow hits an object;
  382. this function parameters are (self, player)
  383. 'hit_node' a function that is called when the arrow hits a node, the
  384. parameters are (self, pos, node)
  385. 'tail' when set to 1 adds a trail or tail to mob arrows
  386. 'tail_texture' texture string used for above effect
  387. 'tail_size' has size for above texture (defaults to between 5 and 10)
  388. 'expire' contains float value for how long tail appears for
  389. (defaults to 0.25)
  390. 'glow' has value for how brightly tail glows 1 to 10 (default is
  391. 0 for no glow)
  392. 'rotate' integer value in degrees to rotate arrow
  393. 'on_step' is a custom function when arrow is active, nil for
  394. default.
  395. 'on_punch' is a custom function when arrow is punched, nil by default
  396. 'collisionbox' is hitbox table for arrow, {-.1,-.1,-.1,.1,.1,.1} by default.
  397. 'lifetime' contains float value for how many seconds arrow exists in
  398. world before being removed (default is 4.5 seconds).
  399. Spawn Eggs
  400. ----------
  401. mobs:register_egg(name, description, background, addegg, no_creative)
  402. This function registers a spawn egg which can be used to properly spawn in a mob.
  403. Animals are spawned as tamed unless sneak/shift is held while spawning.
  404. 'name' this is the name of your new mob to spawn e.g. "mob:sheep"
  405. 'description' the name of the new egg you are creating e.g. "Spawn Sheep"
  406. 'background' the texture displayed for the egg in inventory
  407. 'addegg' would you like an egg image in front of your texture (1 = yes,
  408. 0 = no)
  409. 'no_creative' when set to true this stops spawn egg appearing in creative
  410. mode for destructive mobs like Dungeon Masters.
  411. Explosion Function
  412. ------------------
  413. mobs:explosion(pos, radius) -- DEPRECATED!!! use mobs:boom() instead
  414. mobs:boom(self, pos, radius)
  415. 'self' mob entity
  416. 'pos' centre position of explosion
  417. 'radius' radius of explosion (typically set to 3)
  418. This function generates an explosion which removes nodes in a specific radius
  419. and damages any entity caught inside the blast radius. Protection will limit
  420. node destruction but not entity damage.
  421. Capturing Mobs
  422. --------------
  423. mobs:capture_mob(self, clicker, chance_hand, chance_net, chance_lasso,
  424. force_take, replacewith)
  425. This function is generally called inside the on_rightclick section of the mob
  426. api code, it provides a chance of capturing the mob by hand, using the net or
  427. lasso items, and can also have the player take the mob by force if tamed and
  428. replace with another item entirely.
  429. 'self' mob information
  430. 'clicker' player information
  431. 'chance_hand' chance of capturing mob by hand (1 to 100) 0 to disable
  432. 'chance_net' chance of capturing mob using net (1 to 100) 0 to disable
  433. 'chance_lasso' chance of capturing mob using magic lasso (1 to 100) 0 to
  434. disable
  435. 'force_take' take mob by force, even if tamed (true or false)
  436. 'replacewith' once captured replace mob with this item instead (overrides
  437. new mob eggs with saved information)
  438. mobs:force_capture(self, clicker)
  439. Same as above but does no checks, it simply captures any and all mobs and places
  440. inside a spawn egg containing all of the mob information.
  441. Feeding and Taming/Breeding
  442. ---------------------------
  443. mobs:feed_tame(self, clicker, feed_count, breed, tame)
  444. This function allows the mob to be fed the item inside self.follow be it apple,
  445. wheat or whatever a set number of times and be tamed or bred as a result.
  446. Will return true when mob is fed with item it likes.
  447. 'self' mob information
  448. 'clicker' player information
  449. 'feed_count' number of times mob must be fed to tame or breed
  450. 'breed' true or false stating if mob can be bred and a child created
  451. afterwards
  452. 'tame' true or false stating if mob can be tamed so player can pick
  453. them up
  454. Protecting Mobs
  455. ---------------
  456. mobs:protect(self, clicker)
  457. This function can be used to right-click any tamed mob with mobs:protector item,
  458. this will protect the mob from harm inside of a protected area from other
  459. players. Will return true when mob right-clicked with mobs:protector item.
  460. 'self' mob information
  461. 'clicker' player information
  462. Riding Mobs
  463. -----------
  464. Mobs can now be ridden by players and the following shows its functions and
  465. usage:
  466. mobs:attach(self, player)
  467. This function attaches a player to the mob so it can be ridden.
  468. 'self' mob information
  469. 'player' player information
  470. mobs:detach(player, offset)
  471. This function will detach the player currently riding a mob to an offset
  472. position.
  473. 'player' player information
  474. 'offset' position table containing offset values
  475. mobs:drive(self, move_animation, stand_animation, can_fly, dtime)
  476. This function allows an attached player to move the mob around and animate it at
  477. same time.
  478. 'self' mob information
  479. 'move_animation' string containing movement animation e.g. "walk"
  480. 'stand_animation' string containing standing animation e.g. "stand"
  481. 'can_fly' if true then jump and sneak controls will allow mob to fly
  482. up and down
  483. 'dtime' tick time used inside drive function
  484. mobs:fly(self, dtime, speed, can_shoot, arrow_entity, move_animation, stand_animation)
  485. This function allows an attached player to fly the mob around using directional
  486. controls.
  487. 'self' mob information
  488. 'dtime' tick time used inside fly function
  489. 'speed' speed of flight
  490. 'can_shoot' true if mob can fire arrow (sneak and left mouse button
  491. fires)
  492. 'arrow_entity' name of arrow entity used for firing
  493. 'move_animation' string containing name of pre-defined animation e.g. "walk"
  494. or "fly" etc.
  495. 'stand_animation' string containing name of pre-defined animation e.g.
  496. "stand" or "blink" etc.
  497. Note: animation names above are from the pre-defined animation lists inside mob
  498. registry without extensions.
  499. mobs:set_animation(self, name)
  500. This function sets the current animation for mob, defaulting to "stand" if not
  501. found.
  502. 'self' mob information
  503. 'name' name of animation
  504. Certain variables need to be set before using the above functions:
  505. 'self.v2' toggle switch used to define below values for the
  506. first time
  507. 'self.max_speed_forward' max speed mob can move forward
  508. 'self.max_speed_reverse' max speed mob can move backwards
  509. 'self.accel' acceleration speed
  510. 'self.terrain_type' integer containing terrain mob can walk on
  511. (1 = water, 2 or 3 = land)
  512. 'self.driver_attach_at' position offset for attaching player to mob
  513. 'self.driver_eye_offset' position offset for attached player view
  514. 'self.driver_scale' sets driver scale for mobs larger than {x=1, y=1}
  515. mobs:line_of_sight(self, pos1, pos2, stepsize) [DEPRECATED]
  516. This function is for use within the mobs definition for special use cases and
  517. returns true if a mob can see the player or victim.
  518. ...'self' mob information
  519. 'pos1' position of mob
  520. 'pos2' position of vistim or player
  521. 'stepsize' usually set to 1
  522. Use this instead:
  523. mob_class:line_of_sight(pos1, pos2, stepsize)
  524. External Settings for "minetest.conf"
  525. ------------------------------------
  526. 'enable_damage' if true monsters will attack players (default is true)
  527. 'only_peaceful_mobs' if true only animals will spawn in game (default is
  528. false)
  529. 'mobs_disable_blood' if false blood effects appear when mob is hit (default
  530. is false)
  531. 'mobs_spawn_protected' if set to false then mobs will not spawn in protected
  532. areas (default is true)
  533. 'remove_far_mobs' if true then untamed mobs that are outside players
  534. visual range will be removed (default is true)
  535. 'mobname' can change specific mob chance rate (0 to disable) and
  536. spawn number e.g. mobs_animal:cow = 1000,5
  537. 'mob_difficulty' sets difficulty level (health and hit damage
  538. multiplied by this number), defaults to 1.0.
  539. 'mob_show_health' if false then punching mob will not show health status
  540. (true by default)
  541. 'mob_chance_multiplier' multiplies chance of all mobs spawning and can be set
  542. to 0.5 to have mobs spawn more or 2.0 to spawn less.
  543. e.g. 1 in 7000 * 0.5 = 1 in 3500 so better odds of
  544. spawning.
  545. 'mobs_spawn' if false then mobs no longer spawn without spawner or
  546. spawn egg.
  547. 'mobs_drop_items' when false mobs no longer drop items when they die.
  548. 'mobs_griefing' when false mobs cannot break blocks when using either
  549. pathfinding level 2, replace functions or mobs:boom
  550. function.
  551. 'mob_nospawn_range' Minimum range a mob can spawn near player (def: 12)
  552. 'mob_active_limit' Number of active mobs in game, 0 for unlimited
  553. Players can override the spawn chance for each mob registered by adding a line
  554. to their minetest.conf file with a new value, the lower the value the more each
  555. mob will spawn e.g.
  556. mobs_animal:sheep 11000
  557. mobs_monster:sand_monster 100
  558. ...you can also change how many of a certain mob appear in an active mapblock by
  559. adding a comma and then a new value e.g.
  560. mobs_animal:cow 8000,4 <-- 4 cows per mapblock at 8000 spawn chance
  561. mobs_monster:dirt_monster ,20 <-- 20 dirt monsters per mapblock
  562. Rideable Horse Example Mob
  563. --------------------------
  564. mobs:register_mob("mob_horse:horse", {
  565. type = "animal",
  566. visual = "mesh",
  567. visual_size = {x = 1.20, y = 1.20},
  568. mesh = "mobs_horse.x",
  569. collisionbox = {-0.4, -0.01, -0.4, 0.4, 1.25, 0.4},
  570. animation = {
  571. speed_normal = 15,
  572. speed_run = 30,
  573. stand_start = 25,
  574. stand_end = 75,
  575. walk_start = 75,
  576. walk_end = 100,
  577. run_start = 75,
  578. run_end = 100,
  579. },
  580. textures = {
  581. {"mobs_horse.png"},
  582. {"mobs_horsepeg.png"},
  583. {"mobs_horseara.png"}
  584. },
  585. fear_height = 3,
  586. runaway = true,
  587. fly = false,
  588. walk_chance = 60,
  589. view_range = 5,
  590. follow = {"farming:wheat"},
  591. passive = true,
  592. hp_min = 12,
  593. hp_max = 16,
  594. armor = 200,
  595. lava_damage = 5,
  596. fall_damage = 5,
  597. water_damage = 1,
  598. makes_footstep_sound = true,
  599. drops = {
  600. {name = "mobs:meat_raw", chance = 1, min = 2, max = 3}
  601. },
  602. sounds = {
  603. random = "horse_neigh.ogg",
  604. damage = "horse_whinney.ogg",
  605. },
  606. do_custom = function(self, dtime)
  607. -- set needed values if not already present
  608. if not self.v2 then
  609. self.v2 = 0
  610. self.max_speed_forward = 6
  611. self.max_speed_reverse = 2
  612. self.accel = 6
  613. self.terrain_type = 3
  614. self.driver_attach_at = {x = 0, y = 20, z = -2}
  615. self.driver_eye_offset = {x = 0, y = 3, z = 0}
  616. self.driver_scale = {x = 1, y = 1}
  617. end
  618. -- if driver present allow control of horse
  619. if self.driver then
  620. mobs.drive(self, "walk", "stand", false, dtime)
  621. return false -- skip rest of mob functions
  622. end
  623. return true
  624. end,
  625. on_die = function(self, pos)
  626. -- drop saddle when horse is killed while riding
  627. -- also detach from horse properly
  628. if self.driver then
  629. minetest.add_item(pos, "mobs:saddle")
  630. mobs.detach(self.driver, {x = 1, y = 0, z = 1})
  631. end
  632. end,
  633. on_rightclick = function(self, clicker)
  634. -- make sure player is clicking
  635. if not clicker or not clicker:is_player() then
  636. return
  637. end
  638. -- feed, tame or heal horse
  639. if mobs:feed_tame(self, clicker, 10, true, true) then
  640. return
  641. end
  642. -- make sure tamed horse is being clicked by owner only
  643. if self.tamed and self.owner == clicker:get_player_name() then
  644. local inv = clicker:get_inventory()
  645. -- detatch player already riding horse
  646. if self.driver and clicker == self.driver then
  647. mobs.detach(clicker, {x = 1, y = 0, z = 1})
  648. -- add saddle back to inventory
  649. if inv:room_for_item("main", "mobs:saddle") then
  650. inv:add_item("main", "mobs:saddle")
  651. else
  652. minetest.add_item(clicker.get_pos(), "mobs:saddle")
  653. end
  654. -- attach player to horse
  655. elseif not self.driver
  656. and clicker:get_wielded_item():get_name() == "mobs:saddle" then
  657. self.object:set_properties({stepheight = 1.1})
  658. mobs.attach(self, clicker)
  659. -- take saddle from inventory
  660. inv:remove_item("main", "mobs:saddle")
  661. end
  662. end
  663. -- used to capture horse with magic lasso
  664. mobs:capture_mob(self, clicker, 0, 0, 80, false, nil)
  665. end
  666. })