建立 NPC

設定

isEnabled

設定 NPC 是否啟用。

Key	Values	Default
isEnabled	Boolean	true

範例

isEnabled: true

---

name

設定 NPC 的顯示名稱。支援 Color Codes 與多語言伺服器的翻譯鍵。

Key	Values	Default
name	String	none

範例

name: "&aEnn Peecee"

---

scale

設定 NPC 的尺度(大小)。此項是透過底層實體上的原版 generic_scale 屬性套用的。

Key	Values	Default
scale	Multiplier	1.0

縮放時,1.0 代表預設大小。若要讓實體變大,請增加數值(例如 1.2)。若要讓實體變小,請減少數值(例如 0.8)。

範例

scale: 1.2

---

role

設定 NPC 的角色定位,顯示在名稱下方。僅供視覺呈現。支援 Color Codes 與多語言伺服器的翻譯鍵。

Key	Values	Default
role	String	none

範例

role: "&c<Red Fellow>"

---

profession

設定 NPC 的職業,它會在未使用偽裝時設定其外觀。

Key	Values	Default
profession	Profession	NITWIT

範例

profession: NITWIT

---

greetings

設定 NPC 在玩家首次進入其 activationRadius 時可以說的問候語列表。系統會隨機挑選一則,以浮動聊天氣泡顯示在 NPC 上方(只有該玩家看得到,約持續 5 秒)。支援多語言伺服器的翻譯鍵。

Key	Values	Default
greetings	String List	none

問候語只會在進入半徑時觸發,不會在玩家停留於半徑內時重複觸發。

範例

greetings:
- Hi there!
- Good day. 

---

dialog

設定 NPC 可以用浮動聊天氣泡說出的台詞。每次都會隨機挑選一則(此清單不會依序讀取)。支援多語言伺服器的翻譯鍵。

觸發時機取決於 interactionType:

• CHAT NPC 會在玩家右鍵點擊它們時說出一句對話。
• 其他所有 interactionType 則會在玩家停留於 activationRadius 內時,於每次鄰近掃描時說出一句對話。

台詞中的字面 會把它拆成堆疊的多行氣泡。

Key	Values	Default
dialog	String List	none

範例

dialog:
- I like apples!
- Sure is hot.

---

farewell

設定 NPC 的告別訊息。系統會隨機挑選一則,以浮動聊天氣泡顯示。支援多語言伺服器的翻譯鍵。

Key	Values	Default
farewell	String List	none

告別語會在玩家站在 NPC 5 格範圍內關閉物品欄選單時觸發——通常就在關閉商店、任務或競技場選單之後。當玩家單純走出 activationRadius 時不會觸發。

範例

farewell: 
- Until next time!
- Bye!

---

canTalk

設定 NPC 是否能說話。設為 false 時,NPC 永遠不會顯示聊天氣泡,因此 greetings、dialog 與 farewell 全都會被抑制。

Key	Values	Default
canTalk	Boolean	true

範例

canTalk: true

---

activationRadius

設定 NPC 能偵測到玩家靠近的半徑,單位為格。

Key	Values	Default
activationRadius	Double	3.0

鄰近偵測每 5 秒掃描一次。當玩家位於半徑內時,NPC 會轉向面對他們、會顯示任務指示(適用於 QUEST_GIVER / CUSTOM_QUEST_GIVER NPC),並觸發 greetings / dialog。將此值設為 0(或更低)會完全停用該 NPC 的鄰近偵測。

範例

activationRadius: 3.0

---

scripts

設定附加到此 NPC 的 Lua 腳本。腳本檔案從 plugins/EliteMobs/npc_scripts/ 載入。.lua 副檔名是可選的——若省略會自動附加。

Key	Values	Default
scripts	String List	none

NPC 腳本執行在共用的 MagmaCore Lua 引擎上,並支援下列鉤子:on_spawn、on_tick、on_remove、on_npc_interact、on_npc_proximity_enter、on_npc_proximity_leave、on_zone_enter 與 on_zone_leave。完整的 API 與範例請參閱 Lua NPC 腳本。

