116 lines
8.5 KiB
Markdown
116 lines
8.5 KiB
Markdown
# 首期 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 与运行时都会拒绝不支持的能力,不能仅添加未实现的配置名来声称已经兼容。
|
||
|
||
## 文件布局
|
||
|
||
```text
|
||
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.json`
|
||
- `app/src/platform/loader/world.schema.json`
|
||
- `SchemaValidator.js` 的跨字段检查(所有权、输入绑定、命令尺寸等)。
|
||
|
||
## 可选分部件 GLB 外观
|
||
|
||
通用 runtime 保留 `render.source: "mjcf_visual"`,可增加 `render.body_visuals`,仅替换指定 body 的可见几何:
|
||
|
||
```json
|
||
"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](microban.md)。
|
||
|
||
## 场地与机器人尺寸
|
||
|
||
在 Robot Package 顶层声明参考站姿的全身高度(米),例如:
|
||
|
||
```json
|
||
"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。
|
||
|
||
## 必须逐项核对
|
||
|
||
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>`、`skill:<episodic>`;提示由绑定生成。待权重的 episodic 必须设置 `available:false`,对应绑定 `disabled:true`,不加载虚构的权重路径。
|
||
9. **许可**:填写 license,保存来源、修改与逐文件声明。复制权限不等于所有文件许可一致。
|
||
|
||
## 注册与测试
|
||
|
||
在 `app/public/robots/index.json` 增加条目:
|
||
|
||
```json
|
||
{"id":"example","family":"example","name":"Example","manifest":"example/robot.json"}
|
||
```
|
||
|
||
`adapter: "generic"` 使用通用管线。不要在 RuntimeManager / SimCore / RigRenderer 中加入 `if (robotId === ...)`。Microduck 使用单独的可信内置 adapter,承载其既有状态机和 GLB / 玩法,不是新机器人应复制的一套独立引擎。
|
||
|
||
```bash
|
||
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 接入说明](rp1.md)。每个技能可覆盖 observations/actions/defaults,并可声明 reference;`motion_command` 的 group 必须与技能 owns 一致,reference 的关节顺序/控制时钟/精确数据长度均验证。未知 observation term、RNN 或任意新 ONNX 输入结构仍需显式实现与验证。
|
||
|
||
World 与 Robot 配置解耦:所有现有包与不指定 world 的新通用包均默认 `arena`。Microduck 专用适配器保留其球/可选起伏等特性,通用机器人只共享平地、边界和场地视觉;这不等于任意新机器人都已获得策略兼容或所有 Microduck 玩法。
|