Resource Pack Manager 常见问题

如果这里没有你想要的答案，请先查看侧边栏中 ResourcePackManager 的其他页面。

ResourcePackManager 目前提供哪些命令？

在后端（Paper / Spigot）上，代码中实际提供的命令包括：

• /rspm setup — 打开一个游戏内 GUI 设置菜单（插件更新状态、推荐插件、自动更新开关、指向 wiki / Discord / Nightbreak 账户的链接）
• /rspm recommendedplugins — 显示共享的 Nightbreak 推荐插件菜单（在控制台中则显示文本列表）
• /rspm downloadpluginupdate — 下载可用的 ResourcePackManager 更新，供下次重启时应用
• /rspm downloadall — 下载本插件暴露的所有可用更新（目前即 ResourcePackManager 更新）
• /rspm reload — 重新构建并重新托管合并后的资源包
• /rspm status — 完整的诊断信息（资源包状态、托管模式、网络密钥指纹、集成情况）
• /rspm verbose [on|off] — 开启或关闭详细诊断日志。不带参数时为切换。结果会写回 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 reload、/rspm status、/rspm verbose、/rspm itemsadder <configure|dismiss> 与 /rspm data_compliance_request 都需要 resourcepackmanager.*。

在代理插件（Velocity / BungeeCord）上，只提供诊断类命令：

• /rspm status — 代理侧快照：后端列表、各后端的拉取结果、合并后的资源包状态、Geyser/Floodgate 检测情况
• /rspm debug bedrock [on|off] — Velocity 与 BungeeCord 通用。切换 GeyserBinder 输出的 [RSPM-BedrockDebug] 详细日志，用于排查“基岩版玩家加入但没看到资源包”的情况。代理重启时会重置为关闭。不带参数运行会打印当前状态。

在 Velocity 上，代理命令接受 resourcepackmanager.command.status 或 resourcepackmanager.*。BungeeCord 注册的是确切的 resourcepackmanager.command.status 节点；权限插件仍可能通过通配符展开来满足它。控制台可以运行这些命令。输出可以放心分享——网络密钥只以一段简短的单向哈希指纹出现，绝不会是密钥本身，也不会打印任何令牌——所以宽松授权没有问题。

目前支持哪些插件？

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

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

只有当对应插件已安装且其配置的本地路径或远程 URL 可用时，这些集成才会生效。

每个集成在 plugins/ResourcePackManager/compatible_plugins/ 下都有自己的 YAML 配置文件。你可以在其中按插件自定义 isEnabled、pluginName、localPath、url、zips、cluster、additionalLocalPath 和 reloadCommand。cluster 选项告诉 ResourcePackManager 将本地路径视为包含多个资源包子文件夹的目录，并把它们全部合并在一起。

如何排除某一个自动插件集成？

在 plugins/ResourcePackManager/compatible_plugins/ 下该集成的文件中设置 isEnabled: false，然后运行 /rspm reload（或重启）。RSPM 会移除它为该集成生成或注册的资源包输入，包括生成的 mixer 副本。把插件从 priorityOrder 中删掉并不能排除它，那只会把该资源包移到最低优先级。若要排除你手动添加的某个 ZIP，请把该 ZIP 从 mixer 文件夹中删除或移走。

ResourcePackManager 与 ItemsAdder 兼容吗？

兼容。ResourcePackManager 内置了针对 ItemsAdder 的助手与警告流程。

如果已安装 ItemsAdder 但尚未为 ResourcePackManager 托管做调整，OP 玩家在加入服务器几秒后会看到可点击的警告。已经永久关闭警告的玩家不会再看到。从警告处可以：

• 运行 /rspm itemsadder configure，将 resource-pack.hosting.no-host.enabled 设为 true，禁用全部三项 protect-file-from-unzip 设置，将 compress-json-files 设为 false，运行 /iareload 再运行 /iazip，然后重新加载 ResourcePackManager（约 15 秒后）
• 运行 /rspm itemsadder dismiss，根据玩家 UUID 永久关闭该警告

