跳至主要內容

Resource Pack Manager 疑難排解

此頁面僅涵蓋目前 ResourcePackManager 程式碼中已確認的行為。

對任何 RSPM 問題而言，最有用的第一步是：

/rspm status

它會印出版本、佈署模式（獨立 vs 網路後端）、遮罩過的網路金鑰、Java + Bedrock 資源包狀態、目前啟用的交付路徑及其 URL、解析後的外部主機 + 自動偵測的公開 IP、所有相關的設定旗標、一則代理佈署提醒（網路代理 jar 就是同一個 ResourcePackManager.jar），以及 Floodgate / Geyser-Spigot 的偵測結果。當該 jar 在代理上執行時也有同樣的指令，可印出代理端的對應資訊（後端清單、各後端的擷取結果、合併後的資源包狀態）。

玩家沒有收到資源包​

請先檢查以下事項：

  • 若你希望 ResourcePackManager 自動推送 URL，必須啟用 autoHost
  • 合併後的資源包必須存在，且至少一條交付路徑（自我託管或遠端）必須已成功
  • 玩家只會在加入時，或在託管首次就緒當下發出的首次上傳廣播時才會收到資源包

如有需要：

  1. 執行 /rspm status 並查看「Hosting」區段。Active delivery 會顯示目前正在使用自我託管、遠端或兩者皆未使用。
  2. 若顯示「active delivery: not yet ready」——混合或上傳仍在進行中。當玩家過早加入時，外掛會在主控台以大字橫幅顯示警示，並在交付就緒的當下自動發送資源包。
  3. 若顯示「active delivery: none — hosting disabled or failed」——表示 autoHost 已停用，或自我託管探測與遠端上傳皆失敗。請參閱下方的「自我託管健全性檢查失敗」與「自動託管無法連線到遠端伺服器」。
  4. 執行 /rspm reload，觀察主控台上的上傳 / 自我託管探測結果，然後用測試玩家重新加入。

若你是透過自己的外部管線進行自我託管（autoHost: false），RSPM 不會為你推送自訂 URL。在該設定下，你仍需自行處理伺服器端的資源包派送流程。

已安裝 ItemsAdder，但其內容未出現在最終資源包中​

這通常表示 ItemsAdder 仍以某種方式設定，導致 ResourcePackManager 無法讀取或託管其輸出。

使用：

/rspm itemsadder configure

該指令目前會：

  • 啟用 resource-pack.hosting.no-host.enabled
  • 停用 protection_1、protection_2 與 protection_3
  • 設定 resource-pack.zip.compress-json-files: false
  • 執行 /iareload，然後 /iazip
  • 約 15 秒後重新載入 ResourcePackManager

若該指令告知你 ItemsAdder 已在託管自己的資源包，請先手動停用 ItemsAdder 託管，再執行一次指令。

合併後的資源包無效或無法上傳​

ResourcePackManager 的自動託管整合會明確處理下列伺服器端錯誤類型：

  • 缺少必要檔案
  • 檔案過大
  • 檔案格式無效
  • 缺少工作階段
  • 遠端伺服器無法使用

若遇到上述情況：

  1. 執行 /rspm reload 重新建置資源包。
  2. 檢查是否某個來源資源包已損毀、加密或無法讀取。
  3. 檢查最終合併的資源包根目錄是否仍包含有效的 pack.mcmeta 與 pack.png。

外掛會略過無法乾淨解壓的資源包，並在主控台輸出警告。

當遠端自動託管回傳 SESSION_NOT_FOUND 錯誤時，RSPM 會清除其工作階段 UUID，並在下一次 keep-alive tick 重新初始化——無需手動介入。

某個外掛的資源覆蓋了另一個外掛的資源​

這由下列檔案中的 priorityOrder 控制：

plugins/ResourcePackManager/config.yml

較高的條目會勝過較低的條目。

