Lua API 参考

本参考介绍 MagmaCore、FreeMinecraftModels 和 EliteMobs 的 Lua 表及运行时上下文。共享表与 EliteMobs Boss 能力表的契约不同，请使用与你编写的脚本对应的章节。

大多数表方法同时接受 table.method(...) 与 table:method(...)。全局函数 em.create_*、em.zone.create_*、em.location.* 以及下文标明的 Boss 事件伤害设置器要求点号语法。共享实时字段在访问时解析；需要新值时请重新读取，不要赋值，否则会遮蔽查询。已保存在 Lua 变量中的位置或其他快照不会自行更新。

标明会处理颜色的方法使用共享的颜色代码语法，包括聊天、标题、状态栏、自定义名称和道具容器标题。

实体表

MagmaCore 的 entity 表是通用实体值的基础；Living Entity、Player 和 FreeMinecraftModels Prop 表都继承自它。

属性

字段	类型	说明
uuid	string	实体 UUID。
entity_type	string	小写的 Bukkit 实体类型。
is_valid	bool	实时的有效性值。
is_dead	bool	实时的死亡状态。
current_location	table/nil	实时的 {x, y, z, yaw, pitch, world} 位置。
world	string/nil	实时的世界名称。
is_player	bool	该实体是否为玩家。
is_hostile	bool	该实体是否实现了 Bukkit Monster。
is_passive	bool	该实体是否实现了 Bukkit Animals。
is_on_ground	bool	实时着地状态。
is_flying	bool	实时玩家飞行状态；其他实体类型为 false。
in_block	bool	仅箭矢：当前是否嵌入方块。
attachment_location	table/nil	包含嵌入箭矢当前位置的方块中心；未嵌入时为 nil。
attachment_block	table/nil	由活动附魔动作所拥有的箭矢实际击中的方块中心。没有有效的已记录嵌入命中，或箭矢移开、切换世界、其动作结束后，返回 nil。用于识别被击中的方块，并不提供可安全移动到的碰撞目的地。

方法

方法	参数	返回值	说明
teleport(location)	table	nil	传送到某个位置表。
remove()	—	nil	若实体仍然有效则移除它。
set_silent(enabled)	bool	nil	设置静默状态。
set_invulnerable(enabled)	bool	nil	设置无敌状态。
set_gravity(enabled)	bool	nil	设置重力状态。
set_glowing(enabled)	bool	nil	设置发光状态。
set_velocity(x, y, z)	number, number, number	nil	替换速度；分量必须有限。
set_fall_distance(distance)	number	nil	设置有限且非负的坠落距离。
set_shooter(uuid)	string	bool	仅抛射物：设置已解析且实现 Bukkit ProjectileSource 的实体。
set_direction(x, y, z)	number, number, number	nil	仅火球：设置有限且非零的飞行方向。
set_pickup(status)	string	nil	仅箭矢：ALLOWED、DISALLOWED 或 CREATIVE_ONLY。
can_receive_hostile_effect(actor_uuid)	string	bool	检查目标是否可接受该在线玩家的敌对效果；提供方可增加自己的战斗限制。
has_clear_movement_path(location)	table	bool	对同世界位移预检碰撞、世界边界和已加载区块。非玩家实体还会拒绝保护区域。不会实际移动实体。
movement_path_status(location)	table	string	返回 clear、blocked、protected 或 unavailable；protected 适用于非玩家实体。碰撞检查保守地扫描实体碰撞箱经过的体积。

玩家路径畅通不代表获准进入或战斗。实际移动仍受原有移动监听器约束，包括区域进入限制；单纯的建筑保护不会阻止玩家通行。

共享位置参数要求 x、y、z。省略世界或无法解析世界名时使用实体所在世界。单独的 em.location.* 查询要求已加载世界，缺少的坐标默认为零。移动预检和 can_receive_hostile_effect 都不会自动用于直接传送、速度或伤害调用。

can_receive_hostile_effect 要求有效在线玩家作为行为者，目标为同世界内有效、存活的非玩家实体。它拒绝盔甲架、无敌实体、带 NPC 标签的实体和已驯服动物。EliteMobs 可增加战斗授权限制。set_shooter、set_owner 中无效的 UUID，以及无效的拾取枚举名称，可能引发错误。

实体表：EliteMobs 增强

EliteMobs 增强器向共享表加入以下数据。跟踪标志和 elite 是否存在在建表时确定；只有标明实时的字段会在访问时刷新。FreeMinecraftModels 的可选 EliteMobs 适配器会补充精英信息，但不会加入 elite_player。

属性

字段	类型	说明
is_elite	bool	建表时 EliteMobs 是否在跟踪该实体。
is_custom_boss	bool	被跟踪的精英是否为自定义 Boss。
is_significant_boss	bool	是否为生命值倍率高于 1 的自定义 Boss。
elite	table/nil	嵌套的 EliteMobs 数据，仅在成功解析出精英时存在。
elite.level	int	精英等级快照。
elite.name	string/nil	精英显示名称快照。
elite.health	number	实时生命值。
elite.max_health	number	实时最大生命值。
elite.is_custom_boss	bool	该精英是否为自定义 Boss。
elite.health_multiplier	number	已配置的生命值倍率快照。
elite.damage_multiplier	number	已配置的伤害倍率快照。
elite_player	table/nil	仅玩家：存在 EliteMobs 玩家数据时按需解析的表。
elite_player.tier	number	从技能 XP 计算的玩家战斗层级，不刷新附魔查询。

方法

方法	参数	返回值	说明
elite.remove()	—	nil	通过 EliteMobs 移除流程移除该精英。

实体表：FreeMinecraftModels 增强

FreeMinecraftModels 增强器加入以下快照；建表时 is_modeled 为 true 才有 model。玩家专属值只出现在玩家表上。模型与权限方法在调用时查询底层对象。在 EliteMobs 脚本中，EliteMobs 可选的 FreeMinecraftModels 适配器会添加 is_modeled、is_prop 和 model，但不会添加 is_op 或 has_permission。

属性

字段	类型	说明
is_modeled	bool	FreeMinecraftModels 是否解析出一个带模型的实体。
is_prop	bool	该实体是否为以盔甲架为载体的 FreeMinecraftModels 道具。
model	table/nil	嵌套的模型数据，仅在带模型的实体上存在。
model.model_id	string/nil	模型蓝图标识符。
model.is_dynamic	bool	该带模型实体是否为动态实体。
is_op	bool	仅限玩家的服务器 OP 状态。

方法

方法	参数	返回值	说明
model.play_animation(name, blend?=false, loop?=false)	string, bool?=false, bool?=false	bool	返回是否接受播放，包括排队或被抑制的攻击请求；终止死亡状态拒绝播放。
model.stop_animations()	—	nil	清空待播放队列，并在可用时回到 idle；保留终止死亡状态。
model.remove()	—	nil	移除该带模型的实体。
has_permission(node)	string	bool	仅限玩家的权限检查。

生物实体表

MagmaCore 的 living entity 表继承 Entity Table 的每一个属性和方法。

属性

字段	类型	说明
health	number	实时生命值。
maximum_health	number	实时最大生命值。
name	string/nil	实时的 Bukkit 实体名称。
is_alive	bool	Bukkit 死亡状态的实时取反值。

方法

方法	参数	返回值	说明
damage(amount)	number	nil	造成 Bukkit 伤害。
push(x, y, z)	number, number, number	nil	立即向当前速度叠加向量。
set_facing(x, y, z)	number, number, number	nil	通过改变朝向的传送面向方向向量。
add_potion_effect(type, duration, amplifier)	string (PotionEffectType), int, int	nil	当类型可解析时添加一个药水效果。
remove_potion_effect(type)	string (PotionEffectType)	nil	当类型可解析时移除一个药水效果。
get_scale()	—	number	返回包含修饰器的有效缩放值，不可用时为 1.0。
set_scale(value)	number	nil	服务器支持时设置缩放属性的基础值。
set_ai(enabled)	bool	nil	启用或禁用生物实体 AI。
set_owner(player_uuid)	string	bool	将可驯服实体驯服给在线玩家，同时清除狼的愤怒。实体不支持或玩家不可用时为 false。
has_potion_effect(type)	string	bool	检查 Bukkit 药水效果名；无法解析名称时为 false。

玩家表

MagmaCore 的 player 表继承 Living Entity Table 的每一个属性和方法。

FreeMinecraftModels 还加入 is_holding_elitemobs_item(filename)。传入含 .yml 的完整 EliteMobs 物品文件名，例如 shroomwhispers_shears.yml。它检查主手物品的 EliteMobs 标签，不比较显示名称。空手、其他物品或不可用的 EliteMobs 集成均返回 false。

属性

字段	类型	说明
game_mode	string	小写的 Bukkit 游戏模式快照。

方法

