mujoco可视化ERROR: mj_copyDataVisual: attempting to copy mjData while stack is in use

MuJoCo 3.3.6 “stack is in use” 问题总结

一、现象

• 训练正常，但一开实时可视化就疯狂报错：

  ERROR: mj_copyDataVisual: attempting to copy mjData while stack is in use
  

• 画面静止或程序直接崩溃。

二、根本原因

1. MuJoCo 的 mjData 内部有一块 运行时堆栈（stack）
2. 在 mj_step / mj_forward 期间，堆栈被标记为 “in-use”
3. 任何线程（包括 viewer）此时再去 读/写/拷贝 同一份 mjData，都会触发 硬保护报错
4. Python 层的 threading.Lock 无法挡住 C 层的保护机制

三、解决思路（官方推荐）

双环境 + 完全串行拷贝

1. 训练环境 env：只负责物理仿真，绝不共享指针
2. 渲染环境 vis_env：物理禁用，仅用于显示
3. 主线程 等 mj_step 返回后（堆栈已释放），一次性把 全部状态字段 拷到渲染环境，再 mj_forward 刷新几何
4. viewer 线程 只读渲染环境，永不碰原始 mjData

四、关键代码片段（已验证 MuJoCo 3.3.6）

1. 创建渲染环境（全局）

vis_env = _make_vis_env()               # 物理被禁用
vis_model = vis_env.physics.model.ptr
vis_data  = vis_env.physics.data.ptr

2. 主线程每步仿真后整包深拷

next_timestep = env.step(action)        # mj_step 结束，堆栈空闲

with vis_lock:
    vis_data.time = env.physics.data.time
    np.copyto(vis_data.qpos,  env.physics.data.qpos)
    np.copyto(vis_data.qvel,  env.physics.data.qvel)
    np.copyto(vis_data.act,   env.physics.data.act)
    np.copyto(vis_data.mocap_pos,  env.physics.data.mocap_pos)
    np.copyto(vis_data.mocap_quat, env.physics.data.mocap_quat)
    # 如有 userdata / warm-start 也拷
    mujoco.mj_forward(vis_model, vis_data)   # 仅 viewer 用

3. viewer 线程只读副本

def _viewer_thread():
    with mujoco.viewer.launch_passive(vis_model, vis_data) as v:
        v.cam.distance = 1.2
        while v.is_running() and not vis_exit:
            v.sync()
            time.sleep(0.002)
threading.Thread(target=_viewer_thread, daemon=True).start()

五、结果

• 3D 窗口实时显示果蝇拍翅、悬停
• 控制台 再无 stack is in use 报错
• 训练速度几乎无损失（仅一次额外 mj_forward）

六、一句话记住

“仿真完再拷，整包拷给独立环境，viewer 永远别碰原始 mjData” —— MuJoCo 3.3.6 线程安全可视化就稳了。