Skip to main content

Mob Behaviors

A mob behavior is a Lua file that takes over the AI of a mob FreeMinecraftModels did not spawn: a naturally spawned creeper, a chicken, a pillager from a raid. While the override lasts, the mob does what the file says. Afterwards it has its own AI back and behaves as before.

Four behaviors ship with the plugin. A creeper can follow a player and blow itself up on whoever attacks them, a chicken can turn on players, and pillagers can run away in fear. You put a behavior on a mob with a command or from a Lua script, for a set time or until something clears it.

Build availability

Mob behaviors need the FreeMinecraftModels release after 2.15.0, and Minecraft 1.21.4 or newer.

What an override does​

  • The mob's own goals and Brain stop, so it does nothing by itself. Only the behaviors move it, turn it and make it attack.
  • It keeps everything else: its health, equipment, movement speed and name, and sunlight still burns it.
  • It still despawns once no player is within 128 blocks, unless something had already made it stay. The slower despawning of a mob left idle between 32 and 128 blocks from players does not happen while it is overridden.
  • It moves and fights the way its kind does. A creeper swells and explodes, a skeleton shoots arrows, a zombie hits.
  • A mob can have an owner, a player or any other living entity. Its own attacks never damage its owner: its hits, the projectiles it shoots and a creeper's blast are cancelled. Potion effects are not, and neither is anything a behavior does to the owner through c.overlay.owner.
  • When the time is up or something clears the override, the mob has its own AI back. A zombie hunts players again and a chicken wanders.
  • The override stays on the mob through chunk unloads, server restarts and /fmm reload. A timed one keeps counting while the mob is unloaded, and is gone if its time ran out meanwhile. A behavior's memories start empty when the mob comes back.
  • It ends by itself when its time is up, when the mob dies, when the mob turns into another mob, such as a villager into a witch, or when a behavior calls c.overlay:finish().

Commands​

All of them need the permission freeminecraftmodels.mobbehaviors.admin, which operators have, and are for players only.

CommandPurpose
/fmm mobbehavior apply <behaviors> [seconds] [radius]Overrides the AI of the mob in your crosshair, up to 32 blocks away, with the named behaviors, and makes you its owner. With a radius it takes every mob within that many blocks of you on each axis instead
/fmm mobbehavior applywild <behaviors> [seconds] [radius]The same, with no owner
/fmm mobbehavior clearGives the mob in your crosshair its own AI back
/fmm mobbehavior clear allGives every loaded overridden mob its own AI back. A mob in an unloaded chunk keeps its override and takes it up again when it loads
/fmm mobbehavior listLists the behaviors that loaded and how many mobs run one
  • behaviors is one name, or several joined by commas with no spaces, such as coward,wander.
  • seconds is how long the override lasts. Leave it out, or use 0, and it lasts until cleared.
  • A mob never attacks or fears its owner. To try hostile or coward on yourself, use applywild.
  • hostile and coward do not pick out players in creative or spectator mode, so test in survival. A player in creative who hits the mob is still fought or fled for 10 seconds.
/fmm mobbehavior apply guardian
/fmm mobbehavior applywild hostile 30
/fmm mobbehavior applywild coward,wander 0 12

The first makes the creeper you look at follow and defend you. The second makes a chicken attack you for 30 seconds. The third sends every mob within 12 blocks running from you until you run clear all.

Shipped behaviors​

NameWhat the mob does
guardianStays near its owner and fights whoever hurts them, whoever they hurt, and whoever hurts it
hostileAttacks the nearest player, or whatever its targets setting names
cowardRuns from the nearest player, or whatever its fears setting names
wanderStrolls about when nothing else moves it

An overridden mob has lost its own strolling with the rest of its AI, so without wander it stands still whenever its other behaviors have nothing to do. Add wander to the list, as in coward,wander. Its place in the list does not matter: a behavior's priority decides which one moves the mob.

A mob that shoots uses its melee hit instead of shooting when its target is within reach.