如果 ItemsAdder 已经通过其某种托管模式自托管资源包，助手命令不会自动覆盖该设置，而是提示你先手动禁用 ItemsAdder 的托管。

可以把我自己的资源包加入合并吗？

可以，而且根据你手上的东西，有两个可以放置的位置。

做好的 .zip 放到：

plugins/ResourcePackManager/mixer

如果要控制文件冲突时哪个资源包优先，将带 .zip 后缀的完整文件名加入 plugins/ResourcePackManager/config.yml 中的 priorityOrder。

未压缩的资源包文件夹（一棵 assets/ 目录树加上 pack.mcmeta）放到：

plugins/ResourcePackManager/resource_pack

RSPM 会自己把那个文件夹打包，并在 priorityOrder 中的 ResourcePackManager 条目下合并它，而该条目位于默认列表的最顶端——所以默认情况下它的文件会在与任何插件资源包的冲突中胜出。如果你希望它落败，请把 ResourcePackManager 在列表中往下移。

与之相关的 plugins/ResourcePackManager/blueprint 文件夹存放着 RSPM 贡献给每次合并的 pack.png 与 pack.mcmeta。编辑这两个文件即可更改合并后资源包的图标或其在菜单中的描述；该文件夹在每次启动时都会重新打包为 blueprint.zip。

示例：

priorityOrder:
  - ResourcePackManager
  - EliteMobs
  - MyCustomPack.zip

优先级是如何工作的？

priorityOrder 中越靠上优先级越高，越靠下越低。

对于不可合并的文件，高优先级资源包会替换低优先级文件。对于可合并的 JSON 文件，ResourcePackManager 会合并内容，而不是粗暴地替换。

目前代码视为可合并的类别有：

• sounds.json
• 位于 lang 或 languages 的语言文件
• 位于 minecraft/models/item 的原版物品模型 JSON（采用非递归合并：跨资源包只合并 overrides 数组，文件其余部分遵循最高优先级取胜）
• 图集（atlas）文件
• 字体（font）文件
• 位于 items/ 的 1.21.4+ 物品模型定义（格式感知合并：保留 predicate 树结构完整，不会盲目递归进入不同节点类型）

pack.mcmeta 的合并方式较为特殊：取最高的 pack_format，supported_formats 范围会被扩展以覆盖所有资源包（支持整数、双整数数组以及 {min_inclusive, max_inclusive} 对象三种形式），overlay 条目会被合并，非标准顶层键（例如 sodium）会被保留。Overlay 条目还会针对 1.21.9+ 兼容性进行规范化：缺失时会自动补齐 min_format/max_format 字段。

所有资源包合并完之后，ResourcePackManager 还会将基础 atlas 源合并进 overlay atlas 文件，避免 Minecraft 激活 overlay 时（例如 ItemsAdder 的 ia_overlay_modern_atlas / ia_overlay_legacy_atlas）意外屏蔽基础 atlas 条目。

其他 JSON 文件会被替换，而不是合并。

未列入 priorityOrder 的资源包仍然会参与合并，但会获得最低优先级。

字节完全相同的完整 ZIP 输入会在合并前被去重，只保留第一个（优先级最高的）副本。合并之后，RSPM 还会修复两类常见的 Java 模型缺陷：在可能的情况下，用模型中第一个具体贴图补上缺失的 particle 贴图；并把无效的模型 UV 坐标夹紧到 Minecraft 的 0..16 范围内。

资源包发生变化时，ResourcePackManager 会自动重建吗？

会。它会监视受支持的资源包来源。

当一个被监视的资源包在 3 秒内不再发生变化时，ResourcePackManager 会把它标记为稳定。所有被监视的资源包都稳定后，重新合并会立即开始。期间在线的 OP 玩家会收到通知：“All resource packs are stable. Mixing and sending now.”

