Lua 脚本:行为程序
行为程序用 Lua 行为取代怪物的原生 AI,由这些行为决定它往哪里移动、看向哪里、以哪个实体为目标以及何时攻击。EliteMobs 通过 MagmaCore 的 Mind 运行时,在 Minecraft 原生的 Brain 系统上运行这些程序。
行为程序不是 Lua 能力。Lua 能力对 on_boss_damaged_by_player 等 Boss 事件作出反应;行为程序则每个 tick 都会运行,并掌控怪物的移动控制。一个 Boss 可以同时使用两者:行为可以通过 on_mind_action 请求 Boss 的能力执行某个动作。
FreeMinecraftModels 的宠物行为是格式相同、规则相同的 ai.module 文件。宠物特有的部分(包括 c.pet 和 c.settings 上下文字段)参见宠物行为模块。FreeMinecraftModels 的怪物行为会接管并非由该插件生成的怪物,它们同样是这种文件,带有 c.overlay 和 c.settings。
FreeMinecraftModels 的怪物行为需要 2.15.0 之后的 FreeMinecraftModels 版本。
在自定义 Boss 文件中设置 behavior(参见创建 Boss),或在该实体类型的怪物属性文件中设置。behavior: native 保留原版 AI。如果服务器版本不支持原生 Mind,EliteMobs 会在启动时记录 Native Mind interface is unavailable on this Minecraft version.。此时选择了程序的自定义 Boss 不会生成,并记录 Cannot spawn <boss file>: ...。无论在哪个版本上,如果 Boss 的 behavior 指向缺失或无效的程序,也会以同样的方式失败。
文件
行为文件位于 plugins/EliteMobs/behaviors/。以下内置文件缺失时,EliteMobs 会写入它们:
plugins/
EliteMobs/
behaviors/
basic_melee.lua
modules/
target.lua
pursuit.lua
melee.lua
wander.lua
- 位于任何名为
modules的文件夹中的.lua文件是模块。其他所有.lua文件都是程序。 - Boss 通过相对于
behaviors/的路径引用程序,例如basic_melee.lua或guards/patrol_guard.lua。 - EliteMobs 会在其 Mind 服务启动时加载行为文件。未通过验证的文件会被跳过,控制台会记录
Could not load behavior <file>或Could not load behavior module <file>以及原因。 - 程序和模块 ID 使用
elitemobs命名空间,例如elitemobs:behavior/basic_melee。ID 为小写,可以包含a-z、0-9、.、_和-,冒号之后还可以包含/。两个程序不能共用同一个 ID,每个模块 ID 也应只由一个文件声明。 - 一个命名空间最多容纳 256 个模块。一个模块最多可以列出 32 个依赖,一个程序最多可以解析 64 个模块,每个源文件的长度限制为 1,000,000 个字符。
沙盒与加载
与其他 Lua 脚本相同的沙盒规则同样适用,参见 Lua 沙盒。行为文件有两处不同:
coroutine不可用。xpcall从不调用它的消息处理函数。它返回false和纯错误消息,因此请使用pcall。
每个文件在加载时编译一次,而不是为每只怪物各编译一次,并且其顶层代码会在那时运行以进行检查。每个运行程序的怪物都有自己的 Lua 环境,并会再次运行该程序及其模块的顶层代码,因此文件内的局部变量不会在怪物之间共享。文件设置的全局变量只对该文件可见。每次运行都必须返回相同的 id、revision 以及 modules 或 dependencies。
程序及其所有模块的顶层代码共用 250,000 条 Lua 指令和 50 毫秒 CPU 时间的额度。如果程序启动时已有另一个 Lua 调用正在运行,例如生成该怪物的脚本,顶层代码会改用该调用的剩余额度。请把顶层代码限制在定义和常量上。
程序文件
程序文件返回 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
}
}
| 字段 | 类型 | 说明 |
|---|---|---|
id | 字符串 | 必填。带命名空间的 ID,behaviors/ 中的文件使用 elitemobs:...。它不能是该程序任何一个模块的 ID。 |
revision | 正整数 | 必填。 |
modules | 字符串数组 | 可选。要加入该程序的模块 ID,其记忆、传感器和行为都会并入程序。依赖会先于需要它们的模块加载。重复项和循环依赖会被拒绝。 |
memories、sensors、behaviors | 表 | 可选。程序可以用与模块相同的格式声明自己的这些内容。 |
budget | 表 | 可选的软性调度限制。参见预算。 |
runaway | 表 | 可选的单次回调硬性限制。参见预算。 |
模块文件
模块文件返回 ai.module { ... },用于组织可复用的记忆、传感器和行为:
| 字段 | 类型 | 说明 |
|---|---|---|
id | 字符串 | 必填。带命名空间的模块 ID。 |
revision | 正整数 | 必填。 |
dependencies | 字符串数组 | 可选。该模块需要的其他模块 ID。 |
memories | 表 | 可选。参见记忆。 |
sensors | 数组 | 可选。ai.sensor { ... } 条目。 |
behaviors | 数组 | 可选。ai.behavior { ... } 条目。 |
settings | 表 | 可选。宿主插件可以按生物覆盖的命名默认值。参见模块设置。 |
sensors、behaviors、modules 和 dependencies 必须是没有空位、也没有命名键的普通数组。传感器、行为和记忆的名称在一个程序的所有模块中必须唯一。
模块设置
settings 声明模块的可调值及其默认值:
settings = {
radius = 8,
glow = true,
mode = 'circle',
foods = { 'minecraft:apple', 'minecraft:carrot' }
}
| 值 | 示例 |
|---|---|
| 有限数字 | radius = 8 |
true 或 false | glow = true |
| 文本 | mode = 'circle' |
| 文本列表 | foods = { 'minecraft:apple' } |
每个键都必须是名称。列表必须是只包含文本、没有空位也没有命名键的普通数组。任何其他值(例如函数或带命名值的表)都会使该模块被拒绝。该表按书写内容读取;其上的元表会被忽略。
MagmaCore 只检查这些默认值并将其交给宿主插件,由宿主插件决定脚本如何看到它们。EliteMobs 不读取模块设置,因此它们在 behaviors/ 文件中没有任何效果。FreeMinecraftModels 的宠物会把每个生物的值合并到默认值之上,并把模块自己的设置作为 c.settings 提供给该模块的回调。参见宠物行为模块。FreeMinecraftModels 的怪物行为(需要 2.15.0 之后的 FreeMinecraftModels 版本)对一次接管给出的值也是如此处理;参见怪物行为。
记忆
记忆是带类型的值,供同一只怪物的传感器和行为共享。按名称声明每一项:
memories = {
candidate = { type = 'uuid', persistent = false },
next_attack = 'integer'
}
| 类型 | Lua 值 |
|---|---|
string | 字符串 |
boolean | 布尔值 |
integer | 整数 |
number | 数字 |
uuid | UUID 字符串 |
position | { world = 'world', x = 0, y = 64, z = 0 } |
不含冒号的名称会被放入程序的命名空间。persistent 默认为 false;设为 true 会将该记忆标记为随 Mind 的已保存状态一起序列化。通过 c.memory:get(name)、c.memory:set(name, value, ttl_ticks)、c.memory:forget(name) 和 c.memory:contains(name) 读写记忆。set 的第三个参数是可选的;提供时,该值会在经过相应 tick 数后过期。使用未声明的名称会抛出错误。
传感器
传感器负责收集信息,通常写入记忆中。传感器在行为之前运行。
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
}
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
id | 字符串 | 必填。 | |
interval | 正整数 | 1 | 两次运行之间间隔的 tick 数。 |
sense | 函数 | 必填。接收 Mind 上下文。 |
传感器不能使用 c.actuator;在传感器中调用执行器方法会抛出错误。
传感器时序
传感器在其怪物的身体第一次被 tick 的那个 tick 运行:即生成、区块加载或程序变更之后。此后它每隔 interval 个 tick 运行一次,且每只怪物有各自的相位,因此同时创建的怪物不会都在同一个 tick 感知。第二次运行最晚在第一次之后一个 interval 发生。因怪物达到预算而被跳过的运行会在下一个 tick 重试,然后回到它自己的相位。
行为
行为在持有其声明的控制权期间对怪物施加作用。
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
}
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
id | 字符串 | 必填。 | |
priority | 整数 | 0 | 数字越小,优先级越高。 |
controls | 数组 | 无 | 该行为运行期间租用的控制权。 |
probe_interval | 整数 | 1 | 行为处于停止状态时,两次 can_start 检查之间间隔的 tick 数。至少为 1;大于 200 的值按 200 计。参见探测间隔。 |
can_start | 函数 | 始终为 true | 必须返回 true 或 false。 |
can_continue | 函数 | 与 can_start 相同 | 必须返回 true 或 false。 |
start | 函数 | 无 | 行为启动时运行一次。 |
tick_interval | 整数 | 1 | 行为运行期间,两次 can_continue 和 tick 运行之间间隔的 tick 数。至少为 1;大于 200 的值按 200 计。需要 10.9.14 之后的 EliteMobs 版本,或 2.15.0 之后的 FreeMinecraftModels 版本。 |
tick | 函数 | 必填。行为运行期间每个 tick 运行一次,或每 tick_interval 个 tick 运行一次。 | |
stop | 函数 | 无 | function(c, reason);行为停止时运行。 |
生命周期
- 停止状态下,行为会每个 tick 或每
probe_interval个 tick 检查一次can_start。当它返回true且该行为能够租用所有声明的控制权时,start就会运行。 - 运行期间的每个 tick,或每
tick_interval个 tick,并且始终在启动的那个 tick,都会先运行can_continue。它返回false时,行为以原因completed停止;否则运行tick。 stop(c, reason)会收到completed、preempted、program_replaced、entity_removed、callback_failed或handle_closed之一。停止会释放该行为的控制权,并中止它所掌控的移动、目标或攻击。
can_continue、start 或 tick 中的 Lua 错误会使行为以 callback_failed 停止。can_start 或 can_continue 返回布尔值以外的任何内容都属于错误。每次失败时,控制台都会记录 Mind <program> callback <callback> failed with ...。
探测间隔
默认情况下,处于停止状态的行为在每个 tick 都会检查 can_start。设置 probe_interval = N 后,它改为每 N 个 tick 检查一次,且每只怪物有各自的相位,因此大量带有相同行为的怪物,或同一只怪物的多个行为,不会都在同一个 tick 检查。当启动条件开销较大,或不需要在精确的那个 tick 得到答案时,请使用它。
- 身体开始被 tick 之后的第一次检查要等到该行为的相位,最多 N - 1 个 tick。
- 行为的启动,以及从另一个行为手中夺取控制权,最多比本可以发生的时间晚 N - 1 个 tick。
- 停止的行为会在其下一个相位 tick 再次被检查,最多 N 个 tick 之后。
- 因怪物达到预算而被跳过的检查,或被预算推迟的启动,会在下一个 tick 重试,然后回到该相位。
- 行为运行期间一切照旧:
can_continue和tick仍然每个 tick 运行,或每tick_interval个 tick 运行,stop也不会被延迟。没有can_continue的行为在运行期间仍会每个 tick 调用can_start,因为can_continue默认等于can_start。
该值必须是没有小数部分的数字,且为 1 或更大;其他任何值都会使文件被拒绝。大于 200(10 秒)的值按 200 计。
控制权
| 控制权 | 允许 |
|---|---|
ai.controls.move | c.actuator:move_to(...)、c.actuator:flee(...)、c.actuator:stop_moving() |
ai.controls.look | c.actuator:look_at(...) |
ai.controls.move 和 ai.controls.look 一起 | 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 | 保留;Lua 执行器没有物品相关的方法。 |
每项控制权同一时间只属于一个正在运行的行为。priority 数字较小的行为会从数字较大的行为手中夺取控制权,后者以原因 preempted 停止。它无法夺取数字更小的行为所持有的控制权。优先级相同时,id 按字母顺序排在前面的行为获得控制权。在未持有对应控制权的情况下调用执行器方法会抛出错误。c.actuator:stop_all() 只会停止该行为所持有的内容。
在内置模块中,目标选择使用优先级 5,近战攻击使用 10,追击使用 20,空闲游荡使用 50,因此一旦出现目标,追击就会立即从游荡手中接管移动控制权。
逃跑、射击与设定伤害
这三个调用需要 10.9.14 之后的 EliteMobs 版本。
c.actuator:flee(location, speed)规划一条约十个方块长、远离该位置的路径并沿其前进。当身体无法规划路径、找不到那么长的出路,或有其他系统正在控制其移动时,返回false。规划会尝试多个出路,所以请每隔几个 tick 调用一次;其间会沿着路径前进。c.actuator:shoot(target)发动身体自身种类的远程攻击:骷髅的箭、女巫的药水,或掠夺者的弩(弩为空时先装填)。对没有远程攻击的种类返回false。c.actuator:attack(target, damage)挥击并造成该数值的伤害,记在身体名下,而不是身体自身的攻击伤害。
操控飞行
c.actuator:steer_flight(x, y, z) 让飞行中的身体仅在当前 tick 按该速度(单位为方块每 tick)移动。在怪物应继续飞行的每个 tick 都要调用它;在没有调用的 tick,身体会重新按其正常导航移动。该调用会停止任何由 move_to 开始的路径,会与方块碰撞,并使身体朝其水平行进方向转向,每个 tick 最多转 8 度。长度超过每 tick 4 个方块(每秒 80 个方块)的速度会按相同方向缩小到 4。
该行为必须同时持有 ai.controls.move 和 ai.controls.look。缺少控制权,或数值不是有限数字,会抛出错误。当身体无法飞行,或有其他系统正在控制其移动时,该调用返回 false 且不执行任何操作,否则返回 true。EliteMobs 会给蝙蝠、烈焰人、恶魂、幻翼和恼鬼等会飞的怪物类型提供飞行身体。
请求 Boss 动作
持有 ai.controls.action 的行为可以调用 c.actions:request(identifier, payload)。EliteMobs 会通过 on_mind_action 将请求发送给 Boss 的 Lua 能力。identifier 必须是不超过 128 个字符的小写命名空间键,例如 'elitemobs:slam'。payload 最多包含 16 个条目,键为小写且不超过 64 个字符,字符串值限制为 256 个字符;无效的 identifier 或 payload 会抛出错误。该调用返回 accepted、deferred 或 rejected;在一个 tick 内超出程序 max_action_requests 的请求会返回 deferred。payload 格式请参阅 Mind 动作上下文。
预算
budget 设置软性调度限制。当某只怪物在一个 tick 内达到其中任一限制时,Mind 运行时会跳过该怪物在本 tick 剩余的回调,直到下一个 tick。已经在运行的回调总会执行完毕。被跳过的传感器运行或 can_start 检查会在下一个 tick 重试。
| 键 | 默认值 | 说明 |
|---|---|---|
callback_micros | 2000 | 运行时间超过此值的回调会结束该怪物在本 tick 的回调。 |
entity_micros | 4000 | 每只怪物每 tick 的回调总时间。 |
server_micros | 20000 | 当所有 Mind 程序合计已用掉这么多时间时,该怪物在本 tick 的回调就会停止。 |
max_callbacks | 128 | 每只怪物每 tick 的回调次数。 |
max_action_requests | 8 | 每只怪物每 tick 的动作请求次数;最多 64。 |
所有值都必须为正数,并且 callback_micros 不能超过 entity_micros,entity_micros 不能超过 server_micros。
runaway 设置会中断单个回调的硬性限制:
| 键 | 默认值 | 最大值 | 说明 |
|---|---|---|---|
cpu_micros | 50000 | 50000 | 每个回调的线程 CPU 时间。 |
max_instructions | 50000 | 250000 | 每个回调的 Lua 指令数。 |
budget 也接受 max_instructions,就像内置的 basic_melee.lua 那样。请在 budget 或 runaway 中声明它,不要两处都声明。两个限制都必须为正数。超过最大值的值仍会加载,但会被降低到最大值,且不会给出警告。
这些限制会在回调运行期间将其中断,因此永不结束的循环会失败,而不是让服务器卡死。指令数在运行时计数;CPU 时间每 1,024 条指令检查一次,并在回调返回时检查。如果服务器无法测量线程 CPU 时间,cpu_micros 会改为把实际经过的时间限制在其值的五倍。超出失控限制的回调会像其他任何回调错误一样失败,控制台中的日志行为 failed with RUNAWAY_LIMIT_EXCEEDED。
后续步骤
- 创建 Boss:behavior —— 为 Boss 选择程序
- Lua API 参考:Mind 程序上下文 —— 所有
c.memory、c.perception、c.actuator和c.actions方法 - 钩子与生命周期 ——
on_mind_action以及其他 Lua 能力钩子 - FreeMinecraftModels 宠物行为模块 —— 宠物行为模块及其
c.pet和c.settings字段
