> ## Documentation Index
> Fetch the complete documentation index at: https://dadd.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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>`](/components/mujoco-canvas), but without the Canvas wrapper. Use this when you need control over gl settings, post-processing, or R3F context composition.

## Usage

```tsx theme={null}
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

<ParamField body="config" type="SceneConfig" required>
  Scene configuration: robot ID, model file, joints, etc. See [Loading Models](/loading-models).
</ParamField>

<ParamField body="onReady" type="({ api }) => void">
  Fires when the model is loaded and simulation is ready. Receives the full API object.
</ParamField>

<ParamField body="onError" type="(error: Error) => void">
  Called if model loading or simulation fails.
</ParamField>

<ParamField body="onStep" type="({ time, model, data }) => void">
  Called after each physics step with the current simulation time.
</ParamField>

<ParamField body="onSelection" type="({ bodyId, name }) => void">
  Fired when a body is double-clicked in the scene.
</ParamField>

<ParamField body="paused" type="boolean" default="false">
  Pause/resume the simulation declaratively.
</ParamField>

<ParamField body="speed" type="number" default="1.0">
  Simulation speed multiplier. `0.5` = half speed, `2.0` = double speed.
</ParamField>

<ParamField body="gravity" type="[number, number, number]">
  Override gravity vector (m/s^2). Default: model's gravity.
</ParamField>

<ParamField body="timestep" type="number">
  Override simulation timestep (seconds). Default: model's timestep.
</ParamField>

<ParamField body="substeps" type="number">
  Number of physics substeps per frame for improved stability.
</ParamField>

<ParamField body="interpolate" type="boolean" default="false">
  Smooth rendered body poses between fixed physics steps. Useful for high-refresh displays.
</ParamField>

## Ref

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

```tsx theme={null}
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)