Lua 腳本:Boss 與實體

本頁面涵蓋 EliteMobs Lua 能力中關於 Boss 與實體包裝物的所有內容:context.boss、context.player、context.players、context.entities,以及它們所傳回的實體包裝表。如果你是 Lua 能力的新手,請先從入門開始。

實體包裝物

當你透過 Lua API 存取實體——無論是來自 context.boss、context.player、查詢結果(例如 context.players:nearby_players())或事件欄位——你拿到的永遠是包裝表。這些並不是原始的 Bukkit 物件。每個包裝物提供一組欄位(在建立時擷取的快照值)與方法(每次呼叫都會深入伺服器的即時呼叫)。

兩條規則需牢記:

像 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_custom_boss`	boolean	若實體為自訂 BOSS(區域、實例等)則為 `true`
`entity.is_significant_boss`	boolean	對於 health multiplier 大於 1 的自訂 BOSS(即主要 BOSS,而非次要援軍)為 `true`
`entity.is_monster`	boolean	對怪物類型實體為 `true`
`entity.is_valid`	boolean	有效性快照旗標
`entity.health`	number	目前生命值(快照)
`entity.maximum_health`	number	最大生命值(快照)
`entity.current_location`	location 表	包裝物建立時的位置
`entity.elite`	表或 nil	僅限精英的子表;只在 `entity.is_elite` 為 `true` 且 EliteMobs 對該實體擁有精英資料時才存在。請見下方精英子表。

精英子表

當實體是 EliteMobs 精英時,包裝物會具有額外的 entity.elite 表,內含精英專屬的欄位與方法。在非精英身上此欄位不存在(nil)。

欄位 / 方法	類型	備註
`entity.elite.level`	number	精英的等級
`entity.elite.name`	string 或 nil	精英所設定的顯示名稱
`entity.elite.health`	number	目前生命值的快照(與 `entity.health` 相同)
`entity.elite.max_health`	number	最大生命值的快照(與 `entity.maximum_health` 相同)
`entity.elite.is_custom_boss`	boolean	精英是否為自訂 BOSS
`entity.elite.health_multiplier`	number	在自訂 BOSS 上設定的 health multiplier(一般精英為 1.0)
`entity.elite.damage_multiplier`	number	在自訂 BOSS 上設定的 damage multiplier(一般精英為 1.0)
`entity.elite:remove()`	method	移除精英(使用 `OTHER` 移除原因)。在腳本中用於乾淨的消失。

範例

return {
  api_version = 1,
  on_enter_combat = function(context)
    if context.boss.elite ~= nil then
      context.log:info("Boss level: " .. context.boss.elite.level)
      context.log:info("Health x" .. context.boss.elite.health_multiplier)
    end
  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
}

共通的實體方法

每個生物實體包裝物都支援這些方法。每個方法都會對伺服器執行一次即時呼叫。

`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)`

對實體傳送一條動作列訊息。

參數	類型	備註
`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])`

對實體傳送標題,以及可選的副標題。

參數	類型	預設	備註
`title`	string		標題文字
`subtitle`	string	`""`	副標題文字
`fadeIn`	number	`10`	淡入 tick 數
`stay`	number	`40`	停留 tick 數
`fadeOut`	number	`10`	淡出 tick 數

範例

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 條。

參數	類型	預設	備註
`title`	string		條形標題文字
`color`	string	`"WHITE"`	BarColor 值
`style`	string	`"SOLID"`	BarStyle 值
`duration`	number	`40`	以 tick 為單位的持續時間

範例

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)`

將實體傳送到一個位置。

參數	類型	備註
`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 tick)後施加一個速度推力。用於覆寫擊退。

參數	類型	預設	備註
`vector`	vector 表		方向與強度
`additive`	boolean	`false`	與既有速度相加,而非取代
`delay`	number	`1`	套用前的延遲 tick 數

範例

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)`

讓實體面向一個方向向量或位置。

參數	類型	備註
`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)`

將實體點燃指定時間。

參數	類型	備註
`ticks`	number	燃燒持續時間(20 tick = 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])`

為實體增加視覺凍結 tick(藍色覆蓋效果)。

參數	類型	預設	備註
`ticks`	number	`1`	凍結 tick 數

範例

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])`

對實體套用藥水效果。