Speeds multiply the mob's own movement speed, so 1 is its normal walk. Distances are in blocks and times in ticks.

guardian​

It follows its owner once they are follow_distance away and stops follow_stop from them. It fights the owner's attacker first, then its own, then the owner's target. Each is remembered for 10 seconds after the hit. Without an owner it only defends itself.

SettingDefaultMeaning
follow_distance6How far the owner gets before the mob comes after them
follow_stop3How close it comes
follow_speed1.2Speed while following
chase_speed1.3Speed while fighting
reach2.2How close it gets to hit
fuse_distance3A creeper starts its fuse within this distance of its target
fuse_escape7A creeper's fuse goes out when the target gets this far, or out of sight
shoot_distance12A mob that shoots does so from within this distance, while it can see the target
attack_ticks20Time between two hits or shots
assisttrueAlso fights whoever the owner hurts
defend_itselftrueAlso fights whoever hurts it

hostile​

It attacks whoever hurt it in the last 10 seconds, else the nearest target within range. It looks for a new target every 10 ticks. With an owner, it spares them and the other mobs that serve them.

SettingDefaultMeaning
targetsplayerplayer, hostile, passive, living, or an entity type such as zombie
range16How far it notices targets
damage0What a hit deals. 0 leaves it to the mob's own attack, which is 2 for a kind that has none, such as a chicken
chase_speed, reach, fuse_distance, fuse_escape, shoot_distance, attack_ticksas guardianAs in guardian

coward​

It starts running when something it fears comes within range, and stops once that is safe_distance away. It also runs from whoever hurt it in the last 10 seconds, while that attacker is within range, or within safe_distance once it is running. Each run plans a path of about ten blocks away from the scare. In a room or a pen with no way out that long, it backs off to the far wall.

SettingDefaultMeaning
fearsplayerplayer, hostile, passive, living, or an entity type such as wolf
range10How close a scare gets before it runs
safe_distance16How far away it stops running
speed1.5Speed while running
cornered_distance6How far it tries to back off where it finds no way out

wander​

It picks a spot up to radius blocks away, walks there, then rests. Every other shipped behavior takes the mob from it at once.

SettingDefaultMeaning
radius8How far a stroll goes
speed1Speed while strolling
rest_ticks60Rest after a stroll
rest_random_ticks120A random 0 to this many ticks, less one, added to each rest
walk_ticks200A stroll it cannot finish ends after this long

From a Lua script​

In every Lua script FreeMinecraftModels runs, the entity table of a mob has three more members. Player tables do not have them.

MemberReturnsDescription
mob:override_ai(behaviors, options?)true, or false and the reasonOverrides the mob's AI. behaviors is one name or a list of names. A mob that already has an override gets this one in its place
mob:restore_ai()boolGives the mob its own AI back. true when it had an override
mob.ai_overriddenboolWhether the mob runs an override now

options is a table, and every key is optional:

KeyMeaning
ownerAn entity table or a UUID string. Leave it out for a mob that serves nobody
durationHow long the override lasts, in ticks. Leave it out and it lasts until cleared
settingsA table of setting tables by behavior name, with the values that replace each behavior's defaults
local ok, why = mob:override_ai({ 'guardian', 'wander' }, {
owner = player,
duration = 600,
settings = { guardian = { chase_speed = 1.6, assist = false } }
})

override_ai returns false with the reason when a behavior name did not load, or when the entity cannot be overridden. An empty list, or an owner that is neither an entity table nor a UUID, raises an error. A setting the behavior does not have, or a value of the wrong type, is reported in the console and the default stays.

From EliteMobs scripts​

From the EliteMobs release after 10.9.14, the entity table of a mob has the same three members in EliteMobs scripts, boss powers included, when FreeMinecraftModels is installed. FreeMinecraftModels still runs the behaviors, from its own mob_behaviors folder.

  • Elites, bosses and EliteMobs NPCs are refused there, and override_ai returns false with the reason. A boss can make the mobs around it its guardians, but cannot be overridden itself.
  • The owner can be the boss: owner = context.boss.
  • Give the override a duration. It outlives the boss that started it.
  • Without FreeMinecraftModels, or with a version from before mob behaviors, override_ai returns false with the reason.
