跳到主要内容

ResourcePackManager 安装设置

本页面介绍单服务器（独立）的安装流程。如果你运行 BungeeCord / Velocity 网络，请改为参阅代理网络 — 你在代理上安装的是同一个 ResourcePackManager.jar，但它会生成自己的配置并扮演代理侧的角色。

ResourcePackManager 2.x 以单个通用 jar 发布。同一个 ResourcePackManager.jar 可在 Bukkit/Paper 后端以及 Velocity / BungeeCord 代理上运行，并通过加载器检测平台。不再需要解压单独的 resourcepackmanager-velocity-*.jar / resourcepackmanager-bungee-*.jar 文件。如果检测到代理后的后端没有已保存或初始派生的网络密钥，RSPM 会在 plugins/ResourcePackManager/proxy-extension/ResourcePackManager.jar 准备自身 jar 的副本供你复制到代理，就是同一文件放在方便的位置。

后端插件描述符声明的 Bukkit API 为 1.21.4，因此 Bukkit/Paper 服务器必须是 Minecraft 1.21.4 或更高版本。内置的 Geyser 自定义实体扩展面向 Geyser 2.11+。

  1. 将 ResourcePackManager.jar 放入服务器的 plugins/ 目录。（这与你在 Velocity / BungeeCord 代理上使用的是同一个 jar——没有单独的代理 jar。）
  2. 启动一次服务器，让插件生成配置文件、mixer、blueprint 以及 output 文件夹。
  3. 决定你是否希望：
    • 启用自托管（默认开启）
    • 启用 MagmaGuy 的免费 auto-host 回退（默认开启）
    • 强制客户端接受资源包
    • 通过 mixer 文件夹手动添加自定义资源包
  4. 修改配置或手动添加自定义资源包后，运行 /rspm reload。

默认设置下，RSPM 优先尝试经过验证的自托管；验证失败或不可用时，通过 magmaguy.com 远程托管。如果两条自动路径均失败，就无法公告新的分发 URL。将安装视为完成前，请检查最终状态和客户端下载。

成功建立托管后，会产生如下控制台输出：

[ResourcePackManager] Resource pack is live via self-hosting — http://play.example.com:25566/rspm.zip

RSPM 刻意让控制台保持安静 —— 它报告的是结果而不是每一个步骤，并且不会对它自己能恢复的状况发出警告（一次失败的自托管探测之后成功回退，那是成功而不是故障）。如果确实需要诊断，请运行 /rspm verbose on（或在 config.yml 中设置 verboseLogging: true）并重载。参见故障排查。

RSPM 会生成的文件夹​

位于 plugins/ResourcePackManager/ 下：

文件夹用途
mixer/把做好的 .zip 资源包放到这里以并入合并。在 priorityOrder 中用它们确切的文件名（包含 .zip）来引用。
resource_pack/把未压缩的资源包放到这里（带有 assets/、pack.mcmeta 等的文件夹树）。RSPM 会把它打包并在 ResourcePackManager 这一优先级条目下合并，该条目位于默认 priorityOrder 的最顶端。
blueprint/存放 RSPM 自己贡献给合并的默认 pack.png 与 pack.mcmeta。编辑它们即可更改合并后资源包的图标或其 pack.mcmeta 描述；该文件夹在每次启动时都会重新打包为 blueprint.zip。
output/最终产物：ResourcePackManager_RSP.zip，以及基岩版转换产出时的 ResourcePackManager_Bedrock.zip 与 rspm_geyser_mappings.json。
compatible_plugins/每个受支持的插件集成对应一个 YAML 文件。
data_compliance//rspm data_compliance_request 写入下载内容的位置。
proxy-extension/当代理后端没有已保存或初始派生的网络密钥时创建。包含运行中的 ResourcePackManager.jar 副本，供你安装到代理。残留文件夹不证明后端仍未关联。
geyser-extension/自动扩展安装启用、本地存在 Floodgate 且没有 Geyser-Spigot 时导出。复制到外部 Geyser 的 extensions/ 时，请遵循控制台的确切路径，它可能位于 update/ 内。导出不会配置外部资源包分发。

核心命令​

  • /rspm setup — 打开一个游戏内 GUI 设置菜单（插件更新状态、推荐插件、自动更新开关，以及一个带有指向 wiki、Discord 和你的 Nightbreak 账户令牌的可点击链接的信息按钮）
  • /rspm recommendedplugins — 显示共享的 Nightbreak 推荐插件菜单
  • /rspm downloadpluginupdate — 下载可用的 ResourcePackManager 更新，供下次重启时应用
  • /rspm downloadall — 下载本插件暴露的所有可用更新（目前即 ResourcePackManager 更新）
  • /rspm applypluginupdate — 由共享的 Nightbreak 命令集注册，但 RSPM 始终拒绝执行它：ResourcePackManager updates need a server restart: its Geyser extension only loads when Geyser starts.。请重启服务器以应用已下载的更新。
  • /rspm reload — 重新启动插件初始化并安排资源包准备；未变化的资源包可复用现有托管注册
  • /rspm status — 打印完整的诊断信息：资源包状态、托管模式、网络密钥指纹、集成情况
  • /rspm verbose [on|off] — 无需打开 config.yml 即可开启或关闭详细诊断日志。不带参数时为切换。所选结果会写回 config.yml 中的 verboseLogging，因此重启后仍然有效。别名为 /rspm verboselogging。
  • /rspm itemsadder configure — 自动为 RSPM 托管配置 ItemsAdder（见下文）
  • /rspm itemsadder dismiss — 根据玩家 UUID 永久关闭 ItemsAdder 警告
  • /rspm data_compliance_request — 下载本服务器在远程存储的全部数据

