猹件开发组

Appearance

On this page

常见问题与排错 ​

按下面顺序排查，不要一开始同时改服务端配置、客户端资源和版本。每一步先保留日志证据，再进入下一层。

尚未进服就黑屏 ​

请保留发生黑屏那次客户端的 logs/latest.log 和 logs/debug.log，服务端日志不能替代客户端启动日志。如果出现 chaengine:core/scene_studio 编译失败和 Failed to load required shader programs，请更新修复后的 ChaEngineMod，移除 mods 目录中的旧包后重新启动。此错误发生在客户端启动加载资源时，修改服务端模型配置无法解决。

更新后应能显示主菜单，日志中不再出现上述 Shader 编译错误；若仍黑屏，请提供本次启动的新日志和实际使用的客户端包名。

1. 服务端启动 ​

现象：ChaEngine 未启用，或主命令不存在。

检查顺序：

  1. 查看服务端启动日志中 ChaCore 是否先成功启用。
  2. 查找 ChaEngine 的异常堆栈和缺失依赖提示。
  3. 确认插件文件与当前服务端核心兼容，且没有同时放入重复版本。
  4. 修复启动错误后完整重启，不要先排查模型资源。

下一步：服务端安装。

2. 客户端连接与能力握手 ​

现象：服务端正常，但某玩家的全部模型、物品背景、粒子、按键和相机都无效。

检查顺序：

  1. 核对 Minecraft 版本与加载器是否属于六个支持组合。
  2. 查看客户端加载器列表和日志，确认 ChaEngineMod 已成功加载。
  3. 退出服务器再重新进入，排除首次登录同步时序。
  4. 对比其他已知正常客户端；若只有单人失败，优先检查该客户端安装和 Java 版本。

下一步：客户端安装与版本兼容。

3. 资源路径 ​

现象：配置已同步，但日志提示文件不存在或路径被拒绝。

检查顺序：

  1. 从当前游戏目录开始确认 resourcepacks/ChaEngine/，不要额外套一层目录。
  2. 模型配置中的路径都应相对于 model/；基岩版粒子索引相对于资源根。
  3. 使用 /，禁止盘符、根路径、空段、. 和 ..。
  4. 逐字符核对文件名、扩展名和大小写。

下一步：ChaEngine 资源目录。

4. 模型解析与渲染 ​

现象：只有某个模型不显示、贴图丢失或动画文件解析失败。

检查顺序：

  1. 用最小模型配置确认载体与 ID 有效。
  2. 查看客户端日志中的具体模型、动画或纹理路径。
  3. 核对 .geo.json、动画 JSON 和图片确为相应格式。
  4. OBJ 模型额外检查当前版本支持、MTL 引用和安全相对路径；.bbmodel 额外检查 UTF-8、outliner 引用、支持的数值轨道和 16 MiB 文件上限。
  5. 物品填写 item-texture 后会使用带厚度的平面贴图；要显示三维模型则删除该字段。

下一步：方块模型、物品模型、OBJ 模型或Blockbench .bbmodel 模型。

5. 物品自动匹配与背景 ​

现象：普通物品没有自动使用模型，物品槽背景不显示，或同时命中了错误配置。

检查顺序：

  1. 先用一条 name#contains#明显文字 规则确认客户端能读取物品名称。
  2. 使用 Lore 时核对纯文本内容、全角符号和大小写；同一行逗号条件是“且”，多行是“或”。
  3. 检查所有可能命中的物品模型或背景配置，把更具体规则的 priority 调高。
  4. 物品背景额外检查 PNG 是否位于 resourcepacks/ChaEngine/model/ 下，路径是否相对于 model/。
  5. 物品已有 ChaEngine 模型 ID 时会优先按 ID 渲染，不再用 match 选择另一个物品模型。

下一步：物品模型与物品背景。

6. 实体匹配与真实碰撞 ​

现象：文件能加载，但目标实体没有自动使用模型。

