Java 轉 Bedrock 轉換

ResourcePackManager 可將合併後的 Java 資源包轉換為 Bedrock 資源包，讓 GeyserMC 用戶端看到其中受支援的自訂內容。此功能預設啟用。

何時會執行轉換

轉換以「是否存在 Bedrock 目標」為條件。下列任一條件成立時，RSPM 即視為存在目標：

1. 此後端上安裝了 Geyser-Spigot（Bedrock 玩家在本地連線到 Geyser）。
2. 此後端上安裝了 Floodgate（典型的代理-後端架構——Floodgate 在本地執行，Geyser 在其他地方）。
3. 網路模式啟用中——RSPM 偵測到自身位於 Velocity / BungeeCord 代理後方。後端會產出其 Bedrock 資源包，並透過一個小型 HTTP 伺服器公開，讓代理外掛能拉取。

還需要透過 bedrockConversionEnabled 啟用轉換。若轉換已關閉或沒有目標，RSPM 會撤回先前的 Bedrock 輸出並略過轉換。/rspm status 會說明資源包未產生的原因。

會轉換哪些內容

轉換器與命名空間無關。它會遞迴地遍歷每個符合 1.21.4+ 物品定義格式的 assets/<namespace>/items/**/*.json 檔案，並包含 minecraft 命名空間。

扁平與 3D 的路由判定

轉換器會為每個葉節點模型決定要走兩條管線中的哪一條。以 minecraft:item/generated 或 minecraft:builtin/generated 為根的模型會留在扁平路徑。對於其他所有父模型鏈，只有當模型合併後帶有非空的 elements 陣列時，它才會走 3D 管線；沒有幾何的模型即為 2D 貼圖。

• 扁平：將模型的 layer0 材質複製到 textures/items/<hash>.png 並註冊為 Geyser 圖示。Bedrock 使用這一層作為物品欄和手持的 2D 貼圖，不會保留任意的其他 Java 圖層或模型分支。
• 3D — 轉換器會拼接材質圖集、將 Java 立方體轉換為 Bedrock 幾何、產生手持／頭部動畫、以軟體渲染出 64×64 的物品欄圖示，並為每組 (模型 × 基礎物品 × 物品定義 × 謂詞形狀) 對應寫出一個附掛物。

為什麼幾何檢查很重要：一個扁平的手持工具（父模型為 minecraft:item/handheld、只有 layer0 材質且沒有 elements）仍然是 2D 貼圖。較早的版本會把扁平的手持物品推進 3D 管線，導致它們在幾何步驟失敗，並在 Bedrock 上消失或退回為原版基礎物品圖示。這對 ItemsAdder 資源包影響尤其明顯，因為它們提供大量扁平的手持物品。由於 elements 是從合併後的父模型鏈讀取，因此非產生型、但從父模型繼承幾何的模型仍會被路由到 3D。

RSPM 為每組 (模型 × 基礎物品 × 物品定義 × 謂詞形狀) 對應衍生 Bedrock 識別碼，以區分同一劍模型的不同基礎物品和謂詞變體，並讓重複使用同一模型的兩個物品定義保有各自的識別碼。產生的檔名使用來源識別碼的短雜湊，而非檔案內容的雜湊，避免觸發 Geyser 對 80 字元以上資源包路徑的警告。

支援的物品模型分支

轉換支援 model、condition、range_dispatch 和 select 節點，可以有或沒有 minecraft: 前綴。其他節點類型，包括 composite 和 special，會被略過。Java 資源包顯示正常，不代表每個分支都能在 Bedrock 重現。

節點	支援的屬性和後備行為
condition	broken、damaged、fishing_rod_cast、has_component、custom_model_data。using_item 只保留 on_false 作為閒置模型。其他不支援的條件會略過兩個分支。
range_dispatch	damage、count、bundle_fullness、custom_model_data。use_duration 和其他不支援的屬性只保留 fallback，如果存在。
select	charge_type、trim_material、context_dimension、custom_model_data。display_context 保留 gui 分支，沒有 GUI 分支時使用後備。其他不支援的屬性只保留後備。

這表示 Java 的拉弓階段和各種顯示情境的獨立模型不會自動保留。啟用 bedrockConverterDebug 查看略過的節點和屬性，並在 Bedrock 用戶端檢查產生的物品。