參數	類型	預設	備註
`effect`	string		PotionEffectType 名稱
`duration`	number		持續時間(tick)
`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 Lua 能力中不可用。它只存在於 Magmacore/FMM。請將 apply_potion_effect 的 duration 設為 0 作為變通,或設計不需移除效果的能力。

`entity:deal_damage(amount)` / `entity:deal_custom_damage(amount)` / `entity:deal_damage_from_boss(amount)`

對實體造成傷害。有三種變體可用。

方法	備註
`deal_damage(amount)`	通用傷害來源
`deal_custom_damage(amount)`	使用 BOSS 的 `BossCustomAttackDamage`
`deal_damage_from_boss(amount)`	設定 BOSS 實體為傷害施加者

範例

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)`

治療實體至其最大生命值。

參數	類型	備註
`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	`nil`	經過這麼多 tick 後自動還原

範例

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。可選擇在持續時間後還原。

參數	類型	預設	備註
`enabled`	boolean		`true` 以啟用 AI
`duration`	number	`nil`	經過這麼多 tick 後自動還原

範例

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 追蹤,並持續存在於該實體的生命週期內。

方法	參數	備註
`add_tag(tag[, duration])`	string, optional number	新增標籤,可選擇在指定 tick 數後自動移除
`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)`

讓實體執行一個指令。對玩家而言,這以玩家身分執行;使用不帶前置 / 的指令文字。

參數	類型	備註
`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])`

設定實體的 generic_scale 屬性。可選擇在持續時間後還原為 1.0。

參數	類型	預設	備註
`scale`	number		縮放倍率
`duration`	number	`nil`	經過這麼多 tick 後自動還原

範例

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)`

切換實體的重力。

參數	類型	備註
`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
    -- Disable player gravity briefly and re-enable after 3 seconds
    context.player:set_gravity(false)
    context.player:send_message("&dYou begin to float!")
    context.scheduler:run_after(60, function()
      if context.player ~= nil and context.player:is_alive() then
        context.player:set_gravity(true)
      end
    end)
  end
}

`entity:play_sound_at_entity(sound[, volume][, pitch])`

在實體位置播放音效。

參數	類型	預設	備註
`sound`	string		Bukkit 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])`

在實體位置生成粒子。

參數	類型	預設	備註
`particleOrSpec`	string 或表		粒子名稱或規格表
`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)`

如果實體具有支援動畫的自訂模型,則播放自訂模型動畫。

參數	類型	備註
`name`	string	動畫名稱

範例

return {
  api_version = 1,
  on_enter_combat = function(context)
    context.boss:play_model_animation("attack_swing")
  end
}

`entity:push_relative_to(source[, strength][, xOffset][, yOffset][, zOffset])`

將實體推離某個來源位置或實體包裝物。

參數	類型	預設	備註
`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()`

設定或重置實體的自訂顯示名稱。支援顏色碼。

範例

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.player:set_custom_name("&c&lMarked Target")
    context.player:send_message("&cYou have been marked!")
    -- Reset after 5 seconds
    context.scheduler:run_after(100, function()
      if context.player ~= nil and context.player:is_alive() then
        context.player:reset_custom_name()
      end
    end)
  end
}

`entity:place_temporary_block(material[, duration][, requireAir])`

在實體目前的位置放置一個臨時方塊。

參數	類型	預設	備註
`material`	string		方塊材質名稱
`duration`	number	`0`	移除前的 tick 數
`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()`

如果實體目前站在堅固地面上,則傳回 true。

`entity:is_frozen()`

如果實體(在被追蹤為自訂 BOSS 時)設有 frozen 旗標,則傳回 true。

`entity:set_awareness_enabled(aware[, duration])`

切換怪物的察覺度。僅影響怪物類型的實體。可選擇在持續時間後還原。

參數	類型	預設	備註
`aware`	boolean		`true` 以啟用察覺
`duration`	number	`nil`	經過這麼多 tick 後自動還原

`entity:is_healing()` / `entity:set_healing(enabled)`

檢查或切換精英實體的治療狀態。

`entity:overlaps_box_at_location(center[, halfX][, halfY][, halfZ])`

若實體的邊界框與指定位置的軸對齊方框重疊,則傳回 true。

參數	類型	預設	備註
`center`	location 表		測試方框的中心
`halfX`	number	`0.5`	X 軸上的半寬
`halfY`	number	同 halfX	Y 軸上的半高
`halfZ`	number	同 halfX	Z 軸上的半寬

