CannonRTP 設定
CannonRTP 將其全域設定分散於 plugins/CannonRTP/ 中的多個檔案，另外每座大砲在 plugins/CannonRTP/cannons/ 中各有一份設定檔。
檔案配置
| 檔案 | 用途 |
|---|---|
plugins/CannonRTP/config.yml | 頂層執行階段旗標（設定狀態、語言、粒子間隔、大砲模型優先順序、Spigot 資源 id） |
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 內容包產生的中繼資料（版本、下載連結、用於尋找其檔案的前綴）。通常不應手動編輯。 |
插件預設附帶三份範例大砲設定：
example_cannonrtp.yml—— 空白參考範本，預設停用。手動撰寫大砲檔案時可作為 YAML 參考使用。cannonrtp_free_cannon.yml—— 已啟用、無放置點，指向免費的cannonrtpFMM 模型。cannonrtp_premium_cannon.yml—— 已啟用、無放置點，指向高級的cannonrtp_premiumFMM 模型。
預設情況下這些檔案的 cannonLocations 皆未填入，因此在管理員執行 /wc create 或 /wc place 之前，世界中不會生成任何東西。
config.yml
| 鍵 | 預設 | 行為 |
|---|---|---|
setupDone | false | 追蹤 Nightbreak 首次設定是否已完成 |
language | english | 要載入的翻譯檔案。Release 1 僅提供英文；此鍵為未來翻譯包預留 |
runtime.particleIntervalTicks | 15 | 大砲閒置粒子渲染的頻率（最低 5） |
runtime.cannonModelPriority | [cannonrtp_premium, cannonrtp] | FreeMinecraftModels 模型名稱的優先順序清單，由上至下檢查。伺服器上找到的第一個模型會用於未自行設定 customModel 的所有大砲。若皆未找到，則使用軌道粒子回退方案。 |
runtime.spigotResourceId | "" | 版本檢查器使用的 Spigot 資源 id。留空以停用。 |
landing.yml
| 鍵 | 預設 | 行為 |
|---|---|---|
preloadedLocationsPerCannon | 10 | 插件嘗試為每座大砲維持的安全目的地總數（最低 1） |
chargedLocationsPerCannon | 1 | 大砲必須保有多少位置，其狀態標籤才會切換為 Ready（最低 1，上限為 preloadedLocationsPerCannon）。只要佇列中至少有一個位置，大砲即會發射玩家 —— 此門檻只影響視覺標籤。 |
searchTimeoutAttempts | 100 | 多少次失敗的搜尋嘗試後大砲會被標記為 Exhausted（最低 10）。搜尋嘗試在全域上每 tick 限速一次（每秒 20 次），公平地在所有啟用中的大砲之間分配。 |
slowFallingSeconds | 60 | 空投後緩降效果的最大持續時間（最低 1）。玩家觸地時效果會提早被移除。 |
failOpenOnProtectionErrors | false | 若保護插件 API 發生錯誤，預設會阻止降落。設為 true 則在無法安全查詢保護插件時允許降落繼續。 |
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）。無效音效名稱會以警告形式記錄，該步驟的音效會被默默略過。
messages.yml
所有訊息皆支援 MagmaCore 漸層、MiniMessage 標籤，以及舊式 & 顏色代碼。$prefix 預留位置會以已設定的前綴取代。
完整的訊息鍵、預留位置以及發射序列所使用的標題池清單，請參閱訊息與標題頁面。
每座大砲的設定欄位
每個大砲檔案（plugins/CannonRTP/cannons/<id>.yml）儲存以下欄位：
| 欄位 | 預設 | 備註 |
|---|---|---|
isEnabled | true（用於新建大砲） | 已停用的大砲不會觸發，並顯示為 Disabled |
displayName | CannonRTP（或建立時傳入的名稱） | 用於訊息、狀態輸出與浮動標籤 |
cannonLocations | 空清單 | 序列化的 world,x,y,z,pitch,yaw 字串清單。一份大砲設定可生成多個世界中的放置點。由 /wc create、/wc place、/wc remove 管理。 |
targetWorld | 建立時所在的當前世界 | 支援跨世界目標 —— 將此設為與大砲不同的世界，可使玩家降落在那個世界中。執行時必須已載入，否則大砲會顯示為 Invalid。 |
searchCenter | null | 若未設定，插件會從大砲自身位置（當大砲位於目標世界時）或從目標世界的出生點向外擴散 |
triggerRadius | 1.75 | 用於偵測附近玩家的大砲周圍半徑（最低 0.5 格） |
minSearchRadius | 500 | 從搜尋中心起的最小降落搜尋距離（最低 0） |
maxSearchRadius | 5000 | 最大降落搜尋距離（永遠被限制為至少 minSearchRadius + 1） |
launchWarmupTicks | 42 | Searching 階段的長度，以 tick 計（最低 1） |
verticalBoostTicks | 45 | Firing 階段的長度，以 tick 計（最低 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 在伺服器運行期間被啟用或停用，大砲模型快取會被清除，視覺會於下一個 tick 重新整理。
閒置粒子回退方案
當沒有模型啟用時，大砲會在大砲中心周圍渲染一對軌道運行的 DUST_COLOR_TRANSITION + FIREWORK 粒子。顏色會根據大砲的有效狀態變化：
| 狀態 | 主色 | 重點色 |
|---|---|---|
| Ready | 橙色 | 金色 |
| Searching（充能中 / 維持中） | 暖橙色 | 金色 |
| Exhausted | 紅色 | 暖紅色 |
| Invalid configuration | 深紅色 | 紅色 |
閒置粒子僅在玩家位於大砲 36 格內時渲染。
浮動狀態標籤
每座大砲都會在其基座上方生成一個面向玩家的 TextDisplay，顯示其顯示名稱與目前狀態（Ready、Charging、Maintaining、Exhausted、Disabled 或 Invalid）。標籤為非持久性（永不儲存至區塊資料），並在區塊重新載入時自動重建。
執行階段驗證行為
當以下任一檢查失敗時，CannonRTP 會拒絕候選降落位置：
- 目標世界未載入
- 搜尋中心無效
- 隨機取樣落在世界邊界外
- 候選區塊無法載入
- 找不到安全的固體非液體表面
- 腳部或頭部空間被阻擋
- 地形或身體方塊與設定的不安全材質清單匹配
- 保護插件整合阻擋降落
CannonRTPLocationValidationEvent監聽器否決候選位置
若大砲用盡 searchTimeoutAttempts（預設 100）仍未填滿其儲備，它會變為 Exhausted 狀態，並開始回傳設定的失敗訊息而非發射玩家。失敗訊息會包含最常見拒絕原因的摘要。每當佇列有名額釋出（例如發射後），大砲就會重設其逾時計數器。
互動防護
CannonRTP 會防止玩家在已處於發射序列中時觸發大砲。一旦目前的發射完成（降落或斷線），玩家即可再次使用大砲。沒有額外的冷卻計時器。