猹件开发组

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. 修复启动错误后完整重启，不要先排查模型资源。

下一步：服务端安装。

现象：停服或禁用 ChaEngine 时出现 Plugin must be enabled to send messages。

这是插件停用时仍尝试向在线玩家发送清理消息导致的错误，可能使后续清理中断。请更新包含此修复的 ChaEngine 服务端包，移除旧包后完整重启服务端；无需修改模型、贴图或相机配置。

修复后，插件停用时会完成本地会话与任务清理，不再尝试发送已被服务端禁止的消息。正常停服断开连接后，客户端会恢复相机与输入；如果只禁用插件而玩家仍在线，相机控制会在已有会话超时后恢复。需要立即恢复时，应在禁用前通过相机重置命令清空控制。

现象：执行 /chaengine reload 出现 This registration already exists，错误堆栈经过动作模块。

旧版服务端包曾在重载配置时重复初始化动作服务。更新后的服务端在启动时初始化一次，后续重载只更新配置和动作数据。请按以下步骤处理：

  1. 保留报错实例的完整 logs/latest.log，确认实际服务器目录和正在加载的 ChaEngine 文件；不要只检查另一个测试服。
  2. 备份后替换包含此修复的服务端包，客户端使用同批次发布中对应 Minecraft 版本的包。相同的 1.5.5 版本号不能证明两个文件来自同一次构建，需要按发布记录核对文件大小和 SHA-256。
  3. 完整停止并重新启动服务器；客户端如有更新也要完整退出再启动。/chaengine reload 只重载配置，不能使新 Jar 代码生效。
  4. 启动后连续执行两次 /chaengine reload，预期都成功且不再出现上述异常，再进服确认模型和动作同步。

无需删除已有模型或动作工程。如果更新后仍然报错，请提供重启后的完整日志、实际 Jar 路径和摘要。命令说明见重载配置。

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 模型。

大型模型转动视角时整组消失 ​

如果云团、法阵等 Geo 模型仍有部分在画面内，却随着视角变化整组消失，请更新包含可见性修复的客户端包，并完全重启客户端。自定义实体模型，以及生物实体手持或头戴的自定义物品模型，不再因为载体的小包围盒离开视野而被整组裁掉。

这项处理保留原版渲染距离和正常深度遮挡，不改变模型的 UV、骨骼或动画，也不改变真实碰撞。不要为解决显示问题而增大 collision：它会影响实际碰撞与命中。六个受支持客户端均使用相同的可见性规则，Forge 1.16.5 仍受其原有世界实体模型支持范围限制。

该处理会增加视野外自定义模型的绘制开销，技能效果结束后仍应及时移除载体。若视角固定时依然周期性消失，请继续核对云团动画中的缩放、显隐和服务端技能生命周期；该修复不能替代这些检查。更新后用同一技能分别从上方、下方和侧面观察，确认云团可见部分持续显示。

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.5 构建，并让玩家重新连接完成状态同步。
  6. 实体卸载、切换维度、插件重载或服务器重启后状态会按设计清除，需要重新设置。

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

7. 动画 ​

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

检查顺序：

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

下一步：模型动画。

7.1 Geo 动画与 Blockbench 不一致 ​

现象：云层等特效在 Blockbench 中持续旋转、换帧，在游戏中却停住、跳回初始姿态，或多个模型的动画互相影响。

  1. 确认使用相同的 .geo.json、贴图和独立 .animation.json，并对照同一个动画名称；自动状态切换可能选择另一段动画。
  2. 请更新所用版本的客户端构建；如果使用 NeoForge 1.21.8，还需包含表达式动画时间重置修复，然后完全退出、重启游戏。早期构建存在多个模型共用播放状态的问题，仅重新进服或重载配置不能更新已经加载的模组。
  3. 原动画使用时间旋转和条件换帧时，可以保留原始公式；此问题不需要通过修改骨骼或补数值关键帧来规避。
  4. 同时显示云层、时装和武器，再切换其中一个模型的动画。预期各模型独立播放，其他模型不会因此停住或重播；隐藏时装不应改变云层的播放进度。
  5. 更新后仍有差异时，保留原模型、动画、贴图和对比录像，并注明客户端版本、实际播放的动画名称，以及单个模型和多个模型是否都出现问题。

云层能转，武器贴图或光效却停在首帧：NeoForge 1.21.8 和 1.21.11 的部分构建存在条件换帧异常。请更新包含三元表达式换帧修复的客户端并完全退出、重启游戏，保留原始公式、模型和贴图。先单独召唤武器，再与云层同时召唤；预期两种情况下武器贴图都按原动画换帧。武器落地后的本体姿态可能原本就是固定的，应对比颜色和光效变化，不必为此添加旋转或强行开启循环。修复贴图动画不等于增加方块照明或轮廓发光。

如果已更新且完整重启，帧率正常但贴图仍不动，请核对交付包的文件大小或 SHA-256，并保留客户端启动日志和技能出现时的日志。早期修复包存在修复未生效的情况，仅凭版本号或帧率恢复不能确认这一项已修好；这种情况无需先修改原模型。

动画恢复后出现严重掉帧：部分动画隔离构建会在绘制三维物品或反复生成特效时积累播放状态。更新包含性能修复的对应客户端并完全重启游戏，再比较相同场景、相同模型数量下的帧率。分别记录“刚显示模型就掉帧”与“反复释放技能后逐渐变卡”，并观察特效结束后的帧率；这两类现象需要区分排查。模型消失后旧播放状态不应持续累积，其他模型的动画也不应因清理而重播。尚未取得原场景性能数据时，不能仅凭构建通过认定帧率问题已经解决。

单人正常，进服后立即掉帧：如果尚未释放技能就明显掉帧，应先排查客户端接收模型配置后的基础开销。部分构建会重复检查附近实体是否需要显示自定义模型，即使这些实体没有匹配到模型也会增加耗时。更新包含进服帧率修复的对应客户端并完全重启游戏；无需修改模型、动画文件或服务端配置，也不需要通过降低动画流畅度处理。

对比时保持同一服务器、坐标、朝向、图像设置和帧率上限，分别记录“进服但未释放技能”“技能显示中”“技能结束后”的 FPS 与粒子数量。基础帧率下降和技能自身的额外开销需要分别比较；反馈时同时提供实际客户端包的文件大小或摘要，避免将同版本号的不同构建混在一起。

独立 Geo 动画与 .bbmodel 内嵌动画、动作工作室导入的支持范围不同，详见 Geo 表达式动画。

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 密钥、授权凭据或完整私有资源包。