Lua API 参考

Lua 脚本 API 的完整方法参考。所有方法通过 context.table:method() 语法调用。

全局方法（标记为 GLOBAL）来自 Magmacore，即共享核心库——它们在 EliteMobs 和 FreeMinecraftModels 脚本中的行为完全相同。

EliteMobs 方法（标记为 ELITEMOBS）专用于 EliteMobs Boss 技能脚本。

FMM 方法（标记为 FMM）专用于 FreeMinecraftModels 物品和道具脚本。

需要使用 Bukkit 枚举（Sound、Particle、Material 等）的方法，请参阅 Spigot Javadocs 获取有效值。枚举名称以大写字符串传递（例如 "DIAMOND_SWORD"、"ENTITY_ARROW_SHOOT"）。

实体表 GLOBAL

所有实体表上的基础字段——玩家、怪物、道具等一切实体。

属性

字段	类型	描述
`uuid`	string	实体 UUID
`entity_type`	string	实体类型（小写）
`is_valid`	bool	实体仍存在于世界中
`is_dead`	bool	实体已死亡
`is_player`	bool	是否是玩家
`is_hostile`	bool	是否是 Monster
`is_passive`	bool	是否是 Animal
`is_elite`	bool	是否是 EliteMobs 实体
`is_custom_boss`	bool	是否是 EliteMobs 自定义 Boss
`is_significant_boss`	bool	生命值倍率超过 1 的自定义 Boss（设计好的遭遇战）
`is_modeled`	bool	是否有 FMM 模型
`is_prop`	bool	是否是 FMM 道具
`current_location`	location	实体位置（x、y、z、yaw、pitch、world）
`world`	string	世界名称

方法

方法	参数	返回值	描述
`teleport(location)`	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	设置发光

桥接：entity.elite

仅在 is_elite 为 true 时存在。通过反射填充——不需要 EliteMobs 依赖。

字段	类型	描述
`level`	int	精英怪物等级
`name`	string	精英显示名称
`health`	double	当前生命值
`max_health`	double	最大生命值
`is_custom_boss`	bool	是否是自定义 Boss（也可在顶层获取）
`health_multiplier`	double	配置定义的生命值倍率
`damage_multiplier`	double	配置定义的伤害倍率
`remove()`	method	移除精英实体

桥接：entity.model

仅在 is_modeled 为 true 时存在。通过反射填充——不需要 FMM 依赖。

字段	类型	描述
`model_id`	string	模型蓝图名称
`play_animation(name, blend?, loop?)`	method	播放动画。blend 默认为 false，loop 默认为 false
`stop_animations()`	method	停止所有动画
`remove()`	method	移除模型化实体

生物实体表 GLOBAL

扩展实体表。适用于所有生物实体（怪物和玩家）。

属性

字段	类型	描述
`health`	double	当前生命值
`maximum_health`	double	最大生命值
`name`	string	实体显示名称
`is_alive`	bool	实体未死亡

方法

方法	参数	返回值	描述
`damage(amount)`	double	nil	对实体造成伤害
`push(x, y, z)`	double, double, double	nil	添加速度向量
`set_facing(x, y, z)`	double, double, double	nil	设置朝向
`add_potion_effect(type, duration, amplifier)`	string (PotionEffectType), int, int	nil	按名称应用药水效果
`remove_potion_effect(type)`	string (PotionEffectType)	nil	按名称移除药水效果

context.player GLOBAL

玩家实体表。继承所有实体和生物实体字段。

属性

字段	类型	描述
`game_mode`	string	survival、creative、adventure、spectator

方法

方法	参数	返回值	描述
`send_message(text)`	string	nil	发送聊天消息。支持颜色代码
`get_held_item()`	—	table 或 nil	返回 type、amount、display_name 字段，空手时返回 nil
`consume_held_item(amount?)`	int（默认 1）	nil	减少手持物品堆叠数量
`has_item(material, amount?)`	string (Material), int（默认 1）	bool	检查背包中是否有指定材料
`get_target_entity(range?)`	num（默认 50）	entity 或 nil	射线检测玩家正在看的实体
`get_eye_location()`	—	location	玩家眼睛位置
`get_look_direction()`	—	vector	单位方向向量
`send_block_change(x, y, z, material, ticks?)`	int, int, int, string (Material), int（可选）	bool	发送假方块。如果设置了 ticks 则自动恢复
`reset_block(x, y, z)`	int, int, int	bool	将假方块恢复为真实方块
`sleep(x, y, z)`	num, num, num	nil	在指定位置播放睡觉动画
`wake_up()`	—	nil	从睡眠中醒来
`show_boss_bar(text, color?, progress, ticks?)`	string, string (BarColor，默认 WHITE), num, int（可选）	nil	显示 Boss 血条。经过 ticks 后自动隐藏。支持颜色代码
`hide_boss_bar()`	—	nil	移除 Boss 血条
`show_action_bar(text, ticks?)`	string, int（可选）	nil	显示操作栏。如果 ticks 大于 0 则重复显示。支持颜色代码
`show_title(title, subtitle?, fadeIn, stay, fadeOut)`	string, string（默认空）, int, int, int	nil	显示标题屏幕。支持颜色代码

