Lua 腳本：世界與環境

本頁涵蓋 context.world、context.vectors、context.settings 和 context.event 上可用的每個方法。這些讓你的 Lua 能力能夠與 Minecraft 世界互動 -- 生成實體、播放效果、查詢方塊等。如果你是 Lua 能力新手，請先從入門指南開始。

EliteMobs boss context

EliteMobs 的 Boss 能力沿用 MagmaCore 的 Lua 沙箱。Boss 的 context.world 是從共用的 MagmaCore world 表衍生而來，因此像 get_block_at(...)、set_block_at(...) 與 spawn_particle(...) 這類通用的座標輔助函式仍然可用。本頁著重於 EliteMobs Boss 專屬的 context.world、context.vectors、context.settings 與 context.event 新增項目與覆寫。關於通用的 world API，請參閱 MagmaCore Lua 腳本引擎。

`context.world`

world 表提供了生成實體、播放效果、修改方塊與變更世界狀態的方法。所有方法都以冒號語法呼叫（world:method()）。

`world:spawn_particle_at_location(location, particleSpec)`

在某個位置生成粒子。第二個引數可以是單純的粒子名稱字串，也可以是完整的粒子規格表以進行進階控制。

參數	類型	說明
`location`	location 表	要在哪裡生成粒子
`particleSpec`	string 或 table	粒子名稱，或一個粒子規格表（見下方）

範例

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Simple particle by name
    context.world:spawn_particle_at_location(context.boss:get_location(), "FLAME")

    -- Full particle spec table with red dust
    context.world:spawn_particle_at_location(context.boss:get_location(), {
      particle = "DUST",
      amount = 10,
      x = 0.5,
      y = 0.5,
      z = 0.5,
      speed = 0.02,
      red = 255,
      green = 0,
      blue = 0,
    })
  end
}

粒子規格表格式

欄位	類型	預設值	說明
`particle`	string	必填	粒子名稱
`amount`	int	1	粒子數量
`x`、`y`、`z`	number	0	各軸上的散布/偏移量
`speed`	number	0	粒子速度
`red`、`green`、`blue`	int	255	用於 `DUST` 與 `DUST_COLOR_TRANSITION` 的 RGB 顏色
`toRed`、`toGreen`、`toBlue`	int	255	`DUST_COLOR_TRANSITION` 的漸變目標顏色

提示

對於 DUST_COLOR_TRANSITION，你也可以使用 snake_case 的鍵：to_red、to_green、to_blue。

注意

與 EliteScript 的 YAML 設定不同，Lua 的粒子名稱不支援舊式粒子名稱轉換。你必須使用目前的 Spigot API 名稱（例如 FIREWORK 而非 FIREWORKS_SPARK、SMOKE 而非 SMOKE_NORMAL、DUST 而非 REDSTONE）。完整的現行名稱清單及其舊式對應，請參閱有效粒子清單。

`world:play_sound_at_location(location, sound, volume, pitch)`

在某個位置播放音效。

參數	類型	預設值	說明
`location`	location 表		要在哪裡播放音效
`sound`	string		Minecraft 音效鍵（例如 `"entity.blaze.shoot"`），或 Spigot 的 `Sound` 列舉名稱。資源包的鍵也適用。
`volume`	number	`1.0`	音量
`pitch`	number	`1.0`	音高

範例

return {
  api_version = 1,
  on_spawn = function(context)
    context.world:play_sound_at_location(
      context.boss:get_location(),
      "entity.wither.spawn",
      1.0,
      0.5
    )
  end
}

`world:strike_lightning_at_location(location)`

在某個位置降下閃電（有視覺效果並造成傷害）。

參數	類型	說明
`location`	location 表	要在哪裡降下閃電

範例

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if not context.cooldowns:check_local("lightning", 100) then return end
    context.world:strike_lightning_at_location(context.player:get_location())
    context.player:send_message("&eA bolt of lightning strikes you!")
  end
}

`world:spawn_entity_at_location(entityType, location, options)`

生成一個原版 Minecraft 實體。