方法	参数	返回值	说明
send_message(text)	string	nil	发送经过 MagmaCore 颜色解析器处理的文本。
chat(text)	string	nil	让玩家发送 Bukkit 聊天，包括以其身份执行斜杠开头的命令。文本会处理颜色。
get_held_item()	—	table/nil	返回主手 {type, amount, display_name} 快照，空手为 nil。type 大写，没有显示名称时使用材质名称。
consume_held_item(amount?=1)	int?=1	nil	排队减少执行时主手中的堆叠，不返回付款结果，也不锁定已检查的物品。请使用正数；负数不被拒绝，可能增加数量。
has_item(material, amount?=1)	string (Material), int?=1	bool	检测背包中是否含有所需数量。
get_target_entity(range?=50)	number?=50	table/nil	从眼部联合检测方块与实体，忽略液体、可通过方块和自身，实体射线半径为 0.5。
get_eye_location()	—	table	返回眼部位置。
get_look_direction()	—	table	返回单位 {x, y, z} 方向。
send_block_change(x, y, z, material, ticks?=-1)	int, int, int, string (Material), int?=-1	bool	排队发送客户端方块，并可在正数 ticks 后还原。true 表示接受排队；无效或不可放置材质为 false。
reset_block(x, y, z)	int, int, int	bool	排队为该玩家还原真实方块。
sleep(x, y, z)	number, number, number	nil	排队放置真实的 WHITE_BED 并尝试强制睡眠。醒来或断线后仅还原原始 BlockData，不保留方块实体内容。20 ticks 后首次检查，之后每 10 ticks 检查。
wake_up()	—	nil	排队在玩家睡眠时将其唤醒。
show_boss_bar(text, color?=WHITE, progress, ticks?=-1)	string, string (BarColor)?=WHITE, number, int?=-1	nil	替换当前实心 Boss 血条，并可在正数 ticks 后隐藏。进度限制在 0..1，无效颜色用 WHITE。进度仍是第三个参数；默认颜色需传 nil。
hide_boss_bar()	—	nil	移除玩家当前的 Lua Boss 血条。
show_action_bar(text, ticks?=-1)	string, int?=-1	nil	发送一次，或每 40 ticks 重复一次直到正数时长结束。
show_title(title, subtitle?="", fade_in, stay, fade_out)	string, string?="", int, int, int	nil	显示经过颜色处理的主标题与副标题。

UI 辅助方法排队执行 Bukkit 工作，并在宿主插件内嵌的 MagmaCore 副本中按玩家共享状态栏，不按脚本隔离：新的 show_boss_bar 会替换玩家当前的血条，新的 show_action_bar 会取消当前重复发送的动作栏。到期计时器只移除启动它的那个血条或动作栏，因此旧的到期不会再清除新的条目。这些计时器不属于脚本调度器。方块变化使用执行时玩家的世界，后续还原读取玩家当时的世界；跨世界后不要假定能在原世界还原。

世界表

MagmaCore 的世界表以 context.world 暴露，并持有建表时捕获的世界；Boss 能力继承后应用下文的覆盖。共享邻近查询使用轴对齐箱体，radius 是半尺寸，不是球半径。结果数组从 1 开始，不自动排除归属实体或游戏模式。

属性

字段	类型	说明
name	string	世界名称快照。

方法

方法	参数	返回值	说明
get_block_at(x, y, z)	int, int, int	string	返回小写的 Material 名称；未加载的区块不会被加载，此时返回 air。
set_block_at(x, y, z, material)	int, int, int, string (Material)	bool	排队放置方块；无效材质返回 false，排队任务会跳过未加载的区块。
get_highest_block_y(x, z)	int, int	int	返回最高方块的 Y 坐标。
spawn_particle(particle, x, y, z, count?=1, dx?=0, dy?=0, dz?=0, speed?=0)	string (Particle), number, number, number, int?=1, number?=0, number?=0, number?=0, number?=0	nil	生成粒子；无效名称不做任何事。
play_sound(sound, x, y, z, volume?=1, pitch?=1)	string (Sound), number, number, number, number?=1, number?=1	nil	播放已注册音效，或小写的带命名空间资源包音效键。
strike_lightning(x, y, z)	number, number, number	nil	降下闪电。
get_time()	—	int	以 tick 返回世界时间。
set_time(ticks)	int	nil	设置世界时间。
get_nearby_entities(x, y, z, radius)	number, number, number, number	table	返回附近的 Entity 或 Living Entity 表。
get_nearby_players(x, y, z, radius)	number, number, number, number	table	返回附近的 Player 表。
spawn_entity(type, x, y, z)	string (EntityType), number, number, number	table/nil	生成原版实体；未知枚举名为 nil，合法但不可生成的类型可能抛错。
raycast(from_x, from_y, from_z, dir_x, dir_y, dir_z, max_distance?=50, fluid_mode?=NEVER, blocks_only?=false, loaded_only?=false)	六个数字、number?、string?、bool?、bool?	table/nil	返回 hit_entity、hit_location、hit_block；液体模式为 NEVER、SOURCE_ONLY、ALWAYS。loaded_only 拒绝射线外接矩形内的未加载区块并返回 nil。
place_temporary_block(x, y, z, material, ticks?=0, require_air?=false)	int, int, int, string (Material), int?=0, bool?=false	bool	放置临时方块；无效材质或未加载区块返回 false。
drop_item(x, y, z, material, amount?=1)	number, number, number, string (Material), int?=1	table/nil	自然掉落一个物品并返回其 Entity Table；无效材质返回 nil。
spawn_firework(x, y, z, colors, type?=BALL, power?=1)	number, number, number, table, string (FireworkEffect.Type)?=BALL, int?=1	nil	使用 Bukkit Color 常量名排队生成烟花；若无法解析出任何颜色则默认为白色。
strike_lightning_at_location(location)	table	nil	在位置表所在世界降下闪电。
play_sound_at_location(location, sound, volume?=1, pitch?=1)	table, string (Sound), number?=1, number?=1	nil	播放已注册音效，或小写的带命名空间资源包音效键。
spawn_particle_at_location(location, particle, count?=1, dx?=0, dy?=0, dz?=0, speed?=0)	table, string (Particle), int?=1, number?=0, number?=0, number?=0, number?=0	nil	通过本表持有的世界生成粒子；传入同世界位置。
get_block_at_location(location)	table	string	返回小写材质名称；位置无效或区块未加载时返回 air。
set_block_at_location(location, material)	table, string (Material)	bool	在位置表所在世界排队放置方块。
place_temporary_block_at_location(location, material, ticks?=0, require_air?=false)	table, string (Material), int?=0, bool?=false	bool	在位置表所在世界放置临时方块。
get_highest_block_y_at_location(location)	table	int/nil	返回最高方块的 Y 坐标；位置无效时返回 nil。
terrain_impact_at_location(location, options?)	table, table?	table/nil	显示临时地形冲击视觉效果。选项：radius=4.5 (0.5–6)、intensity=1 (0–1)、duration_ticks=35 (1–200)、view_range=48 (1–96)、seed。返回句柄或 nil。
terrain_impact(x, y, z, options?)	number, number, number, table?	table/nil	在此世界的指定坐标显示相同的视觉效果。
impact.is_active()	—	bool	检查返回句柄的效果是否仍在运行；impact.id 是其字符串标识符。
impact.remove()	—	bool	移除正在运行的效果；效果已结束或移除失败时返回 false。
get_entity(uuid)	string	table/nil	从本世界已加载实体注册表解析有效实体。请使用有效 UUID 字符串。
block_is_passable(x, y, z)	int, int, int	bool/nil	返回方块可通过性；区块未加载或超出高度范围时为 nil。
location_is_protected(location)	table	bool	查询已注册的保护提供方；省略世界时使用本世界。
spawn_dust(location, count, red, green, blue)	table, int, int, int, int	nil	生成固定尺寸的 DUST，RGB 为 0～255，每轴散布 0.1；跳过未加载区块。使用本世界位置。

射线未命中时返回空表，命中字段为 nil。方块命中包含 hit_block = {x, y, z, material}，材质名小写。联合射线的实体半径是 0.5，不使用实体过滤器。loaded_only=true 检查整个外接矩形，即使未加载区块偏离实际路径也可能拒绝。不合法的液体名称会抛错。

共享粒子名称在查找前转为大写。这些位置方法没有粒子数据参数，因此需要数据的粒子可能抛错；RGB 粉尘请用 spawn_dust。最高方块查询与生成方法没有通用的区块加载保护。放置方块不会自动检查区域保护。true 不能证明排队的修改或 require_air 条件成功。

正数 ticks 的临时方块会保存原始 BlockData，并在计时器结束、区块或世界卸载，或插件关闭时还原。只有当该位置仍是这个临时方块时才会还原，因此之后的编辑不会被覆盖。在仍为临时方块的位置再次放置临时方块，会重新开始计时，并保留第一次保存的原方块。带有方块实体的方块（例如箱子和告示牌）、未加载区块中的方块，以及已被其他临时方块所有者占用的方块会被跳过。破坏临时方块不会掉落任何东西，并会结束跟踪且不还原；在该处放置方块同样会结束跟踪。非正数 ticks 会永久放置方块且不跟踪。这不是脚本级回滚机制。

