# google-deepmind/mujoco architecture

> Architecture diagram of the GitHub repository google-deepmind/mujoco, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/google-deepmind/mujoco
- Repository: https://github.com/google-deepmind/mujoco

## Overview

#### 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: [`include/mujoco/mujoco.h`](https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mujoco.h) (C API & data contracts), [`include/mujoco/mjmodel.h`](https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjmodel.h) (Compiled mjModel), [`src/engine/engine_forward.c`](https://github.com/google-deepmind/mujoco/blob/main/src/engine/engine_forward.c) (Step orchestration), [`include/mujoco/mjdata.h`](https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjdata.h) (mjData runtime state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build &amp; targets"]
  node_cmake["CMake build<br/>build system<br/>[CMakeLists.txt]"]
  node_deps["Dependencies<br/>dependency setup"]
  node_wasm_build["WebAssembly target<br/>build target<br/>[CMakeLists.txt]"]
end

subgraph group_model["Model compilation"]
  node_public_api["C API &amp; data contracts<br/>public headers<br/>[mujoco.h]"]
  node_xml["XML &amp; URDF ingestion<br/>model parser<br/>[xml.cc]"]
  node_model_builder["Model compiler &amp; assets<br/>[user_model.cc]"]
  node_model[("Compiled mjModel<br/>immutable model<br/>[mjmodel.h]")]
end

subgraph group_runtime["Native simulation runtime"]
  node_runtime["Step orchestration<br/>simulation pipeline<br/>[engine_forward.c]"]
  node_state[("mjData runtime state<br/>preallocated state<br/>[mjdata.h]")]
  node_smooth["Smooth dynamics<br/>kinematics &amp; forces"]
  node_collision["Collision detection<br/>contact generation"]
  node_constraints["Constraint assembly<br/>constraint pipeline"]
  node_solver["Numerical solver<br/>constraint solver<br/>[engine_solver.c]"]
end

subgraph group_visual["Visualization &amp; apps"]
  node_visualize["Scene visualization<br/>scene preparation"]
  node_renderers["Rendering backends<br/>OpenGL / Filament<br/>[render_context.c]"]
  node_simulate["simulate GUI<br/>native desktop app<br/>[simulate.cc]"]
end

subgraph group_ecosystem["Bindings &amp; extensions"]
  node_plugins["Plugin dispatch<br/>extension runtime<br/>[engine_plugin.cc]"]
  node_python["Python bindings<br/>native Python API<br/>[functions.cc]"]
  node_mjx["MJX<br/>JAX physics runtime<br/>[forward.py]"]
  node_wasm["WASM bindings &amp; demo<br/>web integration<br/>[bindings.cc]"]
  node_unity["Unity integration<br/>C&#35; bindings<br/>[MjBindings.cs]"]
end

node_deps -->|"configures"| node_cmake
node_cmake -->|"builds library"| node_public_api
node_cmake -->|"includes"| node_wasm_build
node_xml -->|"source descriptions"| node_model_builder
node_model_builder -->|"compiles"| node_model
node_public_api -.->|"declares"| node_model
node_public_api -.->|"declares"| node_state
node_model -->|"immutable input"| node_runtime
node_state -->|"mutable input/output"| node_runtime
node_runtime -->|"forward stage"| node_smooth
node_smooth -->|"geometry state"| node_collision
node_collision -->|"contacts"| node_constraints
node_constraints -->|"assembled system"| node_solver
node_solver -->|"updates"| node_state
node_plugins -.->|"extends callbacks"| node_runtime
node_model -->|"scene input"| node_visualize
node_state -->|"scene state"| node_visualize
node_visualize -->|"renderable scene"| node_renderers
node_simulate -->|"drives stepping"| node_runtime
node_simulate -->|"presents"| node_renderers
node_python -->|"wraps"| node_public_api
node_wasm_build -->|"produces"| node_wasm
node_wasm -->|"binds"| node_public_api
node_unity -->|"binds"| node_public_api
node_mjx -.->|"uses model semantics"| node_model

