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	若为生命值乘数大于 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 上配置的生命值乘数(普通精英为 1.0)
`entity.elite.damage_multiplier`	number	自定义 Boss 上配置的伤害乘数(普通精英为 1.0)
`entity.elite:remove()`	方法	移除精英(使用 `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()`

返回实体当前的速度作为向量表。

示例

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`	淡入刻数
`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`	向量表	`{ 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`	向量表		方向与强度
`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`	向量或 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
}

警告

remove_potion_effect(effect) 在 EliteMobs Lua 技能中不可用。它仅存在于 Magmacore/FMM 中。可使用 apply_potion_effect 并将持续时间设为 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
    -- 当玩家命中 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)
    -- 在战斗开始时禁用 Boss AI 3 秒
    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 变为两倍大小持续 5 秒
    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
    -- 短暂禁用玩家重力,3 秒后重新启用
    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!")
    -- 5 秒后重置
    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`	移除前的刻数
`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`	表	`{}`	可选设置(见下文)

选项表:

键	类型	默认值	备注
`enchantments`	表数组	`nil`	每项:`{ type = "SHARPNESS", level = 2 }`
`unbreakable`	boolean	`false`	物品是否不可破坏

示例

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- 给 Boss 一把闪光的钻石剑
    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 是非生命引用包装器;如果 5 秒后仍存活则将其移除
    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 等)。玩家包装器包含上面列出的每个通用实体字段与方法,以及下面的附加项。

警告

在没有关联玩家的钩子中(例如 on_spawn、调度回调和计时器钩子),context.player 为 nil。使用前请始终进行 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()`

返回 Boss 当前的实时位置作为 location 表。

示例

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`	向量表	`{ x, y, z }` 或 `{ x = 0, y = 1, z = 0 }`

示例

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Boss 在战斗开始时跃入空中
    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`	向量或 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`	表	`{}`	见下方选项

选项表:

键	类型	备注
`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[, duration])`

从配置文件召唤一个增援 Boss。

参数	类型	备注
`filename`	string	Boss 配置文件名
`zoneOrLocation`	location 表或 zone	生成位置或 zone 定义
`duration`	number	可选,在此刻数后自动消失

示例

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`	表数组	每项定义一个带位置和方向的粒子

末影龙方法

这些方法仅在 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)`

为给定的伤害原因处理灵步(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)`

对某个目标启动僵尸死灵之书技能,从配置文件中生成亡灵增援。

参数	类型	备注
`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)
    -- 警告世界中的所有玩家
    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)
    -- 对所有附近的精英造成伤害
    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)
    -- 在盒形区域中查找玩家
    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: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)​