參數	類型	說明
`entityType`	string	實體類型名稱（例如 `"FIREBALL"`、`"ARROW"`）
`location`	location 表	要在哪裡生成
`options`	table（可選）	生成選項（見下方）

實體生成選項

欄位	類型	預設值	說明
`velocity`	vector 表	`nil`	初始速度 `{x, y, z}`
`effect`	string	`nil`	生成時要播放的 EntityEffect
`duration`	int	`0`	經過這麼多 tick 後自動移除（0 = 永不）
`on_land`	function	`nil`	該實體落地時的回呼
`max_ticks`	int	`6000`	在強制觸發 `on_land` 回呼之前最多監看幾個 tick

傳回一個實體包裝表。

範例

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if not context.cooldowns:check_local("fireball_spawn", 100) then return end
    -- Spawn a fireball aimed at the player
    local boss_loc = context.boss:get_location()
    local dir = context.vectors.get_vector_between_locations(boss_loc, context.player:get_location())
    dir = context.vectors.normalize_vector(dir)

    context.world:spawn_entity_at_location("FIREBALL", boss_loc, {
      velocity = { x = dir.x * 2, y = dir.y * 2, z = dir.z * 2 },
      duration = 100,
    })
  end
}

範例

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Spawn a primed TNT with a landing callback
    context.world:spawn_entity_at_location("TNT", context.boss:get_location(), {
      velocity = { x = 0, y = 1.5, z = 0 },
      on_land = function(land_location, entity_ref)
        context.world:spawn_particle_at_location(land_location, {
          particle = "EXPLOSION_EMITTER",
          amount = 1,
        })
      end,
    })
  end
}

`world:spawn_falling_block_at_location(location, material, options)`

生成一個掉落方塊實體。

參數	類型	說明
`location`	location 表	要在哪裡生成
`material`	string	材質名稱（例如 `"STONE"`、`"MAGMA_BLOCK"`）
`options`	table（可選）	生成選項（見下方）

掉落方塊選項

欄位	類型	預設值	說明
`velocity`	vector 表	`nil`	初始速度 `{x, y, z}`
`drop_item`	boolean	`false`	該方塊是否會以物品形式掉落
`hurt_entities`	boolean	`false`	該方塊是否會傷害被它砸中的實體
`on_land`	function	`nil`	該方塊落地時的回呼 `function(land_location, entity_ref)`

傳回一個實體參考表。

範例

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Rain magma blocks from above
    local loc = context.boss:get_location()
    for i = 1, 5 do
      local offset_loc = {
        x = loc.x + math.random(-3, 3),
        y = loc.y + 10,
        z = loc.z + math.random(-3, 3),
        world = loc.world
      }
      context.world:spawn_falling_block_at_location(offset_loc, "MAGMA_BLOCK", {
        velocity = { x = 0, y = -0.5, z = 0 },
        hurt_entities = true,
        on_land = function(land_location, entity_ref)
          context.world:spawn_particle_at_location(land_location, { particle = "LAVA", amount = 8 })
        end,
      })
    end
  end
}

`world:spawn_custom_boss_at_location(filename, location, options)`

從設定檔生成一個 EliteMobs 自訂 Boss。

參數	類型	說明
`filename`	string	Boss 設定檔名（例如 `"my_boss.yml"`）
`location`	location 表	要在哪裡生成
`options`	table（可選）	生成選項（見下方）

自訂 Boss 生成選項

欄位	類型	預設值	說明
`level`	int	Boss 等級	覆寫所生成 Boss 的等級
`silent`	boolean	`false`	抑制生成訊息
`velocity`	vector 表	`nil`	初始速度
`add_as_reinforcement`	boolean	`false`	註冊為目前 Boss 的增援

傳回一個實體包裝表；若無法建立該 Boss 則傳回 nil。

範例

return {
  api_version = 1,
  on_enter_combat = function(context)
    local minion = context.world:spawn_custom_boss_at_location(
      "skeleton_minion.yml",
      context.boss:get_location(),
      { level = 10, add_as_reinforcement = true }
    )
    if minion ~= nil then
      context.boss:send_message("&cMinions, arise!")
    end
  end
}

