Scene Management

Runtime model loading and scene configuration

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

loadFromFiles(files, options?)

Load MJCF or URDF from browser-selected files. Folder uploads preserve paths from webkitRelativePath; flat uploads fall back to matching mesh/texture assets by basename.

import { useEffect, useRef } from "react";
import { useMujoco } from "mujoco-react";

function ModelUpload() {
  const sim = useMujoco();
  const inputRef = useRef<HTMLInputElement>(null);

  useEffect(() => {
    inputRef.current?.setAttribute("webkitdirectory", "");
  }, []);

  return (
    <input
      ref={inputRef}
      type="file"
      multiple
      onChange={(event) => {
        if (sim.isReady && event.currentTarget.files) {
          sim.api.loadFromFiles(event.currentTarget.files);
        }
      }}
    />
  );
}

files · FileList | File[] · required

Browser-selected MJCF/URDF files and referenced assets.

options · LoadFromFilesOptions

Optional sceneFile, environmentFiles, homeJoints, xmlPatches, sceneObjects, and onReset settings.

Composable Environments

Use environmentFiles when a robot should run inside a reusable MJCF environment. The loader merges the environment XML’s assets and physics sections into the entry model before MuJoCo compiles it.

const config = {
  src: "/models/xlerobot/",
  sceneFile: "xlerobot.xml",
  environmentFiles: ["splats/tabletop/scene.xml"],
};

This works well with Gaussian splats: keep the .spz as a visual-only layer, and add a paired scene.xml collision/physics layer only when the splat-backed workflow needs contact geometry.

addBody(body), removeBody(name), recompile(patches?)

Edit the current scene configuration and recompile through MuJoCo. This is a model reload, not an in-place mutation of compiled mjModel memory.

await api.addBody({
  name: "spawned_cube",
  type: "box",
  size: [0.03, 0.03, 0.03],
  position: [0.4, 0, 0.1],
  rgba: [1, 0, 0, 1],
  mass: 0.1,
  freejoint: true,
});

await api.removeBody("spawned_cube");

await api.recompile([
  {
    target: "scene.xml",
    replace: ['timestep="0.002"', 'timestep="0.001"'],
  },
]);

Example: Model Switcher

function ModelSelector() {
  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 }