Lua API 參考

本參考說明 MagmaCore、FreeMinecraftModels 與 EliteMobs 的 Lua 資料表及執行情境。共用資料表與 Boss 能力資料表的契約不同，請參閱符合所撰寫腳本的章節。

大多數資料表方法同時接受 table.method(...) 與 table:method(...)。全域函式 em.create_*、em.zone.create_*、em.location.* 及下文標明的 Boss 事件傷害設定器必須使用點號。共用即時欄位在存取時解析；需要新值時重新讀取，勿賦值，否則會遮蔽查詢。儲存在 Lua 變數中的位置或其他快照不會自行更新。

標明會處理顏色的方法使用共用的顏色代碼語法，包括聊天、標題、狀態列、自訂名稱及 prop 容器標題。

實體資料表

MagmaCore 的 entity table 是通用實體值的基礎；Living Entity、Player 與 FreeMinecraftModels Prop 資料表都繼承自它。

屬性

欄位	型別	說明
uuid	string	實體 UUID。
entity_type	string	小寫的 Bukkit 實體型別。
is_valid	bool	即時的有效性值。
is_dead	bool	即時的死亡狀態。
current_location	table/nil	即時的 {x, y, z, yaw, pitch, world} 位置。
world	string/nil	即時的世界名稱。
is_player	bool	該實體是否為玩家。
is_hostile	bool	該實體是否實作 Bukkit Monster。
is_passive	bool	該實體是否實作 Bukkit Animals。
is_on_ground	bool	即時著地狀態。
is_flying	bool	即時玩家飛行狀態；其他實體型別為 false。
in_block	bool	僅箭矢：目前是否嵌入方塊。
attachment_location	table/nil	包含嵌入箭矢目前位置的方塊中心；未嵌入時為 nil。
attachment_block	table/nil	由啟用中的附魔動作所擁有之箭矢實際擊中的方塊中心。沒有有效的已記錄嵌入命中，或箭矢移開、切換世界、其動作結束後，回傳 nil。用於辨識被擊中的方塊，不提供可避免碰撞的移動目的地。

方法

方法	參數	回傳	說明
teleport(location)	table	nil	傳送到某個位置表。
remove()	—	nil	若實體仍有效則移除它。
set_silent(enabled)	bool	nil	設定靜音狀態。
set_invulnerable(enabled)	bool	nil	設定無敵狀態。
set_gravity(enabled)	bool	nil	設定重力狀態。
set_glowing(enabled)	bool	nil	設定發光狀態。
set_velocity(x, y, z)	number, number, number	nil	取代速度；分量必須有限。
set_fall_distance(distance)	number	nil	設定有限且非負的墜落距離。
set_shooter(uuid)	string	bool	僅投射物：指定已解析且實作 Bukkit ProjectileSource 的實體。
set_direction(x, y, z)	number, number, number	nil	僅火球：設定有限且非零的飛行方向。
set_pickup(status)	string	nil	僅箭矢：ALLOWED、DISALLOWED 或 CREATIVE_ONLY。
can_receive_hostile_effect(actor_uuid)	string	bool	檢查目標能否接受該線上玩家的敵對效果；提供者可增加戰鬥限制。
has_clear_movement_path(location)	table	bool	預先檢查同世界位移的碰撞、世界邊界和已載入區塊。非玩家實體還會拒絕保護區域。不會移動實體。
movement_path_status(location)	table	string	回傳 clear、blocked、protected 或 unavailable；protected 適用於非玩家實體。碰撞檢查會保守掃描實體邊界框經過的體積。

玩家路徑暢通不代表獲准進入或戰鬥。實際移動仍受原有移動監聽器約束，包括區域進入限制；單純的建築保護不會阻止玩家通行。

共用位置參數必須有 x、y、z。世界省略或名稱無法解析時使用實體世界。獨立的 em.location.* 查詢要求已載入世界，省略座標為零。移動預檢與 can_receive_hostile_effect 不會自動套用於直接傳送、速度或傷害呼叫。

can_receive_hostile_effect 要求有效線上玩家作為行為者，目標為同世界內有效、存活的非玩家。它拒絕盔甲座、無敵實體、帶 NPC 標籤的實體和已馴服動物。EliteMobs 可增加戰鬥授權限制。set_shooter、set_owner 的無效 UUID，以及無效拾取列舉名稱，可能引發錯誤。

實體資料表：EliteMobs 增補

EliteMobs 增補器加入以下資料。追蹤旗標與 elite 是否存在在建表時決定，只有標明即時的欄位會在存取時更新。FreeMinecraftModels 的選用 EliteMobs 轉接器會加入精英資訊，但不加入 elite_player。

屬性

欄位	型別	說明
is_elite	bool	建表時 EliteMobs 是否追蹤該實體。
is_custom_boss	bool	被追蹤的 elite 是否為自訂 Boss。
is_significant_boss	bool	是否為生命值倍率大於 1 的自訂 Boss。
elite	table/nil	巢狀 EliteMobs 資料，只有成功解析出 elite 時才存在。
elite.level	int	Elite 等級快照。
elite.name	string/nil	Elite 顯示名稱快照。
elite.health	number	即時生命值。
elite.max_health	number	即時最大生命值。
elite.is_custom_boss	bool	該 elite 是否為自訂 Boss。
elite.health_multiplier	number	已設定的生命值倍率快照。
elite.damage_multiplier	number	已設定的傷害倍率快照。
elite_player	table/nil	僅玩家：存在 EliteMobs 玩家資料時按需解析的表。
elite_player.tier	number	由技能 XP 計算的戰鬥階級，不更新附魔查詢。

方法

方法	參數	回傳	說明
elite.remove()	—	nil	透過 EliteMobs 的移除流程移除該 elite。

實體資料表：FreeMinecraftModels 增補

FreeMinecraftModels 增補器加入以下快照；建表時 is_modeled 為 true 才有 model。玩家專用值只出現在玩家表。模型與權限方法會在呼叫時查詢底層物件。在 EliteMobs 腳本中，EliteMobs 的選用 FreeMinecraftModels 轉接器會加入 is_modeled、is_prop 與 model，但不加入 is_op 或 has_permission。

屬性

欄位	型別	說明
is_modeled	bool	FreeMinecraftModels 是否解析出一個帶模型的實體。
is_prop	bool	該實體是否為以盔甲座為基底的 FreeMinecraftModels prop。
model	table/nil	巢狀模型資料，只有在帶模型的實體上才存在。
model.model_id	string/nil	模型藍圖識別碼。
model.is_dynamic	bool	該帶模型實體是否為動態。
is_op	bool	僅限玩家的伺服器管理員狀態。

方法

方法	參數	回傳	說明
model.play_animation(name, blend?=false, loop?=false)	string, bool?=false, bool?=false	bool	回傳播放是否獲接受，包括排隊或被抑制的攻擊請求；終止死亡狀態拒絕播放。
model.stop_animations()	—	nil	清除待播佇列並在可用時回到 idle；保留終止死亡狀態。
model.remove()	—	nil	移除該帶模型的實體。
has_permission(node)	string	bool	僅限玩家的權限檢查。

生物實體資料表

MagmaCore 的 living entity table 繼承 Entity Table 的每一個屬性與方法。

屬性

欄位	型別	說明
health	number	即時生命值。
maximum_health	number	即時最大生命值。
name	string/nil	即時的 Bukkit 實體名稱。
is_alive	bool	Bukkit 死亡狀態的即時反向值。

方法

方法	參數	回傳	說明
damage(amount)	number	nil	造成 Bukkit 傷害。
push(x, y, z)	number, number, number	nil	立即將向量加到目前速度。
set_facing(x, y, z)	number, number, number	nil	透過改變朝向的傳送面向該方向向量。
add_potion_effect(type, duration, amplifier)	string（PotionEffectType）, int, int	nil	在型別可解析時加入藥水效果。
remove_potion_effect(type)	string（PotionEffectType）	nil	在型別可解析時移除藥水效果。
get_scale()	—	number	回傳含修飾器的有效縮放值，不可用時為 1.0。
set_scale(value)	number	nil	伺服器支援時設定縮放屬性的基礎值。
set_ai(enabled)	bool	nil	啟用或停用生物實體 AI。
set_owner(player_uuid)	string	bool	將可馴服實體馴服給線上玩家，同時清除狼的憤怒。實體不支援或玩家不可用時為 false。
has_potion_effect(type)	string	bool	查詢 Bukkit 藥水效果名稱；無法解析時為 false。

玩家資料表

MagmaCore 的 player table 繼承 Living Entity Table 的每一個屬性與方法。

FreeMinecraftModels 另提供 is_holding_elitemobs_item(filename)。請傳入含 .yml 的完整 EliteMobs 物品檔名，例如 shroomwhispers_shears.yml。它檢查主手物品的 EliteMobs 標籤，不比較顯示名稱。空手、其他物品或不可用的 EliteMobs 整合均回傳 false。

屬性

欄位	型別	說明
game_mode	string	小寫的 Bukkit 遊戲模式快照。

方法

