MagmaCore Lua 腳本引擎

MagmaCore 提供 EliteMobs Boss 能力、NPC 腳本、FreeMinecraftModels 道具與自訂附魔效果所用的 Lua 沙盒和 ScriptInstance 執行環境。它們共用檔案驗證及實例管理，但可用掛鉤、上下文資料表、冷卻範圍與生命週期取決於提供者。附魔查詢另有受限上下文和提供者專屬額度，請參閱下方的專用參考。

FMM 道具與 EliteMobs NPC 直接繼承通用資料表（context.world、context.zones、context.scheduler、context.cooldowns、context.log、context.event、context.player、context.state），再加入 context.prop 或 context.npc。Boss 能力使用相同執行環境，但提供多張資料表的專屬變體（context.world、context.zones、context.cooldowns、context.scheduler、context.log、context.event），以及 context.players、context.entities、context.vectors、context.settings 和 context.script。

目前使用此引擎的外掛包含:

• EliteMobs —— 自訂 Boss 的 Lua 能力（on_boss_damaged_by_player、on_enter_combat 等），以及處理互動與接近行為的 NPC Lua 腳本（on_npc_interact、on_npc_proximity_enter 等）。
• FreeMinecraftModels —— 道具 Lua 腳本（on_right_click、on_left_click 等）與自訂物品的附魔效果。

本頁說明 FMM 使用的通用 MagmaCore 功能，以及 EliteMobs Boss 與 NPC 變體的差異。Boss 的完整上下文請查閱 EliteMobs Lua 頁面；NPC 請查閱 NPC Lua 腳本。

---

Lua 簡易入門

如果你完全沒接觸過 Lua,以下是為任何 Nightbreak 外掛撰寫腳本所需的最少語法。

變數

使用 local 儲存一個值:

local cooldown_key = "fire_burst"
local damage_multiplier = 1.5

local 表示該變數僅屬於這個檔案或區塊。

函式

函式是可重複使用的邏輯區塊:

local function warn_player(player)
  player:send_message("&cMove!")
end

稍後可以這樣呼叫:

warn_player(some_player)

if 判斷

當某件事只應在某些情況下發生時,使用 if:

if context.player == nil then
  return
end

意思是「如果這個 hook 沒有玩家,就到此停止」。

nil

nil 表示「沒有值」。它是 Lua 對「什麼都沒有」的表達方式。

你會經常用以下方式檢查 nil:

if context.event ~= nil then
  -- do something with the event
end

~= 表示「不等於」。

表（Tables）

Lua 將表用於多種用途:

• 清單
• 帶有命名鍵的物件
• 最後回傳的腳本定義

帶有命名鍵的表範例:

local particle = {
  particle = "FLAME",
  amount = 1,
  speed = 0.05
}

回傳腳本定義

在每個腳本檔案的結尾,你會回傳一張表:

return {
  api_version = 1,

  on_spawn = function(context)
  end
}

回傳的表就是腳本定義。載入器先執行檔案以驗證，再為每個實例重新執行儲存的原始碼。因此檔案區域變數屬於個別實例，不由使用同一檔案的所有實體共用。編輯檔案不會改變已載入定義或執行中的實例，請透過所屬外掛的流程重新載入。

註解

使用 -- 為人類撰寫註解:

-- This cooldown stops the attack from firing every hit
context.cooldowns:set_local(60, "fire_burst")

---

Lua 沙盒

所有 Lua 腳本皆在沙盒化的 LuaJ 環境中執行。多個可能存取檔案系統或 Java 執行環境的全域物件已被移除。沙盒規則在所有使用 MagmaCore 的外掛之間都相同。

被移除的全域

下列標準 Lua 全域已被設為 nil,無法使用:

移除項目	原因
debug	暴露內部 VM 狀態
dofile	檔案系統存取
io	檔案系統存取
load	任意程式碼載入
loadfile	檔案系統存取
luajava	直接存取 Java 類別
module	模組系統（不需要）
os	作業系統存取
package	模組系統（不需要）
require	模組系統／檔案系統存取

可用的標準函式庫

LuaJ 標準環境提供以下常用 Lua 功能：

類別	函式
數學	math.abs、math.ceil、math.floor、math.max、math.min、math.random、math.sin、math.cos、math.sqrt、math.pi，以及所有其他 math.* 函式
字串	string.byte、string.char、string.find、string.format、string.gsub、string.len、string.lower、string.match、string.rep、string.sub、string.upper，以及所有其他 string.* 函式
表	table.insert、table.remove、table.sort、table.concat，以及所有其他 table.* 函式
迭代器	pairs、ipairs、next
型別	type、tostring、tonumber、select、unpack
錯誤處理	pcall、xpcall、error、assert
其他	print、rawget、rawset、rawequal、rawlen、setmetatable、getmetatable

os 函式庫無法使用

os 已完全移除。通用介面以 context.world:get_time() 取得世界時間，Boss 能力也從共用基底世界表取得此方法。要計算經過時間，可在 on_game_tick 中維護 context.state 的 tick 計數器。

提示

print 會寫入主控台，但建議使用 context.log:info(msg)。所有種類都有 context.log：FMM 與 NPC 提供 info、warn、error，Boss 提供 info、warn、debug。

---

檔案約定

每個 Lua 腳本必須 return 一張表。該表的結構刻意採嚴格規範。

必要與可選的頂層欄位

欄位	必填	型別	說明
api_version	是	number	目前必須為 1
priority	否	number	預設 0，轉換為整數。EliteMobs Boss 與 NPC 先執行較小值；FMM 驗證此欄，但道具依 scripts: 順序執行
支援的掛鉤鍵	否	function	必須使用外掛支援的精確掛鉤名稱

驗證規則

• 檔案必須回傳一張表。
• api_version 為必要欄位,目前必須為 1。
• 若提供 priority,必須為數字。
• 每個額外的頂層鍵都必須是受支援的 hook 名稱。
• 每個 hook 鍵都必須指向一個函式。
• 不認識的頂層鍵會被拒絕。

優先順序依提供者而異

驗證器在所有 MagmaCore 腳本中接受 priority。EliteMobs 用它排序 Boss 與 NPC；FMM 道具則依設定的 scripts: 清單順序。自訂附魔使用提供者目錄及動作、查詢生命週期。