`world:spawn_boss_at_location(filename, location, level)`

一個較簡單的 Boss 生成方法。在某個位置生成一個自訂 Boss，等級為可選。

參數	類型	預設值	說明
`filename`	string		Boss 設定檔名
`location`	location 表	Boss 位置	要在哪裡生成（可選，預設為 Boss 位置）
`level`	int	Boss 等級	覆寫生成等級（可選）

傳回一個實體包裝表，或 nil。

範例

return {
  api_version = 1,
  on_enter_combat = function(context)
    context.world:spawn_boss_at_location("zombie_guard.yml", context.boss:get_location(), 5)
    context.boss:send_message("&cGuards, defend me!")
  end
}

`world:spawn_reinforcement_at_location(filename, location, inheritLevel, velocity)`

生成一個由 EliteMobs 增援系統追蹤的增援。

參數	類型	預設值	說明
`filename`	string		Boss 設定檔名
`location`	location 表		要在哪裡生成
`inheritLevel`	int	`0`	等級繼承模式（0 = 預設）
`velocity`	vector 表	`nil`	初始速度（可選）

傳回一個實體包裝表，或 nil。

範例

return {
  api_version = 1,
  on_enter_combat = function(context)
    context.world:spawn_reinforcement_at_location(
      "necro_skeleton.yml",
      context.boss:get_location(),
      0,
      { x = 0, y = 0.5, z = 0 }
    )
    context.boss:send_message("&5Rise, my servant!")
  end
}

`world:spawn_fireworks_at_location(location, spec)`

生成一個煙火實體，並可完整控制其效果。

參數	類型	說明
`location`	location 表	要在哪裡生成
`spec`	table	煙火規格（見下方）

煙火規格表

欄位	類型	預設值	說明
`power`	int	`1`	飛行力道（高度）
`velocity`	vector 表	`nil`	初始速度
`shot_at_angle`	boolean	`true`	該煙火是否以角度射出（設定 velocity 時使用）
`effects`	表的表	`nil`	煙火效果規格的陣列。若省略，最上層的規格會被視為單一效果。

煙火效果規格

欄位	類型	預設值	說明
`type`	string	`"BALL_LARGE"`	`"BALL"`、`"BALL_LARGE"`、`"STAR"`、`"BURST"`、`"CREEPER"`
`flicker`	boolean	`true`	閃爍效果
`trail`	boolean	`true`	拖尾效果
`colors`	table	`nil`	顏色名稱或 `{red, green, blue}` 表的陣列
`fade_colors`	table	`nil`	淡出顏色名稱或 `{red, green, blue}` 表的陣列

顏色名稱："WHITE", "SILVER", "GRAY", "BLACK", "RED", "MAROON", "YELLOW", "OLIVE", "LIME", "GREEN", "AQUA", "TEAL", "BLUE", "NAVY", "FUCHSIA", "PURPLE", "ORANGE"

傳回一個實體參考表。你可以對它呼叫 :detonate() 以強制立即引爆。

範例

return {
  api_version = 1,
  on_spawn = function(context)
    local fw = context.world:spawn_fireworks_at_location(context.boss:get_location(), {
      power = 0,
      effects = {
        {
          type = "STAR",
          flicker = true,
          trail = true,
          colors = { "RED", "ORANGE", { red = 255, green = 200, blue = 0 } },
          fade_colors = { "YELLOW" },
        },
      },
    })

    -- Detonate immediately for a visual burst
    context.scheduler:run_after(1, function()
      fw:detonate()
    end)
  end
}

`world:spawn_splash_potion_at_location(location, spec)`

生成一個投擲出去的噴濺藥水實體。

參數	類型	說明
`location`	location 表	要在哪裡生成
`spec`	table	藥水規格（見下方）

噴濺藥水規格表

欄位	類型	說明
`velocity`	vector 表	投擲藥水的初始速度
`effects`	表的表	藥水效果規格的陣列

藥水效果規格

