跳到主要内容

ResourcePackManager (RSPM)

ResourcePackManager 用于发现、合并、托管并分发来自受支持插件以及手动提供的资源包。它还可以将合并后的 Java 资源包转换为基岩版资源包，让 GeyserMC 玩家能看到与 Java 玩家相同的自定义内容，并且原生支持 BungeeCord 与 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 插件——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 代理上）— 拉取每个后端的基岩版资源包及映射，将它们合并为一个全网络统一的资源包，然后通过代理上的 Geyser 分发给基岩版客户端。

独立服务器只需要在后端安装这个 jar。代理网络需要在代理和提供资源包的后端安装同一个 jar。已在代理中注册但没有运行 RSPM 的服务器不会拖延资源包分发。详见后端发现。

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

托管方式​

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

  1. 强制自托管（selfHostForce: true）— 覆盖 autoHost 和 selfHostEnabled，跳过探测和远程上传。主要用于测试。公告 URL 前，URL 验证和监听器启动仍须成功。
  2. 当 autoHost: true、preferSelfHost: true 且 selfHostEnabled: true 时，RSPM 在独立服务器和代理后端上都优先尝试自托管。检查主机地址，比较从 localhost 和玩家确切 URL 下载的资源包样本，并要求外部可达后才公告 URL。验证失败或不可用时回退到远程托管。代理仍从后端 HTTP 服务器获取基岩版产物。
  3. 远程托管回退 — 自托管禁用或验证失败时，RSPM 复用或上传资源包到 magmaguy.com/rsp/ 并公告该 URL。远程失败可在 selfHostEnabled: true 时回退到自托管，但须经过同样的验证。两条自动路径均失败时，不公告新的分发 URL。

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

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

selfHostExternalUrl 可设置为通过反向代理或 TLS 终止服务公开的完整 HTTP 或 HTTPS URL。将 /rspm.zip 请求转发给 RSPM，即可继续使用自动资源包分发。

Java 到基岩版的转换​

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

  • 任何使用 1.21.4+ 物品定义格式的插件资源包，其 3D 物品、自定义盔甲和带模型的装备都能在基岩版玩家端正确显示。
  • 自定义盔甲贴图在基岩版玩家身上会以原版盔甲几何体为基础，将 Java 贴图作为可见层叠加渲染。
  • 3D 物品的背包图标由软件根据 Java 模型的 display.gui 变换渲染。
  • 基岩版资源包通过 Geyser 的 API 按基岩版会话实时分发，因此对贴图与模型的微调会到达下一个加入的基岩版玩家，无需重启服务器。自定义物品映射仍需重启，因为 Geyser 是在启动时注册它们的。
  • 手持的 3D 物品从 Java 模型的 display.firstperson_righthand 和 display.thirdperson_righthand 变换获取第一人称和第三人称姿势，并映射到原版基岩版玩家骨架上。没有需要调整的偏移。
  • 如果手持 3D 物品所属的插件提供了粒子附属文件（例如带粒子效果的 FreeMinecraftModels 物品），基岩版玩家也能看到这些粒子。实体资源包同样可以附带基岩版粒子文件。

当前集成情况​

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），并将基岩版资源包分发流程接入找到的那一个。

下一步​