CannonRTP API

CannonRTP 暴露了三個 Bukkit 事件供其他插件掛接。所有事件位於 com.magmaguy.cannonrtp.api 套件中,並於主伺服器執行緒上觸發。

要監聽事件,只需註冊一個一般的 Bukkit @EventHandler —— 無需額外的註冊步驟。

CannonRTPLaunchEvent

於玩家即將開始大砲發射序列的瞬間觸發,早於任何視覺或效果被套用。可取消。

屬性	型別	說明
player	Player	觸發大砲的玩家
cannonId	String	大砲的設定 id（不含 .yml 的檔名）
cannonDisplayName	String	大砲的 displayName 欄位
cannonLocation	Location	被觸發的確切放置點
destination	Location	為本次發射選定的預驗證安全降落位置

取消事件會完全中止發射:玩家原地不動、不套用任何效果,且目的地會被歸還至大砲佇列的最前端,於下次發射時重新使用。適用於基於區域的黑名單、冷卻插件、經濟關卡或 PvP 區域檢查。

@EventHandler
public void onLaunch(CannonRTPLaunchEvent event) {
    if (event.getPlayer().getWorld().getName().equals("event_world")) {
        event.setCancelled(true);
    }
}

CannonRTPLocationValidationEvent

於 CannonRTP 在預載搜尋期間驗證每個候選降落位置時觸發。僅在所有內建檢查（世界邊界、表面、不安全材質、保護插件整合）通過之後才觸發。

屬性	型別	說明
cannonId	String	正在進行搜尋的大砲設定 id
cannonDisplayName	String	大砲的 displayName 欄位
candidate	Location	正在考慮的候選降落位置

此事件在 Bukkit 意義上不可取消。要否決候選位置,請呼叫:

event.setRejected("inside arena spawn protection");

CannonRTP 接下來會將該候選位置視為內部檢查失敗般丟棄,並繼續搜尋。監聽器可實作超出內建保護介接器範疇的自訂區域規則。

注意:在預載嘗試期間於主執行緒上觸發（全域每 tick 一次,在啟用中的大砲之間輪流分配)。請保持處理常式快速。

CannonRTPLandingEvent

於玩家被傳送至目的地且發射序列已完全完成（LANDING 階段已運行、緩降已被移除、衝擊效果已播放）後觸發。不可取消 —— 請使用 CannonRTPLaunchEvent 在發射發生前否決它。

屬性	型別	說明
player	Player	剛剛降落的玩家
cannonId	String	發射該玩家的大砲設定 id
cannonDisplayName	String	大砲的 displayName 欄位
destination	Location	玩家被送往目的地的副本

適用於首次抵達時頒發獎勵、觸發後續效果、授予區域權限、廣播抵達或分析統計。

執行緒與生命週期

• 三個事件皆於主執行緒上派發。
• CannonRTPLocationValidationEvent 於全域預載 tick 期間派發（每個伺服器 tick 嘗試一次,於啟用中的大砲間輪流分配),因此監聽器中的繁重工作會明顯減慢大砲填充其佇列的速度。
• CannonRTPLaunchEvent 在 LaunchSequence 建構前立即派發,因此你變更的任何狀態（藥水效果、物品欄、遊戲模式）會在搜尋階段開始前生效。
• CannonRTPLandingEvent 每次發射派發一次,於 LANDING 階段的 tick 中,於衝擊效果之後。

使用 cannonId

cannonId 與所有管理員指令（/wc place、/wc target 等）所使用的 id 相同,且符合大砲設定不含 .yml 的檔名。請注意,單份大砲設定可驅動多個世界中的放置點;它們全都共享相同的 cannonId 與 cannonDisplayName。若你需要確切的放置點,請使用 CannonRTPLaunchEvent 中的 cannonLocation。