腳本檔案存放位置

各提供者選擇自己的目錄。通用引擎遞迴尋找 .lua，排除已封存設定路徑。正規化的絕對路徑先不分大小寫排序，再依精確路徑排序。每個轉成小寫的檔名只選第一個，並記錄內容與選中檔案不同的略過重複檔案。選中的檔案驗證失敗也不會改用重複檔案。註冊查找保留實際檔名拼寫，請用相同拼寫引用。Boss 能力與附魔目錄有自己的搜尋規則，共用驗證器不代表目錄能互換。

檔名必須唯一

腳本是以檔案名稱為鍵,而非以路徑為鍵。位於不同子資料夾中的兩個 door.lua 是同一個鍵,最後只有其中一個會被註冊。請為每個腳本取一個獨特的檔名。

輔助函式與本地常數應放在最後 return 的上方,而不是放在回傳的表中（除非它們真的是 hook）。

local ANIMATION_NAME = "idle"

local function do_something(context)
  context.log:info("Doing something!")
end

return {
  api_version = 1,
  priority = 0,

  on_spawn = function(context)
    do_something(context)
  end
}

---

常見掛鉤名稱

這些名稱出現在多個執行環境，但各腳本只啟用適用的子集。FMM 道具使用下列全部掛鉤；Boss 使用專屬清單；NPC 使用 on_spawn、on_remove、on_game_tick、on_npc_interact、on_npc_proximity_enter、on_npc_proximity_leave、on_zone_enter、on_zone_leave。

掛鉤	觸發時機
on_spawn	由 FMM 道具、EliteMobs Boss 或 NPC 的生成流程觸發；僅建構 ScriptInstance 不會觸發
on_game_tick	已初始化實例處於啟用且未暫停狀態時，每個 tick 呼叫
on_zone_enter	相容區域的進入事件。FMM 與 NPC 監控玩家；Boss 頂層掛鉤來自 EliteScript 區域事件
on_zone_leave	相容區域的離開事件。FMM 與 NPC 監控玩家；Boss 頂層掛鉤來自 EliteScript 區域事件

---

方法語法:: 與 .

在 Lua 中，object:method(arg) 是 object.method(object, arg) 的簡寫。MagmaCore 的上下文資料表方法會移除隱含的第一個參數，因此 context.log.info 等方法可使用兩種寫法：

context.log:info("hello")
context.log.info("hello")  -- same thing

em 的全域函式使用 . 呼叫：em.create_location(...)、em.zone.create_sphere_zone(...) 和 em.location.is_protected(...)。EliteMobs 的事件修改函式 context.event.set_damage_amount(...) 和 context.event.multiply_damage_amount(...) 也必須使用 .。文件對上下文資料表方法使用 :，對一般函式使用 .。

---

執行預算

每次 hook 呼叫、每個排程回呼，以及腳本檔案本身的初次求值，都在一個硬性執行預算之下執行。該預算是在 Lua VM 內部強制執行的，因此它會在你的程式碼仍在執行時就生效，而不是只在事後檢查時鐘。

一般執行環境套用下列限制：

限制	數值
目前執行緒的 CPU 時間	50 毫秒
已執行的 Lua 指令數	250,000

超限會引發 Lua 錯誤。指令數逐條檢查；時鐘每 1,024 條指令與呼叫返回後檢查。它不會中斷正在執行的 Java/Bukkit 方法，50 毫秒 CPU 時間也不是實際經過時間 50 毫秒的期限。掛鉤或回呼的未捕捉錯誤會關閉實例；初次驗證則拒絕定義。無法測量執行緒 CPU 時間時，改用 250 毫秒經過時間與相同指令上限。附魔查詢批次可能有更小的額度。

無限迴圈會被中止，但仍會占用 tick

VM 在執行 Lua 指令時檢查預算，因此 while true do end 會被中止。它仍可能耗盡伺服器執行緒的 CPU 額度，並導致腳本停用；不要因為有這層保護就撰寫無界限迴圈。

巢狀呼叫共用一份預算：整條呼叫鏈共用50毫秒 CPU 時間和250,000條指令，每次呼叫沒有獨立額度。

要維持在預算內:

• 避免 hooks 內無界限的迴圈。
• 讓 on_game_tick 處理函式保持輕量 —— 它們每個 tick 都會執行。
• 使用 context.scheduler:run_repeating(...) 將工作分散到多個 tick。
• 用 context.cooldowns 或合理間隔限制高成本工作。

腳本執行階段錯誤

未捕捉的掛鉤或回呼錯誤會關閉實例，取消其所屬工作。請修正並重新載入定義，再讓提供者建立新實例。僅儲存檔案無法修復已關閉實例。附魔提供者也會套用自己的失敗抑制規則。

---

context.state

一張在腳本實例整個生命週期中保持的純 Lua 表。用來儲存旗標、計數器、任務 ID、切換狀態,以及任何需要在 hooks 之間共享的資料。

return {
  api_version = 1,

  on_spawn = function(context)
    context.state.is_open = false
    context.state.click_count = 0
    context.state.task_id = nil
  end,

  on_right_click = function(context)
    context.state.click_count = (context.state.click_count or 0) + 1
  end
}

資訊

context.state 在實例的掛鉤間共用資料，只在記憶體中存在，不會跨重新載入或重啟保存。其他表按需建構，可能包含快照。FMM 快取 context.prop，但 current_location 等欄位按需讀取。請再次讀取動態欄位以取得目前值；存入變數的表不會自動更新。寫入動態欄位會遮蔽 getter。

---

context.log

所有種類都可用的主控台日誌。通用 log.info 使用 [Lua] 前綴，需要辨識來源時請自行加入腳本標籤。錯誤診斷會指出檔案，一般日誌不會自動加上檔名。FMM 與 NPC 提供 info、warn、error；Boss 提供 info、warn、debug。

方法	說明
log:info(message)	資訊訊息
log:warn(message)	警告訊息
log:error(message)	警告等級訊息（以 WARN 等級記錄,與 log:warn 相同）

EliteMobs 版本

