mujoco-react 1.0.0 → 2.0.0

package/README.md

@@ -1,7 +1,12 @@
+<p align="center">
+  <img src="docs/images/mj2.gif" alt="mujoco-react demo" width="100%" />
+</p>
+
 # mujoco-react
 
-A thin, unopinionated wrapper around [mujoco-js](https://github.com/nicepkg/mujoco-js) — composable and extensible via React. Built on [React Three Fiber](https://docs.pmnd.rs/react-three-fiber). Works with **any robot, any scene**.
+Composable [React Three Fiber](https://docs.pmnd.rs/react-three-fiber) wrapper around [mujoco-js](https://www.npmjs.com/package/mujoco-js). Load any MuJoCo model, step physics, render bodies, and write controllers as React components.
 
+**[Live Demo](https://mujoco-react-example.pages.dev)** | **[Docs](https://dadd.mintlify.app)** | **[Example Source](https://github.com/noah-wardlow/mujoco-react-example)**
 
 ## Install
 
@@ -15,7 +20,6 @@ npm install mujoco-react three @react-three/fiber @react-three/drei
 import {
   MujocoProvider,
   MujocoCanvas,
-  SceneRenderer,
   IkController,
   IkGizmo,
 } from 'mujoco-react';
@@ -41,7 +45,6 @@ function App() {
         style={{ width: '100%', height: '100vh' }}
       >
         <OrbitControls enableDamping makeDefault />
-        <SceneRenderer />
         <IkController config={{ siteName: 'tcp', numJoints: 7 }}>
           <IkGizmo />
         </IkController>
@@ -53,49 +56,28 @@ function App() {
 }
 ```
 
-## Architecture
-
-Two ways to set up your scene:
-
-### `<MujocoCanvas>` — Quick Start
+## Direct WASM Access
 
-Wraps R3F `<Canvas>` for you. Fastest path to a working scene:
-
-```
-<MujocoProvider>              <- WASM module lifecycle
-  <MujocoCanvas config={...}> <- R3F Canvas + physics context
-    <SceneRenderer />          <- Syncs MuJoCo bodies to Three.js meshes
-    <IkController config={..}> <- Opt-in controller plugin
-      <IkGizmo />
-    </IkController>
-    <YourController />         <- Bring your own controller
-    <YourLights />             <- You compose your own scene
-  </MujocoCanvas>
-</MujocoProvider>
-```
+`useMujoco()` gives you the full typed MuJoCo WASM binary — `mj_step`, `mj_forward`, `MjModel`, `MjData`, and everything else:
 
-### `<MujocoPhysics>` — Bring Your Own Canvas
+```tsx
+import { useMujoco } from 'mujoco-react';
 
-Use inside your own `<Canvas>` for full control over gl settings, post-processing, and R3F context composition:
+const { mujoco, status } = useMujoco();
 
-```
-<MujocoProvider>
-  <Canvas shadows camera={...} gl={...}>   <- Your Canvas, your settings
-    <MujocoPhysics config={config}>         <- Physics context only
-      <SceneRenderer />
-      <YourController />
-    </MujocoPhysics>
-    <OrbitControls />
-    <EffectComposer>...</EffectComposer>    <- Post-processing, etc.
-  </Canvas>
-</MujocoProvider>
+if (mujoco) {
+  const model = mujoco.MjModel.loadFromXML('/path/to/scene.xml');
+  const data = new mujoco.MjData(model);
+  mujoco.mj_step(model, data);
+  console.log(data.qpos);  // joint positions after one step
+}
 ```
 
-The library provides **only MuJoCo engine concerns**: WASM lifecycle, physics stepping, and body rendering. Controllers (IK, teleoperation, RL policies) are composable plugins you opt into — or bring your own.
+Most users won't need this — `<MujocoCanvas>` and hooks like `useBeforePhysicsStep` handle the model/data lifecycle for you. But the raw module is always available when you need it.
 
-## Bring Your Own Controller
+## Writing a Controller
 
-**Controllers are just React components.** Write a function that calls `useBeforePhysicsStep` to drive `data.ctrl` each frame, return `null`, and drop it into your scene tree. No base class, no registration — just hooks.
+A controller is a React component that calls `useBeforePhysicsStep` to write `data.ctrl` each frame:
 
 ```tsx
 import { useBeforePhysicsStep } from 'mujoco-react';
@@ -107,76 +89,68 @@ function MyController() {
   });
   return null;
 }
+```
+
+Drop it into the tree:
 
-// Drop it in:
+```tsx
 <MujocoCanvas config={config}>
-  <SceneRenderer />
   <MyController />
 </MujocoCanvas>
 ```
 
-This is the primary way to use the library. IK, teleoperation, RL policies, state machines — they're all just components that read input and write to `data.ctrl`.
-
-### Bring Your Own IK
-
-The built-in `<IkController>` uses a generic Damped Least-Squares solver, but you can plug in **any** IK solver — analytical, learned, or from another library:
+The `createController<TConfig>()` factory adds typed config and default merging for reusable plugins:
 
 ```tsx
-import type { IKSolveFn } from 'mujoco-react';
+import { createController, useBeforePhysicsStep } from 'mujoco-react';
 
-const myIK: IKSolveFn = (pos, quat, currentQ) => {
-  return myAnalyticalSolver(pos, currentQ); // return joint angles or null
-};
+export const MyController = createController<{ gain: number }>(
+  { name: 'MyController', defaultConfig: { gain: 1.0 } },
+  ({ config }) => {
+    useBeforePhysicsStep((_model, data) => {
+      data.ctrl[0] = config.gain * Math.sin(data.time);
+    });
+    return null;
+  },
+);
 
-<IkController config={{ siteName: 'tcp', numJoints: 7, ikSolveFn: myIK }}>
-  <IkGizmo />
-</IkController>
+// <MyController config={{ gain: 2.0 }} />
 ```
 
-Or skip `<IkController>` entirely and solve IK yourself inside `useBeforePhysicsStep`:
+## Architecture
+
+`<MujocoCanvas>` wraps R3F `<Canvas>` and forwards all Canvas props (`camera`, `shadows`, `gl`, etc.). For full control over the Canvas, use `<MujocoPhysics>` inside your own:
 
-```tsx
-function MyIKController() {
-  useBeforePhysicsStep((model, data) => {
-    const joints = myCustomIKSolve(model, data);
-    if (joints) {
-      for (let i = 0; i < joints.length; i++) data.ctrl[i] = joints[i];
-    }
-  });
-  return null;
-}
+```
+<MujocoProvider>                           <MujocoProvider>
+  <MujocoCanvas config={...}>               <Canvas shadows gl={...}>
+    <IkController config={..}>                <MujocoPhysics config={...}>
+      <IkGizmo />                               <MyController />
+    </IkController>                           </MujocoPhysics>
+    <MyController />                          <EffectComposer>...</EffectComposer>
+  </MujocoCanvas>                           </Canvas>
+</MujocoProvider>                         </MujocoProvider>
 ```
 
-### `createController<TConfig>()` Factory
+### Custom IK Solvers
 
-For reusable controller plugins with typed config and default merging:
+The built-in `<IkController>` uses Damped Least-Squares. Pass `ikSolveFn` to swap in your own solver (analytical, learned, etc.):
 
 ```tsx
-import { createController, useBeforePhysicsStep } from 'mujoco-react';
-
-interface MyConfig {
-  gain: number;
-  targetJoint: string;
-}
-
-function MyControllerImpl({ config }: { config: MyConfig; children?: React.ReactNode }) {
-  useBeforePhysicsStep((_model, data) => {
-    data.ctrl[0] = config.gain * Math.sin(data.time);
-  });
-  return null;
-}
+import type { IKSolveFn } from 'mujoco-react';
 
-export const MyController = createController<MyConfig>(
-  { name: 'MyController', defaultConfig: { gain: 1.0 } },
-  MyControllerImpl,
-);
+const myIK: IKSolveFn = (pos, quat, currentQ) => {
+  return myAnalyticalSolver(pos, currentQ); // return joint angles or null
+};
 
-// Usage: <MyController config={{ gain: 2.0, targetJoint: 'shoulder' }} />
+<IkController config={{ siteName: 'tcp', numJoints: 7, ikSolveFn: myIK }}>
+  <IkGizmo />
+</IkController>
 ```
 
-### Built-in `<IkController>`
+### `<IkController>`
 
-The library ships one controller out of the box — an IK gizmo you can drop in for interactive end-effector control:
+The library includes one controller for interactive end-effector control:
 
 ```tsx
 <IkController config={{ siteName: 'tcp', numJoints: 7 }}>
@@ -209,7 +183,7 @@ const ikCtx = useIk({ optional: true });
 Models are loaded from any HTTP source via `SceneConfig.baseUrl`. Defaults to [MuJoCo Menagerie](https://github.com/google-deepmind/mujoco_menagerie) on GitHub.
 
 ```tsx
-// Menagerie robots — just set robotId
+// Menagerie robots: just set robotId
 const franka: SceneConfig = {
   robotId: 'franka_emika_panda',
   sceneFile: 'scene.xml',
@@ -308,7 +282,6 @@ Physics provider for use inside your own R3F `<Canvas>`. Same physics props as `
 <MujocoProvider>
   <Canvas shadows camera={{ position: [2, 2, 2] }}>
     <MujocoPhysics ref={apiRef} config={config} paused={paused}>
-      <SceneRenderer />
       <MyController />
     </MujocoPhysics>
     <OrbitControls />
@@ -329,10 +302,6 @@ Physics provider for use inside your own R3F `<Canvas>`. Same physics props as `
 | `paused` | `boolean` | Declarative pause |
 | `speed` | `number` | Simulation speed multiplier |
 
-### `<SceneRenderer />`
-
-Syncs MuJoCo bodies to Three.js meshes every frame. Must be inside `<MujocoCanvas>` or `<MujocoPhysics>`.
-
 ### `<IkGizmo />`
 
 drei PivotControls gizmo that tracks a MuJoCo site and drives IK on drag. Must be inside `<IkController>`.
@@ -349,10 +318,9 @@ Click-drag to apply spring forces to bodies. Raycasts to find bodies, applies `F
 
 ### R3F Group Props
 
-All visual components (`SceneRenderer`, `DragInteraction`, `ContactMarkers`, `Debug`, `TendonRenderer`, `FlexRenderer`) accept standard R3F group props — `position`, `rotation`, `scale`, `visible`, etc.
+All visual components (`DragInteraction`, `ContactMarkers`, `Debug`, `TendonRenderer`, `FlexRenderer`) accept standard R3F group props like `position`, `rotation`, `scale`, `visible`.
 
 ```tsx
-<SceneRenderer position={[0, 0, 1]} />
 <ContactMarkers visible={showContacts} />
 <Debug showJoints scale={0.5} />
 ```
@@ -420,9 +388,23 @@ Plays back recorded qpos trajectories with scrubbing.
 
 ## Hooks
 
+### `useMujoco()`
+
+Access the WASM module lifecycle from any child of `<MujocoProvider>`:
+
+```tsx
+const { mujoco, status, error } = useMujoco();
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `mujoco` | `MujocoModule \| null` | The raw WASM module, or `null` while loading |
+| `status` | `'pending' \| 'error'` | Lifecycle state (absent once loaded) |
+| `error` | `string \| null` | Error message if loading failed |
+
 ### `useMujocoSim()`
 
-Access the simulation API and internal refs:
+Access the simulation API and internal refs (must be inside `<MujocoCanvas>` or `<MujocoPhysics>`):
 
 ```tsx
 const { api, mjModelRef, mjDataRef } = useMujocoSim();
@@ -679,7 +661,7 @@ The full API object available via `ref` or `useMujocoSim().api`:
 
 ### Building Controllers
 
-See [Building Controllers](https://mujoco-react.mintlify.app/guides/building-controllers) for full patterns including config-driven controllers, IK gizmo coexistence, multi-arm support, and the `createController` factory.
+See [Building Controllers](https://dadd.mintlify.app/guides/building-controllers) for full patterns including config-driven controllers, IK gizmo coexistence, multi-arm support, and the `createController` factory.
 
 ### Graspable Objects
 
@@ -701,7 +683,7 @@ sceneObjects: [{
 }]
 ```
 
-Without `condim: 4` and high friction, objects slide out of the gripper when lifted. See [Graspable Objects](https://mujoco-react.mintlify.app/guides/graspable-objects) for details.
+Without `condim: 4` and high friction, objects slide out of the gripper when lifted. See [Graspable Objects](https://dadd.mintlify.app/guides/graspable-objects) for details.
 
 ### Click-to-Select
 
@@ -714,14 +696,14 @@ function ClickSelectOverlay() {
 }
 ```
 
-See [Click-to-Select](https://mujoco-react.mintlify.app/guides/click-to-select) for the full implementation.
+See [Click-to-Select](https://dadd.mintlify.app/guides/click-to-select) for the full implementation.
 
 ## useFrame Priority
 
 | Priority | Owner | Purpose |
 |----------|-------|---------|
 | -1 | MujocoSimProvider | beforeStep, mj_step, afterStep |
-| 0 (default) | SceneRenderer, IkController, your code | Body mesh sync, IK, rendering |
+| 0 (default) | SceneRenderer (internal), IkController, your code | Body mesh sync, IK, rendering |
 
 ## Roadmap
 

package/dist/index.d.ts

@@ -718,12 +718,6 @@ declare function useIk(options: {
     optional: true;
 }): IkContextValue | null;
 
-/**
- * SceneRenderer — creates and syncs MuJoCo body meshes every frame.
- * Accepts standard R3F group props (position, rotation, scale, visible, etc.).
- */
-declare function SceneRenderer(props: Omit<ThreeElements['group'], 'ref'>): react_jsx_runtime.JSX.Element;
-
 /**
  * IkGizmo — drei PivotControls that tracks a MuJoCo site.
  *
@@ -1160,4 +1154,4 @@ interface CameraAnimationAPI {
  */
 declare function useCameraAnimation(): CameraAnimationAPI;
 
-export { type ActuatorInfo, type BodyInfo, type BodyStateResult, type CameraAnimationAPI, type ContactInfo, ContactListener, type ContactListenerProps, ContactMarkers, type ControllerComponent, type ControllerOptions, Debug, type DebugProps, DragInteraction, type DragInteractionProps, FlexRenderer, type GeomInfo, type IKSolveFn, type IkConfig, type IkContextValue, IkController, IkGizmo, type IkGizmoProps, type JointInfo, type JointStateResult, type KeyBinding, type KeyboardTeleopConfig, type ModelOptions, MujocoCanvas, type MujocoCanvasProps, type MujocoContact, type MujocoContactArray, type MujocoContextValue, type MujocoData, type MujocoModel, type MujocoModule, MujocoPhysics, type MujocoPhysicsProps, MujocoProvider, type MujocoSimAPI, MujocoSimProvider, type PhysicsConfig, type PhysicsStepCallback, type PolicyConfig, type RayHit, type SceneConfig, SceneLights, type SceneLightsProps, type SceneMarker, type SceneObject, SceneRenderer, SelectionHighlight, type SelectionHighlightProps, type SensorInfo, type SensorResult, type SiteInfo, type SitePositionResult, type StateSnapshot, TendonRenderer, type TrajectoryData, type TrajectoryFrame, TrajectoryPlayer, type TrajectoryPlayerProps, type XmlPatch, createController, findActuatorByName, findBodyByName, findGeomByName, findJointByName, findKeyframeByName, findSensorByName, findSiteByName, findTendonByName, getContact, getName, loadScene, useActuators, useAfterPhysicsStep, useBeforePhysicsStep, useBodyState, useCameraAnimation, useContactEvents, useContacts, useCtrl, useCtrlNoise, useGamepad, useGravityCompensation, useIk, useJointState, useKeyboardTeleop, useMujoco, useMujocoSim, usePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePosition, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder };
+export { type ActuatorInfo, type BodyInfo, type BodyStateResult, type CameraAnimationAPI, type ContactInfo, ContactListener, type ContactListenerProps, ContactMarkers, type ControllerComponent, type ControllerOptions, Debug, type DebugProps, DragInteraction, type DragInteractionProps, FlexRenderer, type GeomInfo, type IKSolveFn, type IkConfig, type IkContextValue, IkController, IkGizmo, type IkGizmoProps, type JointInfo, type JointStateResult, type KeyBinding, type KeyboardTeleopConfig, type ModelOptions, MujocoCanvas, type MujocoCanvasProps, type MujocoContact, type MujocoContactArray, type MujocoContextValue, type MujocoData, type MujocoModel, type MujocoModule, MujocoPhysics, type MujocoPhysicsProps, MujocoProvider, type MujocoSimAPI, MujocoSimProvider, type PhysicsConfig, type PhysicsStepCallback, type PolicyConfig, type RayHit, type SceneConfig, SceneLights, type SceneLightsProps, type SceneMarker, type SceneObject, SelectionHighlight, type SelectionHighlightProps, type SensorInfo, type SensorResult, type SiteInfo, type SitePositionResult, type StateSnapshot, TendonRenderer, type TrajectoryData, type TrajectoryFrame, TrajectoryPlayer, type TrajectoryPlayerProps, type XmlPatch, createController, findActuatorByName, findBodyByName, findGeomByName, findJointByName, findKeyframeByName, findSensorByName, findSiteByName, findTendonByName, getContact, getName, loadScene, useActuators, useAfterPhysicsStep, useBeforePhysicsStep, useBodyState, useCameraAnimation, useContactEvents, useContacts, useCtrl, useCtrlNoise, useGamepad, useGravityCompensation, useIk, useJointState, useKeyboardTeleop, useMujoco, useMujocoSim, usePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePosition, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder };