Lua 腳本：鉤子與生命週期

本頁涵蓋 Lua 能力可以定義的每個鉤子、鉤子執行順序、每個 Boss 如何取得自己的隔離執行階段，以及沙盒中可用的標準函式庫函式。

如果你還沒有編寫過 Lua 能力，請先從入門指南開始。

---

鉤子參考

Every Lua power file returns a table. Each key in that table (besides api_version and priority) must be one of the hooks listed below. The runtime calls the matching function whenever the corresponding game event fires.

Hook	Fires when	context.player available?
on_spawn	The elite mob spawns	No
on_game_tick	Once every server tick (50 ms) while the runtime clock is active	No
on_boss_damaged	The boss takes damage from any source	No
on_boss_damaged_by_player	The boss takes damage from a player	Yes
on_boss_damaged_by_elite	The boss takes damage from another elite mob	No
on_player_damaged_by_boss	A player takes damage from this boss	Yes
on_enter_combat	The boss enters combat	Yes
on_exit_combat	The boss leaves combat	No
on_heal	The boss heals	No
on_boss_target_changed	The boss switches its target	Yes
on_death	The boss dies	No
on_phase_switch	A phase boss switches to a new phase	No

When context.player is listed as "No", accessing it returns nil. Always nil-check before using it.

典型的多鉤子能力

A single Lua power can define as many hooks as it needs. Below is a skeleton that uses three hooks together:

return {
  api_version = 1,

  on_enter_combat = function(context)
    -- Initialize per-fight state when combat begins
    context.state.hit_count = 0
    context.log:info("Combat started!")
  end,

  on_boss_damaged_by_player = function(context)
    -- Track hits and trigger an ability every 5th hit
    context.state.hit_count = (context.state.hit_count or 0) + 1
    if context.state.hit_count % 5 ~= 0 then
      return
    end
    if not context.cooldowns.check_local("counter_attack", 100) then
      return
    end
    -- Fire a projectile back at the player
    local origin = context.boss:get_location()
    origin:add(0, 1, 0)
    context.boss:summon_projectile(
      "SMALL_FIREBALL", origin, context.player:get_location(), 1.5
    )
  end,

  on_death = function(context)
    -- Spawn a firework on death
    context.world:spawn_particle_at_location(
      context.boss:get_location(), "EXPLOSION_EMITTER", 1
    )
  end
}

---

鉤子執行順序

When a boss has multiple Lua powers attached, each power's hook is called for the same event. The order is determined by the priority field:

• Lower values run first (default is 0).
• Powers with the same priority run in load order (effectively unspecified).

return {
  api_version = 1,
  priority = -10, -- runs before most other powers

  on_boss_damaged_by_player = function(context)
    -- This runs early, so other powers see any state changes we make
    context.state.last_attacker = context.player.uuid
  end
}

Priority only affects ordering among Lua powers on the same boss. It does not interact with EliteScript execution order.

---

執行階段模型

每個 Boss 一個執行階段

Every boss entity gets its own independent Lua runtime instance. When the boss spawns, EliteMobs loads the Lua source, evaluates it in a fresh sandboxed environment, and stores the returned table. When the boss despawns or is removed, the runtime is shut down.

This means:

• Global Lua variables set during file evaluation (like helper functions with local function) are private to that boss.
• The returned table's hook functions are never shared between bosses.

狀態隔離

Each runtime has its own context.state table. One boss's state is completely invisible to every other boss, even if they share the same Lua power file. Use context.state to store counters, flags, timers, or any per-boss data you need across hooks.

return {
  api_version = 1,

  on_boss_damaged_by_player = function(context)
    -- Each boss tracks its own enrage counter independently
    context.state.enrage_hits = (context.state.enrage_hits or 0) + 1
    if context.state.enrage_hits >= 20 then
      context.boss:apply_potion_effect("SPEED", 200, 2)
    end
  end
}

排程任務所有權

All tasks created through context.scheduler are owned by the runtime that created them. When a boss despawns:

1. The runtime calls shutdown().
2. Every owned task -- both one-shot (run_after) and repeating (run_every) -- is automatically cancelled.
3. All zone watches are cleared.

You never need to manually clean up scheduled tasks on boss removal. However, you should still cancel repeating tasks when they are no longer needed during normal gameplay to avoid unnecessary work:

return {
  api_version = 1,

  on_enter_combat = function(context)
    local pulse_count = 0
    local task_id
    task_id = context.scheduler:run_every(20, function(tick_context)
      pulse_count = pulse_count + 1
      if pulse_count > 10 or not tick_context.boss.exists then
        tick_context.scheduler:cancel_task(task_id)
        return
      end
      tick_context.world:spawn_particle_at_location(
        tick_context.boss:get_location(),
        { particle = "FLAME", amount = 20, speed = 0.1 }
      )
    end)
  end
}

每 Tick 時鐘行為

