Loading Models

SceneConfig

Every simulation starts with a SceneConfig object that tells mujoco-react what to load and how to configure it:

import type { SceneConfig } from "mujoco-react";

const config: SceneConfig = {
  src: "https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/franka_emika_panda/",
  sceneFile: "scene.xml",
  homeJoints: [1.707, -1.754, 0.003, -2.702, 0.003, 0.951, 2.490],
};

Required Fields

Field	Type	Description
`src`	`string`	Base URL for model files (e.g. `'https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/franka_emika_panda/'`)
`sceneFile`	`string`	Entry MJCF file to load (e.g. `'scene.xml'`)

Optional Fields

Field	Type	Default	Description
`files`	`File[]`	—	Browser-selected local MJCF/URDF files and assets
`homeJoints`	`number[]`	—	Joint positions applied on reset
`sceneObjects`	`SceneObject[]`	—	Dynamic objects injected into scene
`xmlPatches`	`XmlPatch[]`	—	XML transformations before compilation
`onReset`	`({ model, data }) => void`	—	Custom logic run after each reset

Model Sources

DeepMind Menagerie

Models from MuJoCo Menagerie can be loaded by pointing src at the raw GitHub URL for the model directory:

// Loads from: raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/franka_emika_panda/scene.xml
const config: SceneConfig = {
  src: "https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/franka_emika_panda/",
  sceneFile: "scene.xml",
};

Available models include franka_emika_panda, universal_robots_ur5e, kuka_iiwa_14, robotiq_2f85, and many more.

Custom Server

Point src to any HTTP server hosting MJCF files:

const config: SceneConfig = {
  src: "https://my-server.com/models/my_robot/",
  sceneFile: "scene.xml",
};
// Fetches: https://my-server.com/models/my_robot/scene.xml

GitHub Repositories

Use raw GitHub URLs for models hosted in your own repos:

const config: SceneConfig = {
  src: "https://raw.githubusercontent.com/myorg/myrepo/main/my_robot/",
  sceneFile: "robot.xml",
};

Scene Objects

Inject dynamic objects (boxes, spheres, cylinders) into the scene without modifying MJCF files:

const config: SceneConfig = {
  src: "https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/franka_emika_panda/",
  sceneFile: "scene.xml",
  sceneObjects: [
    {
      name: "red_cube",
      type: "box",
      size: [0.025, 0.025, 0.025],
      position: [0.5, 0.0, 0.025],
      rgba: [1, 0, 0, 1],
      mass: 0.1,
      freejoint: true,
    },
    {
      name: "blue_sphere",
      type: "sphere",
      size: [0.02, 0, 0],
      position: [0.4, 0.1, 0.02],
      rgba: [0, 0, 1, 1],
      mass: 0.05,
      freejoint: true,
    },
  ],
};

SceneObject Fields

Field	Type	Default	Description
`name`	`string`	required	Unique body/geom name
`type`	`'box' \| 'sphere' \| 'cylinder'`	required	Geom type
`size`	`[number, number, number]`	required	Geom size (MuJoCo semantics)
`position`	`[number, number, number]`	required	Initial world position
`rgba`	`[number, number, number, number]`	required	Color (0-1 range)
`mass`	`number`	—	Body mass in kg
`freejoint`	`boolean`	—	Add a free joint (6-DOF)
`friction`	`string`	—	MuJoCo friction spec
`solref`	`string`	—	MuJoCo solver reference
`solimp`	`string`	—	MuJoCo solver impedance
`condim`	`number`	—	Contact dimensionality

Objects are injected into </worldbody> before the model is compiled.

XML Patching

For more advanced model customization, use xmlPatches to transform the MJCF XML before it reaches MuJoCo:

const config: SceneConfig = {
  src: "https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/franka_emika_panda/",
  sceneFile: "scene.xml",
  xmlPatches: [
    // Replace a value in the XML
    {
      target: "scene.xml",
      replace: ["timestep=\"0.002\"", "timestep=\"0.001\""],
    },
    // Inject XML after a specific tag
    {
      target: "scene.xml",
      inject: "<body name=\"table\" pos=\"0.5 0 0\"><geom type=\"box\" size=\"0.3 0.3 0.01\" rgba=\"0.6 0.4 0.2 1\"/></body>",
      injectAfter: "<worldbody>",
    },
  ],
};

XmlPatch Fields

Field	Type	Description
`target`	`string`	Filename to patch
`replace`	`[string, string]`	`[search, replacement]` string substitution
`inject`	`string`	XML string to inject
`injectAfter`	`string`	Insert `inject` after this string

Reset Callback

Run custom logic after each simulation reset (e.g., randomize object positions for domain randomization):

const config: SceneConfig = {
  src: "https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/franka_emika_panda/",
  sceneFile: "scene.xml",
  sceneObjects: [
    { name: "cube", type: "box", size: [0.025, 0.025, 0.025],
      position: [0.5, 0, 0.025], rgba: [1, 0, 0, 1],
      mass: 0.1, freejoint: true },
  ],
  onReset: ({ model, data }) => {
    // Randomize cube position on each reset
    const bodyId = 1; // or use findBodyByName
    const qposAdr = model.jnt_qposadr[0];
    data.qpos[qposAdr + 0] = 0.4 + Math.random() * 0.2; // x
    data.qpos[qposAdr + 1] = -0.1 + Math.random() * 0.2; // y
    data.qpos[qposAdr + 2] = 0.025; // z
  },
};

Runtime Scene Loading

Swap the entire model at runtime without remounting:

const { api } = useMujoco();

async function switchRobot() {
  await api.loadScene({
    src: "https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/universal_robots_ur5e/",
    sceneFile: "scene.xml",
  });
}

Getting Started

Guides

Components

Hooks

API Reference

More

SceneConfig

Required Fields

Optional Fields

Model Sources

DeepMind Menagerie

Custom Server

GitHub Repositories

Scene Objects

SceneObject Fields

XML Patching

XmlPatch Fields

Reset Callback

Runtime Scene Loading

​SceneConfig

​Required Fields

​Optional Fields

​Model Sources

​DeepMind Menagerie

​Custom Server

​GitHub Repositories

​Scene Objects

​SceneObject Fields

​XML Patching

​XmlPatch Fields

​Reset Callback

​Runtime Scene Loading

SceneConfig

Required Fields

Optional Fields

Model Sources

DeepMind Menagerie

Custom Server

GitHub Repositories

Scene Objects

SceneObject Fields

XML Patching

XmlPatch Fields

Reset Callback

Runtime Scene Loading