EliteMobs 的 context.log 註冊的是 debug 而非 error。使用 log:debug(message) 輸出除錯訊息（以 info 等級顯示並帶有 debug 前綴）。

context.log:info("Script loaded!")
context.log:warn("Something unexpected happened")
-- Generic/FMM/NPC logger:
context.log:error("Critical failure in zone setup")
-- EliteMobs boss logger:
context.log:debug("Boss debug detail")

---

context.cooldowns

本地冷卻與通用全域冷卻將設定的每個 tick 換算成單調時鐘的 50 毫秒，包含暫停和低 TPS 時間。Boss 全域冷卻則以伺服器 tick 計算。共有兩種範圍：

• 本地冷卻在擁有者儲存區使用精確字串鍵，範圍如下所列。nil 選擇預設鍵，即 __lua: 加腳本檔名。
• 全域冷卻由同一擁有者實體上的所有腳本共享（例如,同一個道具上的所有腳本,或同一個 Boss 上的所有 Lua 能力）。

cooldowns:check_local(key?, duration)

檢查本地鍵，就緒則啟動並回傳 true，否則回傳 false。這是單次同步 Lua 呼叫，不會檢查或啟動全域冷卻。此儲存區不是獨立的跨執行緒鎖定 API。

參數	型別	說明
key	string（可選）	冷卻識別碼。nil 選擇預設鍵
duration	int	以 ticks 計的冷卻時間（20 = 1 秒）

on_right_click = function(context)
  -- Only allow this action once every 3 seconds
  if not context.cooldowns:check_local("interact", 60) then
    return
  end
  -- ... do the action
end

共用參數順序

Boss、NPC、FMM 皆使用 check_local(key?, duration)。預設鍵須寫為 check_local(nil, 60)；check_local(60) 不代表預設鍵的 60 tick 冷卻。早期實驗性 NPC 版本的 check_local(duration, key?) 應改為目前的順序。

cooldowns:local_ready(key?)

若本地冷卻已過期（或從未設定）則回傳 true,仍在進行中則回傳 false。

cooldowns:local_remaining(key?)

回傳本地冷卻剩餘的 tick 數,若已就緒則為 0。

cooldowns:set_local(duration, key?)

設定本地冷卻,不檢查是否已有冷卻在進行中。可用於無條件重設冷卻。

參數	型別	說明
duration	int	以 ticks 計的時間。傳入 0 或負數則清除。
key	string（可選）	冷卻識別碼。nil 選擇預設鍵

cooldowns:global_ready()

若全域冷卻（同一實體上所有腳本共享）已過期則回傳 true。

cooldowns:set_global(duration)

設定全域冷卻。通用表中零或負數會清除冷卻。Boss 全域冷卻會保留較晚的到期時間：較短的持續時間永遠不會縮短仍有效的全域冷卻，零或負數則不會有任何作用。設定本地冷卻不會自動設定全域冷卻，反之亦然。

參數	型別	說明
duration	int	以 ticks 計的時間

全域冷卻範圍

全域冷卻的「擁有者」依腳本類型而定:

• EliteMobs Lua 能力 — 依 EliteEntity 共享（每個 Boss 一個槽位）。global_ready() / set_global() 使用 Boss 內建的能力冷卻系統;本地冷卻也會在同一 Boss 上的所有能力之間共享。
• EliteMobs NPC — 透過 NPC 的單一轉接器共用全域冷卻與明確指定的本地鍵。兩個腳本使用同鍵時互相影響；省略的鍵仍依檔名區分。
• FMM 道具 — 全域依已放置道具共用；各腳本有獨立轉接器與本地儲存區。
• 附魔動作 — 全域在提供者內依玩家共用；本地屬於玩家及附魔 ID，可跨裝備交換與動作完成保留。參閱自訂附魔。

---

context.scheduler

排程器執行延遲與重複任務。透過它建立的任務屬於實例，關閉時會取消。這不會撤銷已生成實體、世界修改或其他 UI／效果輔助方法的計時器。暫停時，到期的單次任務等待恢復，重複任務略過暫停期間的呼叫。

本節使用 MagmaCore 名稱（run_later、run_repeating、cancel）。EliteMobs 名稱（run_after(ticks, callback)、run_every(interval, callback)、cancel_task(taskId)）也是所有腳本介面接受的別名。

scheduler:run_later(ticks, callback)

延遲一段時間後執行一次回呼。回傳數字任務 ID。

參數	型別	說明
ticks	int	以伺服器 ticks 計的延遲（20 ticks = 1 秒）
callback	function	延遲結束時以全新的 context 呼叫

context.scheduler:run_later(40, function(delayed_context)
  delayed_context.log:info("2 seconds have passed!")
end)

scheduler:run_repeating(delay, interval, callback)

以固定間隔重複執行回呼。回傳數字任務 ID。

參數	型別	說明
delay	int	第一次執行前的初始延遲（ticks）
interval	int	後續每次執行間隔的 ticks
callback	function	每次間隔以全新的 context 呼叫

context.state.particle_task = context.scheduler:run_repeating(0, 20, function(tick_context)
  tick_context.log:info("Another second passed!")
end)

scheduler:cancel(taskId)

依 ID 取消本實例所屬任務。未知或其他實例的 ID 不會產生效果。

參數	型別	說明
taskId	int	由 run_later 或 run_repeating 回傳的任務 ID

用途結束時停止重複工作

關閉會自動取消所屬任務。互動或戰鬥階段結束但實例仍存在時，應提早取消，例如在 Boss 的 on_exit_combat。兩組名稱皆可用。請使用所屬外掛的生命週期掛鉤；因錯誤關閉時，不保證執行自訂清理掛鉤。

回呼會收到全新的 context

回呼收到不含原始事件或執行者的新上下文。請使用該參數而非外層上下文。之後若需要原玩家，請在掛鉤中儲存 UUID，稍後重新查找並確認可用。保留的外層上下文也可能在原事件結束後才解析延遲事件欄位。

---

context.world

世界表提供查詢與操作方法，首次建構時捕捉擁有者目前的世界。儲存的表不會跟隨之後的世界變更。

共用世界表

