常见问题

按制作顺序检查复制章节链接

先确认上一层存在，再排查下一层：

1. 字体: TTF 文件存在，ttf 与文件名对应，字体 ID 已登记。
2. 图片: PNG 存在，同组 config.yml 的 img 已登记。
3. Layout: 字体与图片地址引用正确，顶层 Layout ID 全局唯一。
4. 显示: HUD、Popup 或 Stack 引用的 Layout 真实存在。
5. 资源包: 生成成功，客户端加载的是新包。

还没有做过完整流程时，用入门路线逐步核对，不要同时重写所有配置。

看不到任何 HUD复制章节链接

依次检查：

1. Xerr 是否成功启用。
2. 客户端是否加载了最新资源包。
3. core/display/huds 中 HUD 的 enabled 是否为 true。
4. HUD 的 layouts 是否引用了真实 Layout ID。
5. Layout 或绑定条件是否返回 false。
6. 修改坐标后是否重新执行了 /xerr pack。

加载前看到 BossBar 或方块字符，不能证明 Layout 定位正确。加载后消失时，先检查客户端资源包和 Shader 日志，再检查对应显示绑定和坐标；不要仅凭这一现象判断是哪一个原因。

出现方块字符复制章节链接

方块字符表示客户端找不到对应字形。常见原因：

• 没有加载资源包。
• 客户端仍在使用旧包。
• 新增图片、字体或位置后只执行了 /xerr reload。
• 图片 ID、命名空间或 basename 写错。
• 打包过程失败。

重新执行 /xerr pack，确认成功后让客户端重新加载。

修改配置没有变化复制章节链接

先判断修改类型：

• 文字、变量、条件、刷新时间: /xerr reload。
• 图片、字体、坐标、动画位置、Layout 结构: /xerr pack。

Xerr 不会覆盖已经存在的默认配置。升级 JAR 后看不到新版默认主题时，说明服务器仍在使用旧文件。

删除 core 后没有默认 HUD复制章节链接

完整停止服务器后再移走 plugins/Xerr/core，然后正常启动。不要在服务器运行期间删除目录。

生成完成后检查控制台是否有 Unknown HUD layout、重复 ID 或配置解析错误。任何一个被引用的 Layout 缺失，都可能让显示配置加载失败。

自托管没有发送资源包复制章节链接

检查：

• resource-pack.self-host.enabled 是否为 true。
• 修改后是否执行 /xerr reload。
• 下载端口是否被占用。
• 防火墙和面板是否放行端口。
• public-url 是否是客户端能够访问的地址。
• /xerr pack 是否成功完成。

send-on-join 只控制进服发送；开启自托管后，成功执行 /xerr pack 本身就会向在线玩家发送。

点击同意后下载失败复制章节链接

通常是客户端无法访问公开地址：

• 不要把 localhost 或仅服务器可见的内网地址发给外部玩家。
• 使用端口映射时填写映射后的域名和端口。
• 使用 HTTPS 反向代理时转发 /xerr/packs/。
• 检查云服务器安全组和系统防火墙。

下载很快，但客户端加载很久复制章节链接

下载时间和加载时间是两件事。加载阶段会解析字体、图片和 Shader。可以尝试：

• 删除不再使用的大图片和 GIF。
• 减少 GIF 帧数与尺寸。
• 确认没有重复打入第三方资源。
• 只服务一个客户端版本时关闭跨版本资源包并选择对应 version-id。

图片和文字不在同一水平线复制章节链接

当前坐标系统会根据 TTF 指标自动换算文字基线。确认：

• 图片和文字使用相同的逻辑顶部 y。
• 没有保留旧配置中的手动 6px 补偿。
• 自定义 TTF 能被 Java 正常读取。
• 修改字体或字号后重新打包。

不同字体的可见轮廓仍可能需要少量视觉微调，但不应再依赖统一固定补偿。

Popup 列表为空复制章节链接

/xerr popup

这里列出的是可用 Popup 类型。/xerr popup list [玩家] 列出指定玩家尚未结束的实例；省略玩家时查询自己，未触发时为空是正常的。

Compass 没有目标复制章节链接

默认只显示方位条，不自动创建目标。先执行：

/xerr compass set navigation home world 0 64 0 home

同时确认 compass_example 已加入 HUD。目前修改类命令成功静默，不会因此提示缺少显示绑定。可用 list 查目标，再检查 Layout 与 HUD 是否绑定。

资源包与其它插件冲突复制章节链接

多个资源包同时覆盖相同 Minecraft Shader 或字体 JSON 时，后加载者会覆盖前者。与 BetterHud 等核心着色器插件共用时，可能需要手动合并核心着色器才能使用；Xerr 不自动完成这类合并。检查范围见支持版本与兼容性。

遇到客户端提示必需 Shader 加载失败时，先单独加载 Xerr 资源包验证，再逐个合并其它资源包定位冲突。先保存客户端加载日志；单独加载成功后再检查合并时被覆盖的路径。

配置错误导致重载失败复制章节链接

重点检查：

• YAML 缩进。
• 顶层 ID 是否重复。
• 引用的 Layout、图片、背景或模板是否存在。
• 枚举值是否拼写正确。
• 列表是否为空。

控制台异常中的第一个 Xerr 配置错误通常最接近根因，后面的显示异常可能只是连带结果。

多语言修改后没有更新复制章节链接

修改语言文件后执行 /xerr reload；检查控制台是否有 YAML、类型或重复节点错误，失败时仍保留上一份可用词典。确认节点使用原布局 ID，而不是文件名、信息栏行 ID 或临时显示 ID；value 和 list 要与原元素的文字类型对应。修改多行数量、字体或位置后重新 /xerr pack 并加载资源包。脚本返回值和外部传入变量不属于静态布局翻译范围。