NPC 与首领巡逻

EliteMobs 可让已配置的 NPC 和自定义首领使用 Minecraft 原生导航沿作者设定的路线移动。同一套系统也向 Lua 脚本提供 walk_to、hold 和 teleport。

快速编辑流程

1. 生成或放置要编辑的 NPC 或自定义首领。
2. 在 12 格内直视目标并运行 /em patrol edit。
3. 站在每个目的地运行 /em patrol add。节点 0 是配置中的生成位置。
4. 使用 /em patrol mode LOOP 将最后一个节点连回第一个节点，或使用 /em patrol mode REVERSE 按列表原路返回。
5. 运行 /em patrol save 保存路线并刷新该实体。

编辑器显示的是求解后的实际步行路径，而不只是节点之间的直线。编辑时还可使用 /em patrol undo、/em patrol remove、/em patrol status 和 /em patrol cancel。这些命令只能由玩家使用，并需要 elitemobs.patrol.admin。

如果一个 NPC 文件包含多个 spawnLocations，保存时会为当前地点建立单独的子文件，避免把同一组相对偏移应用到所有 NPC 副本。

配置

巡逻节点是相对于配置生成位置的 x,y,z 偏移，而不是绝对世界坐标。

patrol:
  enabled: true
  mode: LOOP
  speed: 1.0
  virtualSpeed: 0.2
  nodes:
  - 0,0,0
  - 1000,0,0
  - 1000,0,250

键	值	默认值	说明
patrol.enabled	true / false	存在节点时为 true	启用此路线。
patrol.mode	LOOP / REVERSE	LOOP	LOOP 将最后节点连到节点 0；REVERSE 沿列表返回。
patrol.speed	正数	1.0	原生导航速度倍率。
patrol.virtualSpeed	正数	观测到的移动速度	持久实体没有已加载身体时每 tick 前进的方块数。通常应省略。
patrol.nodes	至少两个偏移	无	按顺序排列的目的地。支持 x,y,z 字符串或包含 x、y、z 的映射。

系统没有公开的单段距离上限，1,000 格的路段也是有效的。旧实验键 patrol.maxLegDistance 已废弃且不起作用。

长距离寻路

长路段会自动求解。EliteMobs 让 MagmaCore 在当前已加载地形中滚动规划路线，把它拆成原生导航可处理的短目标，并随实体前进继续重新规划。

• 已加载区块的快照通过 MagmaCore 共享的 tick 预算工作负载系统在服务器线程中获取。
• 有界 A* 搜索在这些不可变快照上异步执行。
• 最终的短路段仍由 Minecraft 原生寻路器验证并行走。
• 规划绝不会强制加载区块。若下一片地形不可用，实体会停在最后一段已验证路径的终点，待该区域再次进行实体 tick 后继续。

这样便能穿越整座城市，而无需在一个 tick 内扫描全部地形，也不会沿直线穿过未加载的建筑。飞行和水生生物使用体积搜索；地面生物要求有支撑和足够空间，并避开常见危险方块。

实体行为

• NPC 巡逻会自动启用身体 AI 和自定义模型移动同步。syncMovement 仍控制不巡逻的模型，但它不是第二个巡逻开关。
• 自定义首领必须使用 ai: true、具有正的移动速度，并且不能是其他实体的乘客。
• 首领进入战斗时暂停巡逻，战斗结束后恢复。
• 持久 NPC 和非实例化的持久首领会在区块卸载和重载期间把安全路线位置保存在 patrol-state.yml。
• 实体只会在进行实体 tick 的区域重新实体化。未知地形会冻结路线时间。
• 乘客不能拥有巡逻路线；请为其坐骑设置路线。

Lua 控制

当实体配置了巡逻控制器时，context.npc 和 context.boss 提供以下方法。坐标是相对于生成位置的偏移，每个方法都会返回请求是否被接受。

方法	行为
patrol_pause()	停止当前路线但保留配置。
patrol_resume()	取消脚本等待或临时移动并恢复巡逻。
walk_to(x, y, z)	走到偏移位置，然后恢复巡逻。
hold(x, y, z)	走到偏移位置并停留。
teleport(x, y, z)	目标区域进行实体 tick 时传送过去，然后恢复路线。

return {
  api_version = 1,
  on_npc_interact = function(context)
    context.npc:walk_to(40, 0, -12)
  end
}

walk_to 使用相同的长距离求解器，无需手动拆分中间节点。

诊断

直视实体并运行 /em patrol status。输出包含运行状态、当前与目标节点、路线进度、逻辑位置、虚拟速度、身体是否存在以及暂停原因。terrain_unavailable 表示规划器正在等待已加载且进行实体 tick 的地形。