跳至主要內容

CannonRTP API

產生的 Java 參考文件可搜尋類別、方法與簽章，並記錄各模組的原始碼版本與提交。

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

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

CannonRTPLaunchEvent​

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

屬性型別說明
playerPlayer觸發大砲的玩家
cannonIdString大砲的設定 id（不含 .yml 的檔名）
cannonDisplayNameString大砲的 displayName 欄位
cannonLocationLocation被觸發的確切放置點
destinationLocation為本次發射選定的預驗證安全降落位置

取消事件會完全中止發射：玩家原地不動、不套用任何效果、不會開始任何內建的發射冷卻，且目的地會被歸還至大砲佇列的最前端。為了避免在每個玩家掃描 tick 都觸發一個持續被取消的事件，只要該玩家仍留在觸發範圍內，CannonRTP 會將重試間隔由 1 秒逐步退避至 30 秒；離開觸發範圍或完成一次被接受的發射即會清除該退避。適用於基於區域的黑名單、冷卻插件、經濟關卡或 PvP 區域檢查。

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

CannonRTPLocationValidationEvent​

預載搜尋驗證每個候選降落點時觸發；發射確認時（空投傳送之前）重新驗證從佇列取出的目的地時，會再次觸發。預載階段在通過世界邊界、表面、不安全材質與保護插件檢查後觸發。發射確認階段則重新檢查目前的世界參照、降落點上方的整列空間與保護插件，再觸發事件；此時不會再次檢查世界邊界。

屬性型別說明
cannonIdString正在進行搜尋的大砲設定 id
cannonDisplayNameString大砲的 displayName 欄位
candidateLocation正在考慮的候選降落位置

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

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

在預載期間，CannonRTP 接下來會將該候選位置視為內部檢查失敗般丟棄，並繼續搜尋。你傳入的原因會以 Rejected by another plugin: <reason> 的形式顯示在該大砲的 /wc status 詳細資訊中，直到之後的狀態變更（例如有位置排入佇列或搜尋耗盡）將其取代。而在提交時，否決則會取消該次發射並救回玩家，而不會把他傳送到監聽器已不再接受的位置。監聽器可實作超出內建保護介接器範疇的自訂區域規則。

注意：兩次派發都發生在主執行緒上，且預載嘗試為全域每 tick 一次，在啟用中的大砲之間輪流分配。請保持處理常式快速。

CannonRTPLandingEvent​

於玩家被傳送至目的地且發射序列完全結束後觸發：LANDING 階段已執行，CannonRTP 已解除自身施加的緩降，衝擊效果已播放。原有的效果可能按剩餘時間恢復；其他來源之後施加的效果會保留。不可取消 —— 請使用 CannonRTPLaunchEvent 在發射發生前否決它。

屬性型別說明
playerPlayer剛剛降落的玩家
cannonIdString發射該玩家的大砲設定 id
cannonDisplayNameString大砲的 displayName 欄位
destinationLocation玩家被送往目的地的副本

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

執行緒與生命週期​

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

保護檢查輔助方法​

主插件類別也公開了 /wc probe 所使用的保護檢查：

boolean allowed = CannonRTP.getInstance().isPotentialLandingLocationAllowed(location);

當每個已啟用的保護整合都允許該位置時回傳 true，並遵循 failOpenOnProtectionErrors。它不會檢查地形、空投柱、世界邊界或 CannonRTPLocationValidationEvent 監聽器。在 CannonRTP 於啟動期間載入其大砲之前，它都會回傳 false。CannonRTP 即 com.magmaguy.cannonrtp.CannonRTP。

使用 cannonId​

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