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"）。

Entity Table GLOBAL

所有實體表上都存在的基本欄位 — 玩家、怪物、道具等所有實體。

屬性

欄位	類型	說明
`uuid`	string	實體 UUID
`entity_type`	string	實體類型（小寫）
`is_valid`	bool	實體是否仍存在於世界中
`is_dead`	bool	實體已死亡
`is_player`	bool	是否為玩家
`is_hostile`	bool	是否為怪物
`is_passive`	bool	是否為動物
`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	移除模型實體

Living Entity Table GLOBAL

繼承 Entity Table。套用於所有生物實體（怪物和玩家）。

屬性

欄位	類型	說明
`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

玩家實體表。繼承所有 Entity 和 Living Entity 欄位。

屬性

欄位	類型	說明
`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	世界時間（以刻為單位）
`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 欄位
`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	在位置自然掉落物品實體
`spawn_firework(x, y, z, colors, type?, power?)`	num, num, num, table, string (FireworkEffect.Type)?=BALL, int?=1	nil	生成煙火

context.boss ELITEMOBS

EliteMobs Lua 能力腳本的 Boss 實體表。繼承所有 EliteMobs Living Entity 方法。屬性透過專用 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	指定刻後自動移除
`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	強制著地回呼前的最大刻數

區域/粒子方法

方法	參數	回傳	說明
`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 Living Entity Table ELITEMOBS

在 EliteMobs 能力腳本內建立的實體表（來自 context.boss、事件資料、區域回呼和世界查詢）使用擴展的生物實體表，在全域 Living Entity 之上包含額外方法。context.boss 繼承所有這些方法。

屬性

欄位	類型	說明
`name`	string	實體顯示名稱
`uuid`	string	實體 UUID
`entity_type`	string	實體類型名稱
`is_player`	bool	是否為玩家
`is_monster`	bool	是否為怪物
`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 刻後自動恢復
`set_awareness_enabled(enabled, duration?)`	bool, int?=0	nil	設定怪物感知。指定 duration 刻後自動恢復
`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 刻後自動恢復為 1.0
`set_invulnerable(enabled, duration?)`	bool, int?=0	nil	設定無敵。指定 duration 刻後自動恢復
`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	添加冰凍視覺效果刻數
`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 刻後自動隱藏。支援顏色代碼
`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

冷卻時間管理。本地冷卻時間為每個腳本實例獨立計算；全域冷卻時間在同一實體/擁有者的所有腳本之間共享。如果未提供鍵值，則預設為腳本的檔案名稱。

方法	參數	回傳	說明
`local_ready(key?)`	string（可選）	bool	本地冷卻時間是否已過期
`local_remaining(key?)`	string（可選）	int	本地冷卻時間剩餘刻數（就緒時為 0）
`check_local(key?, duration)`	string（可選）, int	bool	如果就緒，啟動冷卻時間並回傳 true；否則回傳 false
`set_local(duration, key?)`	long, string（可選）	nil	設定本地冷卻時間持續指定刻數
`global_ready()`	—	bool	全域冷卻時間是否已過期
`set_global(duration)`	long	nil	設定全域冷卻時間持續指定刻數

在 EliteMobs 能力腳本中，本地冷卻時間在同一 Boss 實體的所有能力之間共享，全域冷卻時間使用 Boss 內建的能力冷卻系統。

context.scheduler GLOBAL

任務排程。所有任務在腳本關閉時自動取消。

Global（Magmacore）變體

方法	參數	回傳	說明
`run_later(ticks, callback)`	int, function	int	在指定刻數後執行回呼。回傳任務 ID
`run_repeating(delay, interval, callback)`	int, int, function	int	在初始延遲後，每隔指定刻數執行回呼。回傳任務 ID
`cancel(taskId)`	int	nil	取消已排程的任務

EliteMobs 變體

方法	參數	回傳	說明
`run_after(ticks, callback)`	int, function	int	在指定刻數後執行回呼。回傳任務 ID
`run_every(ticks, callback)`	int, function	int	每 N 刻執行回呼。回傳任務 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

區域建立與監控。在所有腳本類型中可用。

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 中）。

Global（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 or vector handle, bool?=false	nil	以速度推動目標實體
`set_facing(target, vector)`	target handle, vector or vector handle	nil	設定目標實體的面朝方向
`spawn_particles(target, particles)`	target handle, table or string	nil	在目標位置生成粒子效果

Target Handle

由 context.script:target(spec) 回傳。規格表使用與 Elite Script YAML 目標設定相同的鍵值（例如 {targetType = "NEARBY_PLAYERS", range = 20}）。

方法	參數	回傳	說明
`entities()`	—	table	目標處的實體陣列
`locations()`	—	table	目標處的位置陣列
`first_entity()`	—	entity or nil	目標處的第一個實體
`first_location()`	—	location or 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 能力腳本的擴展世界表。在全域 world 表之上添加 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 道具腳本中存取。從支撐的盔甲架繼承所有 Entity 欄位。

屬性

欄位	類型	說明
`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

Entity Table GLOBAL​

屬性​

方法​

橋接：entity.elite​

橋接：entity.model​

Living Entity Table GLOBAL​

屬性​

方法​

context.player GLOBAL​

屬性​

方法​

context.world GLOBAL​

屬性​

方法​

context.boss ELITEMOBS​

屬性​

方法​

summon_projectile 選項​

區域/粒子方法​

特殊能力支援​

EliteMobs Living Entity Table ELITEMOBS​

屬性​

方法​

set_equipment 選項​

EliteMobs 玩家方法​

EliteMobs 實體引用表​

context.players ELITEMOBS​

context.entities ELITEMOBS​

context.vectors ELITEMOBS​

context.cooldowns GLOBAL​

context.scheduler GLOBAL​

Global（Magmacore）變體​

EliteMobs 變體​

context.log GLOBAL​

context.zones GLOBAL​

Global（Magmacore）變體​

EliteMobs 變體​

context.event GLOBAL​

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​

Entity Table GLOBAL

屬性

方法

橋接：entity.elite

橋接：entity.model

Living Entity Table GLOBAL

屬性

方法

context.player GLOBAL

屬性

方法

context.world GLOBAL

屬性

方法

context.boss ELITEMOBS

屬性

方法

summon_projectile 選項

區域/粒子方法

特殊能力支援

EliteMobs Living Entity Table ELITEMOBS

屬性

方法

set_equipment 選項

EliteMobs 玩家方法

EliteMobs 實體引用表

context.players ELITEMOBS

context.entities ELITEMOBS

context.vectors ELITEMOBS

context.cooldowns GLOBAL

context.scheduler GLOBAL

Global（Magmacore）變體

EliteMobs 變體

context.log GLOBAL

context.zones GLOBAL

Global（Magmacore）變體

EliteMobs 變體

context.event GLOBAL

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