CannonRTP 設定
CannonRTP 將其全域設定分散於 plugins/CannonRTP/ 中的多個檔案，另外每座大砲在 plugins/CannonRTP/cannons/ 中各有一份設定檔。
檔案配置
| 檔案 | 用途 |
|---|---|
plugins/CannonRTP/config.yml | 頂層執行階段旗標（設定狀態、語言、粒子間隔、發射冷卻、大砲模型優先順序、Spigot 資源 id、Nightbreak 更新設定） |
plugins/CannonRTP/landing.yml | 降落搜尋調整（佇列大小、逾時嘗試次數、緩降時長、不安全材質清單、失敗開放行為） |
plugins/CannonRTP/sounds.yml | 發射序列期間播放的音效 |
plugins/CannonRTP/messages.yml | 所有面向玩家的訊息、前綴與標題池 |
plugins/CannonRTP/protection.yml | 各保護插件整合的切換開關 |
plugins/CannonRTP/cannons/<id>.yml | 每座大砲一份（每份可驅動多個放置點） |
plugins/CannonRTP/cannons_disabled/ | 暫存資料夾，用於存放隨內容包附帶但目前停用的大砲設定。當你於 /wc setup 選單中啟用或停用內容包時，會在 cannons/ 與 cannons_disabled/ 之間搬移檔案。 |
plugins/CannonRTP/content_packages/<package>.yml | 為每個 Nightbreak 內容包產生的中繼資料（版本、下載連結、用於尋找其檔案的前綴）。通常不應手動編輯。 |
plugins/CannonRTP/imports/ | 手動匯入內容的投放資料夾。請參閱內容包。 |
plugins/CannonRTP/nightbreak-changelogs.yml | 共用 /wcchangelog 收件匣的已讀狀態。請參閱更新日誌通知。 |
插件預設附帶三份範例大砲設定：
example_cannonrtp.yml—— 空白參考範本（顯示名稱為Example World Cannon），預設停用。手動撰寫大砲檔案時可作為 YAML 參考使用。cannonrtp_free_cannon.yml—— 已啟用、無放置點，指向免費的cannonrtpFMM 模型。cannonrtp_premium_cannon.yml—— 已啟用、無放置點，指向高級的cannonrtp_premiumFMM 模型。
預設情況下這些檔案的 cannonLocations 皆未填入，因此在管理員執行 /wc create 或 /wc place 之前，世界中不會生成任何東西。它們也都沒有設定 targetWorld，因此每個放置點都會讓玩家降落在其所在的世界中。
每次載入大砲設定時，CannonRTP 都會重新建立 cannons/ 中缺少的這三個檔案。用 /wc delete 刪除其中一個，或在其內容包停用時將其移出，重新載入後都會留下一份不含放置點的全新預設副本。
config.yml
| 鍵 | 預設 | 行為 |
|---|---|---|
setupDone | false | 追蹤 Nightbreak 首次設定是否已完成 |
language | english | 要載入的翻譯檔案。Release 1 僅提供英文；此鍵為未來翻譯包預留 |
runtime.particleIntervalTicks | 15 | 大砲閒置粒子渲染之間的確切間隔，以伺服器 tick 計（最低 1；設為 1 可每 tick 渲染一次） |
runtime.launchCooldownSeconds | 30 | 玩家在兩次被接受的大砲發射之間必須等待的秒數（最低 0；設為 0 可停用）。被取消的 CannonRTPLaunchEvent 不會開始計算冷卻。 |
runtime.cannonModelPriority | [cannonrtp_premium, cannonrtp] | FreeMinecraftModels 模型名稱的優先順序清單，由上至下檢查。伺服器上找到的第一個模型會用於未自行設定 customModel 的所有大砲。若皆未找到，則使用軌道粒子回退方案。 |
runtime.spigotResourceId | "" | 版本檢查器使用的 Spigot 資源 id。留空以停用。 |
nightbreak.autoDownloadPluginUpdates | false | 由內嵌的 MagmaCore 函式庫新增。設為 true 時，CannonRTP 會在啟動幾分鐘後自動下載可用的插件與內容更新檔案。內容更新會在下次伺服器重啟後使用；插件更新則依循 nightbreak.applyPluginUpdatesWithoutRestart。自動插件下載需要有效的 Nightbreak 帳號 token 與有效的贊助者會員資格。留為 false 則改用遊戲內的更新按鈕。 |
nightbreak.applyPluginUpdatesWithoutRestart | never | 由內嵌的 MagmaCore 函式庫新增。決定何時從新的 jar 重新載入 CannonRTP 以套用已下載的插件更新。never 會等到下次重啟。when-empty 在沒有玩家在線時立即套用，否則每 30 秒檢查一次，並在伺服器無人時套用。immediately 會在下載完成後立即套用。其他任何值都視為 never。重新載入會依互動防護所述取消進行中的發射。無論此設定為何，/wc applypluginupdate 都能手動套用已下載的更新。 |
landing.yml
| 鍵 | 預設 | 行為 |
|---|---|---|
preloadedLocationsPerCannon | 10 | 插件嘗試為每座大砲維持的安全目的地總數（最低 1） |
chargedLocationsPerCannon | 1 | 大砲必須保有多少位置，其狀態標籤才會切換為 Ready（最低 1，上限為 preloadedLocationsPerCannon）。只要佇列中至少有一個位置，大砲即會發射玩家 —— 此門檻只影響視覺標籤。 |
searchTimeoutAttempts | 100 | 多少次失敗的搜尋嘗試後大砲會被標記為 Exhausted（最低 10）。搜尋嘗試在全域上每 tick 限速一次（每秒 20 次），公平地在所有啟用中的大砲之間分配。 |
slowFallingSeconds | 60 | 空投後緩降效果的最大持續時間（最低 1）。玩家觸地時效果會提早被移除。 |
failOpenOnProtectionErrors | false | 若保護插件 API 發生錯誤，預設會阻止降落。設為 true 則在無法安全查詢保護插件時允許降落繼續。設為 false 時，載入失敗的已啟用保護整合也會讓每座大砲停止搜尋（請參閱保護整合）。 |
unsafeGroundMaterials | [LAVA, MAGMA_BLOCK, CAMPFIRE, SOUL_CAMPFIRE, CACTUS, POWDER_SNOW] | 會使降落表面失格的材質 |
unsafeBodyMaterials | [LAVA, WATER, FIRE, SOUL_FIRE, SWEET_BERRY_BUSH, POWDER_SNOW, COBWEB] | 降落點至空投位置的整條垂直通道中禁止出現的材質，包括抵達位置的頭部空間 |
材質為 Bukkit Material 列舉名稱。無效條目會以警告形式記錄並略過。
sounds.yml
| 鍵 | 預設 | 行為 |
|---|---|---|
levitationStart.sound | BLOCK_BEACON_ACTIVATE | 搜尋階段開始時播放的音效 |
levitationStart.volume | 1.0 | |
levitationStart.pitch | 1.15 | |
blastOff.sound | ENTITY_GENERIC_EXPLODE | 發射階段開始時播放的音效 |
blastOff.volume | 1.0 | |
blastOff.pitch | 0.9 |
音效值可為 Bukkit Sound 列舉名稱（如 BLOCK_BEACON_ACTIVATE）或命名空間鍵（如 minecraft:block.beacon.activate）。列舉形式的名稱會將每個底線替換為點來轉換，因此鍵中含有底線的音效（例如 minecraft:block.note_block.pling）必須寫成其命名空間鍵。無效音效名稱會以警告形式記錄，該步驟的音效會被默默略過。將音效留空即不播放任何聲音。低於 0 的音量與音高會被提高為 0。
messages.yml
所有訊息皆支援 MagmaCore 漸層、MiniMessage 標籤，以及舊式 & 顏色代碼。$prefix 預留位置會以已設定的前綴取代。
完整的訊息鍵、預留位置以及發射序列所使用的標題池清單，請參閱訊息與標題頁面。
每座大砲的設定欄位
每個大砲檔案（plugins/CannonRTP/cannons/<id>.yml）儲存以下欄位：
| 欄位 | 預設 | 備註 |
|---|---|---|
isEnabled | true（用於新建大砲） | 已停用的大砲不會觸發、不會生成標籤或模型，並在 /wc list 與 /wc status 中顯示為 Disabled |
displayName | CannonRTP（或建立時傳入的名稱） | 用於訊息、狀態輸出與浮動標籤 |
cannonLocations | 空清單 | 序列化的 world,x,y,z,yaw,pitch 字串清單。一份大砲設定可生成多個世界中的放置點。由 /wc create、/wc place、/wc remove 管理。 |
targetWorld | 建立時所在的當前世界 | 支援跨世界目標 —— 將此設為與大砲不同的世界，可使玩家降落在那個世界中。若留空或缺少此欄位，每個放置點都會讓玩家降落在其所在的世界中。執行時必須已載入；在未載入期間，大砲會停止預載，且其 /wc status 詳情會顯示 Target world <name> is not loaded.。 |
searchCenter | null | 若未設定，插件會從大砲自身位置（當大砲位於目標世界時）或從目標世界的出生點向外擴散。若設定為其他世界中的位置，則會在目標世界中使用其 X 與 Z 座標。 |
triggerRadius | 1.75 | 用於偵測附近玩家的大砲周圍半徑（最低 0.5 格） |
minSearchRadius | 500 | 從搜尋中心起的最小降落搜尋距離（最低 0） |
maxSearchRadius | 5000 | 最大降落搜尋距離（永遠被限制為至少 minSearchRadius + 1） |
launchWarmupTicks | 42 | Searching 階段的長度，以 tick 計（最低 1） |
verticalBoostTicks | 45 | Firing 階段的長度，以 tick 計（最低 0）。設為 0 會跳過向上推升；發射音效、爆發效果與目的地標題仍會在傳送前播放。 |
verticalBoostVelocity | 1.35 | 發射階段每 tick 套用的向上速度（最低 0） |
enableParticles | true | 控制閒置時的軌道粒子動畫。僅在沒有自訂模型啟用且玩家於 36 格內時渲染。 |
requiredPermission | "" | 此特定大砲可選的額外權限關卡。擁有 cannonrtp.use 但缺少此節點的玩家會看到已設定的無權限訊息。 |
customModel | "" | 此特定大砲可選的 FreeMinecraftModels 模型名稱。若留空或模型無法使用，插件會回退至 runtime.cannonModelPriority。 |
大砲建立預設值
當你執行 /wc create <id> 時：
- 大砲 id 會被轉為小寫，
a-z、0-9、_、-以外的字元會被替換為_ displayName預設為CannonRTP，除非使用了/wc create <id> <display_name>（<display_name>中的底線會被轉換為空格）- 玩家當前位置會被附加至
cannonLocations targetWorld設為玩家當前所在世界searchCenter不設定（若大砲位於目標世界則回退至大砲自身位置，否則回退至目標世界的出生點）
建立後，插件會回覆設定檔的絕對路徑，讓你可以手動編輯 displayName、customModel、requiredPermission、搜尋半徑與發射調整。
FreeMinecraftModels 整合
當大砲解析至有效的 FreeMinecraftModels 模型 —— 透過其自身的 customModel 欄位或全域 runtime.cannonModelPriority 清單 —— 並且 FreeMinecraftModels 已安裝時：
- 大砲位置會生成一個靜態模型實體
- 浮動文字標籤會被提升至大砲上方 2.0 格處（無模型時為 1.2 格）以避免穿插模型
- 模型啟用期間會抑制閒置軌道粒子動畫
- 在發射過程中，大砲會在搜尋階段開始時播放其
fire動畫（若存在）；搜尋階段期間玩家會被以隱形效果隱藏，使動畫呈現更清晰
若 FreeMinecraftModels 在伺服器運行期間被啟用或停用，大砲模型快取會被清除。目前的 FMM 也會在內容重新載入完成時通知 CannonRTP，以便捨棄舊模型參照並從更新後的登錄表重新建立模型。CannonRTP 也會直接偵測已移除的模型實例，因此同樣支援尚無重新載入完成事件的 FMM 2.4.0。只要 FMM 處於啟用狀態，待重建的模型就會每 20 tick 重試一次，直到找到可用模型。
閒置粒子回退方案
當沒有模型啟用時，大砲會在大砲中心周圍渲染一對軌道運行的 DUST_COLOR_TRANSITION + FIREWORK 粒子。顏色會根據大砲的有效狀態變化：
| 狀態 | 主色 | 重點色 |
|---|---|---|
| Ready | 橙色（255, 179, 71） | 淡金色（255, 241, 168） |
| Searching（充能中 / 維持中） | 暖橙色（255, 140, 66） | 金色（255, 209, 102） |
| Exhausted | 紅色（255, 107, 107） | 暖橙色（255, 159, 104） |
閒置粒子僅在玩家位於大砲 36 格內、enableParticles 為 true，且沒有自訂模型啟用時才會渲染。
浮動狀態標籤
每座已啟用的大砲都會在其基座上方生成一個面向玩家的 TextDisplay，顯示其顯示名稱與目前狀態（Ready、Charging、Maintaining 或 Exhausted）。已停用的大砲不會生成標籤。標籤為非持久性（永不儲存至區塊資料），並在區塊重新載入時自動重建。它位於大砲上方 1.2 格處；若有 FreeMinecraftModels 模型啟用，則為 2.0 格。
執行階段驗證行為
當以下任一檢查失敗時，CannonRTP 會拒絕候選降落位置：
- 目標世界未載入
- 搜尋中心無法解析（只有在目標世界未載入時才會發生）
- 隨機取樣落在世界邊界外
- 候選區塊無法載入
- 找不到安全的固體非液體表面
- 降落點上方 52 格空投柱中的任何方塊被阻擋
- 表層方塊或柱中任一方塊與設定的不安全材質清單匹配
- 保護插件整合阻擋降落
CannonRTPLocationValidationEvent監聽器否決候選位置
搜尋失敗累計達到 searchTimeoutAttempts 次後（預設 100），預載可能進入 Exhausted 狀態。佇列中已有的目的地仍可使用。只有在佇列為空時啟動才會顯示設定的失敗訊息，其中彙整了常見拒絕原因。發射後釋出佇列位置會重設計數器。
使用前，請生成或探索目標世界設定的搜尋區域。CannonRTP只載入現有區塊，不生成地形；未探索的搜尋半徑可能無法提供任何目的地。
互動防護
CannonRTP 會阻止玩家在已處於發射序列中時再次觸發大砲。該觸發狀態會一直鎖住，直到發射結束且玩家確實離開了大砲的觸發半徑，因此被救回大砲座位並不會立刻開始另一次發射。發射被接受之後，管理器層級的每位玩家冷卻也會在 runtime.launchCooldownSeconds（預設 30 秒）內封鎖所有大砲。只要伺服器持續運行，該冷卻在斷線後仍會保留；它使用單調時鐘，並會在 CannonRTP 重建其大砲時被清除：/wc reload、免重啟的插件更新、插件關閉，或任何編輯大砲的指令（create、place、remove、delete、target、center）。重建也會取消進行中的發射、將這些玩家送回大砲座位，並捨棄所有佇列中的目的地。過早踏入大砲會發送可設定的 launchCooldown 訊息；將設定值設為 0 可停用此關卡。