1.21.4 之前的舊版資源包

舊格式掃描器讀取 assets/minecraft/models/item/ 直屬的 JSON 檔案，根據含數值 predicate.custom_model_data 的覆寫項目產生範圍分派定義。它不會遞迴掃描舊格式子目錄，也不會保留覆寫項目的其他謂詞。例如，同時依賴拉弓狀態的覆寫項目會失去該條件。舊格式物品數量只在啟用 bedrockConverterDebug 後顯示。持續維護的資源包請使用 1.21.4+ 物品定義格式，並依上表檢查其分支。

基礎物品

Geyser 會將每個自訂物品對應到一個或多個 Java 基礎物品之下。RSPM 依下列方式選擇：

• 舊格式覆寫檔與根層級的 assets/minecraft/items/<item>.json 定義會對應到該原版物品。
• 其他定義依檔名比對。武器與工具的字詞會對應到相關的原版物品：sword 對應六種劍、pickaxe 對應六種鎬、wand 或 staff 對應 minecraft:stick、spear 對應 minecraft:trident，依此類推。盔甲名稱會使用命名空間的裝備檔案，或 helmet、boots 等裝備欄位字詞。其他所有物品則使用後備組合：紙、木棒、命名牌、指南針與六種劍。
• freeminecraftmodels 命名空間中的定義也會對應到 minecraft:leather_horse_armor 之下，這是 FreeMinecraftModels 用來顯示模型骨骼的物品。
• 產出資源包的外掛可以在 assets/<namespace>/rspm_item_bases/<path>.json 宣告實際的基礎物品，其中 <path> 與 items/<path>.json 相符。檔案內容為 {"base_items": ["minecraft:blaze_rod"]}。只會讀取 minecraft: ID，並將它們加入依檔名選出的結果中。FreeMinecraftModels 會為每個自訂物品寫入一份，內容為其設定所指定的材質，因此以 BLAZE_ROD 為基礎的魔杖會在 Bedrock 上顯示其模型。

僅限 Java 的物品

產出資源包的外掛可以在 assets/<namespace>/rspm_item_java_only/<path>.json 放置檔案，讓物品不參與轉換。只看檔案是否存在。它會排除 items/<path>.json 以及 items/<path>/ 下的所有物品定義，因此這些物品不會取得 Geyser 對應、圖示或附掛物。FreeMinecraftModels 將它用於粒子效果背後的精靈圖物品，這些物品只有 Java 的物品展示實體會使用；Bedrock 玩家看到的則是原生粒子。物品全部僅限 Java 的資源包不會觸發舊格式警告。

手工撰寫的 Bedrock 實體套組

外掛可在 Java 資源包的 assets/<namespace>/rspm_bedrock_pack/ 下提供原生 Bedrock 實體資源。RSPM 將檔案匯入產生的 Bedrock 資源包。只接受實體目錄 entity、models/entity、animations、animation_controllers、render_controllers、materials、particles 和 textures/entity，因此外掛不能覆蓋清單或圖示圖集。受支援的路徑達到 80 字元時會被縮短，同一套組中完全相符的 JSON 路徑參照也會更新。其他檔案按原樣複製。若兩個命名空間在同一輸出位置產生不同位元組，便會發生錯誤。

這正是實現真正自訂 Bedrock 實體的機制——請參閱 Geyser 擴充功能與自訂實體。即使某個資源包只含實體套組、完全沒有物品對應，仍會被發佈。

穿戴盔甲轉換在扁平物品路徑上針對盔甲或鞘翅基礎物品執行。轉換器從物品定義檔名移除已識別的裝備欄位後綴，取得 <material>，再於葉節點模型的命名空間尋找 assets/<namespace>/equipment/<material>.json。它使用 humanoid 的第一層材質；護腿使用 humanoid_leggings，鞘翅在存在時使用 wings。合併後的資源包必須包含對應 PNG。產生的附掛物使用 Bedrock 原版盔甲幾何。只有裝備檔案、額外材質層或無關的裝備資源 ID，不能證明盔甲可以轉換。

