简介这份资源面向具备C基础、希望上手Mujoco物理引擎的机器人学与运动控制学习者围绕「用CMake构建并运行简单动力学计算」这一目标提供可直接编译运行的工程示例。压缩包共217个文件、约26.29MB以cpp与h源码、cmake与make构建脚本、xml与urdf模型描述、stl网格资源为主另含json配置、js与html页面及编译产物完整呈现了从CMakeLists配置、链接Mujoco库到加载XML模型、调用mj_step推进仿真的工程链路。已有311人学习下载适合作为入门模板对照实践帮助读者理解多体系统牛顿-欧拉求解、接触与约束处理的基本流程并掌握find_package、target_link_libraries等构建写法为后续扩展状态存取、多平台编译与性能优化打下基础。1. 从一份“跑不起来”的 CMake 工程说起拿到一个只有标题、没有 README 的动力学计算工程最省事的验证方式不是读代码而是先让它编译通过、跑出一组关节力矩。这个项目就是围绕 MuJoCo 做的最小闭环用 C 写主程序用 CMake 组织构建加载一个 MJCF 模型做前向动力学和逆动力学计算把结果打印出来。它适合两类人一类是想把 MuJoCo 从 Python 脚本迁到 C 工程里的开发者另一类是刚接触刚体动力学、想看清mj_forward和mj_inverse到底在算什么的学生或算法工程师。整份资源的价值不在算法多深而在于把“模型加载、状态设置、动力学调用、结果输出”这条链路用最少的文件跑通方便你在此基础上加控制器、加轨迹、加自己的模型。下面按“能干什么、怎么跑、怎么改”的顺序拆开讲。2. 工程骨架与构建链路CMake 怎么把 MuJoCo 接进来2.1 目录结构与文件职责这类最小动力学工程常见做法是保持四个层次顶层CMakeLists.txt负责找依赖和定编译标准src/放主程序model/放 MJCF 模型文件build/作为外部构建目录。文件不多但每个位置都有明确职责二次开发时不容易乱。mujoco-dynamics-demo/ ├── CMakeLists.txt ├── src/ │ └── main.cpp ├── model/ │ └── arm.xml └── build/ # 构建时生成不提交main.cpp承担全部逻辑初始化、加载模型、读状态、算动力学、打印。arm.xml是一个简单的多关节连杆模型包含worldbody、若干body和joint以及必要的inertial与geom。把模型和代码分开是为了改模型时不用重新编译只换 XML 路径即可。build/放在源码树外是 CMake 的常规习惯避免生成物污染源码目录。2.2 CMakeLists 的关键写法MuJoCo 官方提供 CMake 包配置找到之后用target_link_libraries链接即可。下面是一份能直接用的最小配置关键点在find_package的版本要求和MUJOCO_DIR的提示。cmake_minimum_required(VERSION 3.16) project(mujoco_dynamics_demo LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) # 查找 MuJoCo要求至少 3.x找不到时给出提示 find_package(MuJoCo 3.0 REQUIRED) add_executable(dynamics_demo src/main.cpp) # MuJoCo::mujoco 是官方导出的目标名 target_link_libraries(dynamics_demo PRIVATE MuJoCo::mujoco) # 模型目录作为编译期宏传入运行时按相对路径找 XML target_compile_definitions(dynamics_demo PRIVATE MODEL_DIR${CMAKE_CURRENT_SOURCE_DIR}/model)find_package(MuJoCo 3.0 REQUIRED)依赖系统里已经安装 MuJoCo 并注册了 CMake 配置。如果配置阶段报Could not find a package configuration file provided by MuJoCo说明 CMake 没在默认前缀里找到mujoco-config.cmake这时用-DMuJoCo_DIR/path/to/mujoco/lib/cmake/mujoco指过去。target_compile_definitions把模型目录写成宏是为了让程序不依赖当前工作目录从任何地方启动都能找到 XML。CMAKE_CXX_STANDARD 17不是 MuJoCo 硬性要求但 C17 的std::filesystem和结构化绑定在后续扩展里很顺手。2.3 构建与首次运行构建命令很标准注意-DCMAKE_BUILD_TYPERelease对动力学计算有实际影响Debug 下 Eigen 相关模板会慢不少。cmake -S . -B build -DCMAKE_BUILD_TYPERelease cmake --build build -j ./build/dynamics_demo第一条命令生成构建系统-S .指源码目录-B build指构建目录。第二条并行编译。第三条运行。如果运行时报XML Error: Error opening file先确认model/arm.xml存在再确认编译时传入的MODEL_DIR是否正确可以用strings build/dynamics_demo | grep model粗查宏值。首次跑通的标准输出应该是若干行关节位置、速度以及计算出的力矩数值不必好看能稳定打印就说明链路通了。3. 核心代码拆解一次前向与逆动力学的完整调用3.1 模型加载与数据结构初始化MuJoCo 的 C 接口围绕两个核心结构mjModel描述模型常量mjData描述运行时状态。所有动力学函数都作用在mjData上。下面这段是加载和释放的标准骨架。#include mujoco/mujoco.h #include cstdio #include cstring int main() { char error[1000] ; // 1. 加载 MJCF 模型第二个参数是编译错误缓冲区 mjModel* m mj_loadXML(MODEL_DIR /arm.xml, nullptr, error, 1000); if (!m) { std::printf(load model failed: %s\n, error); return 1; } // 2. 按模型维度分配运行时数据 mjData* d mj_makeData(m); // ... 后续计算 ... mj_deleteData(d); mj_deleteModel(m); return 0; }mj_loadXML的第一个参数是文件路径这里用编译期宏拼出绝对路径第二个参数可以传虚拟文件系统回调最小工程传nullptr即可后两个参数是错误缓冲区和长度加载失败时error里会有具体行号和原因比只看空指针有用得多。mj_makeData按m-nq、m-nv、m-nu等维度一次性分配所有数组不需要手动管理。释放顺序必须先mj_deleteData再mj_deleteModel反过来会留下悬空引用这是血泪经验里最常见的一类崩溃。3.2 设置状态并调用前向动力学前向动力学回答的是“给定当前关节位置和速度加速度是多少”。调用前要把qpos、qvel填好mj_forward会顺带算出质量矩阵、偏置力、接触力等中间量。// 3. 设置初始状态nq 个位置nv 个速度 for (int i 0; i m-nq; i) d-qpos[i] 0.0; for (int i 0; i m-nv; i) d-qvel[i] 0.0; // 给第一个关节一个初始角度避免全零退化 if (m-nq 0) d-qpos[0] 0.3; // 4. 前向动力学填充 qacc、qfrc_bias 等 mj_forward(m, d); std::printf(nq%d nv%d nu%d\n, m-nq, m-nv, m-nu); for (int i 0; i m-nv; i) { std::printf(joint %d qpos%.4f qvel%.4f qacc%.4f\n, i, d-qpos[i], d-qvel[i], d-qacc[i]); }m-nq是位置自由度数量m-nv是速度自由度数量对普通转动关节两者相等但遇到四元数球关节时nq会比nv多所以循环边界要分开写不能图省事统一用nv。mj_forward不返回错误码它假定模型和数据已经合法调用后d-qacc就是当前状态下的加速度。如果模型里没有驱动、没有重力补偿qacc主要由重力和科氏力决定数值看起来“不直观”是正常的不是算错了。3.3 逆动力学与力矩校验逆动力学回答的是“要让系统产生指定加速度需要施加多大关节力矩”。它要求先给定qpos、qvel、qacc再调用mj_inverse结果落在d-qfrc_inverse。// 5. 指定一个目标加速度做逆动力学 for (int i 0; i m-nv; i) d-qacc[i] 0.0; if (m-nv 0) d-qacc[0] 1.0; // 第一个关节 1 rad/s^2 mj_inverse(m, d); for (int i 0; i m-nv; i) { std::printf(joint %d qfrc_inverse%.4f\n, i, d-qfrc_inverse[i]); }mj_inverse内部会重新计算偏置力和质量矩阵所以调用前不需要先跑mj_forward但qpos、qvel、qacc必须已经填好。qfrc_inverse的物理含义是“维持该加速度所需的广义力”包含重力、科氏力、惯性项。一个常用的自检方法是把mj_inverse得到的qfrc_inverse写回d-qfrc_applied再跑一次mj_forward看qacc是否回到设定值。这个闭环校验能快速发现状态没设对、模型缺惯性之类的问题比盯着数字猜靠谱。3.4 质量矩阵与偏置力的单独读取有时候不需要完整动力学只想拿质量矩阵做控制器设计。mj_fullM可以把稀疏的d-qM展开成稠密矩阵配合d-qfrc_bias就能拼出标准形式。#include vector // 6. 读取稠密质量矩阵 M 和偏置力 bias std::vectormjtNum M(m-nv * m-nv, 0.0); mj_fullM(m, M.data(), d-qM); for (int i 0; i m-nv; i) { for (int j 0; j m-nv; j) { std::printf(M[%d][%d]%.4f , i, j, M[i * m-nv j]); } std::printf(\n); } for (int i 0; i m-nv; i) { std::printf(bias[%d]%.4f\n, i, d-qfrc_bias[i]); }mj_fullM的第一个参数是模型第二个是输出缓冲区第三个是d-qM。缓冲区大小必须是nv * nv按行主序存放。d-qfrc_bias是重力、科氏力、离心力的合力满足M * qacc bias qfrc_applied qfrc_constraint这个关系。把这两个量单独拿出来做计算力矩控制或者线性化时就不用反复调mj_inverse省一次完整计算。注意qM是稀疏存储直接按数组下标读会读错必须走mj_fullM。4. 避坑与排查动力学数值不对时先看这几处4.1 现象qacc 全是零或全是 NaN原因通常有两个一是模型里没有给body配inertialMuJoCo 编译时会用几何体估算但如果geom也没配质量惯性就是零质量矩阵奇异二是qpos里用了四元数关节却按普通关节赋值导致归一化失败。解决方式是先检查 XML 里每个body是否有inertial或带mass的geom再确认nq与nv的差异球关节的qpos要写四元数且保证模长为 1。打印m-nq、m-nv是最快的定位手段。4.2 现象编译通过但链接报未定义符号原因多半是find_package找到的是头文件路径链接目标名写错或者系统里同时存在多个 MuJoCo 版本。解决方式是确认target_link_libraries用的是官方导出的MuJoCo::mujoco而不是手写-lmujoco再用cmake --build build --verbose看实际链接命令里库路径指向哪个版本。如果之前装过旧版本清掉build/重新配置避免 CMake 缓存里留着旧路径。4.3 现象程序启动就报 XML 解析错误原因通常是路径拼接问题。MODEL_DIR /arm.xml依赖编译期宏如果宏值末尾带斜杠或没带斜杠拼出来可能是双斜杠或粘连。解决方式是在 CMake 里统一不带尾斜杠代码里显式加/或者干脆用std::filesystem::path拼接。另一个常见原因是 XML 里引用了不存在的mesh文件错误信息会指出具体文件名按名字补文件或删掉对应geom即可。4.4 现象逆动力学结果和预期差一个数量级原因往往是单位或关节类型不一致。MJCF 默认长度单位是米、角度是弧度如果模型是从别处拷来的、按毫米建模力矩就会差几个数量级。解决方式是检查 XML 里compiler的angle属性degree还是radian以及几何尺寸统一到米和弧度。另一个容易忽略的点是d-qacc在调用mj_inverse前是否被mj_forward覆盖过如果先 forward 再改 qacc顺序反了就会用到旧值。4.5 现象换模型后程序崩溃在 mj_makeData 之后原因通常是模型维度和代码里硬编码的索引不匹配。比如代码里默认nv 2直接访问qpos[1]换成一个单关节模型就越界。解决方式是把所有对qpos、qvel、qacc的访问都包在i m-nv或i m-nq的循环里不在业务逻辑里写死关节数量。这个习惯在后续加控制器时尤其重要模型一换硬编码全废。5. 二次开发把最小工程扩成可复用的动力学工具5.1 抽出一个 Dynamics 封装类最小工程把所有逻辑塞在main里改起来快但复用差。我一般会先抽一个类把模型生命周期和状态设置收进去主程序只负责编排。class Dynamics { public: explicit Dynamics(const char* xmlPath) { char err[1000] ; model_ mj_loadXML(xmlPath, nullptr, err, 1000); if (!model_) throw std::runtime_error(err); data_ mj_makeData(model_); } ~Dynamics() { if (data_) mj_deleteData(data_); if (model_) mj_deleteModel(model_); } // 禁止拷贝避免双重释放 Dynamics(const Dynamics) delete; Dynamics operator(const Dynamics) delete; mjModel* model() { return model_; } mjData* data() { return data_; } void setState(const std::vectordouble qpos, const std::vectordouble qvel) { std::copy(qpos.begin(), qpos.end(), data_-qpos); std::copy(qvel.begin(), qvel.end(), data_-qvel); } std::vectordouble inverse(const std::vectordouble qacc) { std::copy(qacc.begin(), qacc.end(), data_-qacc); mj_inverse(model_, data_); return std::vectordouble(data_-qfrc_inverse, data_-qfrc_inverse model_-nv); } private: mjModel* model_ nullptr; mjData* data_ nullptr; };这个类的关键设计点有三个构造时加载、析构时释放配合删除拷贝构造杜绝双重释放setState和inverse用std::vector做边界调用方不用关心裸指针inverse返回新向量而不是暴露qfrc_inverse避免调用方在下次计算后被覆盖。参数上qpos长度必须是nqqvel和qacc长度必须是nv长度不符时std::copy会越界稳妥做法是在setState里加assert或抛异常。5.2 加一个简单的 PD 控制闭环有了封装类加控制就是几行。下面用计算力矩的简化形式先按目标位置算 PD 力矩再叠加逆动力学补偿。std::vectordouble pdControl(Dynamics dyn, const std::vectordouble qDes, double kp, double kd, double dt) { auto* m dyn.model(); auto* d dyn.data(); std::vectordouble tau(m-nv, 0.0); for (int i 0; i m-nv; i) { double err qDes[i] - d-qpos[i]; tau[i] kp * err - kd * d-qvel[i]; } // 用逆动力学补上重力与科氏力 for (int i 0; i m-nv; i) d-qacc[i] 0.0; mj_inverse(m, d); for (int i 0; i m-nv; i) tau[i] d-qfrc_inverse[i]; // 写回驱动力并前向积分 for (int i 0; i m-nv; i) d-qfrc_applied[i] tau[i]; mj_forward(m, d); for (int i 0; i m-nq; i) d-qpos[i] d-qvel[i] * dt; return tau; }kp、kd按关节惯量量级调先小后大dt建议从 0.001 起。这里把qfrc_inverse直接加到 PD 输出上相当于重力补偿能让稳态误差明显变小。注意mj_forward之后qacc已经被更新如果还要做下一步逆动力学得重新设qacc。这个闭环不是严格的时间步进真实仿真应该用mj_step但作为验证动力学调用是否正确足够直观。5.3 验证方法与改造清单改完之后怎么确认没改坏我习惯做三层验证第一层静态状态下mj_inverse得到的力矩与手算重力项对比单连杆模型可以笔算第二层把qfrc_inverse写回qfrc_applied再mj_forward看qacc是否回到设定值误差应在 1e-6 量级第三层跑 PD 闭环看关节是否收敛到目标且不发散。三层都过基本可以认为动力学链路是通的。改造方向改动点注意换模型替换model/arm.xml改MODEL_DIR或路径检查nq/nv是否变化加关节XML 加joint和body同步检查代码里是否有硬编码索引加接触XML 加geom的contype/conaffinity接触力在qfrc_constraint不在qfrc_inverse换积分器m-opt.integrator设为mjINT_RK4RK4 对dt更敏感先降步长5.4 一个容易忽略的细节mj_inverse和mj_forward都会改写mjData里的中间量包括qM、qfrc_bias、efc_*等。如果在一个循环里交替调用两者又依赖上一次的中间结果就会拿到被覆盖的值。我的做法是每次调用前明确自己需要哪些输入调用后立刻把需要的输出拷出来不跨调用共享mjData的中间数组。这个习惯是从一次“逆动力学结果偶尔跳变”的排查里换来的最后定位就是中间量被前一次 forward 覆盖。从那以后我每次在循环里调动力学函数都强制先把输入状态完整写一遍再调用不依赖残留值。希望这些拆解能帮你把这个最小工程跑起来并顺利改成自己需要的形状。本文还有配套的精品资源点击获取