共享世界的 EliteMobs 扩展

EliteMobs 在共享世界表（包括 NPC 脚本）上注册这些辅助方法，要求目标区块已加载。共享 spawn_boss_at_location 要求位置和等级；Boss 能力用后文的可选参数形式覆盖它。

方法	参数	返回值	说明
lightning_effect_at_location(location)	table	nil	使用 EliteMobs 闪电生成绕过机制显示不造成普通伤害的闪电。
spawn_npc_at_location(file, location)	string, table	table/nil	生成已配置 NPC，返回带 remove() 的句柄；生成无效时为 nil。
spawn_boss_at_location(file, location, level)	string, table, int	table/nil	生成已配置自定义 Boss，返回共享生物实体表；不可用时为 nil。

context.world：FreeMinecraftModels 追加内容

FreeMinecraftModels 在自己的 MagmaCore 世界表注册这些方法，供道具脚本通过 context.world 使用。EliteMobs 未启用或玩家无法解析时返回 false。战利品辅助方法在位置缺失或不可用时使用玩家位置。

方法

方法	参数	返回值	说明
start_elitemobs_transport(player, route_id)	player, string	bool	为同世界玩家启动已保存的 EliteMobs 运输路线；玩家或集成不可用时为 false。
drop_elitemobs_procedural_loot(player, level, location?)	table/string, int, table?	bool	为该玩家掉落一件程序化生成的 EliteMobs 物品；当程序化物品掉落被禁用时返回 false。
drop_elitemobs_random_loot(player, level, location?)	table/string, int, table?	bool	按给定等级为该玩家掷取 EliteMobs 战利品表。
drop_elitemobs_custom_loot(player, file, level, location?)	table/string, string, int, table?	bool	为该玩家掉落指定的 EliteMobs 自定义物品文件；当文件无法解析时返回 false。

player 参数接受玩家表、UUID 字符串或精确的玩家名称。location 参数接受位置表，或带有 current_location 的实体表。程序化战利品遵守 EliteMobs 的直接入包设置，溢出部分掉在玩家处，并非始终掉在请求的位置。

em 辅助表

MagmaCore 在任何钩子运行前全局公开此表。构造函数只建立数据，不注册监视、不加载世界、不验证完整形状。全局函数使用点号；返回的位置与区域方法也接受冒号，会修改并返回同一张表。区域设置器保留传入位置表的引用。

属性

辅助构造函数返回下列紧凑数据表。

字段	类型	说明
location.x	number	em.create_location 返回的 X 坐标。
location.y	number	em.create_location 返回的 Y 坐标。
location.z	number	em.create_location 返回的 Z 坐标。
location.world	string/nil	传给 em.create_location 时的世界名称。
location.yaw	number/nil	传给 em.create_location 时的 yaw。
location.pitch	number/nil	传给 em.create_location 时的 pitch。
vector.x	number	em.create_vector 返回的 X 分量。
vector.y	number	em.create_vector 返回的 Y 分量。
vector.z	number	em.create_vector 返回的 Z 分量。
zone.kind	string	sphere、dome、cylinder、cuboid、cone、static_ray、rotating_ray 或 translating_ray。
zone.radius	number/nil	球体、穹顶、圆柱或圆锥的半径。
zone.height	number/nil	圆柱高度。
zone.x	number/nil	立方体的 X 尺寸。
zone.y	number/nil	立方体的 Y 尺寸。
zone.z	number/nil	立方体的 Z 尺寸。
zone.length	number/nil	圆锥或射线的长度。
zone.thickness	number/nil	静态射线的粗细。
zone.point_radius	number/nil	旋转射线或平移射线的点半径。
zone.animation_duration	number/nil	旋转射线或平移射线的动画时长。
zone.origin	table/nil	由 set_center 或 set_origin 设置的位置。
zone.destination	table/nil	由 set_destination 设置的位置。

方法

方法	参数	返回值	说明
em.create_location(x, y, z, world?, yaw?, pitch?)	number, number, number, string?, number?, number?	table	返回一个位置表。
em.create_vector(x, y, z)	number, number, number	table	返回一个 {x, y, z} 向量表。
location.add(dx?=0, dy?=0, dz?=0)	number?=0, number?=0, number?=0	table	就地相加并返回同一个位置表。
em.zone.create_sphere_zone(radius)	number	table	返回带 set_center(location) 的球体定义。
em.zone.create_dome_zone(radius)	number	table	返回带 set_center(location) 的穹顶定义。
em.zone.create_cylinder_zone(radius, height)	number, number	table	返回带 set_center(location) 的圆柱定义。
em.zone.create_cuboid_zone(x, y, z)	number, number, number	table	返回带 set_center(location) 的立方体定义。
em.zone.create_cone_zone(length, radius)	number, number	table	返回带 set_origin(location) 和 set_destination(location) 的圆锥定义。
em.zone.create_static_ray_zone(length, thickness)	number, number	table	返回带起点和终点设置器的静态射线定义。
em.zone.create_rotating_ray_zone(length, point_radius, animation_duration)	number, number, number	table	返回带起点和终点设置器的旋转射线定义。
em.zone.create_translating_ray_zone(length, point_radius, animation_duration)	number, number, number	table	返回带起点和终点设置器的平移射线定义。
zone.set_center(location)	table	table	将中心设为 zone.origin 并返回同一个 zone 表。
zone.set_origin(location)	table	table	设置起点并返回同一个 zone 表。
zone.set_destination(location)	table	table	设置终点并返回同一个 zone 表。
em.location.is_in_dungeon(location)	table	bool	检测已注册的地下城区域，以及报告 dungeon 类型的归属方。
em.location.is_protected(location)	table	bool	检测内置的 WorldGuard/GriefPrevention 适配器以及插件注册的保护归属方。
em.location.owned_by(location, namespace)	table, string	bool	按插件命名空间检测归属关系。
em.location.owners(location)	table	table	返回归属方命名空间字符串数组。
em.location.kinds_at(location)	table	table	返回归属类型字符串数组。
em.location.has_kind(location, kind)	table, string	bool	检测某个归属类型。

em.location.* 要求已加载世界名称或 {name = ...}，不回退到归属者世界。无法解析世界时返回 false 或空数组，缺少坐标为零。归属命名空间区分大小写，类型不区分。归属本身不意味着地下城或保护。查询覆盖已注册提供方，而非自动覆盖所有插件；被查询区域适配器失败时按受保护处理。数组顺序不保证。

Mind 程序上下文

原生 Mind 回调使用此上下文，而非普通能力或 NPC 上下文。文件形式的行为程序也从 plugins/EliteMobs/behaviors/ 加载；参见 Boss 行为配置。EliteMobs 集成通过 EliteMindService 注册 ai.program 和 ai.module；放入普通 powers 目录不会注册 Mind 程序。

字段	类型	说明
tick, generation	number	当前游戏 tick 和运行时世代。
entity	table	行为主体的共享 Living Entity Table。
memory, perception, actuator, actions	table	下列服务，仅供当前回调使用。

方法	参数	返回值	说明
memory.get(key)	string	value/nil	读取已声明的记忆键。
memory.set(key, value, ttl_ticks?)	string, value, int?	nil	按配置类型设置已声明的记忆值，可选过期时间。
memory.forget(key)	string	nil	移除已声明的记忆值。
memory.contains(key)	string	bool	检查已声明的记忆值是否存在。
perception.current_target()	—	table/nil	以共享 Living Entity Table 返回当前目标。
perception.nearest_player(radius)	number	table/nil	返回范围内最近的玩家。
perception.can_see(entity_or_uuid)	table/string	bool	检查到生物实体的视线是否畅通。
perception.navigation()	—	table	返回 destination_active、navigation_in_progress、consecutive_stuck_ticks、可选的 destination，以及含 tick 和 position 的可选 last_progress。
actuator.move_to(location, speed?=1)	table, number?=1	bool	以有限正数速度请求导航到同一世界中的位置；寻路未启动时返回 false。
actuator.stop_moving()	—	nil	停止导航。
actuator.look_at(location)	table	nil	朝向指定位置。
actuator.jump()	—	nil	请求跳跃。
actuator.set_target(entity_or_uuid)	table/string	bool	设置生物目标；无法解析目标时返回 false。
actuator.clear_target()	—	nil	清除目标。
actuator.attack(entity_or_uuid)	table/string	bool	请求攻击；无法解析目标时返回 false。
actuator.stop_all()	—	nil	停止该行为所持控制权涵盖的移动、目标和攻击。
actions.request(identifier, payload?)	string, table?	string	请求语义动作并返回小写结果；载荷值支持标量、实体 UUID 表和 world/x/y/z 位置表。

服务表在每个回调首次访问时构建，随后复用。未声明的记忆键会抛错。actuator.set_target 或 actuator.attack 返回成功，表示已解析到存活目标且请求已转发，不代表导航或攻击已经完成。动作载荷支持上列值形式，不支持任意嵌套的 Lua 表。动作标识符必须是不超过 128 个字符的小写命名空间键；载荷最多包含 16 个条目，键为小写且不超过 64 个字符，字符串值限制为 256 个字符。除 stop_all 外的所有执行器方法以及 actions.request，都要求调用它们的行为持有对应的控制权，否则会抛错。传感器完全不能使用执行器或动作。用 Lua 编写的行为程序参见行为程序。