欄位	類型	預設值	說明
`type`	string	必填	藥水效果類型名稱（例如 `"SLOWNESS"`、`"POISON"`）
`duration`	int	`0`	持續時間，以 tick 計
`amplifier`	int	`0`	效果強度（0 = 等級 I）
`overwrite`	boolean	`true`	是否覆寫同類型的既有效果

傳回一個實體參考表，或 nil。

範例

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if not context.cooldowns:check_local("potion_throw", 200) then return end

    local dir = context.vectors.get_vector_between_locations(
      context.boss:get_location(),
      context.player:get_location()
    )
    dir = context.vectors.normalize_vector(dir)

    context.world:spawn_splash_potion_at_location(context.boss:get_location(), {
      velocity = { x = dir.x * 1.5, y = 0.5, z = dir.z * 1.5 },
      effects = {
        { type = "SLOWNESS", duration = 100, amplifier = 1 },
        { type = "WEAKNESS", duration = 60, amplifier = 0 },
      },
    })
  end
}

`world:place_temporary_block_at_location(location, material, duration, requireAir)`

放置一個暫時方塊，經過一段時間後會自動還原。

參數	類型	預設值	說明
`location`	location 表		要放置在哪裡
`material`	string		材質名稱
`duration`	int	`0`	該方塊還原前的 tick 數（0 = 永久）
`requireAir`	boolean	`false`	若為 `true`，只有在該方塊目前是空氣時才放置

範例

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Create a temporary ice floor under the boss
    local loc = context.boss:get_location()
    for dx = -2, 2 do
      for dz = -2, 2 do
        context.world:place_temporary_block_at_location(
          { x = loc.x + dx, y = loc.y - 1, z = loc.z + dz, world = loc.world },
          "PACKED_ICE",
          100,
          false
        )
      end
    end
  end
}

`world:set_block_at_location(location, material, requireAir)`

永久設定一個方塊。如果你希望它會還原，請使用 place_temporary_block_at_location。

參數	類型	預設值	說明
`location`	location 表		要放置在哪裡
`material`	string		材質名稱
`requireAir`	boolean	`false`	若為 `true`，只有在該方塊目前是空氣時才放置

範例

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Place fire at the boss's location
    context.world:set_block_at_location(context.boss:get_location(), "FIRE", true)
  end
}

`world:get_block_type_at_location(location)`

以字串傳回某個位置上方塊的材質名稱。

參數	類型	說明
`location`	location 表	要查詢的位置

範例

return {
  api_version = 1,
  on_enter_combat = function(context)
    local block_type = context.world:get_block_type_at_location(context.boss:get_location())
    if block_type == "WATER" then
      context.boss:send_message("&bThe boss is empowered by water!")
      context.boss:apply_potion_effect("SPEED", 200, 1)
    end
  end
}

`world:get_highest_block_y_at_location(location)`

傳回指定 X/Z 位置上最高的非空氣方塊的 Y 座標。

參數	類型	說明
`location`	location 表	要查詢的位置（會使用 X 與 Z）

範例

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if not context.cooldowns:check_local("skyport", 200) then return end
    local loc = context.player:get_location()
    local ground_y = context.world:get_highest_block_y_at_location(loc)
    -- Teleport the player to the surface
    context.player:teleport_to_location({
      x = loc.x, y = ground_y + 1, z = loc.z, world = loc.world
    })
    context.player:send_message("&eYou are teleported to the surface!")
  end
}

`world:get_blast_resistance_at_location(location)`

以數字傳回某個位置上方塊的抗爆性。

參數	類型	說明
`location`	location 表	要查詢的位置

範例

return {
  api_version = 1,
  on_enter_combat = function(context)
    local resistance = context.world:get_blast_resistance_at_location(context.boss:get_location())
    context.log:info("Blast resistance at boss: " .. resistance)
  end
}

`world:is_air_at_location(location)`

如果該位置的方塊是空氣，則傳回 true。

參數	類型	說明
`location`	location 表	要查詢的位置

範例

