MujocoPhysics

Physics provider for use inside your own R3F Canvas

Physics context provider for use inside your own React Three Fiber <Canvas>. Same physics configuration as <MujocoCanvas>, but without the Canvas wrapper. Use this when you need control over gl settings, post-processing, or R3F context composition.

Usage

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

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

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

When to Use

Use <MujocoPhysics> instead of <MujocoCanvas> when you need:

• Custom gl settings (antialias, toneMapping, outputColorSpace)
• Post-processing pipelines (EffectComposer, bloom, SSAO)
• Multiple physics contexts in one Canvas
• Full control over the R3F <Canvas> props
• Components outside the physics context but inside the Canvas (e.g., background effects)

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.

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.

Ref

MujocoPhysics forwards its ref as a MujocoSimAPI handle (the same object passed to onReady):

const apiRef = useRef<MujocoSimAPI>(null);

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

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

Notes

• Must be a child of <MujocoProvider> and inside an R3F <Canvas>
• Children can use all mujoco-react hooks (useMujoco, useBeforePhysicsStep, etc.)
• Components placed outside <MujocoPhysics> but inside <Canvas> won’t have access to physics hooks
• Renders nothing while WASM is loading or if loading fails (call onError to handle failures)