如果一次重新合并的输入与上一次逐字节完全相同，则不会真的重新合并。RSPM 会为有序的源资源包列表（名称、大小、内容哈希）生成指纹，并把它作为 .rspm_mix_fingerprint 保存在输出文件旁边；当指纹匹配、且每一个预期的输出文件都仍然存在时，它会直接重新发布现有的 zip，而不是重新构建。任何存疑的情况——输出缺失、指纹无法读取、启用了基岩版转换但磁盘上没有基岩版资源包——都会退回到完整合并。这也是为什么一次没有任何变化的 /rspm reload 几乎瞬间就能完成，并复用已有的托管注册。

看门狗会考虑插件初始化吗？

会。看门狗能感知 Magmacore 插件的初始化状态。

• 它会等到所有被监视插件完成 Magmacore 初始化后再开始稳定性检测。
• 如果某个插件在看门狗运行期间重新加载，看门狗会检测到状态变化，暂停运行，重置所有稳定性追踪，并等待该插件完成重新初始化。
• 这避免了在正常的插件启动或重新加载过程中出现误判“不稳定”的情况。

玩家最终如何收到资源包？

当 autoHost 启用（默认）时，或当 selfHostForce 显式覆盖它时，RSPM 会选择一条分发路径，并把对应的 URL 推送给每个加入的 Java 玩家。决策树如下：

1. 如果 selfHostForce: true，永远走自托管（跳过所有探测——主要用于测试）。
2. 否则如果 preferSelfHost: true（默认），先尝试自托管，运行三项完整性检查（非 LAN 解析主机名、本地回环自探测、通过 magmaguy.com 的外部可达性探测），若全部通过则确认走自托管。
3. 如果自托管失败或已禁用，则把资源包上传到 magmaguy.com/rsp/ 并公告该 URL。

一旦拿到 URL，RSPM 会使用多资源包 API，因此可以与服务器发送的其他资源包共存。当前的 Bukkit 插件描述符要求 Minecraft 1.21.4 或更高版本。

加入时的资源包下发会延迟约一秒。收到 FAILED_DOWNLOAD 或 DISCARDED 响应时会自动重试，针对该玩家会话最多三次；玩家主动拒绝或 URL 无效则不会重试。这里会跳过 Floodgate 玩家，因为他们的基岩版资源包是通过 Geyser 分发的。

如果 autoHost: false 且 selfHostForce: false，RSPM 不会推送任何 URL —— 你需要自己从 plugins/ResourcePackManager/output/ 取出 zip 并通过自己的流程分发。

完整的分发决策树请参阅自托管。

我可以自托管，而不是使用内置的 auto-host 吗？

可以——而且从 RSPM v2 起，内置的 HTTP 服务器就是推荐的自托管路径。selfHostEnabled: true 与 preferSelfHost: true 默认都已开启。

如果你想通过自己已有的 Web 服务器（不是上面两种内置路径）托管 zip：

• 将 autoHost 设为 false。
• 可选地把 resourcePackRerouting 设置为一个相对于 plugins 目录的已存在文件夹路径。
• 自己从 plugins/ResourcePackManager/output/ResourcePackManager_RSP.zip 取出合并后的资源包并分发。

如果设置了 resourcePackRerouting，RSPM 会把该 zip 的一份副本写入重定向文件夹。重定向路径相对于 plugins 目录解析，且目标文件夹必须已存在。

有命令可以请求查看托管数据吗？

有。使用：

/rspm data_compliance_request

如果 magmaguy.com 的远程 auto-host 当前有活动会话，ResourcePackManager 会把响应下载到：

plugins/ResourcePackManager/data_compliance/data.zip

RSPM 还会在同一个 data_compliance 文件夹中写入 ReadMe.md。

如果没有活动的远程会话（例如你正在自托管），该命令会告诉你目前没有可请求的远程数据。

有哪些可用的配置项？

plugins/ResourcePackManager/config.yml 中可用的设置如下：

通用