return {
  api_version = 1,
  on_enter_combat = function(context)
    local loc = context.boss:get_location()
    local above = { x = loc.x, y = loc.y + 2, z = loc.z, world = loc.world }
    if context.world:is_air_at_location(above) then
      -- There is space above the boss, launch upward
      context.boss:set_velocity_vector({ x = 0, y = 1.5, z = 0 })
    end
  end
}

`world:is_passable_at_location(location)`

如果該位置的方塊可通過（實體能從中穿過），則傳回 true。

參數	類型	說明
`location`	location 表	要查詢的位置

範例

return {
  api_version = 1,
  on_enter_combat = function(context)
    if context.world:is_passable_at_location(context.boss:get_location()) then
      context.log:info("Boss is in a passable block")
    end
  end
}

`world:is_passthrough_at_location(location)`

如果該位置的方塊不是固體，則傳回 true（類似於可通過，但依據的是固體檢查）。

參數	類型	說明
`location`	location 表	要查詢的位置

範例

return {
  api_version = 1,
  on_enter_combat = function(context)
    local loc = context.boss:get_location()
    local above = { x = loc.x, y = loc.y + 1, z = loc.z, world = loc.world }
    if context.world:is_passthrough_at_location(above) then
      context.log:info("Boss can move upward")
    end
  end
}

`world:is_on_floor_at_location(location)`

如果該位置的方塊不是固體，而且它下方的方塊是固體，則傳回 true（也就是該位置「站在地板上」）。

參數	類型	說明
`location`	location 表	要查詢的位置

範例

return {
  api_version = 1,
  on_enter_combat = function(context)
    if context.world:is_on_floor_at_location(context.boss:get_location()) then
      context.boss:send_message("&aThe boss slams the ground!")
      context.world:spawn_particle_at_location(context.boss:get_location(), {
        particle = "CLOUD",
        amount = 30,
      })
    end
  end
}

`world:is_standing_on_material(location, material)`

如果該位置正下方的方塊符合指定的材質，則傳回 true。

參數	類型	說明
`location`	location 表	要查詢的位置
`material`	string	要檢查的材質名稱

範例

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if context.world:is_standing_on_material(context.player:get_location(), "SOUL_SAND") then
      context.player:send_message("&8The soul sand saps your strength!")
      context.player:apply_potion_effect("SLOWNESS", 60, 2)
    end
  end
}

`world:set_world_time(time)` / `world:set_world_time(location, time)`

設定世界時間。你可以選擇性地傳入一個位置來指定是哪個世界。

參數	類型	說明
`location`	location 表（可選）	要影響哪個世界。預設為 Boss 所在的世界。
`time`	int	世界時間，以 tick 計（0 = 黎明、6000 = 正午、13000 = 夜晚、18000 = 午夜）

範例

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Set to midnight when combat starts
    context.world:set_world_time(18000)
    context.boss:send_message("&8Darkness falls...")
  end
}

`world:set_world_weather(weather, duration)` / `world:set_world_weather(location, weather, duration)`

設定 Boss 所在世界的天氣。

參數	類型	預設值	說明
`location`	location 表（可選）	Boss 世界	要影響哪個世界
`weather`	string		`"CLEAR"`、`"RAIN"`（或 `"PRECIPITATION"`）、`"THUNDER"`
`duration`	int	`6000`	天氣持續時間，以 tick 計

範例

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Start a thunderstorm for 200 ticks
    context.world:set_world_weather("THUNDER", 200)
    context.boss:send_message("&eA storm gathers!")
  end
}

`world:generate_fake_explosion(blockLocations, sourceLocation)`

使用 EliteMobs 的爆炸再生系統製造一個假爆炸視覺效果（方塊會破壞並再生）。

參數	類型	說明
`blockLocations`	location 表的表	要「爆炸」的方塊位置陣列
`sourceLocation`	location 表（可選）	用於方向計算的爆炸來源

範例

return {
  api_version = 1,
  on_enter_combat = function(context)
    local loc = context.boss:get_location()
    local blocks = {}
    for dx = -1, 1 do
      for dz = -1, 1 do
        table.insert(blocks, { x = loc.x + dx, y = loc.y, z = loc.z + dz, world = loc.world })
      end
    end
    context.world:generate_fake_explosion(blocks, loc)
  end
}

