Troubleshooting

常见问题与调试

先使用 F3+B

F3+B 会绘制 OBB 线框、局部 XYZ 轴和碰撞箱名称：

颜色	含义
白色	物理 b 且可检测 d
蓝色	物理 b，不带 d
黄色	传感器 s 且可检测 d
绿色	传感器 s，不带 d
红色	当前与实体 AABB 或另一个 OBB 重叠

在 config/cnpc_immersiveboss-client.toml 中设置 showObbNames = false 可隐藏名称，只保留线框和轴。

看不到 OBB

• 骨骼名必须符合 h[a][d][b|s]_名称，并以 b_ 或 s_ 结束前缀。
• 骨骼必须至少包含一个有效 cube。
• 确认 NPC 实际引用当前 .geo.json，名称空间与路径一致。
• 按 F3+T 重载资源，并让 NPC 重新进入渲染范围。

大型模型不能攻击或交互

• 给目标部位增加 d，例如将 hs_hand 改为 hds_hand。
• 玩家眼睛到 OBB 的距离不能超过当前实体触及距离。
• 确认视线前没有更近的方块。
• 多人环境确认所有玩家使用相同资源包和模组版本。

传感器不推开玩家

这是预期行为。s 只检测重叠；需要推挤改用 b。需要准星、攻击或交互时再增加 d。

collide(e) 没有触发

• 确认 OBB 体积真正重叠，不能只靠视觉判断。
• 确认 NPC 已被客户端渲染并同步动画 OBB。
• NPC 必须启用脚本且包含对应事件。
• noPhysics 实体和同一载具中的实体可能被过滤。

伤害窗口没有生效

• API 必须从服务端脚本上下文调用并返回 true。
• 确认名称存在，durationTicks > 0 且 damage > 0。
• 延迟期间窗口处于活动状态，但不会造成伤害。
• 检查无敌帧、取消的伤害事件和 maxTargets 是否已占满。
• 动画提前结束时检查脚本是否调用了取消方法。

TaCZ 子弹仍命中原版范围

• 确认服务端实际安装 TaCZ；兼容 mixin 只在检测到模组时启用。
• 当前代码按 1.1.8-hotfix API 开发，其他版本可能发生字节码漂移。
• 在日志中搜索 cnpc_immersiveboss、MixinTacz 和 mixin 注入警告。

收集诊断信息

复现后保留游戏版本、四个必要依赖的完整文件名、资源包、logs/latest.log 和 crash-reports/ 中的新报告。说明问题涉及近战、交互、哪类弹射物、哪个骨骼名，以及 F3+B 显示的颜色和位置。

上一页：脚本 API · 下一页：开发者指南