• priorityOrder — 控制资源包文件冲突时谁优先的列表（最高优先级在最前）
• autoHost — ResourcePackManager 是否自动托管并发送合并后的资源包（布尔值，默认 true）
• forceResourcePack — 是否强制玩家接受资源包（布尔值，默认 false）
• resourcePackPrompt — 向玩家提示资源包时显示的提示语（默认 "Use recommended resource pack?"）
• resourcePackRerouting — 可选文件夹路径（相对于 plugins），用于额外写入合并后 zip 的副本
• verboseLogging — 打印资源包准备与托管握手的每一个步骤（布尔值，默认 false）。默认关闭，因此控制台只显示最终结果；在排查合并或托管问题时再打开。/rspm verbose on|off 会在运行时切换同一个键并保存。它与覆盖基岩版流水线的 bedrockConverterDebug 是相互独立的。
• nightbreak.autoDownloadPluginUpdates — RSPM 是否在启动时自动下载自身的插件更新（布尔值，默认 false；下载的更新仍需重启才能应用）。这是 nightbreak: 段下的嵌套键，而非顶层键——在 config.yml 中搜索单独的 autoDownloadPluginUpdates 行只会发现它缩进在 nightbreak: 之下。这与 /rspm setup GUI 中暴露的开关是同一个。

自托管

• selfHostEnabled — 是否允许使用内置 HTTP 服务器（布尔值，默认 true）
• selfHostPort — 自托管 HTTP 服务器的端口。-1（默认）会自动派生为 mcPort + networkHttpOffset-v2。设为任意正整数则强制使用显式端口。
• networkHttpOffset-v2 — 当 selfHostPort = -1 时，附加到 Minecraft 服务器端口上的回退偏移量。默认 1（例如 MC 25565 → HTTP 25566）。在网络上你不再需要让它与代理保持一致：后端会把它实际绑定的确切 HTTP 端口自动公告给代理，而代理只是在公告到达之前把自己的 network-http-offset-v2 当作一个猜测来用。
• selfHostExternalHost — 客户端用来访问你自托管服务器的公网主机名或 IP。留空（默认）= 通过 api.ipify.org / checkip.amazonaws.com 自动检测。
• selfHostForce — 跳过所有完整性检查以及远程上传，永远使用自托管（布尔值，默认 false，仅用于测试）。
• preferSelfHost — 先尝试带完整性检查的自托管，失败后再回退到远程上传（布尔值，默认 true）。

基岩版

• bedrockConversionEnabled — 是否将合并后的 Java 资源包转换为可供 GeyserMC 使用的基岩版资源包（默认 true）
• bedrockAutoDeployToGeyser — 是否将 Geyser 自定义映射文件复制到已检测到的 Geyser 目录（默认 true）
• bedrockGeyserFolder — 手动指定的 Geyser 目录路径；留空则自动检测
• bedrockConverterDebug — 基岩版流水线的逐物品 / 逐骨骼详细日志（默认 false）
• geyserExtensionAutoInstall — 安装并更新作为 Geyser 扩展的通用 ResourcePackManager.jar，让基岩版自定义实体能够渲染（默认 true）。把它设为 false 会停止后续的安装与更新暂存；它不会删除已经存在的扩展 jar——请在 Geyser 停止时手动删除。代理插件有同样的开关，但名字不同，叫 geyser-extension-auto-install。

另一个文件 plugins/ResourcePackManager/bedrock_display_offsets.yml 提供了十二个可由用户调节的旋钮，用于微调基岩版玩家看到的手持物品相对手部的位置（第一人称六个，第三人称六个）。详情请参阅基岩版转换。

无论是后端还是代理，都刻意不提供 network-key 配置项。手动粘贴密钥曾是配置错误的最大单一来源——一个拼写错误就会悄无声息地破坏 proxy↔backend 链接，而且任何地方都不会报错。

取而代之的是，网络密钥由代理持有并向外分发：

