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 的地形。