方法	參數	回傳	說明
send_message(text)	string	nil	傳送經由 MagmaCore 顏色解析器處理過的文字。
chat(text)	string	nil	讓玩家傳送 Bukkit 聊天，包含以該玩家身分執行斜線開頭的指令。文字經顏色處理。
get_held_item()	—	table/nil	回傳主手 {type, amount, display_name} 快照，空手為 nil。type 為大寫，缺少顯示名稱時使用材質名稱。
consume_held_item(amount?=1)	int?=1	nil	排入減少執行當下主手堆疊的作業，不回傳付款結果，也不固定已檢查物品。請使用正數；負數不會被拒絕，可能增加數量。
has_item(material, amount?=1)	string（Material）, int?=1	bool	測試背包中是否含有指定數量。
get_target_entity(range?=50)	number?=50	table/nil	從眼部聯合偵測方塊與實體，忽略液體、可穿越方塊和自身，實體射線半徑為 0.5。
get_eye_location()	—	table	回傳視線位置。
get_look_direction()	—	table	回傳單位 {x, y, z} 方向。
send_block_change(x, y, z, material, ticks?=-1)	int, int, int, string（Material）, int?=-1	bool	排入僅客戶端可見的方塊與正值 tick 後的選用還原。true 表示接受排程；無效或不可放置材質為 false。
reset_block(x, y, z)	int, int, int	bool	排入為此玩家還原真實方塊的作業。
sleep(x, y, z)	number, number, number	nil	排入真實 WHITE_BED 的放置與強制睡眠嘗試。醒來或斷線時只還原原始 BlockData，不保存方塊實體內容。20 tick 後首次檢查，之後每 10 tick 檢查。
wake_up()	—	nil	排入在玩家睡眠時將其喚醒的作業。
show_boss_bar(text, color?=WHITE, progress, ticks?=-1)	string, string（BarColor）?=WHITE, number, int?=-1	nil	取代目前實心 Boss 血條，並可在正值 tick 後隱藏。進度限制於 0..1，無效顏色使用 WHITE。進度仍須是第三個參數；預設顏色請傳 nil。
hide_boss_bar()	—	nil	移除玩家目前的 Lua Boss 血條。
show_action_bar(text, ticks?=-1)	string, int?=-1	nil	傳送一次，或每 40 tick 重複一次直到正值持續時間結束。
show_title(title, subtitle?="", fade_in, stay, fade_out)	string, string?="", int, int, int	nil	顯示標題，標題與副標題文字皆經過顏色處理。

共用的血條與狀態列在宿主外掛的 MagmaCore 副本中屬於該玩家，不按腳本隔離：新的 show_boss_bar 會取代玩家目前的血條，新的 show_action_bar 會取消目前重複傳送的動作列。到期計時器只會移除啟動它的那個血條或動作列，因此舊的到期計時器不再會清除較新的項目。這些 UI 計時器與排入佇列的方塊變更都不屬於 context.scheduler。方塊變更與還原會在其工作執行時讀取玩家所在的世界；切換世界後，不要假定它們會還原預期的方塊。睡眠清理會在 20 tick 後首次檢查，之後每 10 tick 檢查一次。

世界資料表

MagmaCore 世界表以 context.world 提供，並持有建表時擷取的世界；Boss 能力繼承後套用下文覆寫。共用鄰近查詢使用軸對齊方框，radius 是半尺寸，不是球體半徑。結果陣列從 1 開始，不自動排除擁有者或遊戲模式。

屬性

欄位	型別	說明
name	string	世界名稱快照。

方法

方法	參數	回傳	說明
get_block_at(x, y, z)	int, int, int	string	回傳小寫的 Material 名稱；若區塊未載入則回傳 air 且不會載入該區塊。
set_block_at(x, y, z, material)	int, int, int, string（Material）	bool	排入放置方塊的作業；無效材質回傳 false，未載入的區塊會被排入的工作略過。
get_highest_block_y(x, z)	int, int	int	回傳最高方塊的 Y 值。
spawn_particle(particle, x, y, z, count?=1, dx?=0, dy?=0, dz?=0, speed?=0)	string（Particle）, number, number, number, int?=1, number?=0, number?=0, number?=0, number?=0	nil	生成粒子；無效名稱不會有任何作用。
play_sound(sound, x, y, z, volume?=1, pitch?=1)	string（Sound）, number, number, number, number?=1, number?=1	nil	播放已註冊的音效，或小寫的具命名空間資源包音效鍵。
strike_lightning(x, y, z)	number, number, number	nil	降下閃電。
get_time()	—	int	以 tick 回傳世界時間。
set_time(ticks)	int	nil	設定世界時間。
get_nearby_entities(x, y, z, radius)	number, number, number, number	table	回傳附近的 Entity 或 Living Entity 資料表。
get_nearby_players(x, y, z, radius)	number, number, number, number	table	回傳附近的 Player 資料表。
spawn_entity(type, x, y, z)	string（EntityType）, number, number, number	table/nil	生成原版實體；未知列舉名稱回傳 nil，合法但不可生成的型別可能引發錯誤。
raycast(from_x, from_y, from_z, dir_x, dir_y, dir_z, max_distance?=50, fluid_mode?=NEVER, blocks_only?=false, loaded_only?=false)	六個數字、number?、string?、bool?、bool?	table/nil	回傳 hit_entity、hit_location、hit_block；液體模式為 NEVER、SOURCE_ONLY、ALWAYS。loaded_only 拒絕射線外接矩形中的未載入區塊並回傳 nil。
place_temporary_block(x, y, z, material, ticks?=0, require_air?=false)	int, int, int, string（Material）, int?=0, bool?=false	bool	放置暫時方塊；無效材質或未載入的區塊回傳 false。
drop_item(x, y, z, material, amount?=1)	number, number, number, string（Material）, int?=1	table/nil	自然掉落物品並回傳其 Entity Table；無效材質回傳 nil。
spawn_firework(x, y, z, colors, type?=BALL, power?=1)	number, number, number, table, string（FireworkEffect.Type）?=BALL, int?=1	nil	排入使用 Bukkit Color 常數名稱的煙火；若沒有任何名稱可解析則預設為白色。
strike_lightning_at_location(location)	table	nil	在位置表所屬的世界中降下閃電。
play_sound_at_location(location, sound, volume?=1, pitch?=1)	table, string（Sound）, number?=1, number?=1	nil	播放已註冊的音效，或小寫的具命名空間資源包音效鍵。
spawn_particle_at_location(location, particle, count?=1, dx?=0, dy?=0, dz?=0, speed?=0)	table, string（Particle）, int?=1, number?=0, number?=0, number?=0, number?=0	nil	透過本資料表持有的世界生成粒子；請傳入同世界位置。
get_block_at_location(location)	table	string	回傳小寫材質名稱；位置無效或區塊未載入時回傳 air。
set_block_at_location(location, material)	table, string（Material）	bool	在位置表所屬的世界中排入放置方塊的作業。
place_temporary_block_at_location(location, material, ticks?=0, require_air?=false)	table, string（Material）, int?=0, bool?=false	bool	在位置表所屬的世界中放置暫時方塊。
get_highest_block_y_at_location(location)	table	int/nil	回傳最高方塊的 Y 值；位置無效時回傳 nil。
terrain_impact_at_location(location, options?)	table, table?	table/nil	顯示暫時的地形衝擊視覺效果。選項：radius=4.5 (0.5–6)、intensity=1 (0–1)、duration_ticks=35 (1–200)、view_range=48 (1–96)、seed。回傳控制代碼或 nil。
terrain_impact(x, y, z, options?)	number, number, number, table?	table/nil	在此世界的指定座標顯示相同的視覺效果。
impact.is_active()	—	bool	檢查回傳控制代碼的效果是否仍在執行；impact.id 是其字串識別碼。
impact.remove()	—	bool	移除正在執行的效果；效果已結束或移除失敗時回傳 false。
get_entity(uuid)	string	table/nil	從本世界已載入實體登錄中解析有效實體。請使用有效 UUID 字串。
block_is_passable(x, y, z)	int, int, int	bool/nil	回傳方塊可穿越性；未載入區塊或高度範圍外為 nil。
location_is_protected(location)	table	bool	查詢已註冊保護提供者；世界省略時使用本世界。
spawn_dust(location, count, red, green, blue)	table, int, int, int, int	nil	生成固定尺寸 DUST，RGB 各為 0～255，每軸擴散 0.1；略過未載入區塊。使用本世界位置。

射線未命中時回傳空表，命中欄位為 nil。方塊命中包含 hit_block = {x, y, z, material}，材質名稱為小寫。聯合射線的實體半徑為 0.5，沒有實體篩選器。loaded_only=true 檢查整個外接矩形，因此偏離實際路徑的未載入區塊也可能導致拒絕。無效液體名稱會引發錯誤。

共用粒子名稱在查找前轉成大寫。這些位置方法不接受粒子資料，因此需要資料的粒子可能引發錯誤；RGB 粉塵請使用 spawn_dust。最高方塊查詢及生成方法沒有通用的區塊載入防護。方塊放置不自動檢查區域保護。true 無法證明排程修改或 require_air 條件成功。

正值 tick 的暫時方塊會儲存原本的 BlockData，並在計時器結束、區塊或世界卸載，或外掛關閉時還原。只有當該位置仍是這個暫時方塊時才會還原，因此之後的編輯不會被覆寫。在仍為暫時方塊的位置再次放置暫時方塊，會重新開始計時，並保留第一次儲存的原始方塊。帶有方塊實體的方塊（例如箱子與告示牌）、未載入的區塊，以及已被其他暫時方塊擁有者持有的方塊，都會被略過。破壞暫時方塊不會掉落任何物品，並會結束追蹤且不還原；在該處放置方塊也會結束追蹤。非正值 tick 會永久放置方塊，且不加以追蹤。這不是腳本範圍的回復機制。

