Resource Pack Manager 常见问题

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

ResourcePackManager 目前提供哪些命令？

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

• /rspm setup — 打开一个游戏内 GUI 设置菜单（插件更新状态、推荐插件、自动更新开关、指向 wiki / Discord / Nightbreak 账户的链接）
• /rspm recommendedplugins — 显示共享的 Nightbreak 推荐插件菜单（在控制台中则显示文本列表）
• /rspm downloadpluginupdate — 下载可用的 ResourcePackManager 更新，供下次重启时应用
• /rspm downloadall — 下载本插件暴露的所有可用更新（目前即 ResourcePackManager 更新）
• /rspm applypluginupdate — 属于共享的 Nightbreak 命令集；RSPM 始终拒绝执行它，因为其更新需要重启服务器（它的 Geyser 扩展只在 Geyser 启动时加载）
• /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 命令。

MagmaCore 还会注册以下顶级命令，它们不是 /rspm 的子命令：

• /nightbreaklogin <token> 和 /nightbreaklogout 用于保存或清除服务器共享的 Nightbreak 账户令牌。两者都需要 nightbreak.login（默认 op）。参见 Nightbreak 账户关联。
• /nightbreak plugins 用于浏览 Nightbreak 插件目录，需要 nightbreak.plugins（默认 op）。
• /logify 将当前服务器日志上传到 mclo.gs，需要 logify.*（默认 op）。
• /resourcepackmanagerchangelog [dismiss|disable] 向管理员显示其尚未阅读的 ResourcePackManager 版本说明。参见更新日志通知。

最先加载的 Nightbreak 插件会为整个服务器注册 /nightbreaklogin、/nightbreaklogout、/nightbreak 和 /logify。

后端权限：

• /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.*。

在代理插件（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，然后等待 RSPM 合并重新生成的导出（合并成功或失败时它会报告；它不会重载 RSPM）
• 运行 /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，并合并已声明的格式范围。目录不同的 overlay 条目会合并保留；目录相同时，采用优先级较高的条目。每个 overlay 都保留作者指定的 formats、min_format、max_format 和额外元数据。唯一的补充是：如果 overlay 列表中有某个 overlay 覆盖到资源包格式 64 或更低、而另一个没有声明 formats，Minecraft 1.21.9+ 会拒绝该列表，因此当合并后的列表包含这样的 overlay 时，RSPM 会为每个只声明了 min_format/max_format 的条目补上等效的 formats 范围。除此之外，RSPM 不会改写 overlay 范围。pack、overlays 和顶层对象的额外字段，只要不与更高优先级的值冲突，也会保留。

所有资源包合并完之后，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，而不是重新构建。任何存疑的情况——输出缺失、指纹无法读取、合并后 ZIP 的 SHA-1 不再匹配——都会退回到完整合并。这也是为什么一次没有任何变化的 /rspm reload 几乎瞬间就能完成，并复用已有的托管注册。

当 Java 输入没有变化、但基岩版部分必须重做时（启用了基岩版转换但磁盘上没有基岩版资源包、bedrockConversionEnabled 或基岩版目标发生变化，或者转换器更新改变了基岩版输出），RSPM 会保留经过验证的 Java ZIP，只重做基岩版步骤，因此 Java 资源包的字节和 SHA-1 保持不变。

启动时，RSPM 会在被监控的插件完成初始化之前检查保存的指纹和合并后 ZIP 的 SHA-1。如果两者匹配，Java 托管会直接从保存的资源包开始。之后若有源资源包发生变化，监视器仍会重新合并。

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

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

• 它会等到所有被监视插件完成 Magmacore 初始化后再开始稳定性检测。
• 如果某个插件在看门狗运行期间进入 INITIALIZING 状态，看门狗会暂停并重置稳定性追踪，直到初始化完成。失败或未初始化的可选集成不会无限期阻塞整个合并器。
• 这避免了在正常的插件启动或重新加载过程中出现误判“不稳定”的情况。

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

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