若腳本檔名無法解析到 npc_scripts/ 中的檔案,該項會被略過並發出警告;NPC 仍會照常生成。

範例

scripts:
- wave.lua

---

interactionType

設定 NPC 將執行的互動類型。

Key	Values	Default
interactionType	特殊 [1]	NONE

範例

interactionType: TELEPORT_BACK

---

noPreviousLocationMessage

當傳送員 NPC 沒有可傳送玩家過去的先前位置時,它會顯示此訊息。接受 Color Codes 與多語言伺服器的翻譯鍵。

Key	Values	Default
noPreviousLocationMessage	String	none

範例

noPreviousLocationMessage: '&8[EliteMobs] &cCouldn''t send you back to your previous location - no previous location found!'

---

timeout

設定 NPC 永久消失前的時間量(以分鐘計)。

Key	Values	Default
timeout	Double	0(永不)

範例

timeout: 0

---

questFileName

設定 NPC 發放的自訂任務。需要 CUSTOM_QUEST_GIVER 的 interactionType。請注意此鍵是單數形(questFileName),即使它接受一個清單。

Key	Values	Default
questFileName	String List	none

範例

questFileName:
- my_quest_one.yml
- my_quest_two.yml

---

disguise

設定 NPC 擁有的 LibsDisguises 偽裝。

Key	Values	Default
disguise	LibsDisguises 格式	none

範例

disguise: SKELETON

---

customDisguiseData

設定自訂 LibsDisguises 偽裝的資料。

Key	Values	Default
customDisguiseData	LibsDisguises 格式	none

範例

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

設定 NPC 將使用的 ModelEngine 自訂模型。

Key	Values	Default
customModel	String	none

範例

customModel: MY_MODEL_ONE

---

arena

設定 NPC 將為其開啟選單的競技場檔名(需要 ARENA_MASTER 互動類型)。

Key	Values	Default
arena	Filename	none

範例

arena: my_arena.yml

---

command

設定 NPC 將執行的指令(需要 COMMAND 互動類型)。指令以玩家身分執行,而非控制台。請勿包含開頭的斜線(/)。

Key	Values	Default
command	String	none

範例

command: say Look at me running a command, how cool!

---

spawnLocation

設定 NPC 的單一生成位置。這是舊式的單一位置鍵:只有在 spawnLocations 缺漏或為空時才會被讀取。在遊戲中放置的新位置會改寫入 spawnLocations,因此請優先使用該鍵。

格式為 world,x,y,z,yaw,pitch。

Key	Values	Default
spawnLocation	String	none

範例

spawnLocation: my_world,10,50,10,0,0

---

spawnLocations

設定 NPC 的生成位置。同一個 NPC 檔案可以被放置在多個地點;每個項目會生成一個 NPC。你應透過 /em place npc <npcfilename.yml> 指令來設定這個,該指令會把你當前的位置(包含你面對的方向)附加到此清單,並同時設定 isEnabled: true。

每個項目的格式為 world,x,y,z,yaw,pitch。

Key	Values	Default
spawnLocations	String List	none

範例

spawnLocations: 
- my_world,10,50,10,0,0
- my_world,-10,50,-10,0,0

instanced

設定 NPC 是否應被實例化(供實例副本使用)。設為 true 時,NPC 不會在藍圖世界中生成;而是會被註冊為範本,並為每個副本實例複製一份,每個副本各自存在於對應的實例世界中。

Key	Values	Default
instanced	Boolean	false

範例

instanced: false

---

syncMovement

設定 NPC 的自訂模型是否應與底層實體同步其移動。只有在設定了 customModel 且模型已載入時才會生效——對於一般 NPC 與 LibsDisguises NPC 會被忽略。

Key	Values	Default
syncMovement	Boolean	true

範例

syncMovement: true