ai 全局表

MagmaCore 会在每个 Lua 环境中安装这个全局表。这些构造函数只会为收到的表打上标记；EliteMobs 会从行为程序文件中编译这些带标记的表。

字段	类型	说明
ai.controls.move, look, jump, target, attack, use_item, action	string	用于行为 controls 数组的控制权名称；use_item 没有对应的 Lua 执行器方法。

方法	参数	返回值	说明
ai.program(definition)	table	table	标记程序定义，包含 id、revision，以及可选的 modules、memories、sensors、behaviors、budget 和 runaway。
ai.module(definition)	table	table	标记模块定义，包含 id、revision，以及可选的 dependencies、memories、sensors 和 behaviors。
ai.sensor(definition)	table	table	标记传感器，包含 id、interval?=1 和 sense(c)。
ai.behavior(definition)	table	table	标记行为，包含 id、priority?=0、controls、can_start、can_continue、start、tick 和 stop(c, reason)。

context.mind_action：EliteMobs 能力钩子

在 on_mind_action(context) 中可用。钩子返回 "accepted"、"deferred" 或 "rejected"；系统按附加顺序访问能力，直到某个能力接受该动作。

字段	类型	说明
key	string	带命名空间的语义动作标识符。
payload	table	不可变 Java 请求的可变 Lua 副本；实体 UUID 是字符串，位置是表。修改副本不会改变原请求。
game_tick, generation	number	动作 tick 和运行时世代。

context.state

每个 MagmaCore 脚本实例都会收到一张普通 Lua 表，它在该实例的生命周期内持续存在。可用于计数器、标志位、任务 ID，以及在各钩子之间共享的值。

context.state.counter = (context.state.counter or 0) + 1

context.log

MagmaCore、FreeMinecraftModels 与 EliteMobs NPC 方法

方法	参数	返回值	说明
info(message)	string	nil	以共享的 Lua 前缀记录一条信息性消息。
warn(message)	string	nil	记录一条警告。
error(message)	string	nil	通过共享的警告通道记录。

EliteMobs Boss 能力方法

方法	参数	返回值	说明
info(message)	string	nil	记录一条 Boss 能力的信息性消息。
warn(message)	string	nil	记录一条警告。
debug(message)	string	nil	以 Lua 能力调试前缀记录一条信息性消息。

context.scheduler

计划任务归属于脚本实例，并在实例关闭时被取消。下面两套命名系列在共享的 MagmaCore 接口和 EliteMobs Boss 能力上都可用。

方法	参数	返回值	说明
run_later(ticks, callback)	int, function	int	延迟后运行一次，并返回 Bukkit 任务 ID。
run_repeating(delay, interval, callback)	int, int, function	int	在初始延迟之后重复运行，并返回任务 ID。
cancel(task_id)	int	nil	取消一个自己拥有的任务。
run_after(ticks, callback)	int, function	int	run_later 的别名。
run_every(interval, callback)	int, function	int	无初始延迟地重复运行，并返回任务 ID。
cancel_task(task_id)	int	nil	cancel 的别名。

回调收到新上下文，通常没有事件或玩家。应提前捕获所需值或 UUID，不要保留包含延迟解析字段的旧上下文。到期的一次性任务在暂停时等待，重复任务跳过暂停 tick 且不补跑。回调错误会关闭脚本。取消自有任务不会撤销任意世界/实体修改或独立的 UI 计时器。

context.cooldowns

本地存储属于 ScriptableEntity 适配器。FreeMinecraftModels 每个道具脚本各建一个，EliteMobs NPC 则所有脚本共用一个，因此同 NPC 的命名本地键会冲突。全局值由同一道具或 NPC 共享。省略本地键时用 __lua: 加文件名；命名键精确匹配。Boss 能力共享 Boss 的本地存储与内置全局能力冷却。

共享本地/全局冷却以及 Boss 本地冷却按真实经过时间计量，每个请求 tick 为 50ms，暂停或低 TPS 时仍继续。Boss 全局冷却按服务器 tick 计数，并保留较晚的到期时间：较短的 set_global 永远不会缩短正在生效的全局冷却，非正数时长不起作用。检查或设置本地冷却不会自动检查或设置全局冷却。

方法	参数	返回值	说明
local_ready(key?)	string?	bool	检测所键控的本地冷却是否就绪。
local_remaining(key?)	string?	int	返回剩余 tick 数；已就绪时返回 0。
check_local(key, duration)	string/nil, int	bool	若已就绪则启动冷却并返回 true。传入 nil 以使用默认键。
set_local(duration, key?)	int, string?	nil	设置或清除本地冷却；非正数时长会清除它。
global_ready()	—	bool	检测归属方的全局冷却是否就绪。
set_global(duration)	int	nil	以 tick 设置全局冷却。在共享的 MagmaCore 接口上，非正数时长会清除它。

context.zones：共享的 MagmaCore 接口

FreeMinecraftModels 脚本、EliteMobs NPC 脚本以及其他默认的 MagmaCore 消费者会在当前脚本归属方所在的世界中收到整数型区域句柄。

方法	参数	返回值	说明
create_sphere(x, y, z, radius)	number, number, number, number	int/nil	注册一个球体并返回其句柄；归属方没有世界时返回 nil。
create_cylinder(x, y, z, radius, height)	number, number, number, number, number	int/nil	注册一个圆柱并返回其句柄；归属方没有世界时返回 nil。
create_cuboid(x, y, z, x_size, y_size, z_size)	number, number, number, number, number, number	int/nil	注册一个立方体并返回其句柄；归属方没有世界时返回 nil。
watch(handle, on_enter?, on_leave?)	int, function?, function?	bool/nil	为一个已知句柄启用边界跟踪。函数是否存在决定是否启用对应的 on_zone_enter 或 on_zone_leave 钩子；传入的函数体本身不会被直接调用。
unwatch(handle)	int	nil	停止跟踪并移除该句柄。

通用监视测试玩家位置点。此路径的长方体尺寸是半尺寸（Z 为零时用非零 X），不保证与 EliteMobs 实体重叠或采样点查询体积一致。区域保留创建时坐标和世界，但每 tick 扫描归属者当前世界中的玩家。通用区域钩子通过 context.player 和 context.event.player 暴露跨越边界的玩家。

创建即开始成员跟踪，早于 watch 安装钩子分发器。稍后安装监视不会为已记录在内部的玩家补发进入通知。第二次 watch 省略某个回调不会清除旧分发器。断线和 unwatch 不保证离开钩子。区域检查先于 on_game_tick。

context.event：共享的 MagmaCore 接口

当共享钩子存在当前 Bukkit 事件或行为者时，这张表才存在。计划回调以及两者皆无的钩子中不存在这张表。

字段或方法	类型	说明
is_cancelled	bool	首次解析事件子表时捕获的取消状态；cancel() 或 uncancel() 不会刷新它。
cancel()	method	取消当前事件。仅当事件实现了 Bukkit Cancellable 时存在。
uncancel()	method	撤销当前事件的取消。仅当事件实现了 Bukkit Cancellable 时存在。
player	table	当前行为者可用时，为其提供的 Living Entity Table。

通用区域钩子提供行为者但没有可取消的 Bukkit 事件，因此它们暴露 is_cancelled = false 和 player，但没有 cancel() 或 uncancel()。

context.item

附魔动作脚本在捕获来源具有槽位和物品时暴露此表。它只针对该槽位，将当前物品的材质与元数据和快照比较，忽略损伤值和数量。它不搜索背包，也不跟踪唯一物品身份；同槽位的等价替代品同样匹配。已消耗弹药可能为 nil。这独立于已停用的 FreeMinecraftModels 装备物品运行时。

方法	参数	返回值	说明
get_durability()	—	table/nil	剩余耐久 {current, max}；不可用或无耐久物品为 nil。
get_durability_percentage()	—	number/nil	剩余耐久除以材质最大值，通常为 0..1；外部超额损伤元数据可能使其超出范围。
use_durability(amount, can_break?=false)	int, bool?	bool	修改损伤，负数为修复。默认保留至少一点耐久，can_break=true 可消耗整叠。
use_durability_percentage(fraction, can_break?=false)	number, bool?	bool	按同样损坏规则施加 ceil(max_durability * fraction) 损伤。
consume(amount)	positive int	bool	仅在数量足够时从捕获堆叠中消耗。

耐久使用材质最大值，而非自定义最大损伤组件。这些直接修改不应用原版磨损计算、Unbreaking、不可破坏检查或玩家物品损伤事件。比例必须有限且结果在整数范围内；负比例会修复。损坏会消耗整个捕获堆叠。生命周期与完整上下文见自定义附魔。

context.prop

FreeMinecraftModels 道具脚本会收到这张表；当存在承载实体时，它继承 MagmaCore 的 Entity Table。