1. 当 selfHostForce: true 时，跳过探测并尝试自托管，主要用于测试。URL 验证和监听器启动仍须成功。
2. 否则，当 preferSelfHost: true（默认）且 selfHostEnabled: true 时，检查主机地址，比较从 localhost 和玩家确切 URL 下载的资源包样本，并要求经 magmaguy.com 确认外部可达。只有全部通过才选择自托管。
3. 自托管失败或禁用时，复用或上传资源包到 magmaguy.com/rsp/ 并公告 URL。远程失败可以回退到已启用的自托管，但必须通过同样的检查。外部探测不可用会拒绝自动自托管；两条路径均失败时，不公告新的分发 URL。

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

加入时的资源包下发会延迟约一秒。收到 FAILED_DOWNLOAD 或 DISCARDED 响应时会自动重试，针对该玩家会话最多三次；玩家主动拒绝、URL 无效或 FAILED_RELOAD（客户端自身的资源重载失败；请检查该客户端的 latest.log）则不会重试。这里会跳过 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 中暴露的开关是同一个。自动下载插件需要有效的 Nightbreak 账户令牌以及有效的支持者 Patreon 会员资格。RSPM 不会写入共享的 nightbreak.applyPluginUpdatesWithoutRestart 键，也从不在不重启的情况下应用已下载的更新，因为它的 Geyser 扩展只在 Geyser 启动时加载。

自托管

• selfHostEnabled — 是否允许使用内置 HTTP 服务器（布尔值，默认 true）
• selfHostPort — 自托管 HTTP 端口。-1（默认）使用 mcPort + networkHttpOffset-v2 计算。显式端口和计算结果都须在 1 至 65535 之间。
• networkHttpOffset-v2 — 当 selfHostPort = -1 时，附加到 Minecraft 服务器端口上的回退偏移量。默认 1（例如 MC 25565 → HTTP 25566）。在网络上你不再需要让它与代理保持一致：后端会把它实际绑定的确切 HTTP 端口自动公告给代理，而代理只是在公告到达之前把自己的 network-http-offset-v2 当作一个猜测来用。
• selfHostExternalHost — 客户端访问自托管服务器使用的公网主机名或 IP。默认留空，自动检测主机地址。
• selfHostExternalUrl — 用于反向代理的完整公开 HTTP/HTTPS 资源包 URL，包含路径，默认留空。它覆盖对外公布的 URL，不改变本地监听器；含嵌入式凭据或片段的 URL 会被拒绝。
• 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。该文件已不再读取：基岩版手持物品姿势现在取自 Java 模型的 display 变换。参见手持物品姿势。

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

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

• 代理首先读取已保存且有效的 network-key，然后尝试从 plugins/floodgate/key.pem 派生密钥；两者都不可用时才生成随机密钥。结果会保存在数据文件夹中。后续启动会在密钥有效期间复用它；丢失密钥会重复此流程，可能重新得到相同的 Floodgate 派生密钥。参见网络密钥恢复。
• 每个后端会在第一次有玩家连接到它时，通过 rspm:network 插件通道收到那个密钥，然后把它持久化到自己的 data.yml。已经持有密钥的后端会忽略之后的授予——把某个后端重新指向另一个网络是运维人员的操作，不是一条消息能做到的事。
• RSPM 的网络连接不需要 Floodgate。基岩版认证取决于 Geyser 所选的认证模式，详见 Floodgate 与在线认证。
• 独立（无代理）服务器会生成并保留自己的密钥，因为它本身就是一个只有一台服务器的网络。

两侧的 /rspm status 都只显示密钥的简短单向哈希指纹，不显示密钥本身。指纹一致表示网络身份相同；仍需单独检查拉取结果，验证连接和资源包分发。

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

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

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

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

这一行确认分发 URL 已公布。请使用客户端加入，并查看已知的自定义内容，以验证下载和渲染。

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。它包含 Bukkit、Velocity 和 BungeeCord 的入口点。代理后的后端在尚未收到网络密钥时，会在 plugins/ResourcePackManager/proxy-extension/ResourcePackManager.jar 准备一份副本。其他已注册服务器可以不运行 RSPM；后端发现可避免它们拖延资源包同步。

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

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