Codebase list minetest-mod-mobs-redo / 94016c2d-4e99-406e-a03d-88d76475776b/main api.txt
94016c2d-4e99-406e-a03d-88d76475776b/main

Tree @94016c2d-4e99-406e-a03d-88d76475776b/main (Download .tar.gz)

api.txt @94016c2d-4e99-406e-a03d-88d76475776b/mainraw · history · blame

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
Mobs Redo API
=============

Welcome to the world of mobs in minetest and hopefully an easy guide to defining
your own mobs and having them appear in your worlds.


Registering Mobs
----------------

To register a mob and have it ready for use requires the following function:

   mobs:register_mob(name, definition)

The 'name' of a mob usually starts with the mod name it's running from followed
by it's own name e.g.

   "mobs_monster:sand_monster" or "mymod:totally_awesome_beast"

... and the 'definition' is a table which holds all of the settings and
functions needed for the mob to work properly which contains the following:

   'nametag'       contains the name which is shown above mob.
   'type'          holds the type of mob that inhabits your world e.g.
      "animal"     usually docile and walking around.
      "monster"    attacks player or npc on sight.
      "npc"        walk around and will defend themselves if hit first, they
                   kill monsters.
   'hp_min'        has the minimum health value the mob can spawn with.
   'hp_max'        has the maximum health value the mob can spawn with.
   'armor'         holds strength of mob, 100 is normal, lower is more powerful
                   and needs more hits and better weapons to kill.
   'passive'       when false allows animals to defend themselves when hit,
                   otherwise they amble onwards.
   'walk_velocity' is the speed that your mob can walk around.
   'run_velocity'  is the speed your mob can run with, usually when attacking.
   'stand_chance'  has a 0-100 chance value your mob will stand from walking.
   'walk_chance'   has a 0-100 chance value your mob will walk from standing,
                   set to 0 for jumping mobs only.
   'randomly_turn' if set to false then mob will not turn to face player or
                   randomly turn while walking or standing.
   'jump'          when true allows your mob to jump updwards.
   'jump_height'   holds the height your mob can jump, 0 to disable jumping.
   'stepheight'    height of a block that your mob can easily walk up onto,
                   defaults to 1.1.
   'fly'           when true allows your mob to fly around instead of walking.
   'fly_in'        holds the node name that the mob flies (or swims) around
                   in e.g. "air" or "default:water_source".
   'keep_flying'   when true mobs like birds no longer stop and stand.
   'stay_near'     when set allows mobs the chance to stay around certain nodes.
      'nodes'      string or table of nodes to stay nearby e.g. "farming:straw"
      'chance'     chance of searching for above node(s), default is 10.
   'runaway'       if true causes animals to turn and run away when hit.
   'pushable'      when true mobs can be pushed by player or other mobs.
   'view_range'    how many nodes in distance the mob can see a player.
   'damage'        how many health points the mob does to a player or another
                   mob when melee attacking.
   'damage_group'  group in which damage is dealt, dedaults to "fleshy".
   'damage_texture_modifier' applies texture modifier on hit e.g "^[brighten"
   'knock_back'    when true has mobs falling backwards when hit, the greater
                   the damage the more they move back.
   'fear_height'   is how high a cliff or edge has to be before the mob stops
                   walking, 0 to turn off height fear.
   'fall_speed'    has the maximum speed the mob can fall at, default is -10.
   'fall_damage'   when true causes falling to inflict damage.
   'water_damage'  holds the damage per second infliced to mobs when standing in
                   water.
   'air_damage'    holds damage per second inflicted to mob when standing in air.
   'lava_damage'   holds the damage per second inflicted to mobs when standing
                   in lava.
   'fire_damage'   holds the damage per second inflicted to mobs when standing
                   in fire.

   'light_damage'  holds the damage per second inflicted to mobs when light
                   level is between the min and max values below
   'light_damage_min' minimum light value when mob is affected (default: 14)
   'light_damage_max' maximum light value when mob is affected (default: 15)
   'suffocation'   when > 0 mobs will suffocate inside solid blocks and will be
                   hurt by the value given every second (0 to disable).
   'floats'        when set to 1 mob will float in water, 0 has them sink.
   'follow'        mobs follow player when holding any of the items which appear
                   on this table, the same items can be fed to a mob to tame or
                   breed e.g. {"farming:wheat", "default:apple", "group:fish"}

   'reach'               is how far the mob can attack player when standing
                         nearby, default is 3 nodes.
   'docile_by_day'       when true has mobs wandering around during daylight
                         hours and only attacking player at night or when
                         provoked.
   'attack_chance'       0 to 100 chance the mob will attack (default is 5).
   'attack_monsters'     when true mob will attack monsters.
   'attack_animals'      when true mob will attack animals.
   'attack_npcs'         when true mob will attack npcs within range.
   'attack_players'      when true mob will attack players nearby.
   'owner_loyal'         when true non-docile tamed mobs attack anything player
                         punches when nearby.
   'group_attack'        when true has same mob type grouping together to attack
                         offender.
   'group_helper'        string containing mob name that attacks alongside
                         current mob when group attacking.
                         mob is attacking in groups.
   'attack_type'         tells the api what a mob does when attacking the player
                         or another mob:
      'dogfight'         is a melee attack when player is within mob reach.
      'shoot'            has mob shoot pre-defined arrows at player when inside
                         view_range.
      'dogshoot'         has melee attack when inside reach and shoot attack
                         when inside view_range.
      'explode'          causes mob to stop and explode when inside reach.
   'explosion_radius'           the radius of explosion node destruction,
                                defaults to 1
   'explosion_damage_radius'    the radius of explosion entity & player damage,
                                defaults to explosion_radius * 2
   'explosion_timer'     number of seconds before mob explodes while its target
                         is still inside reach or explosion_damage_radius,
                         defaults to 3.
   'allow_fuse_reset'    Allow 'explode' attack_type to reset fuse and resume
                         chasing if target leaves the blast radius or line of
                         sight. Defaults to true.
   'stop_to_explode'     When set to true (default), mob must stop and wait for
                         explosion_timer in order to explode. If false, mob will
                         continue chasing.
   'arrow'               holds the pre-defined arrow object to shoot when
                         attacking.
   'arrow_override'      function that allows tweaking of arrow entity from
                         inside mob definition (self) passed to function.
   'dogshoot_switch'     allows switching between attack types by using timers
                         (1 for shoot, 2 for dogfight)
   'dogshoot_count_max'  contains how many seconds before switching from
                         dogfight to shoot.
   'dogshoot_count2_max' contains how many seconds before switching from shoot
                         to dogfight.
   'shoot_interval'      has the number of seconds between shots.
   'shoot_offset'        holds the y position added as to where the
                         arrow/fireball appears on mob.
   'specific_attack'     has a table of entity names that mob can also attack
                         e.g. {"player", "mobs_animal:chicken"}.
   'runaway_from'        contains a table with mob names to run away from, add
                         "player" to list to runaway from player also.
   'ignore_invisibility' When true mob will still be able to see and attack
                         player even if invisible (invisibility mod only).
   'blood_amount'        contains the number of blood droplets to appear when
                         mob is hit.
   'blood_texture'       has the texture name to use for droplets e.g.
                         "mobs_blood.png", or table {"blood1.png", "blood2.png"}
   'pathfinding'         set to 1 for mobs to use pathfinder feature to locate
                         player, set to 2 so they can build/break also (only
                         works with dogfight attack and when 'mobs_griefing'
                         in minetest.conf is not false). Adding {unbreakable=1}
                         to node groups stops them being broken by mobs.
   'immune_to'           is a table that holds specific damage when being hit by
                         certain items e.g.
      {"default:sword_wood",  0} -- causes no damage.
      {"default:gold_lump", -10} -- heals by 10 health points.
      {"default:coal_block", 20} -- 20 damage when hit on head with coal blocks.
      {"all"} -- stops all weapons causing damage apart from those on list.

   'makes_footstep_sound' when true you can hear mobs walking.
   'sounds'               this is a table with sounds of the mob
      'distance'          maximum distance sounds can be heard, default is 10.
      'random'            random sound that plays during gameplay.
      'war_cry'           what you hear when mob starts to attack player.
      'attack'            what you hear when being attacked.
      'shoot_attack'      sound played when mob shoots.
      'damage'            sound heard when mob is hurt.
      'death'             played when mob is killed.
      'jump'              played when mob jumps.
      'fuse'              sound played when mob explode timer starts.
      'explode'           sound played when mob explodes.

   'drops'     table of items that are dropped when mob is killed, fields are:
      'name'   name of item to drop.
      'chance' chance of drop, 1 for always, 2 for 1-in-2 chance etc.
      'min'    minimum number of items dropped, set to 0 for rare drops.
      'max'    maximum number of items dropped.
   Note: If weapon has {fire=1} damage group set then cooked items will drop.
   Note2: A function can now be passed which can also return drops table, e.g.
      drops = function(pos)
         -- do something
         return { {name = "farming:bread"}, {name = "default:dirt", chance = 2} }
      end

   'visual'            holds the look of the mob you wish to create:
      'cube'           looks like a normal node
      'sprite'         sprite which looks same from all angles.
      'upright_sprite' flat model standing upright.
      'wielditem'      how it looks when player holds it in hand.
      'mesh'           uses separate object file to define mob.
   'visual_size'       has the size of the mob, defaults to {x = 1, y = 1}
   'collisionbox'      has the box in which mob can be interacted with the
                       world e.g. {-0.5, -0.5, -0.5, 0.5, 0.5, 0.5}
   'selectionbox'      has the box in which player can interact with mob
   'textures'          holds a table list of textures to be used for mob, or you
                       could use multiple lists inside another table for random
                       selection e.g. { {"texture1.png"}, {"texture2.png"} }
   'child_texture'     holds the texture table for when baby mobs are used.
   'gotten_texture'    holds the texture table for when self.gotten value is
                       true, used for milking cows or shearing sheep.
   'texture_mods'      holds a string which overlays a texture on top of the
                       mob texture e.g. "^saddle.png"
   'mesh'              holds the name of the external object used for mob model
                       e.g. "mobs_cow.b3d"
   'gotten_mesh"       holds the name of the external object used for when
                       self.gotten is true for mobs.
   'rotate'            custom model rotation, 0 = front, 90 = side, 180 = back,
                       270 = other side.
   'glow'              has mob glow without light source, 0 to 15 or nil to disable
   'double_melee_attack' when true has the api choose between 'punch' and
                      'punch2' animations. [DEPRECATED]

   'animation'       holds a table containing animation names and settings for use with
                     mesh models:
      'stand_start'  start frame for when mob stands still.
      'stand_end'    end frame of stand animation.
      'stand_speed'  speed of animation in frames per second.
      'walk_start'   when mob is walking around.
      'walk_end'
      'walk_speed'
      'run_start'    when a mob runs or attacks.
      'run_end'
      'run_speed'
      'fly_start'    when a mob is flying.
      'fly_end'
      'fly_speed'
      'punch_start'  when a mob melee attacks.
      'punch_end'
      'punch_speed'
      'punch2_start' alternative melee attack animation.
      'punch2_end'
      'punch2_speed'
      'shoot_start'  shooting animation.
      'shoot_end'
      'shoot_speed'
      'die_start'    death animation
      'die_end'
      'die_speed'
      'die_loop'     when set to false stops the animation looping.
      'die_rotate'   if true mob spins during death animation.

      Using '_loop = false' setting will stop any of the above animations from
      looping.

      'speed_normal' is used for animation speed for compatibility with some
                     older mobs.

      Note: Up to 5 different animations can be used per action e.g.
      stand_start, stand_end, stand1_start, stand1_end .. up to stand4_start


