资源包

Xerr 的图片、字体、坐标和 Screen 效果都依赖客户端资源包。

文件关系复制章节链接

命令复制章节链接

/xerr pack
/xerr pack send [玩家]

send 需要启用自托管且已有成功发布的包。玩家省略名字时发给自己；控制台必须指定在线玩家。允许重复发送同一份包，send-on-join: false 不影响手动发送。

生成目录：

plugins/Xerr/generated/resource_pack

压缩包位于 plugins/Xerr/generated/resource_pack.zip，自托管发布包缓存位于 plugins/Xerr/cache/hosted_packs。

同一时间只会生成一份。生成失败时继续提供上一份成功发布的自托管包。

什么时候需要打包复制章节链接

需要 /xerr pack：

• 图片、GIF、字体和 Hotbar 贴图变化。
• 新增或修改 Layout 坐标。
• Popup、Compass、Screen 的位置或动画范围变化。
• 文字背景和图片进度裁切变化。
• 原版 HUD 隐藏项、TAB 背景隐藏或资源包版本变化。
• 合并来源、覆盖文件或提取保护变化。

通常只需 /xerr reload：

• 普通文字、条件、变量和刷新时间变化。
• 自托管开关、地址和端口变化。

跨版本字段复制章节链接

默认生成一个覆盖 Minecraft 1.20.1～26.3 的 ZIP，通过 overlays 提供版本差异资源，无需按版本拆成多份包。

字段位于 plugins/Xerr/config.yml 的 feature.version 节点。只服务一种客户端版本时，可以使用单版本包，例如：

feature:
  version:
    cross-version: false
    version-id: 12104

12104 用于 1.21.4～1.21.5；其它值见版本对照表。支持范围与插件共用注意事项见支持版本与兼容性。

自托管字段复制章节链接

resource-pack:
  self-host:
    enabled: true
    bind-address: "0.0.0.0"
    port: 8163
    public-url: "http://play.example.com:8163"
    send-on-join: true
    force: false

enabled复制章节链接

开启 HTTP 服务。开启后 /xerr pack 成功会向在线玩家发送包，不需要额外的 send-on-pack 字段。

bind-address复制章节链接

服务端监听地址。0.0.0.0 表示监听全部网络接口，不等于玩家访问地址。

port复制章节链接

独立下载端口。范围由操作系统决定，端口必须未被占用，并在防火墙和面板中放行。

public-url复制章节链接

客户端访问的基础地址：

public-url: "http://play.example.com:8163"

留空时尝试探测公网 IP。内网、端口映射、域名和反向代理环境建议手动填写。

反向代理需要转发：

/xerr/packs/

send-on-join复制章节链接

开启后，玩家进服时发送当前资源包；服务器启动后也会准备一份可下载的包。

force复制章节链接

平台支持时使用强制资源包 API。它不能替客户端自动同意；旧平台不支持时会降级为普通请求。

客户端缓存复制章节链接

Xerr 会把 ZIP 的 SHA-1 一起发送给客户端。内容未变化时，客户端可以复用缓存；新包使用新的版本下载地址。

与其它资源包合并复制章节链接

在 plugins/Xerr/config.yml 的 resource-pack.merge 中填写外部资源包路径。目录和 ZIP 可以混用，路径相对于服务器的 plugins 目录：

resource-pack:
  merge:
    - "ModelEngine/resource pack"
    - "CustomNameplates/resourcepack.zip"
    - "BetterModel/build.zip"

例如 ModelEngine/resource pack 对应 plugins/ModelEngine/resource pack。填写资源包根目录，而不是整个插件目录；ZIP 解压后的第一层应直接包含 assets 或 pack.mcmeta，不要再套一层文件夹。

先让对应插件生成资源包，再执行 /xerr pack。Xerr 只读取来源，不会改写外部插件的文件。

合并结果复制章节链接

找不到的路径会警告并跳过，其它来源继续合并。读取失败、ZIP 损坏或资源冲突会使本次生成失败，上一份成功生成的 ZIP 和已发布资源包仍会保留。

同名资源与冲突复制章节链接

• 不同路径的文件直接合并；同路径且内容一致的文件只保留一份。
• 字体、图集、语言和音效 JSON 可在规则兼容且没有冲突时合并；不是所有 JSON 都能自动合并。
• 同路径但内容不同、又无法安全合并的文件会报错，不会按列表顺序静默覆盖。

需要指定最终文件时，放入 plugins/Xerr/core/pack-overrides/，保持资源包中的相对路径。例如：

plugins/Xerr/core/pack-overrides/assets/minecraft/shaders/core/rendertype_text.vsh

此处的文件作为最终版本使用。核心着色器需要先手动合并双方逻辑，再放入覆盖目录；直接放入其中一方的原文件，仍可能让另一方失效。

压缩与提取保护复制章节链接

在 config.yml 中分别控制压缩与提取保护，无需安装额外工具：

resource-pack:
  compression: true
  protection: false

• compression: true：默认值，优化图片、JSON 并压缩 ZIP，减小资源包体积。
• compression: false：跳过体积优化和 ZIP 压缩，直接生成无压缩 ZIP，适合频繁调试。
• protection: true：开启可选提取保护；与压缩开关独立。

修改后执行 /xerr reload、/xerr pack。两种压缩模式都生成 generated/resource_pack.zip，自托管直接分发同一份文件；切换模式会重新生成，不会复用另一种模式的缓存。

关闭压缩会增大包体，主要加快服务端生成，不保证网络下载或客户端重载更快。保护只增加常见工具直接解包的难度，不是加密，也不能保证内容无法提取；需要普通 ZIP 时保持 protection: false。

常见失败复制章节链接

• 合并来源不存在：检查相对于 plugins 的路径，并先让来源插件生成资源包；Xerr 会警告并跳过缺失路径。
• 资源冲突：按报错中的路径处理文件，将最终版本放入 core/pack-overrides；调整列表顺序不能解决冲突。
• 收不到请求：检查 enabled、打包是否成功以及客户端服务器资源包设置。
• 点击同意后下载失败：检查 public-url、端口映射、防火墙和反向代理。
• 下载快但加载慢：客户端正在解析字体、图片和 Shader；可减少大图、GIF 或改用单版本包。