context.world GLOBAL

世界操作。在所有脚本类型中可用。

属性

字段	类型	描述
`name`	string	世界名称

方法

方法	参数	返回值	描述
`get_block_at(x, y, z)`	int, int, int	string	Material 名称（小写）
`set_block_at(x, y, z, material)`	int, int, int, string (Material)	bool	放置方块
`get_highest_block_y(x, z)`	int, int	int	最高非空气方块的 Y 坐标
`spawn_particle(particle, x, y, z, count?, dx?, dy?, dz?, speed?)`	string (Particle), num, num, num, int?=1, num?=0, num?=0, num?=0, num?=0	nil	生成粒子效果
`play_sound(sound, x, y, z, volume?, pitch?)`	string (Sound), num, num, num, float?=1, float?=1	nil	播放声音
`strike_lightning(x, y, z)`	num, num, num	nil	劈下闪电
`get_time()`	—	int	世界时间（tick）
`set_time(ticks)`	long	nil	设置世界时间
`get_nearby_entities(x, y, z, radius)`	num, num, num, num	table	实体表数组
`get_nearby_players(x, y, z, radius)`	num, num, num, num	table	玩家实体表数组
`spawn_entity(type, x, y, z)`	string (EntityType), num, num, num	entity	生成原版实体
`raycast(fx, fy, fz, dx, dy, dz, max?)`	num, num, num, num, num, num, num?=50	table	返回 hit_entity、hit_location、hit_block 字段
`spawn_firework(x, y, z, colors, type?, power?)`	num, num, num, table, string (FireworkEffect.Type)?=BALL, int?=1	nil	生成烟花
`place_temporary_block(x, y, z, material, ticks?, require_air?)`	int, int, int, string (Material), int?=0, bool?=false	bool	放置经过 ticks 后自动恢复的方块
`drop_item(x, y, z, material, amount?)`	num, num, num, string (Material), int?=1	entity	在指定位置自然掉落物品实体

context.boss ELITEMOBS

EliteMobs Lua 技能脚本的 Boss 实体表。继承所有 EliteMobs 生物实体方法。属性通过专用 getter 刷新。

属性

字段	类型	描述
`name`	string	Boss 显示名称
`uuid`	string	精英实体 UUID
`health`	double	当前生命值（快照）
`maximum_health`	double	最大生命值（快照）
`current_location`	location	Boss 位置（快照）
`level`	int	Boss 等级
`damager_count`	int	对此 Boss 造成过伤害的玩家数量
`is_in_combat`	bool	Boss 是否在战斗中
`exists`	bool	Boss 实体是否存在

方法

