建立 NPC
將定義存放在 plugins/EliteMobs/npcs/，使用包含 .yml 的唯一檔名。儲存後執行 /em reload，再放置新定義的 NPC。具有 elitemobs.place.npc 權限的玩家，可在所需位置與朝向執行 /em place npc <npcfilename.yml>。一個檔案可包含多個放置位置。
重複使用其他 NPC 檔案
NPC 檔案可以透過 extends 以另一個 NPC 檔案為基礎，只修改不同的部分：
extends: my_base_npc.yml
name: "&aSecond Guard"
spawnLocations:
- my_world,20,64,20,90,0
該檔案會繼承基礎檔案的所有值，並覆寫自己設定的鍵。巢狀區段(例如 patrol)會逐鍵合併；清單(例如 dialog)則會整個取代基礎檔案中的清單。指定基礎檔案時只寫檔名，不要包含資料夾路徑。它必須是 npcs(含其子資料夾)中的另一個檔案，而且它本身也可以再繼承其他基礎檔案。
isEnabled、spawnLocation 與 spawnLocations 永遠不會被繼承，因此每個檔案都保有自己的放置位置。設為 isEnabled: false 的基礎檔案可作為範本使用：繼承它的檔案仍會載入。EliteMobs 不會把預設值寫入使用 extends 的檔案。找不到基礎檔案、在 extends 中寫入路徑，或 extends 互相參照形成迴圈時，該檔案會被停用，並在控制台顯示警告。巡邏編輯器從含有多個放置位置的檔案中拆出其中一個時，就會使用 extends。
設定
isEnabled
在讀取設定時啟用此定義。變更後需重新載入。SCROLL_APPLIER 還需要全域 useEliteItemScrolls 已啟用才會生成。
| 鍵 | 值 | 預設值 |
|---|---|---|
isEnabled | 布林值 | true |
範例
isEnabled: true
name
設定顯示名稱，支援色彩代碼。EliteMobs 將原文登錄至翻譯 CSV，若有設定語言的譯文，就會使用該譯文。
| 鍵 | 值 | 預設值 |
|---|---|---|
name | 字串 | 空字串 |
範例
name: "&aEnn Peecee"
名牌配置
名稱與角色標籤採固定配置，沒有每個 NPC 獨立的 nameplateScale 或 nameplateLineGap 設定。一般與偽裝 NPC 的標籤跟隨實體或偽裝高度。相容的 FreeMinecraftModels 模型自行管理名牌；ModelEngine 保留自己的名稱，由 EliteMobs 顯示角色標籤。個人任務標記位於標籤上方。
啟用賭博時，特殊 NPC gambling_den_owner.yml 會在同一組標籤加入莊家收益，約每秒更新一次。
scale
透過 Minecraft 的縮放屬性設定底層村民的大小。模型或偽裝可以自行控制視覺大小，因此不保證外觀隨村民同步縮放。
| 鍵 | 值 | 預設值 |
|---|---|---|
scale | 倍率 | 1.0 |
縮放時,1.0 代表預設大小。若要讓實體變大,請增加數值(例如 1.2)。若要讓實體變小,請減少數值(例如 0.8)。
範例
scale: 1.2
role
設定名稱下方的角色標籤，只影響顯示。支援色彩代碼，並登錄至翻譯 CSV。
| 鍵 | 值 | 預設值 |
|---|---|---|
role | 字串 | 空字串 |
範例
role: "&c<Red Fellow>"
profession
設定底層村民的職業；未使用偽裝或自訂模型時，會決定村民的外觀。
| 鍵 | 值 | 預設值 |
|---|---|---|
profession | 職業 | NITWIT |
範例
profession: NITWIT
greetings
鄰近掃描首次在 activationRadius 內偵測到玩家時，會嘗試隨機挑選一句問候，顯示為僅該玩家可見、持續約 5 秒的浮動氣泡。清單會登錄至翻譯 CSV。發言仍需要 canTalk 啟用且共用對話冷卻結束。
| 鍵 | 值 | 預設值 |
|---|---|---|
greetings | 字串清單 | 無 |
只在偵測到進入時嘗試問候。若被共用冷卻阻擋，繼續留在範圍內不會重試該問候。
範例
greetings:
- Hi there!
- Good day.
dialog
設定浮動氣泡台詞，每次隨機挑選一則，不依清單順序讀取。清單會登錄至翻譯 CSV。
觸發時機取決於 interactionType:
CHAT在互動時嘗試發言，通常是右鍵點擊。FreeMinecraftModels 也會將模型上的左鍵點擊交給互動處理器。- 其他類型在玩家留在範圍內的後續掃描中嘗試對話；進入時的掃描則嘗試問候。
字面上的 \n 會將氣泡拆成多行。請用 YAML 單引號保留，或在雙引號內寫成 \\n。問候與告別也遵循此規則。
| 鍵 | 值 | 預設值 |
|---|---|---|
dialog | 字串清單 | 無 |
範例
dialog:
- I like apples!
- Sure is hot.
farewell
設定隨機挑選並顯示為浮動氣泡的告別語。清單會登錄至翻譯 CSV。
| 鍵 | 值 | 預設值 |
|---|---|---|
farewell | 字串清單 | 無 |
關閉任何標題非空的物品欄畫面，都會嘗試讓附近 NPC 告別。搜尋範圍以玩家為中心沿各軸延伸 5 格，不限於已開啟選單的擁有者。多個 NPC 都可能發言。走出 activationRadius 不會觸發告別。
範例
farewell:
- Until next time!
- Bye!
canTalk
控制內建聊天氣泡。false 抑制 greetings、dialog 與 farewell，但不會停用選單、指令、Lua 腳本、任務對話、鄰近偵測或任務標記。
| 鍵 | 值 | 預設值 |
|---|---|---|
canTalk | 布林值 | true |
範例
canTalk: true
activationRadius
設定 NPC 能偵測到玩家靠近的半徑,單位為格。
| 鍵 | 值 | 預設值 |
|---|---|---|
activationRadius | 小數 | 3.0 |
每 100 tick（約 5 秒）掃描一次，使用三維距離且不檢查視線遮擋。靜止 NPC 可以朝向玩家、在偵測到進入時問候，並在後續掃描中對話。0 或更低會停用這些互動，包括 Lua 鄰近鉤子。QUEST_GIVER 與 CUSTOM_QUEST_GIVER 的個人任務標記使用獨立的 30 格半徑，在 activationRadius: 0 時仍可顯示，內容反映該玩家可接取與可繳交的任務。
巡邏正在移動或編輯時，會抑制掃描與氣泡。patrol.pauseNearPlayersRadius 與 patrol.faceNearbyPlayers 控制玩家附近的暫停與朝向；參閱巡邏。
範例
activationRadius: 3.0
scripts
設定附加到此 NPC 的 Lua 腳本。腳本檔案從 plugins/EliteMobs/npc_scripts/ 載入。.lua 副檔名是可選的——若省略會自動附加。
| 鍵 | 值 | 預設值 |
|---|---|---|
scripts | 字串清單 | 無 |
共用的 MagmaCore Lua 引擎支援 on_spawn、on_game_tick、on_remove、on_npc_interact、on_npc_proximity_enter、on_npc_proximity_leave、on_zone_enter 與 on_zone_leave。NPC 的 tick 鉤子是 on_game_tick。每個 NPC 有自己的腳本實例，較小的優先序先執行。僅有 tick 鉤子的腳本還需要一個可留空的 on_spawn 才能初始化。API 與範例請參閱 Lua NPC 腳本。
名稱無法對應至已載入的腳本定義時，會警告並略過，但 NPC 仍會生成。請符合檔名大小寫，修改腳本後重新載入。
任務對話可能先於 on_npc_interact 處理掉點擊。否則，此鉤子在設定的互動之前執行，不會取消後續互動。
範例
scripts:
- wave.lua
interactionType
設定 NPC 將執行的互動類型。
| 鍵 | 值 | 預設值 |
|---|---|---|
interactionType | 特殊 [1] | NONE |
範例
interactionType: TELEPORT_BACK
noPreviousLocationMessage
TELEPORT_BACK 沒有已儲存的返回位置時顯示此訊息。返回位置是從 EliteMobs 世界以外執行 EliteMobs 傳送時記錄的出發點，不是最近走過的位置或死亡點。返回採用一般 EliteMobs 傳送流程，包括設定的延遲與取消規則。支援色彩代碼，並登錄至翻譯 CSV。
| 鍵 | 值 | 預設值 |
|---|---|---|
noPreviousLocationMessage | 字串 | 空字串 |
範例
noPreviousLocationMessage: '&8[EliteMobs] &cCouldn''t send you back to your previous location - no previous location found!'
timeout
生成後多少分鐘移除 NPC。0 或更低停用計時器。移除不會刪除已儲存的放置位置，也不會停用定義，因此重新載入、重啟或恢復區塊時 NPC 可能返回。
要刪除放置位置，先執行 /em remove 開啟移除模式，擊打 NPC，再執行 /em remove 結束模式。需要 elitemobs.remove。清單形式會移除對應項目；舊式單一位置定義則會被停用。遷移至 spawnLocations 時請刪除舊鍵 spawnLocation，否則清單清空後舊位置可能重新生效。
| 鍵 | 值 | 預設值 |
|---|---|---|
timeout | 小數 | 0（停用計時器） |
範例
timeout: 0
questFileName
為 CUSTOM_QUEST_GIVER 列出 plugins/EliteMobs/customquests/ 內的任務檔名，包括 .yml。鍵名是單數，值是清單。選單提供符合條件的任務，也接受指派給此 NPC 檔名的任務繳交。因此只接受繳交任務的 NPC 可以使用空清單。同一檔案的所有放置位置共用此任務身分。各任務自己的權限與條件仍然適用。
| 鍵 | 值 | 預設值 |
|---|---|---|
questFileName | 字串清單 | 無 |
範例
questFileName:
- my_quest_one.yml
- my_quest_two.yml
disguise
設定偽裝，需要 LibsDisguises。成功載入的自訂模型優先於偽裝。
| 鍵 | 值 | 預設值 |
|---|---|---|
disguise | LibsDisguises 格式 | 無 |
範例
disguise: SKELETON
customDisguiseData
設定自訂 LibsDisguises 偽裝的資料。
| 鍵 | 值 | 預設值 |
|---|---|---|
customDisguiseData | LibsDisguises 格式 | 無 |
範例
disguise: custom:my_cool_disguise_name
customDisguiseData: player my_cool_disguise_name setskin {"id":"364acb6d-9050-46f7-b5fb-f8c3fd83a6fc","name":"Unknown","properties":[{"name":"textures","value":"ewogICJ0aW1lc3RhbXAiIDogMTYxMTk4ODA4Nzc1NSwKICAicHJvZmlsZUlkIiA6ICJkZGVkNTZlMWVmOGI0MGZlOGFkMTYyOTIwZjdhZWNkYSIsCiAgInByb2ZpbGVOYW1lIiA6ICJEaXNjb3JkQXBwIiwKICAic2lnbmF0dXJlUmVxdWlyZWQiIDogdHJ1ZSwKICAidGV4dHVyZXMiIDogewogICAgIlNLSU4iIDogewogICAgICAidXJsIiA6ICJodHRwOi8vdGV4dHVyZXMubWluZWNyYWZ0Lm5ldC90ZXh0dXJlLzliYmVkODQzNWY4YmYyNzhhZmUyNmU2NGZkOTI2YjhiMzc3MzJkODhlMzM0ODk3ZGJkNTI3ZDU2ZmY5MTk5MGUiCiAgICB9CiAgfQp9","signature":"ujLq1joYVktuQAp1xpFKlxQFUVinSePiDBiVCAxxix/mA5vP86i/eAOfb1mtGjaAZ6sO0l2olbzvycnGXNBtbAxgqprguROXY4tpWiePVTDmy3iD4GdOCxHAkYLoyMV5qTT4SNsldUFFuND8GSEgbNMltKDLmhNKwzm08iCigPfpeuYpwljgJPxu6ka54PKNaQu4doI0ZDZXKqq4hPhR3Bs2Sz9MI0SmdmQWwcCzUz3DFdVno27fmQ6LwqmT+eSoOv0EttVG/XMaTYQ5lhBY61mqf6WlJyYVUSfjJk1AbYsctu7dWM+sbY8jFq5ljvXJGGr5TyKi+fs8vHy06Z2go20QgTYOw+caFxFijAS6fgm3oY57VEO/+/9OLHdD+Z9BrWqQWcIIrVeIfxjue/yt4pyeVv9jX59hjNFjhcPEwotkxJ+vZ96WlTLWDG4BiqauDr2VeGyLlVaygO9ZU0wwsN65iSh91GI3tMIA5wbDR0Hts/9ABvt9eafHbowS+4SZXN0i9mYnKg7op1eiB8nMEAGsPJg3DwsmUrh3ACAapQ6eYHiJpo59RXDqKlRcXwo7wsEFp//5LgQWbPj0NP3nxnywdpozqSAeq6236qlhE9BT9eiyJ41V9sMelYFEWMlUAltR40NdbIrHB0J3nmfuLJz44/sTwWf6P1khOy//XX0="}],"legacy":false}
customModel
設定 FreeMinecraftModels 或 ModelEngine 模型。先在所選提供者中安裝模型，再引用其 ID。兩者都可用時優先使用 FreeMinecraftModels；缺少 FMM 模型不會改用 ModelEngine。若沒有模型載入成功，則使用設定的偽裝或一般村民外觀。參閱自訂模型。
| 鍵 | 值 | 預設值 |
|---|---|---|
customModel | 字串 | 無 |
範例
customModel: MY_MODEL_ONE
職業導師與運輸 NPC
使用 interactionType: CLASS_TRAINER 與 classRoot 選擇職業分支。請從內附的 class_trainer_*.yml 定義開始。試煉與進度請參閱 Advanced Combat System。
對於 interactionType: TRANSPORT，transportRoutes 列出不含 .yml 的路線 ID，點擊 NPC 會開啟目的地選擇。參閱運輸路線。
arena
設定 NPC 將為其開啟選單的競技場檔名(需要 ARENA_MASTER 互動類型)。
| 鍵 | 值 | 預設值 |
|---|---|---|
arena | 檔名 | 無 |
範例
arena: my_arena.yml
command
COMMAND 的指令，在下一 tick 以點擊者身分執行，需要該玩家的一般指令權限。省略開頭的 /。此欄位不會自動展開玩家佔位符，也不使用 EliteMobs 控制台指令格式。
| 鍵 | 值 | 預設值 |
|---|---|---|
command | 字串 | 無 |
範例
command: say Look at me running a command, how cool!
spawnLocation
設定 NPC 的單一生成位置。這是舊式的單一位置鍵:只有在 spawnLocations 缺漏或為空時才會被讀取。在遊戲中放置的新位置會改寫入 spawnLocations,因此請優先使用該鍵。
建議格式為 world,x,y,z,yaw,pitch。指定世界必須已載入，此設定不會載入世界。
| 鍵 | 值 | 預設值 |
|---|---|---|
spawnLocation | 字串 | 無 |
範例
spawnLocation: my_world,10,50,10,0,0
spawnLocations
定義同一 NPC 的多個放置位置。/em place npc <npcfilename.yml> 將目前位置與朝向四捨五入至小數點後兩位後加入，並設定 isEnabled: true。序列化後完全相同的位置不會重複加入。區塊可處理實體 tick 後，NPC 才會恢復。
每個項目的格式為 world,x,y,z,yaw,pitch。
| 鍵 | 值 | 預設值 |
|---|---|---|
spawnLocations | 字串清單 | 無 |
範例
spawnLocations:
- my_world,10,50,10,0,0
- my_world,-10,50,-10,0,0
instanced
設定 NPC 是否應被實例化(供實例副本使用)。設為 true 時,NPC 不會在藍圖世界中生成;而是會被註冊為範本,並為每個副本實例複製一份,每個副本各自存在於對應的實例世界中。
| 鍵 | 值 | 預設值 |
|---|---|---|
instanced | 布林值 | false |
範例
instanced: false
syncMovement
設定 NPC 的自訂模型是否應與底層實體同步其移動。只有在設定了 customModel 且模型已載入時才會生效——對於一般 NPC 與 LibsDisguises NPC 會被忽略。
有效的 patrol 設定會啟用移動同步，即使巡邏暫停或本項為 false。本項仍用於不巡邏的自訂模型。
| 鍵 | 值 | 預設值 |
|---|---|---|
syncMovement | 布林值 | true |
範例
syncMovement: true
patrol
為 NPC 新增使用原生導航與自動尋路的路線。節點是相對於此 NPC 設定生成位置的偏移；若設定 patrol.relative: false，則是其所在世界中的確切座標。長路段會自動拆分，且不會強制載入區塊。patrol.startNodeWaitSeconds 會讓 NPC 每繞行一圈時在第一個節點停留一次；NPC 專用的 patrol.pauseNearPlayersRadius 會讓它在玩家附近暫停，而 patrol.faceNearbyPlayers 會讓它在暫停時轉向這些玩家。完整設定、遊戲內編輯器、長距離行為與 Lua 控制請參閱 NPC 與首領巡邏。
NPC 設定範例
isEnabled: true
name: "&cRed Rubin"
role: "&a<Generic NPC>"
profession: NITWIT
greetings:
- Hiya!
- Hello!
dialog:
- Great conversation!
- Pleasure talking with you!
farewell:
- Goodbye!
- Laters!
canTalk: true
activationRadius: 4
interactionType: CHAT
timeout: 0
spawnLocations:
- my_world,584,55,127,90,10
特殊 [1]
以下是有效的 NPC 互動類型列表:
| 類型 | 說明 |
|---|---|
GUILD_GREETER | 開啟武器技能加成。需要 elitemobs.skill.npc。 |
CLASS_TRAINER | 開啟 classRoot 指定的分支。需要 elitemobs.command。 |
TRANSPORT | 開啟 transportRoutes 的目的地。 |
CHAT | 互動時嘗試隨機說出一句 dialog。 |
CUSTOM_SHOP | 開啟自訂商店。需要 elitemobs.shop.custom.npc。 |
PROCEDURALLY_GENERATED_SHOP | 開啟產生的商店。需要 elitemobs.shop.dynamic.npc。 |
BAR | 尚未實作。告知玩家該功能即將推出。 |
ARENA | 無作用。請改用 ARENA_MASTER。 |
QUEST_GIVER | 開啟產生的任務。需要 elitemobs.quest.npc。 |
CUSTOM_QUEST_GIVER | 提供 questFileName 中符合條件的任務，並接受指定任務的繳交。 |
NONE | 沒有內建動作；腳本、鄰近偵測與任務對話仍可執行。 |
SELL | 開啟販售。需要 elitemobs.shop.sell.npc。 |
TELEPORT_BACK | 使用儲存的 EliteMobs 返回位置。需要 elitemobs.back.npc。 |
SCRAPPER | 開啟拆解。需要 elitemobs.scrap.npc。 |
REPAIRMAN | 開啟修理。需要 elitemobs.repair.npc。 |
ENCHANTER | 開啟附魔。需要 elitemobs.enchant.npc。 |
REFINER | 已取代 - 告知玩家該功能已被取代;管理員被告知要移除該 NPC |
SMELTER | 已取代 - 告知玩家該功能已被取代;管理員被告知要移除該 NPC |
ENHANCER | 已取代 - 告知玩家該功能已被取代;管理員被告知要移除該 NPC |
UNBINDER | 開啟解綁。需要 elitemobs.unbind.npc。 |
ARENA_MASTER | 開啟在 arena 中所設定競技場的競技場選單 |
COMMAND | 執行在 command 中所設定的指令 |
SCROLL_APPLIER | 開啟精英物品卷軸。需要 elitemobs.scroll.npc；useEliteItemScrolls 停用時不生成。 |
ARROW_SHOP | 開啟箭矢商店。需要 elitemobs.shop.arrow.npc。 |
GAMBLING_BLACKJACK | 開啟二十一點。需要 elitemobs.gambling.npc。 |
GAMBLING_COINFLIP | 開啟擲幣。需要 elitemobs.gambling.npc。 |
GAMBLING_SLOTS | 開啟吃角子老虎。需要 elitemobs.gambling.npc。 |
GAMBLING_HIGHERLOWER | 開啟猜大小。需要 elitemobs.gambling.npc。 |
有關 SCRAPPER 及類似互動類型作用的更多資訊,請點擊這裡。
NPC 行為注意事項
內建行為還包括：
- 移動：通常保持靜止並朝向附近玩家，巡邏與腳本可以移動 NPC。巡邏路線取代一般村民行為。
- 互動順序：任務對話可能先於 Lua 與內建動作處理點擊。否則先執行 Lua，再執行設定動作及其權限檢查。每個玩家有跨 NPC 的 1 tick 防重複限制。編輯巡邏會阻擋互動，一般巡邏移動不會。
- 保護：NPC 本體不會正常發生碰撞。EliteMobs 取消傷害、村民轉化，以及一般交易畫面的開啟。
- 標籤：名稱與角色採用上述固定配置。一般與偽裝 NPC 使用目前本體高度，因此縮放也可能移動標籤。相容的 FMM 模型統一管理名稱與角色。
- Bedrock：顯示取決於目前啟用的模型與顯示整合。現行 NPC 名牌繪製不使用保留的
bedrockNPCRoleYOffset設定鍵。 - 對話冷卻：每個 NPC 在所有玩家間共用 3 秒發言間隔。向一名玩家問候可能阻止同時向另一名玩家問候。個人氣泡約 5 秒後消失。
- 隱形:處於隱形藥水效果下的 NPC 不會顯示聊天氣泡。
- 區塊：卸載時移除 NPC，區塊恢復實體 tick 處理後重建。NPC 實體不儲存在世界中，放置位置由設定提供。
- 改名：主手持命名牌對本體村民進行一般右鍵互動時，會取消並提示。模型使用自己的點擊回呼；FreeMinecraftModels 將左鍵與右鍵點擊都交給 NPC 互動處理器。