建立能力

撰寫能力的兩種方式

以檔案定義的能力存放於 plugins/EliteMobs/powers，包含子資料夾。共有兩種格式：

格式	檔案	適用情境
Lua	`*.lua`	使用 Boss 鉤子、迴圈與狀態撰寫行為。大多數隨附能力使用此格式。
EliteScript	`*.yml`	本頁其餘部分所記載的宣告式事件／動作格式。仍完整支援。

隨附的 71 個能力中，有 68 個使用 Lua。只有 bonus_coins.yml、custom_summon.yml 與 elite_script.yml 仍是以 YAML 為基礎的 Java 能力。撰寫新行為時，請從 Lua 入門指南與 Boss 鉤子與生命週期開始。

兩種格式從 Boss 引用的方式完全相同，都是透過 powers 清單。

所有子資料夾中的檔名都應保持唯一。登錄表使用檔名，而非包含資料夾的路徑，因此子資料夾無法隔離重複名稱。兩個檔案同名時，EliteMobs 會載入完整路徑排序在前的那一個，並為另一個記錄 Duplicate content filename，除非兩個檔案內容完全相同。編輯後執行 /em reload 並檢查載入警告。

.lua 能力優先於同名的 .yml 能力

當 Boss 要求 attack_fire.yml 時，EliteMobs 會先尋找成功載入的 attack_fire.lua。要求 .yaml 時也使用相同規則。Lua 替代檔載入成功後，舊引用即可繼續使用。新設定應直接指定 .lua 檔名，並符合已登錄檔名的大小寫。

預製 .lua 檔案只寫入一次，編輯過的檔案永遠不會被覆寫

只有在 powers 下找不到對應檔案時，才會寫入隨附 Lua 能力。當更新修正了某個隨附能力時，EliteMobs 會列出先前隨附版本的校驗碼。未經編輯且符合其中之一的副本，會被移至 plugins/MagmaCore/outdated files/EliteMobs/，並在同一次啟動時寫入目前版本。你編輯過的檔案永遠不會相符，因此會維持原樣，也不會收到上游修正。請為修改後的副本取獨立檔名，並將保留的預製檔案與打算使用的版本比較。

Lua 區域不會觸發 on_zone_enter / on_zone_leave

兩個鉤子名稱都受支援，但建立 Lua 區域不會觸發它們。內建來源是 EliteScript 區域監聽器：同一 Boss 的 YAML 腳本在 Events: 中列出 ZoneEnterEvent 或 ZoneLeaveEvent 並定義可用區域時，監聽器才會啟動。事件會傳給該 Boss 上所有符合的能力，且不會指出是哪個 YAML 區域觸發。僅在純 Lua Boss 宣告這些鉤子不會讓它們執行。

除非你是刻意要把它與這類 YAML 區域腳本搭配使用，否則請不要圍繞這兩個鉤子建構 Lua 能力。請改用 context.zones:watch_zone(...)（它自己的 on_enter / on_leave 回呼會被直接呼叫）、EliteScript 的 Zone 區塊，或從 on_game_tick 輪詢。請參閱鉤子與生命週期與腳本事件。

EliteMobs 腳本系統

本頁其餘部分介紹了如何建立 Elite 腳本！

這是一項進階功能，需要對 EliteMobs 有深入的了解。

注意：Elite 腳本可以作為能力檔案添加，也可以添加到自訂 Boss 檔案中！ 如果用作能力檔案，你可以像往常一樣使用自訂 Boss 的 powers 設定，將它們作為一般能力添加到 Boss 中。

添加 EliteScript

要開始向 Boss 添加 EliteScript，請在 Boss 檔案中添加以下條目：

eliteScript:

注意：以下內容對大小寫和空格極其敏感！請確保你的空格、換行符和整體格式與範例一致！

現在你已經宣告了腳本的開始，可以添加你的特定腳本了。在此範例中，我們將建立一個名為 Example 的腳本：

eliteScript:
  Example:

EliteScript 有五個部分：Events、Conditions、Zone、Actions 和 Cooldowns。請提供非空的 Actions 清單，讓腳本能執行動作。由其他腳本或落地回呼呼叫的腳本可以省略 Events；若無呼叫端，這種腳本不會自行執行。Conditions 和 Cooldowns 是鍵值對應結構，不是清單。

讓我們看一個簡單的範例：

eliteScript:
  Example:
    Events:
    - EliteMobDamagedByPlayerEvent
    Actions:
    - action: PUSH
      Target:
        targetType: SELF
      vValue: 0,0.5,0
    Cooldowns:
      local: 60
      global: 20

受到符合條件的玩家攻擊時，此腳本會將菁英怪向上推，並啟動 60 tick 的區域冷卻與 20 tick 的全域冷卻。在 20 TPS 下分別為三秒和一秒。全域冷卻只影響會檢查它的能力，不會阻止所有鉤子或動作。事件觸發的 YAML 腳本會在區域或全域值為正數時檢查冷卻。被呼叫腳本的行為請參閱下方冷卻指南。