方法	参数	返回值	描述
`is_alive()`	—	bool	Boss 实体是否存活（实时检查）
`get_health()`	—	double	当前生命值（实时）
`get_maximum_health()`	—	double	最大生命值（实时）
`get_location()`	—	location	当前位置（实时）
`restore_health(amount)`	double	nil	治疗 Boss
`despawn()`	—	nil	移除 Boss 实体
`get_damager_count()`	—	int	实时伤害者计数
`add_tag(tag, ticks?)`	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?, pitch?)`	string (Sound), float?=1, float?=1	nil	在 Boss 位置播放声音
`play_sound_at_entity(sound, volume?, pitch?)`	string (Sound), float?=1, float?=1	nil	在 Boss 位置播放声音（别名）
`spawn_particle_at_self(particle, count?)`	string (Particle) 或 table, int?=1	nil	在 Boss 位置生成粒子
`play_model_animation(name)`	string	nil	播放 FMM 模型动画（需要 FMM 模型）
`navigate_to_location(location, speed?, force?, timeout?)`	location, double?=1, bool?=false, int?=0	nil	寻路到指定位置
`send_message(text, range?)`	string, double?=20	nil	向附近玩家发送消息。支持颜色代码
`get_nearby_players(range)`	double	table	范围内的玩家表数组
`get_target_player()`	—	player 或 nil	当前怪物目标（如果是玩家）
`get_nearby_players_in_zone(zone)`	zone table	table	区域形状内的玩家
`get_ender_dragon_phase()`	—	string 或 nil	EnderDragon.Phase 名称
`set_ender_dragon_phase(phase)`	string (EnderDragon.Phase)	nil	设置末影龙阶段
`summon_reinforcement(file, zone?, level?)`	string, zone 或 nil, int?=0	entity 或 nil	生成增援 Boss
`summon_projectile(type, origin, dest, speed?, options?)`	string (EntityType), location, location, double?=1, table	entity	生成追踪投射物

summon_projectile 选项

选项	类型	默认值	描述
`custom_damage`	number	—	覆盖投射物伤害
`detonation_power`	string	—	爆炸威力等级
`yield`	number	—	火球威力
`incendiary`	bool	true	火球是否点火
`gravity`	bool	—	启用重力
`glowing`	bool	false	设置发光
`invulnerable`	bool	false	设置无敌
`persistent`	bool	true	设置持久化
`duration`	int	0	经过 tick 后自动移除
`effect`	string	—	生成时播放的 EntityEffect
`spawn_at_origin`	bool	false	在起点生成而非从 Boss 位置发射
`direction_only`	bool	false	仅设置方向不设置速度（火球）
`track`	bool	true	注册为精英投射物
`on_land`	function	—	投射物落地时的回调：`function(location, entity)`
`max_ticks`	int	6000	强制落地回调前的最大 tick 数

区域/粒子方法

方法	参数	返回值	描述
`spawn_particles_in_zone(zone, particle, ...)`	zone, particle spec, coverage?=1.0	nil	在区域内填充粒子
`spawn_particles_in_zone_border(zone, particle, ...)`	zone, particle spec, coverage?=1.0	nil	在区域边界描绘粒子
`get_particles_from_self_toward_zone(zone, particle, speed?)`	zone, string, double?=0.1	table	从 Boss 到区域的定向粒子
`get_particles_toward_self(zone, particle, speed?)`	zone, string, double?=0.1	table	从区域到 Boss 的定向粒子
`spawn_particles_with_vector(particles)`	table	nil	生成定向粒子数组

特殊技能支持

方法	参数	返回值	描述
`start_tracking_fireball_system(speed?)`	double?=0.5	nil	启动追踪火球 AI
`handle_spirit_walk_damage(cause)`	string (DamageCause)	nil	按原因处理灵魂行走伤害
`shield_wall_is_active()`	—	bool	护盾墙是否激活
`initialize_shield_wall(charges?)`	int?=1	nil	激活护盾墙
`shield_wall_absorb_damage(player, damage)`	entity table, double	bool	尝试吸收伤害
`deactivate_shield_wall()`	—	nil	停用护盾墙
`start_zombie_necronomicon(target, file)`	entity table, string	nil	对目标启动死灵之书

EliteMobs 生物实体表 ELITEMOBS

在 EliteMobs 技能脚本中创建的实体表（来自 context.boss、事件数据、区域回调和世界查询）使用扩展的生物实体表，在全局生物实体之上提供额外方法。context.boss 继承所有这些方法。

属性

字段	类型	描述
`name`	string	实体显示名称
`uuid`	string	实体 UUID
`entity_type`	string	实体类型名称
`is_player`	bool	是否是玩家
`is_monster`	bool	是否是 Monster
`is_elite`	bool	是否是 EliteMobs 实体
`is_valid`	bool	实体是否仍然存在
`health`	double	当前生命值（快照）
`maximum_health`	double	最大生命值（快照）
`current_location`	location	实体位置（快照）
`game_mode`	string	游戏模式（仅玩家）

方法

方法	参数	返回值	描述
`is_alive()`	—	bool	实体是否存活（实时检查）
`is_ai_enabled()`	—	bool	AI 是否启用
`is_frozen()`	—	bool	Boss 是否被冻结（仅 CustomBossEntity）
`is_on_ground()`	—	bool	实体是否在地面上
`is_healing()`	—	bool	精英是否在治疗中
`get_location()`	—	location	当前位置（实时）
`get_eye_location()`	—	location	眼睛位置（实时）
`get_height()`	—	double	实体高度
`get_health()`	—	double	当前生命值（实时）
`get_maximum_health()`	—	double	最大生命值（实时）
`get_velocity()`	—	vector	当前速度向量
`deal_damage(amount)`	double	nil	造成通用伤害
`deal_custom_damage(amount)`	double	nil	从技能所属 Boss 造成自定义 Boss 攻击伤害
`deal_damage_from_boss(amount)`	double	nil	造成归属于技能所属 Boss 实体的伤害
`restore_health(amount)`	double	nil	治疗实体（如果是精英则使用 EliteMobs 治疗）
`play_sound_at_entity(sound, volume?, pitch?)`	string (Sound), float?=1, float?=1	nil	在实体位置播放声音
`play_sound_at_self(sound, volume?, pitch?)`	string (Sound), float?=1, float?=1	nil	在实体位置播放声音（别名）
`spawn_particle_at_self(particle, count?)`	string (Particle) 或 table, int?=1	nil	在实体位置生成粒子
`spawn_particles_at_location(loc, particle, count?)`	location, particle spec, int?=1	nil	在指定位置生成粒子
`teleport_to_location(location)`	location	nil	传送实体
`set_velocity_vector(vector)`	vector	nil	设置速度
`set_gravity(enabled)`	bool	nil	设置重力
`apply_push_vector(vector, additive?, delay?)`	vector, bool?=false, int?=1	nil	延迟后应用速度。additive 会叠加到现有速度上
`push_relative_to(location, force?, extraX?, extraY?, extraZ?)`	location, double?=1, double?=0, double?=0, double?=0	nil	将实体从指定位置推开
`set_custom_name(name)`	string	nil	设置自定义显示名称。支持颜色代码
`reset_custom_name()`	—	nil	重置名称为 EliteMobs 默认值
`set_custom_name_visible(visible)`	bool	nil	切换名称可见性
`set_ai_enabled(enabled, duration?)`	bool, int?=0	nil	设置 AI 状态。经过 duration tick 后自动恢复
`set_awareness_enabled(enabled, duration?)`	bool, int?=0	nil	设置怪物感知。经过 duration tick 后自动恢复
`face_direction_or_location(target)`	vector 或 location	nil	面向方向或朝向某个位置
`play_model_animation(name)`	string	nil	播放 FMM 模型动画（需要 FMM 模型）
`set_scale(scale, duration?)`	double, int?=0	nil	设置实体大小。经过 duration tick 后自动恢复为 1.0
`set_invulnerable(enabled, duration?)`	bool, int?=0	nil	设置无敌。经过 duration tick 后自动恢复
`set_healing(enabled)`	bool	nil	设置精英治疗状态
`navigate_to_location(location, speed?, force?, timeout?)`	location, double?=1, bool?=false, int?=0	nil	寻路到指定位置（仅 CustomBossEntity）
`add_tag(tag, ticks?)`	string, int?=0	nil	添加标签，经过 ticks 后自动移除
`remove_tag(tag)`	string	nil	移除标签
`has_tag(tag)`	string	bool	检查标签
`overlaps_box_at_location(center, halfX?, halfY?, halfZ?)`	location, double?=0.5, double?=halfX, double?=halfX	bool	实体碰撞箱是否与指定位置的箱体重叠
`remove_elite()`	—	nil	通过 EliteMobs 移除流程移除
`apply_potion_effect(type, duration, amplifier?)`	string (PotionEffectType), int, int?=0	nil	应用药水效果
`set_equipment(slot, material, options?)`	string (EquipmentSlot), string (Material), table	nil	设置装备栏物品
`set_fire_ticks(ticks)`	int	nil	设置着火时间
`add_visual_freeze_ticks(ticks?)`	int?=1	nil	添加冰冻视觉效果 tick
`place_temporary_block(material, ticks?, visual?)`	string (Material), int?=0, bool?=false	nil	在实体位置放置临时方块

set_equipment 选项

选项	类型	默认值	描述
`unbreakable`	bool	false	使物品无法破坏
`enchantments`	table	—	`{type = "ENCHANT_NAME", level = 1}` 表的数组

EliteMobs 玩家方法

EliteMobs 脚本中的玩家拥有所有 EliteMobs 生物实体方法，加上：

方法	参数	返回值	描述
`send_message(text)`	string	nil	发送聊天消息。支持颜色代码
`show_action_bar(text)`	string	nil	显示操作栏文本。支持颜色代码
`show_title(title, subtitle?, fadeIn?, stay?, fadeOut?)`	string, string?="", int?=10, int?=40, int?=10	nil	显示标题屏幕。支持颜色代码
`show_boss_bar(title, color?, style?, duration?)`	string, string (BarColor)?=WHITE, string (BarStyle)?=SOLID, int?=40	nil	显示 Boss 血条。经过 duration tick 后自动隐藏。支持颜色代码
`run_command(command)`	string	nil	以玩家身份执行命令

EliteMobs 实体引用表

非生物实体（投射物、下落方块、烟花）从 EliteMobs 生成方法返回时获得一个轻量级引用表：

字段 / 方法	参数	返回值	描述
`name`	—	string	实体名称
`uuid`	—	string	实体 UUID
`entity_type`	—	string	实体类型名称
`is_player`	—	bool	始终为 false
`is_elite`	—	bool	始终为 false
`is_valid()`	—	bool	实体是否仍然有效（实时检查）
`current_location`	—	location	位置（快照）
`get_location()`	—	location	当前位置（实时）
`get_velocity()`	—	vector	当前速度向量
`is_on_ground()`	—	bool	实体是否在地面上
`teleport_to_location(location)`	location	nil	传送实体
`set_velocity_vector(vector)`	vector	nil	设置速度
`set_direction_vector(vector)`	vector	nil	设置方向（仅火球）
`set_yield(amount)`	double	nil	设置火球威力
`set_gravity(enabled)`	bool	nil	设置重力
`detonate()`	—	nil	引爆烟花
`remove()`	—	nil	移除实体
`unregister(reason?)`	string?=OTHER	nil	从 EliteMobs 实体追踪器取消注册

context.players ELITEMOBS

EliteMobs 技能脚本中可用的玩家查询表。提供辅助方法来查找相对于 Boss 的玩家。

方法	参数	返回值	描述
`current_target()`	—	player 或 nil	如果事件触发者是玩家则返回该玩家，或者 Boss 当前的怪物目标（如果是玩家）
`nearby_players(radius)`	double	table	Boss 范围内的玩家表数组
`all_players_in_world()`	—	table	Boss 所在世界的所有玩家表数组

context.entities ELITEMOBS

EliteMobs 技能脚本中可用的实体查询表。提供辅助方法来查找相对于 Boss 的实体。所有查询排除 Boss 自身。

方法	参数	返回值	描述
`get_nearby_entities(radius, filter?)`	double, string?="living"	table	范围内的实体。过滤器：`"living"`、`"all"`、`"entities"`
`get_entities_in_box(center, halfX, halfY, halfZ, filter?)`	location, double, double, double, string?="living"	table	轴对齐箱体内的实体
`get_all_entities(filter?)`	string?="living"	table	Boss 所在世界的所有实体
`get_direct_target_entity()`	—	entity 或 nil	触发事件的直接目标实体
`get_boss_spawn_location()`	—	location	Boss 的原始生成位置

context.vectors ELITEMOBS

EliteMobs 技能脚本中可用的向量数学工具。

方法	参数	返回值	描述
`get_vector_between_locations(from, to, options?)`	location, location, table	vector	从源到目标的向量。选项可修改结果
`rotate_vector(vector, pitch?, yaw?)`	vector, double?=0, double?=0	vector	按俯仰角和偏航角旋转向量（度）
`normalize_vector(vector)`	vector	vector	归一化为单位长度

context.cooldowns GLOBAL

冷却时间管理。本地冷却时间针对每个脚本实例；全局冷却时间在同一实体/所有者的所有脚本之间共享。如果未提供 key，则默认使用脚本文件名。

方法	参数	返回值	描述
`local_ready(key?)`	string（可选）	bool	本地冷却时间是否已到期
`local_remaining(key?)`	string（可选）	int	本地冷却剩余 tick 数（就绪时为 0）
`check_local(key?, duration)`	string（可选）, int	bool	如果就绪，启动冷却并返回 true；否则返回 false
`set_local(duration, key?)`	long, string（可选）	nil	设置本地冷却时间（tick）
`global_ready()`	—	bool	全局冷却时间是否已到期
`set_global(duration)`	long	nil	设置全局冷却时间（tick）

在 EliteMobs 技能脚本中，本地冷却时间在同一 Boss 实体的所有技能之间共享，全局冷却时间使用 Boss 内置的技能冷却系统。

context.scheduler GLOBAL

任务调度。所有任务在脚本关闭时自动取消。

全局（Magmacore）变体

方法	参数	返回值	描述
`run_later(ticks, callback)`	int, function	int	在指定 tick 后运行回调。返回任务 ID
`run_repeating(delay, interval, callback)`	int, int, function	int	在初始延迟后每隔 interval tick 运行回调。返回任务 ID
`cancel(taskId)`	int	nil	取消已调度的任务

EliteMobs 变体

方法	参数	返回值	描述
`run_after(ticks, callback)`	int, function	int	在指定 tick 后运行回调。返回任务 ID
`run_every(ticks, callback)`	int, function	int	每隔 N tick 运行回调。返回任务 ID
`cancel_task(taskId)`	int	nil	取消已调度的任务

context.log GLOBAL

用于调试脚本的日志工具。

方法	参数	返回值	描述
`info(message)`	string	nil	记录信息消息
`warn(message)`	string	nil	记录警告消息
`error(message)`	string	nil	记录错误/警告消息
`debug(message)`	string	nil	记录调试消息（显示为带调试前缀的信息）

context.zones GLOBAL

区域创建和监控。在所有脚本类型中可用。

全局（Magmacore）变体

方法	参数	返回值	描述
`create_sphere(x, y, z, radius)`	num, num, num, num	int	创建球形区域，返回句柄
`create_cylinder(x, y, z, radius, height)`	num, num, num, num, num	int	创建圆柱形区域，返回句柄
`create_cuboid(x, y, z, xSize, ySize, zSize)`	num, num, num, num, num, num	int	创建长方体区域，返回句柄
`watch(handle, on_enter?, on_leave?)`	int, function, function	bool	开始追踪区域的玩家进入/离开事件
`unwatch(handle)`	int	nil	停止追踪区域

EliteMobs 变体

方法	参数	返回值	描述
`get_entities_in_zone(zone, options?)`	zone table, table	table	获取区域内的实体。选项：filter、mode
`get_locations_in_zone(zone, options?)`	zone table, table	table	获取区域内的位置。选项：coverage、mode
`zone_contains(zone, location, mode?)`	zone table, location, string?="full"	bool	位置是否在区域内（"full" 或 "border"）
`watch_zone(zone, callbacks, mode?)`	zone table, table, string?="full"	int	监视区域的进入/离开事件。回调：`{on_enter = fn, on_leave = fn}`

context.event GLOBAL

触发当前脚本执行的钩子的事件数据表。仅在事件驱动钩子中存在（不适用于 on_tick）。

全局（Magmacore）变体

字段 / 方法	类型	描述
`is_cancelled`	bool	事件当前是否已取消
`cancel()`	method	取消事件
`uncancel()`	method	取消事件的取消
`player`	entity table	事件中涉及的玩家（如果有）

有关 EliteMobs 事件表（提供伤害数值、伤害原因等），请参阅 EliteMobs 事件表。

context.script ELITEMOBS

连接 EliteMobs Elite Script 系统的桥接。让 Lua 技能使用基于 YAML 的目标、区域和相对向量系统，通过与 Elite Script YAML 配置相同字段名的 Lua 表来调用。

方法

方法	参数	返回值	描述
`target(spec)`	table	target handle	从 Elite Script 目标规格表创建目标句柄
`zone(spec)`	table	zone handle	从 Elite Script 区域规格表创建区域句柄
`relative_vector(spec, location?, zone?)`	table, location, zone handle	vector handle	从 Elite Script 向量规格创建相对向量
`damage(target, amount?, multiplier?)`	target handle, double?=0, double?=1	nil	对目标中的所有实体造成伤害
`push(target, vector, additive?)`	target handle, vector 或 vector handle, bool?=false	nil	以速度推动目标实体
`set_facing(target, vector)`	target handle, vector 或 vector handle	nil	设置目标实体的朝向
`spawn_particles(target, particles)`	target handle, table 或 string	nil	在目标位置生成粒子

Target Handle

由 context.script:target(spec) 返回。规格表使用与 Elite Script YAML 目标配置相同的键（例如 {targetType = "NEARBY_PLAYERS", range = 20}）。

方法	参数	返回值	描述
`entities()`	—	table	目标位置的实体表数组
`locations()`	—	table	目标位置的位置表数组
`first_entity()`	—	entity 或 nil	目标位置的第一个实体
`first_location()`	—	location 或 nil	目标位置的第一个位置

Zone Handle

由 context.script:zone(spec) 返回。规格表使用与 Elite Script YAML 区域配置相同的键（例如 {shape = "SPHERE", radius = 5, target = {targetType = "SELF"}}）。

方法	参数	返回值	描述
`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?)`	location, string?="full"	bool	位置是否在区域内
`watch(callbacks, mode?)`	table, string?="full"	int	监视进入/离开事件。返回任务 ID

Vector Handle

由 context.script:relative_vector(spec) 返回。规格表使用与 Elite Script YAML 相对向量配置相同的键。

方法	参数	返回值	描述
`resolve()`	—	vector	计算当前上下文的向量

context.world（EliteMobs） ELITEMOBS

EliteMobs 技能脚本的扩展世界表。在全局世界表基础上增加了 Boss 专用的生成、方块检查和效果。

方块查询

方法	参数	返回值	描述
`get_block_type_at_location(loc)`	location	string 或 nil	Material 名称
`get_highest_block_y_at_location(loc)`	location	int 或 nil	最高方块 Y 坐标
`get_blast_resistance_at_location(loc)`	location	double	爆炸抗性值
`is_air_at_location(loc)`	location	bool	方块是否为空气
`is_passable_at_location(loc)`	location	bool	方块是否可通过
`is_passthrough_at_location(loc)`	location	bool	方块是否非实心
`is_on_floor_at_location(loc)`	location	bool	空气且下方有实心方块
`is_standing_on_material(loc, material)`	location, string (Material)	bool	下方方块是否匹配材料

方块操作

方法	参数	返回值	描述
`set_block_at_location(loc, material, visual?)`	location, string (Material), bool?=false	nil	放置方块。visual=true 为假方块
`place_temporary_block_at_location(loc, material, ticks?, visual?)`	location, string, int?=0, bool?=false	nil	放置方块，经过 ticks 后自动移除

生成

方法	参数	返回值	描述
`spawn_boss_at_location(file, loc?, level?)`	string, location?=boss loc, int?=boss level	entity 或 nil	生成自定义 Boss
`spawn_custom_boss_at_location(file, loc, options?)`	string, location, table	entity 或 nil	带选项生成 Boss（level、silent、add_as_reinforcement、velocity）
`spawn_entity_at_location(type, loc, options?)`	string (EntityType), location, table	entity	带选项生成原版实体（velocity、duration、effect、on_land、max_ticks）
`spawn_falling_block_at_location(loc, material, options?)`	location, string (Material), table	entity	生成下落方块（drop_item、hurt_entities、velocity、on_land）
`spawn_reinforcement_at_location(file, loc, level?, velocity?)`	string, location, int?=0, vector	entity 或 nil	生成绑定到 Boss 的增援
`spawn_fireworks_at_location(loc, config)`	location, table	entity 或 nil	生成烟花
`spawn_splash_potion_at_location(loc, config)`	location, table	entity 或 nil	生成喷溅药水

效果和工具

方法	参数	返回值	描述
`play_sound_at_location(loc, sound, volume?, pitch?)`	location, string (Sound), float?=1, float?=1	nil	播放声音
`spawn_particle_at_location(loc, particle, count?)`	location, string (Particle) 或 table, int?=1	nil	生成粒子
`strike_lightning_at_location(loc)`	location	nil	劈下闪电（绕过 EM 保护）
`run_empowered_lightning_task_at_location(loc)`	location	nil	强化闪电效果
`generate_fake_explosion(locations, center?)`	table of locations, location	nil	无伤害的视觉爆炸
`spawn_fake_gold_nugget_at_location(loc, velocity, gravity?)`	location, vector, bool?=false	fake projectile	生成视觉金粒投射物
`run_fake_gold_nugget_damage(projectiles)`	table	nil	对假投射物执行伤害检测
`set_world_time(time) or (loc, time)`	long，或 location + long	nil	设置世界时间
`set_world_weather(weather, duration?) or (loc, weather, duration?)`	string (CLEAR, RAIN, PRECIPITATION, THUNDER), int?=6000	nil	设置天气
`run_console_command(command)`	string	nil	执行控制台命令
`generate_player_loot(level?)`	int?=1	nil	为伤害者生成战利品
`drop_bonus_coins(multiplier?)`	double?=2	nil	在 Boss 位置掉落额外金币

context.settings（EliteMobs）

方法	参数	返回值	描述
`warning_visual_effects_enabled()`	—	bool	配置中是否启用了警告视觉效果

EliteMobs 事件表

context.event 表传递给伤害和生成钩子。字段因事件类型而异。

字段 / 方法	类型	存在条件	描述
`damage_amount`	double	伤害事件	原始伤害量
`damage_cause`	string	伤害事件	DamageCause 名称
`damager`	entity table	实体造成伤害事件	造成伤害的实体
`projectile`	entity table	投射物伤害事件	造成伤害的投射物
`spawn_reason`	string	生成事件	生成原因名称
`entity`	entity table	死亡/区域事件	相关实体
`cancel_event()`	method	大多数事件	取消事件
`set_damage_amount(amount)`	method (double)	伤害事件	覆盖伤害量
`multiply_damage_amount(multiplier)`	method (double)	伤害事件	乘以当前伤害

context.item FMM

在 FMM 物品脚本中访问。通过 PDC 标签从玩家装备的槽位解析特定的脚本化物品。

属性

字段	类型	描述
`id`	string	物品的脚本标识符

方法

方法	参数	返回值	描述
`material()`	—	string	Material 名称
`get_amount()`	—	int	堆叠数量
`set_amount(n)`	int	nil	设置堆叠数量
`consume(n?)`	int?=1	nil	减少数量 n，为零时移除
`get_uses()`	—	int	PDC 存储的使用计数器
`set_uses(n)`	int	nil	设置 PDC 使用计数器
`get_durability()`	—	table 或 nil	返回 `current` 和 `max` 字段，无耐久条时返回 nil
`get_durability_percentage()`	—	number 或 nil	0.0--1.0 剩余比例，或 nil
`use_durability(amount, can_break?)`	int, bool?=false	nil	按固定值减少耐久度。为 false 时最低保留 1
`use_durability_percentage(fraction, can_break?)`	number, bool?=false	nil	按最大值比例减少耐久度（0.0--1.0）
`get_name()`	—	string 或 nil	显示名称
`set_name(s)`	string	nil	设置显示名称。支持颜色代码
`get_lore()`	—	table	描述字符串数组
`set_lore(table)`	table	nil	从字符串数组设置描述

context.prop FMM

在 FMM 道具脚本中访问。从支撑盔甲架继承所有实体字段。

属性

字段	类型	描述
`model_id`	string	蓝图模型名称
`current_location`	location	道具当前位置

方法

方法	参数	返回值	描述
`play_animation(name, blend?, loop?)`	string, bool?=true, bool?=true	bool	播放命名动画
`stop_animation()`	—	nil	停止所有当前动画
`hurt_visual()`	—	nil	红色闪烁，不造成伤害
`pickup()`	—	nil	移除道具并掉落放置物品
`has_mount_points()`	—	bool	道具是否有挂载点骨骼
`mount(player)`	entity table	bool	将玩家挂载到第一个可用座位
`dismount(player)`	entity table	bool	解除玩家挂载
`get_passengers()`	—	table	已挂载玩家的实体表数组
`spawn_elitemobs_boss(file, x, y, z)`	string, num, num, num	entity 或 nil	生成 EliteMobs Boss（需要 EliteMobs）
`open_inventory(player, title, rows?)`	entity table, string, int?=3	bool	打开持久化箱子背包（1--6 行）。标题支持颜色代码
`place_book(player)`	entity table	bool	将玩家手持的成书存储到道具上
`read_book(player)`	entity table	bool	打开存储的书供阅读
`take_book(player)`	entity table	bool	将存储的书归还给玩家
`has_book()`	—	bool	是否存储了书
`drop_inventory()`	—	bool	掉落所有存储的物品并清空
`drop_book()`	—	bool	掉落存储的书并清空
`is_viewing_inventory(player)`	entity table	bool	玩家是否打开了此道具的背包
`set_persistent_data(key, value)`	string, string	bool	在道具的 PDC 中存储字符串
`get_persistent_data(key)`	string	string 或 nil	从道具的 PDC 中获取字符串

颜色代码

所有标记为支持颜色代码的方法使用 Magmacore 的 ChatColorConverter。这些格式可以在任何字符串中自由混合：

传统代码

使用 & 后跟颜色/格式字符：

代码	颜色	代码	格式
`&0`	黑色	`&l`	粗体
`&1`	深蓝	`&m`	~~删除线~~
`&2`	深绿	`&n`	下划线
`&3`	深青	`&o`	斜体
`&4`	深红	`&r`	重置
`&5`	深紫
`&6`	金色
`&7`	灰色
`&8`	深灰
`&9`	蓝色
`&a`	绿色
`&b`	青色
`&c`	红色
`&d`	浅紫
`&e`	黄色
`&f`	白色

十六进制颜色

使用 6 位十六进制的精确 RGB 颜色：

&#FF5500          -- ampersand prefix
<#FF5500>         -- tag syntax

渐变

在文本中平滑插值两种或多种颜色：

<gradient:#FF0000:#0000FF>This text fades red to blue</gradient>
<g:#FF0000:#00FF00:#0000FF>Three-color gradient</g>

简写形式 g 与 gradient 功能完全相同。你可以链接任意数量的颜色停靠点。

彩虹

循环完整色相光谱。可选饱和度（0--100）：

<rainbow>Full rainbow text</rainbow>
<r:50>Pastel rainbow (50% saturation)</r>

通用类型

location

{ x = number, y = number, z = number, yaw = number, pitch = number, world = string }

vector

{ x = number, y = number, z = number }

entity table

任何带有 uuid 字段的表。来自 context 的玩家和实体表可直接使用：

context.player                              -- valid entity table
context.world:get_nearby_entities(x,y,z,r)  -- returns array of entity tables

实体表 GLOBAL​

属性​

方法​

桥接：entity.elite​

桥接：entity.model​

生物实体表 GLOBAL​

属性​

方法​

context.player GLOBAL​

属性​

方法​

context.world GLOBAL​

属性​

方法​

context.boss ELITEMOBS​

属性​

方法​

summon_projectile 选项​

区域/粒子方法​

特殊技能支持​

EliteMobs 生物实体表 ELITEMOBS​

属性​

方法​

set_equipment 选项​

EliteMobs 玩家方法​

EliteMobs 实体引用表​

context.players ELITEMOBS​

context.entities ELITEMOBS​

context.vectors ELITEMOBS​

context.cooldowns GLOBAL​

context.scheduler GLOBAL​

全局（Magmacore）变体​

EliteMobs 变体​

context.log GLOBAL​

context.zones GLOBAL​

全局（Magmacore）变体​

EliteMobs 变体​

context.event GLOBAL​

全局（Magmacore）变体​

context.script ELITEMOBS​

方法​

Target Handle​

Zone Handle​

Vector Handle​

context.world（EliteMobs） ELITEMOBS​

方块查询​

方块操作​

生成​

效果和工具​

context.settings（EliteMobs）​

EliteMobs 事件表​

context.item FMM​

属性​

方法​

context.prop FMM​

属性​

方法​

颜色代码​

传统代码​

十六进制颜色​

渐变​

彩虹​

通用类型​

location​

vector​

entity table​

实体表 GLOBAL

属性

方法

桥接：entity.elite

桥接：entity.model

生物实体表 GLOBAL

属性

方法

context.player GLOBAL

属性

方法

context.world GLOBAL

属性

方法

context.boss ELITEMOBS

属性

方法

summon_projectile 选项

区域/粒子方法

特殊技能支持

EliteMobs 生物实体表 ELITEMOBS

属性

方法

set_equipment 选项

EliteMobs 玩家方法

EliteMobs 实体引用表

context.players ELITEMOBS

context.entities ELITEMOBS

context.vectors ELITEMOBS

context.cooldowns GLOBAL

context.scheduler GLOBAL

全局（Magmacore）变体

EliteMobs 变体

context.log GLOBAL

context.zones GLOBAL

全局（Magmacore）变体

EliteMobs 变体

context.event GLOBAL

全局（Magmacore）变体

context.script ELITEMOBS

方法

Target Handle

Zone Handle

Vector Handle

context.world（EliteMobs） ELITEMOBS

方块查询

方块操作

生成

效果和工具

context.settings（EliteMobs）

EliteMobs 事件表

context.item FMM

属性

方法

context.prop FMM

属性

方法

颜色代码

传统代码

十六进制颜色

渐变

彩虹

通用类型

location

vector

entity table