How google-deepmind/mujoco works
Purpose and primary entry points
MuJoCo is a high-performance articulated-body physics engine with contact simulation. Its core product is a native C/C++ library exposing a C API, compiled models, preallocated runtime state, visualization, and utilities. Public API/data contracts are in include/mujoco/mujoco.h, include/mujoco/mjmodel.h, and include/mujoco/mjdata.h. Native interactive execution starts at simulate/main.cc; basic embedding examples start at sample/basic.cc.
Build and package boundary
Top-level CMake assembles the native library, optional renderers, apps, plugins, tests, and bindings: CMakeLists.txt, src/engine/CMakeLists.txt, python/mujoco/CMakeLists.txt. Dependency acquisition/configuration is centralized under cmake/MujocoDependencies.cmake and cmake/third_party_deps/; important external graphics/UI dependencies include OpenGL/GLAD, GLFW/SDL2, Dear ImGui, and Filament. The project targets native desktop platforms and WebAssembly (wasm/CMakeLists.txt).
Model ingestion and compilation
The user-facing model layer converts MJCF/XML (and supported URDF/assets) into the fixed-layout mjModel consumed by simulation. XML parsing, schema-driven reading/writing, and URDF handling live in src/xml/xml.cc, src/xml/xml_native_reader.cc, and src/xml/xml_urdf.cc. Model construction, asset/resource resolution, meshes, composites, flex structures, and virtual filesystems are handled in src/user/user_model.cc, src/user/user_resource.cc, and src/user/user_vfs.cc. This is the major boundary between mutable source descriptions/resources and compiled simulation data.
Physics runtime pipeline
The engine advances mjData against immutable mjModel, with low-level memory and callback/plugin integration supporting the runtime. Initialization and orchestration are in src/engine/engine_init.c and src/engine/engine_forward.c. A typical step flows through kinematics/smooth dynamics and passive forces (src/engine/engine_core_smooth.c, src/engine/engine_passive.c), collision detection (src/engine/engine_collision_driver.c, src/engine/engine_collision_convex.c), constraint assembly (src/engine/engine_core_constraint.c), and numerical solving (src/engine/engine_solver.c). Sensors, inverse dynamics, derivatives, ray queries, sleeping, and islands are adjacent runtime stages.
Visualization and interactive applications
Visualization derives renderable scene data from model/runtime state, then dispatches to interchangeable rendering backends. Engine visualization preparation is in src/engine/engine_vis_visualize.c; classic OpenGL is in src/render/classic/render_context.c; the newer Filament backend is rooted at src/render/filament/mjrfilament.cc. The simulate desktop GUI coordinates GLFW/platform UI, simulation, and rendering through simulate/simulate.cc and simulate/glfw_adapter.cc. Experimental Studio is a separate richer native/web-oriented application stack: src/experimental/studio/main.cc, src/experimental/studio/app.cc, src/experimental/studio/sim/model_holder.cc.
Extension and ecosystem surfaces
Plugins extend engine behavior and asset decoding through the public plugin API in include/mujoco/mjplugin.h and runtime dispatch in src/engine/engine_plugin.cc; reference implementations reside in plugin/actuator/register.cc and plugin/sdf/register.cc. Python bindings wrap the native library via compiled extensions and Python APIs (python/mujoco/__init__.py, python/mujoco/functions.cc, python/mujoco/renderer.py). MJX is a separate JAX-oriented physics implementation with its own forward/collision/solver path (mjx/mujoco/mjx/_src/forward.py, mjx/mujoco/mjx/_src/collision_driver.py, mjx/mujoco/mjx/_src/solver.py). WebAssembly bindings/demo are generated and exposed from wasm/codegen/generated/bindings.cc and wasm/demo_app/app.ts; Unity consumes C# bindings/components under unity/Runtime/Bindings/MjBindings.cs and unity/Runtime/Components/MjScene.cs.
Main entry points: mujoco.h C API & data contracts · mjmodel.h Compiled mjModel · engine_forward.c Step orchestration · mjdata.h mjData runtime state
Components 21
Build & targets
- CMake build · Assembles native library, optional targets, and bindings.
CMakeLists.txt - Dependencies
cmake/MujocoDependencies.cmake - WebAssembly target
wasm/CMakeLists.txt
Model compilation
- C API & data contracts · Defines mjModel, mjData, and the native API.
include/mujoco/mujoco.h - XML & URDF ingestion
src/xml/xml.cc - Model compiler & assets · Converts mutable descriptions and resources into fixed-layout mjModel.
src/user/user_model.cc - Compiled mjModel
include/mujoco/mjmodel.h
Native simulation runtime
- Step orchestration · Advances mutable mjData against mjModel.
src/engine/engine_forward.c - mjData runtime state
include/mujoco/mjdata.h - Smooth dynamics
src/engine/engine_core_smooth.c - Collision detection
src/engine/engine_collision_driver.c - Constraint assembly
src/engine/engine_core_constraint.c - Numerical solver
src/engine/engine_solver.c
Visualization & apps
- Scene visualization · Derives renderable scene data from model and runtime state.
src/engine/engine_vis_visualize.c - Rendering backends
src/render/classic/render_context.c - simulate GUI
simulate/simulate.cc
Bindings & extensions
- Plugin dispatch
src/engine/engine_plugin.cc - Python bindings
python/mujoco/functions.cc - MJX · Separate JAX-oriented forward, collision, and solver implementation.
mjx/mujoco/mjx/_src/forward.py - WASM bindings & demo
wasm/codegen/generated/bindings.cc - Unity integration
unity/Runtime/Bindings/MjBindings.cs
Connections 25
- Dependencies → CMake build: configures
- CMake build → C API & data contracts: builds library
- CMake build → WebAssembly target: includes
- XML & URDF ingestion → Model compiler & assets: source descriptions
- Model compiler & assets → Compiled mjModel: compiles
- C API & data contracts → Compiled mjModel: declares
- C API & data contracts → mjData runtime state: declares
- Compiled mjModel → Step orchestration: immutable input
- mjData runtime state → Step orchestration: mutable input/output
- Step orchestration → Smooth dynamics: forward stage
- Smooth dynamics → Collision detection: geometry state
- Collision detection → Constraint assembly: contacts
- Constraint assembly → Numerical solver: assembled system
- Numerical solver → mjData runtime state: updates
- Plugin dispatch → Step orchestration: extends callbacks
- Compiled mjModel → Scene visualization: scene input
- mjData runtime state → Scene visualization: scene state
- Scene visualization → Rendering backends: renderable scene
- simulate GUI → Step orchestration: drives stepping
- simulate GUI → Rendering backends: presents
- Python bindings → C API & data contracts: wraps
- WebAssembly target → WASM bindings & demo: produces
- WASM bindings & demo → C API & data contracts: binds
- Unity integration → C API & data contracts: binds
- MJX → Compiled mjModel: uses model semantics