對於不可合併的檔案，ResourcePackManager 會取代較低優先級的檔案；對於可合併的 JSON 檔案，則會合併內容。目前可合併的 JSON 類別為：

  • sounds.json
  • 語言檔
  • minecraft/models/item 下的原版物品模型 JSON（非遞迴合併：只有 overrides 陣列會跨資源包合併，檔案其餘部分則遵循「最高優先級勝出」）
  • atlas 檔
  • font 檔
  • items/ 下的 1.21.4+ 物品模型定義（格式感知合併，會尊重 predicate-tree 結構）

pack.mcmeta 也採用特殊合併規則：最高的 pack_format 勝出、supported_formats 範圍會擴大（支援整數、雙整數陣列以及 {min_inclusive, max_inclusive} 物件格式）、overlay 條目會被合併，且非標準頂層鍵會保留。Overlay 條目會被標準化以相容 1.21.9+，缺少時會自動加上 min_format/max_format 欄位。基礎 atlas 來源也會合併到 overlay atlas 檔中，避免 overlay 遮蔽基礎條目。

若需檢視上一次合併期間的細節，請查看：

plugins/ResourcePackManager/collision_log.txt

GUI 文字或字型元素顯示錯誤​

字型檔是 ResourcePackManager 會合併的其中一個 JSON 類別，但這並不保證兩種不同的字型系統在 Minecraft 中能良好共存。

若字型驅動的選單或 HUD 顯示異常：

  1. 調整 priorityOrder，讓你想保留的資源包排在更高位置。
  2. 執行 /rspm reload。
  3. 檢查 collision_log.txt，確認衝突是否如預期發生。

資源包變更未立即顯示​

ResourcePackManager 對受支援的資源包來源有一個監視器。

它會等待某個變動的資源包 3 秒內未再變動，然後一旦所有受監視的資源包都穩定，重新混合便會立即發生。

若你正在主動重新產生其他外掛的資源包，請在檔案寫入停止後再等幾秒。若有疑慮，可在上游外掛完成後執行 /rspm reload。

自我託管健全性檢查失敗；改回退至遠端託管​

當 preferSelfHost: true（預設）且三項自我託管健全性檢查之一失敗時，此訊息屬於正常行為：

  1. 第 1 層（heuristic） — 解析後的外部主機為 RFC1918 / loopback / link-local。請將 selfHostExternalHost 設為你的實際公開主機名稱，或確保外掛能連到 api.ipify.org / checkip.amazonaws.com。
  2. 第 2 層（本機 self-probe） — 對 http://127.0.0.1:<port>/rspm.zip 發出的 HEAD 請求未回傳含非空主體的 200。可揪出連接埠綁定衝突或資源包檔案缺失。
  3. 第 3 層（外部可達性探測） — magmaguy.com 試圖擷取你公告的 URL 卻連不上。最常見原因：HTTP 連接埠未在路由器 / 防火牆上轉送。探測 URL 與原因會被記錄下來。

修復方式（依優先順序）：在防火牆與路由器上開放 HTTP 連接埠、將 selfHostExternalHost 設為可路由的主機名稱，或將 preferSelfHost: false 完全略過自我託管。

當 magmaguy.com 探測本身無法連線時（RSPM 連請求都送不出去），會保留自我託管而非標記失敗——理由是回退路徑同樣需要 magmaguy.com，若以無法探測為由拒絕承諾自我託管會自相矛盾。

完整的決策樹請參閱自我託管。

自動託管無法連線到遠端伺服器​

ResourcePackManager 的內建遠端託管會與以下位址通訊：

https://magmaguy.com/rsp/

若連線失敗，外掛會記錄通訊警告，且在重新連線成功前無法使用遠端回退。