检查顺序：

  1. 暂时只保留一条名称完全匹配规则，确认实际纯文本名称。
  2. 再加入类型、UUID 或顶层 NBT 条件；一行内条件是“且”，多行是“或”。
  3. 检查实体是否已有临时或永久强制模型；强制模型优先于匹配规则。
  4. 强制 ID 不存在时先清除它，不会自动回退到匹配规则。
  5. 模型命中但攻击范围不对时检查 collision 和服务端真实碰撞适配警告；水平宽度取 X、Z 较大值，高度取 Y。

下一步：实体模型。

现象：实体自定义描边命令被拒绝，或命令成功后看不到颜色。

检查顺序：

  1. 颜色必须带 # 且恰好是六位十六进制字符，例如 #33CCFF；三位缩写、八位透明色和颜色名称都会被拒绝。
  2. 目标必须是生物实体；掉落物、弹射物等非生物目标会被拒绝。玩家执行命令时可先用 @aim 或 @nearest 排除数字 ID 变化问题。
  3. 检查客户端是否允许显示原版实体轮廓；ChaEngine 不会绕过这一显示条件。
  4. 确认实体仍然可见并处于客户端渲染距离内，没有被原版剔除。
  5. 确认服务端 ChaEngine 与客户端 ChaEngineMod 都使用包含该能力的 1.5.4 构建，并让玩家重新连接完成状态同步。
  6. 实体卸载、切换维度、插件重载或服务器重启后状态会按设计清除，需要重新设置。

清除自定义颜色后，实体会恢复原版发光与队伍颜色规则；这不代表描边渲染失效。

7. 动画 ​

现象：模型显示正常，但动画不播放、无法恢复或名称无效。

检查顺序：

  1. 在动画文件中确认完整动画 ID。
  2. 区分客户端自动状态动画与服务端特殊动画。
  3. 停止实体特殊动画后会恢复自动选择；停止方块特殊动画后进入明确的无特殊动画状态。
  4. API 调用检查 INVALID_ANIMATION、INVALID_ENTITY、INVALID_LOCATION 等返回值；命令调用查看发送者收到的失败提示。
  5. 需要叠加受击或技能动作时使用覆盖动画 API；普通特殊动画会替换基础自动状态。

下一步：模型动画。

8. 相机 ​

现象：相机预设或场景镜头无效、镜头无法恢复、输入一直被锁定。

检查顺序：

  1. 先查看相机状态，确认该在线客户端已经声明支持；仅安装 Mod 不等于本次连接已经准备完成。
  2. 预设检查 camera/presets/，场景检查 camera/scenes/；调用 ID 不带扩展名并包含必要的子目录。
  3. 查看服务端重载日志。任意相机文件非法时会保留上一份有效快照，不会部分应用。
  4. 镜头穿墙时使用 collision: clamp；玩家朝向被鼠标带动时检查 look-mode；移动方向异常时检查 movement-reference。
  5. 场景结束后应恢复下层会话；需要立即清空全部控制时执行相机重置。
  6. 断线、切换世界或实体锚点消失后仍锁定时，保留客户端和服务端日志并按连接问题提交，不要删除玩家配置绕过恢复错误。
  7. 黑边不显示时检查 cinematic 是否恰好包含四个 0～0.5 数值；场景后三帧可省略并继承，但第一帧省略会从零开始。
  8. 新 transitions 或 interrupt 被拒绝时，通常是客户端包未声明对应能力。服务端不会把打断悄悄降级为 stop，请先更新双方发布包并重新连接。

启动时直接崩溃：日志出现 Some clientbound payloads are missing client-side handlers: [chaengine:camera_control]。

这表示当前客户端包没有为相机能力完成加载。该问题曾影响 NeoForge 1.21.8 与 1.21.11 的早期发布包；它不是相机预设或场景配置错误。

  1. 删除 mods 目录中重复或旧的 ChaEngineMod，只保留一个文件。
  2. 重新下载最新发布包，并确认 Minecraft 版本、NeoForge 加载器与文件标注的游戏版本匹配。
  3. 完整退出并重启客户端；只从标题界面重新进服不能替换已经加载的 Mod。
  4. 如果更新后仍出现同一行错误，提交完整客户端崩溃报告和 FML 日志，不要通过删除相机配置来绕过启动检查。

下一步：相机系统、相机预设与场景镜头。

9. 粒子 ​