The internal tick clock for a Lua power instance only runs when there is a reason to tick. Specifically, the clock is registered when either:

• The power defines an on_game_tick hook, or
• The power has created at least one zone watch via context.zones:watch_zone(...).

If neither condition is true, no per-tick overhead is incurred. The clock is unregistered automatically when the boss despawns or the runtime shuts down.

---

錯誤和效能行為

EliteMobs enforces strict error and performance limits on Lua powers:

例外

If a hook function or a scheduled callback throws a Lua error (or a Java exception surfaces from an API call), the power is immediately disabled for that boss instance. The runtime is shut down and all owned tasks are cancelled.

The error is logged to the server console along with the filename of the power:

[EliteMobs] Lua power frost_cone.lua failed while handling on_boss_damaged_by_player.

執行預算

Every hook invocation and every callback invocation is timed. If a single call takes longer than 50 milliseconds, the power is disabled with a console warning:

[EliteMobs] Lua power my_power.lua exceeded the 50ms execution budget on on_game_tick and was disabled.

This prevents runaway scripts from freezing the server. To stay within budget:

• Avoid unbounded loops inside hooks. Use context.scheduler:run_every(...) to spread work across ticks.
• Keep on_game_tick handlers lightweight -- they run every single tick.
• Move heavy initialization into on_spawn or on_enter_combat rather than repeating it every tick.

---

Lua 沙盒

Lua powers run inside a sandboxed LuaJ environment. Several globals that could access the filesystem or the Java runtime are removed.

已移除的全域變數

The following standard Lua globals are set to nil and cannot be used:

Removed	Why
debug	Exposes internal VM state
dofile	Filesystem access
io	Filesystem access
load	Arbitrary code loading
loadfile	Filesystem access
luajava	Direct Java class access
module	Module system (not needed)
os	Operating system access
package	Module system (not needed)
require	Module system / filesystem access

可用的標準函式庫

Everything else from the Lua standard library works normally:

Category	Functions
Math	math.abs, math.ceil, math.floor, math.max, math.min, math.random, math.sin, math.cos, math.sqrt, math.pi, and all other math.* functions
String	string.byte, string.char, string.find, string.format, string.gsub, string.len, string.lower, string.match, string.rep, string.sub, string.upper, and all other string.* functions
Table	table.insert, table.remove, table.sort, table.concat, and all other table.* functions
Iterators	pairs, ipairs, next
Type	type, tostring, tonumber, select, unpack
Error handling	pcall, xpcall, error, assert
Other	print, rawget, rawset, rawequal, rawlen, setmetatable, getmetatable

提示

print writes to the server console, but prefer context.log:info(msg) or context.log:warn(msg) for output. These are prefixed with the power name, making it easier to trace which power produced the message.

---

em 輔助命名空間

The em table is available at file load time (before any hook runs). It provides helper constructors for building location tables, vector tables, and zone definitions used throughout the API.

Function	Purpose
em.create_location(x, y, z [, world, yaw, pitch])	Create a location table with optional world name, yaw, and pitch
em.create_vector(x, y, z)	Create a vector table
em.zone.create_sphere_zone(radius)	Create a sphere zone definition
em.zone.create_dome_zone(radius)	Create a dome zone definition
em.zone.create_cylinder_zone(radius, height)	Create a cylinder zone definition
em.zone.create_cuboid_zone(x, y, z)	Create a cuboid zone definition
em.zone.create_cone_zone(length, radius)	Create a cone zone definition
em.zone.create_static_ray_zone(length, thickness)	Create a static ray zone definition
em.zone.create_rotating_ray_zone(length, point_radius, animation_duration)	Create a rotating ray zone definition
em.zone.create_translating_ray_zone(length, point_radius, animation_duration)	Create a translating ray zone definition

Zone builders return chainable tables with :set_center(loc) (or :set_origin(loc) / :set_destination(loc) depending on zone type). These are designed to be used at the top of a file or inside hooks:

-- At file scope: create a reusable zone shape
local blast_zone = em.zone.create_sphere_zone(5)

return {
  api_version = 1,

  on_boss_damaged_by_player = function(context)
    -- Anchor the zone to the boss's current location at call time
    blast_zone:set_center(context.boss:get_location())

    local entities = context.zones:get_entities_in_zone(blast_zone)
    for i = 1, #entities do
      if entities[i].type == "PLAYER" then
        entities[i]:apply_potion_effect("SLOWNESS", 60, 1)
      end
    end
  end
}

For a full breakdown of zone shapes, filters, watchers, and targeting patterns, see Zones & Targeting.

---

後續步驟

• Boss & Entities -- context.boss, context.player, entity wrappers
• World & Environment -- particles, sounds, spawning, context.world
• Zones & Targeting -- native zones, script utilities, context.zones / context.script
• Examples & Patterns -- complete working powers you can study and adapt
• Enums & Values -- Spigot Javadoc links for all string constants