Files

116 lines
8.5 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 首期 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 玩法。