This text file documents yams' haphazard additions to the Mobs Redo API.

Changes
-------

mob_expire(pos, dtime) now returns true if the mob was removed and false
otherwise.

'active_spawn_count' for mobs is now 50 by default instead of 1.

The default value for sounds.distance is now 32 instead of 10.

Around y = 0, monsters will always spawn with an HP value around 'hp_min'
instead of being a random value between 'hp_min' and 'hp_max'. 'hp_max' is
now used when scaling the mobs' stats. The HP value is slightly randomized
and will be between 90% to 110% of the determined value.

For non-monsters or if scaling is not enabled for a particular mob, 'hp_min'
and 'hp_max' behave like before.

For projectiles, the default value of 'lifetime' is now 10 seconds instead of
4.5 seconds. Projectiles now have default behavior for the 'hit_player',
'hit_node', and 'hit_mob' functions if they are not defined.

For monsters that explode, the 'damage' field is now taken into account, and
damage dealt scales with depth. 'damage' should be set to the maximum damage
possible, as damage will decrease the further the player is from the explosion.
mobs:boom and mobs:safe_boom now take in a damage parameter, which is optional.
Note that mobs that die by explosion only award half EXP and no item drops.

'attack_chance' is no longer used.

Originally, animals and NPCs that are not passive have a small chance of
attacking the player if they are not tamed, but in yams, these mobs will never
attack the player unless provoked first.

Additions
---------

Mobs have a new method named 'examine_mob' that sends a message to the player
about the current state of the mob. This is intended to be used for animals.
It is normally called from mobs:feed_tame(), but it can be called manually from
a mob's 'on_rightclick' callback if needed.

examine_mob(self, clicker)
- 'clicker' - the player that right-clicked the mob

Mobs have a new method named 'yams_arrow_punch' that must be called when a
projectile owned by a player hits a mob. Do not use the regular 'object:punch'
method in this case.

yams_arrow_punch(puncher, tflp, toolcaps, dir, yams_data)
- First four parameters are the same as in 'object:punch'
- 'yams_data' - a table with the following properties:
    - 'angle' - required; the direction in radians of the projectile's velocity
                note that the 'dir' parameter is ignored due to a bug in the
                Minetest API so this value is needed
    - 'knockback' - amount of knockback to inflict; defaults to the projectile's
                    damage, but it is strongly recommended that you specify this
    - 'elements' - elemental damage data; should be a table of one or more
                   entries in the form of {element_name = 100}
    - 'proj_name' - the projectile entity's technical name; can be retrieved
                    through self.cause_of_death.projectile if it defeats a mob

Projectiles now have a '_yams_mob_projectile' field, which is read-only. It
can be used to identify projectiles spawned by Mobs Redo.

Additional fields for 'mobs:spawn':
- 'biome_allow' - if specified, a table containing biome names that the mob
                  is allowed to spawn within
- 'biome_deny' - if specified, a table containing biome names that the mob
                 cannot spawn within; has priority over 'biome_allow'

Keep in mind that if mobs:spawn() is called with the same mob more than once,
then 'biome_allow' and 'biome_deny' need to be specified every time. An ABM
is run for each time that mobs:spawn() is called, and if each call to
mobs:spawn() has different 'biome_allow' and 'biome_deny' settings, one ABM
may allow a mob to spawn in a biome that another ABM disallows. Try to avoid
calling mobs:spawn() for the same mob more than once if possible in order to
avoid this problem.

Additional fields for 'register_mob':
- 'damage_max' - maximum melee damage the mob can deal; default is damage * 10
- 'arrow_damage' - base amount of damage the mob inflicts using its
                   projectiles; if set, always overrides the arrow's
                   definition and is applied after arrow_override
- 'arrow_damage_max' - maximum amount of damage the mob inflicts using its
                       projectiles; defaults to arrow_damage * 10 if
                       'arrow_damage' was set
- 'run_velocity_max' - maximum running speed; default is same as run_velocity
- 'melee_interval' - how often the mob punches the player; default is 1.0
- 'melee_knockback' - how much knockback is applied when something gets punched
                      by this mob; default is 8.0
- 'arrow_knockback' - how much knockback is applied when something gets hit by
                      this mob's projectiles; default is 8.0
- 'arrow_error' - how inaccurate arrows can be in radians; default is 0.0
- 'fuse_reset_range' - how far away a player must be from an exploding mob
                       before its fuse resets; defaults to 'reach'
- 'explosion_height_offset' - adjust the height of the explosion's origin; can
                              be used if damage isn't the expected value
- 'base_exp' - base exp value of the mob; default is 50 for monsters and 10
               otherwise
- 'max_exp' - maximum exp value; default is 5000
- 'yams_scaling_opts' - a table that may contain any of the following values:
    - 'enable_scaling' - set to true to enable scaling; default is true
    - 'cavern_start' - depth where scaling the mob's stats should start;
                       defaults to -64 and is also the maximum allowed value
    - 'cavern_fast_until' - by default, stats scale faster until a certain
                           depth from 'cavern_start'; the default is -2048;
                           must be deeper than the value for 'cavern_start'
    - 'cavern_end' - depth where the mob's stats are at their highest;
                     defaults to -19900
    - 'nether_start' - depth in the Nether where scaling should start;
                       defaults to -22000
    - 'nether_end' - depth in the Nether where scaling should end;
                     defaults to -30900
    - 'nether_boost' - what percentage of stats to add if a mob spawns in the
                       Nether; this is used for mobs that spawn both within the
                       caves and the Nether; defaults to 0.0 and valid range is
                       0.0 to 1.0
    - 'cloudlands_start' - height in the Cloudlands where scaling should start;
                           defaults to 1200
    - 'cloudlands_end' - height in the Cloudlands where scaling should end;
                         defaults to 8100
    - 'cloudlands_boost' - what percentage of stats to add if a mob spawns in
                           the Cloudlands; this is used for mobs that spawn
                           both on the surface and up above; defaults to 0.25
                           and valid range is 0.0 to 1.0
    - Note that only mobs with the "monster" type are scaled; animals and NPCs
      will never be scaled
- 'yams_resists' - a table that contains resistance values for mobs
    - each entry looks like: {element_name = {damage = 100, knockback = 100}}
        - 'damage' - percentage modifier for damage; 0 means no damage taken,
                     200 means 2x damage taken, and negative values heal
        - 'knockback' - percentage modifier for knockback; 0 means no knockback,
                        and 200 means 2x the knockback
- 'yams_melee_effects' - a table that contains status effects applied to the
                         player when they are hit with melee attacks
    - each entry looks like: {name = "status", duration = 10, chance = 100}
        - 'name' - name of the effect; must be registered with the
                   'playereffects' mod first
        - 'duration' - how long the effect lasts in seconds
        - 'chance' - chance of the effect being applied from 0-100
- 'yams_arrow_effects' - a table that contains status effects applied to the
                         player when they are hit with the mob's projectiles
    - see documentation above for the format of each entry
- 'on_knockback' - function(self, kb) that is called when knocked back; return
                   value is ignored and it is not called if the mob died from
                   the attack

Additional fields for arrow definitions:
- 'damage' - damage that the projectile does by default if the mob that shoots
             the projectile does not override it with either 'arrow_override'
             or with 'arrow_damage'