属性

字段	类型	说明
model_id	string/nil	模型蓝图名称；不存在蓝图时为 nil。
current_location	table/nil	实时的道具位置。

方法

方法	参数	返回值	说明
play_animation(name, blend?=true, loop?=true)	string, bool?=true, bool?=true	bool	播放指定名称的动画。
stop_animation()	—	nil	清空排队播放，并在可用时回到 idle；保留终止死亡状态。
hurt_visual()	—	nil	播放红色染色受伤特效但不造成伤害。
pickup()	—	nil	排队永久移除并掉落一个放置物品。
has_mount_points()	—	bool	检测该道具是否具有骑乘点骨骼。
mount(player)	table	bool	排队让已解析的玩家骑乘到第一个可用座位上。
dismount(player)	table	bool	排队让已解析的玩家从该道具上下来。
get_passengers()	—	table	返回已骑乘玩家的 Entity Table。
spawn_elitemobs_boss(file, x, y, z)	string, number, number, number	table/nil	当 EliteMobs 已启用时生成一个 EliteMobs 自定义 Boss。
open_inventory(player, title, rows?=3)	table, string, int?=3	bool	排队打开持久化存储，rows 钳制在 1 到 6 之间。
place_book(player)	table	bool	当道具尚未存放书本时，排队存入一本手持的成书或书与笔。
read_book(player)	table	bool	排队打开已存放的成书。
take_book(player)	table	bool	排队把已存放的书本归还给玩家。
has_book()	—	bool	检测该道具是否存放着书本。
drop_inventory()	—	bool	排队清空持久化存储并掉落其中的物品。
drop_book()	—	bool	排队清空并掉落已存放的书本。
is_viewing_inventory(player)	table	bool	检测该玩家是否正在查看此道具所跟踪的容器界面。
set_persistent_data(key, value)	string, string	bool	在道具范围内的 fmm_lua_ 键下存储一个字符串。
get_persistent_data(key)	string	string/nil	返回已存储的字符串，或 nil。

对于排队道具操作，true 只说明初始玩家/承载实体检查通过，不保证有座位、存书成功或界面已打开。take_book 在加入背包前先删除存储，也不会掉落溢出物品。同一道具的所有查看者共享同一个实时容器，在最后一名查看者关闭时保存；容器打开期间，后续调用会沿用其标题和大小。存储内容超过请求行数时，会按存储时的大小打开，因此不会丢弃任何槽位。道具数据存于承载盔甲架，回收时新生成的放置物品不保证保留这些数据。

在 on_projectile_hit 中，道具脚本还会收到 context.projectile，即弹射物的共享 Entity Table。如果其他插件已经取消了这次命中，该钩子不会触发。context.event 包装可取消的 FreeMinecraftModels 命中事件；当射击者是生物实体（包括怪物）时，context.event.player 就是射击者；只有当玩家发射弹射物时才会设置 context.player。

context.npc

EliteMobs NPC 脚本继承共享的 MagmaCore 上下文，并追加这张 NPC 专属表。

属性

字段	类型	说明
name	string	已配置的 NPC 显示名称。
filename	string	NPC 配置文件名。
uuid	string	运行时 NPC UUID。
activation_radius	number	已配置的激活半径。
current_location	table	位置快照，仅在承载的生物实体存在时出现。
entity_type	string	大写的 Bukkit 实体类型，仅在承载的生物实体存在时出现。

方法

方法	参数	返回值	说明
is_valid()	—	bool	检测该 NPC 是否有效。
remove()	—	nil	通过管理该 NPC 的生命周期移除它。
get_location()	—	table	返回当前 NPC 位置，回退到其出生位置。该表还包含一个 direction 向量。
get_eye_location()	—	table	返回当前眼部位置，回退到出生位置。该表还包含一个 direction 向量。
get_activation_radius()	—	number	返回当前已配置的激活半径。
get_nearby_players(radius)	number	table	返回同世界内距 NPC 脚部三维半径内的玩家，不过滤游戏模式。
face_direction_or_location(target)	table	nil	面向向量或同世界位置；巡逻移动活跃时忽略。
say_greeting(player?)	table/string?	nil	发送已配置的问候语，可用时默认发给触发的玩家。接受玩家表、UUID 或名称。
say_dialog(player?)	table/string?	nil	以相同的玩家解析方式发送已配置的对话。
say_farewell(player?)	table/string?	nil	以相同的玩家解析方式发送已配置的告别语。
play_model_animation(name)	string	nil	当存在自定义模型时播放模型动画。
patrol_pause()	—	bool	暂停已配置的巡逻。
patrol_resume()	—	bool	在脚本等待或临时移动后恢复巡逻。
walk_to(x, y, z)	number, number, number	bool	走到相对于原点的偏移并恢复巡逻。
hold(x, y, z)	number, number, number	bool	走到偏移位置并停留。
teleport(x, y, z)	number, number, number	bool	传送到进行实体 tick 的偏移位置。

EliteMobs 能力位置表

EliteMobs Boss 能力表通过 get_location()、get_eye_location()、current_location 及其他位置结果返回这种位置结构。缺失的位置会返回空表。

属性

字段	类型	说明
x, y, z	number	坐标。
yaw, pitch	number	朝向。
world	string/nil	位置带有世界时的世界名称。
direction	table	单位朝向向量 {x, y, z}。

方法

方法	参数	返回值	说明
add(dx?=0, dy?=0, dz?=0)	number?=0, number?=0, number?=0	table	就地增加坐标并返回同一张表；direction 不会更新。

EliteMobs 能力实体引用表

对于抛射物、烟花、下落方块等非生物实体，EliteMobs Boss 能力方法会返回这张轻量表。

属性

字段	类型	说明
name	string	实体名称快照。
uuid	string	实体 UUID。
entity_type	string	大写的 Bukkit 实体类型快照。
is_player	bool	恒为 false。
is_elite	bool	恒为 false。
is_mount	bool	除非某个 Boss 将返回的坐骑表标记为 true，否则为 false。
current_location	table	位置快照。

方法

方法	参数	返回值	说明
is_valid()	—	bool	检测实时有效性。
get_location()	—	table	返回实时位置。
get_velocity()	—	table	返回实时速度。
is_on_ground()	—	bool	检测实时的着地状态。
teleport_to_location(location)	table	nil	当位置可解析时传送。
set_velocity_vector(vector)	table	nil	当向量可解析时设置速度。
set_direction_vector(vector)	table	nil	适用时设置火球方向。
set_yield(amount)	number	nil	适用时设置火球威力。
set_gravity(enabled)	bool	nil	设置重力。
detonate()	—	nil	当实体为烟花时引爆。
remove()	—	nil	移除该实体。
unregister(reason?=OTHER)	string?=OTHER	nil	使用 DEATH、PHASE_BOSS_RESET、PHASE_BOSS_PHASE_END、CHUNK_UNLOAD、WORLD_UNLOAD、SHUTDOWN、EFFECT_TIMEOUT、BOSS_TIMEOUT、NPC_TIMEOUT、OTHER、UNSPECIFIED_WATCHDOG_REMOVAL、REMOVE_COMMAND、KILL_COMMAND、REINFORCEMENT_CULL、ENTITY_REPLACEMENT 或 ARENA_RESET 注销。
is_inside_vehicle()	—	bool	检测该实体是否正在乘坐载具。
has_vehicle()	—	bool	检测是否存在载具。
get_vehicle()	—	table/nil	返回当前载具引用。
set_vehicle(vehicle)	table	bool	让该实体乘坐已解析的载具。
leave_vehicle()	—	bool	离开当前载具。
has_passengers()	—	bool	检测是否存在乘客。
get_passenger_count()	—	int	返回乘客数量。
get_passengers()	—	table	返回乘客引用。
add_passenger(passenger)	table	bool	添加已解析的乘客。
remove_passenger(passenger)	table	bool	移除已解析的乘客。
eject_passengers()	—	bool	弹出每一位乘客。

EliteMobs 能力生物实体表

EliteMobs Boss 能力的生物值使用这张独立的表；Boss 表和 EliteMobs Power Player 表都继承它。

属性

字段	类型	说明
name	string	实体名称快照。
uuid	string	实体 UUID。
entity_type	string	大写的 Bukkit 实体类型快照。
is_player	bool	该实体是否为玩家。
is_monster	bool	该实体是否实现了 Bukkit Monster。
is_elite	bool	EliteMobs 是否在跟踪该实体。
is_mount	bool	被跟踪的自定义 Boss 是否为坐骑。
is_valid	bool	有效性快照。
health	number	生命值快照。
maximum_health	number	最大生命值快照。
current_location	table	位置快照。

方法