Node Replacement
----------------

Mobs can look around for specific nodes as they walk and replace them to mimic
eating.

   'replace_what'   group of items to replace e.g.
                    {"farming:wheat_8", "farming:carrot_8"}
                    or you can use the specific options of what, with and
                    y offset by using this instead:
                    {
                       {"group:grass", "air", 0},
                       {"default:dirt_with_grass", "default:dirt", -1}
                    }
   'replace_with'   replace with what e.g. "air" or in chickens case "mobs:egg"
   'replace_rate'   how random should the replace rate be (typically 10)
   'replace_offset' +/- value to check specific node to replace

   'on_replace(self, pos, oldnode, newnode)' is called when mob is about to
                                             replace a node.
      'self'    ObjectRef of mob
      'pos'     Position of node to replace
      'oldnode' Current node
      'newnode' What the node will become after replacing

       If false is returned, the mob will not replace the node.

       By default, replacing sets self.gotten to true and resets the object
       properties. (DEPRECATED, use on_replace to make changes).


Custom Definition Functions
---------------------------

Along with the above mob registry settings we can also use custom functions to
enhance mob functionality and have them do many interesting things:

   'on_die'         a function that is called when the mob is killed the
                    parameters are (self, pos)
   'on_rightclick'  its same as in minetest.register_entity()
   'on_blast'       is called when an explosion happens near mob when using TNT
                    functions, parameters are (object, damage) and returns
                    (do_damage, do_knockback, drops)
   'on_spawn'       is a custom function that runs on mob spawn with 'self' as
                    variable, return true at end of function to run only once.
   'after_activate' is a custom function that runs once mob has been activated
                    with these paramaters (self, staticdata, def, dtime)
   'on_breed'       called when two similar mobs breed, paramaters are
                    (parent1, parent2) objects, return false to stop child from
                    being resized and owner/tamed flags and child textures being
                    applied.  Function itself must spawn new child mob.
   'on_grown'       is called when a child mob has grown up, only paramater is
                    (self).
   'do_punch'       called when mob is punched with paramaters (self, hitter,
                    time_from_last_punch, tool_capabilities, direction), return
                    false to stop punch damage and knockback from taking place.
   'custom_attack'  when set this function is called instead of the normal mob
                    melee attack, parameters are (self, to_attack) and if true
                    is returned normal attack function continued.
   'on_die'         a function that is called when mob is killed (self, pos), also
                    has access to self.cause_of_death table.
   'on_flop'        function called when flying or swimmimng mob is no longer in
                    air/water, (self) paramater and return true to skip the built
                    in api flop feature.
   'do_custom'      a custom function that is called every tick while mob is
                    active and which has access to all of the self.* variables
                    e.g. (self.health for health or self.standing_in for node
                    status), return with 'false' to skip remainder of mob API.