這裡說明 FMM 道具與 NPC 使用的共用表，包括造成傷害的 strike_lightning(...)。FMM 加入可選的 EliteMobs 運輸與戰利品方法，參閱 FMM 世界表擴充。EliteMobs 為共用表加入檢查區塊載入狀態的視覺閃電、NPC 與 Boss 生成功能。Boss 能力再覆寫或加入專屬方法，參閱 EliteMobs 世界與環境。

座標與位置表形式並存

通用介面同時接受 strike_lightning(x, y, z)、spawn_particle(name, x, y, z, ...) 等座標形式，以及 strike_lightning_at_location(loc)、spawn_particle_at_location(loc, ...) 等位置表形式。Boss 也支援兩種形式，但部分位置表方法的行為不同。

共用位置參數須有 x、y、z。世界省略或無法解析時使用該表的世界。共用位置式粒子仍使用捕捉的世界，請提供同世界的位置。Boss 轉換器與 em.location.* 查詢有各自的規則。

完整世界表參考也介紹實體查找、通行性與保護查詢、彩色粉塵、地形衝擊及位置表形式。

world.name

包含世界名稱的字串欄位。

---

world:get_block_at(x, y, z)

回傳 "stone"、"air" 等小寫材質名。目標區塊未載入時回傳 "air"，不會強制載入。

參數	型別	說明
x	int	方塊 X 座標
y	int	方塊 Y 座標
z	int	方塊 Z 座標

---

world:set_block_at(x, y, z, material)

在主執行緒設定方塊，避免強制載入區塊。

參數	型別	說明
x	int	方塊 X 座標
y	int	方塊 Y 座標
z	int	方塊 Z 座標
material	string	Bukkit Material 名稱,小寫（例如 "stone"、"air"、"oak_planks"）

材質有效且修改已排入佇列時回傳 true，材質無效則回傳 false。任務執行時區塊未載入，會略過修改。

不會自動檢查區域保護。請使用方塊材質，並先執行相關保護查詢。接受請求不代表方塊已變更。

---

world:spawn_particle(particle, x, y, z, count, dx, dy, dz, speed)

於指定位置生成粒子。

參數	型別	預設值	說明
particle	string	必填	Bukkit Particle 列舉名稱，查找時轉為大寫，例如 "FLAME"、"HAPPY_VILLAGER"
x	number	必填	X 座標
y	number	必填	Y 座標
z	number	必填	Z 座標
count	int	1	粒子數量
dx	number	0	X 分散／偏移
dy	number	0	Y 分散／偏移
dz	number	0	Z 分散／偏移
speed	number	0	粒子速度

需要資料的粒子

DUST、FALLING_DUST 等粒子需要此簡易 API 不提供的額外資料。請使用 CLOUD、SMOKE、CAMPFIRE_COSY_SMOKE、SNOWFLAKE、FLAME、HAPPY_VILLAGER、HEART、NOTE、ENCHANT 等不需資料的粒子。彩色粉塵可用世界表參考的 world:spawn_dust(...)。

因未提供 Bukkit 粒子資料物件，需要資料的粒子可能拋出例外並停用實例。FMM/MagmaCore 腳本應優先使用上述不需資料的粒子。

---

world:play_sound(sound, x, y, z, volume, pitch)

於指定位置播放音效。

參數	型別	預設值	說明
sound	string	必填	Bukkit Sound 列舉名稱（例如 "ENTITY_EXPERIENCE_ORB_PICKUP"），或自訂資源包音效鍵（例如 "mypack:boss.roar"）
x	number	必填	X 座標
y	number	必填	Y 座標
z	number	必填	Z 座標
volume	number	1.0	音量
pitch	number	1.0	音高

自訂資源包音效

該名稱會先與 Bukkit 已註冊的音效比對（不分大小寫，因此 "ENTITY_ARROW_SHOOT" 與 "entity_arrow_shoot" 相同）。若沒有符合項目，它會被正規化為小寫的具命名空間鍵，並作為自訂資源包音效播放。既非已知音效、也非有效具命名空間鍵的值會不播放任何東西，而不會引發錯誤，因此打錯字只會靜默無作用，而不會停用你的腳本。

world:play_sound_at_location(loc, sound, volume, pitch) 同樣適用。

---

world:strike_lightning(x, y, z)

於指定位置降下閃電（具視覺效果並造成傷害）。

參數	型別	說明
x	number	X 座標
y	number	Y 座標
z	number	Z 座標

---

world:get_time()

回傳目前世界時間（ticks）。

---

world:set_time(ticks)

設定世界時間。

參數	型別	說明
ticks	int	世界時間（0 = 日出,6000 = 中午,13000 = 夜晚,18000 = 午夜）

---

world:get_nearby_entities(x, y, z, radius)

回傳以指定座標為中心、與座標軸平行的盒內實體表陣列，索引從 1 開始。不排除腳本擁有者。

參數	型別	說明
x	number	中心 X
y	number	中心 Y
z	number	中心 Z
radius	number	搜尋半徑（在三軸上皆作為半延伸值使用）

警告

回傳範圍內所有實體，包含掉落物、投射物等非生物實體。呼叫生物方法前請檢查 if entity.damage then。

---

world:get_nearby_players(x, y, z, radius)

回傳軸對齊盒內的玩家陣列，索引從 1 開始，radius 是每軸半邊長。不依遊戲模式過濾。

參數	型別	說明
x	number	中心 X
y	number	中心 Y
z	number	中心 Z
radius	number	搜尋半徑

---

world:spawn_entity(entity_type, x, y, z)

於指定位置生成原版 Minecraft 實體。

參數	型別	說明
entity_type	string	Bukkit 實體類型名稱,小寫（例如 "zombie"、"skeleton"、"pig"）
x	number	X 座標
y	number	Y 座標
z	number	Z 座標

回傳實體表，適用時含生物方法。未知列舉名稱回傳 nil；有效但無法生成的類型可能拋出錯誤。不檢查區塊是否已載入。

---

world:get_highest_block_y(x, z)

回傳 Bukkit 查詢的 X/Z 最高方塊 Y。與 get_block_at 不同，不檢查區塊載入狀態。

參數	型別	說明
x	int	方塊 X 座標
z	int	方塊 Z 座標

---

