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)

Integrator override

integrator accepts "Euler", "RK4", "implicit", "implicitfast", or "discrete". Omit it to keep the MJCF setting. discrete integrates stiffness and constraints implicitly; verify controller tuning and use a compatible solver (CG or Newton).