Internal Variables
------------------

The mob api also has some preset variables and functions that it will remember
for each mob.

   'self.health'        contains current health of mob (cannot exceed
                        self.hp_max)
   'self.texture_list'  contains list of all mob textures
   'self.child_texture' contains mob child texture when growing up
   'self.base_texture'  contains current skin texture which was randomly
                        selected from textures list
   'self.gotten'        this is used for obtaining milk from cow and wool from
                        sheep
   'self.horny'         when animal fed enough it is set to true and animal can
                        breed with same animal
   'self.hornytimer'    background timer that controls breeding functions and
                        mob childhood timings
   'self.child'         used for when breeding animals have child, will use
                        child_texture and be half size
   'self.owner'         string used to set owner of npc mobs, typically used for
                        dogs
   'self.order'         set to "follow" or "stand" so that npc will follow owner
                        or stand it's ground
   'self.nametag'       contains the name of the mob which it can show above
   'self.state'         Current mob state.
                        "stand": no movement (except turning around)
                        "walk": walk or move around aimlessly
                        "attack": chase and attack enemy
                        "runaway": flee from target
                        "flop": bounce around aimlessly
                                (for swimming mobs that have stranded)
                        "die": during death


Adding Mobs in World
--------------------

	mobs:add_mob(pos, {
		name = "mobs_animal:chicken",
		child = true,
		owner = "singleplayer",
		nametag = "Bessy",
		ignore_count = true -- ignores mob count per map area
	})