click node_cmake "https://github.com/google-deepmind/mujoco/blob/main/CMakeLists.txt"
click node_deps "https://github.com/google-deepmind/mujoco/blob/main/cmake/MujocoDependencies.cmake"
click node_wasm_build "https://github.com/google-deepmind/mujoco/blob/main/wasm/CMakeLists.txt"
click node_public_api "https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mujoco.h"
click node_xml "https://github.com/google-deepmind/mujoco/blob/main/src/xml/xml.cc"
click node_model_builder "https://github.com/google-deepmind/mujoco/blob/main/src/user/user_model.cc"
click node_model "https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjmodel.h"
click node_runtime "https://github.com/google-deepmind/mujoco/blob/main/src/engine/engine_forward.c"
click node_state "https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjdata.h"
click node_smooth "https://github.com/google-deepmind/mujoco/blob/main/src/engine/engine_core_smooth.c"
click node_collision "https://github.com/google-deepmind/mujoco/blob/main/src/engine/engine_collision_driver.c"
click node_constraints "https://github.com/google-deepmind/mujoco/blob/main/src/engine/engine_core_constraint.c"
click node_solver "https://github.com/google-deepmind/mujoco/blob/main/src/engine/engine_solver.c"
click node_plugins "https://github.com/google-deepmind/mujoco/blob/main/src/engine/engine_plugin.cc"
click node_visualize "https://github.com/google-deepmind/mujoco/blob/main/src/engine/engine_vis_visualize.c"
click node_renderers "https://github.com/google-deepmind/mujoco/blob/main/src/render/classic/render_context.c"
click node_simulate "https://github.com/google-deepmind/mujoco/blob/main/simulate/simulate.cc"
click node_python "https://github.com/google-deepmind/mujoco/blob/main/python/mujoco/functions.cc"
click node_mjx "https://github.com/google-deepmind/mujoco/blob/main/mjx/mujoco/mjx/_src/forward.py"
click node_wasm "https://github.com/google-deepmind/mujoco/blob/main/wasm/codegen/generated/bindings.cc"
click node_unity "https://github.com/google-deepmind/mujoco/blob/main/unity/Runtime/Bindings/MjBindings.cs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cmake,node_deps,node_wasm_build toneBlue
class node_public_api,node_xml,node_model_builder,node_model toneAmber
class node_runtime,node_state,node_smooth,node_collision,node_constraints,node_solver toneMint
class node_visualize,node_renderers,node_simulate toneRose
class node_plugins,node_python,node_mjx,node_wasm,node_unity toneIndigo
```

## Components

### Build & targets

- [CMake build](https://github.com/google-deepmind/mujoco/blob/main/CMakeLists.txt): build system · Assembles native library, optional targets, and bindings. · `CMakeLists.txt`
- [Dependencies](https://github.com/google-deepmind/mujoco/blob/main/cmake/MujocoDependencies.cmake): dependency setup · `cmake/MujocoDependencies.cmake`
- [WebAssembly target](https://github.com/google-deepmind/mujoco/blob/main/wasm/CMakeLists.txt): build target · `wasm/CMakeLists.txt`

### Model compilation

- [C API & data contracts](https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mujoco.h): public headers · Defines mjModel, mjData, and the native API. · `include/mujoco/mujoco.h`
- [XML & URDF ingestion](https://github.com/google-deepmind/mujoco/blob/main/src/xml/xml.cc): model parser · `src/xml/xml.cc`
- [Model compiler & assets](https://github.com/google-deepmind/mujoco/blob/main/src/user/user_model.cc): model compiler · Converts mutable descriptions and resources into fixed-layout mjModel. · `src/user/user_model.cc`
- [Compiled mjModel](https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjmodel.h): immutable model · `include/mujoco/mjmodel.h`

### Native simulation runtime

- [Step orchestration](https://github.com/google-deepmind/mujoco/blob/main/src/engine/engine_forward.c): simulation pipeline · Advances mutable mjData against mjModel. · `src/engine/engine_forward.c`
- [mjData runtime state](https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjdata.h): preallocated state · `include/mujoco/mjdata.h`
- [Smooth dynamics](https://github.com/google-deepmind/mujoco/blob/main/src/engine/engine_core_smooth.c): kinematics & forces · `src/engine/engine_core_smooth.c`
- [Collision detection](https://github.com/google-deepmind/mujoco/blob/main/src/engine/engine_collision_driver.c): contact generation · `src/engine/engine_collision_driver.c`
- [Constraint assembly](https://github.com/google-deepmind/mujoco/blob/main/src/engine/engine_core_constraint.c): constraint pipeline · `src/engine/engine_core_constraint.c`
- [Numerical solver](https://github.com/google-deepmind/mujoco/blob/main/src/engine/engine_solver.c): constraint solver · `src/engine/engine_solver.c`

### Visualization & apps

- [Scene visualization](https://github.com/google-deepmind/mujoco/blob/main/src/engine/engine_vis_visualize.c): scene preparation · Derives renderable scene data from model and runtime state. · `src/engine/engine_vis_visualize.c`
- [Rendering backends](https://github.com/google-deepmind/mujoco/blob/main/src/render/classic/render_context.c): OpenGL / Filament · `src/render/classic/render_context.c`
- [simulate GUI](https://github.com/google-deepmind/mujoco/blob/main/simulate/simulate.cc): native desktop app · `simulate/simulate.cc`

### Bindings & extensions

- [Plugin dispatch](https://github.com/google-deepmind/mujoco/blob/main/src/engine/engine_plugin.cc): extension runtime · `src/engine/engine_plugin.cc`
- [Python bindings](https://github.com/google-deepmind/mujoco/blob/main/python/mujoco/functions.cc): native Python API · `python/mujoco/functions.cc`
- [MJX](https://github.com/google-deepmind/mujoco/blob/main/mjx/mujoco/mjx/_src/forward.py): JAX physics runtime · Separate JAX-oriented forward, collision, and solver implementation. · `mjx/mujoco/mjx/_src/forward.py`
- [WASM bindings & demo](https://github.com/google-deepmind/mujoco/blob/main/wasm/codegen/generated/bindings.cc): web integration · `wasm/codegen/generated/bindings.cc`
- [Unity integration](https://github.com/google-deepmind/mujoco/blob/main/unity/Runtime/Bindings/MjBindings.cs): C# bindings · `unity/Runtime/Bindings/MjBindings.cs`

## Connections

- 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