Bedrock 資源包的 manifest header / module UUID 是依外掛版本字串以確定性方式衍生（種子為 rspm_bedrock_header:<pluginVersion> 與 rspm_bedrock_module:<pluginVersion>），因此在同一外掛版本的多次重建之間保持穩定，只有在外掛版本變更時才會改變。可見的 header 名稱固定為 ResourcePackManager Bedrock Pack；它不是 UUID 的一部分。版本三元組會在每次建置時依一個 cache-bust token 遞增，該 token 衍生自暫存 Bedrock 資源包內容的 SHA-256 摘要——相同內容會產生相同版本（因此無變動的重建不會擾動 Geyser 的快取），而真正的內容變更則會讓 Bedrock 以 (uuid, version) 為鍵的資源包快取失效。建置時間（System.currentTimeMillis()）僅在無法計算內容摘要時作為後備使用。

每個工作階段即時提供（獨立模式）

啟用轉換且 Geyser-Spigot 位於同一個獨立後端時，RSPM 會訂閱 SessionLoadResourcePacksEvent，從磁碟向每位加入的玩家提供最新獲准發佈的 Bedrock 資源包。如果已註冊的物品對應不變，材質或幾何修改可在下次加入時送達，不必重啟伺服器。網路模式後端將分發交給代理，即使本地也安裝了 Geyser-Spigot。

Geyser 的自訂物品對應，即 custom_mappings/ 中的 JSON，在啟動時固定。增刪物品、修改模型參照或謂詞可能需要新的對應，因此需要重啟。啟用自動佈署時，RSPM 會在啟動早期佈署先前獲准發佈的對應檔。首次轉換成功後，請重啟 Geyser 載入新對應，再重新連線 Bedrock 用戶端。

目前已連線的 Bedrock 玩家會保留各自加入時收到的資源包——這是 Bedrock 通訊協定的限制，外掛無法在工作階段中途覆寫。

在代理模式下如何運作

在代理網路中，後端本身不會註冊 SessionLoadResourcePacks 訂閱者（本地沒有 Geyser 可供訂閱）。改為：

1. 後端產出 output/ResourcePackManager_Bedrock.zip，並在存在物品對應時產出 output/rspm_geyser_mappings.json。
2. 後端啟動一個小型 HTTP 伺服器（自動衍生連接埠，預設為 mcPort + 1），公開 /bedrock.zip 與 /mappings.json 路由，每次請求都會即時讀取檔案，並向代理通報它實際綁定的確切連接埠。
3. 代理外掛每 5 秒輪詢一次，優先使用搭配 If-None-Match 的強 ETag，同時保留對舊版後端的 If-Modified-Since 相容性。它會在每個後端的輸出變更時下載，並等待 inbox 穩定。
4. 代理外掛將每個後端的 Bedrock 資源包合併為單一的網路級資源包，再透過代理的 Geyser 提供給 Bedrock 用戶端。
5. 若代理無法直接連到後端的 HTTP 連接埠（在共享 / 代管託管環境中常見，相鄰埠通常被防火牆擋掉），後端會將檔案推送到 magmaguy.com 中繼端點，代理則從那裡取得。

設定方式請參閱代理網路。代理端的合併是自動進行的，沒有啟用開關。代理設定只有兩個項目：network-http-offset-v2，即在後端端點通報可用之前所使用的後備連接埠偏移量；以及 geyser-extension-auto-install，即 geyserExtensionAutoInstall 的代理端對應設定。

輸出檔案

成功混合之後，Bedrock 檔案會位於：

plugins/ResourcePackManager/output/ResourcePackManager_Bedrock.zip
plugins/ResourcePackManager/output/rspm_geyser_mappings.json  # only when item mappings exist

若啟用了自動佈署，且偵測到本機的 Geyser 資料夾，對應檔也會複製到：

<geyser-folder>/custom_mappings/rspm_geyser_mappings.json

Bedrock 資源包的 zip 不會複製到 <geyser-folder>/packs/——而是改為每個工作階段即時提供。若較舊版本的 RSPM 曾在 Geyser 的資源包目錄中留下 ResourcePackManager_Bedrock.zip，目前的外掛在 Geyser 執行期間不會刪除它：Geyser 已經掃描過該路徑，可能仍將其保留在記憶體中。RSPM 會在該次啟動中略過即時提供者的註冊，並印出確切的舊檔路徑。請完整停止伺服器，只刪除那個舊檔，然後再啟動伺服器。/reload 是不夠的。