共用世界的 EliteMobs 擴充

EliteMobs 在共用世界資料表（包含 NPC 腳本）註冊這些方法，要求目的區塊已載入。共用 spawn_boss_at_location 的位置與等級必填，Boss 能力則覆寫成下文的選用參數形式。

方法	參數	回傳	說明
lightning_effect_at_location(location)	table	nil	使用 EliteMobs 閃電生成繞過機制，顯示不造成一般傷害的閃電。
spawn_npc_at_location(file, location)	string, table	table/nil	生成已設定 NPC，回傳含 remove() 的控制代碼；無法生成時為 nil。
spawn_boss_at_location(file, location, level)	string, table, int	table/nil	生成已設定自訂 Boss，回傳共用生物實體資料表；不可用時為 nil。

context.world：FreeMinecraftModels 新增功能

FreeMinecraftModels 在自己的 MagmaCore 世界表註冊這些方法，供 prop 腳本透過 context.world 使用。EliteMobs 未啟用或玩家無法解析時回傳 false。戰利品輔助方法在位置省略或無法使用時採用玩家位置。

方法

方法	參數	回傳	說明
start_elitemobs_transport(player, route_id)	player, string	bool	為同世界玩家啟動已儲存的 EliteMobs 運輸路線；玩家或整合不可用時為 false。
drop_elitemobs_procedural_loot(player, level, location?)	table/string, int, table?	bool	為該玩家掉落一件程序化產生的 EliteMobs 物品；若程序化物品掉落已停用則回傳 false。
drop_elitemobs_random_loot(player, level, location?)	table/string, int, table?	bool	以指定等級為該玩家擲骰 EliteMobs 戰利品表。
drop_elitemobs_custom_loot(player, file, level, location?)	table/string, string, int, table?	bool	為該玩家掉落特定的 EliteMobs 自訂物品檔；若該檔案無法解析則回傳 false。

player 參數接受玩家資料表、UUID 字串，或完全相符的玩家名稱。location 參數接受位置表，或帶有 current_location 的實體資料表。程序化戰利品遵守 EliteMobs 的直接入背包設定，溢出部分掉在玩家處，不一定掉在請求的位置。

em 輔助資料表

MagmaCore 在任何掛鉤執行前全域公開此表。建構器只建立資料，不註冊監看、不載入世界、不驗證完整形狀。全域函式使用點號；回傳的位置與區域方法也接受冒號，修改並回傳同一張表。區域設定器保留傳入位置表的參考。

屬性

輔助建構器會回傳下列精簡資料表。

欄位	型別	說明
location.x	number	em.create_location 回傳的 X 座標。
location.y	number	em.create_location 回傳的 Y 座標。
location.z	number	em.create_location 回傳的 Z 座標。
location.world	string/nil	提供給 em.create_location 時的世界名稱。
location.yaw	number/nil	提供給 em.create_location 時的 yaw。
location.pitch	number/nil	提供給 em.create_location 時的 pitch。
vector.x	number	em.create_vector 回傳的 X 分量。
vector.y	number	em.create_vector 回傳的 Y 分量。
vector.z	number	em.create_vector 回傳的 Z 分量。
zone.kind	string	sphere、dome、cylinder、cuboid、cone、static_ray、rotating_ray 或 translating_ray。
zone.radius	number/nil	球體、半球、圓柱或圓錐的半徑。
zone.height	number/nil	圓柱高度。
zone.x	number/nil	長方體的 X 尺寸。
zone.y	number/nil	長方體的 Y 尺寸。
zone.z	number/nil	長方體的 Z 尺寸。
zone.length	number/nil	圓錐或射線的長度。
zone.thickness	number/nil	靜態射線的粗細。
zone.point_radius	number/nil	旋轉或平移射線的點半徑。
zone.animation_duration	number/nil	旋轉或平移射線的動畫持續時間。
zone.origin	table/nil	由 set_center 或 set_origin 設定的位置。
zone.destination	table/nil	由 set_destination 設定的位置。

方法

方法	參數	回傳	說明
em.create_location(x, y, z, world?, yaw?, pitch?)	number, number, number, string?, number?, number?	table	回傳一個位置表。
em.create_vector(x, y, z)	number, number, number	table	回傳一個 {x, y, z} 向量表。
location.add(dx?=0, dy?=0, dz?=0)	number?=0, number?=0, number?=0	table	就地相加並回傳同一個位置表。
em.zone.create_sphere_zone(radius)	number	table	回傳帶有 set_center(location) 的球體定義。
em.zone.create_dome_zone(radius)	number	table	回傳帶有 set_center(location) 的半球定義。
em.zone.create_cylinder_zone(radius, height)	number, number	table	回傳帶有 set_center(location) 的圓柱定義。
em.zone.create_cuboid_zone(x, y, z)	number, number, number	table	回傳帶有 set_center(location) 的長方體定義。
em.zone.create_cone_zone(length, radius)	number, number	table	回傳帶有 set_origin(location) 與 set_destination(location) 的圓錐定義。
em.zone.create_static_ray_zone(length, thickness)	number, number	table	回傳帶有起點與終點設定器的靜態射線定義。
em.zone.create_rotating_ray_zone(length, point_radius, animation_duration)	number, number, number	table	回傳帶有起點與終點設定器的旋轉射線定義。
em.zone.create_translating_ray_zone(length, point_radius, animation_duration)	number, number, number	table	回傳帶有起點與終點設定器的平移射線定義。
zone.set_center(location)	table	table	將中心設為 zone.origin 並回傳同一個 zone 表。
zone.set_origin(location)	table	table	設定起點並回傳同一個 zone 表。
zone.set_destination(location)	table	table	設定終點並回傳同一個 zone 表。
em.location.is_in_dungeon(location)	table	bool	測試已註冊的地下城區域，以及回報 dungeon 類型的擁有者。
em.location.is_protected(location)	table	bool	測試內建的 WorldGuard/GriefPrevention 轉接器，以及外掛程式註冊的保護擁有者。
em.location.owned_by(location, namespace)	table, string	bool	測試某個外掛程式命名空間的擁有權。
em.location.owners(location)	table	table	回傳擁有者命名空間字串的陣列。
em.location.kinds_at(location)	table	table	回傳擁有權類型字串的陣列。
em.location.has_kind(location, kind)	table, string	bool	測試某個擁有權類型。

em.location.* 要求已載入世界名稱或 {name = ...}，不退回擁有者世界。無法解析世界時回傳 false 或空陣列，省略座標為零。擁有者命名空間區分大小寫，類型不區分。擁有權本身不代表地下城或保護。查詢涵蓋已註冊提供者，不會自動涵蓋每個外掛；被查詢的區域轉接器失敗時視為受保護。陣列順序不保證。

Mind 程式上下文

原生 Mind 回呼使用此上下文，而非一般能力或 NPC 上下文。檔案形式的行為程式也從 plugins/EliteMobs/behaviors/ 載入；參閱 Boss 行為設定。EliteMobs 整合透過 EliteMindService 註冊 ai.program 和 ai.module；放入一般 powers 目錄不會註冊 Mind 程式。

欄位	型別	說明
tick, generation	number	目前的遊戲 tick 與執行階段世代。
entity	table	行為主體的共用 Living Entity Table。
memory, perception, actuator, actions	table	下列服務，僅供目前回呼使用。

方法	參數	回傳值	說明
memory.get(key)	string	value/nil	讀取已宣告的記憶鍵。
memory.set(key, value, ttl_ticks?)	string, value, int?	nil	依設定型別設定已宣告的記憶值，可選擇到期時間。
memory.forget(key)	string	nil	移除已宣告的記憶值。
memory.contains(key)	string	bool	檢查已宣告的記憶值是否存在。
perception.current_target()	—	table/nil	以共用 Living Entity Table 回傳目前目標。
perception.nearest_player(radius)	number	table/nil	回傳範圍內最近的玩家。
perception.can_see(entity_or_uuid)	table/string	bool	檢查通往生物實體的視線是否暢通。
perception.navigation()	—	table	回傳 destination_active、navigation_in_progress、consecutive_stuck_ticks、可選的 destination，以及包含 tick 和 position 的可選 last_progress。
actuator.move_to(location, speed?=1)	table, number?=1	bool	以有限的正數速度請求導航至同一世界中的位置；未開始尋路時回傳 false。
actuator.stop_moving()	—	nil	停止導航。
actuator.look_at(location)	table	nil	朝向指定位置。
actuator.jump()	—	nil	請求跳躍。
actuator.set_target(entity_or_uuid)	table/string	bool	設定生物目標；無法解析目標時回傳 false。
actuator.clear_target()	—	nil	清除目標。
actuator.attack(entity_or_uuid)	table/string	bool	請求攻擊；無法解析目標時回傳 false。
actuator.stop_all()	—	nil	停止此行為所持有之控制權涵蓋的移動、目標與攻擊。
actions.request(identifier, payload?)	string, table?	string	請求語意動作並回傳小寫結果；承載資料支援純量、實體 UUID 資料表及 world/x/y/z 位置資料表。

