Skip to main content
Methods for loading and swapping models at runtime.

​
loadScene(newConfig)

Load a new model, replacing the current scene entirely. 
await api.loadScene({
  src: "https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/universal_robots_ur5e/",
  sceneFile: "scene.xml",
  numArmJoints: 6,
  tcpSiteName: "tcp",
});
​
newConfig
SceneConfig
required
New scene configuration. See Loading Models for all fields.
Returns: Promise<void> — resolves when the new model is loaded and ready. This method:
  1. Fetches the new model files
  2. Applies XML patches and injects scene objects
  3. Compiles the model with mj_loadXML
  4. Creates new model/data objects
  5. Rebuilds the scene graph (SceneRenderer will re-render)
  6. Fires the onReady callback with the updated API

​
Example: Robot Switcher

function RobotSelector() {
  const { api } = useMujoco();
  const [loading, setLoading] = useState(false);

  const robots = [
    { src: "https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/franka_emika_panda/", label: "Franka Panda", joints: 7 },
    { src: "https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/universal_robots_ur5e/", label: "UR5e", joints: 6 },
    { src: "https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/kuka_iiwa_14/", label: "KUKA iiwa", joints: 7 },
  ];

  async function switchRobot(robot: typeof robots[0]) {
    setLoading(true);
    await api.loadScene({
      src: robot.src,
      sceneFile: "scene.xml",
      numArmJoints: robot.joints,
      tcpSiteName: "tcp",
    });
    setLoading(false);
  }

  return (
    <div>
      {robots.map(r => (
        <button key={r.label} onClick={() => switchRobot(r)} disabled={loading}>
          {r.label}
        </button>
      ))}
      {loading && <span>Loading...</span>}
    </div>
  );
}

​
Utility Functions

These standalone functions are exported for advanced use cases (e.g., building custom loaders).

​
getName(model, address)

Read a null-terminated C string from the WASM model’s name buffer. 
import { getName } from "mujoco-react";
const bodyName = getName(model, model.name_bodyadr[bodyId]);

​
find*ByName(model, name)

Look up element indices by name. All return -1 if not found. 
import {
  findBodyByName,
  findJointByName,
  findGeomByName,
  findSiteByName,
  findActuatorByName,
  findSensorByName,
  findTendonByName,
  findKeyframeByName,
} from "mujoco-react";

const bodyId = findBodyByName(model, "gripper");
const jointId = findJointByName(model, "joint1");
const siteId = findSiteByName(model, "tcp");
const actuatorId = findActuatorByName(model, "gripper");

​
loadScene(mujoco, config, onProgress?)

The standalone scene loader function (used internally by the provider). 
import { loadScene } from "mujoco-react";

const result = await loadScene(mujoco, config, (msg) => {
  console.log("Loading:", msg);
});
// result: { mjModel, mjData, siteId, gripperId }