Returns false if mob could not be added, returns mob object if spawned ok.


Removing Mob from World
-----------------------

	mobs:remove(self, decrease)

Removes mob 'self' from the world and if 'decrease' is true then the mob counter
will also be decreased by one.


Spawning Mobs in World
----------------------

    mobs:spawn({
       name = "mobs_monster:tree_monster",
       nodes = {"group:leaves"},
       max_light = 7,
    })

Spawn functions require the following settings, some of which already have a
default setting and can be omitted:

    'name'                is the name of the animal/monster
    'nodes'               is a list of nodenames on that the animal/monster can
                          spawn on top of (defaults to {"group:dirt", "group:stone"}
    'neighbors'           is a list of nodenames on that the animal/monster will
                          spawn beside (default is {"air"})
    'interval'            is same as in register_abm() (default is 30)
    'chance'              is same as in register_abm() (default is 5000)
    'min_light'           is the minimum light level (default is 0)
    'max_light'           is the maximum light (default is 15)
    'min_height'          is the minimum height a mob can spawn (default: -31000)
    'max_height'          is the maximum height a mob can spawn (default is 31000)
    'active_object_count' number of this type of mob to spawn at one time inside
                          map area (default is 1)
    'day_toggle'          true for day spawning, false for night or nil for
                          anytime
    'on_spawn'            is a custom function which runs after mob has spawned
                          and gives self and pos values.
    'on_map_load'         when true mobs will have a chance of spawning only
                          when new areas of map are loaded, interval will not be
                          used.

The older spawn functions are still active and working but have no defaults like
the mobs:spawn, so it is recommended to use the above instead.

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

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

A simpler way to handle mob spawns has been added with the mobs:spawn(def)
command which uses above names to make settings clearer:


For each mob that spawns with this function is a field in mobs.spawning_mobs.
It tells if the mob should spawn or not.  Default is true.  So other mods can
only use the API of this mod by disabling the spawning of the default mobs in
this mod.


mobs:spawn_abm_check(pos, node, name)

This global function can be changed to contain additional checks for mobs to
spawn e.g. mobs that spawn only in specific areas and the like.  By returning
true the mob will not spawn.

    'pos'    holds the position of the spawning mob
    'node'   contains the node the mob is spawning on top of
    'name'   is the name of the animal/monster


Particle Effects
----------------

mobs:effect(pos, amount, texture, min_size, max_size, radius, gravity, glow, fall)

This function provides a quick way to spawn particles as an effect.

    'pos'       center position of particle effect.
    'amount'    how many particles.
    'texture'   texture filename to use for effect.
    'min_size'  smallest particle size.
    'max_size'  largest particle size.
    'radius'    how far particles spread outward from center.
    'gravity'   gravity applied to particles once they spawn.
    'glow'      number between 1 and 15 for glowing particles.
    'fall'      when true particles fall, false has them rising, nil has them scatter.


Making Arrows
-------------

mobs:register_arrow(name, definition)

This function registers a arrow for mobs with the attack type shoot.

    'name'            is the name of the arrow
    'definition'      is a table with the following values:
       'visual'       same is in minetest.register_entity()
       'visual_size'  same is in minetest.register_entity()
       'textures'     same is in minetest.register_entity()
       'physical'     same is in minetest.register_entity() [default: false]
       'collide_with_objects'       same as above
       'velocity'     the velocity of the arrow
       'drop'         if set to true any arrows hitting a node will drop as item
       'hit_player'   a function that is called when the arrow hits a player;
                      this function should hurt the player, the parameters are
                      (self, player)
       'hit_mob'      a function that is called when the arrow hits a mob;
                      this function should hurt the mob, the parameters are
                      (self, player)
       'hit_object'   a function that is called when the arrow hits an object;
                      this function parameters are (self, player)
       'hit_node'     a function that is called when the arrow hits a node, the
                      parameters are (self, pos, node)
       'tail'         when set to 1 adds a trail or tail to mob arrows
       'tail_texture' texture string used for above effect
       'tail_size'    has size for above texture (defaults to between 5 and 10)
       'expire'       contains float value for how long tail appears for
                      (defaults to 0.25)
       'glow'         has value for how brightly tail glows 1 to 10 (default is
                      0 for no glow)
       'rotate'       integer value in degrees to rotate arrow
       'on_step'      is a custom function when arrow is active, nil for
                      default.
       'on_punch'     is a custom function when arrow is punched, nil by default
       'collisionbox' is hitbox table for arrow, {-.1,-.1,-.1,.1,.1,.1} by default.
       'lifetime'     contains float value for how many seconds arrow exists in
                      world before being removed (default is 4.5 seconds).


Spawn Eggs
----------

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

This function registers a spawn egg which can be used to properly spawn in a mob.
Animals are spawned as tamed unless sneak/shift is held while spawning.

   'name'        this is the name of your new mob to spawn e.g. "mob:sheep"
   'description' the name of the new egg you are creating e.g. "Spawn Sheep"
   'background'  the texture displayed for the egg in inventory
   'addegg'      would you like an egg image in front of your texture (1 = yes,
                 0 = no)
   'no_creative' when set to true this stops spawn egg appearing in creative
                 mode for destructive mobs like Dungeon Masters.


Explosion Function
------------------

mobs:explosion(pos, radius) -- DEPRECATED!!!  use mobs:boom() instead

mobs:boom(self, pos, radius)
   'self' mob entity
   'pos' centre position of explosion
   'radius' radius of explosion (typically set to 3)

This function generates an explosion which removes nodes in a specific radius
and damages any entity caught inside the blast radius.  Protection will limit
node destruction but not entity damage.


Capturing Mobs
--------------

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

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, using the net or
lasso items, and can also have the player take the mob by force if tamed and
replace with another item entirely.

   'self'         mob information
   'clicker'      player information
   'chance_hand'  chance of capturing mob by hand (1 to 100) 0 to disable
   'chance_net'   chance of capturing mob using net (1 to 100) 0 to disable
   'chance_lasso' chance of capturing mob using magic lasso (1 to 100) 0 to
                  disable
   'force_take'   take mob by force, even if tamed (true or false)
   'replacewith'  once captured replace mob with this item instead (overrides
                  new mob eggs with saved information)

mobs:force_capture(self, clicker)

Same as above but does no checks, it simply captures any and all mobs and places
inside a spawn egg containing all of the mob information.


Feeding and Taming/Breeding
---------------------------

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

This function allows the mob to be fed the item inside self.follow be it apple,
wheat or whatever a set number of times and be tamed or bred as a result.
Will return true when mob is fed with item it likes.

   'self'       mob information
   'clicker'    player information
   'feed_count' number of times mob must be fed to tame or breed
   'breed'      true or false stating if mob can be bred and a child created
                afterwards
   'tame'       true or false stating if mob can be tamed so player can pick
                them up


Protecting Mobs
---------------

mobs:protect(self, clicker)

This function can be used to right-click any tamed mob with mobs:protector item,
this will protect the mob from harm inside of a protected area from other
players.  Will return true when mob right-clicked with mobs:protector item.

   'self'    mob information
   'clicker' player information


Riding Mobs
-----------

Mobs can now be ridden by players and the following shows its functions and
usage:


mobs:attach(self, player)

This function attaches a player to the mob so it can be ridden.

   'self'   mob information
   'player' player information


mobs:detach(player, offset)

This function will detach the player currently riding a mob to an offset
position.

   'player' player information
   'offset' position table containing offset values


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

This function allows an attached player to move the mob around and animate it at
same time.

   'self'            mob information
   'move_animation'  string containing movement animation e.g. "walk"
   'stand_animation' string containing standing animation e.g. "stand"
   'can_fly'         if true then jump and sneak controls will allow mob to fly
                     up and down
   'dtime'           tick time used inside drive function


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

This function allows an attached player to fly the mob around using directional
controls.

   'self'            mob information
   'dtime'           tick time used inside fly function
   'speed'           speed of flight
   'can_shoot'       true if mob can fire arrow (sneak and left mouse button
                     fires)
   'arrow_entity'    name of arrow entity used for firing
   'move_animation'  string containing name of pre-defined animation e.g. "walk"
                     or "fly" etc.
   'stand_animation' string containing name of pre-defined animation e.g.
                     "stand" or "blink" etc.

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


mobs:set_animation(self, name)

This function sets the current animation for mob, defaulting to "stand" if not
found.

   'self' mob information
   'name' name of animation


Certain variables need to be set before using the above functions:

   'self.v2'                toggle switch used to define below 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 or 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}


