Lua Scripting: Behavior Programs
A behavior program replaces a mob's native AI with Lua behaviors that decide where it moves, what it looks at, which entity it targets and when it attacks. EliteMobs runs these programs on Minecraft's native Brain system through MagmaCore's Mind runtime.
Behavior programs are not Lua powers. A Lua power reacts to boss events such as on_boss_damaged_by_player; a behavior program runs every tick and owns the mob's movement controls. A boss can use both: a behavior can ask the boss's powers to perform an action through on_mind_action.
FreeMinecraftModels pet behaviors are ai.module files in the same format and follow the same rules. See Pet Behavior Modules for the pet-specific parts, including the c.pet and c.settings context fields. FreeMinecraftModels mob behaviors, which take over a mob the plugin did not spawn, are the same kind of file again, with c.overlay and c.settings.
FreeMinecraftModels mob behaviors need the FreeMinecraftModels release after 2.15.0.
Set behavior in a custom boss file, as described in Creating Bosses, or in the entity type's mob-properties file. behavior: native keeps vanilla AI. If the server version has no native Mind support, EliteMobs logs Native Mind interface is unavailable on this Minecraft version. at startup. A custom boss that selects a program then does not spawn and logs Cannot spawn <boss file>: .... A boss whose behavior names a missing or invalid program fails the same way on any version.
Files
Behavior files live in plugins/EliteMobs/behaviors/. EliteMobs writes these bundled files when they are missing:
plugins/
EliteMobs/
behaviors/
basic_melee.lua
modules/
target.lua
pursuit.lua
melee.lua
wander.lua
- A
.luafile inside any folder namedmodulesis a module. Every other.luafile is a program. - A boss references a program by its path relative to
behaviors/, for examplebasic_melee.luaorguards/patrol_guard.lua. - EliteMobs loads behavior files when its Mind service starts. A file that fails validation is skipped and the console logs
Could not load behavior <file>orCould not load behavior module <file>with the reason. - Program and module ids use the
elitemobsnamespace, such aselitemobs:behavior/basic_melee. Ids are lowercase and may containa-z,0-9,.,_and-, plus/after the colon. Two programs cannot share an id, and each module id should be declared by one file. - One namespace holds at most 256 modules. A module can list at most 32 dependencies, a program can resolve at most 64 modules, and each source file is limited to 1,000,000 characters.
Sandbox and loading
The same sandbox rules as other Lua scripts apply. See the Lua Sandbox. Behavior files differ in two ways:
coroutineis not available.xpcallnever calls its message handler. It returnsfalseand the plain error message, so usepcall.
Each file is compiled when it loads, not for each mob, and its top-level code runs then to check it. Each mob that runs a program gets its own Lua environment and runs the top-level code of the program and its modules again, so file-local variables are not shared between mobs. A global variable that a file sets is visible only to that file. Every run must return the same id, revision and modules or dependencies.
The top-level code of a program and all its modules shares one allowance of 250,000 Lua instructions and 50 milliseconds of CPU time. If another Lua call is already running when the program starts, for example a script that spawns the mob, the top-level code uses that call's remaining allowance instead. Keep top-level code to definitions and constants.
Program File
A program file returns ai.program { ... }:
return ai.program {
id = 'elitemobs:behavior/basic_melee', revision = 1,
modules = {
'elitemobs:behavior/target', 'elitemobs:behavior/pursuit',
'elitemobs:behavior/melee', 'elitemobs:behavior/wander'
},
budget = {
callback_micros = 2000, entity_micros = 4000, server_micros = 5000,
max_callbacks = 20, max_instructions = 12000, max_action_requests = 2
}
}
| Field | Type | Notes |
|---|---|---|
id | string | Required. Namespaced id, elitemobs:... for files in behaviors/. It cannot be the id of one of the program's modules. |
revision | positive integer | Required. |
modules | array of strings | Optional. Module ids whose memories, sensors and behaviors join the program. Dependencies load before the modules that need them. Duplicates and dependency cycles are rejected. |
memories, sensors, behaviors | tables | Optional. A program can declare its own, in the same format as a module. |
budget | table | Optional soft scheduling limits. See Budgets. |
runaway | table | Optional hard per-callback limits. See Budgets. |
Module File
A module file returns ai.module { ... } and groups reusable memories, sensors and behaviors:
| Field | Type | Notes |
|---|---|---|
id | string | Required. Namespaced module id. |
revision | positive integer | Required. |
dependencies | array of strings | Optional. Other module ids this module needs. |
memories | table | Optional. See Memories. |
sensors | array | Optional. ai.sensor { ... } entries. |
behaviors | array | Optional. ai.behavior { ... } entries. |
settings | table | Optional. Named default values a host plugin can override per creature. See Module settings. |
sensors, behaviors, modules and dependencies must be plain arrays without gaps or named keys. Sensor, behavior and memory names must be unique across every module in a program.
Module settings
settings declares a module's tunable values and their defaults:
settings = {
radius = 8,
glow = true,
mode = 'circle',
foods = { 'minecraft:apple', 'minecraft:carrot' }
}
| Value | Example |
|---|---|
| finite number | radius = 8 |
true or false | glow = true |
| text | mode = 'circle' |
| list of text | foods = { 'minecraft:apple' } |
Every key must be a name. A list must be a plain array of text without gaps or named keys. Any other value, such as a function or a table of named values, rejects the module. The table is read as written; a metatable on it is ignored.
MagmaCore only checks the defaults and hands them to the host plugin, which decides how scripts see them. EliteMobs does not read module settings, so they have no effect in behaviors/ files. FreeMinecraftModels pets merge each creature's values over the defaults and give a module's callbacks its own settings as c.settings. See Pet Behavior Modules. FreeMinecraftModels mob behaviors, which need the FreeMinecraftModels release after 2.15.0, do the same with the values an override gives; see Mob Behaviors.
Memories
Memories are typed values that sensors and behaviors share for one mob. Declare each one by name:
memories = {
candidate = { type = 'uuid', persistent = false },
next_attack = 'integer'
}
| Type | Lua value |
|---|---|
string | string |
boolean | boolean |
integer | whole number |
number | number |
uuid | UUID string |
position | { world = 'world', x = 0, y = 64, z = 0 } |
A name without a colon is placed in the program's namespace. persistent defaults to false; true marks the memory for serialization with the Mind's saved state. Read and write memories through c.memory:get(name), c.memory:set(name, value, ttl_ticks), c.memory:forget(name) and c.memory:contains(name). The third set argument is optional; when supplied, the value expires after that many ticks. Using an undeclared name raises an error.
Sensors
A sensor gathers information, usually into memories. Sensors run before behaviors.
ai.sensor {
id = 'elitemobs:behavior/find_target', interval = 20,
sense = function(c)
local target = c.perception:nearest_player(35)
if target then c.memory:set('candidate', target.uuid, 21)
else c.memory:forget('candidate') end
end
}
| Field | Type | Default | Notes |
|---|---|---|---|
id | string | Required. | |
interval | positive integer | 1 | Ticks between runs. |
sense | function | Required. Receives the Mind context. |
Sensors cannot use c.actuator; calling an actuator method from a sensor raises an error.
Sensor timing
A sensor runs on the first tick its mob's body is ticked: after a spawn, a chunk load or a program change. After that it runs every interval ticks, on a phase of its own for each mob, so mobs created together do not all sense on the same tick. The second run comes up to one interval after the first. A run skipped because the mob reached a budget is retried on the next tick and then returns to its phase.
Behaviors
A behavior acts on the mob while it holds the controls it declares.
ai.behavior {
id = 'elitemobs:behavior/attack', priority = 10,
controls = { ai.controls.attack },
can_start = function(c) return c.perception:current_target() ~= nil end,
can_continue = function(c) return c.perception:current_target() ~= nil end,
tick = function(c)
local target = c.perception:current_target()
if target then c.actuator:attack(target) end
end
}
| Field | Type | Default | Notes |
|---|---|---|---|
id | string | Required. | |
priority | integer | 0 | Lower numbers take precedence. |
controls | array | none | Controls this behavior leases while it runs. |
probe_interval | whole number | 1 | Ticks between can_start checks while the behavior is stopped. At least 1; values above 200 count as 200. See Probe interval. |
can_start | function | always true | Must return true or false. |
can_continue | function | same as can_start | Must return true or false. |
start | function | none | Runs once when the behavior starts. |
tick_interval | whole number | 1 | Ticks between runs of can_continue and tick while the behavior runs. At least 1; values above 200 count as 200. Needs the EliteMobs release after 10.9.14, or the FreeMinecraftModels release after 2.15.0. |
tick | function | Required. Runs every tick while the behavior runs, or every tick_interval ticks. | |
stop | function | none | function(c, reason); runs when the behavior stops. |
Lifecycle
- While stopped, the behavior checks
can_startevery tick, or everyprobe_intervalticks. When it returnstrueand the behavior can lease every declared control,startruns. - On every tick while it runs, or every
tick_intervalticks, and always on the tick it started,can_continueruns first. When it returnsfalse, the behavior stops with reasoncompleted; otherwisetickruns. stop(c, reason)receives one ofcompleted,preempted,program_replaced,entity_removed,callback_failedorhandle_closed. Stopping releases the behavior's controls and halts the movement, target or attack it held.
A Lua error in can_continue, start or tick stops the behavior with callback_failed. Returning anything other than a boolean from can_start or can_continue is an error. The console logs Mind <program> callback <callback> failed with ... for each failure.
Probe interval
By default a stopped behavior checks can_start on every tick. With probe_interval = N it checks every N ticks instead, on a phase of its own for each mob, so a crowd of mobs with the same behavior, or one mob's several behaviors, do not all check on the same tick. Use it when the start condition is costly or does not need an answer on the exact tick.
- The first check after the body starts ticking waits for the behavior's phase, up to N - 1 ticks.
- A behavior starts, and takes controls from another behavior, up to N - 1 ticks after it could have.
- A behavior that stops is checked again on its next phase tick, up to N ticks later.
- A check skipped because the mob reached a budget, or a start deferred by one, is retried on the next tick and then returns to the phase.
- Nothing changes while the behavior runs:
can_continueandtickstill run every tick, or everytick_intervalticks, andstopis not delayed. A behavior withoutcan_continuestill callscan_startevery tick while it runs, becausecan_continuedefaults tocan_start.
The value must be a number with no fractional part, 1 or more; anything else rejects the file. Values above 200 (10 seconds) count as 200.
Controls
| Control | Allows |
|---|---|
ai.controls.move | c.actuator:move_to(...), c.actuator:flee(...), c.actuator:stop_moving() |
ai.controls.look | c.actuator:look_at(...) |
ai.controls.move and ai.controls.look together | c.actuator:steer_flight(...) |
ai.controls.jump | c.actuator:jump() |
ai.controls.target | c.actuator:set_target(...), c.actuator:clear_target() |
ai.controls.attack | c.actuator:attack(...), c.actuator:shoot(...) |
ai.controls.action | c.actions:request(...) |
ai.controls.use_item | Reserved; the Lua actuator has no item method. |
Each control belongs to one running behavior at a time. A behavior with a lower priority number takes a control from a behavior with a higher number, which stops with reason preempted. It cannot take a control held by a behavior with a lower number. Between equal priorities, the behavior whose id sorts first alphabetically wins the control. Calling an actuator method without holding its control raises an error. c.actuator:stop_all() stops only what the behavior holds.
In the bundled modules, target selection uses priority 5, melee attacks 10, pursuit 20 and idle wandering 50, so pursuit takes movement from wandering as soon as a target exists.
Fleeing, shooting and setting the damage
These three calls need the EliteMobs release after 10.9.14.
c.actuator:flee(location, speed)plans a path of about ten blocks that leads away from the location and follows it. It returnsfalsewhen the body cannot plan paths, finds no way out that long, or another system is controlling its movement. Planning tries several ways out, so call it every few ticks; the path is followed in between.c.actuator:shoot(target)makes the ranged attack of the body's own kind: a skeleton's arrow, a witch's potion, or a pillager's crossbow, which is loaded first when it is empty. It returnsfalsefor a kind that has none.c.actuator:attack(target, damage)swings and deals that much damage, credited to the body, instead of the body's own attack damage.
Steering flight
c.actuator:steer_flight(x, y, z) moves a flying body by that velocity, in blocks per tick, for the current tick only. Call it on every tick the mob should keep flying; on a tick without a call, the body moves by its normal navigation again. The call stops any path started with move_to, collides with blocks, and turns the body toward its horizontal travel by at most 8 degrees per tick. A velocity longer than 4 blocks per tick (80 blocks per second) is scaled down to 4 in the same direction.
The behavior must hold both ai.controls.move and ai.controls.look. A missing control or a value that is not a finite number raises an error. The call returns false and does nothing when the body cannot fly or another system is controlling its movement, and true otherwise. EliteMobs gives flying mob types, such as bats, blazes, ghasts, phantoms and vexes, a flying body.
Requesting boss actions
A behavior holding ai.controls.action can call c.actions:request(identifier, payload). EliteMobs sends the request to the boss's Lua powers through on_mind_action. The identifier must be a lowercase namespaced key of at most 128 characters, such as 'elitemobs:slam'. The payload holds at most 16 entries with lowercase keys of at most 64 characters, and string values are limited to 256 characters; an invalid identifier or payload raises an error. The call returns accepted, deferred or rejected; requests beyond the program's max_action_requests in one tick return deferred. See the Mind action context for the payload format.
Budgets
budget sets soft scheduling limits. When a mob reaches one in a tick, the Mind runtime skips that mob's remaining callbacks until the next tick. A callback that is already running always finishes. A skipped sensor run or can_start check is retried on the next tick.
| Key | Default | Notes |
|---|---|---|
callback_micros | 2000 | A callback that runs longer than this ends the mob's callbacks for the tick. |
entity_micros | 4000 | Total callback time per mob per tick. |
server_micros | 20000 | The mob's callbacks stop for the tick once all Mind programs together have used this much time. |
max_callbacks | 128 | Callbacks per mob per tick. |
max_action_requests | 8 | Action requests per mob per tick; at most 64. |
All values must be positive, and callback_micros cannot exceed entity_micros, which cannot exceed server_micros.
runaway sets hard limits that interrupt a single callback:
| Key | Default | Maximum | Notes |
|---|---|---|---|
cpu_micros | 50000 | 50000 | Thread CPU time per callback. |
max_instructions | 50000 | 250000 | Lua instructions per callback. |
budget also accepts max_instructions, as in the bundled basic_melee.lua. Declare it in budget or runaway, not both. Both limits must be positive. A larger value still loads, but it is lowered to the maximum without a warning.
The limits stop a callback while it runs, so a loop that never ends fails instead of hanging the server. Instructions are counted as they run; CPU time is checked every 1,024 instructions and when the callback returns. If the server cannot measure thread CPU time, cpu_micros limits elapsed time at five times its value. A callback that exceeds a runaway limit fails like any other callback error, and the console line reads failed with RUNAWAY_LIMIT_EXCEEDED.
Next Steps
- Creating Bosses: behavior -- selecting a program for a boss
- Lua API Reference: Mind program context -- every
c.memory,c.perception,c.actuatorandc.actionsmethod - Hooks & Lifecycle --
on_mind_actionand the other Lua power hooks - FreeMinecraftModels Pet Behavior Modules -- pet behavior modules and their
c.petandc.settingsfields
