CannonRTP（WorldCannon）
CannonRTP 是一個適用於 Minecraft 伺服器的多重大砲隨機傳送插件。「WorldCannon」是較舊的／wiki 區段名稱；插件在 Bukkit 中註冊為 CannonRTP，發佈檔案為 CannonRTP.jar，這也是玩家與管理員實際看到的名稱。
關鍵命名細節：
- 插件名稱：
CannonRTP - 根指令：
/cannonrtp - 別名：
/crtp、/wc - 權限：
cannonrtp.admin、cannonrtp.use - 設定資料夾：
plugins/CannonRTP/
功能說明
CannonRTP 是一套多重大砲隨機降落系統，而非單一固定的發射器。每一個設定好的大砲可以在世界中放置一處或多處，而每個放置點都會偵測走入其觸發半徑內的玩家。
每一座大砲可以：
- 透過
/wc create與/wc place多次放置 —— 一份大砲設定可驅動所有放置點 - 偵測進入該大砲觸發半徑內的玩家（預設 1.75 格）
- 在指定的目標世界中預先載入並維持一條安全降落點佇列（支援跨世界目標）
- 拒絕不安全的地形、被阻擋的空間、受保護的領地，以及超出世界邊界的位置
- 可選擇性地要求額外的個別大砲權限
- 透過五個階段的電影式序列發射玩家
- 顯示 FreeMinecraftModels 3D 動態大砲模型（個別大砲的
customModel，或透過全域優先順序清單）；若未安裝 FMM，則回退至顏色變化的軌道粒子 - 在大砲上方顯示一個面向玩家的浮動狀態標籤（Ready / Charging / Maintaining / Exhausted）；已停用的大砲不會生成標籤或模型，只會在
/wc list與/wc status中顯示為 Disabled
快速開始
- 把
CannonRTP.jar放進plugins/並啟動伺服器。 - 在遊戲中執行
/wc initialize，接著執行/wc setup下載大砲模型包。下載需要已連結的 Nightbreak 帳號，而模型需要 FreeMinecraftModels。沒有模型時，大砲會使用粒子視覺效果。 - 站在大砲應該所在的位置，執行
/wc create spawn。新的大砲會把玩家降落在它所在的世界。 - 選用：執行
/wc target spawn <world>讓玩家降落在另一個已載入的世界，或執行/wc center spawn以你目前的位置為中心搜尋。 - 確認搜尋區域已有生成的地形（預設距離搜尋中心 500 到 5000 格），然後執行
/wc status。大砲只要持有至少一個已檢查的目的地，就會發射玩家。
發射流程
使用前，請生成或探索目標世界設定的搜尋區域。CannonRTP只載入現有區塊，不生成地形；未探索的搜尋半徑可能無法提供任何目的地。
發射序列由五階段的狀態機驅動（SEARCHING -> FIRING -> TELEPORTING -> DROPPING -> LANDING）。當玩家走入符合條件的大砲觸發半徑時：
- CannonRTP 檢查
cannonrtp.use。 - 檢查該大砲可選的
requiredPermission。 - 檢查每位玩家的發射冷卻（
runtime.launchCooldownSeconds，預設 30 秒）。此限制適用於所有大砲，且不會消耗佇列中的目的地。 - 確認該大砲的佇列中至少有一個預先載入的降落點。（已停用的大砲、位於未載入世界中的大砲，以及位於未載入區塊中的大砲永遠不會走到這一步——它們被完全排除在 tick 迴圈之外，因此根本無法被觸發。）
- 從該大砲佇列中消耗一個預先載入的安全降落點。
- 觸發
CannonRTPLaunchEvent（可取消）。若有監聽器取消此事件，目的地會被歸還至佇列，且不會開始計算冷卻。 - Searching 階段（預設 42 ticks，可透過
launchWarmupTicks設定）：玩家獲得漂浮效果，若啟用了自訂模型，則大砲會播放其fire動畫，標題／副標題上會閃過隨機座標預覽。在模型啟用期間，玩家會獲得隱形效果，使動畫呈現更清晰。 - Firing 階段（預設 45 ticks，透過
verticalBoostTicks設定）：漂浮／隱形效果被移除，播放升空音效，生成火焰＋煙霧＋爆炸效果，並在每個 tick 套用verticalBoostVelocity。真正的目的地座標被揭示。 - Teleporting 階段（單一 tick）：佇列中的目的地會被重新驗證（地形柱、保護插件整合、API 監聽器）。若仍通過驗證，玩家會被傳送至該處正上方恰好 50 格處，並套用緩降效果。空投高度永遠不會被夾限——降落驗證器已經保證抵達方塊位於世界最大高度之下，而不再通過驗證的目的地會取消該次發射並改為救回玩家。
- Dropping 階段：玩家伴隨著煙霧軌跡緩慢下降（
LARGE_SMOKE+CAMPFIRE_SIGNAL_SMOKE）。 - Landing 階段：玩家站在地面上且垂直速度低於每 tick 0.08 格時進入。CannonRTP 解除自身施加的緩降，播放衝擊效果（雲霧衝擊波、火焰環、塵土轉場），並觸發
CannonRTPLandingEvent。若下降超過最大時長（slowFallingSecondsx 20 ticks），CannonRTP 會救回玩家，不觸發降落事件。
降落安全規則
在某個位置被接受加入預載佇列之前，目前的程式碼會依序檢查：
- 目標世界已載入（在未載入期間，大砲會停止預載並回報
Target world <name> is not loaded.） - 搜尋中心可解析——優先為設定的
searchCenter，其次是大砲本身位於目標世界中時的所在位置，再其次是目標世界的出生點 - 候選位置位於世界邊界內
- 候選區塊已載入（按需載入，不會產生新地形）
- 候選位置所在欄位中存在最高的非空氣方塊
- 降落點正下方的表層方塊為固體且非液體
- 該表層方塊不在設定的不安全地面材質清單中，也不是地獄的基岩天花板
- 降落點位於世界最低高度或以上，且其上方 51 格處的抵達方塊仍低於世界最大高度
- 整條 52 格的空投柱（自降落點向上至抵達處的頭部方塊）的每一個方塊都是空氣或可通過
- 該柱中沒有任何方塊屬於設定的不安全身體材質清單
- 所有啟用的保護插件整合允許該位置
- 任何
CannonRTPLocationValidationEvent監聽器未否決該候選位置
在地獄中，CannonRTP 會拒絕基岩天花板，並向下掃描尋找完整空投柱皆安全的外露洞窟地面。這讓地獄目標成為可能，而不會把玩家丟在天花板之上或穿過實心地形。
搜尋嘗試在全域上每 tick 限速一次（每秒 20 次），透過輪流方式公平地在所有啟用中的大砲之間分配。每座大砲擁有自己的逾時計數器（searchTimeoutAttempts，預設 100，最低 10）。
大砲狀態
每座大砲都有透過 /wc status 或 /wc list 可見的內部狀態：
| 顯示 | 內部狀態 | 含義 |
|---|---|---|
| Disabled | -- | 大砲在其設定中被明確停用 |
| Charging | SEARCHING（佇列為空） | 仍在預載第一批安全位置 |
| Maintaining | SEARCHING（佇列非空） | 已有部分位置，但仍在補充已消耗的名額 |
| Ready | READY | 擁有足夠的預載位置（>= chargedLocationsPerCannon）以發射玩家 |
| Exhausted | EXHAUSTED | 已用盡 searchTimeoutAttempts 仍未填滿儲備 |
內部搜尋狀態恰好只有三個值（READY、SEARCHING、EXHAUSTED）；Disabled 是在查詢搜尋狀態之前就決定的，而 Charging / Maintaining 則是 SEARCHING 的兩種呈現方式。Ready 優先於 Exhausted——仍持有充能儲備的大砲即使最近一次搜尋視窗逾時，仍會顯示為 Ready。
當某個已啟用保護插件的整合載入失敗且 failOpenOnProtectionErrors 為 false 時，大砲也會在不取樣任何地形的情況下顯示 Exhausted。請參閱保護整合。
並不存在獨立的「設定無效」狀態。目標世界變得無法使用時，會丟棄該世界的佇列目的地，並將搜尋狀態重設為 SEARCHING。空佇列顯示 Charging，/wc status 的 $reason 欄位回報 Target world <name> is not loaded.。目標世界載入後會恢復搜尋。messages.yml 中的 statusLabels.invalid 鍵存在，但不會顯示。
只要大砲佇列中有至少一個目的地，即可發射玩家。chargedLocationsPerCannon 門檻只會影響視覺上的 READY 標籤。
執行環境需求
- Minecraft：
plugin.yml宣告api-version: 1.21.4；目前的原始碼樹是針對 Spigot26.3-R0.1-SNAPSHOTAPI 建置的 - Java：
21 - 建議的伺服器軟體：Paper 或現行相容的分支
- MagmaCore：
2.2.0或更新版本（共用程式庫，已遮蔽進插件內） - 可選依賴：FreeMinecraftModels（用於 3D 動態大砲模型）
- 統計：CannonRTP 會向 bStats 回報匿名使用統計（插件 id
34460）。若要退出，請在plugins/bStats/config.yml中設定enabled: false，這會套用到伺服器上所有使用 bStats 的插件。
穩定性與復原
CannonRTP 會在世界與區塊生命週期事件中保持其視覺與佇列一致：
- 當大砲所在的區塊卸載時，其標籤與模型會被移除；在區塊重新載入時會重新生成
- 當大砲所在的世界卸載時，大砲會被暫停；若世界再次載入則會喚醒
- FreeMinecraftModels 啟用、停用，或在支援重載完成事件的版本上完成內容重載時，會丟棄舊大砲模型並從目前的模型登錄表重新建立；沒有該事件的舊版 FMM 中，已移除的模型實例也能被直接偵測到
- 在空投傳送之前，佇列中的目的地會再次針對地形、保護插件整合與 API 監聽器進行檢查；若它已變得不安全，該次發射會救回玩家，而不會採用過時的座標
- 發射後的清理只會移除 CannonRTP 仍然擁有的漂浮、隱形與緩降效果，並會還原它暫時取代掉的較舊效果，而不會刪除其他插件較新的狀態
- 若某次發射因目的地世界被卸載而無法繼續，CannonRTP 會將玩家救回大砲座位或其他已載入世界的出生點；若沒有安全的救援世界可用，則會保留緩降效果
/wc reload、免重啟的插件更新，以及每個編輯大砲的指令（create、place、remove、delete、target、center）都會重建所有大砲：進行中的發射會被取消並將玩家救回大砲座位，佇列中的目的地會被捨棄並重新搜尋，發射冷卻時間也會重設- 若玩家在發射途中斷線，該次發射會結束，CannonRTP 會移除它所施加的效果；玩家不會被傳送
疑難排解
- 大砲一直停在 Charging，或變成 Exhausted。 執行
/wc status並閱讀其原因。常見原因包括目標世界未載入、搜尋區域從未生成、地表未通過降落安全規則（水預設是不安全的材質，因此開闊的海洋永遠不符合），以及領地或區域覆蓋了該區域。/wc probe會在你所站的位置測試保護檢查。已啟用但載入失敗的保護整合會讓所有大砲停止搜尋；請參閱保護整合。 - 玩家走進大砲卻沒有任何反應。 檢查
cannonrtp.use、大砲的requiredPermission、大砲是否已啟用，以及發射冷卻（runtime.launchCooldownSeconds，預設 30 秒）。 - 刪除大砲或移動使用中的目的地之前， 請備份它在
plugins/CannonRTP/cannons/中的檔案。
尋求協助時，請附上 /wc status 的輸出、CannonRTP 和伺服器的版本、受影響大砲的設定檔，以及完整的伺服器日誌。/logify 會上傳日誌並回傳連結。