MujocoCanvas

R3F Canvas wrapper with physics simulation

A thin wrapper around React Three Fiber’s <Canvas> that sets up the physics simulation. Accepts all standard R3F Canvas props plus MuJoCo-specific configuration.

Usage

import { useRef } from "react";
import { MujocoProvider, MujocoCanvas } from "mujoco-react";
import type { MujocoSimAPI } from "mujoco-react";
import { OrbitControls } from "@react-three/drei";

function App() {
  const apiRef = useRef<MujocoSimAPI>(null);

  return (
    <MujocoProvider>
      <MujocoCanvas
        ref={apiRef}
        config={{
          src: "https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/franka_emika_panda/",
          sceneFile: "scene.xml",
        }}
        camera={{ position: [2, -1.5, 2.5], up: [0, 0, 1], fov: 45 }}
        shadows
        paused={false}
        speed={1.0}
        style={{ width: "100%", height: "100vh" }}
      >
        <OrbitControls makeDefault />
        <ambientLight intensity={0.7} />
      </MujocoCanvas>
    </MujocoProvider>
  );
}

Props

MuJoCo Props

config · SceneConfig · required

Scene configuration — robot ID, model file, joints, etc. See Loading Models.

onReady · ({ api }) => void

Fires when the model is loaded and simulation is ready. Receives the full API object.

onError · (error: Error) => void

Called if model loading or simulation fails.

onStep · ({ time, model, data }) => void

Called after each physics step with the current simulation time.

onSelection · ({ bodyId, name }) => void

Fired when a body is double-clicked in the scene.

Physics Props

paused · boolean · default: "false"

Pause/resume the simulation declaratively.

speed · number · default: "1.0"

Simulation speed multiplier. 0.5 = half speed, 2.0 = double speed.

gravity · [number, number, number]

Override gravity vector (m/s^2). Default: model’s gravity.

timestep · number

Override simulation timestep (seconds). Default: model’s timestep.

substeps · number

Number of physics substeps per frame for improved stability.

interpolate · boolean · default: "false"

Smooth rendered body poses between fixed physics steps. Useful for high-refresh displays.

renderOptions · MujocoRenderOptions

Optional render-time settings for generated MuJoCo geometry. Set renderOptions={{ meshNormalSmoothing: true }} to weld duplicate mesh vertices before recomputing normals, which smooths faceted STL visuals. Leave it unset when you need exact policy-render parity.

hiddenBodies · readonly string[]

Names of model bodies whose geometry should not be rendered. The bodies stay in the compiled model and keep simulating — only their meshes are skipped at scene-build time, so body, joint, and actuator indices are unchanged. The set is reapplied on every render rebuild, so toggling names can never be lost to a scene rebuild. Use it to show one arm of a bimanual model, hide fixtures, etc.

R3F Canvas Props

All standard @react-three/fiber Canvas props are passed through:

<MujocoCanvas
  camera={{ position: [2, 2, 2], fov: 45, up: [0, 0, 1] }}
  shadows
  dpr={[1, 2]}
  gl={{ antialias: true }}
  style={{ width: "100%", height: "100vh" }}
  className="my-canvas"
>

Ref

MujocoCanvas forwards its ref as a MujocoSimAPI handle — the same object passed to onReady:

const apiRef = useRef<MujocoSimAPI>(null);

<MujocoCanvas ref={apiRef} config={config}>
  {/* ... */}
</MujocoCanvas>

// Later: apiRef.current?.reset()

Notes

• Must be a child of <MujocoProvider>
• Children can use all mujoco-react hooks (useMujoco, useBeforePhysicsStep, etc.)
• The config prop is read on mount and when api.loadScene() is called — changing it after mount has no effect