方法	参数	返回值	说明
is_alive()	—	bool	检测实时的有效性与死亡状态。
is_ai_enabled()	—	bool	返回实时的 AI 状态。
is_frozen()	—	bool	返回 EliteMobs 自定义 Boss 的冻结设置，或 false。
get_location()	—	table	返回实时位置。
get_eye_location()	—	table	返回实时眼部位置。
get_height()	—	number	返回 Bukkit 实体高度。
get_health()	—	number	返回实时生命值。
get_maximum_health()	—	number	返回实时最大生命值。
get_velocity()	—	table	返回实时速度。
deal_damage(amount)	number	nil	造成通用的 Bukkit 伤害。
deal_custom_damage(amount)	number	nil	从 Boss 向生物目标提交原始自定义伤害；会跳过 Boss 自身、无敌或已死亡的目标，以及不处于生存/冒险模式的玩家。仍受实例规则及伤害事件取消影响。
deal_damage_from_boss(amount)	number	nil	造成归因于该能力所属 Boss 的 Bukkit 伤害。
restore_health(amount)	number	nil	被跟踪时通过 EliteMobs 治疗，否则将 Bukkit 生命值钳制到上限。
play_sound_at_entity(sound, volume_or_options?=1, pitch?=1)	string (Sound), number/table?=1, number?=1	nil	在该实体处播放已注册音效或自定义命名空间音效。第二个参数也可以改为 {volume, pitch}。
play_sound_at_self(sound, volume_or_options?=1, pitch?=1)	string (Sound), number/table?=1, number?=1	nil	在该实体处播放的别名。第二个参数也可以改为 {volume, pitch}。
spawn_particle_at_self(particle, count?=1)	string (Particle)/table, int?=1	nil	在该实体处生成粒子字符串或粒子规格表。
spawn_particles_at_location(location, particle, count?=1, dx?=0, dy?=0, dz?=0, speed?=0)	table, string (Particle), int?=1, number?=0, number?=0, number?=0, number?=0	nil	在某个位置生成粒子。
teleport_to_location(location)	table	nil	当位置可解析时传送。
set_velocity_vector(vector)	table	nil	当向量可解析时设置速度。
set_gravity(enabled)	bool	nil	设置重力。
is_on_ground()	—	bool	检测实时的着地状态。
apply_push_vector(vector, additive?=false, delay?=1)	table, bool?=false, int?=1	nil	延迟之后施加速度，可选择叠加到当前速度之上。
set_custom_name(name)	string	nil	设置经颜色处理的自定义名称。
reset_custom_name()	—	nil	被跟踪时还原 EliteMobs 名称，否则还原 Bukkit 名称。
set_custom_name_visible(visible)	bool	nil	设置自定义名称的可见性。
set_ai_enabled(enabled, duration?=0)	bool, int?=0	nil	以归属修改的形式设置 AI；正数 ticks 后恢复被替换的值。传入 true 时，若该能力有生效中的 AI 修改，会结束该修改，而不是应用新值。
set_awareness_enabled(enabled, duration?=0)	bool, int?=0	nil	以归属修改的形式设置怪物感知；正数 ticks 后恢复被替换的值。传入 true 时，若该能力有生效中的感知修改，会结束该修改，而不是应用新值。
face_direction_or_location(target)	table	nil	面向某个向量或同世界的位置。
play_model_animation(name)	string	nil	可用时播放自定义模型动画。
set_scale(scale, duration?=0)	number, int?=0	nil	以归属修改的形式设置基础缩放；正数 ticks 后恢复被替换的值。
set_invulnerable(enabled, duration?=0)	bool, int?=0	nil	以归属修改的形式设置无敌状态；正数 ticks 后恢复被替换的值。
remove_elite()	—	nil	通过 EliteMobs 移除流程移除被跟踪的精英。
is_healing()	—	bool	检测被跟踪精英的治疗状态。
set_healing(enabled)	bool	nil	true 会在被跟踪精英尚未处于治疗状态时将其标记为治疗中；false 只清除该能力设置的治疗状态。能力关闭时会清除它仍持有的治疗状态。
navigate_to_location(location, speed?=1, force?=false, timeout?=0)	table, number?=1, bool?=false, int?=0	nil	让被跟踪的自定义 Boss 寻路。
add_tag(tag, duration?=0)	string, int?=0	nil	添加一个标签，并在正数 ticks 之后移除。
remove_tag(tag)	string	nil	移除一个标签。
has_tag(tag)	string	bool	检测实体、精英或玩家标签。
push_relative_to(location, force?=1, extra_x?=0, extra_y?=0, extra_z?=0)	table, number?=1, number?=0, number?=0, number?=0	nil	立即将速度替换为远离源位置的单位向量乘力度，再加世界轴偏移。源位置必须在同一世界。
overlaps_box_at_location(center, half_x?=0.5, half_y?=half_x, half_z?=half_x)	table, number?=0.5, number?, number?	bool	检测实体碰撞箱与所请求的箱体是否相交。
is_inside_vehicle()	—	bool	检测该实体是否正在乘坐载具。
has_vehicle()	—	bool	检测是否存在载具。
get_vehicle()	—	table/nil	返回当前载具引用。
set_vehicle(vehicle)	table	bool	让该实体乘坐已解析的载具。
leave_vehicle()	—	bool	离开当前载具。
has_passengers()	—	bool	检测是否存在乘客。
get_passenger_count()	—	int	返回乘客数量。
get_passengers()	—	table	返回乘客引用。
add_passenger(passenger)	table	bool	添加已解析的乘客。
remove_passenger(passenger)	table	bool	移除已解析的乘客。
eject_passengers()	—	bool	弹出每一位乘客。
apply_potion_effect(type, duration, amplifier?=0)	string (PotionEffectType), int, int?=0	nil	解析转为大写的 Bukkit 药水名，在实例规则允许时应用。增幅值从零开始。
set_equipment(slot, material, options?)	string (EquipmentSlot), string (Material), table?	nil	设置装备；options 支持 unbreakable，以及带 type 和 level 的 enchantments 条目。
damage_equipment(slot, amount)	string, int	int	请求对 HAND、OFF_HAND、HEAD、CHEST、LEGS 或 FEET 的装备造成1–64点耐久损耗，返回实际损耗。遵守玩家物品损伤事件的取消结果和不可破坏设置；可能使物品损坏。
set_fire_ticks(ticks)	int	nil	实例规则允许时设置着火 tick。
add_visual_freeze_ticks(ticks?=1)	int?=1	nil	规则允许时增加 Minecraft 冰冻 tick，可能造成冰冻伤害，不是 AI 或移动锁定。
place_temporary_block(material, ticks?=0, require_air?=false)	string (Material), int?=0, bool?=false	nil	在该实体处放置一个临时方块。

AI、感知、缩放和无敌修改归调用它们的能力所有。每项修改都会记录它所替换的值。正数时长会在指定 tick 后恢复该值；时长为 0 时修改会一直保持到能力关闭，关闭时同样会恢复。多个能力修改同一属性时，结束其中一项修改会恢复剩余修改中最新的那一项；没有剩余修改时则恢复原始值。如果在此期间有其他插件或命令修改了该属性，则保留其值，不进行恢复。暂停能力不会结束这些修改。延迟的 apply_push_vector 和标签移除计时器仍独立于脚本调度器运行。reset_custom_name 对跟踪精英恢复其名称，对普通 Bukkit 实体则使用当前名称，而非保存的原名。

EliteMobs 能力玩家表

EliteMobs Boss 能力的玩家值继承 EliteMobs Power Living Entity 的每一个属性和方法。

属性

字段	类型	说明
game_mode	string	大写的 Bukkit 游戏模式快照。

方法

方法	参数	返回值	说明
send_message(text)	string	nil	发送经颜色处理的聊天文本。
show_action_bar(text)	string	nil	发送经颜色处理的动作栏。
show_title(title, subtitle?="", fade_in?=10, stay?=40, fade_out?=10)	string, string?="", int?=10, int?=40, int?=10	nil	显示经颜色处理的标题。
show_boss_bar(title, color?=WHITE, style?=SOLID, duration?=40)	string, string (BarColor)?=WHITE, string (BarStyle)?=SOLID, int?=40	nil	显示 Boss 血条，并在正数 ticks 之后移除。
run_command(command)	string	nil	以该玩家身份执行一条命令。

context.boss

EliteMobs Boss 能力会收到这张表，它继承 EliteMobs Power Living Entity 的每一个属性和方法，并用精英层面的语义覆盖此处列出的行。

属性

字段	类型	说明
name	string	精英显示名称或脚本文件名快照。
uuid	string	精英 UUID。
health	number	精英生命值快照。
maximum_health	number	精英最大生命值快照。
current_location	table	精英位置快照。
level	int	精英等级快照。
damager_count	int	伤害者数量快照。
is_in_combat	bool	战斗状态快照。
exists	bool	精英存在性快照。

方法

