建立事件
本指南適用於 EliteMobs 10 及以上版本
什麼是自訂事件？
這裡的自訂事件指的是在遊戲中隨機發生的事件，無論是基於玩家動作或具有定時觸發。外掛預載了多個自訂事件，例如炎魔（Balrog）事件、海怪（Kraken）事件與寶藏哥布林（Treasure Goblin）事件，僅舉幾例。
這套系統之所以稱為自訂事件，是因為這些事件不僅可以自訂，還能從零開始建立。以下是一份關於如何建立與自訂你自己的事件的指南。
建立你的自訂事件
自訂事件設定檔應建立於：
plugins/EliteMobs/customevents/
檔案必須使用 .yml 格式。參照事件時請使用包含 .yml 副檔名的完整檔名。
範例：my_cool_event.yml 會以 my_cool_event.yml 來引用
儲存檔案後執行 /em reload 載入變更。events.yml 中對應的動作／定時事件開關也必須啟用。
通用設定
以下設定可/應同時用於動作事件與定時事件。
isEnabled
設定事件是否啟用。
| 鍵 | 值 | 預設值 |
|---|---|---|
isEnabled | 布林值 | true |
範例
isEnabled: true
eventType
設定事件的類型。
| 鍵 | 值 | 預設值 |
|---|---|---|
eventType | BREAK_BLOCK / FISH / TILL_SOIL / TIMED | DEFAULT |
請注意，BREAK_BLOCK、FISH 與 TILL_SOIL 是動作事件，而 TIMED 是定時事件。
eventType 是必填的。 DEFAULT 是當此設定缺漏、或不符合上述任何類型時 EliteMobs 退回使用的佔位值。停留在 DEFAULT 的事件會記錄一則警告且完全不會被註冊，因此它底下的所有設定甚至不會被讀取。
範例
eventType: BREAK_BLOCK
bossFilenames
列出要一起生成的自訂 BOSS 檔名，包含 .yml。必填！ 並非從清單中隨機挑選一個 BOSS。使用事件前請確認每個參照的 BOSS。定時事件會跳過無效檔名，沒有有效 BOSS 就無法排入佇列。動作事件只要有任何無效檔名，就會在生成任何東西之前取消；若某個 BOSS 的生成遭到拒絕，已經生成的 BOSS 會被移除。
| 鍵 | 值 | 預設值 |
|---|---|---|
bossFilenames | 字串清單 | 無 |
範例
bossFilenames:
- balrog.yml
- my_event_boss.yml
announcementPriority
設定事件開始與結束訊息的接收者。事件優先度與 BOSS 公告優先度的行為不同：
| 優先度 | 接收者 |
|---|---|
0 | 事件所在世界的玩家；不會關閉訊息 |
1 | 所有線上玩家；設定 announcementBroadcastWorldOnly: true 時僅限事件所在世界 |
2 | 事件所在世界的玩家 |
3 或以上 | 事件所在世界的玩家，以及已設定的 DiscordSRV |
省略 startMessage 或 endMessage 即可關閉對應的事件訊息。BOSS 本身的生成公告是獨立的。
| 鍵 | 值 | 預設值 |
|---|---|---|
announcementPriority | 整數 | 0 |
範例
announcementPriority: 1
startMessage
設定事件實際開始時發送的訊息，而非定時事件排入佇列時發送。開始與結束訊息支援色彩格式，但事件系統不會替換 $boss 或 $player 等 BOSS／玩家預留位置。
| 鍵 | 值 | 預設值 |
|---|---|---|
startMessage | 字串 | 無 |
範例
startMessage: An event has started!
endMessage
設定在事件結束時發送的訊息。
| 鍵 | 值 | 預設值 |
|---|---|---|
endMessage | 字串 | 無 |
範例
endMessage: An event has ended!
eventStartCommands
設定事件開始時由主控台執行的指令，不要加開頭的 /，也不會提供玩家或 BOSS 預留位置。每條指令獨立執行；可選的 $chance=0.5$ 讓該指令有 50% 機率執行。使用 0～1 的機率；省略時必定執行。
| 鍵 | 值 | 預設值 |
|---|---|---|
eventStartCommands | 字串清單 | 無 |
範例
eventStartCommands:
- say The event now starts!!
- "$chance=0.5$ say What a spawn!"
eventEndCommands
設定事件結束時安排在下一次伺服器工作中執行的主控台指令。語法與逐條指令機率和 eventStartCommands 相同，不提供玩家或 BOSS 預留位置。
| 鍵 | 值 | 預設值 |
|---|---|---|
eventEndCommands | 字串清單 | 無 |
範例
eventEndCommands:
- say The event ends, so sad.
- "$chance=0.5$ say Too slow bud!"
minimumPlayerCount
設定所需的最低線上人數，計算所有世界與遊戲模式，而非只計算附近符合資格的參與者。
動作事件會在動作觸發時檢查此值。定時事件會在自動挑選器選擇事件時、已排入佇列的事件搜尋位置前，以及其 BOSS 生成前一刻再次檢查此值。已排入佇列的定時事件會等到線上人數足夠；其自訂生成仍必須透過自身的玩家與位置檢查找到合適地點。
| 鍵 | 值 | 預設值 |
|---|---|---|
minimumPlayerCount | 整數 | 1 |
範例
minimumPlayerCount: 5
事件設定範例
這裡僅展示通用設定；完整的定時事件還需要 spawnType 與正的選取權重。
isEnabled: true
eventType: TIMED
bossFilenames:
- "cool_boss.yml"
- "other_cool_boss.yml"
announcementPriority: 3
startMessage: "Cool event is starting!"
endMessage: "Cool event is ending!"
eventStartCommands:
- say The event started!
eventEndCommands:
- say The event ended!
完整定時事件範例
isEnabled: true
eventType: TIMED
bossFilenames:
- "my_timed_boss.yml"
announcementPriority: 3
startMessage: "A timed event has started!"
endMessage: "The timed event has ended!"
eventStartCommands:
- say The timed event began!
eventEndCommands:
- say The timed event concluded!
spawnType: "my_spawn_location.yml"
localCooldown: 120
globalCooldown: 30
weight: 100
eventDuration: 15
endEventWithBossDeath: true
動作事件
在特定動作（例如破壞方塊或釣魚）發生時有機率執行的事件。
動作事件開始後會套用玩家個人冷卻，預設為 4 分鐘，可透過 events.yml 的 actionEventMinimumCooldownMinutes 設定。每次動作只會啟動一個動作事件：只要有一個相符的檔案啟動，玩家就會進入冷卻，其餘檔案會被跳過。未能成功啟動的事件不會消耗冷卻。設定 actionEventsEnabled: false 可在全伺服器停用動作事件。
三種動作類型的觸發方式如下：
eventType | 觸發條件 |
|---|---|
BREAK_BLOCK | 玩家破壞方塊。會先擲 chance，再檢查被破壞的方塊是否符合 breakableMaterials。 |
FISH | 釣魚事件具有捕獲的實體，包括被鉤住的生物。沒有捕獲實體就不會觸發。生成位置是該實體的位置。 |
TILL_SOIL | 玩家主手持木、石、鐵、金、鑽石或獄髓鋤，右鍵點擊 DIRT 或 GRASS_BLOCK。不要求方塊實際變成耕地。 |
已取消的 Bukkit 事件會被忽略。位置必須在啟用 EliteMobs 的世界內、EliteMobs 副本世界以及副本、競技場或職業試煉的實例區域之外，並獲得 WorldGuard elitemobs-events 旗標允許。這些監聽器不另外限制玩家的遊戲模式。
動作事件在互動位置生成：被破壞方塊的 X/Z 中心、捕獲實體的位置，或被點擊土壤上方一格。它們不使用 spawnType、定時事件選取權重或選取冷卻。
啟用 suppressEvents 時，Peace Banner 保護也會阻止事件。下文的持續時間、結束時刻與 BOSS 移除後結束等監控檢查，同樣適用於動作事件。
chance
設定當動作發生時，事件發生的機率。
| 鍵 | 值 | 預設值 |
|---|---|---|
chance | 0.0 到 1.0 之間的數值 | 0 |
範例
chance: 0.001
breakableMaterials
設定當動作設為 BREAK_BLOCK 時要檢查的材料列表。
| 鍵 | 值 | 預設值 |
|---|---|---|
breakableMaterials | 材料清單 | 無 |
範例
breakableMaterials:
- BEEHIVE
- BIRCH_WOOD
設定範例
chance: 0.001
breakableMaterials:
- COAL_ORE
設定在破壞煤礦石方塊時有 0.1% 的機率執行事件，前提是事件類型為 BREAK_BLOCK。
完整動作事件範例
isEnabled: true
eventType: BREAK_BLOCK
bossFilenames:
- "mining_boss.yml"
announcementPriority: 2
startMessage: "You've awakened something..."
chance: 0.001
breakableMaterials:
- DIAMOND_ORE
- EMERALD_ORE
定時事件
定時事件先進行加權自動選取，再進入自訂生成佇列。被選中不保證立即生成，也不保證固定時間表。不同檔案的事件可以同時排隊或執行。
沒有線上玩家時不會自動選取事件。同一檔案已有排隊或執行中的副本，或線上玩家少於其 minimumPlayerCount 時，自動選取器會排除該檔案。設定 events.yml 中的 timedEventsEnabled: false 可在全伺服器停用定時事件。
spawnType
設定事件所使用的自訂生成，它定義了 BOSS 可以生成的位置。
| 鍵 | 值 | 預設值 |
|---|---|---|
spawnType | 檔名 | 無 |
範例
spawnType: nether_spawn.yml
localCooldown
設定再次自動選取此事件前的等待分鐘數，從被選中時計算。即使後續驗證或其他外掛阻止排入佇列，仍會消耗這次冷卻。已有排隊或執行中的副本也會阻止再次自動選取，即使冷卻已結束。
| 鍵 | 值 | 預設值 |
|---|---|---|
localCooldown | 雙精度數值 | 0 |
範例
localCooldown: 120
globalCooldown
設定自動選取的全域等待分鐘數。在成功排入佇列時設定一次，實際開始時再次設定，手動排入的事件也適用。它不是從事件結束時計算。後一次設定會取代原有截止時間。
| 鍵 | 值 | 預設值 |
|---|---|---|
globalCooldown | 雙精度數值 | 0 |
範例
globalCooldown: 60
weight
設定目前符合資格的定時事件之間的相對選取權重。請使用有限的正數。建議值：100。零權重不能可靠地停用事件，尤其是所有候選權重都為零時；請使用 isEnabled: false。
權重系統決定事件被選中的相對機率。例如：
- 權重 100 的事件 A 對上權重 50 的事件 B = 事件 A 被選中的可能性是兩倍
- 權重越高 = 被挑選的機率越高
- 排程器初始化約 5 分鐘後首次檢查，之後每分鐘檢查一次。伺服器延遲可能推遲檢查。
| 鍵 | 值 | 預設值 |
|---|---|---|
weight | 雙精度數值 | 0 |
範例
weight: 60.5
eventDuration
設定從實際開始起算的持續時間限制，單位為分鐘。0 與負數都會停用此檢查。監控器每 20 個伺服器刻檢查一次，因此事件最多可能晚一秒結束，伺服器延遲時還會更晚。同樣適用於動作事件。
| 鍵 | 值 | 預設值 |
|---|---|---|
eventDuration | 雙精度數值 | 0 |
範例
eventDuration: 30
endEventWithBossDeath
當所有主要 BOSS 物件都不再存在時結束事件。設定多個 bossFilenames 時，只移除或擊敗其中一個不會在其他 BOSS 仍存在時結束事件。增援不算額外的主要 BOSS。此項檢查是否存在，不要求是歸屬玩家的擊殺。無論因何結束事件，剩餘主要 BOSS 都會以逾時方式移除。同樣適用於動作事件。
| 鍵 | 值 | 預設值 |
|---|---|---|
endEventWithBossDeath | 布林值 | true |
範例
endEventWithBossDeath: true
eventEndTime
設定事件結束時的遊戲內時間（以刻 ticks 計）。使用 Minecraft 的時間系統，其中 0=黎明、6000=正午、12000=黃昏、18000=午夜、23000=深夜。設為 -1 可停用基於時間的結束。
檢查條件是 世界時間 > eventEndTime，不會等待隔日或精確跨過該時刻。如果事件在該時刻之後開始，可能在第一次監控檢查時就結束。請協調生成時段與結束時刻。世界時間範圍是 0～23999，不會超過 23999 或更高門檻。同樣適用於動作事件。
| 鍵 | 值 | 預設值 |
|---|---|---|
eventEndTime | 整數（可達門檻為 0～23998；-1 停用） | -1 |
範例
eventEndTime: 23000
排入佇列會啟動自訂生成的位置搜尋與重試流程。它可能在快取位置等待時間或月相符合要求，等待期間不會重新執行所有位置檢查。具體檢查與限制見上方連結的自訂生成指南。同一時間只會生成一個定時事件，而且生成也會等待 minimumPlayerCount 與 timedEventMinimumCooldownMinutes 間隔條件滿足。定時事件確認主要 BOSS 存在後，才會執行開始訊息與開始指令。
事件設定範例
isEnabled: true
eventType: TIMED
bossFilenames:
- "cool_boss.yml"
- "other_cool_boss.yml"
announcementPriority: 3
startMessage: "Cool event is starting!"
endMessage: "Cool event is ending!"
eventStartCommands:
- say The event started!
eventEndCommands:
- say The event ended!
spawnType: "myCoolSpawn.yml"
localCooldown: 30
globalCooldown: 15
weight: 100
eventDuration: 20
endEventWithBossDeath: true
eventEndTime: 10000
手動觸發事件
/em event <event filename>
將定時事件排入佇列，等待有效的時間與地點。需要 elitemobs.event.start 權限，必須由玩家執行，且只接受已載入的定時事件範本。啟用 timedEventsEnabled 時，外掛從已啟用的 TIMED 檔案建立這些範本。
指令略過加權選取、本地／全域選取冷卻，以及已有排隊或執行副本的檢查。重複執行可能排入重複副本。自訂生成的位置與時間條件、事件的 minimumPlayerCount，以及 timedEventMinimumCooldownMinutes 間隔仍適用。
無法排入佇列時會說明原因：spawnType 缺漏或無效、沒有有效的 bossFilenames，或其他外掛取消了事件。成功訊息只確認已接受排隊，不代表已出現可見 BOSS。請檢查實際 BOSS 與主控台中的生成重試紀錄。
全伺服器事件設定
這些設定位於 plugins/EliteMobs/events.yml，編輯後請重新載入：
| 鍵 | 說明 | 預設 |
|---|---|---|
actionEventsEnabled | 動作事件是否會發生 | true |
timedEventsEnabled | 定時事件是否會發生 | true |
actionEventMinimumCooldownMinutes | 動作事件觸發後，每位玩家的冷卻時間（分鐘） | 4 |
timedEventMinimumCooldownMinutes | 定時事件開始後，必須經過多少分鐘，另一個定時事件才能搜尋位置或生成其 BOSS，包括已在快取位置等待的事件 | 4 |
announcementBroadcastWorldOnly | 將優先度 1 的訊息限制在事件所在世界；其他優先度的遊戲內訊息原本就只傳送到該世界 | false |