根命令为 /resourcepackmanager，/rspm 是它的别名。上面的更新与推荐插件命令是由 RSPM 注册的共享 MagmaCore/Nightbreak 命令。

权限：

  • /rspm setup 与 /rspm recommendedplugins 需要 resourcepackmanager.setup。/rspm setup 仅允许玩家执行，因为它会打开一个物品栏 GUI。
  • /rspm downloadpluginupdate、/rspm downloadall、/rspm applypluginupdate、/rspm reload、/rspm status、/rspm verbose、/rspm itemsadder <configure|dismiss> 以及 /rspm data_compliance_request 都需要 resourcepackmanager.*。

ItemsAdder​

目前推荐的 ItemsAdder 接入方式不再是纯手动配置。

请使用：

/rspm itemsadder configure

该助手更新 ItemsAdder 的相关设置、请求重新生成资源包，并等待 RSPM 合并新的导出。具体来说它会：

  • 将 resource-pack.hosting.no-host.enabled 设为 true
  • 禁用 resource-pack.zip.protect-file-from-unzip 下的 protection_1、protection_2 与 protection_3
  • 将 resource-pack.zip.compress-json-files 设为 false（RSPM 需要未压缩、可解析的模型 JSON 供 mixer 和基岩版转换器使用）
  • 在 20 个服务器 tick 后执行 /iareload，再过 100 tick 执行 /iazip
  • 等待 RSPM 的监视器检测到重新生成的 ItemsAdder 导出并完成合并，然后报告 RSPM merged the regenerated ItemsAdder export. Use /rspm status to check hosting.。如果合并失败，它会报告导出无法合并，RSPM 会重试。

该助手不会重载 ResourcePackManager。在之前的配置仍未完成时，它会拒绝启动；如果 ItemsAdder 的 config.yml 在编辑期间被修改，它会停止且不保存。如果 ItemsAdder 拒绝执行 /iareload 或 /iazip，请手动运行该命令。合并消息只确认合并完成，不代表托管成功：之后请检查 /rspm status 和真实客户端下载。

如果 ItemsAdder 已被配置为自托管资源包（self-host、external-host 或 lobfile），助手命令会停止执行，并提示你先手动禁用 ItemsAdder 的托管。

基岩版 / GeyserMC 支持​

RSPM 可以将合并 Java 资源包中的受支持资产转换为 GeyserMC 使用的基岩版资源包。它扫描任何插件的 1.21.4+ 物品定义，包括支持的 3D 手持物品和装备；这不保证转换每种模型节点、谓词或盔甲设计。请查阅下方转换指南中的支持限制。

bedrockConversionEnabled 默认为 true。转换还要求检测到基岩版目标并存在受支持的源资产；启动时注册可能需要按下文说明重启 Geyser。

对于独立服务器，只要满足以下任一条件即可触发转换：本服务器装有 Geyser-Spigot；本服务器装有 Floodgate；或 RSPM 检测到处于代理模式（详见代理网络）。

本地装有 Geyser-Spigot 且 geyserExtensionAutoInstall: true 时，RSPM 会在 plugins/Geyser-Spigot/extensions/ 安装或暂存其通用 jar。重启服务器才能加载新安装或暂存的扩展。自定义基岩版实体还要求兼容的生成方通过桥接标记 Java 实体、注册定义以及正确的客户端资源包。geyserExtensionAutoInstall: false 阻止后续安装和暂存，但不会删除已安装 jar 或取消已暂存的更新。参见 Geyser 扩展与自定义实体。

完整的流水线说明、输出路径和手持物品姿势请参阅基岩版 / Geyser 转换。

验证安装​

使用公开 HTTPS 下载地址时，请保持自动托管启用，并将 selfHostExternalUrl 设为反向代理的完整资源包 URL。监听和转发设置参见 HTTPS 与反向代理。

在控制台中或以 OP 身份运行 /rspm status。输出分为多个部分：

  • 插件信息 — 版本与部署模式（独立或网络后端）。网络后端还显示简短、非机密的网络密钥指纹及来源：代理提供、本服务器保存、从 Floodgate 密钥派生或尚未设置。
  • Java 资源包 — 是否已合并、大小、SHA1 前缀
  • 基岩版资源包 — 是否已转换、是否有映射文件，以及跳过转换时的诊断提示
  • 托管 — 当前分发路径（自托管／远程／尚未就绪）、客户端 URL、解析的外部主机、检测到的公网 IP，以及最近一次自托管检查的结果和失败原因
  • 代理部署 — 提醒使用同一个 ResourcePackManager.jar，复制到网络代理的 plugins/ 文件夹
  • 集成 — Floodgate／Geyser-Spigot 检测情况和在线玩家数

状态显示分发 URL 后，请用真实客户端加入、接受资源包，并检查已知的自定义物品或模型。基岩版在资源包重建后应重新连接；需要注册新映射或实体定义时，应重启 Geyser。状态和托管日志描述的是发布情况，不是客户端渲染结果。

如果有异常，请查看故障排查。

下一步​