ResourcePackManager 設定

本頁涵蓋單一伺服器（獨立）的設定方式。若你運行 BungeeCord / Velocity 網路，請改參閱代理網路——你會在代理上安裝同一個 ResourcePackManager.jar，但它會產生自己的設定並扮演代理端的角色。

ResourcePackManager 2.x 以單一通用 jar 發布。同一個 ResourcePackManager.jar 可在 Bukkit/Paper 後端以及 Velocity / BungeeCord 代理上執行，透過載入器偵測平台。不再需要解壓獨立的 resourcepackmanager-velocity-*.jar / resourcepackmanager-bungee-*.jar 檔案。如果偵測到代理後的後端沒有已儲存或初始衍生的網路金鑰，RSPM 會在 plugins/ResourcePackManager/proxy-extension/ResourcePackManager.jar 準備自身 jar 的副本，供你複製到代理，就是同一檔案放在方便的位置。

後端外掛描述檔宣告的是 Bukkit API 1.21.4，因此 Bukkit/Paper 伺服器必須是 Minecraft 1.21.4 或更新版本。內附的 Geyser 自訂實體擴充功能則以 Geyser 2.11+ 為目標。

建議的設定（獨立）

1. 將 ResourcePackManager.jar 放入伺服器的 plugins/ 資料夾。（這與你在 Velocity / BungeeCord 代理上會使用的是同一個 jar——沒有獨立的代理 jar。）
2. 啟動伺服器一次，讓設定檔、mixer、blueprint 與 output 資料夾自動產生。
3. 決定你想要：
   • 自我託管（預設開啟）
   • MagmaGuy 的免費自動託管作為回退（預設開啟）
   • 強制用戶端接受
   • 在 mixer 資料夾中手動加入自訂資源包
4. 修改設定或手動加入自訂資源包後，執行 /rspm reload。

預設設定下，RSPM 優先嘗試經過驗證的自我託管；驗證失敗或無法使用時，透過 magmaguy.com 遠端託管。若兩條自動路徑皆失敗，就無法公告新的交付 URL。將設定視為完成前，請檢查最終狀態和用戶端下載。

成功建立託管後，會產生如下主控台輸出：

[ResourcePackManager] Resource pack is live via self-hosting — http://play.example.com:25566/rspm.zip

RSPM 刻意讓主控台保持安靜——它回報的是結果而非每個步驟，而且不會為自己就能恢復的狀況發出警告（自我託管探測失敗後成功回退，是成功而非故障）。若有需要診斷的情況，請執行 /rspm verbose on（或在 config.yml 中設定 verboseLogging: true）並重新載入。請參閱疑難排解。

RSPM 會產生的資料夾

位於 plugins/ResourcePackManager/ 之下：

資料夾	用途
mixer/	把做好的 .zip 資源包放在這裡即可納入合併。在 priorityOrder 中要以其確切檔名（含 .zip）參照它們。
resource_pack/	把未壓縮的資源包放在這裡（含 assets/、pack.mcmeta 等的資料夾樹）。RSPM 會將其壓縮，並以 ResourcePackManager 這個優先級條目納入合併，該條目位於預設 priorityOrder 的最上方。
blueprint/	存放 RSPM 貢獻給合併的預設 pack.png 與 pack.mcmeta。編輯它們即可變更合併後資源包的圖示或其 pack.mcmeta 描述；此資料夾會在每次啟動時重新壓縮成 blueprint.zip。
output/	完成的成品：ResourcePackManager_RSP.zip，以及 Bedrock 轉換有產出時的 ResourcePackManager_Bedrock.zip 與 rspm_geyser_mappings.json。
compatible_plugins/	每個受支援的外掛整合各一個 YAML。
data_compliance/	/rspm data_compliance_request 寫入其下載內容的位置。
proxy-extension/	代理後端沒有已儲存或初始衍生的網路金鑰時建立。內含執行中的 ResourcePackManager.jar 副本，供安裝到代理。殘留資料夾不能證明後端仍未連結。
geyser-extension/	自動擴充功能安裝啟用、本機存在 Floodgate 且沒有 Geyser-Spigot 時匯出。複製到外部 Geyser 的 extensions/ 時，請遵循主控台的確切路徑，它可能位於 update/ 內。匯出不會設定外部資源包交付。

核心指令

• /rspm setup — 開啟一個遊戲內的 GUI 設定選單（外掛更新狀態、推薦外掛、自動更新切換，以及一個帶有可點擊連結的資訊按鈕，連往 wiki、Discord 與你的 Nightbreak 帳號 token）
• /rspm recommendedplugins — 顯示共用的 Nightbreak 推薦外掛選單
• /rspm downloadpluginupdate — 下載可用的 ResourcePackManager 更新，供下次重啟時套用
• /rspm downloadall — 下載此外掛所公開的所有可用更新（目前即 ResourcePackManager 的更新）
• /rspm applypluginupdate — 由共用的 Nightbreak 指令組註冊，但 RSPM 一律會拒絕執行：ResourcePackManager updates need a server restart: its Geyser extension only loads when Geyser starts. 請重啟伺服器以套用已下載的更新。
• /rspm reload — 重新啟動外掛初始化並安排資源包準備；未變更的資源包可重用現有託管註冊
• /rspm status — 印出完整的診斷資訊：資源包狀態、託管模式、網路金鑰指紋、整合狀況
• /rspm verbose [on|off] — 不需開啟 config.yml 即可開關詳細診斷日誌。不帶參數時為切換。選擇會寫回 config.yml 中的 verboseLogging，因此重啟後仍有效。別名為 /rspm verboselogging。
• /rspm itemsadder configure — 自動為 RSPM 託管設定 ItemsAdder（見下文）
• /rspm itemsadder dismiss — 為你的玩家 UUID 永久關閉 ItemsAdder 警告
• /rspm data_compliance_request — 下載此伺服器所有遠端儲存的資料