沒有可轉換的物品對應或允許的實體檔案時，RSPM 撤回發佈，並嘗試刪除先前的本地輸出及其已佈署到 Geyser 的對應。被鎖定而留下的檔案也不再獲准分發。後端的 /bedrock.zip 回傳 404，表示該後端不提供 Bedrock 內容。只含實體的資源包仍會發佈。單純替換 Java 方塊或原版材質不會產生轉換後的資源包，需要另行製作 Bedrock 資源包。

關閉 bedrockAutoDeployToGeyser 後，RSPM 會在協調設定時移除先前佈署的對應。修改 bedrockGeyserFolder 也會清理原先由 RSPM 管理的目標位置。這些操作都不會改變執行中的 Geyser 已載入的對應；請重啟 Geyser 套用新的對應集合。

config.yml 設定

# Toggles Java-to-Bedrock conversion altogether.
bedrockConversionEnabled: true

# Copies the Geyser custom mappings file into the detected Geyser folder's
# custom_mappings/ directory on each mix.
bedrockAutoDeployToGeyser: true

# Manual override for the Geyser data folder. Empty = auto-detect.
# Relative values are tried from the server working directory first, then
# relative to plugins/. Absolute paths work directly.
bedrockGeyserFolder: ""

# Installs and updates the universal ResourcePackManager.jar in Geyser's
# extensions/ folder, which is what makes custom Bedrock ENTITIES render
# instead of armor stands. Separate from pack conversion above — items,
# textures and models convert and serve normally either way.
# Setting this false stops future installation and update staging; it does NOT
# remove an extension jar that is already installed. Delete that by hand while
# Geyser is stopped. See the Geyser extension page.
geyserExtensionAutoInstall: true

# Verbose per-item / per-bone progress logging from the Bedrock pipeline.
# Default false — a clean run emits a single "Bedrock conversion complete: N
# mappings" summary instead of dozens to hundreds of per-item lines. Flip on
# when debugging a specific conversion issue.
bedrockConverterDebug: false

自動偵測 Geyser 資料夾時，會依序檢查：

1. 若有設定 bedrockGeyserFolder（先按照字面值使用，因此相對路徑會從伺服器工作目錄解析；若該位置不存在，再改以相對於 plugins/ 嘗試）。絕對路徑同樣可用。
2. plugins/Geyser-Spigot/
3. plugins/Geyser-*/（任何變體）
4. config/Geyser-*/（適用於 Fabric/NeoForge 環境）

手持物品姿勢

每個 3D 附掛物都會取得第一人稱、第三人稱與頭部動畫。手持姿勢來自 Java 模型的 display.firstperson_righthand 與 display.thirdperson_righthand 變換。RSPM 會透過原版 Bedrock 玩家骨架對應每個變換，讓手持模型落在 Java 繪製它的位置，並具有相同的位置、方向與各軸縮放。模型未定義的欄位會使用 Java 的單位變換。頭部動畫則來自 display.head。

這裡沒有需要調整的項目。若要改變物品在手中的位置，請修改 Java 模型的 display 變換；Java 與 Bedrock 便會採用相同的數值。骨架使用寬手臂（Steve），因此使用細手臂外觀時，Bedrock 可能與 Java 相差半個像素。

較早的版本會從 plugins/ResourcePackManager/bedrock_display_offsets.yml 加入手動調整的偏移。該檔案及其 firstPerson* 與 thirdPerson* 設定已不再被讀取，RSPM 在更新後會重新產生快取的 Bedrock 資源包。舊的檔案副本可以刪除。

手持物品粒子

產出資源包的外掛可以透過位於 assets/<namespace>/rspm_item_particles/<model path>.json 的附屬檔案，為手持的 3D 物品附加粒子，其中 <model path> 是手持 Java 模型的路徑（freeminecraftmodels:display/wand 即為 display/wand）。附屬檔案會將效果名稱對應到外掛在其實體套組中提供的粒子識別碼，以 Java 模型像素列出定位器，並包含一條循環粒子時間軸。RSPM 會將定位器加入物品幾何，並把時間軸作為額外的附掛物動畫播放，讓 Bedrock 用戶端在第一人稱與第三人稱下都於手部繪製粒子。FreeMinecraftModels 會為具有粒子效果的物品寫入這些附屬檔案。無法讀取的附屬檔案會被略過並發出警告。

