跳至主要内容

Java 轉 Bedrock 轉換

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

會轉換哪些內容​

轉換器不再僅限於 FreeMinecraftModels。它會在合併後的 Java 資源包上連續執行兩條管線：

  1. FreeMinecraftModels bone 掃描器 — 擷取 assets/freeminecraftmodels/models/ 下的 FMM bone 模型，並將每個 bone 轉換為一個 Bedrock 附掛物 (attachable)。
  2. 通用物品定義管線 — 遍歷每個符合 1.21.4+ 格式的 assets/<namespace>/items/*.json 檔案（跳過 minecraft 與 freeminecraftmodels 命名空間）。對每個葉節點模型會選擇下列其中之一：
    • 產出扁平的 Bedrock 物品欄圖示（適用於一般的 minecraft:item/generated 與類似的扁平內建父模型），或
    • 產出 Bedrock 幾何模型、附掛物、動畫檔以及軟體渲染的 2D 物品欄圖示（適用於真正的 3D 模型）。

每組 (模型 × 基礎物品) 都會產生唯一的 Bedrock 識別碼，因此例如將同一把劍模型註冊到多個基礎物品時，在 Geyser 端不會發生衝突。

當存在並列的 assets/<namespace>/equipment/<material>.json 時，會偵測到自訂盔甲組。轉換器會串接一個盔甲附掛物，結合原版盔甲幾何與 Java 材質作為可見圖層，因此 Bedrock 玩家穿戴該物品時可看到正確的盔甲材質。

Bedrock 資源包的 manifest UUID 是依資源包名稱以確定性方式衍生，因此跨建置之間保持穩定；每次建置只會更新版本三元組（cache-bust token 由建置時間衍生）。

每個工作階段即時提供​

當偵測到 Geyser-Spigot 時，ResourcePackManager 會註冊一個 SessionLoadResourcePacksEvent 訂閱者。每位在新一次混合之後加入的 Bedrock 玩家，都會直接從磁碟收到最新的 Bedrock 資源包，材質或模型編輯無需重啟伺服器。

Geyser 的自訂物品對應 (custom_mappings/ 中的 JSON) 仍會在啟動時凍結，因此新增自訂物品或移除既有物品時，仍需重啟伺服器才能讓 Bedrock 用戶端看到那些變更。RSPM 會在啟動早期預先佈署上一次執行的對應檔，讓 Geyser 啟動時的自訂物品註冊能自動取得。

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

輸出檔案​

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

plugins/ResourcePackManager/output/ResourcePackManager_Bedrock.zip
plugins/ResourcePackManager/output/rspm_geyser_mappings.json

若啟用了自動佈署且偵測到 Geyser，對應檔也會複製到：

<geyser-folder>/custom_mappings/rspm_geyser_mappings.json

Bedrock 資源包的 zip 不會複製到 <geyser-folder>/packs/——而是改為每個工作階段即時提供。RSPM 也會移除舊版外掛在該資料夾中遺留的舊副本，避免 Geyser 重複提供同一個資源包（重複的 UUID 會讓 Bedrock 用戶端混淆）。

config.yml 設定​

# 完全切換 Java 轉 Bedrock 轉換。
bedrockConversionEnabled: true

# 在每次混合時，將 Geyser 自訂對應檔複製到偵測到的 Geyser 資料夾的
# custom_mappings/ 目錄中。
bedrockAutoDeployToGeyser: true

# 手動覆寫 Geyser 資料夾路徑。留空 = 自動偵測。
# 可為絕對路徑，或相對於 plugins/ 目錄的路徑。
bedrockGeyserFolder: ""

自動偵測依序檢查：

  1. 若有設定 bedrockGeyserFolder（先視為絕對路徑，再視為相對於 plugins/ 的路徑）。
  2. plugins/Geyser-Spigot/
  3. plugins/Geyser-*/（任何變體）
  4. config/Geyser-*/（適用於 Fabric/NeoForge 環境）

調整手持物品顯示：bedrock_display_offsets.yml​

Bedrock 透過一個父 bone 來渲染手持物品，而該 bone 的靜止姿勢與 Java 的第一人稱/第三人稱變換不同，因此算法式轉換必須在 Java 模型 display 變換所指定的內容之上再套用一個基礎偏移。預設偏移適用於一般的右手 Java 模型，但特殊情況可能需要調整。

第一人稱與第三人稱是兩個完全獨立的 Bedrock 渲染流程（不同的父 bone、不同的靜止姿勢），因此各自有獨立的六個調整項。調整其中一邊不會影響另一邊。

# ===== 第一人稱（右手，由持有者看到的視角）=====
firstPersonBaseRotationX: -90.0   # pitch（朝向/遠離鏡頭傾斜）。預設值用於抵消父層旋轉。
firstPersonBaseRotationY: 0.0     # yaw（繞垂直軸旋轉）
firstPersonBaseRotationZ: 0.0     # roll（繞鏡頭前向軸旋轉）
firstPersonBasePositionX: 0.0     # 螢幕上的垂直位置（正值 = 向上）
firstPersonBasePositionY: 12.5    # 深度（正值 = 更深入場景）
firstPersonBasePositionZ: 0.0     # 螢幕上的水平位置（正值 = 向右）

# ===== 第三人稱（右手，由其他玩家/F5 看到的視角）=====
thirdPersonBaseRotationX: 90.0    # 觀察者所見的 pitch
thirdPersonBaseRotationY: 0.0     # yaw
thirdPersonBaseRotationZ: 0.0     # 繞物品長軸的 roll
thirdPersonBasePositionX: 0.0     # 跨持有者身體的水平位置（正值 = 向外）
thirdPersonBasePositionY: 12.5    # 垂直位置（正值 = 抬高模型）
thirdPersonBasePositionZ: 0.0     # 相對於持有者的深度（正值 = 向前）

位置值的單位為像素，其中 1 像素 = 1/16 個方塊。旋轉值的單位為角度。

Bedrock 用戶端會即時重新載入 attachable JSON，無需重新啟動。若有 Bedrock 測試用戶端已登入，改完數值後執行 /rspm reload，下一次 Bedrock 加入（或在某些情況下，目前已連線的玩家在世界中執行一個會重新綁定附掛物的小動作之後）即可看到新的偏移。反覆迭代直到看起來正確。

限制與已知行為​

  • 3D 物品欄圖示是透過 Java 模型的 display.gui 變換以軟體渲染。渲染結果合理但並非像素級完美；若圖示看起來不對，最常見的原因是模型參照的材質檔案缺失或檔名錯誤。
  • 用作物品圖示的 flipbook 材質會被裁切為第 0 幀——Bedrock 的 item_texture.json 不支援動畫圖示，只有透過 flipbook_textures.json 的方塊/地形材質才支援動畫。
  • 附掛物幾何格式版本固定為 1.21.0（舊版外掛為 1.16.0）；若你的安裝無法解析，請更新 Geyser。
  • 原版物品模型 (shield.json、crossbow.json) 不會跨資源包遞迴合併，以避免跨資源包的 predicate-tree 損壞；這兩者以最高優先級資源包的版本為準。
  • 若轉換器無法解析某個被參照的材質或模型檔，該葉節點會被略過，並記錄一則 [BedrockConverter] 警告；管線其餘部分會繼續執行。