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.
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.
| Command | Purpose |
|---|---|
/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 clear | Gives the mob in your crosshair its own AI back |
/fmm mobbehavior clear all | Gives 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 list | Lists the behaviors that loaded and how many mobs run one |
behaviorsis one name, or several joined by commas with no spaces, such ascoward,wander.secondsis how long the override lasts. Leave it out, or use0, and it lasts until cleared.- A mob never attacks or fears its owner. To try
hostileorcowardon yourself, useapplywild. hostileandcowarddo 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
| Name | What the mob does |
|---|---|
guardian | Stays near its owner and fights whoever hurts them, whoever they hurt, and whoever hurts it |
hostile | Attacks the nearest player, or whatever its targets setting names |
coward | Runs from the nearest player, or whatever its fears setting names |
wander | Strolls 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.
| Setting | Default | Meaning |
|---|---|---|
follow_distance | 6 | How far the owner gets before the mob comes after them |
follow_stop | 3 | How close it comes |
follow_speed | 1.2 | Speed while following |
chase_speed | 1.3 | Speed while fighting |
reach | 2.2 | How close it gets to hit |
fuse_distance | 3 | A creeper starts its fuse within this distance of its target |
fuse_escape | 7 | A creeper's fuse goes out when the target gets this far, or out of sight |
shoot_distance | 12 | A mob that shoots does so from within this distance, while it can see the target |
attack_ticks | 20 | Time between two hits or shots |
assist | true | Also fights whoever the owner hurts |
defend_itself | true | Also 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.
| Setting | Default | Meaning |
|---|---|---|
targets | player | player, hostile, passive, living, or an entity type such as zombie |
range | 16 | How far it notices targets |
damage | 0 | What 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_ticks | as guardian | As 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.
| Setting | Default | Meaning |
|---|---|---|
fears | player | player, hostile, passive, living, or an entity type such as wolf |
range | 10 | How close a scare gets before it runs |
safe_distance | 16 | How far away it stops running |
speed | 1.5 | Speed while running |
cornered_distance | 6 | How 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.
| Setting | Default | Meaning |
|---|---|---|
radius | 8 | How far a stroll goes |
speed | 1 | Speed while strolling |
rest_ticks | 60 | Rest after a stroll |
rest_random_ticks | 120 | A random 0 to this many ticks, less one, added to each rest |
walk_ticks | 200 | A 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.
| Member | Returns | Description |
|---|---|---|
mob:override_ai(behaviors, options?) | true, or false and the reason | Overrides 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() | bool | Gives the mob its own AI back. true when it had an override |
mob.ai_overridden | bool | Whether the mob runs an override now |
options is a table, and every key is optional:
| Key | Meaning |
|---|---|
owner | An entity table or a UUID string. Leave it out for a mob that serves nobody |
duration | How long the override lasts, in ticks. Leave it out and it lasts until cleared |
settings | A 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_aireturnsfalsewith the reason. A boss can make the mobs around it its guardians, but cannot be overridden itself. - The
ownercan 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_aireturnsfalsewith 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.luafile there is a behavior. - A behavior's name is its file name without
.lua. It may use only lower-case letters, digits,.,_and-. - Its
idmust befmm:mob/followed by its name, somob_behaviors/scared_of_cats.luadeclaresid = '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 reloadrereads 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
prioritynumber goes first and takes the controls it lists from a running behavior with a higher number. The shipped behaviors use5forcowardand forguardian's fight,10forhostile,20forguardian's follow and40forwander. probe_intervalis how often a stopped behavior is askedcan_start, in ticks.tick_intervalis how often a running one runscan_continueandtick. Both default to1and count as200above that.- Two behaviors on one mob cannot share a behavior id, a sensor id or a memory name.
override_aiand the command refuse such a pair and say why.
What a callback gets
| Name | What it is |
|---|---|
c.overlay | The mob's place in the override. See c.overlay |
c.settings | This behavior's settings for this mob: its defaults with the override's values on top |
c.memory | get(name), set(name, value), forget(name) and contains(name) for the names in memories. Each mob has its own |
c.tick | The current game tick, for timers |
c.entity | The mob's entity table, with current_location, health, entity_type and the rest |
c.perception, c.actuator | MagmaCore'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.
| Member | What it gives or does |
|---|---|
c.overlay.owner | The owner's entity table while they are alive in the mob's world, else nil |
c.overlay.owner_attacker | Whoever hurt the owner in the last 10 seconds, or nil |
c.overlay.owner_target | Whoever the owner hurt in the last 10 seconds, or nil |
c.overlay.attacker | Whoever 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.remaining | The 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.
| Call | Control | What it does |
|---|---|---|
c.actuator:move_to(location, speed) | move | Walks there along a path |
c.actuator:flee(location, speed) | move | Plans 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() | move | Stops |
c.actuator:look_at(location) | look | Turns the head there for the next two ticks |
c.actuator:attack(target) | attack | The 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) | attack | A swing that deals that much damage |
c.actuator:shoot(target) | attack | The 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,tickorstop, in a behavior that lists the control it needs. - Keep per-mob state in
c.memory, declared undermemories, 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_airefuses. 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_intervalcheck. - 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 reloadhas run: at once on loaded mobs, and on the others when they load.
After a fix, run /fmm reload.