mob:override_ai('guardian', { owner = context.boss, duration = 600 })

From another plugin​

A plugin reaches mob behaviors in Java through com.magmaguy.freeminecraftmodels.api.MobBehaviorAPI. overrideAI(mob, behaviors, owner, durationTicks, settings) returns null, or the reason it refused. restoreAI(mob) and isAIOverridden(entity) return a boolean, and behaviors() lists the loaded names. Every parameter is a plain Java or Bukkit type, so a plugin that compiles against an older FreeMinecraftModels can look the methods up by name. Call them on the server thread.

Which mobs​

  • Any mob can be overridden, whatever spawned it. Players and armor stands cannot.
  • It is built for mobs that walk along paths: zombies, skeletons, creepers, pillagers, cows, chickens and their like. So far it has been tested on husks, creepers and chickens.
  • Mobs that do not walk along paths may move badly or not at all under an override. That covers slimes, magma cubes, ghasts, phantoms, rabbits, squid and fish.
  • Pets and other mobs that already run a behavior program, such as an EliteMobs boss with a behavior, cannot be overridden.
  • An EliteMobs elite without a behavior program is an ordinary mob to FreeMinecraftModels and takes an override, but that combination has not been tested yet.

Files​

  • Behaviors live in plugins/FreeMinecraftModels/mob_behaviors/, in that folder or any subfolder. Every .lua file there is a behavior.
  • A behavior's name is its file name without .lua. It may use only lower-case letters, digits, ., _ and -.
  • Its id must be fmm:mob/ followed by its name, so mob_behaviors/scared_of_cats.lua declares id = 'fmm:mob/scared_of_cats'. A file whose id does not match its name is left out with a warning.
  • When two files share a name, the one whose path sorts first loads and the console warns about the other.
  • FreeMinecraftModels writes each of its four behaviors when mob_behaviors/ has no file of that name directly in it. A deleted one comes back on the next start or /fmm reload. A file you edited is never overwritten. Moving one into a subfolder brings the default back beside it, and only the one whose path sorts first loads.
  • /fmm reload rereads every file. Running overrides stop and start again on the new files.

Writing a behavior​

A behavior file is a pet behavior module with a different id prefix: ai.module with settings, memories, behaviors and sensors. The shared rules are in EliteMobs Behavior Programs. Start from the shipped file closest to what you want, copy it under a new name, and change its id, its behavior ids and its memory names to start with the new name.

This behavior makes a mob run from cats:

-- Runs from the nearest cat within range.
return ai.module {
id = 'fmm:mob/scared_of_cats', revision = 1,
settings = { range = 8, speed = 1.4 },
behaviors = {
ai.behavior {
-- Asked and run every 5 ticks: each run plans a new way out.
id = 'fmm:mob/scared_of_cats', priority = 5, probe_interval = 5, tick_interval = 5,
controls = { ai.controls.move },
can_start = function(c)
return c.overlay:nearest(c.settings.range, 'cat') ~= nil
end,
tick = function(c)
local cat = c.overlay:nearest(c.settings.range, 'cat')
if cat ~= nil then c.actuator:flee(cat.current_location, c.settings.speed) end
end,
stop = function(c) c.actuator:stop_moving() end
}
}
}
  • The lower priority number goes first and takes the controls it lists from a running behavior with a higher number. The shipped behaviors use 5 for coward and for guardian's fight, 10 for hostile, 20 for guardian's follow and 40 for wander.
  • probe_interval is how often a stopped behavior is asked can_start, in ticks. tick_interval is how often a running one runs can_continue and tick. Both default to 1 and count as 200 above that.
  • Two behaviors on one mob cannot share a behavior id, a sensor id or a memory name. override_ai and the command refuse such a pair and say why.

What a callback gets​