---

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
questFileName: 
- my_quest.yml #npc interactionType must be set to CUSTOM_QUEST_GIVER
disguise: SKELETON
customDisguiseData: #used when a custom libsdisguise is being set
customModel: MODEL_ONE
arena: my_arena.yml #npc interactionType must be set to ARENA_MASTER
command: say Hello World! #npc interactionType must be set to COMMAND (do not include the leading slash)
spawnLocation: my_world,584,55,127,90,10 #remember that NPCs use pitch and yaw to set where they are looking at. this is also automatically set when running the /em place npc <npcfilename.yml> command, so make sure you pose where you want the NPC to be facing when running the command.

---

特殊 [1]

以下是有效的 NPC 互動類型列表:

Type	Description
GUILD_GREETER	開啟武器技能加成選擇選單
CHAT	右鍵點擊會從 dialog 中說出一句隨機台詞
CUSTOM_SHOP	開啟自訂商店選單
PROCEDURALLY_GENERATED_SHOP	開啟程序化產生的商店
BAR	尚未實作。告知玩家該功能即將推出。
ARENA	無作用。請改用 ARENA_MASTER。
QUEST_GIVER	開啟程序化產生的任務選單
CUSTOM_QUEST_GIVER	開啟在 questFileName 中所設定特定任務的任務選單
NONE	無互動
SELL	開啟販售選單
TELEPORT_BACK	將玩家傳送回他們所在過的最後一個非 elitemobs 世界位置
SCRAPPER	開啟拆解選單
REPAIRMAN	開啟修理選單
ENCHANTER	開啟附魔選單
REFINER	已取代 - 告知玩家該功能已被取代;管理員被告知要移除該 NPC
SMELTER	已取代 - 告知玩家該功能已被取代;管理員被告知要移除該 NPC
ENHANCER	已取代 - 告知玩家該功能已被取代;管理員被告知要移除該 NPC
UNBINDER	開啟解綁選單
ARENA_MASTER	開啟在 arena 中所設定競技場的競技場選單
COMMAND	執行在 command 中所設定的指令
SCROLL_APPLIER	開啟精英物品卷軸選單。當 useEliteItemScrolls 停用時,該 NPC 根本不會生成
ARROW_SHOP	開啟箭矢商店選單
GAMBLING_BLACKJACK	開啟二十一點賭博遊戲
GAMBLING_COINFLIP	開啟擲幣賭博遊戲
GAMBLING_SLOTS	開啟吃角子老虎賭博遊戲
GAMBLING_HIGHERLOWER	開啟猜大小賭博遊戲

有關 SCRAPPER 及類似互動類型作用的更多資訊,請點擊這裡。

NPC 行為注意事項

NPC 有數種無法設定的硬編碼行為:

• AI 已停用:NPC 無法移動或尋路。它們會停留在它們的生成位置。但它們會原地轉向,面對位於 activationRadius 內的玩家。
• 角色定位顯示:role 文字會以浮動文字顯示實體渲染在 NPC 上方。垂直偏移取決於 NPC 的渲染方式——一般 NPC 為 2.52、LibsDisguises NPC 為 2.30、使用 customModel 的則為 2.3。
• Bedrock 角色定位標籤:Bedrock 用戶端無法渲染文字顯示實體,因此經過偽裝的 NPC 會額外取得一個帶有角色定位文字的隱形標記盔甲座,只顯示給 Bedrock 玩家並對 Java 玩家隱藏。其高度由 config.yml 中的 bedrockNPCRoleYOffset 設定(預設 2.2)。此後備機制需要後端伺服器上有 Geyser 或 Floodgate;僅在代理端安裝 Geyser 的架構會停用它。
• 對話冷卻:NPC 在說話事件之間會等待 3 秒,以防止訊息重疊。聊天氣泡是每位玩家專屬的浮動文字,約 5 秒後消失,並非聊天訊息。
• 隱形:處於隱形藥水效果下的 NPC 不會顯示聊天氣泡。
• 區塊生命週期:NPC 在其區塊卸載時消失,並在區塊重新載入時重新生成。NPC 實體永遠不會被存進世界——它們是從設定檔重新建立的。
• 禁止改名:手持命名牌右鍵點擊 NPC 的行為會被取消,並告知玩家該 NPC 無法被改名。