現在你已經了解了腳本結構的一般格式，是時候學習每個部分可以做什麼了！

事件

點擊上方的連結了解如何使用事件！

目標

點擊上方的連結了解如何使用目標！

動作

點擊上方的連結了解如何使用動作！

區域

點擊上方的連結了解如何使用區域！

條件

點擊上方的連結了解如何使用條件！

冷卻

點擊上方的連結了解如何使用冷卻時間！

添加多個 EliteScripts

你可以在一個事件上擁有多個動作，但如果你想在同一個 Boss 上擁有多個腳本呢？只需建立一個新的腳本條目即可！讓我們擴展前面的範例並添加另一個腳本：

eliteScript:
  Example:
    Events:
    - EliteMobDamagedByPlayerEvent
    Actions:
    - action: PUSH
      Target:
        targetType: SELF
      vValue: 0,0.5,0
    Cooldowns:
      local: 60
      global: 20
  Example2:
    Events:
    - PlayerDamagedByEliteMobEvent
    Actions:
    - action: SET_ON_FIRE
      duration: 20
      Target:
        targetType: DIRECT_TARGET
    Cooldowns:
      local: 200
      global: 60

Example2 使用 DIRECT_TARGET 將受傷玩家點燃 20 tick。其 200 tick 的區域冷卻在 20 TPS 下可阻止此腳本十秒內再次由事件觸發。60 tick 的全域冷卻與檢查 Boss 冷卻的能力共用。其他腳本仍可獨立施加燃燒。

建立獨立能力

將獨立 YAML 能力放入 plugins/EliteMobs/powers。eliteScript 區塊定義行為，下方選用的中繼資料欄位控制載入、分類、顯示與冷卻中繼資料。範例：

isEnabled: true
powerType: UNIQUE
eliteScript:
  Example:
    Events:
    - EliteMobDamagedByPlayerEvent
    Actions:
    - action: PUSH
      Target:
        targetType: SELF
      vValue: 0,.3,0
    Cooldowns:
      local: 60
      global: 20

isEnabled

控制設定的能力是否啟用，預設為 true。對自訂 Lua 而言，停用配套中繼資料檔會阻止探索該 Lua 檔案。隨附 Lua 能力即使配套檔已停用仍會載入，但會被標記為停用，詳見下文。

powerType

能力類型提供預設抽取池與環繞物品環分類所用的類別中繼資料。可用值：

UNIQUE：用於明確指定。自動產生共用清單時會排除它，但仍可手動加入自然能力清單。
DEFENSIVE / MISCELLANEOUS / OFFENSIVE：對應共用清單缺少時，用於產生該清單。是否可分配取決於設定的抽取池、啟用狀態與怪物等級。
MAJOR_ZOMBIE、MAJOR_SKELETON、MAJOR_BLAZE、MAJOR_ENDERMAN、MAJOR_GHAST：這五種計為主要能力，其餘均為次要能力。自然分配使用實體的 majorPowers 清單，不會在執行時檢查類型尾碼是否符合實體。

`powerType` 如何影響自然菁英怪：`EliteMobPowers.yml`

自然菁英怪從 plugins/EliteMobs/EliteMobPowers.yml 抽取能力，而非只依據 powerType。該檔案包含：

鍵	意義
`defensivePowers`	自然菁英怪可隨機抽到的防禦型能力
`offensivePowers`	自然菁英怪可隨機抽到的攻擊型能力
`miscellaneousPowers`	自然菁英怪可隨機抽到的雜項能力
`majorPowers.<ENTITY_TYPE>`	該實體類型可隨機抽到的主要能力
`disabledPowers.<ENTITY_TYPE>`	套用共用清單之後，要從該實體類型移除的能力

缺少的共用防禦、攻擊與雜項清單會以已載入的對應類型能力產生。主要能力預設值依實體類型明確指定。現有清單會保留，因此稍後新增能力不會自動將其加入清單，必須自行編輯。相反地，產生缺少的雜項清單時，已存在的自訂 Lua 能力可能進入該預設抽取池。

這些清單同時接受 .lua 檔名與舊式的 .yml 名稱；產生的預設值是以 .yml 別名寫入的。無法解析到任何能力的名稱會被略過，並在主控台發出指出該檔案與該鍵的警告。

自然能力欄位分別在等級 10、20、30、40 解鎖防禦、攻擊、雜項與主要能力。各類別的第二個欄位在等級 50、60、70、80 解鎖。抽取池為空或停用時，可能取得較少能力。編輯清單不會改變能力的主要／次要分類。

effect

設定能力環繞物品的材質。MAJOR_* 類型使用主要環，其餘類型使用次要環。值必須是物品材質，或不需額外資料的粒子名稱(此時會改以粒子環繞)。其他任何值都會停用此效果，並記錄 Disabled invalid power trail。