每個回呼會在首次存取時建立服務區段，並在該回呼內重複使用。記憶鍵必須事先宣告，未宣告的鍵會引發錯誤。actuator.set_target 或 actuator.attack 回傳成功，表示已解析出存活目標並轉送請求，不代表導航或攻擊已完成。動作承載資料接受所支援的純量或實體／位置值，不接受任意巢狀 Lua 表。動作識別碼必須是不超過 128 個字元的小寫命名空間鍵；承載資料最多 16 個項目，鍵為不超過 64 個字元的小寫字串，字串值的上限為 256 個字元。除 stop_all 外的每個致動器方法以及 actions.request，在呼叫的行為未持有對應控制權時都會引發錯誤。感測器完全不能使用致動器或動作。以 Lua 撰寫的行為程式說明請見行為程式。

ai 全域變數

MagmaCore 會在每個 Lua 環境中安裝這個全域變數。建構函式只會為收到的表加上標記；EliteMobs 會從行為程式檔案編譯這些已標記的表。

欄位	型別	說明
ai.controls.move, look, jump, target, attack, use_item, action	string	用於行為 controls 陣列的控制權名稱；use_item 沒有對應的 Lua 致動器方法。

方法	參數	回傳值	說明
ai.program(definition)	table	table	為程式定義加上標記，包含 id、revision，以及選填的 modules、memories、sensors、behaviors、budget 與 runaway。
ai.module(definition)	table	table	為模組定義加上標記，包含 id、revision，以及選填的 dependencies、memories、sensors 與 behaviors。
ai.sensor(definition)	table	table	為感測器加上標記，包含 id、interval?=1 與 sense(c)。
ai.behavior(definition)	table	table	為行為加上標記，包含 id、priority?=0、controls、can_start、can_continue、start、tick 與 stop(c, reason)。

context.mind_action：EliteMobs 能力掛鉤

可在 on_mind_action(context) 中使用。掛鉤回傳 "accepted"、"deferred" 或 "rejected"；系統依附加順序呼叫能力，直到某個能力接受動作。

欄位	型別	說明
key	string	含命名空間的語意動作識別碼。
payload	table	不可變 Java 請求的可變 Lua 副本；實體 UUID 為字串，位置為資料表。編輯副本不改變原請求。
game_tick, generation	number	動作 tick 與執行階段世代。

context.state

每個 MagmaCore 腳本實例都會取得一個純 Lua 資料表，其生命週期與該實例相同。可用於計數器、旗標、工作 ID，以及在各掛鉤之間共用的值。

context.state.counter = (context.state.counter or 0) + 1

context.log

MagmaCore、FreeMinecraftModels 與 EliteMobs NPC 方法

方法	參數	回傳	說明
info(message)	string	nil	以共用的 Lua 前綴記錄一則資訊訊息。
warn(message)	string	nil	記錄一則警告。
error(message)	string	nil	透過共用的警告頻道記錄。

EliteMobs Boss 能力方法

方法	參數	回傳	說明
info(message)	string	nil	記錄一則 Boss 能力的資訊訊息。
warn(message)	string	nil	記錄一則警告。
debug(message)	string	nil	以 Lua 能力除錯前綴記錄一則資訊訊息。

context.scheduler

排程工作屬於該腳本實例，並會在其關閉時被取消。下列兩套命名家族在共用的 MagmaCore 介面與 EliteMobs Boss 能力上都可使用。

方法	參數	回傳	說明
run_later(ticks, callback)	int, function	int	延遲後執行一次並回傳 Bukkit 工作 ID。
run_repeating(delay, interval, callback)	int, int, function	int	在初始延遲後重複執行並回傳工作 ID。
cancel(task_id)	int	nil	取消自己擁有的工作。
run_after(ticks, callback)	int, function	int	run_later 的別名。
run_every(interval, callback)	int, function	int	不含初始延遲地重複執行並回傳工作 ID。
cancel_task(task_id)	int	nil	cancel 的別名。

回呼取得新的上下文，通常沒有事件或玩家。應擷取需要的值或 UUID，不要保留具有延遲解析欄位的舊上下文。到期的一次性工作在暫停時等待；重複工作跳過暫停 tick，不會補跑。回呼錯誤會關閉腳本。取消自有工作不會撤銷任意世界/實體修改或獨立 UI 計時器。

context.cooldowns

區域儲存屬於 ScriptableEntity 轉接器。FreeMinecraftModels 為每個 prop 腳本各建一個，EliteMobs NPC 則由所有腳本共用一個，因此具名區域鍵可能在同一 NPC 間衝突。全域值由同一 prop 或 NPC 共用。省略區域鍵時使用 __lua: 加檔名；具名鍵精確比對。Boss 能力共用 Boss 的區域儲存及內建全域能力冷卻。

共用區域/全域冷卻與 Boss 區域冷卻測量真實經過時間，每個要求 tick 為 50ms，即使暫停或 TPS 低仍繼續。Boss 全域冷卻以伺服器 tick 計算，並保留較晚的到期時間：較短的 set_global 永遠不會縮短仍有效的全域冷卻，而非正數的持續時間不會有任何作用。檢查或設定區域冷卻，不會自動檢查或設定全域冷卻。

方法	參數	回傳	說明
local_ready(key?)	string?	bool	測試指定索引鍵的區域冷卻是否已就緒。
local_remaining(key?)	string?	int	回傳剩餘 tick 數；已就緒時回傳 0。
check_local(key, duration)	string/nil, int	bool	若已就緒則啟動冷卻並回傳 true。傳入 nil 可使用預設索引鍵。
set_local(duration, key?)	int, string?	nil	設定或清除區域冷卻；非正值的持續時間會清除它。
global_ready()	—	bool	測試該擁有者的全域冷卻是否已就緒。
set_global(duration)	int	nil	以 tick 設定全域冷卻。在共用的 MagmaCore 介面上，非正值的持續時間會清除它。

context.zones：共用的 MagmaCore 介面

FreeMinecraftModels 腳本、EliteMobs NPC 腳本，以及其他預設的 MagmaCore 使用者，會在目前腳本擁有者所在的世界中取得整數型的 zone 控制代碼。

方法	參數	回傳	說明
create_sphere(x, y, z, radius)	number, number, number, number	int/nil	註冊一個球體並回傳其控制代碼；若擁有者沒有世界則回傳 nil。
create_cylinder(x, y, z, radius, height)	number, number, number, number, number	int/nil	註冊一個圓柱並回傳其控制代碼；若擁有者沒有世界則回傳 nil。
create_cuboid(x, y, z, x_size, y_size, z_size)	number, number, number, number, number, number	int/nil	註冊一個長方體並回傳其控制代碼；若擁有者沒有世界則回傳 nil。
watch(handle, on_enter?, on_leave?)	int, function?, function?	bool/nil	為已知的控制代碼啟用邊界追蹤。函式存在與否會決定是否啟用對應的 on_zone_enter 或 on_zone_leave 掛鉤；所提供的函式主體不會被直接呼叫。
unwatch(handle)	int	nil	停止追蹤並移除該控制代碼。

通用監看測試玩家位置點。此路徑的長方體尺寸是半尺寸，Z 為零時採用非零 X，不保證與 EliteMobs 實體重疊或取樣位置查詢體積一致。區域保留建立座標及世界，但每 tick 掃描擁有者目前世界中的玩家。掛鉤透過 context.player 與 context.event.player 公開穿越邊界的玩家。

建立即開始成員追蹤，早於 watch 安裝掛鉤分派器。稍後安裝監看不會對已追蹤在內部的玩家補發進入通知。第二次 watch 省略回呼不會清除舊分派器。斷線與 unwatch 不保證離開掛鉤。區域檢查早於 on_game_tick。

context.event：共用的 MagmaCore 介面

只要共用掛鉤有目前的 Bukkit 事件或行為者，此資料表就會存在。它不會出現在排程回呼中，也不會出現在兩者皆無的掛鉤中。

欄位或方法	型別	說明
is_cancelled	bool	首次解析事件子表時擷取的取消狀態；cancel() 或 uncancel() 不會更新它。
cancel()	method	取消目前的事件。僅在該事件實作 Bukkit Cancellable 時存在。
uncancel()	method	取消目前事件的取消狀態。僅在該事件實作 Bukkit Cancellable 時存在。
player	table	目前行為者的 Living Entity Table（若有）。

通用的 zone 掛鉤提供行為者但沒有可取消的 Bukkit 事件，因此它們會公開 is_cancelled = false 與 player，但不含 cancel() 或 uncancel()。

context.item

附魔動作腳本在擷取來源具有欄位位置與物品時公開此表。它只針對該欄位，比對目前物品材質與中繼資料和原快照，忽略損傷及數量。它不搜尋背包，也不追蹤唯一物品身分；同欄位的等價替代品也會符合。已消耗彈藥可能為 nil。這與已停用的 FreeMinecraftModels 裝備物品執行階段無關。

方法	參數	回傳	說明
get_durability()	—	table/nil	剩餘耐久 {current, max}；不可用或無耐久物品為 nil。
get_durability_percentage()	—	number/nil	剩餘耐久除以材質最大值，通常為 0..1；外部超額損傷資料可能使其超出範圍。
use_durability(amount, can_break?=false)	int, bool?	bool	修改損傷，負數為修復。預設保留至少一點耐久；can_break=true 可消耗整疊。
use_durability_percentage(fraction, can_break?=false)	number, bool?	bool	按相同損壞規則套用 ceil(max_durability * fraction) 損傷。
consume(amount)	positive int	bool	數量足夠時才從擷取堆疊消耗。