方法	参数	返回值	说明
is_alive()	—	bool	检测生物实体以及 EliteMobs 的存在状态。
get_health()	—	number	返回实时的精英生命值。
get_maximum_health()	—	number	返回实时的精英最大生命值。
get_location()	—	table	返回实时的精英位置。
restore_health(amount)	number	nil	通过 EliteMobs 实体进行治疗。
add_tag(tag, duration?=0)	string, int?=0	nil	添加一个精英标签，并在正数 ticks 之后移除。
remove_tag(tag)	string	nil	移除一个精英标签。
has_tag(tag)	string	bool	检测一个精英标签。
reset_custom_name()	—	nil	还原精英显示名称。
play_sound_at_self(sound, volume_or_options?=1, pitch?=1)	string (Sound), number/table?=1, number?=1	nil	在精英位置播放已注册音效或自定义命名空间音效。第二个参数也可以改为 {volume, pitch}。
play_sound_at_entity(sound, volume_or_options?=1, pitch?=1)	string (Sound), number/table?=1, number?=1	nil	在精英位置播放的别名。第二个参数也可以改为 {volume, pitch}。
spawn_particle_at_self(particle, count?=1)	string (Particle)/table, int?=1	nil	在精英位置生成粒子。
play_model_animation(name)	string	nil	可用时播放自定义 Boss 模型动画。
navigate_to_location(location, speed?=1, force?=false, timeout?=0)	table, number?=1, bool?=false, int?=0	nil	让自定义 Boss 寻路。
get_damager_count()	—	int	返回实时的伤害者数量。
despawn()	—	nil	以 OTHER 原因移除该精英。
remove()	—	nil	despawn() 的别名。
patrol_pause()	—	bool	暂停已配置的巡逻。
patrol_resume()	—	bool	在脚本等待或临时移动后恢复巡逻。
walk_to(x, y, z)	number, number, number	bool	走到相对于原点的偏移并恢复巡逻。
hold(x, y, z)	number, number, number	bool	走到偏移位置并停留。
teleport(x, y, z)	number, number, number	bool	传送到进行实体 tick 的偏移位置。
get_ender_dragon_phase()	—	string/nil	返回 EnderDragon.Phase 名称，或 nil。
set_ender_dragon_phase(phase)	string (EnderDragon.Phase)	nil	设置一个有效的末影龙阶段。
has_mount()	—	bool	检测该 Boss 是否有存活的坐骑载具。
get_mount()	—	table/nil	返回标记了 is_mount = true 的坐骑引用。
set_mount(mount)	table	bool	让该 Boss 乘坐已解析的实体。
clear_mount()	—	bool	离开当前载具。
dismount()	—	bool	clear_mount() 的别名。
start_tracking_fireball_system(speed?=0.5)	number?=0.5	nil	对于怪物型 Boss，在其有目标期间，于下一个 tick 以及之后每 160 ticks 向每个轴向 20 格范围内的生存/冒险模式玩家发射追踪火球。该任务归能力所有：暂停能力会暂停它，失去目标或关闭能力会停止它。速度必须是有限正数。
handle_spirit_walk_damage(cause)	string (DamageCause)	nil	运行 Spirit Walk 伤害处理。
shield_wall_is_active()	—	bool	检测护盾墙状态。
initialize_shield_wall(openingDirection?=1)	int?=1	nil	将各方向护盾耐久初始化为 Boss 等级。缺口：1 北、2 东、3 南、4 西；其他整数保护四面。已激活的护盾墙不变。
shield_wall_absorb_damage(player, damage)	table, number	bool	攻击者所在方向的耐久原本为正时扣除伤害；返回 true 表示脚本应自行取消伤害事件，不会自动取消。
deactivate_shield_wall()	—	nil	停止护盾墙的独立任务并移除状态与显示效果。仅关闭 Lua 不会停用护盾墙。
start_zombie_necronomicon(target, chant)	table, string	nil	为生物目标启动独立控制器。字符串是显示的咒文，不是文件名；使用固定的 necronomicon 僵尸／骷髅文件，以施法者等级召唤。
send_message(text, range?=20)	string, number?=20	nil	向范围内玩家发送经颜色处理的文本。
get_nearby_players(range)	number	table	返回附近的 EliteMobs Power Player 表。
get_nearby_elites(radius)	number	table	返回同一世界中最多32个存活且被追踪的精英，排除首领自身；按距离排序，距离相同时按 UUID 排序。半径必须大于0且不超过64。
get_target_player()	—	table/nil	当前怪物目标是玩家时返回该目标。
get_nearby_players_in_zone(zone)	table	table	返回该区域内包含的玩家。
spawn_particles_in_zone(zone, particle, count?=1, dx?=0, dy?=0, dz?=0, speed?=0, coverage?=1)	table, string (Particle), int?=1, number?=0, number?=0, number?=0, number?=0, number?=1	nil	对区域内部采样并生成粒子。
spawn_particles_in_zone_border(zone, particle, count?=1, dx?=0, dy?=0, dz?=0, speed?=0, coverage?=1)	table, string (Particle), int?=1, number?=0, number?=0, number?=0, number?=0, number?=1	nil	对区域边缘采样并生成粒子。
get_particles_from_self_toward_zone(zone, particle, speed?=0.1)	table, string (Particle), number?=0.1	table	构建从 Boss 指向采样区域点的定向粒子规格。
get_particles_toward_self(zone, particle, speed)	table, string (Particle), number	table	构建指向 Boss 的定向粒子规格；当前的实时构建器会从最后一个传入参数读取 speed。
spawn_particles_with_vector(particles)	table	nil	生成一组定向粒子规格。
summon_reinforcement(file, zone_or_location?, duration?=0)	string, table?, int?=0	table/nil	在区域采样点、位置或 Boss 处召唤增援；正数 duration 会在该 tick 数后移除。
summon_projectile(type, origin, destination, speed?=1, options?)	string (EntityType), table, table, number?=1, table?	table/nil	生成一个抛射物；options 支持 custom_damage、detonation_power、yield、incendiary、gravity、glowing、invulnerable、persistent、duration、EntityEffect effect、spawn_at_origin、direction_only、track、on_land 和 max_ticks。

context.players：EliteMobs Boss 能力

方法	参数	返回值	说明
current_target()	—	table/nil	当事件行为者是玩家时返回该行为者，否则在 Boss 当前的怪物目标是玩家时返回该目标。
nearby_players(radius)	number	table	返回 Boss 半径范围内的 Player Table。
all_players_in_world()	—	table	返回 Boss 当前世界中的所有 Player Table。

context.entities：EliteMobs Boss 能力

集合查询排除 Boss 自身。生物过滤器接受 player/players、elite/elites、mob/mobs，其他值表示所有生物。不强制生存/冒险模式，也不检查地下城实例成员身份。直接目标查询独立于这些集合过滤器，返回钩子提供的目标。

方法	参数	返回值	说明
get_nearby_entities(radius, filter?="living")	number, string?	table	生物过滤器使用脚部三维距离；all 或 entities 改用 Bukkit 轴对齐箱体查询，包含非生物。
get_entities_in_box(center, half_x, half_y, half_z, filter?="living")	table, number, number, number, string?	table	返回脚部位置在箱内或边界上的生物实体。
get_all_entities(filter?="living")	string?	table	返回 Boss 所在世界中匹配的生物实体。
get_direct_target_entity()	—	table/nil	返回当前钩子提供的直接目标。
get_boss_spawn_location()	—	table	返回 Boss 最初的出生位置。

context.vectors：EliteMobs Boss 能力

方法	参数	返回值	说明
get_vector_between_locations(source, destination, options?)	table, table, table?	table	返回同世界两个位置之间的向量；输入无效或跨世界时返回 {x=0,y=0,z=0}。options 支持 normalize、multiplier 和向量 offset。
rotate_vector(vector, pitch?=0, yaw?=0)	table, number?=0, number?=0	table	返回按 pitch 和 yaw（单位为度）旋转后的向量。
normalize_vector(vector)	table	table	返回单位向量；零向量仍为零。

context.zones：EliteMobs Boss 能力

EliteMobs Boss 能力用 Elite Script 区域定义查询取代了共享的整数句柄区域接口。

实体归属、点包含和粒子位置采样是不同形状操作，边界结果可能不同。coverage 改变采样位置，不改变实体选择。watch_zone 捕获形状，向回调传入实体表而非上下文；一 tick 后开始检查，已在内部的实体也会作为进入报告。停止监视不发出离开回调。

方法	参数	返回值	说明
get_entities_in_zone(zone, options?)	table, table?	table	返回匹配的生物实体。options 支持 filter 以及 mode = "full" 或 "border"。
get_locations_in_zone(zone, options?)	table, table?	table	返回采样得到的位置。options 支持 coverage 以及 mode = "full" 或 "border"。
zone_contains(zone, location, mode?="full")	table, table, string?	bool	检测该位置是否位于完整形状内或边界上。
watch_zone(zone, callbacks, options?)	table, table, table?	nil	使用 {on_enter, on_leave} 回调进行监视。options 支持 filter 和 mode；所拥有的监视会随脚本一同停止。

context.script：EliteMobs Boss 能力

这个桥接层接受与 Elite Script 目标、区域和相对向量 YAML 配置相同的表键。

方法

