Files
VibemakerSandbox/docs/robots/package-authoring.md
T
chenlin fc5ee4f2c6 feat: release v0.2 multi-robot simulator
Add declarative robot packages, shared simulation lifecycle and Microban ONNX/PD walking with independent head control.

Unify comic UI and chase camera; default robot packages to a 4.5m arena with real collision walls. Include regression tests, asset provenance/licenses and verification evidence.
2026-10-28 14:00:26 +08:00

5.0 KiB
Raw Blame History

首期 Robot Package 接入指南

已实现能力

Robot 是数据包,平台核心不根据 robot id 分支。对于现有能力可表达的机器人,新增 Package 与索引条目即可。

首期通用 runtime 支持:

  • floating base、具名 freejoint / root body;受控关节为标量 hinge / slide。
  • 每个受控关节一个 unit-gear actuator,独立解析 joint / qpos / dof / actuator 地址,不依赖其数组顺序。
  • ONNX primary;不相交关节组的正弦 overlay。
  • gyro、body projected gravity、joint position relative、joint velocity、lastAction、command。
  • 关节位置目标;unit-gain torque motor 的子步 PD,或原生 position servo。
  • MJCF 编译后 visual geom / mesh / material 渲染;默认 arena 为 4.5 × 4.5 m 有碰撞围墙的平地,使用 Microduck 暗色/橙色地面和墙网格;同款 comic UI 与背后相机,C 恢复。
  • presentation.world 可省略,统一由平台 DEFAULT_WORLD 解析,不要在每个新包里复制默认场地名。需要诊断时,通用包可显式设为 "flat"(无墙)。机器人出生点和尺寸应适合默认边界。
  • Package 绑定驱动的键盘输入与同源提示 / 技能按钮。

固定基座、ball joint 的多维 action、非单位 gear、自定义外部 JS、RNN、历史 / 图像张量、IK、velocity / effort action 等尚不支持。JSON Schema 与运行时都会拒绝不支持的能力,不能仅添加未实现的配置名来声称已经兼容。

文件布局

app/public/robots/example/
  robot.json
  model.xml
  assets/...
  policies/walk.onnx
  SOURCE.md
  LICENSES/...

从 microban/robot.json 复制结构,再按自己的模型 / 策略核对全部字段,不能只替换 id。模型应是 Robot 本体,不要重复内置 World 的地面。资源清单枚举所有 mesh / texture / include 依赖,path 是 Package 相对 URL,vfs 是 MJCF 编译时相对路径;例如 compiler meshdir="assets" 对应 VFS assets/part.stl。

规范结构见:

  • app/src/platform/loader/robot.schema.json
  • app/src/platform/loader/world.schema.json
  • SchemaValidator.js 的跨字段检查(所有权、输入绑定、命令尺寸等)。

必须逐项核对

  1. joint group:joints.groups.policy 是 actor 的真实顺序,不是 MJCF 或 metadata 全体顺序;overlay 另列 group。
  2. defaults / initial:metadata 参考姿态用于 relative observation 和 action offset;base.initial 是出生 / reset 姿态,两者不必相同。
  3. sensor frame:声明实际 gyro sensor 和 gravity body;不要把 sensor frame 与 root body frame 默认当成同一个坐标系。
  4. obs / action:尺寸由 terms 汇总,并与真实 session 的 dtype、shape、input / output 对比;NaN 与非法 target 不允许部分写入 ctrl。
  5. actuator:不能把关节角写进 torque motor。PD 增益 / 力矩上限由配置显式指定,不能自动等价于任意训练 metadata。
  6. 资源路径:以 manifest 为基准解析;不得依赖源项目绝对路径。内置 asset URL 必须同源,保留 Vite base 与已有同源签名参数。
  7. 终止:配置合理的倾角 / 高度;没有恢复策略时使用手动 reset,不用自动重置掩盖跌倒。
  8. 输入:语义动作支持 move_forward / move_backward / turn_left / turn_right、reset、pause、toggle:<overlay>;提示由绑定生成。
  9. 许可:填写 license,保存来源、修改与逐文件声明。复制权限不等于所有文件许可一致。

注册与测试

在 app/public/robots/index.json 增加条目:

{"id":"example","family":"example","name":"Example","manifest":"example/robot.json"}

adapter: "generic" 使用通用管线。不要在 RuntimeManager / SimCore / RigRenderer 中加入 if (robotId === ...)。Microduck 使用单独的可信内置 adapter,承载其既有状态机和 GLB / 玩法,不是新机器人应复制的一套独立引擎。

npm --prefix app run validate:packages
npm --prefix app test
npm --prefix app run test:e2e

除了 schema / 文件存在和 ONNX 冒烟,还要提供真实 WASM 的站立 / 运动序列、位移方向、跌倒 / 重置计数、控制周期及切换 / 清理证据。静态模型显示成功不等于策略兼容。

npm run baseline:record 只生成候选基线,不能用新快照掩盖已有机器人回归。

扩充能力

确需新能力时,在独立阶段明确数值约定、schema、注册项、单元与浏览器测试。观测 / 动作注册表在 platform/policy/TermRegistry.js;可信特殊生命周期放在 src/robots/ 的编译期注册工厂。首期没有 Worker 沙箱或任意 Package URL 的 JS 执行入口。

World 与 Robot 配置解耦:现有三个包与不指定 world 的新通用包均默认 arena。Microduck 专用适配器保留其球/可选起伏等特性,通用机器人只共享平地、边界和场地视觉;这不等于任意新机器人都已获得策略兼容或所有 Microduck 玩法。