调试与回归测试

物理问题必须能被重放。只录一段“有时会抖”的视频，无法区分随机初态、调度重复、数值阈值和显示插值。建议使用三层方法：即时观测、确定性 snapshot、manifest 回归。

1. 即时观测

先选定唯一实例，再把它读入临时对象：

execute as @e[tag=demo_body,limit=1,sort=nearest] run function demo:body/_get
function vve:_print_coord
function vve:_print_velocity
function vve:_print_angular
function vve:_print_response

打印响应必须紧跟介质探测；下一次探测会覆盖共享信号。若需要长期比较，把关键值复制到自己的记分板或 storage，不要期待公共临时区保留。

安装 GELib 后可以使用：

• vve:cpoint/_render_debug：碰撞点；
• vve:object/_render_uvw*：局部坐标轴；
• vve:tensor/_render：惯性张量；
• vve:_detect_render：以 storage math:io render_command 绘制探测位置。

2. 用单步隔离阶段

当物体落地异常：

1. Pause；
2. 记录 p/v/ω/q；
3. Step 一次；
4. 对比 shift、impulse、couple、friction、grab-layer；
5. 再 Step，确认变化来自哪个阶段。

如果物理 scores 不再变化而画面仍抖，检查 display transformation、teleport_duration 与 interpolation_duration。如果 scores 本身来回变化，就不要先调渲染。

3. Datapack Sandbox 命令行闭环

构建 CLI 后：

java -jar cli/build/libs/datapack-sandbox-cli.jar version --docs
java -jar cli/build/libs/datapack-sandbox-cli.jar commands --version 26.2
java -jar cli/build/libs/datapack-sandbox-cli.jar check --strict path/to/test.dps.json

调试资源时先确认目录被加载：

java -jar cli/build/libs/datapack-sandbox-cli.jar resources --version 26.2 --pack path/to/pack

4. 最小回归 manifest

下面的形状固定初态、推进函数并断言状态性质。具体 assertion 字段以仓库 schema/manifest/dps-manifest.schema.json 为准：

{
  "$schema": "../../schema/manifest/dps-manifest.schema.json",
  "version": "26.2",
  "unsupported": "warn",
  "packs": ["math3", "math3-lalib", "vve3", "demo-pack"],
  "steps": [
    {
      "commands": [
        "function math:_init",
        "function math:_init_la",
        "function vve:_init",
        "function demo:test/setup"
      ]
    },
    {
      "repeat": 80,
      "commands": ["function demo:simulator/main"]
    }
  ],
  "assertions": [
    {
      "score": {
        "target": "#settled",
        "objective": "demo_test",
        "equals": 1
      }
    }
  ]
}

把复杂 selector/速度阈值判断写进 demo:test/assert_settled，最终只设置稳定的测试分数。这样 manifest 保持可读，业务判断也能在游戏内复用。

5. 推荐断言

状态安全

• 坐标在允许范围；
• 四元数与局部轴没有溢出/退化；
• 实例数量与 result tag 无泄漏；
• 销毁后关联 display/seat/marker 一并回收。

物理性质

• 无介质时轨迹与预期离散积分一致；
• 落地后位置处于容差区间；
• 反弹速度不超过入射速度与参数允许范围；
• 稳态后继续推进 N tick 不重新获得明显能量；
• 偏心冲量产生角速度，质心冲量不产生非预期旋转。

调度性质

• 20 个游戏 tick 对应预期子步数；
• rate=0 时物理不推进；
• 切换 inv_dt 只在周期边界生效；
• 同一对象不被两个模拟器重复执行。

6. 记录已知边界

测试失败并不总是引擎 bug。例如 block 之间相互穿过是因为它们不是实体介质；高速点跨过薄墙是离散探测的边界；缺少资源包导致 fallback 外观不影响物理。把这些边界写进测试名称和文档，避免团队反复“修复”预期行为。