# MuJoCo Web 仿真平台

基于 MuJoCo 官方 JavaScript/WASM 绑定的中文桌面仿真平台。平台依赖与当前源码版本一致的 `@mujoco/mujoco` 默认入口（单线程）；本工作区现有 `wasm/dist/` 是启用线程构建的产物，因此不作为 MVP 运行入口。所有模型和资源只写入浏览器内的 Emscripten MEMFS，不上传到服务器。

## MVP 功能

- 导入单个/多个 MJCF(XML)、URDF 和关联资源
- 兼容常见 ROS URDF：规范化重复 material、解析 `package://` 工程内资源路径
- URDF 导入时可选为 hinge/slide 关节生成 motor 驱动器，并可用 kp/kv 调整对应 MJCF 关节刚度与阻尼，并将可调位置/朝向的摄像头固连到指定机器人 Body
- 导入保留相对路径的文件夹或 ZIP 工程
- 多模型入口选择、中文加载和编译错误
- Three.js primitive、mesh、材质/贴图显示与对象选择
- 播放、暂停、单步、重置、0.25×–4× 速度
- actuator 滑杆、hinge/slide 关节拖动、动态 body 外力拖拽
- 导入单文件 `.py` 控制器，通过本地 Pyodide 在 `mj_step` 前按仿真时间同步执行
- FPS、物理耗时和主线程步进预算提示

## 开发

从仓库根目录运行：

```bash
npm install --prefix wasm
npm run dev:platform --prefix wasm
```

打开 Vite 输出的 HTTP 地址。应用**不支持**通过 `file://` 直接打开，也不注册 Service Worker/PWA。

## 质量检查

```bash
npm run typecheck:platform --prefix wasm
npm run lint:platform --prefix wasm
npm run test:platform --prefix wasm
npm run build:platform --prefix wasm
npm run test:e2e:platform --prefix wasm
```

E2E 默认使用系统安装的 Google Chrome。若没有 Chrome，可修改 `playwright.config.ts` 或运行 `npx playwright install chromium` 后移除 `channel: 'chrome'`。

## 生产构建与本地静态部署

```bash
npm run build:platform --prefix wasm
python3 -m http.server 8080 --directory wasm/web-platform-dist
```

访问 <http://127.0.0.1:8080/>。构建使用 `base: './'`，可部署到任意静态子目录。静态服务器需将 `.wasm` 返回为 `application/wasm`；Python 3.11+、Vite preview、Nginx 等常见服务器均支持。

## 工程导入约定

- 文件夹和 ZIP 中必须至少有一个根元素为 `<mujoco>` 或 `<robot>` 的 `.xml`/`.urdf`。
- 只有一个入口时自动加载；多个入口优先根目录 `model.xml`、`scene.xml` 或唯一 URDF，否则弹窗选择。
- XML 的 `include`、mesh 和贴图路径必须相对于入口/编译器配置可解析。
- 路径穿越、绝对路径、加密 ZIP、重复路径会被拒绝。
- 默认限制：2000 个文件、单文件 128 MiB、总解压大小 512 MiB、ZIP 文件 128 MiB。
- 文件夹或 ZIP 中的 `.py` 会显示在“控制 → Python 控制器”；也可以在加载模型后单独导入不超过 1 MiB 的 `.py`。

## Python 控制器

Python 控制器是可信的单文件脚本，必须同步定义 `step(ctx, state)`；可选定义 `NAME`、`CONTROL_HZ`（限制为 1–500 Hz）、`init(api)`、`command(name, state)`、`reset(state)` 和 `dispose(state)`。`init` 可用 `api.joint(name)`、`api.actuator(name)`、`api.sensor(name)`、`api.body(name)` 预解析 ID；`step` 可用 `ctx.qpos(id)`、`ctx.qvel(id)`、`ctx.sensor(id)`、`ctx.body_quat(id)`、`ctx.body_position(id)` 读取状态，并用 `ctx.set_control(id, value)` 写入经过有限值检查和 actuator 限幅的控制量。定义 `command` 后，界面会显示停止、前进、后退、左转、右转和起跳按钮，并分别传入 `stop`、`forward`、`backward`、`turn_left`、`turn_right`、`jump`。所有回调都必须同步；异常会自动停止控制器或显示诊断，运行期异常还会暂停仿真并清零 `ctrl`。

当前 Python 与 MuJoCo 都运行在主线程，以保证闭环调用严格位于 `mj_step` 前。仅运行可信脚本；死循环仍可能阻塞页面。Pyodide 及 Python 标准库由 npm 包随生产构建离线发布，不从 CDN 下载；暂不支持第三方 Python 包、`pip` 或多文件 import。

## 示例

`fixtures/` 包含（用于测试和手工验收，不会打进生产构建）：

- `mjcf_include/`：MJCF include、OBJ/STL mesh 和 PNG texture；
- `urdf_mesh/`：引用 OBJ 的 URDF；
- `python_controller/`：倒立摆模型及 `balance.py` PD 控制器；
- `invalid.xml`：无效模型；
- `missing-resource.xml`：缺失资源错误示例。

在“打开文件夹”中选择夹具目录即可加载。

## 当前限制

- 仅面向桌面版 Chrome、Edge、Firefox；未适配手机和平板。
- 物理运行在主线程、单线程 WASM。超出每帧预算时限制追帧并提示。
- 不支持 Xacro、账号或云端保存；Python 控制器暂不支持第三方包和不可信代码隔离。
- 关节拖动只支持 hinge/slide；ball/free joint 只读。
- MuJoCo WASM 本身不支持 DAE mesh。平台会移除 DAE visual，并以 collision 几何显示；DAE collision 会替换为半径 0.05 m 的占位球体并在界面警告。高精度仿真应先将 DAE 转为 OBJ/STL 或改为 URDF primitive。
- 导入工程只存在当前页面内存，刷新页面后需重新导入。