mujoco: Initial implementation

[azeey]

🎉 New feature

Toward #299

Summary

Initial implementation of the Mujoco plugin targetting Mujoco 3.5. Enough of the features are implemented to enable testing with gz-sim

gz sim  -v4  rolling_shapes.sdf --physics-engine gz-physics-mujoco-plugin 

Screen.Recording.2025-11-20.at.23.09.28.mov

Missing features are listed in #299 (comment)

Note: This builds mujoco from source using CMake's ExternalProject_Add. This is a temporary solution until we have Mujoco available from upstream binary sources.

Checklist

• Signed all commits for DCO
• Added a screen capture or video to the PR description that demonstrates the feature
• Added tests
• Added example and/or tutorial
• Updated documentation (as needed)
• Updated migration guide (as needed)
• Consider updating Python bindings (if the library has them)
• codecheck passed (See contributing)
• All tests passed (See test coverage)
• Updated Bazel files (if adding new files). Created an issue otherwise.
• While waiting for a review on your PR, please help review another open pull request to support the maintainers
• Was GenAI used to generate this PR? If so, make sure to add "Generated-by" to your commits. (See this policy for more info.)

Generated-By: Gemini 3.0

Note to maintainers: Remember to use Squash-Merge and edit the commit message to match the pull request summary while retaining Signed-off-by and Generated-by messages.

Backports: If this is a backport, please use Rebase and Merge instead.

[IceShuttle]

Following the current instructions the gz-physics build failed as it cannot find tests so now it checks for them before adding them as a dependency. I have opened up a pr here

[cmeng-gao]

Hi, I'm excited to see the progress on MuJoCo integration! MuJoCo is widely used in the reinforcement learning community, and having it as a physics backend in Gazebo would be a great addition.

I'd like to contribute to this effort. Before jumping in, I wanted to ask: what are the current blockers or challenges? Are there specific features that need help with implementation, or any known
issues that are difficult to resolve?

I've reviewed the current prototype branch and noticed that Joint, Link, and Shape features are still pending. Is this the priority area, or are there other aspects that need attention first?

Looking forward to hearing from the maintainers and contributors!

[EmmanuelMess]

I am getting a crash from MuJoCo, when it tries to save an XML:

QStandardPaths: XDG_RUNTIME_DIR not set, defaulting to '/tmp/runtime-root'
amdgpu: os_same_file_description couldn't determine if two DRM fds reference the same file description.
If they do, bad things may happen!
Model: ground_plane constructed in 0.00132365
Model: box constructed in 0.000108937
Model: cylinder constructed in 3.9465e-05
Model: sphere constructed in 3.5708e-05
Model: capsule constructed in 3.9124e-05
Model: ellipsoid constructed in 3.8222e-05
Stack trace (most recent call last) in thread 1357:
#23   Object "", at 0xffffffffffffffff, in 
#22   Source "../sysdeps/unix/sysv/linux/x86_64/clone.S", line 100, in clone [0x7e9b38d29a63]
#21   Source "./nptl/pthread_create.c", line 447, in start_thread [0x7e9b38c9caa3]
#20   Object "/usr/lib/x86_64-linux-gnu/libstdc++.so.6.0.33", at 0x7e9b38f2cdb3, in 
#19   Object "/opt/ros/rolling/opt/gz_sim_vendor/lib/libgz-sim.so.10.0.0", at 0x7e9b3a0b677c, in 
#18   Object "/opt/ros/rolling/opt/gz_sim_vendor/lib/libgz-sim.so.10.0.0", at 0x7e9b3a0c3266, in gz::sim::v10::SimulationRunner::Run(unsigned long)
#17   Object "/opt/ros/rolling/opt/gz_sim_vendor/lib/libgz-sim.so.10.0.0", at 0x7e9b3a0c28be, in gz::sim::v10::SimulationRunner::Step(gz::sim::v10::UpdateInfo const&)
#16   Object "/opt/ros/rolling/opt/gz_sim_vendor/lib/libgz-sim.so.10.0.0", at 0x7e9b3a0bf09d, in gz::sim::v10::SimulationRunner::UpdateSystems()
#15   Object "/opt/ros/rolling/opt/gz_sim_vendor/lib/gz-sim-10/plugins/libgz-sim-physics-system.so.10.0.0", at 0x7e9b2c3f132e, in 
#14   Object "/opt/ros/rolling/opt/gz_sim_vendor/lib/gz-sim-10/plugins/libgz-sim-physics-system.so.10.0.0", at 0x7e9b2c3fd5d3, in 
#13   Object "/opt/ros/rolling/opt/gz_sim_vendor/lib/gz-sim-10/plugins/libgz-sim-physics-system.so.10.0.0", at 0x7e9b2c408cc0, in 
#12   Object "/opt/ros/rolling/opt/gz_sim_vendor/lib/gz-sim-10/plugins/libgz-sim-physics-system.so.10.0.0", at 0x7e9b2c46ae1c, in 
#11   Object "/opt/ros/rolling/opt/gz_sim_vendor/lib/gz-sim-10/plugins/libgz-sim-physics-system.so.10.0.0", at 0x7e9b2c407a2e, in 
#10   Source "/root/gz-physics/mujoco/src/KinematicsFeatures.cc", line 36, in FrameDataRelativeToWorld [0x7e9afb122147]
         33:   if (linkInfo)
         34:   {
         35:     auto worldInfo = linkInfo->modelInfo.lock()->worldInfo.lock();
      >  36:     this->RecompileSpec(*worldInfo);
         37:     mjData *d = worldInfo->mjDataObj;
         38: 
         39:     auto bodyId = mjs_getId(linkInfo->body->element);
#9    Source "/root/gz-physics/mujoco/src/Base.cc", line 46, in RecompileSpec [0x7e9afb11c403]
         43:     gzerr << "Error compiling:" << mjs_getError(_worldInfo.mjSpecObj) << "\n";
         44:     return false;
         45:   }
      >  46:   mj_saveXML(_worldInfo.mjSpecObj, "/tmp/mujoco_model.xml", nullptr, 0);
         47: 
         48:   mj_forward(_worldInfo.mjModelObj, _worldInfo.mjDataObj);
         49:   return true;
