Lua 腳本:Boss 與實體
本頁面涵蓋 EliteMobs Lua 能力中關於 Boss 與實體包裝物的所有內容:context.boss、context.player、context.players、context.entities,以及它們所傳回的實體包裝表。如果你是 Lua 能力的新手,請先從入門開始。
實體包裝物
透過 context.boss、context.player、context.players:nearby_players() 等查詢結果或事件欄位存取實體時，你取得的是包裝表，而非原始 Bukkit 物件。欄位保存建立時的快照，方法則在呼叫時存取伺服器。
本頁介紹 EliteMobs 原生 Boss 能力包裝物。context.world:get_entity(uuid) 等共用 MagmaCore 方法可能傳回另一種包裝物，其欄位延遲讀取即時值，方法簽章也可能不同，詳見共用 API 參考。原生方法支援冒號呼叫，也支援不必明確傳入 self 的點號呼叫。對包裝物欄位賦值只會修改 Lua 表；要修改實體，請使用方法。
兩條規則需牢記:
- 像
health、current_location與maximum_health這類欄位是快照。它們反映的是包裝物建立當下的狀態,而不會自動更新。 - 像
get_location()、get_health()與is_alive()這類方法會在你每次呼叫時執行即時檢查。
共通的實體欄位
每個生物實體包裝物都包含這些欄位。
| 欄位 | 類型 | 備註 |
|---|---|---|
entity.name | string | 顯示名稱 |
entity.uuid | string | 文字形式的 UUID |
entity.entity_type | string | Bukkit EntityType 名稱(例如 "ZOMBIE"、"PLAYER") |
entity.is_player | boolean | 對玩家為 true |
entity.is_elite | boolean | 若 EliteMobs 將其追蹤為精英則為 true |
entity.is_mount | boolean | 若此包裝物代表的是 Boss 坐騎則為 true |
entity.is_monster | boolean | 對怪物類型實體為 true |
entity.health | number | 目前生命值(快照) |
entity.maximum_health | number | 最大生命值(快照) |
entity.current_location | location 表 | 包裝物建立時的位置 |
entity.is_valid | boolean | 包裝物建立時的 Bukkit 有效性快照，不只是存在性檢查 |
is_valid 是欄位，不是方法在生物實體包裝物中，包括 context.player 與 context.boss，is_valid 是建立包裝物時擷取的布林值。呼叫 entity:is_valid() 會引發 attempt to call a boolean value，並停用能力。
- 使用點號讀取快照：
entity.is_valid。 - 若要即時檢查，請呼叫
entity:is_alive()，每次都會重新查詢伺服器。
summon_projectile、spawn_falling_block_at_location 等方法傳回的非生物實體參考包裝物則確實提供 is_valid() 方法。跨 tick 保存這類參考時，可用它確認目前是否仍有效。
若要讀取精英專屬的資料(例如 Boss 等級),請使用下方 context.boss 一節所述的 context.boss 欄位與方法。若要在腳本中讓精英消失,請呼叫 entity:remove_elite() 方法。
範例
return {
api_version = 1,
on_enter_combat = function(context)
context.log:info("Boss level: " .. context.boss.level)
end
}
範例
return {
api_version = 1,
on_enter_combat = function(context)
local target = context.players:current_target()
if target ~= nil then
context.log:info("Target: " .. target.name .. " HP: " .. target.health)
end
end
}
共通的實體方法
以下方法即時存取伺服器。移動、生命值、裝備和效果操作屬於生物實體包裝物；聊天、動作列、標題、Boss 血條和玩家指令需要玩家包裝物。context.boss:send_message(...) 是向附近玩家廣播的獨立 Boss 方法。除非明確說明傳回值，修改方法傳回 nil，不是操作成功旗標。
AI、警覺性、無敵與縮放的修改屬於做出修改的能力。每項修改都會記錄被它取代的值：正數持續時間會在指定 tick 數後還原該值，關閉腳本時也會還原仍有效的修改。多個能力修改同一屬性時，結束其中一項修改會還原剩餘修改中最新的一項，若已無剩餘修改則還原原始值。若期間有其他外掛或指令修改了該屬性，則會保留其值。暫停腳本不會撤銷這些修改。標籤持續時間、延遲推力和玩家 Boss 血條使用獨立的遊戲時鐘工作，腳本關閉後仍會繼續執行。其他實體修改不會被撤銷。
entity:is_alive()
若實體仍然有效且未死亡,則傳回 true。
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
if context.player:is_alive() then
context.player:send_message("&aYou're still standing!")
end
end
}
entity:get_location()
以 location 表的形式傳回目前的即時位置。
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
local loc = context.player:get_location()
context.world:play_sound_at_location(loc, "entity.experience_orb.pickup")
end
}
entity:get_eye_location()
以 location 表的形式傳回眼睛高度的位置。
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
local eye = context.player:get_eye_location()
context.world:spawn_particle_at_location(eye, "FLAME")
end
}
entity:get_health() / entity:get_maximum_health()
傳回即時的目前生命值或最大生命值。
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
local pct = context.player:get_health() / context.player:get_maximum_health()
if pct < 0.25 then
context.player:send_message("&cYou're running low!")
end
end
}
entity:get_velocity()
以 vector 表的形式傳回實體目前的速度。
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
local vel = context.player:get_velocity()
context.log:info("Player speed Y: " .. vel.y)
end
}
entity:send_message(text)
向玩家傳送聊天訊息，支援 EliteMobs 顏色格式。
| 參數 | 類型 | 備註 |
|---|---|---|
text | string | 含顏色代碼的訊息 |
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
context.player:send_message("&6[Boss] &fPrepare yourself!")
end
}
entity:show_action_bar(message)
透過 EliteMobs 的 Lua 動作列訊息來源向玩家傳送訊息。它參與動作列合成，不會讓此腳本獨占顯示區域。
| 參數 | 類型 | 備註 |
|---|---|---|
message | string | 含顏色代碼的動作列文字 |
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
context.player:show_action_bar("&c&lDANGER ZONE")
end
}
entity:show_title(title[, subtitle][, fadeIn][, stay][, fadeOut])
向玩家傳送標題與選用的副標題，支援 EliteMobs 顏色格式。時間參數是整數刻數。
| 參數 | 類型 | 預設值 | 備註 |
|---|---|---|---|
title | string | 標題文字 | |
subtitle | string | "" | 副標題文字 |
fadeIn | number | 10 | 淡入的刻數 |
stay | number | 40 | 停留的刻數 |
fadeOut | number | 10 | 淡出的刻數 |
範例
return {
api_version = 1,
on_enter_combat = function(context)
local nearby = context.players:nearby_players(20)
for _, p in ipairs(nearby) do
p:show_title("&4PHASE 2", "&7The boss is enraged!", 10, 40, 10)
end
end
}
entity:show_boss_bar(title[, color][, style][, duration])
透過 Boss 血條順序管理器為玩家建立新血條。顏色與樣式名稱不區分大小寫，未知值分別使用 WHITE 與 SOLID。正數持續時間會安排獨立的移除計時器，非正數不新增計時器。此方法不傳回供稍後移除的控制代碼或鍵，請使用正數持續時間。此簽章與共用 MagmaCore 的鍵控血條 API 不同。
| 參數 | 類型 | 預設值 | 備註 |
|---|---|---|---|
title | string | 血條標題文字 | |
color | string | "WHITE" | BarColor 值 |
style | string | "SOLID" | BarStyle 值 |
duration | number | 40 | 持續時間(以刻為單位) |
範例
return {
api_version = 1,
on_enter_combat = function(context)
local nearby = context.players:nearby_players(20)
for _, p in ipairs(nearby) do
p:show_boss_bar("&cIncoming Attack!", "RED", "SOLID", 100)
end
end
}
entity:teleport_to_location(location)
要求 Bukkit 傳送並傳回 nil，不回報傳送是否成功。原生位置轉換接受 x、y、z、選用的 yaw/pitch、已載入的 world 名稱或巢狀 current_location 表。缺少的座標取 0；省略世界時使用施法 Boss 的世界，不一定是目標實體的世界。明確指定未知世界會轉換失敗。nil 或非表值使用 Boss 位置。這裡不新增安全目的地或區域保護檢查。
| 參數 | 類型 | 備註 |
|---|---|---|
location | location 表 | 目的地 |
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
if not context.cooldowns:check_local("teleport_pull", 200) then return end
context.player:teleport_to_location(context.boss:get_location())
context.player:send_message("&cThe boss pulls you in!")
end
}
entity:set_velocity_vector(vector)
立即設定實體的速度。
| 參數 | 類型 | 備註 |
|---|---|---|
vector | vector 表 | { x, y, z } 或 { x = 0, y = 1, z = 0 } |
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
if not context.cooldowns:check_local("launch", 100) then return end
context.player:set_velocity_vector({ x = 0, y = 1.5, z = 0 })
context.player:send_message("&cYou are launched into the air!")
end
}
entity:apply_push_vector(vector[, additive][, delay])
保存傳入的速度向量，在延遲後套用，預設延遲 1 刻。獨立計時器會確認實體仍有效。additive = true 時加到執行時的速度上，否則取代該速度。暫停或關閉腳本不會取消推力。
| 參數 | 類型 | 預設值 | 備註 |
|---|---|---|---|
vector | vector 表 | 方向與強度 | |
additive | boolean | false | 將其加到現有速度上,而非取代 |
delay | number | 1 | 施加前的延遲刻數 |
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
if not context.cooldowns:check_local("push_up", 100) then return end
context.player:apply_push_vector({ x = 0, y = 2.0, z = 0 })
context.player:send_message("&cUpward blast!")
end
}
entity:face_direction_or_location(directionOrLocation)
將實體以新的旋轉角度傳送到目前位置，藉此改變朝向。含字串 world 或巢狀 current_location 的表視為目的地，必須與實體在同一世界。只有 x/y/z 的表視為方向向量。零向量不執行操作。
| 參數 | 類型 | 備註 |
|---|---|---|
directionOrLocation | vector 或 location 表 | 要面向的目標 |
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
context.player:face_direction_or_location(context.boss:get_location())
context.player:send_message("&cThe boss forces you to look at it!")
end
}
entity:set_fire_ticks(ticks)
設定 Bukkit 燃燒刻數。呼叫時依實例效果規則重新檢查目標。玩家必須在線、存活且與效果來源處於同一世界；實例中的玩家還必須屬於有效比賽及其參與者清單。其他生物實體必須有效。此操作不保證火焰造成傷害。
| 參數 | 類型 | 備註 |
|---|---|---|
ticks | number | 著火持續時間(以刻為單位,20 刻 = 1 秒) |
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
if not context.cooldowns:check_local("ignite", 100) then return end
context.player:set_fire_ticks(60)
context.player:send_message("&cYou catch fire!")
end
}
entity:add_visual_freeze_ticks([ticks])
增加 Bukkit 的實際凍結刻數，遵守與 set_fire_ticks 相同的實例效果規則。它不只是封包層面的畫面覆蓋，也不會直接凍結 AI 或移動；正常的 Minecraft 凍結行為可能生效。
| 參數 | 類型 | 預設值 | 備註 |
|---|---|---|---|
ticks | number | 1 | 凍結刻數 |
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
if not context.cooldowns:check_local("freeze", 200) then return end
context.player:add_visual_freeze_ticks(100)
context.player:send_message("&bYou feel a chilling frost!")
end
}
entity:apply_potion_effect(effect, duration[, amplifier])
通過與 set_fire_ticks 相同的實例效果檢查後，套用 Bukkit 藥水效果。名稱不區分大小寫，未知名稱會警告且不執行操作。取代既有狀態遵循 Bukkit 的效果規則，不會強制覆寫所有現有效果。
| 參數 | 類型 | 預設值 | 備註 |
|---|---|---|---|
effect | string | PotionEffectType 名稱 | |
duration | number | 持續時間(以刻為單位) | |
amplifier | number | 0 | 效果等級(0 = 等級 I) |
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
if not context.cooldowns:check_local("slow", 200) then return end
context.player:apply_potion_effect("SLOWNESS", 60, 1)
context.player:send_message("&7You feel sluggish...")
end
}
remove_potion_effect(effect) 不適用於 EliteMobs 原生 Boss 能力實體包裝物，但共用 MagmaCore 包裝物提供此方法。套用效果時請設定適當的持續時間。再次套用持續時間為 0 的效果無法可靠地移除現有效果。
entity:deal_damage(amount) / entity:deal_custom_damage(amount) / entity:deal_damage_from_boss(amount)
向 Bukkit 提交傷害。三種方法都傳回 nil；要求的數量不能證明實際損失的生命值。戰鬥規則及後續監聽器可能修改或取消攻擊。
| 方法 | 備註 |
|---|---|
deal_damage(amount) | 不指定攻擊者，呼叫 Bukkit 傷害方法 |
deal_custom_damage(amount) | 以施法 Boss 呼叫 BossCustomAttackDamage，拒絕自身、無敵或死亡目標，以及非 Survival/Adventure 玩家；提交自訂攻擊後清除原生傷害冷卻 |
deal_damage_from_boss(amount) | 以施法 Boss 為攻擊者呼叫 Bukkit 傷害方法，可能進入正常 EliteMobs 戰鬥處理 |
範例
return {
api_version = 1,
on_enter_combat = function(context)
local nearby = context.players:nearby_players(10)
for _, p in ipairs(nearby) do
p:deal_custom_damage(10)
p:send_message("&cThe boss unleashes a shockwave!")
end
end
}
entity:restore_health(amount)
對追蹤中的精英呼叫 EliteMobs 治療並觸發可取消的 EliteMobHealEvent。其他生物實體直接回復到最大生命屬性的基礎值，這可能不同於 get_maximum_health() 傳回的有效最大值。請傳入非負數量；此方法不是會自動限制輸入的傷害 API。
| 參數 | 類型 | 備註 |
|---|---|---|
amount | number | 治療量 |
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
-- Heal the player slightly when they hit the boss
context.player:restore_health(5)
context.player:send_message("&aYou drain life from the boss!")
end
}
entity:set_invulnerable(enabled[, duration])
設定實體無敵狀態，並記錄被取代的值。正數持續時間會在指定刻數後還原該值；否則修改會持續到此能力關閉，關閉時同樣會還原。由同一能力再次呼叫，會取代該能力先前的修改。
| 參數 | 類型 | 預設值 | 備註 |
|---|---|---|---|
enabled | boolean | true 表示啟用無敵 | |
duration | number | 0 | 在這些刻數後還原被取代的值；0 會讓修改持續到能力關閉 |
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
if not context.cooldowns:check_local("shield", 200) then return end
context.player:set_invulnerable(true, 40)
context.player:send_message("&6A brief shield protects you!")
end
}
entity:set_ai_enabled(enabled[, duration])
設定實體 AI，並記錄被取代的值。正數持續時間會在指定刻數後還原該值；否則修改會持續到此能力關閉，關閉時同樣會還原。此能力持有 AI 修改時呼叫 set_ai_enabled(true)，會結束該修改並還原被取代的值，而不是套用新的修改。
| 參數 | 類型 | 預設值 | 備註 |
|---|---|---|---|
enabled | boolean | true 表示啟用 AI | |
duration | number | 0 | 在這些刻數後還原被取代的值；0 會讓修改持續到能力關閉 |
範例
return {
api_version = 1,
on_enter_combat = function(context)
-- Disable boss AI for 3 seconds at combat start
context.boss:set_ai_enabled(false, 60)
context.boss:send_message("&7The boss is stunned!")
end
}
entity:add_tag(tag[, duration]) / entity:remove_tag(tag) / entity:has_tag(tag)
管理追蹤中精英及已載入 EliteMobs 玩家背包資料的玩家標籤。它們不是 Bukkit 計分板標籤，不適用於一般未追蹤生物。標籤區分大小寫。到期計時器獨立執行，舊計時器可能移除後來重新新增的同名標籤。
| 方法 | 參數 | 備註 |
|---|---|---|
add_tag(tag[, duration]) | string、可選的 number | 新增標籤,可選擇在經過指定刻數後自動移除 |
remove_tag(tag) | string | 移除該標籤 |
has_tag(tag) | string | 若標籤存在則傳回 true |
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
if not context.player:has_tag("marked") then
context.player:add_tag("marked", 200)
context.player:send_message("&cYou have been marked!")
end
end
}
entity:run_command(command)
立即以玩家身分及其權限執行指令，傳回 nil。這是玩家專用方法，不展開預留位置。指令不要加上開頭的 /。
| 參數 | 類型 | 備註 |
|---|---|---|
command | string | 不含開頭 / 的指令文字 |
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
if not context.cooldowns:check_local("curse_cmd", 200) then return end
context.player:run_command("say I have been cursed!")
end
}
entity:set_scale(scale[, duration])
在可用時設定實體縮放屬性的基礎值，並記錄被取代的值。正數持續時間會在指定刻數後還原該值；否則修改會持續到此能力關閉，關閉時同樣會還原。屬性修飾項仍可能讓實際大小不同。
| 參數 | 類型 | 預設值 | 備註 |
|---|---|---|---|
scale | number | 縮放倍率 | |
duration | number | 0 | 在這些刻數後還原被取代的縮放；0 會讓修改持續到能力關閉 |
範例
return {
api_version = 1,
on_enter_combat = function(context)
-- Boss grows to double size for 5 seconds
context.boss:set_scale(2.0, 100)
context.boss:send_message("&4The boss grows in size!")
end
}
entity:set_gravity(enabled)
設定實體重力，不自動還原。下方還原回呼屬於 Lua 實例，腳本關閉後可能不會執行。
| 參數 | 類型 | 備註 |
|---|---|---|
enabled | boolean | true 表示正常重力 |
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
if not context.cooldowns:check_local("levitate", 200) then return end
-- Change the boss's gravity; the callback runs only while this script stays active.
context.boss:set_gravity(false)
context.scheduler:run_after(60, function(tick_context)
if tick_context.boss.exists then
tick_context.boss:set_gravity(true)
end
end)
end
}
entity:play_sound_at_entity(sound[, volume][, pitch])
在實體的位置播放一個音效。
| 參數 | 類型 | 預設值 | 備註 |
|---|---|---|---|
sound | string | Minecraft 音效鍵(例如 "entity.ender_dragon.growl")，或 Spigot Sound 列舉名稱。資源包的鍵同樣可用。 | |
volume | number | 1.0 | 音量 |
pitch | number | 1.0 | 音高 |
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
context.player:play_sound_at_entity("entity.ender_dragon.growl", 1.0, 0.5)
end
}
entity:play_sound_at_self(sound[, volume][, pitch])
play_sound_at_entity 的別名。在實體的位置播放一個音效。
entity:spawn_particle_at_self(particleOrSpec[, count])
在實體目前位置生成粒子，使用與原生世界方法相同的粒子規格。表中的 amount 優先於備用的 count。名稱轉為大寫，不支援的資料相依粒子會警告而不生成。
| 參數 | 類型 | 預設值 | 備註 |
|---|---|---|---|
particleOrSpec | string 或 table | 粒子名稱或規格表 | |
count | number | 1 | 粒子數量 |
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
context.player:spawn_particle_at_self("HEART", 5)
end
}
entity:spawn_particles_at_location(location, particle[, count])
在指定的位置生成粒子。
| 參數 | 類型 | 預設值 | 備註 |
|---|---|---|---|
location | location 表 | 目標位置 | |
particle | string | 粒子類型名稱 | |
count | number | 1 | 粒子數量 |
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
local loc = context.player:get_location()
context.player:spawn_particles_at_location(loc, "FLAME", 10)
end
}
entity:play_model_animation(name)
僅當 EliteMobs 將實體追蹤為具有自訂模型的自訂 Boss 時要求動畫。傳回 nil，不等待完成，也不回報動畫名稱是否存在。一般有模型的實體不符合此原生方法的條件。
| 參數 | 類型 | 備註 |
|---|---|---|
name | string | 動畫名稱 |
範例
return {
api_version = 1,
on_enter_combat = function(context)
context.boss:play_model_animation("attack_swing")
end
}
載具與乘客方法
生物實體包裝物也提供 Bukkit 載具與乘客方法。包裝物參數透過 Bukkit UUID 解析，不接受單獨的 UUID 字串。乘騎會拒絕缺失、相同或無效實體，暫時繞過 EliteMobs 的坐騎漏洞防護，並傳回 Bukkit 是否接受操作。這些方法不會註冊腳本運輸路線，也不安排腳本關閉時的清理。
| 方法 | 傳回 | 備註 |
|---|---|---|
entity:is_inside_vehicle() | boolean | 若該實體正乘騎另一個實體則為 True。 |
entity:has_vehicle() | boolean | 若該實體目前擁有載具則為 True。 |
entity:get_vehicle() | 實體包裝物或 nil | 傳回目前的載具包裝物。 |
entity:set_vehicle(vehicle) | boolean | 讓此實體乘騎 vehicle。 |
entity:leave_vehicle() | boolean | 讓此實體離開其目前的載具。 |
entity:has_passengers() | boolean | 若此實體擁有乘客則為 True。 |
entity:get_passenger_count() | number | 乘客數量。 |
entity:get_passengers() | table | 乘客包裝物的陣列。 |
entity:add_passenger(passenger) | boolean | 為此實體新增一名乘客。 |
entity:remove_passenger(passenger) | boolean | 從此實體移除一名乘客。 |
entity:eject_passengers() | boolean | 拋出所有乘客。 |
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
if context.player:has_vehicle() then
context.player:leave_vehicle()
end
end
}
entity:push_relative_to(source[, strength][, xOffset][, yOffset][, zOffset])
將從來源位置指向實體的位移正規化，乘上 strength，加上世界軸偏移，立即以結果取代速度。位置重合時仍使用偏移。包裝物提供的是保存的 current_location，需要即時位置時請傳入 source:get_location()。此方法不檢查世界是否一致，只應使用同一世界的位置。
| 參數 | 類型 | 預設值 | 備註 |
|---|---|---|---|
source | location 或包裝物 | 推力來源 | |
strength | number | 1.0 | 推力強度倍率 |
xOffset | number | 0 | 額外的 X 偏移 |
yOffset | number | 0 | 額外的 Y 偏移 |
zOffset | number | 0 | 額外的 Z 偏移 |
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
if not context.cooldowns:check_local("knockback", 60) then return end
context.player:push_relative_to(context.boss:get_location(), 2.0, 0, 0.5, 0)
context.player:send_message("&cThe boss knocks you back!")
end
}
entity:set_custom_name(name) / entity:reset_custom_name()
使用顏色格式設定 Bukkit 自訂名稱。重設時，追蹤中的精英使用設定名稱；未追蹤實體使用其目前 getName()，因此不會還原預先保存的原名。這不會修改玩家帳號名稱或包裝物的快照欄位。
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
if not context.cooldowns:check_local("mark", 200) then return end
context.boss:set_custom_name("&c&lEnraged Boss")
context.boss:send_message("&cThe boss is enraged!")
-- Reset after 5 seconds
context.scheduler:run_after(100, function(tick_context)
if tick_context.boss:is_alive() then
tick_context.boss:reset_custom_name()
end
end)
end
}
entity:place_temporary_block(material[, duration][, requireAir])
在實體目前位置放置臨時方塊，傳回 nil，包括 requireAir 阻止放置的情況。持續時間為正數時，會在計時器結束、區塊或世界卸載，或插件關閉時還原保存的方塊資料（不含容器內容），但前提是該位置仍是這個臨時方塊。在同一個臨時方塊上再次放置會重新開始計時。帶有方塊實體的方塊（例如箱子），以及已被其他臨時方塊擁有者持有的方塊，都會被略過。破壞該方塊不會有任何掉落物。非正數持續時間會永久放置方塊，且不加以追蹤。請使用方塊材質並自行檢查保護規則。
| 參數 | 類型 | 預設值 | 備註 |
|---|---|---|---|
material | string | 方塊材質名稱 | |
duration | number | 0 | 正數表示還原前的刻數；非正數會永久放置方塊 |
requireAir | boolean | false | 僅在該方塊目前為空氣時才放置 |
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
if not context.cooldowns:check_local("ice_trap", 200) then return end
context.player:place_temporary_block("ICE", 60, true)
context.player:send_message("&bIce forms at your feet!")
end
}
entity:get_height()
傳回實體以方塊為單位的高度。
entity:is_on_ground()
傳回 Bukkit 目前的 isOnGround() 旗標，不重新查詢方塊或頭部空間。
entity.is_valid
在生物實體包裝物中，這是布林欄位，不是方法。它記錄建立包裝物時的 Bukkit 有效性，不只是實體是否存在。請使用點號讀取 entity.is_valid，用冒號呼叫會引發錯誤。
快照可能過時，無法取代即時檢查。若需要目前狀態，請使用 entity:is_alive()；對於跨 tick 保存的非生物實體參考包裝物，則使用 is_valid() 方法。
entity:is_frozen()
若實體(當被追蹤為自訂 Boss 時)設定了凍結旗標,則傳回 true。
entity:set_awareness_enabled(aware[, duration])
設定 Mob 警覺性，並記錄被取代的值。只影響 Mob 類型的實體。正數持續時間會在指定刻數後還原該值；否則修改會持續到此能力關閉，關閉時同樣會還原。此能力持有警覺性修改時以 true 呼叫，會結束該修改，而不是套用新的修改。
| 參數 | 類型 | 預設值 | 備註 |
|---|---|---|---|
aware | boolean | true 表示啟用警覺性 | |
duration | number | 0 | 在這些刻數後還原被取代的值；0 會讓修改持續到能力關閉 |
entity:is_healing() / entity:set_healing(enabled)
讀取或設定追蹤中精英的治療狀態旗標，不直接回復生命值，也不啟動治療計時器。set_healing(true) 會在精英尚未處於治療狀態時將其標記為治療中；set_healing(false) 只會清除此能力所設定的治療狀態。能力關閉時，會清除它仍持有的任何治療旗標。未追蹤實體的讀取結果為 false，寫入不產生變化。
entity:overlaps_box_at_location(center[, halfX][, halfY][, halfZ])
檢查實體碰撞箱是否與數值定義的軸對齊方框重疊，不比較世界。請傳入與實體同世界的中心。無法解析中心時傳回 false。
| 參數 | 類型 | 預設值 | 備註 |
|---|---|---|---|
center | location 表 | 測試方框的中心 | |
halfX | number | 0.5 | X 軸上的半寬 |
halfY | number | 與 halfX 相同 | Y 軸上的半高 |
halfZ | number | 與 halfX 相同 | Z 軸上的半寬 |
entity:remove_elite()
將精英實體從 EliteMobs 的追蹤中移除。如果該實體是精英,這會透過 EliteMobs 正確地讓它消失。
entity:remove()
移除由腳本生成的普通生物實體，例如盔甲座。移除成功時傳回 true。玩家與精英會被拒絕並傳回 false；要讓精英消失，請使用 remove_elite()。
entity:set_invisible(enabled) 與 entity:set_silent(enabled)
set_invisible 會隱藏實體的身體；穿戴與手持的物品仍然可見。set_silent 會讓實體自身的聲音靜音。
entity:set_marker(enabled)
僅限盔甲座。這四個方法只存在於盔甲座包裝物件上，其他實體都沒有。
| 方法 | 效果 |
|---|---|
set_marker(enabled) | 標記盔甲座沒有碰撞箱，無法被擊中或碰撞 |
set_small(enabled) | 半尺寸盔甲座 |
set_base_plate(enabled) | 顯示或隱藏石質底座 |
set_arms(enabled) | 顯示或隱藏手臂 |
若只需要純視覺效果的懸浮物品或方塊，建議改用 world:spawn_display_at_location，它完全不需要上述任何方法。
entity:set_custom_name_visible(visible)
設定實體的自訂名稱是永遠可見,還是僅在被注視時才可見。
| 參數 | 類型 | 備註 |
|---|---|---|
visible | boolean | true 表示永遠可見 |
entity:set_equipment(slot, material[, options])
用新建的材質物品取代所選欄位。欄位、材質和附魔名稱不區分大小寫。未知欄位或材質不執行操作；未知附魔會略過，已識別附魔使用不受一般限制的等級。此方法不載入自訂物品檔，也不保留原物品的中繼資料，傳回 nil。
| 參數 | 類型 | 預設值 | 備註 |
|---|---|---|---|
slot | string | 裝備欄位:"HEAD"、"CHEST"、"LEGS"、"FEET"、"HAND"、"OFF_HAND" | |
material | string | 材質名稱(例如 "DIAMOND_SWORD"、"IRON_HELMET") | |
options | table | {} | 可選設定(見下文) |
選項表：
| 鍵 | 類型 | 預設值 | 備註 |
|---|---|---|---|
enchantments | table 陣列 | nil | 每個項目:{ type = "SHARPNESS", level = 2 } |
unbreakable | boolean | false | 物品是否為不可破壞 |
範例
return {
api_version = 1,
on_enter_combat = function(context)
-- Give the boss a glowing diamond sword
context.boss:set_equipment("HAND", "DIAMOND_SWORD", {
unbreakable = true,
enchantments = {
{ type = "SHARPNESS", level = 5 }
}
})
end
}
entity:damage_equipment(slot, amount)
損傷 HAND、OFF_HAND、HEAD、CHEST、LEGS 或 FEET 欄位的物品，傳回實際套用的耐久損傷。每次要求 1 到 64 點。缺失、沒有耐久值或不可破壞的物品傳回 0。
玩家操作會觸發 PlayerItemDamageEvent，遵守取消及修改後的數量。監聽器可以把數量提高到原始要求上限 64 以上，但最終仍受剩餘耐久限制。達到最大損傷時會移除整個物品堆疊，並觸發玩家的 PlayerItemBreakEvent。支援自訂最大損傷中繼資料，不自行計算耐久附魔減免。無效欄位或超出 1..64 的要求會引發 Lua 引數錯誤。
entity:is_ai_enabled()
實體目前啟用 AI 時傳回 true。追蹤中的精英讀取 EliteMobs 的邏輯 AI 狀態，包括原生行為的控制權，而非只依賴底層 Bukkit AI 旗標。
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.boss:is_ai_enabled() then
context.log:info("Boss AI is active")
else
context.log:info("Boss AI is disabled (stunned?)")
end
end
}
非生物實體參考包裝物
當一個生成的實體並非 LivingEntity 時——例如下落的方塊、投射物或火球——你會拿到一個較輕量的參考包裝物。這些是由 context.world:spawn_falling_block_at_location() 或 context.boss:summon_projectile() 這類方法所傳回的。
快照欄位： name、uuid、entity_type、is_player（固定為 false）、is_elite（固定為 false）、is_mount（通常為 false；boss:get_mount() 將其設為 true）、current_location
方法:
| 方法 | 備註 |
|---|---|
is_valid() | 即時有效性檢查。與生物實體包裝物不同，這裡確實是方法 |
get_location() | 目前的即時位置 |
get_velocity() | 目前的速度向量 |
is_on_ground() | 是否在地面上 |
teleport_to_location(location) | 傳送該實體 |
set_velocity_vector(vector) | 設定速度 |
set_direction_vector(vector) | 設定方向(僅限 Fireball) |
set_yield(value) | 設定爆炸威力(僅限 Fireball) |
set_gravity(enabled) | 切換重力 |
detonate() | 要求引爆煙火實體，對其他類型不生效 |
remove() | 將實體從世界中移除 |
unregister([reason]) | 對追蹤器識別的實體執行 EliteMobs 移除流程，未追蹤實體不變 |
這些包裝物也提供完整的載具與乘客方法，包括 is_inside_vehicle()、get_vehicle()、set_vehicle(v)、add_passenger(p) 和 eject_passengers() 等，因此可以讓 Boss 乘坐非生物實體。
unregister 接受不區分大小寫的移除原因，預設為 OTHER，不是布林成功查詢。包裝物方法保留底層實體參考，使用保存的參考前請呼叫 is_valid()。Lua 實例安排的延遲移除會在實例關閉時取消；若清理必須在腳本結束後繼續，請使用適當的原生持續時間或擁有者追蹤。
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
if not context.cooldowns:check_local("fireball", 100) then return end
local fb = context.boss:summon_projectile("FIREBALL",
context.boss:get_eye_location(),
context.player:get_location(),
1.5
)
if fb == nil then return end
-- fb is a non-living reference wrapper; remove it after 5 seconds if still alive
context.scheduler:run_after(100, function()
if fb:is_valid() then
fb:remove()
end
end)
end
}
context.player
事件的直接目標或行為者可解析為玩家時可用，包括 on_boss_damaged_by_player 與 on_player_damaged_by_boss，優先使用直接目標。玩家包裝物提供共通生物實體方法，但要求追蹤中精英或自訂 Boss 的方法對一般玩家不生效。下列額外內容僅供玩家使用。
在沒有相關聯玩家的鉤子中,context.player 為 nil,例如 on_spawn、排程回呼以及計時器鉤子。使用前請務必進行 nil 防護。
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
context.player:send_message("&cHello!")
end
}
僅限玩家的欄位
| 欄位 | 類型 | 備註 |
|---|---|---|
game_mode | string | 建立時的遊戲模式快照，使用大寫名稱，例如 "SURVIVAL" |
僅限玩家的方法
| 方法 | 備註 |
|---|---|
send_message(message) | 含 EliteMobs 顏色格式的聊天訊息 |
show_action_bar(message) | 動作列文字 |
show_title(title[, subtitle][, fadeIn][, stay][, fadeOut]) | 標題畫面覆蓋 |
show_boss_bar(title[, color][, style][, duration]) | 臨時 Boss 血條 |
run_command(command) | 以該玩家身分執行指令(不含開頭 /) |
範例
return {
api_version = 1,
on_player_damaged_by_boss = function(context)
if context.player == nil then return end
local hp_pct = context.player:get_health() / context.player:get_maximum_health()
if hp_pct < 0.3 then
context.player:show_title("&4LOW HEALTH", "&7Find cover!", 5, 30, 10)
context.player:show_boss_bar("&cBoss Enrage Incoming", "RED", "SEGMENTED_6", 80)
end
end
}
context.boss
擁有此 Lua 能力的精英怪物包裝物。底層實體不存在時，不會提供完整的生物實體欄位與方法。
底層實體存在時，Boss 包裝物繼承共通生物實體操作，但不包含玩家專用的介面和指令操作。本節方法是 Boss 專屬方法，或透過 EliteEntity 層執行不同行為的方法。
Boss 欄位
| 欄位 | 類型 | 備註 |
|---|---|---|
boss.name | string | 顯示名稱 |
boss.uuid | string | Boss 精英 UUID |
boss.entity_type | string | Bukkit EntityType 名稱 |
boss.is_monster | boolean | 若底層實體為 Monster 則為 true |
boss.level | number | 精英等級 |
boss.health | number | 目前生命值(快照) |
boss.maximum_health | number | 最大生命值(快照) |
boss.damager_count | number | 傷害來源數量(快照) |
boss.is_in_combat | boolean | 戰鬥狀態快照 |
boss.exists | boolean | 精英是否存在的快照 |
boss.current_location | location 表 | 包裝物建立時的位置(快照) |
範例
return {
api_version = 1,
on_spawn = function(context)
context.log:info(context.boss.name .. " level " .. context.boss.level)
end
}
Boss 方法
巡邏移動方法
已設定巡邏的首領會提供 patrol_pause()、patrol_resume()、walk_to(x, y, z)、hold(x, y, z) 與 teleport(x, y, z)。座標是相對於生成位置的偏移，每個方法都會回傳請求是否被接受。walk_to 抵達後恢復路線；hold 等待 patrol_resume()；長距離使用自動解算器。
boss:is_alive()
若 Boss 實體有效、未死亡,且精英仍存在,則傳回 true。進行即時檢查時請使用此方法,而非 exists 欄位。
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if not context.boss:is_alive() then return end
context.boss:send_message("&cI still live!")
end
}
boss:get_location()
以 location 表的形式傳回 Boss 目前的即時位置。
範例
return {
api_version = 1,
on_enter_combat = function(context)
local loc = context.boss:get_location()
context.world:spawn_particle_at_location(loc, "FLAME")
end
}
boss:get_eye_location()
傳回 Boss 眼睛高度的位置。
範例
return {
api_version = 1,
on_enter_combat = function(context)
local eye = context.boss:get_eye_location()
context.world:spawn_particle_at_location(eye, "SMOKE")
end
}
boss:set_ai_enabled(enabled[, duration])
設定 Boss 的 AI，並遵循與 entity:set_ai_enabled 相同的修改歸屬規則：正數持續時間會還原被取代的值，關閉能力時也會還原仍有效的修改。
| 參數 | 類型 | 預設值 | 備註 |
|---|---|---|---|
enabled | boolean | true 表示啟用 AI | |
duration | number | 0 | 在這些刻數後還原被取代的值；0 會讓修改持續到能力關閉 |
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if not context.cooldowns:check_local("stun", 200) then return end
context.boss:set_ai_enabled(false, 60)
context.boss:send_message("&7The boss is stunned for 3 seconds!")
end
}
boss:teleport_to_location(location)
要求傳送 Boss，但不修改設定中的生成位置或巡邏路線。傳回 nil，不是傳送成功旗標。
| 參數 | 類型 | 備註 |
|---|---|---|
location | location 表 | 目的地 |
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if not context.cooldowns:check_local("retreat", 300) then return end
local spawn = context.entities:get_boss_spawn_location()
context.boss:teleport_to_location(spawn)
context.boss:send_message("&7The boss retreats to its lair!")
end
}
boss:set_velocity_vector(vector)
立即設定 Boss 的速度。
| 參數 | 類型 | 備註 |
|---|---|---|
vector | vector 表 | { x, y, z } 或 { x = 0, y = 1, z = 0 } |
範例
return {
api_version = 1,
on_enter_combat = function(context)
-- Boss leaps into the air at combat start
context.boss:set_velocity_vector({ x = 0, y = 2.0, z = 0 })
context.boss:send_message("&cThe boss leaps!")
end
}
boss:restore_health(amount)
以非負數量治療 Boss，上限為 EliteMobs 最大生命值與最大生命屬性基礎值中的較小者。會觸發可取消的 EliteMobHealEvent，傳回 nil。
| 參數 | 類型 | 備註 |
|---|---|---|
amount | number | 治療量 |
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if not context.cooldowns:check_local("heal", 200) then return end
context.boss:restore_health(20)
context.boss:send_message("&aThe boss regenerates!")
context.boss:spawn_particle_at_self("HEART")
end
}
boss:play_sound_at_self(sound[, volume][, pitch])
在 Boss 的位置播放一個音效。
| 參數 | 類型 | 預設值 | 備註 |
|---|---|---|---|
sound | string | Minecraft 音效鍵(例如 "entity.wither.spawn")，或 Spigot Sound 列舉名稱。資源包的鍵同樣可用。 | |
volume | number | 1.0 | 音量 |
pitch | number | 1.0 | 音高 |
範例
return {
api_version = 1,
on_spawn = function(context)
context.boss:play_sound_at_self("entity.wither.spawn", 1.0, 0.8)
end
}
boss:spawn_particle_at_self(particleOrSpec[, count])
在 Boss 的位置生成粒子。
| 參數 | 類型 | 預設值 | 備註 |
|---|---|---|---|
particleOrSpec | string 或 table | 粒子名稱或規格表 | |
count | number | 1 | 粒子數量 |
範例
return {
api_version = 1,
on_enter_combat = function(context)
context.boss:spawn_particle_at_self("SMOKE", 20)
context.boss:send_message("&8Smoke billows from the boss!")
end
}
boss:play_model_animation(name)
如果可用,則在 Boss 身上播放一段自訂模型動畫。
| 參數 | 類型 | 備註 |
|---|---|---|
name | string | 動畫名稱 |
範例
return {
api_version = 1,
on_enter_combat = function(context)
context.boss:play_model_animation("slam")
end
}
boss:has_mount() / boss:get_mount()
檢查或傳回此 Boss 目前所乘騎的實體。如果 Boss 沒有坐騎,boss:get_mount() 會傳回 nil。當傳回一個坐騎時,其包裝物的 is_mount = true。
範例
return {
api_version = 1,
on_enter_combat = function(context)
local mount = context.boss:get_mount()
if mount ~= nil then
context.log:info("Boss is mounted on " .. mount.entity_type)
end
end
}
boss:set_mount(entity) / boss:clear_mount() / boss:dismount()
讓 Boss 乘騎或下騎。boss:set_mount(entity) 會讓 Boss 乘騎所提供的實體包裝物,並在 Bukkit 接受該乘客變更時傳回 true。boss:clear_mount() 與 boss:dismount() 都會讓 Boss 離開其目前的載具。
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if not context.cooldowns:check_local("mount_check", 100) then return end
if context.boss:has_mount() then
context.boss:dismount()
end
end
}
boss:face_direction_or_location(vectorOrLocation)
讓 Boss 面向某個方向或位置。
| 參數 | 類型 | 備註 |
|---|---|---|
vectorOrLocation | vector 或 location 表 | 要面向的方向 |
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
context.boss:face_direction_or_location(context.player:get_location())
end
}
boss:navigate_to_location(location[, speed][, forceTeleport][, timeout])
使用尋路功能讓 Boss 走向指定位置。僅適用於自訂 Boss。
| 參數 | 類型 | 預設值 | 備註 |
|---|---|---|---|
location | location 表 | 目的地 | |
speed | number | 1.0 | 移動速度倍率 |
forceTeleport | boolean | false | 若經過 timeout 仍未抵達，將 Boss 傳送至目的地 |
timeout | number | 0 | 放棄導航前等待的刻數。0 代表使用內建預設值 100 刻（5秒） |
當 Boss 距離目的地不足一個方塊、不再存在或離開目的地所在世界時，導航也會停止。開始新的導航會取消該 Boss 原本正在執行的導航。它使用獨立 Bukkit 工作，暫停或關閉 Lua 實例不會取消。目的地在呼叫時保存，傳回 nil 而非抵達結果。
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
if not context.cooldowns:check_local("charge", 200) then return end
context.boss:navigate_to_location(context.player:get_location(), 1.5)
context.boss:send_message("&cThe boss charges at you!")
end
}
boss:add_tag(tag[, duration]) / boss:remove_tag(tag) / boss:has_tag(tag)
管理 Boss 上的標籤。
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
local pct = context.boss:get_health() / context.boss:get_maximum_health()
if pct < 0.5 and not context.boss:has_tag("phase2") then
context.boss:add_tag("phase2")
context.boss:send_message("&4Entering Phase 2!")
end
end
}
boss:send_message(message[, range])
向 Boss 同世界球形三維範圍內的所有玩家傳送帶格式的聊天訊息，不依遊戲模式、視線、戰鬥參與或實例成員身分篩選。
| 參數 | 類型 | 預設值 | 備註 |
|---|---|---|---|
message | string | 含顏色代碼的訊息文字 | |
range | number | 20 | 半徑(以方塊為單位) |
範例
return {
api_version = 1,
on_enter_combat = function(context)
context.boss:send_message("&4You dare challenge me?!")
end
}
boss:summon_projectile(entityType, origin, destination[, speed][, options])
建立實體並傳回原生包裝物；位置無法解析或實體類型未知時傳回 nil。已識別但不能生成的類型仍可能失敗。一般 Bukkit 投射物從 Boss 發射，除非設定 spawn_at_origin = true；提供的起點仍用來計算朝向目的地的方向。此方法不檢查兩個位置的世界是否一致，請確保它們在同一世界。非投射物在提供的起點生成，並使用對應的生物或非生物包裝物。
| 參數 | 類型 | 預設值 | 備註 |
|---|---|---|---|
entityType | string | 實體類型(例如 "FIREBALL"、"ARROW") | |
origin | location 表 | 發射位置 | |
destination | location 表 | 目標位置 | |
speed | number | 1.0 | 投射物速度 |
options | table | {} | 見下方選項 |
選項表：
| 鍵 | 類型 | 備註 |
|---|---|---|
duration | number | 正數安排獨立計時器，在這些刻數後移除；非正數不新增計時器 |
max_ticks | number | 落地監測上限，預設為 6000 |
custom_damage | number | 投射物戰鬥處理使用的自訂傷害中繼資料，不保證生命損失量 |
detonation_power | string | 爆炸投射物中繼資料使用的能力檔名，不是數值爆炸強度 |
yield | number | 爆炸威力(Fireball) |
persistent | boolean | 提供時設定 Bukkit 持久性，不覆寫持續時間、碰撞或擁有者移除 |
effect | string | 生成時要播放的 EntityEffect 名稱 |
incendiary | boolean | 爆炸是否會點火 |
gravity | boolean | 投射物是否有重力 |
glowing | boolean | 發光效果 |
invulnerable | boolean | 投射物是否無敵 |
track | boolean | 預設為 true：向 EliteMobs 註冊投射物，不會使其追蹤目標。 |
spawn_at_origin | boolean | 預設為 false：一般投射物從 Boss 處發射。設為 true 才會在指定起點生成。 |
direction_only | boolean | 對明確起點生成的火球，設定方向後不額外設定速度 |
on_land | function | 接地、失效或超過 max_ticks 時的回呼 (landing_location, spawned_entity)，不只在撞擊時觸發 |
direction_only 影響在指定起點明確生成的火球，略過設定方向後的額外速度賦值。目的地仍決定方向。Bukkit 投射物以 Boss 為射手。track = true 會向 EliteMobs 註冊投射物，並將其納入 Boss 援軍的生命週期；此追蹤不適用於非投射物類型。track = false 不參與擁有者清理，需要另行安排移除。
on_land 監測屬於 Lua 實例，在實例關閉時停止。它在接地、失效或計數器超限時呼叫一次 (landing_location, spawned_entity)，監測本身不會移除實體。正數 duration 計時器獨立執行，腳本關閉後仍繼續。因此，回呼發生並不證明投射物命中了目標。
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
if not context.cooldowns:check_local("fireball", 100) then return end
context.boss:summon_projectile(
"FIREBALL",
context.boss:get_eye_location(),
context.player:get_location(),
1.5,
{
custom_damage = 10,
on_land = function(loc, entity)
context.world:spawn_particle_at_location(loc, "EXPLOSION")
end
}
)
end
}
boss:summon_reinforcement(filename[, zoneOrLocation][, duration])
從自訂 Boss 檔案靜默召喚援軍，記錄召喚者，並在自訂 Boss 召喚者使用標準化戰鬥時繼承該模式。援軍等級由自身設定和動態等級規則決定。區域會隨機選擇取樣位置，若沒有位置則使用中心；解析失敗時退回 Boss 位置。傳回存活援軍的生物實體包裝物，未生成存活援軍時傳回 nil。
| 參數 | 類型 | 備註 |
|---|---|---|
filename | string | Boss 配置檔名稱 |
zoneOrLocation | location 表或 zone | 可選的生成位置或區域定義。預設為 Boss 的位置。 |
duration | number | 選用的正數逃離時間，以刻為單位。預設 0 不新增此方法的計時器；不是等級覆寫值 |
範例
return {
api_version = 1,
on_enter_combat = function(context)
context.boss:summon_reinforcement("my_minion.yml", context.boss:get_location(), 0)
context.boss:send_message("&cMinions, come to my aid!")
end
}
boss:despawn()
透過 EliteMobs 以原因 OTHER 移除 Boss。boss:remove() 是使用相同生命週期的別名。此操作不是傷害命中，也不是正常死亡獎勵要求。
範例
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
local pct = context.boss:get_health() / context.boss:get_maximum_health()
if pct < 0.1 then
context.boss:send_message("&7The boss vanishes into thin air!")
context.boss:despawn()
end
end
}
boss:get_nearby_players(range)
傳回 Boss 同世界球形三維範圍內的玩家包裝物陣列，不依遊戲模式、視線或實例參與篩選，也不依距離排序。
| 參數 | 類型 | 備註 |
|---|---|---|
range | number | 半徑(以方塊為單位) |
範例
return {
api_version = 1,
on_enter_combat = function(context)
local players = context.boss:get_nearby_players(30)
for _, p in ipairs(players) do
p:show_action_bar("&cThe boss sees you!")
end
end
}
boss:get_damager_count()
傳回 Boss 已記錄攻擊者對照表的目前大小。與 damager_count 欄位不同，這是即時讀取，但不代表附近或目前在線的戰鬥參與者人數。
boss:get_nearby_elites(radius)
傳回 Boss 同世界內最多 32 個存活且受追蹤的精英，排除 Boss 自身。半徑必須有限、大於 0 且不超過 64 個方塊。結果為生物實體包裝物，依距離排序，同距離以精英 UUID 決定順序。此查詢本身並不證明某個效果可以作用於所有結果。
boss:get_target_player()
以玩家包裝物的形式傳回 Boss 目前的怪物目標,若目標不是玩家或尚未設定,則傳回 nil。
區域與粒子方法
這些方法結合了區域與粒子效果。它們需要一個 zone 表作為輸入。
boss:get_nearby_players_in_zone(zone)
傳回 Boss 世界內符合原生區域形狀的玩家包裝物，不依遊戲模式或實例參與篩選。每次重新查詢，不是持續監測器。
| 參數 | 類型 | 備註 |
|---|---|---|
zone | zone 表 | 一個區域形狀定義 |
boss:spawn_particles_in_zone(zone, particle[, amount][, x][, y][, z][, speed][, coverage])
以粒子填滿區域內部。參數必須依位置傳入，此方法不接受規格表。
| 參數 | 類型 | 預設值 | 備註 |
|---|---|---|---|
zone | zone 表 | 使用原生 kind 格式的區域形狀；參閱區域與目標選取 | |
particle | string | 粒子類型名稱 | |
amount | number | 1 | 每個取樣位置的粒子數量 |
x, y, z | number | 0 | 擴散量；amount 為 0 時代表方向 |
speed | number | 0 | 粒子速度 |
coverage | number | 1.0 | 每個位置獨立的取樣機率，限制在 0.01 到 1.0；非空位置集合至少貢獻一個位置 |
boss:spawn_particles_in_zone_border(zone, particle[, amount][, x][, y][, z][, speed][, coverage])
與上一個方法相同，但取樣區域邊界而非內部位置。
boss:get_particles_from_self_toward_zone(zone, particle[, speed])
傳回位於區域取樣位置、方向遠離 Boss 的粒子規格表陣列。它不會在 Boss 位置生成粒子，也不會建立從那裡出發的移動動畫。請將結果傳給 boss:spawn_particles_with_vector(...)。
| 參數 | 類型 | 預設值 | 備註 |
|---|---|---|---|
zone | zone 表 | 目標區域 | |
particle | string | 粒子類型名稱 | |
speed | number | 0.1 | 粒子行進速度 |
每個項目的格式為 { location = ..., particle = ..., amount = 0, x/y/z = <unit direction>, speed = ... }。每個區域位置有 20% 的取樣機率，非空集合至少選擇一個位置；隨後略過與 Boss 重合的位置。實際方向行為取決於粒子類型。
boss:get_particles_toward_self(zone, particle, speed)
回傳從區域朝向 Boss 的粒子規格陣列，不會直接生成粒子。請將結果傳給 boss:spawn_particles_with_vector(...)。
| 參數 | 類型 | 預設值 | 備註 |
|---|---|---|---|
zone | zone 表 | 來源區域 | |
particle | string | 粒子類型名稱 | |
speed | number | 請明確傳入 0.1 等數值；省略時會嘗試將粒子名稱當作數字讀取，導致呼叫失敗。 |
boss:spawn_particles_with_vector(particles)
生成一個由方向性粒子組成的陣列,每個粒子各自擁有自己的位置與速度向量。
| 參數 | 類型 | 備註 |
|---|---|---|
particles | table 陣列 | 每個項目定義一個帶有位置與方向的粒子 |
終界龍方法
這些方法僅在 Boss 實體為終界龍(Ender Dragon)時適用。
boss:get_ender_dragon_phase()
以字串形式傳回目前的 EnderDragon.Phase 名稱,若 Boss 不是終界龍則傳回 nil。
boss:set_ender_dragon_phase(phase)
設定終界龍的階段。
| 參數 | 類型 | 備註 |
|---|---|---|
phase | string | EnderDragon.Phase 名稱(例如 "CIRCLING"、"CHARGE_PLAYER") |
特殊能力支援方法
這些方法可從 Lua 腳本支援 EliteMobs 內建的能力機制。
boss:start_tracking_fireball_system(speed?)
為 Monster 類型 Boss 上的此能力啟動一個控制器。怪物有目標時，控制器會在首次執行（下一個 tick）以及之後每 8 秒，向每個軸向 20 方塊範圍內的 Survival/Adventure 玩家發射追蹤火球。沒有目標的執行（包括首次執行）會停止控制器，再次呼叫可重啟。執行中重複呼叫不會取代速度。控制器屬於該能力的腳本：暫停腳本會暫停它，關閉腳本會停止它。此呼叫啟動控制器時，速度必須是有限正數，否則呼叫會引發錯誤。
火球爆炸威力為 3 且可點火。每顆火球的追蹤工作獨立於腳本。它會在約 3 分鐘後或情境無效時停止，但停止工作本身不移除火球。對受追蹤火球的未取消攻擊會讓它在玩家與施法者之間切換追逐目標。
| 參數 | 類型 | 預設值 | 備註 |
|---|---|---|---|
speed | number | 0.5 | 火球速度；必須是有限正數 |
boss:handle_spirit_walk_damage(cause)
將傷害原因傳給 Spirit Walk 方法。火焰、燃燒刻數、中毒、凋零、荊棘及橫掃攻擊不推進計數器。溺水或窒息立即觸發逃離；其他受理原因每第九次命中觸發。它尋找附近有效目的地，並在暫時無敵狀態下播放移動過程。不會取消傳入的傷害事件，也不保證移動到攻擊者背後。
| 參數 | 類型 | 備註 |
|---|---|---|
cause | string | Bukkit DamageCause 名稱(例如 "ENTITY_ATTACK"、"PROJECTILE") |
boss:shield_wall_is_active()
傳回護盾控制器的啟用旗標，不保證某個方向仍有正數護盾值。
boss:initialize_shield_wall(openingDirection?)
護盾牆尚未啟用時，初始化方向護盾值和顯示。每個受保護方向的初始生命值等於 Boss 等級。參數選擇未受保護的開口方向，不是充能次數。傳回 nil，不會自動註冊傷害事件處理器。
| 參數 | 類型 | 預設值 | 備註 |
|---|---|---|---|
openingDirection | number | 1 | 1 = 北，2 = 東，3 = 南，4 = 西；其他整數使四面都受保護 |
boss:shield_wall_absorb_damage(player, damage)
依攻擊者相對 Boss 的位置判定方向，從該方向護盾值減去指定傷害。減法前的值為正時傳回 true，即使本次傷害超過剩餘值。玩家或狀態缺失、位於其他世界、該方向已耗盡或為開口時傳回 false。不會取消傷害事件。 傳回 true 時，你的傷害鉤子必須呼叫 context.event.cancel_event() 才能阻止命中。請傳入非負傷害量。
| 參數 | 類型 | 備註 |
|---|---|---|
player | 玩家包裝物 | 進行攻擊的玩家 |
damage | number | 要吸收的傷害量 |
boss:deactivate_shield_wall()
停止護盾牆獨立的顯示工作，移除狀態和護盾盔甲座。僅關閉 Lua 實例不會呼叫此方法；機制結束時請明確停用。
boss:start_zombie_necronomicon(target, chant)
以生物實體目標和捲動咒文啟動 Necronomicon 控制器。第二個參數是顯示文字，不是 Boss 檔名。它以施法者等級，每 60 刻召喚一個固定檔案的援軍，80% 機率使用 necronomicon_zombie.yml，20% 使用 necronomicon_skeleton.yml。僅當受追蹤援軍不超過 9 個且沒有作用中控制器時接受新啟動。執行中的控制器補充至 11 個，滿員時啟用 AI，數量下降後恢復施法。
施法會停用 Boss AI 並變更顯示名稱，警告顯示遵守警告效果設定。目標必須保持有效、同世界且位於 30 方塊內。情境無效或擁有者移除會停止控制器、還原顯示並清除其援軍。這些是獨立 Bukkit 工作，僅關閉 Lua 不會停止。方法傳回 nil。
| 參數 | 類型 | 備註 |
|---|---|---|
target | 實體包裝物 | 死靈之書的目標實體 |
chant | string | 捲動顯示文字；空白文字使用 Boss 名稱，較短文字會補齊 |
context.players
以 Boss 為中心的玩家查詢輔助器。使用這些方法來尋找玩家,而無需從事件中取得特定的玩家。
這些查詢不依遊戲模式、視線、存活狀態、戰鬥參與或實例成員身分篩選，也不依距離排序。current_target() 優先使用事件行為者，可能不同於優先使用直接目標的 context.player。新建的排程情境沒有事件行為者，因此退回目前 Mob 目標。
| 方法 | 傳回 | 備註 |
|---|---|---|
players:current_target() | 玩家包裝物或 nil | 事件玩家,或當 Boss 的怪物目標為玩家時的該目標 |
players:nearby_players(radius) | 玩家包裝物的陣列 | Boss 半徑內的所有玩家 |
players:all_players_in_world() | 玩家包裝物的陣列 | Boss 所在世界中的所有玩家 |
範例
return {
api_version = 1,
on_enter_combat = function(context)
local nearby = context.players:nearby_players(20)
for _, player in ipairs(nearby) do
player:send_message("&cThe boss is enraged!")
player:apply_potion_effect("GLOWING", 60, 0)
end
end
}
範例
return {
api_version = 1,
on_spawn = function(context)
-- Warn everyone in the world
local everyone = context.players:all_players_in_world()
for _, p in ipairs(everyone) do
p:show_title("&4WARNING", "&7A world boss has spawned!", 10, 60, 20)
end
end
}
context.entities
以 Boss 為中心的一般實體查詢輔助器。
| 方法 | 傳回 | 備註 |
|---|---|---|
entities:get_nearby_entities(radius[, filter]) | 實體包裝物的陣列 | Boss 周圍的附近實體 |
entities:get_entities_in_box(center, halfX, halfY, halfZ[, filter]) | 實體包裝物的陣列 | 中心所在世界中，腳部位置位於包含邊界的方框內的生物實體；不是碰撞箱重疊檢查 |
entities:get_all_entities([filter]) | 實體包裝物的陣列 | Boss 所在世界中所有符合的實體 |
entities:get_direct_target_entity() | 實體包裝物或 nil | 目前事件的直接目標 |
entities:get_boss_spawn_location() | location 表 | Boss 原本的生成位置 |
有效的篩選條件: living(預設)、player / players、elite / elites、mob / mobs、all / entities
all / entities 僅在 get_nearby_entities 中生效。它包含掉落物和投射物等非生物實體，以輕量的參考包裝物傳回；生物實體仍使用完整的生物實體包裝物。此篩選條件以每軸取指定半徑的軸對齊方框搜尋，生物實體篩選條件使用球形距離。在其他查詢中，all / entities 退回為 living。所有結果都排除 Boss 自身。
篩選條件不區分大小寫，未知值也退回為 living。mob 指任何非玩家生物實體，不只是敵對怪物。這些查詢沒有自動的實例參與者篩選、結果數上限或距離排序。廣泛的生物實體查詢會掃描世界中已載入的生物實體，請限制半徑並避免不必要的重複掃描。get_direct_target_entity() 使用事件直接目標，可能為 nil，不會退回怪物目前戰鬥目標。
範例
return {
api_version = 1,
on_enter_combat = function(context)
-- Damage all nearby elites
local elites = context.entities:get_nearby_entities(10, "elites")
for _, elite in ipairs(elites) do
elite:deal_damage(5)
end
end
}
範例
return {
api_version = 1,
on_enter_combat = function(context)
-- Find players in a box area
local center = context.boss:get_location()
local players = context.entities:get_entities_in_box(center, 10, 5, 10, "players")
for _, p in ipairs(players) do
p:send_message("&eYou are in the danger zone!")
end
end
}