耐久使用材質最大值，不是自訂最大損傷元件。這些直接修改不套用原版耗損、Unbreaking、不可破壞檢查或玩家物品損傷事件。比例必須有限且結果在整數範圍內；負比例會修復。損壞會消耗整個擷取堆疊。生命週期與完整上下文請參閱自訂附魔。

context.prop

FreeMinecraftModels prop 腳本會取得此資料表；當存在支援它的實體時，它會繼承 MagmaCore Entity Table。

屬性

欄位	型別	說明
model_id	string/nil	模型藍圖名稱；沒有藍圖時回傳 nil。
current_location	table/nil	即時的 prop 位置。

方法

方法	參數	回傳	說明
play_animation(name, blend?=true, loop?=true)	string, bool?=true, bool?=true	bool	播放指定名稱的動畫。
stop_animation()	—	nil	清除待播佇列並在可用時回到 idle；保留終止死亡狀態。
hurt_visual()	—	nil	播放紅色染色的受傷視覺效果，但不造成傷害。
pickup()	—	nil	排入永久移除並掉落放置用物品的作業。
has_mount_points()	—	bool	測試該 prop 是否具有騎乘點骨骼。
mount(player)	table	bool	排入讓已解析的玩家騎乘到第一個可用座位的作業。
dismount(player)	table	bool	排入讓已解析的玩家從此 prop 上下來的作業。
get_passengers()	—	table	回傳已騎乘玩家的 Entity Table。
spawn_elitemobs_boss(file, x, y, z)	string, number, number, number	table/nil	在 EliteMobs 啟用時生成一個 EliteMobs 自訂 Boss。
open_inventory(player, title, rows?=3)	table, string, int?=3	bool	排入開啟持久化儲存空間的作業，列數會被夾在 1 到 6 之間。
place_book(player)	table	bool	當 prop 尚未存放書本時，排入存放一本手持之成書或書與筆的作業。
read_book(player)	table	bool	排入開啟已存放成書的作業。
take_book(player)	table	bool	排入將已存放的書本歸還給玩家的作業。
has_book()	—	bool	測試該 prop 是否存放著書本。
drop_inventory()	—	bool	排入清空持久化儲存空間並掉落其中物品的作業。
drop_book()	—	bool	排入清除並掉落已存放書本的作業。
is_viewing_inventory(player)	table	bool	測試該玩家是否正在檢視此 prop 所追蹤的容器。
set_persistent_data(key, value)	string, string	bool	在 prop 範圍的 fmm_lua_ 索引鍵下儲存一個字串。
get_persistent_data(key)	string	string/nil	回傳已儲存的字串，或 nil。

對排程 prop 操作，true 只表示最初的玩家/承載實體檢查通過，不保證有座位、存書成功或介面開啟。take_book 先刪除儲存再放入背包，不會掉落溢出物品。同一 prop 的所有檢視者共用一個即時容器，並在最後一位檢視者關閉時儲存；容器開啟期間，之後的呼叫會沿用其標題與大小。已儲存的內容若多於要求的列數，會以其儲存時的大小開啟，因此不會遺失任何欄位。prop 資料存於承載盔甲座；回收後新生成的放置物品不保證保留這些資料。

在 on_projectile_hit 中，prop 腳本還會收到 context.projectile，這是代表該投射物的共用實體資料表。若其他外掛已取消這次命中，此鉤子不會觸發。context.event 包裝可取消的 FreeMinecraftModels 命中事件；射擊者為存活實體（包括生物）時，context.event.player 就是射擊者，而 context.player 只有在玩家發射投射物時才會設定。

context.npc

EliteMobs NPC 腳本會繼承共用的 MagmaCore 情境，並加入這個 NPC 專屬的資料表。

屬性

欄位	型別	說明
name	string	已設定的 NPC 顯示名稱。
filename	string	NPC 設定檔的檔名。
uuid	string	執行時期的 NPC UUID。
activation_radius	number	已設定的啟用半徑。
current_location	table	位置快照，只有在支援它的生物實體存在時才有。
entity_type	string	大寫的 Bukkit 實體型別，只有在支援它的生物實體存在時才有。

方法

方法	參數	回傳	說明
is_valid()	—	bool	測試該 NPC 是否有效。
remove()	—	nil	透過管理 NPC 的生命週期移除它。
get_location()	—	table	回傳目前的 NPC 位置，若無則退回其生成位置。該資料表也包含一個 direction 向量。
get_eye_location()	—	table	回傳目前的視線位置，若無則退回生成位置。該資料表也包含一個 direction 向量。
get_activation_radius()	—	number	回傳目前設定的啟用半徑。
get_nearby_players(radius)	number	table	回傳同世界中距 NPC 腳部三維半徑內的玩家，不篩選遊戲模式。
face_direction_or_location(target)	table	nil	面向向量或同世界位置；巡邏移動進行中會忽略。
say_greeting(player?)	table/string?	nil	傳送已設定的問候語；若有觸發玩家則預設為該玩家。可接受玩家資料表、UUID 或名稱。
say_dialog(player?)	table/string?	nil	以相同的玩家解析方式傳送已設定的對話。
say_farewell(player?)	table/string?	nil	以相同的玩家解析方式傳送已設定的道別語。
play_model_animation(name)	string	nil	當存在自訂模型時播放模型動畫。
patrol_pause()	—	bool	暫停已設定的巡邏。
patrol_resume()	—	bool	在腳本等待或暫時移動後恢復巡邏。
walk_to(x, y, z)	number, number, number	bool	走到相對於原點的偏移並恢復巡邏。
hold(x, y, z)	number, number, number	bool	走到偏移位置並停留。
teleport(x, y, z)	number, number, number	bool	傳送到進行實體 tick 的偏移位置。

EliteMobs 能力位置資料表

EliteMobs Boss 能力資料表會從 get_location()、get_eye_location()、current_location 及其他位置結果回傳這種位置格式。沒有位置時回傳空表。

屬性

欄位	型別	說明
x, y, z	number	座標。
yaw, pitch	number	旋轉。
world	string/nil	位置有世界時的世界名稱。
direction	table	單位長度的 {x, y, z} 朝向向量。

方法

方法	參數	回傳	說明
add(dx?=0, dy?=0, dz?=0)	number?=0, number?=0, number?=0	table	直接加到座標上並回傳同一個表；direction 不會更新。

EliteMobs 能力實體參考資料表

EliteMobs Boss 能力方法會為投射物、煙火與掉落方塊等非生物實體回傳這個輕量資料表。

屬性

欄位	型別	說明
name	string	實體名稱快照。
uuid	string	實體 UUID。
entity_type	string	大寫的 Bukkit 實體型別快照。
is_player	bool	永遠為 false。
is_elite	bool	永遠為 false。
is_mount	bool	除非某個 Boss 將回傳的坐騎資料表標記為 true，否則為 false。
current_location	table	位置快照。

方法

方法	參數	回傳	說明
is_valid()	—	bool	測試即時有效性。
get_location()	—	table	回傳即時位置。
get_velocity()	—	table	回傳即時速度。
is_on_ground()	—	bool	測試即時的著地狀態。
teleport_to_location(location)	table	nil	位置可解析時進行傳送。
set_velocity_vector(vector)	table	nil	向量可解析時設定速度。
set_direction_vector(vector)	table	nil	適用時設定火球方向。
set_yield(amount)	number	nil	適用時設定火球威力。
set_gravity(enabled)	bool	nil	設定重力。
detonate()	—	nil	當該實體為煙火時引爆。
remove()	—	nil	移除該實體。
unregister(reason?=OTHER)	string?=OTHER	nil	以 DEATH、PHASE_BOSS_RESET、PHASE_BOSS_PHASE_END、CHUNK_UNLOAD、WORLD_UNLOAD、SHUTDOWN、EFFECT_TIMEOUT、BOSS_TIMEOUT、NPC_TIMEOUT、OTHER、UNSPECIFIED_WATCHDOG_REMOVAL、REMOVE_COMMAND、KILL_COMMAND、REINFORCEMENT_CULL、ENTITY_REPLACEMENT 或 ARENA_RESET 取消註冊。
is_inside_vehicle()	—	bool	測試該實體是否正在乘坐載具。
has_vehicle()	—	bool	測試是否存在載具。
get_vehicle()	—	table/nil	回傳目前的載具參考。
set_vehicle(vehicle)	table	bool	讓此實體乘坐已解析的載具。
leave_vehicle()	—	bool	離開目前的載具。
has_passengers()	—	bool	測試是否存在乘客。
get_passenger_count()	—	int	回傳乘客數量。
get_passengers()	—	table	回傳乘客參考。
add_passenger(passenger)	table	bool	加入已解析的乘客。
remove_passenger(passenger)	table	bool	移除已解析的乘客。
eject_passengers()	—	bool	彈出所有乘客。

EliteMobs 能力生物實體資料表

EliteMobs Boss 能力的生物值使用這個獨立的資料表；Boss 資料表與 EliteMobs 能力玩家資料表都繼承自它。

屬性

欄位	型別	說明
name	string	實體名稱快照。
uuid	string	實體 UUID。
entity_type	string	大寫的 Bukkit 實體型別快照。
is_player	bool	該實體是否為玩家。
is_monster	bool	該實體是否實作 Bukkit Monster。
is_elite	bool	EliteMobs 是否追蹤該實體。
is_mount	bool	被追蹤的自訂 Boss 是否為坐騎。
is_valid	bool	有效性快照。
health	number	生命值快照。
maximum_health	number	最大生命值快照。
current_location	table	位置快照。

