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）和可选的副标题（subtitle）。
| 参数 | 类型 | 默认值 | 备注 |
|---|---|---|---|
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 | 着火持续时间（以 tick 为单位，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 中。可以使用持续时间为 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 | 经过这么多 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，可选 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
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 | 移除前的 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 进行追踪时）设置了冻结标志，则返回 true。
entity:set_awareness_enabled(aware[, duration])
切换怪物的感知（awareness）。仅影响怪物类型的实体。可选择在一段时间后恢复。
| 参数 | 类型 | 默认值 | 备注 |
|---|---|---|---|
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 | table | {} | 可选设置（见下文） |
options 表：
| 键 | 类型 | 默认值 | 备注 |
|---|---|---|---|
enchantments | 表的数组 | 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 | 经过这么多 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 | 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 | 经过这么多 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 | table | {} | 见下方选项 |
options 表：
| 键 | 类型 | 备注 |
|---|---|---|
duration | number | 在若干 tick 后自动移除 |
max_ticks | number | 监测落地的最大 tick 数 |
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 | 表的数组 | 每个条目定义一个带有位置和方向的粒子 |
末影龙方法
这些方法仅在 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)
在某个目标上启动僵尸死灵之书（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
}