`world:run_console_command(command)`

以伺服器身分執行一個主控台指令。

參數	類型	說明
`command`	string	要執行的指令（不含開頭的 `/`）

範例

return {
  api_version = 1,
  on_enter_combat = function(context)
    context.world:run_console_command("say The boss has entered phase 2!")
  end
}

`world:run_empowered_lightning_task_at_location(location)`

執行強化閃電的視覺任務（供終界龍能力使用）。這會製造出更具戲劇性的閃電，並帶有額外效果。

參數	類型	說明
`location`	location 表	要在哪裡降下閃電

範例

return {
  api_version = 1,
  on_enter_combat = function(context)
    context.world:run_empowered_lightning_task_at_location(context.boss:get_location())
    context.boss:send_message("&eFeel the power of the storm!")
  end
}

`world:spawn_fake_gold_nugget_at_location(location, velocity, hasGravity)`

生成一個彈幕系統所使用的假金粒投射物。

參數	類型	預設值	說明
`location`	location 表		生成位置
`velocity`	vector 表		初始速度
`hasGravity`	boolean	`false`	該投射物是否受重力影響

傳回一個假投射物表，其方法有：get_location()、set_gravity(bool)、remove()、is_removed()。

範例

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if not context.cooldowns:check_local("nugget", 60) then return end

    local dir = context.vectors.get_vector_between_locations(
      context.boss:get_location(),
      context.player:get_location()
    )
    dir = context.vectors.normalize_vector(dir)

    context.world:spawn_fake_gold_nugget_at_location(
      context.boss:get_location(),
      { x = dir.x, y = dir.y, z = dir.z }
    )
  end
}

`world:run_fake_gold_nugget_damage(projectiles)`

為一組假金粒投射物處理對附近實體造成的傷害。

參數	類型	說明
`projectiles`	table	來自 `spawn_fake_gold_nugget_at_location` 的假投射物表陣列

範例

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Spawn some projectiles and store them
    context.state.active_projectiles = {}
    local loc = context.boss:get_location()
    for i = 1, 5 do
      local angle = (i / 5) * math.pi * 2
      local nugget = context.world:spawn_fake_gold_nugget_at_location(
        loc,
        { x = math.cos(angle) * 0.5, y = 0.3, z = math.sin(angle) * 0.5 }
      )
      table.insert(context.state.active_projectiles, nugget)
    end

    -- Process damage each tick for 3 seconds
    local task_id
    task_id = context.scheduler:run_every(1, function(tick_context)
      tick_context.world:run_fake_gold_nugget_damage(tick_context.state.active_projectiles)
    end)
    context.scheduler:run_after(60, function(later_context)
      later_context.scheduler:cancel_task(task_id)
    end)
  end
}

`world:generate_player_loot(times)`

為傷害過該 Boss 的玩家產生戰利品。

參數	類型	預設值	說明
`times`	int	`1`	戰利品擲骰次數

範例

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    local pct = context.boss:get_health() / context.boss:get_maximum_health()
    if pct < 0.5 and not context.boss:has_tag("bonus_loot") then
      context.boss:add_tag("bonus_loot")
      context.world:generate_player_loot(2)
      context.boss:send_message("&6Bonus loot drops!")
    end
  end
}

`world:drop_bonus_coins(multiplier)`

為所有參與傷害該 Boss 的玩家掉落額外金幣。

參數	類型	預設值	說明
`multiplier`	number	`2.0`	金幣數量倍率

範例

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    local pct = context.boss:get_health() / context.boss:get_maximum_health()
    if pct < 0.25 and not context.boss:has_tag("bonus_coins") then
      context.boss:add_tag("bonus_coins")
      context.world:drop_bonus_coins(3.0)
      context.boss:send_message("&6Gold spills everywhere!")
    end
  end
}

`context.vectors`

向量數學輔助函式。這些是以一般函式（點語法）呼叫，而不是方法。