方法

方法	參數	回傳	說明
is_alive()	—	bool	測試即時有效性與死亡狀態。
is_ai_enabled()	—	bool	回傳即時的 AI 狀態。
is_frozen()	—	bool	回傳 EliteMobs 自訂 Boss 的凍結設定，否則為 false。
get_location()	—	table	回傳即時位置。
get_eye_location()	—	table	回傳即時視線位置。
get_height()	—	number	回傳 Bukkit 實體高度。
get_health()	—	number	回傳即時生命值。
get_maximum_health()	—	number	回傳即時最大生命值。
get_velocity()	—	table	回傳即時速度。
deal_damage(amount)	number	nil	造成一般的 Bukkit 傷害。
deal_custom_damage(amount)	number	nil	由 Boss 向存活目標提交原始自訂傷害；會略過 Boss 本身、無敵或已死亡的目標，以及不在生存/冒險模式的玩家。仍受實例規則與傷害事件取消影響。
deal_damage_from_boss(amount)	number	nil	造成歸屬於該能力所屬 Boss 的 Bukkit 傷害。
restore_health(amount)	number	nil	被追蹤時透過 EliteMobs 治療，否則將 Bukkit 生命值夾至最大值。
play_sound_at_entity(sound, volume_or_options?=1, pitch?=1)	string（Sound）, number/table?=1, number?=1	nil	在該實體處播放已註冊或自訂的具命名空間音效。第二個參數也可改為 {volume, pitch}。
play_sound_at_self(sound, volume_or_options?=1, pitch?=1)	string（Sound）, number/table?=1, number?=1	nil	在該實體處播放的別名。第二個參數也可改為 {volume, pitch}。
spawn_particle_at_self(particle, count?=1)	string（Particle）/table, int?=1	nil	在該實體處生成粒子字串或粒子規格表。
spawn_particles_at_location(location, particle, count?=1, dx?=0, dy?=0, dz?=0, speed?=0)	table, string（Particle）, int?=1, number?=0, number?=0, number?=0, number?=0	nil	在某個位置生成粒子。
teleport_to_location(location)	table	nil	位置可解析時進行傳送。
set_velocity_vector(vector)	table	nil	向量可解析時設定速度。
set_gravity(enabled)	bool	nil	設定重力。
is_on_ground()	—	bool	測試即時的著地狀態。
apply_push_vector(vector, additive?=false, delay?=1)	table, bool?=false, int?=1	nil	延遲後套用速度，並可選擇疊加到目前速度上。
set_custom_name(name)	string	nil	設定經顏色處理的自訂名稱。
reset_custom_name()	—	nil	被追蹤時還原 EliteMobs 名稱，否則還原 Bukkit 名稱。
set_custom_name_visible(visible)	bool	nil	設定自訂名稱的可見性。
set_ai_enabled(enabled, duration?=0)	bool, int?=0	nil	以歸屬於能力的修改設定 AI；正值 tick 後會還原被取代的值。true 會結束此能力仍有效的 AI 修改（若有），而不是套用新值。
set_awareness_enabled(enabled, duration?=0)	bool, int?=0	nil	以歸屬於能力的修改設定生物的感知能力；正值 tick 後會還原被取代的值。true 會結束此能力仍有效的感知修改（若有），而不是套用新值。
face_direction_or_location(target)	table	nil	面向一個向量或同世界的位置。
play_model_animation(name)	string	nil	可用時播放自訂模型動畫。
set_scale(scale, duration?=0)	number, int?=0	nil	以歸屬於能力的修改設定基礎縮放；正值 tick 後會還原被取代的值。
set_invulnerable(enabled, duration?=0)	bool, int?=0	nil	以歸屬於能力的修改設定無敵；正值 tick 後會還原被取代的值。
remove_elite()	—	nil	透過 EliteMobs 的移除流程移除被追蹤的 elite。
is_healing()	—	bool	測試被追蹤 elite 的治療狀態。
set_healing(enabled)	bool	nil	true 會在被追蹤的 elite 尚未處於治療狀態時將其標記為治療中；false 只清除此能力所設定的治療狀態。能力關閉時會清除它仍持有的治療狀態。
navigate_to_location(location, speed?=1, force?=false, timeout?=0)	table, number?=1, bool?=false, int?=0	nil	讓被追蹤的自訂 Boss 進行導航。
add_tag(tag, duration?=0)	string, int?=0	nil	加入一個標籤，並在正值 tick 後移除它。
remove_tag(tag)	string	nil	移除一個標籤。
has_tag(tag)	string	bool	測試實體、elite 或玩家標籤。
push_relative_to(location, force?=1, extra_x?=0, extra_y?=0, extra_z?=0)	table, number?=1, number?=0, number?=0, number?=0	nil	立即以遠離來源的單位向量乘力度，再加世界軸偏移，取代速度。來源必須在同世界。
overlaps_box_at_location(center, half_x?=0.5, half_y?=half_x, half_z?=half_x)	table, number?=0.5, number?, number?	bool	測試實體的邊界框是否與指定的方框重疊。
is_inside_vehicle()	—	bool	測試該實體是否正在乘坐載具。
has_vehicle()	—	bool	測試是否存在載具。
get_vehicle()	—	table/nil	回傳目前的載具參考。
set_vehicle(vehicle)	table	bool	讓此實體乘坐已解析的載具。
leave_vehicle()	—	bool	離開目前的載具。
has_passengers()	—	bool	測試是否存在乘客。
get_passenger_count()	—	int	回傳乘客數量。
get_passengers()	—	table	回傳乘客參考。
add_passenger(passenger)	table	bool	加入已解析的乘客。
remove_passenger(passenger)	table	bool	移除已解析的乘客。
eject_passengers()	—	bool	彈出所有乘客。
apply_potion_effect(type, duration, amplifier?=0)	string（PotionEffectType）, int, int?=0	nil	解析轉成大寫的 Bukkit 藥水名稱，實例規則允許時套用。增幅值從零開始。
set_equipment(slot, material, options?)	string（EquipmentSlot）, string（Material）, table?	nil	設定裝備；options 支援 unbreakable 以及帶有 type 與 level 的 enchantments 項目。
damage_equipment(slot, amount)	string, int	int	請求對 HAND、OFF_HAND、HEAD、CHEST、LEGS 或 FEET 的裝備造成1–64點耐久損耗，回傳實際損耗。遵守玩家物品損傷事件的取消結果及不可破壞設定；可能使物品損壞。
set_fire_ticks(ticks)	int	nil	實例規則允許時設定燃燒 tick。
add_visual_freeze_ticks(ticks?=1)	int?=1	nil	規則允許時增加 Minecraft 冰凍 tick；可能造成冰凍傷害，不會鎖定 AI 或移動。
place_temporary_block(material, ticks?=0, require_air?=false)	string（Material）, int?=0, bool?=false	nil	在該實體處放置一個暫時方塊。

AI、感知、縮放與無敵的變更歸屬於呼叫的能力。每項變更都會記錄被它取代的值。正值持續時間會在指定 tick 數後還原該值；持續時間為 0 時，變更會保留到能力關閉，關閉時同樣會還原。多個能力變更同一屬性時，結束其中一項變更會還原剩餘變更中最新的一項，若已無剩餘變更則還原原始值。若期間有其他外掛或指令變更了該屬性，則保留其值，不還原任何東西。暫停能力不會結束這些變更。延遲的 apply_push_vector 與標籤移除計時器仍獨立於腳本排程器執行。reset_custom_name 對受追蹤精英還原其名稱；一般 Bukkit 實體使用目前名稱，而非儲存的原名。

EliteMobs 能力玩家資料表

EliteMobs Boss 能力的玩家值繼承 EliteMobs 能力生物實體的每一個屬性與方法。

屬性

欄位	型別	說明
game_mode	string	大寫的 Bukkit 遊戲模式快照。

方法

方法	參數	回傳	說明
send_message(text)	string	nil	傳送經顏色處理的聊天文字。
show_action_bar(text)	string	nil	傳送經顏色處理的動作列訊息。
show_title(title, subtitle?="", fade_in?=10, stay?=40, fade_out?=10)	string, string?="", int?=10, int?=40, int?=10	nil	顯示經顏色處理的標題。
show_boss_bar(title, color?=WHITE, style?=SOLID, duration?=40)	string, string（BarColor）?=WHITE, string（BarStyle）?=SOLID, int?=40	nil	顯示 Boss 血條，並在正值 tick 後移除。
run_command(command)	string	nil	以該玩家的身分執行指令。

context.boss

EliteMobs Boss 能力會取得此資料表；它繼承 EliteMobs 能力生物實體的每一個屬性與方法，並以 elite 層級的語意覆寫此處列出的項目。

屬性

欄位	型別	說明
name	string	Elite 顯示名稱或腳本檔名的快照。
uuid	string	Elite UUID。
health	number	Elite 生命值快照。
maximum_health	number	Elite 最大生命值快照。
current_location	table	Elite 位置快照。
level	int	Elite 等級快照。
damager_count	int	傷害者數量快照。
is_in_combat	bool	戰鬥狀態快照。
exists	bool	Elite 是否存在的快照。

方法