`entity:remove_elite()`

從 EliteMobs 追蹤中移除精英實體。如果實體是精英,這會適當地透過 EliteMobs 讓它消失。

`entity:set_custom_name_visible(visible)`

設定實體的自訂名稱是要永遠可見,或只在被看到時可見。

參數	類型	備註
`visible`	boolean	`true` 為永遠可見

`entity:set_equipment(slot, material[, options])`

設定實體上的裝備。

參數	類型	預設	備註
`slot`	string		裝備欄位:`"HEAD"`、`"CHEST"`、`"LEGS"`、`"FEET"`、`"HAND"`、`"OFF_HAND"`
`material`	string		材質名稱(例如 `"DIAMOND_SWORD"`、`"IRON_HELMET"`)
`options`	表	`{}`	選擇性設定(見下方)

Options 表:

鍵	類型	預設	備註
`enchantments`	array of tables	`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.is_ai_enabled`

一個方法,若實體目前啟用了 AI 則傳回 true。

範例

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、is_elite、current_location

方法:

方法	備註
`is_valid()`	即時有效性檢查
`get_location()`	目前即時位置
`get_velocity()`	目前速度向量
`is_on_ground()`	是否在地面上
`teleport_to_location(location)`	傳送實體
`set_velocity_vector(vector)`	設定速度
`set_direction_vector(vector)`	設定方向(僅火球)
`set_yield(value)`	設定爆炸威力(僅火球)
`set_gravity(enabled)`	切換重力
`detonate()`	引爆煙火實體
`remove()`	從世界移除實體
`unregister([reason])`	從實體追蹤器解除註冊

範例

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
    )
    -- 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`

可在玩家直接相關的 hook 中使用(on_boss_damaged_by_player、on_player_damaged_by_boss 等)。玩家包裝物包含上方所列的每個共通實體欄位與方法,以及下方的額外項目。

警告

context.player 在沒有相關玩家的 hook 中為 nil,例如 on_spawn、排程回呼與計時器 hook。使用前請務必做 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 包裝物。在每個 hook 中始終可用。

提示

BOSS 包裝物繼承了上方所列的每個共通實體方法(例如 push_relative_to、apply_push_vector、set_gravity、set_scale、set_invulnerable、spawn_particle_at_self、overlaps_box_at_location 等)。本節所記述的方法,要麼是 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 方法

`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。可選擇在持續時間後還原。

參數	類型	預設	備註
`enabled`	boolean		`true` 以啟用 AI
`duration`	number	`nil`	經過這麼多 tick 後自動還原

範例

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 傳送到一個位置。

參數	類型	備註
`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 至其最大生命值。

參數	類型	備註
`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		Bukkit 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 或表		粒子名稱或規格表
`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: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][, follow][, timeout])`

使用尋路將 BOSS 走到指定位置。

參數	類型	預設	備註
`location`	location 表		目的地
`speed`	number	`1.0`	移動速度倍率
`follow`	boolean	`false`	持續跟隨目標
`timeout`	number	`nil`	經過這麼多 tick 後取消導航

範例

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])`

向所有附近的玩家傳送一條聊天訊息。

參數	類型	預設	備註
`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])`

從 BOSS 發射一個類投射物的實體。

參數	類型	預設	備註
`entityType`	string		實體類型(例如 `"FIREBALL"`、`"ARROW"`)
`origin`	location 表		發射位置
`destination`	location 表		目標位置
`speed`	number	`1.0`	投射物速度
`options`	表	`{}`	見下方選項

Options 表:

鍵	類型	備註
`duration`	number	經過指定 tick 後自動移除
`max_ticks`	number	監控落地的最大 tick 數
`custom_damage`	number	撞擊時的傷害
`detonation_power`	string	撞擊時的爆炸威力
`yield`	number	爆炸威力(火球)
`persistent`	boolean	投射物是否持續存在(預設 `true`)
`effect`	string	生成時播放的 EntityEffect 名稱
`incendiary`	boolean	爆炸是否帶火
`gravity`	boolean	投射物是否受重力影響
`glowing`	boolean	發光效果
`invulnerable`	boolean	投射物是否無敵
`track`	boolean	是否追蹤目標
`spawn_at_origin`	boolean	在原點而非偏移處生成
`direction_only`	boolean	只使用方向,忽略目標
`on_land`	function	回呼 `(landing_location, spawned_entity)`

範例

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。

參數	類型	備註
`filename`	string	BOSS 設定檔的檔名
`zoneOrLocation`	location 表或 zone	生成位置或 zone 定義
`duration`	number	可選,經過指定 tick 後自動消失

範例

return {
  api_version = 1,
  on_enter_combat = function(context)
    context.boss:summon_reinforcement("my_minion.yml", context.boss:get_location(), 200)
    context.boss:send_message("&cMinions, come to my aid!")
  end
}

`boss:despawn()`

將 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.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_target_player()`