world:raycast(from_x, from_y, from_z, dir_x, dir_y, dir_z, [max_distance], [fluid_mode], [blocks_only], [loaded_only])

從一個點朝一個方向射出射線,並回傳所擊中物的資訊。

參數	型別	預設值	說明
from_x	number	必填	起點 X
from_y	number	必填	起點 Y
from_z	number	必填	起點 Z
dir_x	number	必填	方向 X 分量
dir_y	number	必填	方向 Y 分量
dir_z	number	必填	方向 Z 分量
max_distance	number	50	射線最大距離
fluid_mode	string	"NEVER"	NEVER、SOURCE_ONLY 或 ALWAYS
blocks_only	boolean	false	忽略實體，只檢測方塊
loaded_only	boolean	false	射線包圍矩形內有未載入區塊時，不追蹤而回傳 nil

loaded_only=true 時也要檢查 nil 結果。否則，未命中會回傳命中欄位為 nil 的表：

欄位	型別	說明
hit_entity	entity table or nil	射線擊中的第一個實體,若無則為 nil
hit_location	location table or nil	射線擊中物的精確位置
hit_block	table or nil	擊中方塊的 {x, y, z, material},若未擊中方塊則為 nil

方塊材質是小寫。組合追蹤使用實體射線大小 0.5，沒有實體過濾器。區塊檢查涵蓋整個包圍矩形，可能因偏離實際射線的未載入區塊而拒絕。無效流體模式名稱會拋出錯誤。

---

world:spawn_firework(x, y, z, colors, [type], [power])

於指定位置生成煙火火箭。

參數	型別	預設值	說明
x	number	必填	X 座標
y	number	必填	Y 座標
z	number	必填	Z 座標
colors	table	必填	顏色字串陣列，例如 {"RED", "BLUE", "WHITE"}
type	string	"BALL"	煙火形狀:"BALL"、"BALL_LARGE"、"STAR"、"BURST"、"CREEPER"
power	int	1	飛行高度,0-127

-- Example: red and yellow firework burst
context.world:spawn_firework(loc.x, loc.y, loc.z, {"RED", "YELLOW"}, "BURST", 2)

---

world:place_temporary_block(x, y, z, material, [ticks], [require_air])

放置暫時方塊，正數時間後還原儲存的 BlockData。不保存完整方塊狀態或物品欄。

參數	型別	預設值	說明
x	int	必填	方塊 X 座標
y	int	必填	方塊 Y 座標
z	int	必填	方塊 Z 座標
material	string	必填	Bukkit Material 名稱（例如 "stone"、"ice"）
ticks	int	0	還原前的 tick 數。零或負數會永久放置方塊，且不加以追蹤
require_air	boolean	false	若為 true,僅在目標為空氣時放置方塊

材質無效或目標區塊未載入時回傳 false，否則請求接受後回傳 true。require_air=true 且目標非空氣時，即使請求已接受，管理器也會略過替換。

tick 數為正數時，管理器會儲存原本的方塊資料，並在計時器結束、區塊或世界卸載，或外掛關閉時還原。只有當該位置仍是這個暫時方塊時才會還原，因此之後的編輯不會被覆蓋。在仍為暫時方塊的位置再次放置，會重新開始計時，並保留第一次儲存的原始方塊。帶有方塊實體的方塊（例如箱子與告示牌），以及已被其他暫時方塊擁有者（例如附魔租約）持有的方塊，都會被略過。破壞暫時方塊不會掉落任何物品，並會結束追蹤且不還原；在該處放置方塊也會結束追蹤。

計時器不隨 Lua 腳本取消，放置也不自動檢查區域保護。

---

world:drop_item(x, y, z, material, [amount])

於指定位置自然散落物品實體。

參數	型別	預設值	說明
x	number	必填	X 座標
y	number	必填	Y 座標
z	number	必填	Z 座標
material	string	必填	Bukkit Material 名稱
amount	int	1	堆疊大小

回傳所掉落物品的實體表,若材質無效則回傳 nil。

---

context.zones

區域表可建立空間區域並監控玩家進出。FMM 道具與 NPC 使用此處的 create_sphere(...)、create_cylinder(...)、create_cuboid(...)、watch(...)、unwatch(...)，觸發 on_zone_enter 和 on_zone_leave。區域屬於實例，關閉時自動清理。Boss 使用獨立專屬表，提供 get_entities_in_zone(...)、get_locations_in_zone(...)、watch_zone(...)；參閱 EliteMobs 區域與目標。

zones:create_sphere(x, y, z, radius)

以指定座標為中心建立球體，回傳數字控制代碼；擁有者沒有世界時回傳 nil。

參數	型別	說明
x	number	中心 X
y	number	中心 Y
z	number	中心 Z
radius	number	球體半徑

---

zones:create_cylinder(x, y, z, radius, height)

建立圓柱，回傳數字控制代碼；擁有者沒有世界時回傳 nil。

參數	型別	說明
x	number	中心 X
y	number	中心 Y（底部）
z	number	中心 Z
radius	number	圓柱半徑
height	number	圓柱高度

---

zones:create_cuboid(x, y, z, xSize, ySize, zSize)

建立長方體，回傳數字控制代碼；擁有者沒有世界時回傳 nil。通用監控測試玩家位置點，尺寸是中心周圍的半邊長，與 Boss 區域的實體重疊、取樣位置操作不同。若 zSize 是零且 xSize 非零，共用形狀會以 xSize 代替 Z。

參數	型別	說明
x	number	中心 X
y	number	中心 Y
z	number	中心 Z
xSize	number	X 軸半延伸
ySize	number	Y 軸半延伸
zSize	number	Z 軸半延伸

---

zones:watch(handle, onEnterCallback, onLeaveCallback)

啟用已建立區域的進出通知。回呼參數須為 Lua 函式，但不直接執行其本體，邏輯由 on_zone_enter 和 on_zone_leave 執行。成員追蹤從建立時開始，稍後加入 watch 不會為已被記錄在內的玩家補發進入事件。後續呼叫傳 nil 不會清除已啟用的通知。

參數	型別	說明
handle	int	從 create_* 呼叫取得的區域 handle
onEnterCallback	function 或 nil	函式啟用 on_zone_enter，函式本體被忽略
onLeaveCallback	function 或 nil	函式啟用 on_zone_leave，函式本體被忽略

