跳到主要内容

Java 到基岩版转换

ResourcePackManager 可以将合并后的 Java 资源包转换为基岩版资源包，让 GeyserMC 客户端看到与 Java 客户端相同的自定义内容。该功能默认启用。

哪些内容会被转换​

转换器不再仅限于 FreeMinecraftModels。它会对合并后的 Java 资源包依次运行两条流水线：

  1. FreeMinecraftModels 骨骼扫描器 — 拾取位于 assets/freeminecraftmodels/models/ 下的 FMM 骨骼模型，并将每个骨骼转换为一个基岩版可附着物（attachable）。
  2. 通用物品定义流水线 — 遍历所有符合 1.21.4+ 格式的 assets/<namespace>/items/*.json 文件（跳过 minecraft 与 freeminecraftmodels 命名空间）。对每个叶子模型，它会：
    • 输出一个扁平的基岩版背包图标（针对 minecraft:item/generated 等扁平 builtin 父模型），或
    • 输出基岩版几何体（geometry）、可附着物（attachable）、动画文件以及由软件渲染的 2D 背包图标（针对真正的 3D 模型）。

每对 (模型 × 基础物品) 都会生成唯一的基岩版标识符，因此例如同一把剑模型绑定到多个基础物品时，在 Geyser 端不会发生冲突。

当 assets/<namespace>/equipment/<material>.json 同级存在时，会被识别为自定义盔甲套装。转换器会装配一个将原版盔甲几何体与 Java 贴图作为可见层组合的盔甲可附着物，使基岩版玩家穿戴该物品时能看到正确的盔甲贴图。

基岩版资源包的清单 UUID 是根据资源包名确定性派生的，因此跨次构建保持稳定；每次构建只会更新版本三元组（cache-bust 令牌取自构建时间）。

按会话实时分发​

当检测到 Geyser-Spigot 时，ResourcePackManager 会注册一个 SessionLoadResourcePacksEvent 订阅者。每个在新一次合并之后加入的基岩版玩家，都会直接从磁盘获取最新的基岩版资源包，贴图或模型编辑无需重启服务器。

Geyser 的自定义物品映射（即 custom_mappings/ 中的 JSON）仍然是启动时冻结的，因此新增或移除自定义物品仍需重启服务器，基岩版客户端才能看到这些变更。RSPM 会在启动早期预先部署上一次运行生成的映射文件，让 Geyser 在启动时的自定义物品注册流程能够自动拾取它。

当前已连接的基岩版玩家会保留各自加入时收到的资源包——这是基岩版协议的限制，插件无法在会话中途绕过它。

输出文件​

合并成功后，基岩版相关文件位于：

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

如果启用了自动部署并检测到 Geyser，映射文件还会被复制到：

<geyser-folder>/custom_mappings/rspm_geyser_mappings.json

基岩版资源包的 zip 不会被复制到 <geyser-folder>/packs/ 中——而是按会话实时分发。RSPM 还会移除旧版本插件可能留在该文件夹中的遗留副本，以免 Geyser 重复分发同一份资源包（重复的 UUID 会让基岩版客户端困惑）。

config.yml 设置​

# 总开关：是否启用 Java 到基岩版的转换。
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​

基岩版通过一个父骨骼来渲染手持物品，而该骨骼的静止姿势与 Java 的第一人称/第三人称变换并不相同，因此算法在转换时必须在 Java 模型的 display 变换之上额外施加一个基础偏移。默认偏移适用于典型的右手 Java 模型，但特殊情况可能需要微调。

第一人称与第三人称是两个完全独立的基岩版渲染通道（父骨骼不同，静止姿势不同），所以各有一组互相独立的六个旋钮。调整一个不会影响另一个。

# ===== 第一人称（右手，持有者视角）=====
firstPersonBaseRotationX: -90.0   # 俯仰角（向相机方向倾斜/远离）。默认值用于抵消父级旋转。
firstPersonBaseRotationY: 0.0     # 偏航角（绕垂直轴旋转）
firstPersonBaseRotationZ: 0.0     # 翻滚角（绕相机前向轴）
firstPersonBasePositionX: 0.0     # 屏幕上的纵向位置（正值 = 向上）
firstPersonBasePositionY: 12.5    # 深度（正值 = 向场景纵深方向）
firstPersonBasePositionZ: 0.0     # 屏幕上的横向位置（正值 = 向右）

# ===== 第三人称（右手，其他玩家或 F5 视角）=====
thirdPersonBaseRotationX: 90.0    # 旁观者所见的俯仰角
thirdPersonBaseRotationY: 0.0     # 偏航角
thirdPersonBaseRotationZ: 0.0     # 绕物品长轴的翻滚角
thirdPersonBasePositionX: 0.0     # 沿持有者身体的横向位置（正值 = 向外）
thirdPersonBasePositionY: 12.5    # 纵向（正值 = 抬高模型）
thirdPersonBasePositionZ: 0.0     # 相对持有者的深度（正值 = 向前）

位置值以像素为单位，1 像素 = 1/16 个方块。旋转以度为单位。

基岩版客户端会在不重启的情况下热重载可附着物 JSON。如果有一个基岩版测试客户端已在线，修改数值后运行 /rspm reload，下一次基岩版玩家加入时（在某些情况下，连接中的同一玩家做一个能重新绑定可附着物的小动作之后）就会看到新的偏移。如此反复迭代直到效果合适。

局限性与已知行为​

  • 3D 背包图标由软件根据 Java 模型的 display.gui 变换渲染。效果合理但并非像素级精确；如果图标看起来不对，最常见的原因是模型引用的贴图文件缺失或命名错误。
  • 用作物品图标的连拍贴图（flipbook）会被裁剪到第 0 帧——基岩版的 item_texture.json 不支持动画图标，只能通过 flipbook_textures.json 支持动画方块/地形贴图。
  • 可附着物几何体的格式版本固定为 1.21.0（旧版插件曾使用 1.16.0）；如果你的安装无法解析它，请升级 Geyser。
  • 原版物品模型（shield.json、crossbow.json）不会跨资源包递归合并，以避免 predicate 树被破坏；这两个文件由最高优先级资源包的版本取胜。
  • 如果转换器无法解析某个被引用的贴图或模型文件，会跳过该叶子并记录一条 [BedrockConverter] 警告；其余流水线继续执行。