简介这份资源面向具备一定C基础、希望上手Mujoco物理引擎的机器人学与运动控制学习者围绕「用CMake构建并运行简单动力学计算」这一目标组织内容帮助读者打通从库配置到仿真步进的完整链路。压缩包共217个文件、约26.29MB以txt说明、stl几何模型、cmake与make构建脚本、h头文件、cpp源码及json、xml模型描述为主另含编译产物与urdf机器人描述文件便于直接对照工程结构理解各模块职责。已有311人学习下载可作为入门参考。资源中既有CMakeLists配置示例也有加载XML模型、调用mj_step推进仿真并释放资源的代码骨架读者可据此掌握模型加载、数据初始化与动力学步进的基本流程并借鉴其目录组织方式排查编译链接问题为后续多平台构建与复杂场景仿真打下基础。1. 用 CMake 把 MuJoCo 动力学算例跑通一份能直接复现的 C 工程骨架很多人第一次碰 MuJoCo 的 C 接口卡住的地方不是物理公式而是构建系统。官方给的示例往往默认你已经把mujoco的头文件和动态库放到了系统路径里可实际开发机上 CMake 找不到mujoco.h、链接阶段又报undefined reference to mj_step一个简单的动力学计算能折腾一下午。这份资源就是围绕「C CMake MuJoCo」这条最小链路把模型加载、前向动力学、状态推进、结果输出串成一个可编译、可调试的工程骨架适合已经会写 C、想用 MuJoCo 做仿真验证或控制器原型的人。它不追求覆盖全部 API而是把最容易翻车的构建与调用边界先钉死让你把注意力放回动力学本身。2. 工程结构与 CMake 链接先让编译器认识 MuJoCo2.1 目录怎么摆依赖怎么放MuJoCo 的 C 使用本质上就三样东西头文件目录、动态库Linux 下libmujoco.soWindows 下mujoco.dll加导入库、以及运行时能找到库的路径。工程骨架一般长这样我习惯把第三方依赖单独收在third_party下避免和系统安装的版本打架mujoco_dyn_demo/ ├── CMakeLists.txt ├── src/ │ └── main.cpp ├── model/ │ └── arm.xml └── third_party/ └── mujoco/ ├── include/mujoco/mujoco.h └── lib/libmujoco.so模型文件用 MuJoCo 自己的 MJCF 格式一个两连杆摆的例子就够验证动力学了。下面这段 MJCF 定义了一个带两个 hinge 关节的刚体链重力默认朝下跑起来能看到关节角随重力演化mujoco modeltwo_link option timestep0.002 gravity0 0 -9.81/ worldbody body namelink1 pos0 0 1 joint namej1 typehinge axis0 1 0/ geom typecapsule fromto0 0 0 0.3 0 0 size0.03/ body namelink2 pos0.3 0 0 joint namej2 typehinge axis0 1 0/ geom typecapsule fromto0 0 0 0.3 0 0 size0.03/ /body /body /worldbody /mujocotimestep决定积分步长gravity是重力加速度向量两个hinge关节绕 y 轴转动capsule只是可视化用的碰撞体动力学里质量默认由 geom 的密度推算。模型不需要写actuator因为这一步只做被动动力学没有控制输入正好用来验证mj_step是否真的在推进状态。2.2 CMakeLists 的关键几行真正让新手翻车的是链接。下面这份CMakeLists.txt把 include 路径、库路径、运行时 rpath 一次性配好Linux 下拷到别的机器也能直接跑cmake_minimum_required(VERSION 3.16) project(mujoco_dyn_demo CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) # MuJoCo 依赖根目录允许命令行覆盖 set(MUJOCO_ROOT ${CMAKE_SOURCE_DIR}/third_party/mujoco CACHE PATH MuJoCo install root) find_package(Threads REQUIRED) add_executable(dyn_demo src/main.cpp) target_include_directories(dyn_demo PRIVATE ${MUJOCO_ROOT}/include) target_link_libraries(dyn_demo PRIVATE ${MUJOCO_ROOT}/lib/libmujoco.so Threads::Threads ${CMAKE_DL_LIBS}) # 让可执行文件在构建目录直接找到 .so省去每次设 LD_LIBRARY_PATH set_target_properties(dyn_demo PROPERTIES BUILD_RPATH ${MUJOCO_ROOT}/lib INSTALL_RPATH ${MUJOCO_ROOT}/lib)MUJOCO_ROOT用CACHE PATH声明意味着你可以cmake -DMUJOCO_ROOT/opt/mujoco ..覆盖不用改文件。Threads::Threads和${CMAKE_DL_LIBS}是 MuJoCo 内部用到线程与动态加载时需要的漏了会在链接期报一堆符号缺失。BUILD_RPATH是最容易被忽略的一行——没有它编译能过一运行就error while loading shared libraries: libmujoco.so这是血泪经验里出现频率最高的报错之一。2.3 最小动力学主程序主程序只做四件事加载模型、拿mjData、循环mj_step、打印关节角。代码短但每一行都对应一个容易出错的 API 契约#include mujoco/mujoco.h #include cstdio #include cstring int main() { char error[1000] ; // 1. 加载 MJCF失败时 error 里带具体原因 mjModel* m mj_loadXML(model/arm.xml, nullptr, error, 1000); if (!m) { std::printf(load failed: %s\n, error); return 1; } // 2. mjData 必须由 mj_makeData 分配不能 new mjData* d mj_makeData(m); // 3. 给关节一个初始角速度否则纯重力下从静止开始变化太慢 d-qvel[0] 1.0; const int steps 1000; for (int i 0; i steps; i) { mj_step(m, d); // 前向动力学 积分 if (i % 200 0) { std::printf(step %4d q1%.4f q2%.4f\n, i, d-qpos[0], d-qpos[1]); } } // 4. 释放顺序先 data 后 model mj_deleteData(d); mj_deleteModel(m); return 0; }mj_loadXML的第四个参数是错误缓冲区长度传小了错误信息会被截断排查时反而误导。mj_makeData内部按模型维度分配所有状态数组用new mjData是典型误用析构时会对不上。d-qvel[0]对应第一个 hinge 关节的自由度MuJoCo 里qpos和qvel的索引按关节在模型中的声明顺序排列多关节模型一定要先确认索引映射别想当然。mj_step一次完成「计算加速度 → 积分位置和速度」不需要你手动调mj_forward再积分这是和某些教科书式写法最大的差别。构建与运行cmake -S . -B build -DCMAKE_BUILD_TYPERelease cmake --build build -j ./build/dyn_demo如果输出里q1、q2随时间连续变化且没有nan说明整条链路通了。出现nan通常是模型里质量或惯量为零或者timestep给得过大导致积分发散先把timestep降到0.001再试。3. 动力学计算的核心调用mj_forward、mj_step 与状态数组3.1 三个函数的分工别搞混MuJoCo 的动力学 API 里mj_forward、mj_step、mj_step1/mj_step2经常被混用。理解它们的分工决定了你写出来的是「每步算两遍」还是「算一遍就够」函数做什么典型场景mj_forward由当前qpos/qvel计算所有派生量加速度、约束力等不积分只想读传感器、接触力不推进时间mj_step内部先 forward 再积分一步到位常规仿真循环mj_step1/mj_step2把一步拆成两半中间可插入自定义逻辑需要在一步内改控制量或做事件检测常见误用是循环里先mj_forward再mj_step等于每步算了两遍动力学性能直接砍半而且如果中间改了qpos还会引入不一致。我一般只在需要读取d-qfrc_constraint这类派生量、又不想推进时间时单独调mj_forward。3.2 状态数组的索引映射qpos和qvel的长度不等于关节数。hinge 和 slide 关节各占 1 个qposfree 关节占 7 个3 位置 4 四元数ball 关节占 4 个。qvel里 free 关节占 6 个。写控制器前先打印维度核对std::printf(nq%d nv%d nu%d\n, m-nq, m-nv, m-nu); for (int j 0; j m-njnt; j) { std::printf(joint %d: name%s qposadr%d dofadr%d\n, j, mj_id2name(m, mjOBJ_JOINT, j), m-jnt_qposadr[j], m-jnt_dofadr[j]); }jnt_qposadr和jnt_dofadr是官方给的索引映射比自己数关节靠谱得多。多关节模型里用错索引表现是「某个关节不动」或「力矩加到了错误的自由度上」这类 bug 不看映射表很难定位。3.3 加控制输入的最小改法被动动力学验证完下一步通常是加执行器。在 MJCF 里补一段actuator主程序里写d-ctrl[0]actuator motor jointj1 ctrlrange-5 5 ctrllimitedtrue/ /actuator// 简单 PD目标角 0当前角 d-qpos[0] const double kp 20.0, kd 2.0; d-ctrl[0] -kp * d-qpos[0] - kd * d-qvel[0]; mj_step(m, d);ctrlrange和ctrllimited一定要设否则 PD 输出可能瞬间超出执行器能力仿真里表现为关节角剧烈震荡甚至发散。d-ctrl的长度是m-nu索引按 actuator 声明顺序和关节索引不是一回事这点在多个执行器时尤其要小心。4. 避坑与排查链接、路径、数值三类高频翻车4.1 编译过了运行报找不到 libmujoco.so现象cmake --build成功执行时报error while loading shared libraries: libmujoco.so: cannot open shared object file。原因链接期用的是绝对路径但运行时动态加载器只查系统路径和 rpath构建目录没被写进 rpath。解决在CMakeLists.txt里设BUILD_RPATH见 2.2或者临时LD_LIBRARY_PATHthird_party/mujoco/lib ./build/dyn_demo验证。长期方案是 rpath临时方案只用于确认问题根源。4.2 mj_loadXML 返回空但错误信息是乱码或截断现象加载失败error缓冲区里只有半句话。原因错误缓冲区长度传得太小或者模型路径是相对路径而工作目录不对。解决缓冲区给到 1000 以上路径统一用相对于可执行文件的方式或者在 CMake 里用configure_file把模型目录绝对路径写进配置头。我一般会在加载前打印一次getcwd确认工作目录这个习惯省掉过很多次「明明文件在却找不到」的困惑。4.3 仿真几步后 qpos 变成 nan现象前几十步正常之后qpos出现nan并扩散到所有状态。原因积分步长相对模型刚度太大或者模型里某个 geom 的mass为 0、惯量矩阵奇异。解决先把timestep减半观察是否消失再检查 MJCF 里是否有density0又没显式给mass的 geom。数值发散在刚体动力学里是玄学重灾区二分步长是最快的定位手段。4.4 多关节模型力矩加错自由度现象给d-ctrl[0]赋值动的却是另一个关节。原因actuator 顺序和 joint 顺序不一致ctrl索引按 actuator 排不是按 joint 排。解决用mj_id2name打印每个 actuator 绑定的关节名或者直接按名字查 id 再映射别靠声明顺序硬记。4.5 Release 下结果和 Debug 不一致现象Debug 构建结果正常Release 下轨迹偏移。原因代码里有未初始化变量或者浮点优化改变了累加顺序在动力学这种对初值敏感的循环里被放大。解决编译加-Wall -Wextra把未初始化警告打开对比时固定timestep和初始状态逐帧打印qpos找第一处偏差。这类问题不是 MuJoCo 的锅但仿真会把它放大到肉眼可见。5. 进阶验证用能量守恒和解析解给仿真结果上保险跑通不等于算对。动力学代码最怕「看起来在动其实数值是错的」我习惯用两个低成本手段做验证。第一个是能量守恒无控制、无接触、无阻尼的被动系统总能量应该基本恒定。在循环里加一段能量统计// 动能 0.5 * qvel^T * M * qvelM 用 mj_fullM 取 std::vectordouble M(m-nv * m-nv); mj_fullM(m, M.data(), d-qM); double ke 0.0; for (int i 0; i m-nv; i) for (int j 0; j m-nv; j) ke 0.5 * d-qvel[i] * M[i * m-nv j] * d-qvel[j]; // 势能近似各 body 的 z 坐标乘质量乘 g简化版够用 double pe 0.0; for (int b 1; b m-nbody; b) pe m-body_mass[b] * 9.81 * d-xpos[3 * b 2]; std::printf(E%.6f\n, ke pe);mj_fullM把稀疏的qM展开成稠密矩阵小模型直接这么用没问题大模型要注意nv平方的内存开销。能量在几百步内漂移超过百分之几基本可以判定步长偏大或有未建模的阻尼。第二个手段是对单摆做解析对照把模型简化成一个 hinge 加一个质点初始角给一个小角度仿真周期应接近2π√(l/g)偏差大就回头查惯量和质心位置。这两个检查不花多少代码但能把「能跑」和「算对」区分开。从那以后我每次新建 MuJoCo 工程都先把 rpath、错误缓冲区、索引映射这三件事在骨架里固定好再动动力学逻辑省下来的排查时间远比写这几行配置多。希望帮到你。本文还有配套的精品资源点击获取