#8    Object "/usr/local/lib/libmujoco.so.3.4.0", at 0x7e9afaeafa20, in mj_saveXML
#7    Object "/usr/local/lib/libmujoco.so.3.4.0", at 0x7e9afaeaf8f7, in WriteXML[abi:cxx11](mjModel_ const*, mjSpec_*, char*, int)
#6    Object "/usr/local/lib/libmujoco.so.3.4.0", at 0x7e9afaed7692, in mjXWriter::Write[abi:cxx11](char*, unsigned long)
#5    Object "/usr/local/lib/libmujoco.so.3.4.0", at 0x7e9afaecbd18, in WriteDoc(tinyxml2::XMLDocument&, char*, unsigned long) [clone .lto_priv.0]
#4    Object "/usr/lib/x86_64-linux-gnu/libtinyxml2.so.10.0.0", at 0x7e9b37017564, in tinyxml2::XMLDocument::Accept(tinyxml2::XMLVisitor*) const
#3    Object "/usr/lib/x86_64-linux-gnu/libtinyxml2.so.10.0.0", at 0x7e9b37017616, in tinyxml2::XMLElement::Accept(tinyxml2::XMLVisitor*) const
#2    Object "/usr/lib/x86_64-linux-gnu/libtinyxml2.so.10.0.0", at 0x7e9b3701d9ae, in tinyxml2::XMLPrinter::VisitEnter(tinyxml2::XMLElement const&, tinyxml2::XMLAttribute const*)
#1    Object "/usr/lib/x86_64-linux-gnu/libtinyxml2.so.10.0.0", at 0x7e9b3701d8a3, in tinyxml2::XMLPrinter::OpenElement(char const*, bool)
#0    Source "./libio/iofwrite.c", line 37, in _IO_fwrite [0x7e9b38c86971]
Segmentation fault (Address not mapped to object [0x1])
Segmentation fault (core dumped)

Removing the mj_saveXML(_worldInfo.mjSpecObj, "/tmp/mujoco_model.xml", nullptr, 0); line fixes it.

[EmmanuelMess]

Just as an FYI: a873414 fixes the Ubuntu CI / Ubuntu Noble CI (pull_request) failure

[IceShuttle]

Following the current instructions the gz-physics build failed as it cannot find tests so now it checks for them before adding them as a dependency. I have opened up a pr here

Hi I just today realized that the link I mentioned was broken I have fixed it now

[iche033]

There was an issue with the use of FetchContent which caused targets and cmake flags from mujoco and its dependencies to leak into gz-physics targets. For example, the tinyxml2 static library was being linked against the dartsim plugin. I've changed it to use ExternalProject_Add in d7e5de5, which is similar to compiling mujoco externally. I now have all (unskipped) tests passing on Linux and macOS.

confirmed that this fixes the tinyxml2 symbol issue for me.

[iche033]

Looks good to me. Let's get this in. We can follow up with fixes in other PRs.

Feedback addressed