你的選擇有：

  1. 修正伺服器對外 HTTPS 連線
  2. 等待遠端服務恢復可用
  3. 停用 autoHost，改以自我託管產生的 zip
  4. 開放你的 HTTP 連接埠並保持 preferSelfHost: true，這樣 RSPM 完全無需 magmaguy.com 即可使用自我託管（此情況下也建議將 selfHostExternalHost 設為你的公開主機名稱，使第 3 層外部探測變得不必要——當探測發生 IOException 時，RSPM 會保留自我託管）

我想透過自己的網頁伺服器自我託管合併後的資源包​

由程式碼支援的設定方式為：

  1. 設定 autoHost: false。
  2. 若希望 ResourcePackManager 將額外副本寫入已存在的資料夾，請設定 resourcePackRerouting。
  3. 自行託管 ResourcePackManager_RSP.zip。

resourcePackRerouting 路徑會以 plugins 目錄為基準解析，目標資料夾必須已存在。

若你想改為使用 RSPM 內建的自我託管 HTTP 伺服器（這是不同的東西——與外掛位於同一 JVM 中），請參閱自我託管。

我需要檢視為此伺服器儲存了哪些遠端資料​

使用：

/rspm data_compliance_request

若有作用中的遠端託管工作階段，ResourcePackManager 會將回應下載至：

plugins/ResourcePackManager/data_compliance

若沒有遠端工作階段（例如你正在使用自我託管），該指令會回報沒有遠端資料可索取。

沒有產生 Bedrock 資源包​

bedrockConversionEnabled 預設為 true，因此應會自動執行。請先執行 /rspm status——Bedrock Pack 區段會告訴你為何磁碟上沒有資源包：

  • 「No Bedrock target detected」——本地沒有 Geyser-Spigot、沒有 Floodgate，也不在網路模式中。轉換是刻意被略過的。請安裝 Floodgate（用於代理設定）或 Geyser-Spigot（用於獨立設定），然後執行 /rspm reload。
  • 「Network mode is active so this backend SHOULD produce a Bedrock pack. The file is missing」——通常表示首次混合週期尚未完成（啟動後等約 30 秒），或掃描器在合併後的資源包中找不到任何物品定義，或轉換過程拋出例外。在主控台搜尋 [BedrockConverter] 警告或 Generic scanner: discovered 0 items definition files。

若 Geyser 自動偵測失敗：

  1. 在 config.yml 中將 bedrockGeyserFolder 設為你的 Geyser 資料夾路徑（例如 Geyser-Spigot）。
  2. 該路徑可為絕對路徑，或相對於 plugins 目錄的路徑。

轉換器會自動偵測 plugins/Geyser-Spigot/、任何 plugins/Geyser-*/ 變體，或 Fabric/NeoForge 環境下的 config/Geyser-*/。

如需逐物品 / 逐 bone 的日誌輸出，請設定 bedrockConverterDebug: true 並重新載入。

Bedrock 玩家看到的手持物品位置不正確​

這是調整問題，並非轉換 bug。開啟 plugins/ResourcePackManager/bedrock_display_offsets.yml 並調整相關軸。第一人稱與第三人稱是獨立的——調整一邊不會影響另一邊。Bedrock 用戶端會即時重新載入 attachable JSON，無需重新啟動，因此迭代很快。完整的調整選項列表與各項說明，請參閱 Bedrock 轉換頁面。

Bedrock 玩家缺少自訂盔甲材質​

自訂盔甲在 Bedrock 上的呈現是結合原版盔甲幾何與 Java 材質作為可見圖層。要使其正常運作，來源外掛的資源包必須在 assets/<namespace>/equipment/<material>.json 下定義一個與物品定義並列的裝備檔。若轉換日誌顯示該物品但遊戲中沒有盔甲材質，請確認該檔案存在於合併後的資源包中。

代理：啟動時出現「Floodgate key.pem missing」​