NameWhat it is
c.overlayThe mob's place in the override. See c.overlay
c.settingsThis behavior's settings for this mob: its defaults with the override's values on top
c.memoryget(name), set(name, value), forget(name) and contains(name) for the names in memories. Each mob has its own
c.tickThe current game tick, for timers
c.entityThe mob's entity table, with current_location, health, entity_type and the rest
c.perception, c.actuatorMagmaCore's Mind context. See Mind program context

c.overlay​

The four entities are read afresh each time, so keep one in a local when a callback uses it more than once.

MemberWhat it gives or does
c.overlay.ownerThe owner's entity table while they are alive in the mob's world, else nil
c.overlay.owner_attackerWhoever hurt the owner in the last 10 seconds, or nil
c.overlay.owner_targetWhoever the owner hurt in the last 10 seconds, or nil
c.overlay.attackerWhoever hurt this mob in the last 10 seconds, or nil
c.overlay:nearest(radius, kind?)The nearest living entity of a kind within the radius, or nil. kind is player, hostile (monsters), passive (animals), living (the default), or an entity type by its Bukkit name, such as zombie or iron_golem. Villagers and golems are neither hostile nor passive. The radius reaches 128 blocks at most
c.overlay:entity(uuid)The living entity with that UUID while it is alive in the mob's world, else nil. For a behavior that keeps its target's UUID in a memory
c.overlay.remainingThe ticks the override has left, or nil when it has no end
c.overlay:finish()Ends the override once this tick is over, and the mob has its own AI back

owner_attacker, owner_target, attacker and nearest never give the mob's owner or another mob that serves the same owner. nearest also skips players in creative and spectator mode, and armor stands.

Moving and fighting​

These c.actuator calls do the work. Each needs its behavior to list the control named.

CallControlWhat it does
c.actuator:move_to(location, speed)moveWalks there along a path
c.actuator:flee(location, speed)movePlans a path of about ten blocks away from the location and follows it. false when the mob finds no way out or cannot plan paths. Call it every few ticks, not every tick
c.actuator:stop_moving()moveStops
c.actuator:look_at(location)lookTurns the head there for the next two ticks
c.actuator:attack(target)attackThe kind's own hit: a swing that deals the mob's attack damage, or 2 for a kind that has none. A creeper swells instead, for as long as the call comes every tick, and explodes once fully swollen. A tick without the call and it deflates
c.actuator:attack(target, damage)attackA swing that deals that much damage
c.actuator:shoot(target)attackThe kind's own shot: a skeleton's arrow, a pillager's crossbow, a witch's potion, a llama's spit. false for a kind that has none

flee, shoot and attack with a damage are new with mob behaviors, and work in pet behavior modules too, where flee needs a body that plans paths and shoot a body whose kind shoots.

Rules​

  • Call the actuator only from a behavior's start, tick or stop, in a behavior that lists the control it needs.
  • Keep per-mob state in c.memory, declared under memories, with names that start with the behavior's name.
  • Keep callbacks short. Mob behaviors run under the same limits as pet behavior modules, and share the 10 ms a tick with them.

When something is wrong​

Nothing here stops the server or the other mobs. Search the console, ignoring case, for mob behavior.

  • A behavior does not load. A file that does not compile, whose id does not match its file name, or whose name has other characters is left out with a warning naming the file and the reason. Every other file still loads.
  • The command or override_ai refuses. It says why: a behavior name that did not load, with the ones that did, or an entity that cannot be overridden.
  • The mob stands still. Its behaviors have nothing to do. Add wander, or check that you are in survival and not the mob's owner.
  • A callback fails while mobs run. It is logged once per callback and kind of failure until the next reload. The behavior is stopped, or not started, and asked again at its next probe_interval check.
  • A mob could not take its override up again. When its chunk loads and one of its behaviors no longer exists, the console says so and the mob keeps its own AI. The override comes back once the file is back and /fmm reload has run: at once on loaded mobs, and on the others when they load.

After a fix, run /fmm reload.