方法	參數	回傳	說明
is_alive()	—	bool	測試生物實體與 EliteMobs 的存在狀態。
get_health()	—	number	回傳即時的 elite 生命值。
get_maximum_health()	—	number	回傳即時的 elite 最大生命值。
get_location()	—	table	回傳即時的 elite 位置。
restore_health(amount)	number	nil	透過 EliteMobs 實體進行治療。
add_tag(tag, duration?=0)	string, int?=0	nil	加入一個 elite 標籤，並在正值 tick 後移除。
remove_tag(tag)	string	nil	移除一個 elite 標籤。
has_tag(tag)	string	bool	測試某個 elite 標籤。
reset_custom_name()	—	nil	還原 elite 的顯示名稱。
play_sound_at_self(sound, volume_or_options?=1, pitch?=1)	string（Sound）, number/table?=1, number?=1	nil	在 elite 位置播放已註冊或自訂的具命名空間音效。第二個參數也可改為 {volume, pitch}。
play_sound_at_entity(sound, volume_or_options?=1, pitch?=1)	string（Sound）, number/table?=1, number?=1	nil	在 elite 位置播放的別名。第二個參數也可改為 {volume, pitch}。
spawn_particle_at_self(particle, count?=1)	string（Particle）/table, int?=1	nil	在 elite 位置生成粒子。
play_model_animation(name)	string	nil	可用時播放自訂 Boss 的模型動畫。
navigate_to_location(location, speed?=1, force?=false, timeout?=0)	table, number?=1, bool?=false, int?=0	nil	讓自訂 Boss 進行導航。
get_damager_count()	—	int	回傳即時的傷害者數量。
despawn()	—	nil	以原因 OTHER 移除該 elite。
remove()	—	nil	despawn() 的別名。
patrol_pause()	—	bool	暫停已設定的巡邏。
patrol_resume()	—	bool	在腳本等待或暫時移動後恢復巡邏。
walk_to(x, y, z)	number, number, number	bool	走到相對於原點的偏移並恢復巡邏。
hold(x, y, z)	number, number, number	bool	走到偏移位置並停留。
teleport(x, y, z)	number, number, number	bool	傳送到進行實體 tick 的偏移位置。
get_ender_dragon_phase()	—	string/nil	回傳 EnderDragon.Phase 名稱，或 nil。
set_ender_dragon_phase(phase)	string（EnderDragon.Phase）	nil	設定一個有效的終界龍階段。
has_mount()	—	bool	測試該 Boss 是否有存活的坐騎載具。
get_mount()	—	table/nil	回傳標記為 is_mount = true 的坐騎參考。
set_mount(mount)	table	bool	讓該 Boss 乘坐已解析的實體。
clear_mount()	—	bool	離開目前的載具。
dismount()	—	bool	clear_mount() 的別名。
start_tracking_fireball_system(speed?=0.5)	number?=0.5	nil	對怪物型 Boss，在其有目標期間，於下一個 tick 及之後每 160 tick 向每個軸向 20 格內的生存/冒險玩家發射追蹤火球。此工作歸屬於該能力：暫停能力會暫停它，失去目標或能力關閉會停止它。速度必須是有限正數。
handle_spirit_walk_damage(cause)	string（DamageCause）	nil	執行 Spirit Walk 的傷害處理。
shield_wall_is_active()	—	bool	測試護盾牆狀態。
initialize_shield_wall(openingDirection?=1)	int?=1	nil	將各方向護盾耐久初始化為 Boss 等級。開口：1 北、2 東、3 南、4 西；其他整數保護四面。已啟動的護盾牆不變。
shield_wall_absorb_damage(player, damage)	table, number	bool	攻擊者所在方向的耐久原本為正時扣除傷害；傳回 true 表示腳本應自行取消傷害事件，不會自動取消。
deactivate_shield_wall()	—	nil	停止護盾牆的獨立任務並移除狀態與顯示效果。僅關閉 Lua 不會停用護盾牆。
start_zombie_necronomicon(target, chant)	table, string	nil	為生物目標啟動獨立控制器。字串是顯示的咒文，不是檔名；使用固定的 necronomicon 殭屍／骷髏檔案，以施法者等級召喚。
send_message(text, range?=20)	string, number?=20	nil	將經顏色處理的文字傳送給範圍內的玩家。
get_nearby_players(range)	number	table	回傳附近的 EliteMobs 能力玩家資料表。
get_nearby_elites(radius)	number	table	回傳同一世界中最多32個存活且受追蹤的精英，不含首領本身；依距離排序，距離相同時依 UUID 排序。半徑必須大於0且不超過64。
get_target_player()	—	table/nil	當目前的生物目標是玩家時回傳它。
get_nearby_players_in_zone(zone)	table	table	回傳該 zone 所包含的玩家。
spawn_particles_in_zone(zone, particle, count?=1, dx?=0, dy?=0, dz?=0, speed?=0, coverage?=1)	table, string（Particle）, int?=1, number?=0, number?=0, number?=0, number?=0, number?=1	nil	取樣 zone 內部並生成粒子。
spawn_particles_in_zone_border(zone, particle, count?=1, dx?=0, dy?=0, dz?=0, speed?=0, coverage?=1)	table, string（Particle）, int?=1, number?=0, number?=0, number?=0, number?=0, number?=1	nil	取樣 zone 邊緣並生成粒子。
get_particles_from_self_toward_zone(zone, particle, speed?=0.1)	table, string（Particle）, number?=0.1	table	建立由 Boss 朝向取樣 zone 點位的方向性粒子規格。
get_particles_toward_self(zone, particle, speed)	table, string（Particle）, number	table	建立朝向 Boss 的方向性粒子規格；目前的建構器是從最後傳入的參數讀取 speed。
spawn_particles_with_vector(particles)	table	nil	生成一組方向性粒子規格的陣列。
summon_reinforcement(file, zone_or_location?, duration?=0)	string, table?, int?=0	table/nil	在區域取樣點、指定位置或 Boss 處召喚增援；正值 duration 會在該 tick 數後移除。
summon_projectile(type, origin, destination, speed?=1, options?)	string（EntityType）, table, table, number?=1, table?	table/nil	生成投射物；options 支援 custom_damage、detonation_power、yield、incendiary、gravity、glowing、invulnerable、persistent、duration、EntityEffect effect、spawn_at_origin、direction_only、track、on_land 與 max_ticks。

context.players：EliteMobs Boss 能力

方法	參數	回傳	說明
current_target()	—	table/nil	當事件行為者是玩家時回傳它；否則在 Boss 目前的生物目標是玩家時回傳該目標。
nearby_players(radius)	number	table	回傳 Boss 半徑範圍內的 Player Table。
all_players_in_world()	—	table	回傳 Boss 目前世界中的所有 Player Table。

context.entities：EliteMobs Boss 能力

集合查詢排除 Boss 自身。生物篩選器接受 player/players、elite/elites、mob/mobs，其他值代表所有生物。不強制生存/冒險模式或地下城實例成員身分。直接目標查詢獨立於這些集合篩選器，回傳掛鉤提供的目標。

方法	參數	回傳	說明
get_nearby_entities(radius, filter?="living")	number, string?	table	生物篩選器使用腳部三維距離；all 或 entities 改用 Bukkit 軸對齊方框查詢，包含非生物。
get_entities_in_box(center, half_x, half_y, half_z, filter?="living")	table, number, number, number, string?	table	回傳腳部位置在方框內或邊界上的生物。
get_all_entities(filter?="living")	string?	table	回傳 Boss 所在世界中相符的生物實體。
get_direct_target_entity()	—	table/nil	回傳目前掛鉤所提供的直接目標。
get_boss_spawn_location()	—	table	回傳該 Boss 原本的生成位置。

context.vectors：EliteMobs Boss 能力

方法	參數	回傳	說明
get_vector_between_locations(source, destination, options?)	table, table, table?	table	回傳同世界兩個位置之間的向量；輸入無效或跨世界時回傳 {x=0,y=0,z=0}。options 支援 normalize、multiplier 與向量 offset。
rotate_vector(vector, pitch?=0, yaw?=0)	table, number?=0, number?=0	table	回傳依 pitch 與 yaw（度）旋轉後的向量。
normalize_vector(vector)	table	table	回傳單位向量；零向量仍為零。

context.zones：EliteMobs Boss 能力

EliteMobs Boss 能力會以 Elite Script 的 zone 定義查詢取代共用的整數控制代碼 zone 介面。

實體所屬、點包含與粒子位置取樣是不同形狀操作，邊界結果可能不同。coverage 改變取樣位置，不改變實體選擇。watch_zone 擷取形狀，向回呼傳入實體資料表而非上下文；一 tick 後開始檢查，已在內部的實體也會回報進入。停止監看不發出離開回呼。

方法	參數	回傳	說明
get_entities_in_zone(zone, options?)	table, table?	table	回傳相符的生物實體。options 支援 filter 以及 mode = "full" 或 "border"。
get_locations_in_zone(zone, options?)	table, table?	table	回傳取樣後的位置。options 支援 coverage 以及 mode = "full" 或 "border"。
zone_contains(zone, location, mode?="full")	table, table, string?	bool	測試該位置是否位於完整形狀或邊界內。
watch_zone(zone, callbacks, options?)	table, table, table?	nil	以 {on_enter, on_leave} 回呼進行監看。options 支援 filter 與 mode；所擁有的監看會隨腳本一起停止。

context.script：EliteMobs Boss 能力

此橋接介面接受與 Elite Script 的 target、zone 與相對向量 YAML 設定相同的資料表索引鍵。

方法