• 代理只解析一次自己的密钥：若存在已保存的 network-key 文件就读取它；否则在 plugins/floodgate/key.pem 存在时从中播种（这样已有的网络在升级后仍保持相同身份）；否则生成一个全新的。无论走哪条路，它都会把结果保存到代理插件自身数据文件夹中的 network-key，此后再也不看 key.pem。
• 每个后端会在第一次有玩家连接到它时，通过 rspm:network 插件通道收到那个密钥，然后把它持久化到自己的 data.yml。已经持有密钥的后端会忽略之后的授予——把某个后端重新指向另一个网络是运维人员的操作，不是一条消息能做到的事。
• 这一切不需要 Floodgate。基岩版玩家要连上代理才需要它，而一个纯 Java 的网络完全可以在没有它的情况下使用 RSPM 的代理功能。
• 独立（无代理）服务器会生成并保留自己的密钥，因为它本身就是一个只有一台服务器的网络。

两侧的 /rspm status 都只打印该密钥的一段简短单向哈希指纹，绝不会打印密钥本身。代理与后端的指纹一致就说明链接正常。

为什么控制台这么安静？它到底有没有在干活？

这是刻意设计的。准备一个资源包是一条很长的流水线 —— 暂存每个贡献插件的资源包、合并集群、等待它们不再变化、混合、为基岩版转换、把结果交给托管方。把这一切都叙述出来，每次启动大约会产生六十行控制台输出，并把唯一两件有人会看的事情埋没掉：玩家到底能不能拿到资源包，以及拿不到时该怎么办。

因此一次正常的启动只打印一行：

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

只要你看到这一行，就说明成功了。

RSPM 还刻意不会对它自己能修复的状况发出警告。如果一次自托管探测失败、RSPM 回退到远程托管，那就是一次成功 —— 控制台报告的是结果，而不是绕行的过程。为已经处理好的事情发出警告读起来就像出了故障，会让人去追一个根本不存在的问题。

要查看完整叙述，请运行 /rspm verbose on（或在 config.yml 中设置 verboseLogging: true），然后执行 /rspm reload。若专门针对基岩版转换器，请改用 bedrockConverterDebug: true。

其他插件能否通过代码注册自己的资源包？

可以。ResourcePackManager 提供了用于以编程方式注册资源包的 Java API。详情请参阅 API 页面。

基岩版转换是否只对 FreeMinecraftModels 有效？

不，已经不再是这样。当前的转换器可递归处理任何在 assets/<namespace>/items/**/*.json 下提供 1.21.4+ 物品定义的插件资源包。这包括 FreeMinecraftModels 的骨骼模型、EliteMobs 装备、Oraxen/Nexo 自定义物品、自定义盔甲套装，以及任何你自己按该格式组装的资源包。纯 2D 的自定义物品会作为基岩版扁平图标输出；3D 自定义物品则会输出基岩版几何体/可附着物，以及由软件渲染的背包图标。

每次基岩版资源包变更都需要重启服务器吗？

对现有自定义物品的贴图与模型调整，下一个加入的基岩版玩家就会看到——RSPM 通过 Geyser 的 API 按会话实时分发基岩版资源包。仅当自定义物品集合发生变化（新增或移除物品）时才需要重启，因为 Geyser 是在启动时注册自定义物品标识符的。

ResourcePackManager 支持 BungeeCord / Velocity 吗？

支持——这是一等公民拓扑结构。各处使用的都是同一个 ResourcePackManager.jar：把它放到每个后端上，再放一份到代理上。这一个 jar 同时打包了 Bukkit、Velocity 和 BungeeCord/Waterfall 的入口点，因此无论宿主是后端还是代理，它都能正确加载。不再有需要构建或解压的、按平台区分的代理 jar——而且如果你忘了往代理上放副本，位于代理之后的后端会替你在 plugins/ResourcePackManager/proxy-extension/ResourcePackManager.jar 暂存一份，并在控制台里说明。

以代理插件身份运行时，它会合并每个后端转换好的基岩版资源包，并通过代理上的 Geyser 分发给基岩版客户端。Java 资源包仍由每个后端直接负责分发——Java 客户端看到的是各自所在后端的资源包。

安装、排错和验证步骤请参阅代理网络。