方法	傳回值	說明
`vectors.get_vector_between_locations(loc1, loc2[, options])`	vector 表	從 `loc1` 指向 `loc2` 的方向
`vectors.normalize_vector(vec)`	vector 表	傳回一個單位長度的向量
`vectors.rotate_vector(vec, pitch, yaw)`	vector 表	依 pitch 與 yaw 的度數旋轉一個向量

所有 vector 表都有 x、y、z 欄位。

`vectors.get_vector_between_locations(loc1, loc2, options)`

參數	類型	說明
`loc1`	location 表	起點
`loc2`	location 表	終點
`options`	table（可選）	後處理選項（見下方）

向量選項

欄位	類型	預設值	說明
`normalize`	boolean	`false`	將結果向量正規化
`multiplier`	number	`1.0`	縮放該向量
`offset`	vector 表	`nil`	加上一個偏移向量

範例

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if not context.cooldowns:check_local("dash", 100) then return end
    -- Compute a normalized direction from boss to player, scaled to speed 2
    local dir = context.vectors.get_vector_between_locations(
      context.boss:get_location(),
      context.player:get_location(),
      { normalize = true, multiplier = 2.0 }
    )
    -- Launch the boss toward the player
    context.boss:set_velocity_vector(dir)
  end
}

`vectors.normalize_vector(vec)`

參數	類型	說明
`vec`	vector 表	輸入向量

範例

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    local raw = context.vectors.get_vector_between_locations(
      context.boss:get_location(),
      context.player:get_location()
    )
    local unit = context.vectors.normalize_vector(raw)
    context.log:info("Direction: " .. unit.x .. ", " .. unit.y .. ", " .. unit.z)
  end
}

`vectors.rotate_vector(vec, pitch, yaw)`

參數	類型	說明
`vec`	vector 表	輸入向量
`pitch`	number	繞 X 軸旋轉的度數
`yaw`	number	繞 Y 軸旋轉的度數

範例

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if not context.cooldowns:check_local("spread_shot", 100) then return end
    local forward = context.vectors.normalize_vector(
      context.vectors.get_vector_between_locations(
        context.boss:get_location(),
        context.player:get_location()
      )
    )
    -- Fire three fireballs in a spread pattern
    for _, yaw_offset in ipairs({ -30, 0, 30 }) do
      local dir = context.vectors.rotate_vector(forward, 0, yaw_offset)
      context.boss:summon_projectile(
        "FIREBALL",
        context.boss:get_eye_location(),
        {
          x = context.boss:get_location().x + dir.x * 10,
          y = context.boss:get_location().y + dir.y * 10,
          z = context.boss:get_location().z + dir.z * 10,
          world = context.boss:get_location().world
        },
        1.0
      )
    end
  end
}

提示

你可以在迴圈中旋轉一個基準向量，藉此建立出一組散開的方向：

local base = context.vectors.normalize_vector(
  context.vectors.get_vector_between_locations(boss_loc, target_loc)
)
for angle = 0, 360, 30 do
  local dir = context.vectors.rotate_vector(base, 0, angle)
  -- Use dir for spawning projectiles in a ring
end

`context.settings`

對能力相關設定值的唯讀存取。

方法	傳回值	說明
`settings.warning_visual_effects_enabled`	boolean	怪物戰鬥設定中是否啟用了警告視覺效果

範例

return {
  api_version = 1,
  on_enter_combat = function(context)
    if context.settings:warning_visual_effects_enabled() then
      context.world:spawn_particle_at_location(context.boss:get_location(), {
        particle = "DUST",
        amount = 20,
        red = 255, green = 0, blue = 0,
      })
    end
  end
}

`context.event`

目前掛鉤的事件資料。可用的欄位取決於是哪一個掛鉤觸發了這次呼叫。