主指令是 /resourcepackmanager，/rspm 是其別名。上方的更新與推薦外掛指令是由 RSPM 註冊的共用 MagmaCore/Nightbreak 指令。

權限：

• /rspm setup 與 /rspm recommendedplugins 需要 resourcepackmanager.setup。/rspm setup 僅限玩家使用，因為它會開啟一個物品欄 GUI。
• /rspm downloadpluginupdate、/rspm downloadall、/rspm applypluginupdate、/rspm reload、/rspm status、/rspm verbose、/rspm itemsadder <configure|dismiss> 與 /rspm data_compliance_request 均需要 resourcepackmanager.*。

ItemsAdder

目前建議的 ItemsAdder 流程不再僅限於手動操作。

使用：

/rspm itemsadder configure

該輔助工具更新 ItemsAdder 的相關設定、請求重新產生資源包，並等待 RSPM 合併新的匯出內容。具體會：

• 設定 resource-pack.hosting.no-host.enabled: true
• 停用 resource-pack.zip.protect-file-from-unzip 下的 protection_1、protection_2 與 protection_3
• 設定 resource-pack.zip.compress-json-files: false（RSPM 需要未壓縮、可解析的模型 JSON 供混合器與 Bedrock 轉換器使用）
• 在 20 個伺服器 tick 後執行 /iareload，再過 100 tick 執行 /iazip
• 等待 RSPM 的監控程式取得重新產生的 ItemsAdder 匯出內容並完成合併，然後回報 RSPM merged the regenerated ItemsAdder export. Use /rspm status to check hosting.。若合併失敗，會回報匯出內容無法合併，並由 RSPM 重試。

輔助工具不會重新載入 ResourcePackManager。若先前的設定仍在進行中，它會拒絕啟動；若 ItemsAdder 的 config.yml 在編輯期間發生變更，它會停止且不儲存。若 ItemsAdder 拒絕 /iareload 或 /iazip，請手動執行該指令。合併訊息確認的是合併，而非託管：之後請檢查 /rspm status 與真實用戶端下載。

若 ItemsAdder 已被設定為託管自己的資源包（自我託管、外部託管或 lobfile），輔助工具會停止，並提示你先手動停用 ItemsAdder 託管。

Bedrock / GeyserMC 支援

RSPM 可以將合併 Java 資源包中的受支援素材轉換為 GeyserMC 使用的 Bedrock 資源包。它掃描任何外掛的 1.21.4+ 物品定義，包括支援的 3D 手持物品與裝備；這不保證轉換每種模型節點、判斷條件或盔甲設計。請查閱下方轉換指南中的支援限制。

bedrockConversionEnabled 預設為 true。轉換還要求偵測到 Bedrock 目標並存在受支援的來源素材；啟動時註冊可能需要依下文說明重新啟動 Geyser。

對於獨立伺服器，當下列任一條件成立時轉換便會啟動：此伺服器上已安裝 Geyser-Spigot、此伺服器上已安裝 Floodgate，或 RSPM 偵測到代理模式（請參閱代理網路）。

本機安裝 Geyser-Spigot 且 geyserExtensionAutoInstall: true 時，RSPM 會在 plugins/Geyser-Spigot/extensions/ 安裝或暫存其通用 jar。重新啟動伺服器才能載入新安裝或暫存的擴充功能。自訂 Bedrock 實體還要求相容的產生端透過橋接標記 Java 實體、註冊定義，以及正確的用戶端資源包。geyserExtensionAutoInstall: false 阻止後續安裝和暫存，但不會刪除已安裝 jar 或取消已暫存的更新。請參閱 Geyser 擴充功能與自訂實體。

完整管線、輸出路徑及手持物品姿勢，請參閱 Bedrock / Geyser 轉換。

驗證設定

使用公開 HTTPS 下載位址時，請保持自動託管啟用，並將 selfHostExternalUrl 設為反向代理的完整資源包 URL。監聽與轉送設定請參閱 HTTPS 與反向代理。

在主控台或以 OP 身份執行 /rspm status。輸出分為以下幾個區塊：

• 外掛資訊 — 版本與部署模式（獨立或網路後端）。網路後端還顯示簡短、非機密的網路金鑰指紋與來源：代理提供、本伺服器儲存、從 Floodgate 金鑰衍生或尚未設定。
• Java 資源包 — 是否已合併、大小、SHA1 前綴
• Bedrock 資源包 — 是否已轉換、對應檔是否存在，以及略過轉換時的診斷提示
• 託管 — 目前交付路徑（自我託管／遠端／尚未就緒）、用戶端 URL、解析的外部主機、偵測到的公開 IP，以及最近一次自我託管檢查的結果與失敗原因
• 代理部署 — 提醒使用同一個 ResourcePackManager.jar，複製到網路代理的 plugins/ 資料夾
• 整合 — Floodgate／Geyser-Spigot 偵測結果與線上玩家數

狀態顯示交付 URL 後，請以真實用戶端加入、接受資源包，並檢查已知的自訂物品或模型。Bedrock 在資源包重建後應重新連線；需要註冊新對應或實體定義時，應重新啟動 Geyser。狀態和託管日誌描述的是發布情況，不是用戶端算繪結果。

若有任何問題，請參閱疑難排解。

下一步

• 常見問題 — 常見疑問
• Bedrock / Geyser 轉換 — 轉換器細節
• Geyser 擴充功能與自訂實體 — 擴充功能安裝與 Geyser 版本需求
• 自我託管 — 內建 HTTP 伺服器、連接埠解析
• 代理網路 — 若你運行 BungeeCord / Velocity
• API — 從程式碼註冊你的外掛資源包