Mujoco_WASM/wasm/web_platform/README.md

MuJoCo Web 仿真平台

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

MVP 功能

• 导入单个/多个 MJCF(XML)、URDF 和关联资源
• 兼容常见 ROS URDF：规范化重复 material、解析 package:// 工程内资源路径
• 导入保留相对路径的文件夹或 ZIP 工程
• 多模型入口选择、中文加载和编译错误
• Three.js primitive、mesh、材质/贴图显示与对象选择
• 播放、暂停、单步、重置、0.25×–4× 速度
• actuator 滑杆、hinge/slide 关节拖动、动态 body 外力拖拽
• FPS、物理耗时和主线程步进预算提示

开发

从仓库根目录运行：

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

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

质量检查

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'。

生产构建与本地静态部署

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。

示例

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

• mjcf_include/：MJCF include、OBJ/STL mesh 和 PNG texture；
• urdf_mesh/：引用 OBJ 的 URDF；
• invalid.xml：无效模型；
• missing-resource.xml：缺失资源错误示例。

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

当前限制

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