若監控設定成功則回傳 true,若區域 handle 無效則回傳 nil。

資訊

檢查在 on_game_tick 之前執行，使用擁有者目前世界中玩家的位置點，而非完整邊界盒。球體要求嚴格位於半徑內；圓柱要求在半徑內，包含底面、不含頂面。區域保留建立時的座標與世界。斷線或移除監控不保證觸發離開掛鉤。請維持合理區域數量。

---

zones:unwatch(handle)

停止監控區域,並清理其資源。

參數	型別	說明
handle	int	要停止監控的區域 handle

---

範例：接近觸發區域

return {
  api_version = 1,

  on_spawn = function(context)
    local loc = context.prop.current_location
    if loc == nil then return end

    local handle = context.zones:create_sphere(loc.x, loc.y, loc.z, 5)

    -- Pass placeholder functions to enable on_zone_enter and on_zone_leave hooks.
    -- The placeholder bodies are ignored; the actual logic goes in the hooks below.
    context.zones:watch(handle, function() end, function() end)

    context.state.zone_handle = handle
  end,

  on_zone_enter = function(context)
    context.log:info("Player entered zone!")
  end,

  on_zone_leave = function(context)
    context.log:info("Player left zone!")
  end,

  on_destroy = function(context)
    if context.state.zone_handle then
      context.zones:unwatch(context.state.zone_handle)
    end
  end
}

---

context.event

掛鉤具有事件或執行者時出現此表。FMM 道具點擊使用外掛取消旗標，NPC 互動和通用區域可在沒有 Bukkit 事件時提供執行者。on_game_tick、排程回呼、沒有觸發玩家的生命週期掛鉤中不存在。

FMM 道具的 on_projectile_hit 掛鉤會收到可取消的 FreeMinecraftModels 投射物命中事件，因此提供 cancel() 與 uncancel()。此掛鉤在 FMM 處理完命中之後才執行，所以取消並不能阻止非穿透投射物被消耗。若其他外掛已取消這次命中，此掛鉤不會觸發。射擊者為存活實體（可能是生物）時，context.event.player 就是射擊者，否則不存在；context.player 只有在玩家發射投射物時才會設定。此掛鉤也會以實體表的形式提供 context.projectile，代表該投射物。

通用 on_zone_enter、on_zone_leave 的 context.player 與 context.event.player 是進入或離開的玩家。它們沒有可取消 Bukkit 事件，所以不提供 cancel() 或 uncancel()。

欄位 / 方法	型別	說明
is_cancelled	boolean	首次解析事件子表時的取消狀態。cancel()、uncancel() 不會刷新此值
cancel()	method	取消事件，僅在可取消事件中存在
uncancel()	method	解除取消，僅在可取消事件中存在
player	entity table	事件中涉及的玩家（若有）

on_right_click = function(context)
  if context.event and context.event.cancel then
    context.event:cancel()  -- prevent the default right-click interaction
  end
end

EliteMobs 事件表

EliteMobs 能力有更詳細的事件表，包括傷害量、原因、來源與修改方法。完整欄位參閱 Lua API 參考。

---

em 輔助命名空間

em 在檔案載入時可用。建構函式只建立資料，不載入世界、註冊監控或驗證完整形狀。回傳的 setter 修改自身資料表，並保留傳入位置表的參考。

函式	用途
em.create_location(x, y, z [, world, yaw, pitch])	建立位置表,可選 world 名稱、yaw 與 pitch。回傳的表還有一個 .add(dx, dy, dz) 方法,可就地偏移位置並回傳自身以便鏈式呼叫。
em.create_vector(x, y, z)	建立向量表
em.zone.create_sphere_zone(radius)	建立球形區域定義
em.zone.create_dome_zone(radius)	建立穹頂區域定義
em.zone.create_cylinder_zone(radius, height)	建立圓柱區域定義
em.zone.create_cuboid_zone(x, y, z)	建立長方體區域定義
em.zone.create_cone_zone(length, radius)	建立錐形區域定義
em.zone.create_static_ray_zone(length, thickness)	建立靜態射線區域定義
em.zone.create_rotating_ray_zone(length, point_radius, animation_duration)	建立旋轉射線區域定義
em.zone.create_translating_ray_zone(length, point_radius, animation_duration)	建立平移射線區域定義
em.location.is_in_dungeon(loc)	檢查位置是否位於任何已註冊的地下城區域內（任何回報 "dungeon" 種類的擁有者）
em.location.is_protected(loc)	檢查位置是否位於任何受保護的區域內（WorldGuard、GriefPrevention、EM 區域等）
em.location.owned_by(loc, namespace)	檢查特定外掛命名空間是否擁有該位置（例如 "EliteMobs"）
em.location.owners(loc)	擁有該位置的命名空間字串陣列
em.location.kinds_at(loc)	該位置的種類標籤陣列（"elitemobs"、"dungeon"、"world_package"、"open_world_dungeon"、地下城大小分類）
em.location.has_kind(loc, kind)	檢查位置是否帶有指定種類的標籤

自動偵測區域外掛

MagmaCore 內附 WorldGuard 與 GriefPrevention 轉接器，由使用方啟用時初始化，保護查詢也可按需初始化。查詢涵蓋已註冊提供者，不是所有保護外掛。已註冊區域轉接器失敗時回報為受保護。沒有提供者或保護歸屬時回傳 false；警告會指出缺少的提供者。

em.location.* 的 world 須為已載入世界名或 {name=...}，不會退回擁有者世界。世界缺失、無法解析或輸入 nil 時回傳 false 或空陣列。缺少座標預設零，但格式錯誤的數值欄位可能拋出錯誤。擁有權命名空間區分大小寫，種類標籤不區分。擁有位置不代表屬於地下城或受保護。回傳陣列順序不保證。

區域建構函式回傳可鏈式呼叫的表，提供 :set_center(loc)，或依種類提供 :set_origin(loc)、:set_destination(loc)：

-- At file scope: create a reusable zone shape
local blast_zone = em.zone.create_sphere_zone(5)