现象：粒子整组不显示、只有某行无效或客户端掉帧。

检查顺序：

  1. 确认接收玩家在线并安装客户端 Mod。
  2. 核对世界、锚点、96 格渲染距离和 TTL。
  3. 粒子程序逐行检查形状与原版粒子 ID；基岩版粒子检查索引、效果 JSON 和贴图。
  4. 避免在不同范围复用同一个组 ID 或实例 ID。
  5. 掉帧时先降低生成数量并提高执行间隔。

下一步：粒子程序或基岩版粒子。

10. 按键 ​

现象：控制设置中没有按键，或按下后服务端无事件。

检查顺序：

  1. 确认客户端已进入服务器并收到本次连接的按键快照。
  2. 核对默认键是否只有一个主键，修饰键拼写是否受支持。
  3. 检查逻辑 ID 与玩家最终改键是否冲突。
  4. 查看服务端是否收到未知 ID，或动作是否因过长、为空而被跳过。

下一步：客户端按键。

11. ChaAssets 授权与完整性 ​

现象：直接文件能用，但启用加密包后资源拒绝或损坏。

检查顺序：

  1. 确认客户端安装 ChaAssetsMod，服务端安装 ChaAssets。
  2. 确认 .chaassets 位于客户端当前游戏目录的 resourcepacks/ChaEngine/。
  3. 核对包声明的虚拟根、服务器身份、授权版本和资源相对路径。
  4. 区分未声明或资源底座不可用，与已声明但拒绝、包损坏；后两者必须失败关闭，不能用同路径明文掩盖问题。
  5. 更新或撤销授权后重新连接，确认旧的模型、动画和纹理缓存已清理。

下一步：ChaAssets 资源加密。

Unsupported API version 1.20 ​

现象：1.16.5 服务端启动时提示 Unsupported API version 1.20，ChaAssets 未启用。

这是旧版 ChaAssets Jar 的插件声明与 1.16.5 不兼容，不是资源授权或客户端模型问题。按以下顺序处理：

  1. 关闭服务端，删除 plugins/ 中重复或旧的 ChaAssets Jar。
  2. 放入新的 ChaAssets-1.0.1-ob.jar（或对应构建产物）。
  3. 完整退出并重启服务端；仅执行 /reload 不会替换已经加载的插件。
  4. 不要手工编辑 Jar 内的 plugin.yml 或其他 YAML，避免破坏签名和后续升级。
  5. 确认日志不再出现该错误后，再使用匹配 Forge 的 1.16.5 ChaAssetsMod 进服验证加密资源。

附加日志中可能同时出现旧客户端的 pack.mcmeta warning；那是客户端资源包提示，与服务端 Unsupported API version 1.20 属于两类独立问题，应分别处理。

打开时装工坊创造背包页面时崩溃 ​

如果 Forge 1.16.5 在创造背包显示 Armourer's Workshop（时装工坊）模特物品时崩溃，并且日志包含 ConcurrentHashMap.get、resolveEntityGlow 和 armourers_workshop:mannequin，这是旧客户端对预览模特的自定义发光查询兼容问题，与模型文件、贴图路径或服务器连接无关。

更新到包含此修复的 ChaEngineMod 客户端包，完整退出并重启游戏，再打开原来触发崩溃的页面。修复后，预览模特不应用未设置的猹引擎自定义发光，仍由时装工坊正常渲染；真实实体已设置的自定义发光不受影响。无需删除模特资源或修改服务端模型配置。

若更新后仍然崩溃，请保留新的完整客户端日志，确认是否仍为上述调用栈，不要仅根据启动器列出的疑似冲突 Mod 判断原因。

提交问题时保留什么 ​

  • 服务端从 ChaCore、ChaEngine 启用开始的完整日志；
  • 客户端加载器、Minecraft、Java 与 ChaEngineMod 版本；
  • 失败配置及其引用的相对路径；
  • 最小可复现模型或粒子资源；
  • 是所有玩家失败、单版本失败，还是单个资源失败。
  • 相机问题额外保留预设或场景 ID、返回状态与会话 UUID；

不要公开 .chaassets 密钥、授权凭据或完整私有资源包。