代理外掛在代理主機上找不到 plugins/floodgate/key.pem 而進入閒置狀態。RSPM 從該檔案衍生網路身份識別，若沒有該檔案，代理就無法連結到任何後端。修復方式：

  1. 在代理上安裝 Floodgate。Bedrock 玩家要連到代理本來就需要它，因此無論如何 RSPM 都需要這個。
  2. 確保代理上的 plugins/floodgate/key.pem 與每個後端的同名檔案逐位元組相同。將其中一份正本的 key.pem 複製到每個元件（其他後端 + 代理），然後重新啟動所有元件。Floodgate 本來就要求這樣以用於 Bedrock 認證，因此如果你網路上的 Bedrock 玩家目前能正常運作，這部分就已完成。

代理：經過數次輪詢仍顯示「no merged pack」​

在代理上經過 ~20 秒的空輪詢週期（預設間隔 5 秒，共 4 次）之後，RSPM 會記錄一次性的診斷橫幅，列出它輪詢過的每個後端、嘗試過的 HTTP URL，以及結果（200 / 304 / 404 / CONNECT_FAILED / 等等）。該橫幅會說明最常見的修復方式：

  • 每個後端皆顯示 CONNECT_FAILED → 代理無法連到後端的 HTTP 連接埠。請檢查 velocity.toml / config.yml 中設定的位址是否為代理實際可達的位址（而非例如代理網路中無法解析的 Docker 內部名稱），並確認後端通報的 HTTP 連接埠在代理與後端之間是開放的。該橫幅會印出它嘗試的確切 URL；在某個後端通報其連接埠之前，代理會回退至 mcPort + network-http-offset-v2，因此早期的 CONNECT_FAILED 也可能表示該後備連接埠尚不可達。
  • 每個後端皆顯示 NOT_FOUND_404 → 後端正在運作但未產生 Bedrock 資源包。請在每個後端執行 /rspm status；Bedrock Pack 診斷區塊會告訴你原因。

該橫幅在每次「卡住」期間只會觸發一次，當至少一個後端開始重新回傳內容時，會記錄一行「NetworkSync: recovered」。更多資訊請參閱代理網路。

代理：首次代理啟動時 Bedrock 玩家看不到模型​

Geyser 只在代理啟動時才會註冊其自訂物品表。如果代理在任何後端產出 Bedrock 資源包之前啟動，Geyser 會在空對應表的狀態下運行，並維持整個工作階段不變。

修復方式是在後端記錄了 Wrote merged Geyser mappings: N entries 之後重新啟動代理。RSPM 會在代理啟動時預先佈署前次執行的對應檔，因此這個問題僅會在全新安裝時出現——之後的啟動都會在 Geyser 掃描前就準備好對應內容。

後端：「Backend HTTP server failed to bind on port X」​

在網路模式下，後端會透過一個小型 HTTP 伺服器公開其 Bedrock 輸出。若連接埠被佔用或無法使用，主控台會出現多行的 [ERROR] 區塊。修復方式：

  • 在 config.yml 中將 selfHostPort 設為另一個正整數。
  • 或變更 networkHttpOffset-v2，讓自動衍生的連接埠避開衝突（例如 RCON 在 mcPort + 1？將其設為 2 或 3）。你不需要更新代理以保持一致：一旦後端成功綁定，它就會自動向代理通報其實際的 HTTP 連接埠，因此代理本身的 network-http-offset-v2 只在通報之前作為猜測才有意義。

當後端 HTTP 伺服器停擺時，此後端的 Bedrock 資源包無法透過直接擷取送到代理。但 magmaguy.com 中繼回退仍能運作（後端會將檔案推送到中繼端點，代理則從那裡擷取）。

清理過時的 v1 設定​

從 RSPM v1 升級的操作員，其 config.yml 中可能還留有失效的 networkHttpOffset（沒有 -v2）鍵。RSPM v2 刻意不讀取舊鍵——下次啟動時會自動將 v2 預設值（1）寫入設定。失效的 v1 鍵會作為無害的殘留留在設定中，直到你手動清理為止。