Skip to main content

Lua Scripting: Behavior Programs

webapp_banner.jpg

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.

Build availability

FreeMinecraftModels mob behaviors need the FreeMinecraftModels release after 2.15.0.

Selecting a program

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 .lua file inside any folder named modules is a module. Every other .lua file is a program.
  • A boss references a program by its path relative to behaviors/, for example basic_melee.lua or guards/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> or Could not load behavior module <file> with the reason.
  • Program and module ids use the elitemobs namespace, such as elitemobs:behavior/basic_melee. Ids are lowercase and may contain a-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:

  • coroutine is not available.
  • xpcall never calls its message handler. It returns false and the plain error message, so use pcall.

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
}
}
FieldTypeNotes
idstringRequired. Namespaced id, elitemobs:... for files in behaviors/. It cannot be the id of one of the program's modules.
revisionpositive integerRequired.
modulesarray of stringsOptional. 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, behaviorstablesOptional. A program can declare its own, in the same format as a module.
budgettableOptional soft scheduling limits. See Budgets.
runawaytableOptional hard per-callback limits. See Budgets.

Module File​

A module file returns ai.module { ... } and groups reusable memories, sensors and behaviors:

FieldTypeNotes
idstringRequired. Namespaced module id.
revisionpositive integerRequired.
dependenciesarray of stringsOptional. Other module ids this module needs.
memoriestableOptional. See Memories.
sensorsarrayOptional. ai.sensor { ... } entries.
behaviorsarrayOptional. ai.behavior { ... } entries.
settingstableOptional. 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' }
}
ValueExample
finite numberradius = 8
true or falseglow = true
textmode = 'circle'
list of textfoods = { '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'
}
TypeLua value
stringstring
booleanboolean
integerwhole number
numbernumber
uuidUUID 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
}
FieldTypeDefaultNotes
idstringRequired.
intervalpositive integer1Ticks between runs.
sensefunctionRequired. 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
}
FieldTypeDefaultNotes
idstringRequired.
priorityinteger0Lower numbers take precedence.
controlsarraynoneControls this behavior leases while it runs.
probe_intervalwhole number1Ticks between can_start checks while the behavior is stopped. At least 1; values above 200 count as 200. See Probe interval.
can_startfunctionalways trueMust return true or false.
can_continuefunctionsame as can_startMust return true or false.
startfunctionnoneRuns once when the behavior starts.
tick_intervalwhole number1Ticks 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.
tickfunctionRequired. Runs every tick while the behavior runs, or every tick_interval ticks.
stopfunctionnonefunction(c, reason); runs when the behavior stops.

Lifecycle​

  1. While stopped, the behavior checks can_start every tick, or every probe_interval ticks. When it returns true and the behavior can lease every declared control, start runs.
  2. On every tick while it runs, or every tick_interval ticks, and always on the tick it started, can_continue runs first. When it returns false, the behavior stops with reason completed; otherwise tick runs.
  3. stop(c, reason) receives one of completed, preempted, program_replaced, entity_removed, callback_failed or handle_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_continue and tick still run every tick, or every tick_interval ticks, and stop is not delayed. A behavior without can_continue still calls can_start every tick while it runs, because can_continue defaults to can_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​

ControlAllows
ai.controls.movec.actuator:move_to(...), c.actuator:flee(...), c.actuator:stop_moving()
ai.controls.lookc.actuator:look_at(...)
ai.controls.move and ai.controls.look togetherc.actuator:steer_flight(...)
ai.controls.jumpc.actuator:jump()
ai.controls.targetc.actuator:set_target(...), c.actuator:clear_target()
ai.controls.attackc.actuator:attack(...), c.actuator:shoot(...)
ai.controls.actionc.actions:request(...)
ai.controls.use_itemReserved; 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​

Build availability

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 returns false when 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 returns false for 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.

KeyDefaultNotes
callback_micros2000A callback that runs longer than this ends the mob's callbacks for the tick.
entity_micros4000Total callback time per mob per tick.
server_micros20000The mob's callbacks stop for the tick once all Mind programs together have used this much time.
max_callbacks128Callbacks per mob per tick.
max_action_requests8Action 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:

KeyDefaultMaximumNotes
cpu_micros5000050000Thread CPU time per callback.
max_instructions50000250000Lua 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​