除錯日誌

有兩個除錯介面可用：

• 後端：在 config.yml 中設定 bedrockConverterDebug: true 會開啟轉換器的逐物品、逐附掛物、逐對應日誌行。當你需要了解某個特定物品為何沒進入 Bedrock 資源包時相當有用。這與 verboseLogging 是分開的——後者涵蓋的是資源包合併與託管，而非 Bedrock 管線；遇到轉換問題時你要用的是 bedrockConverterDebug。
• 代理（Velocity 與 BungeeCord）：/rspm debug bedrock on 會切換代理 GeyserBinder 發出的 [RSPM-BedrockDebug] 日誌串流。當 Bedrock 玩家加入代理但看不到資源包時相當有用。此設定會在代理重啟時重置為關閉，因此不會意外被遺留為開啟。

限制與已知行為

• 3D 物品欄圖示是透過 Java 模型的 display.gui 變換以軟體渲染。渲染結果合理但並非像素級完美；若圖示看起來不對，最常見的原因是模型參照的材質檔案缺失或檔名錯誤。
• 用作物品圖示的 flipbook 材質會被裁切為第 0 幀——Bedrock 的 item_texture.json 不支援動畫圖示，只有透過 flipbook_textures.json 的方塊/地形材質才支援動畫。
• 附掛物幾何格式版本固定為 1.21.0；若你的安裝無法解析，請更新 Geyser。
• 舊版原版物品模型覆寫檔（assets/minecraft/models/item/ 下的任何檔案，包括 shield.json 與 crossbow.json）會跨資源包合併，而非讓單一資源包完全勝出：只有 overrides 陣列會被合併（並依覆寫鍵去除重複），非覆寫欄位則維持「最高優先級勝出」。沒有任何檔案會被挑出來特殊處理。
• 若轉換器無法解析某個被參照的材質或模型檔，該葉節點會被略過，管線其餘部分則繼續執行。啟用 bedrockConverterDebug 可取得詳細的解析追蹤。當某個物品最終完全沒有有效的自訂材質，或某個被參照的模型 JSON 無法解析時，會發出一般等級的警告。
• 無法解析的物品定義 JSON 會以 Bedrock conversion failed: ... 中止轉換。有效 JSON 若缺少模型或含有不支援的節點，則可能只是被略過並記錄除錯日誌。請檢查錯誤和產生的對應數量，不要將每個略過的定義都視為致命解析錯誤。
• 旗幟與紅石基礎物品會被略過。 基礎物品為 16 種染色旗幟之一或 minecraft:redstone 的自訂物品不會取得 Geyser 自訂物品對應，因為 Geyser 會從那些基礎物品衍生出無效的方塊放置器。Bedrock 上會顯示原版圖示。發生時主控台會列出受影響的物品。
• 轉換支援協作式取消。RSPM 暫存 ZIP 和對應，再將發佈內容整組替換。替換過程中失敗或取消時，會嘗試還原上一組；替換前的轉換失敗則撤回舊輸出。已發佈的雜湊和資源組中繼資料可讓接收方拒絕過時或混合的世代。磁碟上存在 ZIP，不能證明它目前獲准分發，也不能證明 Bedrock 用戶端已渲染它。
• 合併後的資源包既沒有可轉換對應，也沒有允許的實體檔案時，RSPM 撤回先前發佈並嘗試刪除輸出。只含實體的資源包在物品對應為零時也會產生。

資源包大小最佳化

在發佈 Bedrock 資源包之前，RSPM 會去除副檔名相同且位元組完全一致的重複材質檔案，並將精確的 JSON 材質參照改寫為指向保留下來的檔案。當某個參照有歧義、內嵌在較長的字串中，或出現在格式錯誤／不透明的 JSON 內時，它會刻意保留別名，以免最佳化悄悄破壞資源參照。