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_mount`	boolean	若此包裝物代表的是 Boss 坐騎則為 `true`
`entity.is_monster`	boolean	對怪物類型實體為 `true`
`entity.is_valid`	boolean	有效性快照旗標
`entity.health`	number	目前生命值(快照)
`entity.maximum_health`	number	最大生命值(快照)
`entity.current_location`	location 表	包裝物建立時的位置

若要讀取精英專屬的資料(例如 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
}

共通的實體方法

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

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

向實體發送一則動作列(action bar)訊息。

參數	類型	備註
`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`	淡入的刻數
`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 血條。

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

將實體傳送到某個位置。

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

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

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

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

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

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

對實體套用一個藥水效果。

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

警告

在 EliteMobs Lua 能力中並不提供 remove_potion_effect(effect)。它僅存在於 Magmacore/FMM 中。可以使用持續時間為 0 的 apply_potion_effect 作為變通方案,或是設計你的能力時不需要移除效果。

`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`	經過這麼多刻後自動還原

範例

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`	經過這麼多刻後自動還原

範例

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、可選的 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)`

讓實體執行一個指令。對於玩家,這會以該玩家的身分執行;使用指令文字時不要加上開頭的 /。

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

範例

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
    local player = context.player
    player:set_gravity(false)
    player:send_message("&dYou begin to float!")
    context.scheduler:run_after(60, function()
      if player:is_alive() then
        player:set_gravity(true)
      end
    end)
  end
}

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

在實體的位置播放一個音效。

參數	類型	預設值	備註
`sound`	string		Minecraft 音效鍵(例如 `"entity.ender_dragon.growl"`)
`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 或 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)`

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

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

範例

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

載具與乘客方法

生物實體包裝物也提供 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])`

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

參數	類型	預設值	備註
`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
    local player = context.player
    player:set_custom_name("&c&lMarked Target")
    player:send_message("&cYou have been marked!")
    -- Reset after 5 seconds
    context.scheduler:run_after(100, function()
      if player:is_alive() then
        player:reset_custom_name()
      end
    end)
  end
}

`entity:place_temporary_block(material[, duration][, 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()`

若實體目前站在堅實的地面上,則傳回 true。

`entity:is_frozen()`

若實體(當被追蹤為自訂 Boss 時)設定了凍結旗標,則傳回 true。

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

切換怪物的警覺性。僅影響怪物類型的實體。可選擇在一段時間後還原。

參數	類型	預設值	備註
`aware`	boolean		`true` 表示啟用警覺性
`duration`	number	`nil`	經過這麼多刻後自動還原

`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`	table	`{}`	可選設定(見下文)

Options 表:

Key	類型	預設值	備註
`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: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)`	設定方向(僅限 Fireball)
`set_yield(value)`	設定爆炸威力(僅限 Fireball)
`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`

可在直接涉及玩家的鉤子中使用(on_boss_damaged_by_player、on_player_damaged_by_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 包裝物繼承了上方所列的每一個共通實體方法(例如 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`	經過這麼多刻後自動還原

範例

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		Minecraft 音效鍵(例如 `"entity.wither.spawn"`)
`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][, follow][, timeout])`

使用尋路功能讓 Boss 走向某個位置。

參數	類型	預設值	備註
`location`	location 表		目的地
`speed`	number	`1.0`	移動速度倍率
`follow`	boolean	`false`	持續追隨目標
`timeout`	number	`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])`

向所有附近的玩家發送一則聊天訊息。

參數	類型	預設值	備註
`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`	table	`{}`	見下方選項

Options 表:

Key	類型	備註
`duration`	number	經過指定刻數後自動移除
`max_ticks`	number	監控落地的最大刻數
`custom_damage`	number	撞擊時的傷害
`detonation_power`	string	撞擊時的爆炸威力
`yield`	number	爆炸威力(Fireball)
`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][, level])`

從一個配置檔召喚一個援軍 Boss。

參數	類型	備註
`filename`	string	Boss 配置檔名稱
`zoneOrLocation`	location 表或 zone	可選的生成位置或區域定義。預設為 Boss 的位置。
`level`	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()`

將 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 表作為輸入。

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

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

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

`boss:handle_spirit_walk_damage(cause)`

針對指定的傷害原因處理靈魂行走(spirit walk)行為。靈魂行走會讓 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)`

在目標身上啟動殭屍死靈之書(zombie necronomicon)能力,從一個配置檔生成不死系援軍。

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

後續步驟

入門 | 鉤子與生命週期 | 世界與環境 | 區域與目標選取 | 範例 | 列舉 | 疑難排解
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:has_mount() / boss:get_mount()​

boss:set_mount(entity) / boss:clear_mount() / boss:dismount()​

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][, level])​

boss:despawn()​

boss:get_nearby_players(range)​

boss:get_damager_count()​

boss:get_target_player()​

區域與粒子方法​

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