跳到主要内容

ResourcePackManager (RSPM)

ResourcePackManager 用于发现、合并、托管并分发来自受支持插件以及手动提供的资源包。它还可以将合并后的 Java 资源包转换为基岩版资源包，让 GeyserMC 玩家能看到与 Java 玩家相同的自定义内容，并且原生支持 BungeeCord、Waterfall 与 Velocity 代理网络。

它能做什么​

  • 自动发现受支持插件的资源包并按 priorityOrder 合并
  • 内置自己的 HTTP 服务器，可以自托管合并后的资源包（无需外部文件托管服务）
  • 当自托管不可行时，可回退到 MagmaGuy 的免费托管（auto-host）
  • 可强制或可选地提示玩家使用资源包
  • 监视资源包变更，并在来源稳定后自动重新合并
  • 将合并后的 Java 资源包转换为可供 GeyserMC 使用的基岩版资源包
  • 通过随附的 Geyser 扩展向 Geyser 注册真正的基岩版自定义实体，让建模实体（例如 FreeMinecraftModels、EliteMobs）在基岩版玩家端正常渲染并播放动画
  • 适配代理网络：每个后端生成自己的基岩版资源包，代理插件拉取并合并它们，再通过 Geyser 分发结果
  • 无需粘贴任何密钥即可完成网络链接：代理持有网络密钥，把它保存到自己的 network-key 文件中，并在玩家首次连接到某个后端时自动推送给它
  • 能够在整个网络上保持自身最新：后端通过一条经过认证的路由提供通用插件 jar；代理会校验其结构与版本、拒绝降级、用 SHA-256 校验传输过来的字节，并把它暂存到下次关闭时应用

架构概览​

RSPM v2 是一个多模块的 Maven 构建，但它以单个 jar 的形式发布：ResourcePackManager.jar。这一个 jar 同时包含 Bukkit/Paper 插件、Velocity 插件以及 BungeeCord/Waterfall 插件——Minecraft 会加载与所运行平台相匹配的那个入口点。不再有单独的 ResourcePackManager-Velocity.jar / ResourcePackManager-BungeeCord.jar 文件需要解压。

proxy-extension/ 文件夹依然存在，但如今它的含义不同了：当某个后端发现自己位于代理之后、且从未收到过网络密钥时，它会在 plugins/ResourcePackManager/proxy-extension/ResourcePackManager.jar 暂存一份与自身正在运行的 jar 逐字节相同的副本，并提示你把那一个文件复制到代理上。它只是你已经拥有的那个 jar 的便利副本，而不是按平台区分的另一个构件。

同一个 jar 会根据你放置它的位置扮演两种角色：

  • 作为后端插件（放在每个 Paper/Spigot 后端上）— 合并 Java 资源包、运行基岩版转换器、托管资源包、暴露一个小型 HTTP 服务器，并将资源包推送给 Java 客户端。
  • 作为代理插件（放在 Velocity 或 BungeeCord/Waterfall 代理上）— 拉取每个后端的基岩版资源包及映射，将它们合并为一个全网络统一的资源包，然后通过代理上的 Geyser 分发给基岩版客户端。

独立服务器只需要在后端放置这个 jar。代理网络则需要在每个后端上都放置同一个 jar，并在代理上也放一份。

同一个 jar 还兼作 Geyser 扩展。当后端检测到本地安装了 Geyser-Spigot 时，它会把完全相同的这个通用 ResourcePackManager.jar 安装到 Geyser-Spigot/extensions/ 中，让 Geyser 能够渲染 RSPM 的自定义基岩版实体；代理角色也会对代理端的 Geyser 做同样的事。（较早的版本会附带一个单独的 ResourcePackManager-GeyserBridge.jar —— 该文件已废弃，并会通过 Geyser 的更新队列自动替换。）参见 Geyser 扩展与自定义实体。

托管方式​

Java 资源包的分发按以下优先级进行：

  1. 强制自托管（selfHostForce: true）— 覆盖 autoHost 与 selfHostEnabled，跳过所有探测和远程上传，直接公告本地 URL。主要用于测试。
  2. 优先自托管（autoHost: true、preferSelfHost: true 且 selfHostEnabled: true，均为默认值）— RSPM 启动自己的 HTTP 服务器，运行一连串完整性检查（非 LAN 地址、本地回环自探测、通过 magmaguy.com 的外部可达性探测），并向客户端公告本地 URL。对 MagmaGuy 而言带宽成本为零。在代理后端上会跳过这条“先试自托管”的偏好，直接进入第 3 步；不过后端自己的 HTTP 服务器仍然会运行，因为代理要从它那里拉取基岩版构件。
  3. 远程自动托管回退 — 如果自托管被禁用，或某项实际的自托管可达性检查失败，RSPM 会将资源包上传到 MagmaGuy 的 CDN（magmaguy.com/rsp/），转而公告该 URL。如果远程路径失败，在 selfHostEnabled: true 时它可以回退到自托管。

如果 autoHost: false 且 selfHostForce: false，RSPM 会将合并后的 zip 写入 plugins/ResourcePackManager/output/，而不推送任何 URL。

完整的分发决策树、端口解析以及外部主机检测请参阅自托管。

Java 到基岩版的转换​

基岩版转换器不再仅限于 FreeMinecraftModels。它会递归遍历合并后资源包中每一个 1.21.4+ 物品定义文件（assets/<namespace>/items/**/*.json），并为提供这些文件的任意插件生成基岩版几何体（geometry）、可附着物（attachables）和背包图标：

  • 任何使用 1.21.4+ 物品定义格式的插件资源包，其 3D 物品、自定义盔甲和带模型的装备都能在基岩版玩家端正确显示。
  • 自定义盔甲贴图在基岩版玩家身上会以原版盔甲几何体为基础，将 Java 贴图作为可见层叠加渲染。
  • 3D 物品的背包图标由软件根据 Java 模型的 display.gui 变换渲染。
  • 基岩版资源包通过 Geyser 的 API 按基岩版会话实时分发，因此对贴图与模型的微调会到达下一个加入的基岩版玩家，无需重启服务器。自定义物品映射仍需重启，因为 Geyser 是在启动时注册它们的。
  • 通过 bedrock_display_offsets.yml 提供 12 个可调旋钮，用于微调手持物品的显示偏移（第一人称 6 个、第三人称 6 个）。

当前集成情况​

ResourcePackManager 内置了以下插件的预设集成：

  • BackpackPlus
  • BetterHUD
  • BetterStructures
  • CannonRTP
  • EliteMobs
  • EternalTD
  • FreeMinecraftModels
  • InfiniteVehicles
  • ItemsAdder
  • MegaBlockSurvivors
  • MMOInventory
  • ModelEngine
  • Nexo
  • Nova
  • Oraxen
  • RealisticSurvival
  • ResurrectionChest
  • ValhallaMMO
  • vane-core

只有当对应插件已安装且其配置的本地路径或远程 URL 可用时，这些集成才会生效。插件还会在启动时检测 Geyser（后端上的 Geyser-Spigot，代理上的 Geyser-Velocity / Geyser-BungeeCord），并将基岩版资源包分发流程接入找到的那一个。

下一步​