return {
  api_version = 1,

  on_spawn = function(context)
    -- Anchor the zone at call time
    blast_zone:set_center(context.boss:get_location())
    local entities = context.zones:get_entities_in_zone(blast_zone)
    -- ...
  end
}

資訊

em 命名空間在 EliteMobs 中特別有用,因為區域定義會與 context.zones:get_entities_in_zone() 及 context.script 一同使用。在 FreeMinecraftModels 中,context.zones:create_sphere(...) / create_cylinder(...) / create_cuboid(...) 方法更常用於簡單的監控型區域。

---

實體表

下表介紹常用方法。完整 Lua API 參考還涵蓋投射物欄位、移動路徑檢查、擁有權與保護方法，適用於通用實體表。Boss 能力專用包裝表有獨立章節。

世界查詢與事件資料會回傳實體表，依實體種類提供不同層次的欄位及方法。

實體基本欄位

欄位	型別	說明
uuid	string	實體的 UUID
entity_type	string	實體類型（例如 "player"、"zombie"、"skeleton"、"villager"）
is_valid	boolean	實體參考是否仍有效
is_dead	boolean	實體是否已死亡
is_player	boolean	實體是否為玩家
is_hostile	boolean	是否實作 Bukkit Monster，不代表目前敵意
is_passive	boolean	是否實作 Bukkit Animals，不保證被動行為
current_location	location table	實體當前位置（x、y、z、world、yaw、pitch）
world	string	實體所在的世界名稱

實體基本方法

方法	回傳值	說明
teleport(location_table)	void	必須提供 x、y、z；世界省略或無法解析時用實體世界。yaw、pitch 預設零。不自動檢查移動路徑或保護
remove()	void	從世界中移除實體。僅在實體仍有效時生效。
set_silent(flag)	void	抑制或重新啟用實體聲音。
set_invulnerable(flag)	void	使實體無敵或可受傷。
set_gravity(flag)	void	啟用或停用實體重力。
set_glowing(flag)	void	切換實體的發光輪廓效果。

---

生物實體欄位

生物實體（玩家、生物等）擁有所有實體基本欄位之外,還包括:

欄位	型別	說明
health	number	當前生命值
maximum_health	number	最大生命值
name	string	顯示名稱
is_alive	boolean	實體是否存活

生物實體方法

方法	回傳值	說明
damage(amount)	void	對實體造成指定數量的傷害
push(x, y, z)	void	立即將向量加到目前速度
set_facing(x, y, z)	void	在原地以新朝向傳送
add_potion_effect(effect, duration, amplifier)	void	加上藥水效果。effect 為字串（如 "speed"、"slowness"、"regeneration"）。duration 以 ticks 計。amplifier 為效果等級減 1（0 = 等級 I）。
remove_potion_effect(effect)	void	依名稱移除藥水效果
get_scale()	number	回傳含修飾值的有效縮放，無法使用時為 1.0
set_scale(value)	void	屬性可用時修改縮放基礎值

警告

並非所有由 get_nearby_entities() 回傳的實體都是生物實體。可以使用 entity.is_player、entity.is_hostile 或 entity.is_passive 依分類過濾,或在呼叫 damage()、push()、add_potion_effect() 等生物實體方法前以 if entity.damage then 加以判斷。

---

外掛整合欄位

實體表可包含整合欄位，沒有相應擴充器時欄位不存在，讀取為 nil。追蹤旗標、模型識別、管理員狀態與多數巢狀資料是建構時快照，不跟隨之後的追蹤變更。共用 EliteMobs 生命欄位按需取得，模型與權限方法在呼叫時查詢底層物件。

EliteMobs 欄位

當 EliteMobs 已安裝時可用。

欄位	型別	說明
is_elite	boolean	實體是否為 EliteMobs 精英
is_custom_boss	boolean	實體是否為 EliteMobs 自訂 Boss（也可在 elite 子表中取得）
is_significant_boss	boolean	實體是否為生命值倍率超過 1 的自訂 Boss(即設計過的戰鬥,而非普通的精英)
elite	table or nil	精英資訊子表（見下）。若實體非精英則為 nil。

elite 子表包含:

欄位	型別	說明
elite.level	int	精英的等級
elite.name	string 或 nil	精英的顯示名稱
elite.health	number	當前生命值
elite.max_health	number	最大生命值
elite.is_custom_boss	boolean	是否為自訂 Boss（相對於天然精英）
elite.health_multiplier	number	設定檔定義的生命值倍率
elite.damage_multiplier	number	設定檔定義的傷害倍率
elite:remove()	void	透過 EliteMobs 移除流程移除精英；不等於擊殺，也不保證戰利品

範例:對精英採用不同傷害

local entities = context.world:get_nearby_entities(x, y, z, 5)
for _, entity in ipairs(entities) do
    if entity.is_elite then
        -- Deal double damage to elites
        entity:damage(20)
        context.log:info("Hit elite: " .. entity.elite.name .. " (level " .. entity.elite.level .. ")")
    elseif entity.is_hostile then
        entity:damage(10)
    end
end

FreeMinecraftModels 欄位

當 FreeMinecraftModels 已安裝時可用。

欄位	型別	說明
is_modeled	boolean	實體是否附加 FMM 模型（DynamicEntity 或 PropEntity）
is_prop	boolean	實體是否為 FMM 道具（靜態裝飾用實體）
model	table or nil	模型資訊子表（見下）。若實體未附帶模型則為 nil。

model 子表包含:

欄位	型別	說明
model.model_id	string 或 nil	模型藍圖 ID（例如 "torch_01"）
model.is_dynamic	boolean	帶模型的實體是否為 DynamicEntity（生物／Boss 模型）而非靜態道具
model:play_animation(name, [blend], [loop])	boolean	接受動畫請求。blend、loop 預設 false。排隊或受抑制的攻擊可回傳 true 而未立即播放；終結死亡狀態拒絕播放
model:stop_animations()	void	清除播放佇列，並在可用時回到待機動畫；不影響終結死亡狀態
model:remove()	void	透過 FMM 的標準移除流程移除帶模型的實體。

FMM 還會在玩家表加入：

欄位 / 方法	型別	說明
is_op	boolean	玩家是否為伺服器管理員
has_permission(node)	boolean	玩家是否擁有權限

