8.5 KiB
首期 Robot Package 接入指南
已实现能力
Robot 是数据包,平台核心不根据 robot id 分支。对于现有能力可表达的机器人,新增 Package 与索引条目即可。
首期通用 runtime 支持:
- floating base、具名 freejoint / root body;受控关节为标量 hinge / slide。
- 每个受控关节一个 unit-gear actuator,独立解析 joint / qpos / dof / actuator 地址,不依赖其数组顺序。
- ONNX primary;不相交关节组的正弦 overlay;与 primary 独占相同关节组的 ONNX episodic 技能。
- gyro、body projected gravity、joint position relative、joint velocity、lastAction、command;可选 1–64 帧 frame-major / term-major 历史,首次采样回填,reset 清空。
- episodic 可用
motion_command读取仿真时钟驱动的 joint position/velocity 参考。每技能独立进度,pause 冻结、激活从帧 0 重启;参考只进入观测,不运动学改写机器人。 - 关节位置目标;unit-gain torque motor 的子步 PD,或原生 position servo。PD 可配置每关节增益/力矩上限与可选四象限 torque-speed envelope。
- MJCF 编译后 visual geom / mesh / material 渲染;默认
arena是按机器人站立高度缩放的有碰撞围墙平地。Microduck 基准为 4.5 × 4.5 m,使用暗色/橙色地面和墙网格;同款 comic UI 与背后相机,C 恢复。 presentation.world可省略,统一由平台DEFAULT_WORLD解析,不要在每个新包里复制默认场地名。需要诊断时,通用包可显式设为"flat"(无墙)。机器人出生点和尺寸应适合默认边界。- Package 绑定驱动的键盘输入与同源提示 / 技能按钮。
固定基座、ball joint 的多维 action、非单位 gear、自定义外部 JS、RNN、图像张量、BeyondMimic 的 privileged motion_preview/anchor/base-linear-velocity terms、IK、velocity / effort action 等尚不支持。JSON Schema 与运行时都会拒绝不支持的能力,不能仅添加未实现的配置名来声称已经兼容。
文件布局
app/public/robots/example/
robot.json
model.xml
assets/...
policies/walk.onnx
policies/wave.onnx # 可选独立 episodic
motions/wave.json # 可选 reference 描述
motions/wave.f32 # positions_then_velocities / float32-le
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.jsonapp/src/platform/loader/world.schema.jsonSchemaValidator.js的跨字段检查(所有权、输入绑定、命令尺寸等)。
可选分部件 GLB 外观
通用 runtime 保留 render.source: "mjcf_visual",可增加 render.body_visuals,仅替换指定 body 的可见几何:
"body_visuals": [
{
"body": "trunk",
"path": "visuals/trunk.glb",
"position": [0, 0, 0],
"quaternion": [0, 0, 0, 1]
}
]
body 必须是 MJCF 中存在的非 world body,且不能重复。position 为米制 body-local 平移;quaternion 为 xyzw 单位四元数;省略时分别使用零平移 / 单位旋转。不按导出文件名猜 body,不使用 MuJoCo 编译器重心校正后的 geom 坐标绑定 GLB。模型单位须预先为米,不支持隐式自动缩放。
GLB 必须自包含(纹理/二进制内嵌),不能引用外部图片或 buffer;path 是包内相对 .glb 路径。资源经 PackageLoader 加载,保留部署前缀与同源签名。GLB 不加入 assets / VFS,因为它们不参与物理编译。隐藏原 visual 不修改原碰撞、惯量、关节、策略或动作。缺失 body 或资源导致候选加载失败,并通过现有切换流程回退。
新增视觉资源应单独保存 visual-source-manifest.json,包含 files: [{"file":"visuals/trunk.glb","sha256":"..."}];validate:packages 同时验证原来源记录、视觉记录和 GLB 自包含约束。示例与实测记录见 Microban。
场地与机器人尺寸
在 Robot Package 顶层声明参考站姿的全身高度(米),例如:
"dimensions": { "height": 1.32 }
默认 arena 的 scale_to_robot.reference_height 为 Microduck 的 0.27 m,场地长宽、墙高、墙厚、网格间距与淡出距离均按 height / 0.27 同比缩放。Microduck 保持 4.5 m 方形场地 / 0.25 m 墙高;Microban(0.33 m)为 5.5 m / 0.306 m;RP1(1.32 m)为 22 m / 1.222 m。物理碰撞和视觉墙使用同一份解析后 World 尺寸。
高度是稳定的名义尺寸,不是 base.spawn.z,不会随蹲下、跌倒或挥手动态改变;Microduck 腿/轮共用同一参考值。省略 dimensions 的旧包按基准倍率 1 兼容,新增机器人应明确填写。自定义 World 不声明 scale_to_robot 就保持固定米制尺寸;flat 诊断场地不受影响。解析后的 world.scale 是运行时派生值,不应写进 world.json。
必须逐项核对
- joint group:
joints.groups.policy是 actor 的真实顺序,不是 MJCF 或 metadata 全体顺序;overlay 另列 group。 - defaults / initial:metadata 参考姿态用于 relative observation 和 action offset;
base.initial是出生 / reset 姿态,两者不必相同。 - sensor frame:声明实际 gyro sensor 和 gravity body;不要把 sensor frame 与 root body frame 默认当成同一个坐标系。
- obs / action:尺寸由 terms 汇总,并与真实 session 的 dtype、shape、input / output 对比;NaN 与非法 target 不允许部分写入 ctrl。
- actuator:不能把关节角写进 torque motor。PD 增益 / 力矩上限由配置显式指定,不能自动等价于任意训练 metadata。
- 资源路径:以 manifest 为基准解析;不得依赖源项目绝对路径。内置 asset URL 必须同源,保留 Vite base 与已有同源签名参数。
- 终止:配置合理的倾角 / 高度;没有恢复策略时使用手动 reset,不用自动重置掩盖跌倒。
- 输入:语义动作支持
move_forward/move_backward/turn_left/turn_right、reset、pause、toggle:<overlay>、skill:<episodic>;提示由绑定生成。待权重的 episodic 必须设置available:false,对应绑定disabled:true,不加载虚构的权重路径。 - 许可:填写 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 执行入口。
新增完整的历史观测、独立策略默认姿态与 episodic 状态机约定见 RP1 接入说明。每个技能可覆盖 observations/actions/defaults,并可声明 reference;motion_command 的 group 必须与技能 owns 一致,reference 的关节顺序/控制时钟/精确数据长度均验证。未知 observation term、RNN 或任意新 ONNX 输入结构仍需显式实现与验证。
World 与 Robot 配置解耦:所有现有包与不指定 world 的新通用包均默认 arena。Microduck 专用适配器保留其球/可选起伏等特性,通用机器人只共享平地、边界和场地视觉;这不等于任意新机器人都已获得策略兼容或所有 Microduck 玩法。