简介面向机器人学与强化学习开发者这份压缩包演示了如何用 CMake 搭建 MuJoCo 项目并完成简单动力学计算适合刚接触物理仿真与构建系统的读者快速入手。包体共 217 个文件、约 26.29MB包含 CMakeLists 与 cmake 配置、c/cpp 源文件、头文件、xml/urdf 模型描述、stl 几何网格以及 txt、json 等说明与配套文件可覆盖从代码编写、编译配置到模型加载仿真的完整链路。已有 310 人学习下载。内容提供 CMake 查找与链接 MuJoCo 的示例、main.cpp 中加载模型并循环执行 mj_step 的写法还包含 makefile、ninja 等构建产物读者可直接参考目录结构复现实验或在此基础上扩展自己的机器人动力学仿真任务。1. MuJoCo 的 C 动力学计算为什么我坚持用 CMake 自己编把 MuJoCo 以 C 和 CMake 方式串起来是我在做一个两连杆机器人动力学模拟项目时踩过最多轮的组合。很多人会用 pip 装 mujoco跑 Python 例程方便但一旦需要把引擎嵌进自己的 C 仿真工程就绕不开交叉编译、ABI 和静态链接问题。这个工程将 MuJoCo 源码通过 CMake 编进一个独立可执行程序完成从加载模型到正向动力学的完整计算既绕开预编译包的限制又能自由改步长、重力甚至质量矩阵。它适合想脱离官方 demo、亲自掌控构建选项和控制数值粒度的工程师与研究者新手可以直接照做熟手可以对比参数和裁剪手段。2. CMake 拉取与编译 MuJoCo从源码到可链接库2.1 为什么不用官方预编译包官方预编译包解决的是“零配置跑起来”真实工程里却往往是最难受的一环它默认按某种编译器版本和 ABI 打包换编译器、换系统就容易遇到符号不一致想裁剪掉 UI 和渲染模块或者想静态链接进嵌入式环境预编译包基本没法满足。而 MuJoCo 官方仓库本身就是一套 CMake 工程源码编一次的成本其实很低换来的是对构建方式的完全掌控。我一般会把源码放在3rdparty/mujoco不直接改官方文件而是通过根目录的CMakeLists.txt来控制开关。这样后续换版本、打补丁都干净。2.2 最小可编译的 CMakeLists这里给出一个我实际用过的完整配置直接抄作业即可cmake_minimum_required(VERSION 3.16) project(simple_dynamics LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_BUILD_TYPE Release) # MuJoCo 构建选项关闭示例、UI、模拟器只保留动力学核心 set(MUJOCO_BUILD_EXAMPLES OFF CACHE BOOL FORCE) set(MUJOCO_BUILD_SIMULATE OFF CACHE BOOL FORCE) set(MUJOCO_BUILD_UI OFF CACHE BOOL FORCE) set(MUJOCO_HEADLESS ON CACHE BOOL FORCE) add_subdirectory(3rdparty/mujoco) add_executable(simple_demo main.cpp) target_link_libraries(simple_demo PRIVATE mujoco)MUJOCO_BUILD_UI和MUJOCO_BUILD_SIMULATE关掉后编译时间能省一大截依赖也只保留最基本的系统库。MUJOCO_HEADLESS开启后引擎内部的 OpenGL 渲染链路不会参与编译对纯动力学计算完全够用。target_link_libraries 只需要写mujoco一个名字因为 add_subdirectory 引入的 target 会自动传递 include 目录。头文件路径在编译时会被带入不需要手动加-I。2.3 构建命令与验证构建命令走标准流程cmake -B build -S . -DCMAKE_BUILD_TYPERelease cmake --build build --parallel 4编完后写一个极简检查确认库和头文件都能正常工作#include iostream #include mujoco/mujoco.h int main() { std::cout mujoco version: mj_version() std::endl; return 0; }跑出来如果能看到版本号说明mujoco.h路径和链接都通了。这一关过了后面加模型和仿真代码才有意义。很多人在这一步卡住往往是头文件找不到或链接时缺库后面专门讲。2.4 构建选项的裁剪建议如果只做动力学计算我建议把MUJOCO_BUILD_SIMULATE和MUJOCO_BUILD_EXAMPLES都关掉。示例代码会引入额外的 GLFW、OpenGL 依赖编起来慢还容易在服务器无图形环境下报错。当前资源包里的根目录 CMakeLists 默认就是裁剪过的。静态链接也是需要注意的是项。如果你想把可执行文件丢到别的机器上跑BUILD_SHARED_LIBS默认编出的共享库需要一起分发改成-DBUILD_SHARED_LIBSOFF再编一次产出的静态库可以直接嵌进二进制。代价是最终文件体积变大但省去了运行时库路径问题。注意改完BUILD_SHARED_LIBS后建议删除 build 目录重新配置一次CMake 缓存里残留的旧选项会导致链接产物不对。3. 从加载模型到正向动力学模型对象、数据对象与步进循环3.1 模型 XML 与 mjModel/mjData 的关系MuJoCo 里mjModel描述系统本身杆件长度、质量、关节轴、执行器位置全部是只读的。mjData是运行时的可变状态当前关节角、角速度、外力、加速度每次步进都会被改写。两者不能混淆——mjModel在程序生命周期里基本不变mjData每步都在变。先给一个两连杆摆模型的 XMLmujoco modeltwo_link_arm option timestep0.002 gravity0 0 -9.81/ worldbody body namelink1 pos0 0 0.1 joint namej1 typehinge axis0 0 1/ geom typecapsule size0.02 fromto0 0 0 0 0.2 0 mass0.5/ body namelink2 pos0 0 0.2 joint namej2 typehinge axis0 0 1/ geom typecapsule size0.015 fromto0 0 0 0 0.15 0 mass0.3/ /body /body /worldbody actuator motor nameJ1 jointj1 ctrlrange-10 10 gear1/ motor nameJ2 jointj2 ctrlrange-10 10 gear1/ /actuator /mujoco加载模型并初始化数据对象的代码#include mujoco/mujoco.h #include iostream int main(int argc, char** argv) { if (argc 2) { std::cerr usage: simple_demo model.xml std::endl; return 1; } char err[1024] {0}; mjModel* model mj_loadXML(argv[1], nullptr, err, 1024); if (!model) { std::cerr load error: err std::endl; return 2; } mjData* data mj_makeData(model); std::cout nq model-nq nv model-nv timestep model-opt.timestep std::endl; mj_deleteData(data); mj_deleteModel(model); return 0; }nq是广义坐标维度nv是广义速度维度对纯 hinge 关节来说两者相同。model-opt.timestep就是仿真步长XML 里没写时默认是 2 毫秒。如果模型里含球关节或滑动关节nq 和 nv 会不同做索引时千万别拿 nq 当数组长度去遍历 qvel。3.2 设置初始状态并跑仿真循环核心的正向动力学循环其实很短// 设置初始关节角与角速度>int body_id mj_name2id(model, mjOBJ_BODY, link2); if (body_id 0) { double px >#include sys/stat.h bool file_exists(const std::string path) { struct stat st; return stat(path.c_str(), st) 0; }加载前先if (!file_exists(path)) return -1;能提前排除绝大多数“空指针但无提示”的假玄学。4.2 给 qpos 赋值后直接 mj_step第一步数值就飞了现象设置初始角度 0.5 弧度跑第一步输出 qpos 变成几十甚至几百明显不符合物理。原因修改 qpos 后没有调用mj_forward内部的质量矩阵和姿态相关量仍然停留在上一步步进结束时的状态。MuJoCo 里mjData的很多派生量是惰性缓存的不 forward 不会自动重算。解决所有手动状态初始化必须按这个顺序来mj_resetData(model, data);>add_executable(simple_demo main.cpp) target_link_libraries(simple_demo PRIVATE mujoco)mujocotarget 会把自己的 include 和链接目录带出来。如果是手写 Makefile库必须放在目标文件之后simple_demo: main.cpp libmujoco.a g -stdc17 main.cpp -lmujoco -o simple_demo4.4 xpos 是 float 不是 double精度坑比想象中隐蔽现象从>float fx >rm -rf build cmake -B build -S . -DBUILD_SHARED_LIBSOFF这个习惯养成了基本不会再遇到“我明明改了配置怎么还编出旧产物”的怪问题。5. 收尾把单文件 Demo 封装成 Simulator 类并做数值验证跑通简单 Demo 之后下一步是复用。我通常会把 mjModel/mjData 的生命周期封装在一个类里避免在多个函数之间传递裸指针class SimpleDynamics { public: ~SimpleDynamics() { if (data_) mj_deleteData(data_); if (model_) mj_deleteModel(model_); } bool Load(const std::string xml_path) { char err[1024] {0}; model_ mj_loadXML(xml_path.c_str(), nullptr, err, 1024); if (!model_) return false; data_ mj_makeData(model_); return true; } void Step() { mj_step(model_, data_); } double GetPosition(int body_name_id, int axis) const { float val data_-xpos[3 * body_name_id axis]; return static_castdouble(val); } private: mjModel* model_ nullptr; mjData* data_ nullptr; };封装的核心是把初始化、步进、状态读取的接口收拢上层算法只跟类交互不碰原始的 model/data 指针。这样后续换用更精细的执行器模型或加传感器都不会牵扯到业务代码。数值验证方面我会在测试工程里加一个能量守恒检查记录初始动能加势能跑 1000 步后对比数值漂移。MuJoCo 的仿真有数值耗散能量不可能是严格恒定的但如果出现明显单调发散说明要么步长过大要么初始状态 set 得不合理。具体做法是在步进循环里累计动能和重力势能的差值并打印比值double ke 0.0; for (int i 0; i model_-nv; i) { ke 0.5 * data_-qvel[i] * data_-qvel[i]; }这里只取了粗略的动能指标严格版本需要用mj_fullM展开质量矩阵才算准但作为日常验证已经够用了。从那以后我每次接新的 C 动力学工程都强制先跑一遍加载检查、数值一致性和步长实验再谈上层算法。这套流程帮我避开了不少隐藏的初始化问题希望你也能少走几步弯路。本文还有配套的精品资源点击获取 
长河君 · 2026/10/16 3:31:38 · 阅读 1.2k MuJoCo C++动力学计算：CMake编译与正向动力学实战
简介面向机器人学与强化学习开发者这份压缩包演示了如何用 CMake 搭建 MuJoCo 项目并完成简单动力学计算适合刚接触物理仿真与构建系统的读者快速入手。包体共 217 个文件、约 26.29MB包含 CMakeLists 与 cmake 配置、c/cpp 源文件、头文件、xml/urdf 模型描述、stl 几何网格以及 txt、json 等说明与配套文件可覆盖从代码编写、编译配置到模型加载仿真的完整链路。已有 310 人学习下载。内容提供 CMake 查找与链接 MuJoCo 的示例、main.cpp 中加载模型并循环执行 mj_step 的写法还包含 makefile、ninja 等构建产物读者可直接参考目录结构复现实验或在此基础上扩展自己的机器人动力学仿真任务。1. MuJoCo 的 C 动力学计算为什么我坚持用 CMake 自己编把 MuJoCo 以 C 和 CMake 方式串起来是我在做一个两连杆机器人动力学模拟项目时踩过最多轮的组合。很多人会用 pip 装 mujoco跑 Python 例程方便但一旦需要把引擎嵌进自己的 C 仿真工程就绕不开交叉编译、ABI 和静态链接问题。这个工程将 MuJoCo 源码通过 CMake 编进一个独立可执行程序完成从加载模型到正向动力学的完整计算既绕开预编译包的限制又能自由改步长、重力甚至质量矩阵。它适合想脱离官方 demo、亲自掌控构建选项和控制数值粒度的工程师与研究者新手可以直接照做熟手可以对比参数和裁剪手段。2. CMake 拉取与编译 MuJoCo从源码到可链接库2.1 为什么不用官方预编译包官方预编译包解决的是“零配置跑起来”真实工程里却往往是最难受的一环它默认按某种编译器版本和 ABI 打包换编译器、换系统就容易遇到符号不一致想裁剪掉 UI 和渲染模块或者想静态链接进嵌入式环境预编译包基本没法满足。而 MuJoCo 官方仓库本身就是一套 CMake 工程源码编一次的成本其实很低换来的是对构建方式的完全掌控。我一般会把源码放在3rdparty/mujoco不直接改官方文件而是通过根目录的CMakeLists.txt来控制开关。这样后续换版本、打补丁都干净。2.2 最小可编译的 CMakeLists这里给出一个我实际用过的完整配置直接抄作业即可cmake_minimum_required(VERSION 3.16) project(simple_dynamics LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_BUILD_TYPE Release) # MuJoCo 构建选项关闭示例、UI、模拟器只保留动力学核心 set(MUJOCO_BUILD_EXAMPLES OFF CACHE BOOL FORCE) set(MUJOCO_BUILD_SIMULATE OFF CACHE BOOL FORCE) set(MUJOCO_BUILD_UI OFF CACHE BOOL FORCE) set(MUJOCO_HEADLESS ON CACHE BOOL FORCE) add_subdirectory(3rdparty/mujoco) add_executable(simple_demo main.cpp) target_link_libraries(simple_demo PRIVATE mujoco)MUJOCO_BUILD_UI和MUJOCO_BUILD_SIMULATE关掉后编译时间能省一大截依赖也只保留最基本的系统库。MUJOCO_HEADLESS开启后引擎内部的 OpenGL 渲染链路不会参与编译对纯动力学计算完全够用。target_link_libraries 只需要写mujoco一个名字因为 add_subdirectory 引入的 target 会自动传递 include 目录。头文件路径在编译时会被带入不需要手动加-I。2.3 构建命令与验证构建命令走标准流程cmake -B build -S . -DCMAKE_BUILD_TYPERelease cmake --build build --parallel 4编完后写一个极简检查确认库和头文件都能正常工作#include iostream #include mujoco/mujoco.h int main() { std::cout mujoco version: mj_version() std::endl; return 0; }跑出来如果能看到版本号说明mujoco.h路径和链接都通了。这一关过了后面加模型和仿真代码才有意义。很多人在这一步卡住往往是头文件找不到或链接时缺库后面专门讲。2.4 构建选项的裁剪建议如果只做动力学计算我建议把MUJOCO_BUILD_SIMULATE和MUJOCO_BUILD_EXAMPLES都关掉。示例代码会引入额外的 GLFW、OpenGL 依赖编起来慢还容易在服务器无图形环境下报错。当前资源包里的根目录 CMakeLists 默认就是裁剪过的。静态链接也是需要注意的是项。如果你想把可执行文件丢到别的机器上跑BUILD_SHARED_LIBS默认编出的共享库需要一起分发改成-DBUILD_SHARED_LIBSOFF再编一次产出的静态库可以直接嵌进二进制。代价是最终文件体积变大但省去了运行时库路径问题。注意改完BUILD_SHARED_LIBS后建议删除 build 目录重新配置一次CMake 缓存里残留的旧选项会导致链接产物不对。3. 从加载模型到正向动力学模型对象、数据对象与步进循环3.1 模型 XML 与 mjModel/mjData 的关系MuJoCo 里mjModel描述系统本身杆件长度、质量、关节轴、执行器位置全部是只读的。mjData是运行时的可变状态当前关节角、角速度、外力、加速度每次步进都会被改写。两者不能混淆——mjModel在程序生命周期里基本不变mjData每步都在变。先给一个两连杆摆模型的 XMLmujoco modeltwo_link_arm option timestep0.002 gravity0 0 -9.81/ worldbody body namelink1 pos0 0 0.1 joint namej1 typehinge axis0 0 1/ geom typecapsule size0.02 fromto0 0 0 0 0.2 0 mass0.5/ body namelink2 pos0 0 0.2 joint namej2 typehinge axis0 0 1/ geom typecapsule size0.015 fromto0 0 0 0 0.15 0 mass0.3/ /body /body /worldbody actuator motor nameJ1 jointj1 ctrlrange-10 10 gear1/ motor nameJ2 jointj2 ctrlrange-10 10 gear1/ /actuator /mujoco加载模型并初始化数据对象的代码#include mujoco/mujoco.h #include iostream int main(int argc, char** argv) { if (argc 2) { std::cerr usage: simple_demo model.xml std::endl; return 1; } char err[1024] {0}; mjModel* model mj_loadXML(argv[1], nullptr, err, 1024); if (!model) { std::cerr load error: err std::endl; return 2; } mjData* data mj_makeData(model); std::cout nq model-nq nv model-nv timestep model-opt.timestep std::endl; mj_deleteData(data); mj_deleteModel(model); return 0; }nq是广义坐标维度nv是广义速度维度对纯 hinge 关节来说两者相同。model-opt.timestep就是仿真步长XML 里没写时默认是 2 毫秒。如果模型里含球关节或滑动关节nq 和 nv 会不同做索引时千万别拿 nq 当数组长度去遍历 qvel。3.2 设置初始状态并跑仿真循环核心的正向动力学循环其实很短// 设置初始关节角与角速度>int body_id mj_name2id(model, mjOBJ_BODY, link2); if (body_id 0) { double px >#include sys/stat.h bool file_exists(const std::string path) { struct stat st; return stat(path.c_str(), st) 0; }加载前先if (!file_exists(path)) return -1;能提前排除绝大多数“空指针但无提示”的假玄学。4.2 给 qpos 赋值后直接 mj_step第一步数值就飞了现象设置初始角度 0.5 弧度跑第一步输出 qpos 变成几十甚至几百明显不符合物理。原因修改 qpos 后没有调用mj_forward内部的质量矩阵和姿态相关量仍然停留在上一步步进结束时的状态。MuJoCo 里mjData的很多派生量是惰性缓存的不 forward 不会自动重算。解决所有手动状态初始化必须按这个顺序来mj_resetData(model, data);>add_executable(simple_demo main.cpp) target_link_libraries(simple_demo PRIVATE mujoco)mujocotarget 会把自己的 include 和链接目录带出来。如果是手写 Makefile库必须放在目标文件之后simple_demo: main.cpp libmujoco.a g -stdc17 main.cpp -lmujoco -o simple_demo4.4 xpos 是 float 不是 double精度坑比想象中隐蔽现象从>float fx >rm -rf build cmake -B build -S . -DBUILD_SHARED_LIBSOFF这个习惯养成了基本不会再遇到“我明明改了配置怎么还编出旧产物”的怪问题。5. 收尾把单文件 Demo 封装成 Simulator 类并做数值验证跑通简单 Demo 之后下一步是复用。我通常会把 mjModel/mjData 的生命周期封装在一个类里避免在多个函数之间传递裸指针class SimpleDynamics { public: ~SimpleDynamics() { if (data_) mj_deleteData(data_); if (model_) mj_deleteModel(model_); } bool Load(const std::string xml_path) { char err[1024] {0}; model_ mj_loadXML(xml_path.c_str(), nullptr, err, 1024); if (!model_) return false; data_ mj_makeData(model_); return true; } void Step() { mj_step(model_, data_); } double GetPosition(int body_name_id, int axis) const { float val data_-xpos[3 * body_name_id axis]; return static_castdouble(val); } private: mjModel* model_ nullptr; mjData* data_ nullptr; };封装的核心是把初始化、步进、状态读取的接口收拢上层算法只跟类交互不碰原始的 model/data 指针。这样后续换用更精细的执行器模型或加传感器都不会牵扯到业务代码。数值验证方面我会在测试工程里加一个能量守恒检查记录初始动能加势能跑 1000 步后对比数值漂移。MuJoCo 的仿真有数值耗散能量不可能是严格恒定的但如果出现明显单调发散说明要么步长过大要么初始状态 set 得不合理。具体做法是在步进循环里累计动能和重力势能的差值并打印比值double ke 0.0; for (int i 0; i model_-nv; i) { ke 0.5 * data_-qvel[i] * data_-qvel[i]; }这里只取了粗略的动能指标严格版本需要用mj_fullM展开质量矩阵才算准但作为日常验证已经够用了。从那以后我每次接新的 C 动力学工程都强制先跑一遍加载检查、数值一致性和步长实验再谈上层算法。这套流程帮我避开了不少隐藏的初始化问题希望你也能少走几步弯路。本文还有配套的精品资源点击获取