故障排查

函数不存在

症状：Unknown function math:_init_la 或 vve_examples:dice_6/init。

检查：

1. ZIP/文件夹里 pack.mcmeta 是否位于根层，而不是多套一层目录；
2. 目标版本使用 data/<ns>/function 还是旧式 functions；
3. Math3 LALib 与 VVE 是否都启用；
4. 运行 resources --version <version> --pack <path> 查看实际注册资源；
5. 示例命名空间是否在你使用的发行包中被裁剪。

初始化命令失败或很慢

VVE 初始化会创建大量 scoreboard、数据模板和运算结构。首次浏览器实验需要下载/解压依赖，属于正常开销。若最终失败：

• 分别执行 Math3、LALib、VVE，找出第一处失败；
• 提高 Sandbox 命令预算，而不是反复点击 Run；
• 确认没有同时播放 tick；cell 执行与模拟应串行；
• 检查版本范围 1.21.5–26.2 与当前 profile。

物体不动

• 是否只创建实例，未调度 main_c/tick？
• 模拟器 global_rate 是否为 0？
• 对象 tag 是否与 tick selector 一致？
• 修改临时对象后是否 _store？
• 物理正确但没 _sync_motion？
• 对象是否已被业务 sleep 标签排除？

物体直线落下并穿地

• 调用了 _iter_motion，却没调用碰撞点探测/响应；
• 使用 _detect_box，它本来就不碰普通实心方块；
• 执行位置与 c_x/y/z 不一致；
• 速度太高，一步跨过碰撞表面；
• 碰撞点与视觉尺寸不一致；
• 方块被 #vve:pass 归类为可穿过。

物体互相穿过

block 和 box_object 不是实体介质，只会主动探测环境。需要双方可查询，选择 cublock/cubox 或显式添加实体介质职责，并确保探测入口会查询它们。

落地后抖动

按顺序排查：

1. 是否重复 tick；
2. shift_response 是否稳定后仍在来回修正；
3. grab-layer 接触数/速度阈值是否临界振荡；
4. _regular、摩擦、冲量顺序；
5. 外部 impulse receiver 是否每帧被重复读取；
6. 物理 scores 稳定后，再看 display 插值是否反复重启。

静体策略应要求连续多帧低速 + 稳定支撑，并有更宽的唤醒阈值。

显示实体在动，但方向/缩放错误

• 修改物理 a/scale 后没更新 _update_display；
• item model 自带 display transform；
• 左右旋转四元数顺序或 pivot 不一致；
• 根实体与几何中心存在 cube_shift_y；
• 资源包没加载，看到的是 fallback 物品；
• 自定义矩阵与分解 transformation 混用。

Playground 没画面

• 等待依赖全部装载并先 Run 初始化；
• 点击 Reset view 恢复自动取景；
• 确认对象在安全坐标内且场景中有 block/display；
• WebGL2/context lost 时看恢复提示，静态 Render 仍应工作；
• 禁用浏览器强制省电或检查硬件加速；
• 命令输出成功不代表资源模型存在，必要时导入匹配资源包/client JAR。

每 tick 提示 dropped tick

这表示执行上一批数据包命令超过实时预算，视窗为了响应性丢弃了过期追赶 tick。它不是物理函数返回值。减少活动对象/调试输出、避免重复模拟器、降低目标 tick 工作量；不要无限提高补算上限，否则只会把输入和画面延迟越积越长。

字体或原版视觉不一致

Sandbox 使用 clean-room 渲染器，不承诺完整客户端字体 provider、shader、light map 和后处理。导入匹配资源包可提供模型/纹理；严格的原版视觉验收仍在真实客户端完成。