欄位或方法	可用時機	說明
`event.damage_amount`	傷害掛鉤	目前的傷害量（呼叫當下的快照）
`event.damage_cause`	傷害掛鉤	Bukkit `DamageCause` 列舉名稱（例如 `"ENTITY_ATTACK"`）
`event.cancel_event()`	可取消的事件	取消該事件
`event.set_damage_amount(value)`	以 `EliteDamageEvent` 為基礎的掛鉤	直接設定傷害值
`event.multiply_damage_amount(multiplier)`	以 `EliteDamageEvent` 為基礎的掛鉤	將目前的傷害乘上倍率
`event.damager`	帶有加害實體的傷害事件	加害者的實體參考包裝物
`event.projectile`	加害者為投射物的傷害事件	投射物的實體參考包裝物
`event.spawn_reason`	`on_spawn`	生成原因的列舉名稱
`event.entity`	`on_death`、區域事件	相關的實體包裝物

範例：把承受的傷害減半

範例

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.event ~= nil then
      local dmg = context.event.damage_amount
      context.log:info("Boss took " .. dmg .. " damage, halving it")
      context.event.multiply_damage_amount(0.5)
    end
  end
}

範例：取消來自投射物的傷害

範例

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.event ~= nil and context.event.damage_cause == "PROJECTILE" then
      context.event.cancel_event()
      if context.player ~= nil then
        context.player:send_message("&cThe boss deflects your projectile!")
      end
    end
  end
}

範例：讀取傷害原因

範例

return {
  api_version = 1,
  on_player_damaged_by_boss = function(context)
    if context.event ~= nil then
      context.log:info("Damage cause: " .. (context.event.damage_cause or "unknown"))
    end
  end
}

備註

damage_amount 是一份快照。在呼叫 set_damage_amount() 或 multiply_damage_amount() 之後，它不會自動更新。
在排程的回呼內，context.event 為 nil。若要修改事件，請使用事件掛鉤。

後續步驟

區域與目標鎖定 -- 區域查詢、觀察器與實體目標鎖定
Boss 與實體 -- Boss 包裝物、實體方法、玩家方法
範例 -- 完整可運作的 Lua 能力範例

context.world
context.vectors
context.settings
context.event
後續步驟

context.world​

world:spawn_particle_at_location(location, particleSpec)​

粒子規格表格式​

world:play_sound_at_location(location, sound, volume, pitch)​

world:strike_lightning_at_location(location)​

world:spawn_entity_at_location(entityType, location, options)​

實體生成選項​

world:spawn_falling_block_at_location(location, material, options)​

掉落方塊選項​

world:spawn_custom_boss_at_location(filename, location, options)​

自訂 Boss 生成選項​

world:spawn_boss_at_location(filename, location, level)​

world:spawn_reinforcement_at_location(filename, location, inheritLevel, velocity)​

world:spawn_fireworks_at_location(location, spec)​

煙火規格表​

煙火效果規格​

world:spawn_splash_potion_at_location(location, spec)​

噴濺藥水規格表​

藥水效果規格​

world:place_temporary_block_at_location(location, material, duration, requireAir)​

world:set_block_at_location(location, material, requireAir)​

world:get_block_type_at_location(location)​

world:get_highest_block_y_at_location(location)​

world:get_blast_resistance_at_location(location)​

world:is_air_at_location(location)​

world:is_passable_at_location(location)​

world:is_passthrough_at_location(location)​

world:is_on_floor_at_location(location)​

world:is_standing_on_material(location, material)​

world:set_world_time(time) / world:set_world_time(location, time)​

world:set_world_weather(weather, duration) / world:set_world_weather(location, weather, duration)​

world:generate_fake_explosion(blockLocations, sourceLocation)​

world:run_console_command(command)​

world:run_empowered_lightning_task_at_location(location)​

world:spawn_fake_gold_nugget_at_location(location, velocity, hasGravity)​

world:run_fake_gold_nugget_damage(projectiles)​

world:generate_player_loot(times)​

world:drop_bonus_coins(multiplier)​

context.vectors​

vectors.get_vector_between_locations(loc1, loc2, options)​

向量選項​

vectors.normalize_vector(vec)​

vectors.rotate_vector(vec, pitch, yaw)​

context.settings​

context.event​

範例：把承受的傷害減半​

範例：取消來自投射物的傷害​

範例：讀取傷害原因​

後續步驟​