跳到主要内容

Lua 脚本:行为程序

webapp_banner.jpg

行为程序用 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 或 falseglow = 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数字
uuidUUID 字符串
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);行为停止时运行。

生命周期​

  1. 停止状态下,行为会每个 tick 或每 probe_interval 个 tick 检查一次 can_start。当它返回 true 且该行为能够租用所有声明的控制权时,start 就会运行。
  2. 运行期间的每个 tick,或每 tick_interval 个 tick,并且始终在启动的那个 tick,都会先运行 can_continue。它返回 false 时,行为以原因 completed 停止;否则运行 tick。
  3. 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.movec.actuator:move_to(...)、c.actuator:flee(...)、c.actuator:stop_moving()
ai.controls.lookc.actuator:look_at(...)
ai.controls.move 和 ai.controls.look 一起c.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_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_micros2000运行时间超过此值的回调会结束该怪物在本 tick 的回调。
entity_micros4000每只怪物每 tick 的回调总时间。
server_micros20000当所有 Mind 程序合计已用掉这么多时间时,该怪物在本 tick 的回调就会停止。
max_callbacks128每只怪物每 tick 的回调次数。
max_action_requests8每只怪物每 tick 的动作请求次数;最多 64。

所有值都必须为正数,并且 callback_micros 不能超过 entity_micros,entity_micros 不能超过 server_micros。

runaway 设置会中断单个回调的硬性限制:

键默认值最大值说明
cpu_micros5000050000每个回调的线程 CPU 时间。
max_instructions50000250000每个回调的 Lua 指令数。

budget 也接受 max_instructions,就像内置的 basic_melee.lua 那样。请在 budget 或 runaway 中声明它,不要两处都声明。两个限制都必须为正数。超过最大值的值仍会加载,但会被降低到最大值,且不会给出警告。

这些限制会在回调运行期间将其中断,因此永不结束的循环会失败,而不是让服务器卡死。指令数在运行时计数;CPU 时间每 1,024 条指令检查一次,并在回调返回时检查。如果服务器无法测量线程 CPU 时间,cpu_micros 会改为把实际经过的时间限制在其值的五倍。超出失控限制的回调会像其他任何回调错误一样失败,控制台中的日志行为 failed with RUNAWAY_LIMIT_EXCEEDED。


后续步骤​