跳到主要内容

ResourcePackManager (RSPM)

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

它能做什么​

  • 自动发现受支持插件的资源包并按 priorityOrder 合并
  • 内置自己的 HTTP 服务器，可以自托管合并后的资源包（无需外部文件托管服务）
  • 当自托管不可行时，可回退到 MagmaGuy 的免费托管（auto-host）
  • 可强制或可选地提示玩家使用资源包
  • 监视资源包变更，并在来源稳定后自动重新合并
  • 将合并后的 Java 资源包转换为可供 GeyserMC 使用的基岩版资源包
  • 适配代理网络：每个后端生成自己的基岩版资源包，代理插件拉取并合并它们，再通过 Geyser 分发结果

架构概览​

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

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

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

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

当后端检测到本地安装了 Geyser-Spigot 时，它还会把一个捆绑的 ResourcePackManager-GeyserBridge.jar 放入 Geyser-Spigot/extensions/（这是一个 Geyser 扩展，而非独立插件），让 Geyser 能够渲染 RSPM 的自定义基岩版实体。

托管方式​

当 autoHost: true 时，系统会按以下顺序自动选择三种分发路径之一：

  1. 优先自托管（preferSelfHost: true，默认值）— RSPM 启动自己的 HTTP 服务器，运行一连串完整性检查（非 LAN 地址、本地回环自探测、通过 magmaguy.com 的外部可达性探测），并向客户端公告本地 URL。对 MagmaGuy 而言带宽成本为零。
  2. 远程自动托管回退 — 如果任一自托管检查失败，RSPM 会将资源包上传到 MagmaGuy 的 CDN（magmaguy.com/rsp/），转而公告该 URL。
  3. 强制自托管（selfHostForce: true）— 完全跳过两层探测和远程上传。主要用于测试。

如果 autoHost: false，RSPM 会将合并后的 zip 写入 plugins/ResourcePackManager/output/，由你自行处理后续流程。

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

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

下一步​