以玩家包裝物的形式傳回 BOSS 目前的怪物目標,如果目標不是玩家或未設定,則傳回 nil。

Zone 與粒子方法

這些方法將區域與粒子效果結合。它們需要一個 zone 表作為輸入。

`boss:get_nearby_players_in_zone(zone)`

傳回目前位於指定區域內的所有玩家的包裝物陣列。

參數	類型	備註
`zone`	zone 表	區域形狀定義

`boss:spawn_particles_in_zone(zone, particle, ..., coverage?)`

以粒子填滿區域內部。

參數	類型	備註
`zone`	zone 表	要填滿的區域形狀
`particle`	string	粒子類型名稱
`...`		額外的粒子參數
`coverage`	number(可選)	粒子密度覆蓋係數

`boss:spawn_particles_in_zone_border(zone, particle, ..., coverage?)`

以粒子描繪區域的邊界。

參數	類型	備註
`zone`	zone 表	要描邊的區域形狀
`particle`	string	粒子類型名稱
`...`		額外的粒子參數
`coverage`	number(可選)	粒子密度覆蓋係數

`boss:get_particles_from_self_toward_zone(zone, particle, speed?)`

生成由 BOSS 朝區域移動的方向性粒子。

參數	類型	預設	備註
`zone`	zone 表		目標區域
`particle`	string		粒子類型名稱
`speed`	number	`nil`	粒子移動速度

`boss:get_particles_toward_self(zone, particle, speed?)`

生成由區域朝 BOSS 移動的方向性粒子。

參數	類型	預設	備註
`zone`	zone 表		來源區域
`particle`	string		粒子類型名稱
`speed`	number	`nil`	粒子移動速度

`boss:spawn_particles_with_vector(particles)`

生成一個方向性粒子陣列,每個粒子都有自己的位置與速度向量。

參數	類型	備註
`particles`	array of tables	每個項目以位置與方向定義一個粒子

Ender Dragon 方法

這些方法僅在 BOSS 實體為終界龍時適用。

`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?)`

在 BOSS 上啟動追蹤火球 AI 系統。BOSS 會週期性地發射追蹤其目標的火球。

參數	類型	預設	備註
`speed`	number	`0.5`	火球速度

`boss:handle_spirit_walk_damage(cause)`

處理指定傷害原因的靈魂漫步行為。靈魂漫步使 BOSS 對某些傷害類型免疫,並傳送到攻擊者身後。

參數	類型	備註
`cause`	string	Bukkit `DamageCause` 名稱(例如 `"ENTITY_ATTACK"`、`"PROJECTILE"`)

`boss:shield_wall_is_active()`

如果 BOSS 目前具有啟用中的盾牆,則傳回 true。

`boss:initialize_shield_wall(charges?)`

在 BOSS 上啟用一個可吸收傳入傷害的盾牆。

參數	類型	預設	備註
`charges`	number	`1`	盾牌可吸收的攻擊次數

`boss:shield_wall_absorb_damage(player, damage)`

嘗試以盾牆吸收傷害。如果傷害被吸收則傳回 true,如果盾牆未啟用或已耗盡則傳回 false。

參數	類型	備註
`player`	玩家包裝物	進行攻擊的玩家
`damage`	number	要吸收的傷害量

`boss:deactivate_shield_wall()`

停用 BOSS 的盾牆,移除任何剩餘的次數。

`boss:start_zombie_necronomicon(target, file)`

在目標上啟動殭屍死靈書能力,從設定檔生成不死生物援軍。

參數	類型	備註
`target`	實體包裝物	死靈書的目標實體
`file`	string	召喚不死生物的 BOSS 設定檔名稱

`context.players`