方法	參數	回傳	說明
target(spec)	table	target handle	建立一個 target 控制代碼。
zone(spec)	table	zone handle	建立一個 zone 控制代碼。
relative_vector(spec, location?, zone?)	table, table?, zone handle?	vector handle	建立一個相對向量控制代碼，其動作位置預設為 Boss。
damage(target, amount?=0, multiplier?=1)	target handle, number?=0, number?=1	nil	提交歸屬 Boss 的 Bukkit 傷害。玩家命中進入含倍率的 EliteMobs 戰鬥縮放；非玩家命中不套用此倍率。
push(target, vector, additive?=false)	target handle, table/vector handle, bool?=false	nil	一個自有 tick 後取代或疊加已擷取目標的速度；所有目標共用一個解析向量，缺少或非有限向量變成零。
set_facing(target, vector)	target handle, table/vector handle	nil	讓已解析的目標實體沿該向量面向。
spawn_particles(target, particles)	target handle, table/string	nil	在已解析的目標位置生成該粒子規格。

這些呼叫不會自動執行 Elite Script 動作清單、條件、冷卻、預警延遲或重複。目標控制代碼保留建立時的事件/直接目標情境，不應跨無關掛鉤重用依賴事件的控制代碼。first_entity() 是解析器第一個結果，不保證最近。

Target 控制代碼方法

方法	參數	回傳	說明
entities()	—	table	解析並回傳 Entity Table。
locations()	—	table	解析並回傳位置表。
first_entity()	—	table/nil	回傳第一個已解析的實體。
first_location()	—	table/nil	回傳第一個已解析的位置。

Zone 控制代碼方法

方法	參數	回傳	說明
full_target(coverage?)	number?	target handle	為形狀內部建立一個 target 控制代碼。
border_target(coverage?)	number?	target handle	為邊界建立一個 target 控制代碼。
full_locations(coverage?)	number?	table	解析取樣後的內部位置。
border_locations(coverage?)	number?	table	解析取樣後的邊界位置。
full_entities()	—	table	解析形狀內部的實體。
border_entities()	—	table	解析邊界上的實體。
contains(location, mode?="full")	table, string?	bool	測試是否屬於完整形狀或邊界。
watch(callbacks, mode?="full")	table, string?	int	啟動一個自己擁有的 {on_enter, on_leave} 監看並回傳其工作 ID。

相對向量控制代碼方法

方法	參數	回傳	說明
resolve()	—	table	為目前情境解析該向量。

EliteMobs 能力事件資料表

EliteMobs Boss 能力的事件值會依事件型別有條件地公開欄位與方法。

屬性

欄位	型別	說明
damage_amount	number/nil	傷害事件的數值快照。
damage_cause	string/nil	當傷害事件有提供時的 DamageCause 名稱。
damager	table/nil	原始傷害來源實體參考；投射物命中時是投射物，不是射手。
projectile	table/nil	當傷害者為投射物時的投射物參考。
spawn_reason	string/nil	Elite 的生成原因。
entity	table/nil	依掛鉤為受傷增援、死亡或區域事件實體。
is_damage_transfer	bool/nil	僅玩家對精英傷害：目前是否處理明確轉移的命中。

方法

方法	參數	回傳	說明
cancel_event()	—	nil	取消 EliteDamageEvent 或其他可取消的事件。
set_damage_amount(amount)	number	nil	取代 EliteDamageEvent 的傷害值；必須使用點號呼叫：context.event.set_damage_amount(...)。
multiply_damage_amount(multiplier)	number	nil	將 EliteDamageEvent 的傷害值相乘；必須使用點號呼叫：context.event.multiply_damage_amount(...)。
get_damage_amount()	—	number	回傳修改後的目前 EliteDamageEvent 傷害量。
transfer_damage(target, amount)	entity reference, number	bool	僅玩家對精英傷害：向實例規則允許的另一存活精英提交有限非負傷害。零、已取消輸入、巢狀轉移和原目標為 false；非精英接收者會出錯。true 表示提交，不保證傷害生效，也不扣除或取消原傷害。

context.world：EliteMobs 新增與覆寫

Boss 能力繼承共用世界資料表，包含 EliteMobs 視覺閃電與 NPC 生成輔助功能，再新增或覆寫下列方法。繼承的座標方法維持共用行為。Boss 專用位置方法使用 Boss 轉換器：省略或非表位置退回 Boss，省略座標為零，明確指定的世界名稱必須能解析。

方法

方法	參數	回傳	說明
play_sound_at_location(location, sound, volume?=1, pitch?=1)	table, string（Sound）, number?=1, number?=1	nil	覆寫版本，透過 EliteMobs 的支援接受已註冊或自訂的具命名空間音效。
spawn_particle_at_location(location, particle, count?=1)	table, string（Particle）/table, int?=1	nil	覆寫版本，接受 EliteMobs 的粒子規格表。
set_block_at_location(location, material, require_air?=false)	table, string（Material）, bool?=false	nil	覆寫版本，透過暫時方塊管理器永久放置方塊，不設計時器也不加以追蹤。
place_temporary_block_at_location(location, material, ticks?=0, require_air?=false)	table, string（Material）, int?=0, bool?=false	nil	覆寫版本，使用 EliteMobs 的暫時方塊放置。
get_block_type_at_location(location)	table	string/nil	回傳大寫的 Material 名稱；位置無效時回傳 nil。
get_highest_block_y_at_location(location)	table	int/nil	覆寫版本，回傳最高方塊的 Y 值，或 nil。
get_blast_resistance_at_location(location)	table	number	回傳方塊的爆炸抗性；位置無效時預設為 0。
is_air_at_location(location)	table	bool	測試目標方塊是否為空氣。
is_passable_at_location(location)	table	bool	測試 Bukkit 的可穿越性。
is_passthrough_at_location(location)	table	bool	測試該材質是否為非固體。
is_on_floor_at_location(location)	table	bool	測試目標為非固體且其下方為固體方塊。
is_standing_on_material(location, material)	table, string（Material）	bool	測試下方的方塊。
strike_lightning_at_location(location)	table	nil	覆寫版本，在降下閃電前啟用 EliteMobs 的閃電繞過機制。
run_empowered_lightning_task_at_location(location)	table	nil	獨立發出 60 次預警，接著生成真實閃電及爆炸強度為 5 的向下火球。會造成傷害；暫停或關閉 Lua 不會取消任務。
set_world_time(time) / set_world_time(location, time)	int/table, int?	nil	設定 Boss 所在世界的時間，或所提供位置之世界的時間。
set_world_weather(weather, duration?=6000) / set_world_weather(location, weather, duration?=6000)	string/table, string/int?, int?=6000	nil	設定 CLEAR、PRECIPITATION、RAIN 或 THUNDER。
run_console_command(command)	string	nil	以主控台身分派送一則指令。
spawn_boss_at_location(file, location?, level?)	string, table?, int?	table/nil	在所提供或目前的位置，以所提供或目前的等級生成一個自訂 Boss。
spawn_custom_boss_at_location(file, location, options?)	string, table, table?	table/nil	生成自訂 Boss；options 支援 silent、level、add_as_reinforcement 與 velocity。
spawn_entity_at_location(type, location, options?)	string（EntityType）, table, table?	table/nil	生成原版實體；options 支援 velocity、duration、EntityEffect effect、on_land 與 max_ticks。
spawn_falling_block_at_location(location, material, options?)	table, string（Material）, table?	table/nil	生成掉落方塊；options 支援 drop_item、hurt_entities、velocity 與 on_land。
spawn_reinforcement_at_location(file, location, duration?=0, velocity?)	string, table, int?=0, table?	table/nil	召喚與 Boss 綁定的增援；正值 duration 會在該 tick 數後移除。
spawn_fireworks_at_location(location, options)	table, table	table/nil	生成煙火；options 支援 effects、type、flicker、trail、colors、fade_colors、power、velocity 與 shot_at_angle，其中 type 使用 FireworkEffect.Type 名稱。
spawn_splash_potion_at_location(location, options)	table, table	table/nil	生成噴濺藥水；effects 項目接受 PotionEffectType type、duration、amplifier 與 overwrite，另外還有頂層的 velocity。
generate_fake_explosion(locations, source?)	table, table?	nil	啟用爆炸再生時，移除真實方塊並生成會造成傷害的掉落碎片。1200 tick 後開始還原；關閉 Lua 不會撤銷。位置必須在 Boss 所在世界。
spawn_fake_gold_nugget_at_location(location, velocity, gravity?=false)	table, table, bool?=false	table/nil	生成一個假金粒投射物。
run_fake_gold_nugget_damage(projectiles)	table	nil	執行假投射物的傷害處理。
generate_player_loot(times?=1)	int?=1	nil	為符合資格的傷害者產生玩家戰利品。
drop_bonus_coins(multiplier?=2)	number?=2	nil	為符合資格的傷害者掉落額外金幣。

EliteMobs 假投射物資料表

spawn_fake_gold_nugget_at_location 在生成成功時會回傳此資料表。

方法

方法	參數	回傳	說明
get_location()	—	table	回傳假投射物的位置。
set_gravity(enabled)	bool	nil	設定假投射物的重力。
remove()	—	nil	移除該假投射物。
is_removed()	—	bool	測試它是否已被移除。

context.settings

EliteMobs Boss 能力會從同一個 world table 建構器取得此設定資料表。

方法

方法	參數	回傳	說明
warning_visual_effects_enabled()	—	bool	回傳目前的警告視覺效果設定。