排错与构建

盔甲架仍然显示

先用 /c version 确认实际加载的版本，排除 plugins 目录放了两个 JAR 或未重启。 2.0.2 起统一通过 Bukkit ArmorStand API 设置本体不可见，避免各 NMS 混淆方法名漂移。装备和头颅仍应显示。 重新召唤后仍异常，请记录完整服务端版本、Java 版本、随从标识、所用 JAR 和启动日志；构建通过不等于实际客户端渲染全部验证。

商店空白或显示变量原文

• 玩家需要 companions.player.shop 及 companions.buy.<标识>；已经拥有的随从会从商店隐藏。
• 2.0.3 起 %companion% 在商店描述中解析。确认修改的是 gui/companions.yml，并执行 /c reload。
• 名称字段和任意自定义字段不一定支持描述变量，优先对照默认文件。
• 材质或声音枚举必须适合当前服务端；使用不存在的材质可能回退为替代图标。

GUI 修改不生效

迁移后不再读取旧文件的 GUI 段。修改 gui/gui.yml 或 gui/companions.yml。 检查槽位是否在尺寸范围内，是否与导航按钮重叠。黑色玻璃只填空白格；它不是“菜单没有载入”的错误标记。

帮助重复、Tab 补全不出现

2.0.3 修复管理员帮助重复；2.0.4 添加补全。先确认版本，再查命令是否被别的插件占用及权限是否授予。 无权限、不匹配当前前缀、参数已填完时，返回空补全是预期行为。离线玩家不进入补全，但适用的命令可以手动输入其名字。

编辑器无法保存

冲突提示表示配置在打开草稿后变化，需放弃草稿重开；非法数字、材质、贴图或重名按提示调整。 聊天太长无法发送的贴图请直接写入文件。备份为一对 .bak，恢复方式见编辑器。

IDEA 中 Lombok 标红

项目使用 Gradle 导入，Gradle JVM 用 JDK 21，MC26 工具链准备 JDK 25。不要把所有模块统一改为 Java 8。 先重新加载所有 Gradle 项目，检查 Lombok 插件和注解处理；构建通过但标红时检查 IDEA 索引及模块模型。 之前日志出现过 ModuleComponentManager has already been disposed，可关闭重开项目并重载。仅凭标红不能认定源码编译失败。

从源码构建

.\gradlew.bat build

产物为 dist/build/libs/Companions-2.0.4.jar，包含全部实现和运行期库，不要使用 core 或单个 NMS 的 JAR。 仓库的 gradle.properties 包含本机 JDK 路径和代理设置，换电脑时先调整到实际环境；首次下载依赖需要可用的依赖仓库连接。 已完成全模块构建和 21 项测试。旧目标 Java 8、过时 Bukkit API 与 Gradle 弃用警告不等于编译失败；尚未完成全部服务端版本的游戏内验收。