這兩個玩家值只存在於 FreeMinecraftModels 腳本中。在 EliteMobs 內建立的共用表上，EliteMobs 自己的 FreeMinecraftModels 轉接器會加入 is_modeled、is_prop 與 model，但不加入 is_op 或 has_permission。

FMM 玩家表的 is_holding_elitemobs_item(filename) 檢查主手 EliteMobs 檔名標籤，包含 .yml，不是顯示名稱。空手、其他物品或整合不可用時回傳 false。EliteMobs 自己的共用擴充器會在資料可用時加入含戰鬥 tier 的 elite_player；FMM 的可選 EliteMobs 轉接器不加入此子表。

橋接與道具的預設值

模型橋接的 blend、loop 預設 false。道具表 的 play_animation 兩者預設 true，啟用排隊與循環。blend 控制排隊，不是動畫交叉淡化。

範例:依類型過濾實體

local entities = context.world:get_nearby_entities(x, y, z, 10)
for _, entity in ipairs(entities) do
    if entity.is_prop then
        -- Skip props
    elseif entity.is_player then
        entity:damage(5)
    elseif entity.entity_type == "villager" then
        -- Don't hurt villagers
    elseif entity.is_elite then
        entity:damage(20)
    elseif entity.is_hostile then
        entity:damage(10)
    end
end

---

玩家專屬欄位

玩家實體在所有實體與生物實體欄位之外還包含:

欄位	型別	說明
game_mode	string	玩家的遊戲模式（"creative"、"survival"、"adventure"、"spectator"）

玩家專屬方法

文字格式

在 API 中任何標示「支援色碼」的地方，Magmacore 都會把該字串交給它內建的 MiniMessage 解析器。舊式 & 色碼、&#RRGGBB 十六進位、<#RRGGBB>、<gradient>、<rainbow> 以及 MiniMessage 標籤集的其餘部分全都可用，且可自由混用。Kyori Adventure 不是相依項目，腳本也無法取得任何 Adventure API —— 你不需要它。

Lua 的文字方法會向下轉換為舊式色碼字串，因此顏色、漸層與裝飾都能正確呈現，而互動標籤（<hover>、<click>、<insert>、<font>、<key>、<lang>）雖會被解析但不會有效果。完整標籤清單請參閱顏色代碼。

方法	回傳值	說明
send_message(msg)	void	對玩家傳送聊天訊息。支援 & 色碼。
chat(text)	void	將色彩處理後的文字交給 Bukkit 玩家聊天，斜線開頭的指令以該玩家身分執行
get_held_item()	table 或 nil	回傳主手的 {type, amount, display_name}，空手為 nil。type 是 "GOLD_INGOT" 等大寫 Bukkit Material 名
consume_held_item(amount?)	void	將消耗請求排入佇列，使用執行時的主手物品。預設 1；不保留先前檢查的物品，也不確認付款。請傳正數，負數不會被拒絕
has_item(material, amount?)	boolean	若玩家物品欄任何位置至少有 amount（預設 1）數量的指定材質則回傳 true
get_target_entity([range])	entity table 或 nil	從眼部追蹤方塊與實體，排除玩家自身，實體射線大小 0.5。忽略流體和可通行方塊，預設範圍 50
get_eye_location()	location table	回傳玩家眼睛高度的位置表
get_look_direction()	table	回傳玩家視線方向的 {x, y, z} 方向向量
send_block_change(x, y, z, material, [ticks])	boolean	將客戶端專用方塊排入佇列，正數 ticks 後還原。true 表示已排程；無效或非方塊材質回傳 false
reset_block(x, y, z)	boolean	排程還原真實方塊的顯示，回傳 true
sleep(x, y, z)	void	排程放置真實白床並嘗試睡眠。起床或斷線只還原 BlockData，不還原方塊實體內容
wake_up()	void	喚醒正在睡眠的玩家。

排程的方塊修改與還原在執行時讀取玩家世界，不要依賴它們在換世界後還原原本方塊。睡眠清理在 20 tick 後檢查，之後每 10 tick 檢查。這些任務不屬於 context.scheduler。

---

玩家 UI 方法

下列是共用玩家表方法。Boss 能力的玩家表有不同 UI 簽章，列於 API 參考。共用條在宿主外掛的 MagmaCore 副本內依玩家識別，不依腳本區分。到期計時器只會移除啟動它的那個 Boss 條或重複動作列，因此舊的到期計時器不會清除較新的項目。其 Bukkit 計時器不屬於 context.scheduler。

player:show_boss_bar(text, [color], progress, [ticks])

替換玩家共用的實心 Boss 條。進度限制在 0..1，無效顏色改為白色。省略顏色時傳 nil，讓進度保留在第三個參數。

參數	型別	預設值	說明
text	string	必填	要顯示的文字。支援 & 色碼。
color	string	"WHITE"	血條顏色。可為:"RED"、"BLUE"、"GREEN"、"YELLOW"、"PURPLE"、"PINK"、"WHITE"
progress	number	必填	填充量，從 0.0（空）到 1.0（滿）
ticks	int	-1	正數安排移除；否則保留到隱藏或替換

player:hide_boss_bar()

從玩家畫面上移除 Boss 血條。不需參數。

player:show_action_bar(text, [ticks])

於動作列區域（快捷欄上方）顯示文字。

參數	型別	預設值	說明
text	string	必填	要顯示的文字。支援 & 色碼。
ticks	int	-1	正數每 40 tick 重送直到到期，否則只送一次。新呼叫取消先前重複任務

player:show_title(title, [subtitle], fade_in, stay, fade_out)

向玩家顯示標題畫面。

參數	型別	預設值	說明
title	string	必填	主標題文字。支援 & 色碼。
subtitle	string	""	主標題下方的副標題。可選。
fade_in	int	必填	淡入持續 ticks
stay	int	必填	標題在畫面上停留的 ticks
fade_out	int	必填	淡出持續 ticks

---

下一步

各外掛專屬的 hooks、API 與工作流程:

• EliteMobs: 開始使用 | NPC 腳本 | 掛鉤與生命週期 | Boss 與實體 | 世界與環境 | 區域與目標
• FreeMinecraftModels: 開始使用 | 道具 API | 範例