未設定 effect 或值為空的能力不會向環中新增物品。自訂 Lua 能力未在選用 YAML 中繼資料檔指定 effect 時，預設如此。

目前，獨立 YAML EliteScript 不會將此中繼資料複製到執行時的軌跡。因此，為這類 YAML 能力設定 effect 不會新增環繞物品。自訂 Lua 能力會複製配套檔中的 effect。

鍵	值	預設值
`effect`	材質	無

powerCooldown

設定能力中繼資料中的冷卻時間，單位為 tick。YAML EliteScript 使用自己的 Cooldowns.local 與 Cooldowns.global，初始化時會取代這些中繼資料值。Lua 能力必須使用文件中的冷卻 API 來檢查與設定冷卻。

鍵	值	預設值
`powerCooldown`	Integer	`0`

globalCooldown

設定全域冷卻中繼資料，單位為 tick。全域冷卻只阻止會檢查它的能力，不會無條件鎖住所有鉤子與動作。對於 YAML 腳本，請設定腳本自己的 Cooldowns 部分。

鍵	值	預設值
`globalCooldown`	Integer	`0`

製作獨立的 Lua 能力

獨立 Lua 能力是放在 plugins/EliteMobs/powers 的 .lua 檔案，包含子資料夾。YAML 中繼資料檔是選用的。

return {
  api_version = 1,
  on_player_damaged_by_boss = function(context)
    if context.player == nil then
      return
    end
    context.player:apply_potion_effect("BLINDNESS", 60, 0)
  end
}

若同一目錄沒有相同主檔名的 .yml 中繼資料檔，自訂 Lua 能力會使用下列預設值：

powerType 為 MISCELLANEOUS。
effect 未設定。

對於自訂 my_power.lua，可在旁邊新增 my_power.yml，包含 isEnabled、powerType、effect、powerCooldown 與 globalCooldown。例如，powerType: UNIQUE 可將其排除於預設雜項抽取池之外。停用中繼資料檔會阻止載入此自訂 Lua 檔案。

隨附預製 Lua 能力旁相同主檔名的 .yml 或 .yaml 檔案同樣會套用到該能力。其中的 isEnabled、effect、powerCooldown 與 globalCooldown 值會取代內建值，包括你省略之鍵的預設值，因此省略 effect 會移除該能力的環繞物品。powerType 只有在設定時才會取代內建類型。停用的檔案不會阻止隨附能力載入。

自然菁英怪使用 EliteMobPowers.yml 中明確指定的抽取池，新增自訂能力時請檢查這些清單。要直接分配給 Boss，將 .lua 檔名加入其 powers: 清單。

Boss Lua 能力可用的鉤子

鉤子	觸發時機
`on_spawn`	Boss 生成時
`on_game_tick`	執行實例處於活動狀態，且未暫停或受抑制時的每個伺服器 tick
`on_boss_damaged`	Boss 受到任何來源的傷害
`on_boss_damaged_by_player`	Boss 受到玩家的傷害
`on_reinforcement_damaged_by_player`	增援受到玩家傷害；鉤子在其召喚者上執行
`on_boss_damaged_by_elite`	Boss 受到其他菁英怪的傷害
`on_player_damaged_by_boss`	Boss 對玩家造成傷害
`on_enter_combat`	Boss 進入戰鬥
`on_exit_combat`	Boss 離開戰鬥
`on_heal`	Boss 治療
`on_boss_target_changed`	玩家目標事件，包含初次取得目標；並非每次目標變更或遺失
`on_death`	Boss 死亡
`on_phase_switch`	Boss 切換階段
`on_mind_action`	原生 Mind 向附加能力要求動作

也接受 on_zone_enter 與 on_zone_leave。內建派發器從同一 Boss 的 EliteScript 區域監聽器接收這些事件，而非 Lua 區域監視器。請參閱本頁最上方的警告。

每個附加 Lua 能力都擁有針對該 Boss 的獨立執行實例與狀態。上方範例刻意不設冷卻，每次派發符合的攻擊事件都會執行。需要時請明確加入冷卻檢查與設定；只有中繼資料不會限制 Lua 鉤子。傷害可能同時派發通用鉤子與更具體的鉤子，因此同時定義兩者可能執行兩個處理常式。取消、移除與失敗行為請參閱生命週期指南。

關於你在這些鉤子中實際能呼叫什麼，請參閱 Lua 入門指南、Boss 鉤子與生命週期與 Boss 與實體。

撰寫能力的兩種方式​

EliteMobs 腳本系統​

添加 EliteScript​

事件

目標

動作

區域

條件

冷卻

添加多個 EliteScripts​

建立獨立能力​

isEnabled​

powerType​

powerType 如何影響自然菁英怪：EliteMobPowers.yml​

effect​

powerCooldown​

globalCooldown​

製作獨立的 Lua 能力​

Boss Lua 能力可用的鉤子​