mobs:line_of_sight(self, pos1, pos2, stepsize) [DEPRECATED]

This function is for use within the mobs definition for special use cases and
returns true if a mob can see the player or victim.

...'self' mob information
   'pos1' position of mob
   'pos2' position of vistim or player
   'stepsize' usually set to 1

Use this instead:

    mob_class:line_of_sight(pos1, pos2, stepsize)


mobs:can_spawn(pos, name)

This function checks the surrounding area at [pos] to see if there is enough empty
space to spawn mob [name], if so then a new position is returned for use,
otherwise nil is returned.


External Settings for "minetest.conf"
------------------------------------

   'enable_damage'          if true monsters will attack players (default is true)
   'only_peaceful_mobs'     if true only animals will spawn in game (default is
                            false)
   'mobs_disable_blood'     if false blood effects appear when mob is hit (default
                            is false)
   'mobs_spawn_protected'   if set to false then mobs will not spawn in protected
                            areas (default is true)
   'mobs_spawn_monster_protected'   if set to false then monsters will not spawn in
                            protected areas (default is true)
   'remove_far_mobs'        if true then untamed mobs that are outside players
                             visual range will be removed (default is true)
   'mobname'                can change specific mob chance rate (0 to disable) and
                            spawn number e.g. mobs_animal:cow = 1000,5
   'mob_difficulty'         sets difficulty level (health and hit damage
                            multiplied by this number), defaults to 1.0.
   'mob_show_health'        if false then punching mob will not show health status
                            (true by default)
   'mob_chance_multiplier'  multiplies chance of all mobs spawning and can be set
                            to 0.5 to have mobs spawn more or 2.0 to spawn less.
                            e.g.  1 in 7000 * 0.5 = 1 in 3500 so better odds of
                            spawning.
   'mobs_spawn'             if false then mobs no longer spawn without spawner or
                            spawn egg.
   'mobs_drop_items'        when false mobs no longer drop items when they die.
   'mobs_griefing'          when false mobs cannot break blocks when using either
                            pathfinding level 2, replace functions or mobs:boom
                            function.
   'mob_nospawn_range'      Minimum range a mob can spawn near player (def: 12)
   'mob_active_limit'       Number of active mobs in game, 0 for unlimited
   'mob_area_spawn'         When true will check surrounding area the size of the
                            mob for obstructions before spawning, otherwise it
                            defaults to checking the height of the mob only.
   'mob_smooth_rotate'      Enables smooth rotation when mobs turn by default.

Players can override the spawn chance for each mob registered by adding a line
to their minetest.conf file with a new value, the lower the value the more each
mob will spawn e.g.

mobs_animal:sheep 11000
mobs_monster:sand_monster 100

...you can also change how many of a certain mob appear in an active mapblock by
adding a comma and then a new value e.g.

mobs_animal:cow = 8000,4            <-- 4 cows per mapblock at 8000 spawn chance
mobs_monster:dirt_monster = ,20     <-- 20 dirt monsters per mapblock


Rideable Horse Example Mob
--------------------------

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}
	},
	sounds = {
		random = "horse_neigh.ogg",
		damage = "horse_whinney.ogg",
	},

	do_custom = function(self, dtime)

		-- set needed values if not already present
		if not self.v2 then
			self.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 and self.owner == clicker:get_player_name() then

			local inv = clicker:get_inventory()

			-- detatch player already riding horse
			if self.driver and 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.get_pos(), "mobs:saddle")
				end

			-- attach player to horse
			elseif not self.driver
			and 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
})