以 BOSS 為中心的玩家查詢輔助工具。使用這些來尋找玩家,而不需要從事件中取得特定玩家。

方法	傳回	備註
`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

範例

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
}

下一步

入門 | Hooks 與生命週期 | 世界與環境 | 區域與目標 | 範例 | 列舉 | 疑難排解
API 參考 | 腳本引擎

實體包裝物
共通的實體欄位
- 精英子表
共通的實體方法
非生物實體參考包裝物
context.player
- 玩家專屬欄位
- 玩家專屬方法
context.boss
context.players
context.entities
下一步

實體包裝物​

共通的實體欄位​

精英子表​

共通的實體方法​

entity:is_alive()​

entity:get_location()​

entity:get_eye_location()​

entity:get_health() / entity:get_maximum_health()​

entity:get_velocity()​

entity:send_message(text)​

entity:show_action_bar(message)​

entity:show_title(title[, subtitle][, fadeIn][, stay][, fadeOut])​

entity:show_boss_bar(title[, color][, style][, duration])​

entity:teleport_to_location(location)​

entity:set_velocity_vector(vector)​

entity:apply_push_vector(vector[, additive][, delay])​

entity:face_direction_or_location(directionOrLocation)​

entity:set_fire_ticks(ticks)​

entity:add_visual_freeze_ticks([ticks])​

entity:apply_potion_effect(effect, duration[, amplifier])​

entity:deal_damage(amount) / entity:deal_custom_damage(amount) / entity:deal_damage_from_boss(amount)​

entity:restore_health(amount)​

entity:set_invulnerable(enabled[, duration])​

entity:set_ai_enabled(enabled[, duration])​

entity:add_tag(tag[, duration]) / entity:remove_tag(tag) / entity:has_tag(tag)​

entity:run_command(command)​

entity:set_scale(scale[, duration])​

entity:set_gravity(enabled)​

entity:play_sound_at_entity(sound[, volume][, pitch])​

entity:play_sound_at_self(sound[, volume][, pitch])​

entity:spawn_particle_at_self(particleOrSpec[, count])​

entity:spawn_particles_at_location(location, particle[, count])​

entity:play_model_animation(name)​

entity:push_relative_to(source[, strength][, xOffset][, yOffset][, zOffset])​

entity:set_custom_name(name) / entity:reset_custom_name()​

entity:place_temporary_block(material[, duration][, requireAir])​

entity:get_height()​

entity:is_on_ground()​

entity:is_frozen()​

entity:set_awareness_enabled(aware[, duration])​

entity:is_healing() / entity:set_healing(enabled)​

entity:overlaps_box_at_location(center[, halfX][, halfY][, halfZ])​

entity:remove_elite()​

entity:set_custom_name_visible(visible)​

entity:set_equipment(slot, material[, options])​

entity.is_ai_enabled​

非生物實體參考包裝物​

context.player​

玩家專屬欄位​

玩家專屬方法​

context.boss​

BOSS 欄位​

BOSS 方法​

boss:is_alive()​

boss:get_location()​

boss:get_eye_location()​

boss:set_ai_enabled(enabled[, duration])​

boss:teleport_to_location(location)​

boss:set_velocity_vector(vector)​

boss:restore_health(amount)​

boss:play_sound_at_self(sound[, volume][, pitch])​

boss:spawn_particle_at_self(particleOrSpec[, count])​

boss:play_model_animation(name)​

boss:face_direction_or_location(vectorOrLocation)​

boss:navigate_to_location(location[, speed][, follow][, timeout])​

boss:add_tag(tag[, duration]) / boss:remove_tag(tag) / boss:has_tag(tag)​

boss:send_message(message[, range])​

boss:summon_projectile(entityType, origin, destination[, speed][, options])​

boss:summon_reinforcement(filename, zoneOrLocation[, duration])​

boss:despawn()​

boss:get_nearby_players(range)​

boss:get_damager_count()​

boss:get_target_player()​

Zone 與粒子方法​

boss:get_nearby_players_in_zone(zone)​

boss:spawn_particles_in_zone(zone, particle, ..., coverage?)​

boss:spawn_particles_in_zone_border(zone, particle, ..., coverage?)​

boss:get_particles_from_self_toward_zone(zone, particle, speed?)​

boss:get_particles_toward_self(zone, particle, speed?)​

boss:spawn_particles_with_vector(particles)​