方法	参数	返回值	说明
target(spec)	table	target handle	创建一个目标句柄。
zone(spec)	table	zone handle	创建一个区域句柄。
relative_vector(spec, location?, zone?)	table, table?, zone handle?	vector handle	创建一个相对向量句柄，其动作位置默认为 Boss。
damage(target, amount?=0, multiplier?=1)	target handle, number?=0, number?=1	nil	提交归因于 Boss 的 Bukkit 伤害；玩家命中进入含倍率的 EliteMobs 战斗缩放，非玩家命中不应用该倍率。
push(target, vector, additive?=false)	target handle, table/vector handle, bool?=false	nil	一个自有 tick 后替换或叠加捕获目标的速度；所有目标共用一个已解析向量，缺失或非有限向量变为零。
set_facing(target, vector)	target handle, table/vector handle	nil	让解析出的目标实体沿该向量朝向。
spawn_particles(target, particles)	target handle, table/string	nil	在解析出的目标位置生成该粒子规格。

这些调用不会自动执行 Elite Script 动作列表、条件、冷却、预警延迟或重复。目标句柄保留创建时的事件/直接目标上下文，不应跨无关钩子复用事件相关句柄。first_entity() 是解析器的第一个结果，不保证最近。

目标句柄方法

方法	参数	返回值	说明
entities()	—	table	解析并返回 Entity Table。
locations()	—	table	解析并返回位置表。
first_entity()	—	table/nil	返回第一个解析出的实体。
first_location()	—	table/nil	返回第一个解析出的位置。

区域句柄方法

方法	参数	返回值	说明
full_target(coverage?)	number?	target handle	为形状内部创建一个目标句柄。
border_target(coverage?)	number?	target handle	为边界创建一个目标句柄。
full_locations(coverage?)	number?	table	解析采样得到的内部位置。
border_locations(coverage?)	number?	table	解析采样得到的边界位置。
full_entities()	—	table	解析形状内部的实体。
border_entities()	—	table	解析边界上的实体。
contains(location, mode?="full")	table, string?	bool	检测是否属于完整形状或边界。
watch(callbacks, mode?="full")	table, string?	int	启动一个自己拥有的 {on_enter, on_leave} 监视并返回其任务 ID。

相对向量句柄方法

方法	参数	返回值	说明
resolve()	—	table	为当前上下文解析该向量。

EliteMobs 能力事件表

EliteMobs Boss 能力的事件值会按事件类型有条件地暴露字段和方法。

属性

字段	类型	说明
damage_amount	number/nil	伤害事件的数值快照。
damage_cause	string/nil	当伤害事件暴露该值时，为 DamageCause 名称。
damager	table/nil	原始伤害来源实体引用；抛射物命中时是抛射物，而非射手。
projectile	table/nil	当伤害来源是抛射物时的抛射物引用。
spawn_reason	string/nil	精英生成原因。
entity	table/nil	按钩子类型为受伤增援、死亡或区域事件实体。
is_damage_transfer	bool/nil	仅玩家对精英伤害：当前是否处理显式转移的命中。

方法

方法	参数	返回值	说明
cancel_event()	—	nil	取消 EliteDamageEvent 或其他可取消事件。
set_damage_amount(amount)	number	nil	替换 EliteDamageEvent 的伤害值；必须用点号调用：context.event.set_damage_amount(...)。
multiply_damage_amount(multiplier)	number	nil	乘算 EliteDamageEvent 的伤害值；必须用点号调用：context.event.multiply_damage_amount(...)。
get_damage_amount()	—	number	返回修改后的实时 EliteDamageEvent 伤害。
transfer_damage(target, amount)	entity reference, number	bool	仅玩家对精英伤害：向实例规则允许的另一个存活精英提交有限非负伤害。零、已取消输入、嵌套转移和原目标返回 false；非精英接收者会报错。true 表示提交，不保证伤害生效，不减少或取消原伤害。

context.world：EliteMobs 追加与覆盖

Boss 能力继承共享世界表，包括 EliteMobs 视觉闪电与 NPC 生成辅助方法，再添加或覆盖下列方法。继承的坐标方法保留共享行为。Boss 专用位置方法使用 Boss 转换器：省略或非表位置回退到 Boss，缺失坐标为零，显式世界名必须能解析。

方法

方法	参数	返回值	说明
play_sound_at_location(location, sound, volume?=1, pitch?=1)	table, string (Sound), number?=1, number?=1	nil	覆盖版本，可通过 EliteMobs 支持接受已注册音效或自定义命名空间音效。
spawn_particle_at_location(location, particle, count?=1)	table, string (Particle)/table, int?=1	nil	覆盖版本，可接受 EliteMobs 粒子规格表。
set_block_at_location(location, material, require_air?=false)	table, string (Material), bool?=false	nil	覆盖版本，通过临时方块管理器永久放置方块，不设计时器，也不跟踪。
place_temporary_block_at_location(location, material, ticks?=0, require_air?=false)	table, string (Material), int?=0, bool?=false	nil	覆盖版本，使用 EliteMobs 临时方块放置。
get_block_type_at_location(location)	table	string/nil	返回大写的 Material 名称；位置无效时返回 nil。
get_highest_block_y_at_location(location)	table	int/nil	覆盖版本，返回最高方块的 Y 坐标，或 nil。
get_blast_resistance_at_location(location)	table	number	返回方块的爆炸抗性；位置无效时默认为 0。
is_air_at_location(location)	table	bool	检测目标方块是否为空气。
is_passable_at_location(location)	table	bool	检测 Bukkit 可通过性。
is_passthrough_at_location(location)	table	bool	检测该材质是否为非固体。
is_on_floor_at_location(location)	table	bool	检测目标为非固体且其下方为固体方块。
is_standing_on_material(location, material)	table, string (Material)	bool	检测下方的方块。
strike_lightning_at_location(location)	table	nil	覆盖版本，在降下闪电之前启用 EliteMobs 闪电绕过机制。
run_empowered_lightning_task_at_location(location)	table	nil	独立发出 60 次预警，随后生成真实闪电及爆炸强度为 5 的向下火球。会造成伤害；暂停或关闭 Lua 不会取消任务。
set_world_time(time) / set_world_time(location, time)	int/table, int?	nil	设置 Boss 所在世界的时间，或所传位置所在世界的时间。
set_world_weather(weather, duration?=6000) / set_world_weather(location, weather, duration?=6000)	string/table, string/int?, int?=6000	nil	设置 CLEAR、PRECIPITATION、RAIN 或 THUNDER。
run_console_command(command)	string	nil	以控制台身份派发一条命令。
spawn_boss_at_location(file, location?, level?)	string, table?, int?	table/nil	在所传位置或当前位置、以所传等级或当前等级生成一个自定义 Boss。
spawn_custom_boss_at_location(file, location, options?)	string, table, table?	table/nil	生成一个自定义 Boss；options 支持 silent、level、add_as_reinforcement 和 velocity。
spawn_entity_at_location(type, location, options?)	string (EntityType), table, table?	table/nil	生成一个原版实体；options 支持 velocity、duration、EntityEffect effect、on_land 和 max_ticks。
spawn_falling_block_at_location(location, material, options?)	table, string (Material), table?	table/nil	生成一个下落方块；options 支持 drop_item、hurt_entities、velocity 和 on_land。
spawn_reinforcement_at_location(file, location, duration?=0, velocity?)	string, table, int?=0, table?	table/nil	召唤与 Boss 绑定的增援；正数 duration 会在该 tick 数后移除。
spawn_fireworks_at_location(location, options)	table, table	table/nil	生成烟花；options 支持 effects、type、flicker、trail、colors、fade_colors、power、velocity 和 shot_at_angle，其中 type 使用 FireworkEffect.Type 名称。
spawn_splash_potion_at_location(location, options)	table, table	table/nil	生成一瓶喷溅药水；effects 条目接受 PotionEffectType 的 type、duration、amplifier 和 overwrite，以及顶层的 velocity。
generate_fake_explosion(locations, source?)	table, table?	nil	启用爆炸再生时，移除真实方块并生成会造成伤害的下落碎片。1200 游戏刻后开始恢复；关闭 Lua 不会撤销。位置必须在 Boss 所在世界。
spawn_fake_gold_nugget_at_location(location, velocity, gravity?=false)	table, table, bool?=false	table/nil	生成一个假金粒抛射物。
run_fake_gold_nugget_damage(projectiles)	table	nil	运行假抛射物的伤害判定。
generate_player_loot(times?=1)	int?=1	nil	为符合条件的伤害者生成玩家战利品。
drop_bonus_coins(multiplier?=2)	number?=2	nil	为符合条件的伤害者掉落额外金币。

EliteMobs 假抛射物表

当生成成功时，spawn_fake_gold_nugget_at_location 会返回这张表。

方法

方法	参数	返回值	说明
get_location()	—	table	返回假抛射物的位置。
set_gravity(enabled)	bool	nil	设置假抛射物的重力。
remove()	—	nil	移除该假抛射物。
is_removed()	—	bool	检测它是否已被移除。

context.settings

EliteMobs Boss 能力会从同一个 world 表构建器收到这张设置表。

方法

方法	参数	返回值	说明
warning_visual_effects_enabled()	—	bool	返回当前的警告视觉特效设置。