cmvr-es/cmvr-es/simulate/README.md

Simulate 模块开发指南

simulate/ 保存仿真引擎适配和可视化辅助能力。当前实现主要是 MuJoCo viewer；模拟摄像头、电机和机械臂仍通过 devices/ 中相同的设备抽象接入系统。

返回项目总览。

职责边界

simulate/ 负责：

• 仿真引擎上下文、模型和 viewer；
• 引擎事件循环、渲染和 UI adapter；
• 仿真资源加载的通用辅助能力。

devices/ 负责：

• 将仿真传感器或执行器实现为 AbstractDevice 子类；
• 对外提供与真机一致的设备语义；
• 参与 DeviceFactory、DeviceManager 和 gRPC/媒体接入。

不要让 service 或 task 直接调用 MuJoCo API；它们应通过设备抽象工作。

当前 CMake

• CMakeLists.txt 加载 mujoco/；
• mujoco/CMakeLists.txt 加载 viewer；
• target cmvr_es::mujoco_viewer 链接 MuJoCo、GLFW 和 OpenGL。

新增仿真引擎

1. 新建 simulate/<engine>/；
2. 将 engine context 和资源所有权封装在独立类中；
3. 提供明确 initialize/start/step/stop 生命周期；
4. 通过 adapter 向模拟设备暴露最小能力；
5. 在 devices/ 中实现对应模拟后端；
6. 在设备 config proto 的 oneof backend 增加配置；
7. 更新两侧 CMake；
8. 提供 headless 测试，并将图形测试单独标记。

线程和资源

• 明确由哪个线程调用 engine step 和 render；
• 不在多个线程无锁访问引擎状态；
• viewer 关闭不能悬挂设备回调；
• 设备停止后不得继续读取已释放的仿真模型；
• 模型路径通过 ConfigHelper::resolveResourceFile() 解析；
• headless 环境不能强制创建 OpenGL 窗口；
• 固定或记录仿真 timestep，避免控制周期与仿真周期混淆。

测试建议

• 模型加载失败和资源路径错误；
• headless 初始化、step 和停止；
• 重复启动/停止；
• 模拟设备与真机抽象的行为一致性；
• 时间步、单位、关节顺序和坐标系；
• viewer 关闭与后台设备线程并发；
• 测试结束后无线程、窗口和引擎资源泄漏。