mujoco-react 1.0.0 → 3.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,11 +20,10 @@ npm install mujoco-react three @react-three/fiber @react-three/drei
 import {
   MujocoProvider,
   MujocoCanvas,
-  SceneRenderer,
   IkController,
   IkGizmo,
 } from 'mujoco-react';
-import type { SceneConfig, MujocoSimAPI } from 'mujoco-react';
+import type { SceneConfig } from 'mujoco-react';
 import { OrbitControls } from '@react-three/drei';
 
 const config: SceneConfig = {
@@ -29,19 +33,15 @@ const config: SceneConfig = {
 };
 
 function App() {
-  const apiRef = useRef<MujocoSimAPI>(null);
-
   return (
     <MujocoProvider>
       <MujocoCanvas
-        ref={apiRef}
         config={config}
         camera={{ position: [2, -1.5, 2.5], up: [0, 0, 1], fov: 45 }}
         shadows
         style={{ width: '100%', height: '100vh' }}
       >
         <OrbitControls enableDamping makeDefault />
-        <SceneRenderer />
         <IkController config={{ siteName: 'tcp', numJoints: 7 }}>
           <IkGizmo />
         </IkController>
@@ -53,49 +53,29 @@ function App() {
 }
 ```
 
-## Architecture
-
-Two ways to set up your scene:
-
-### `<MujocoCanvas>` — Quick Start
+## `useMujoco()`
 
-Wraps R3F `<Canvas>` for you. Fastest path to a working scene:
+Inside `<MujocoCanvas>` or `<MujocoPhysics>`, `useMujoco()` gives you the simulation API, refs to the live model/data, and status:
 
-```
-<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>
-```
+```tsx
+import { useMujoco } from 'mujoco-react';
 
-### `<MujocoPhysics>` — Bring Your Own Canvas
+function StatusOverlay() {
+  const { status, api, mjModelRef, mjDataRef } = useMujoco();
 
-Use inside your own `<Canvas>` for full control over gl settings, post-processing, and R3F context composition:
+  if (status !== 'ready') return <span>Loading...</span>;
 
+  return (
+    <button onClick={() => api?.reset()}>
+      Reset ({mjModelRef.current?.nq} joints)
+    </button>
+  );
+}
 ```
-<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>
-```
-
-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.
 
-## 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 +87,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
 
-```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;
-}
+`<MujocoCanvas>` wraps R3F `<Canvas>` and forwards all Canvas props (`camera`, `shadows`, `gl`, etc.). For full control over the Canvas, use `<MujocoPhysics>` inside your own:
+
+```
+<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 +181,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 +280,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 +300,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 +316,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,12 +386,29 @@ Plays back recorded qpos trajectories with scrubbing.
 
 ## Hooks
 
-### `useMujocoSim()`
+### `useMujoco()`
+
+Access the simulation API and internal refs (must be inside `<MujocoCanvas>` or `<MujocoPhysics>`):
+
+```tsx
+const { api, status, mjModelRef, mjDataRef } = useMujoco();
+```
+
+### `useMujocoWasm()`
 
-Access the simulation API and internal refs:
+Access the raw WASM module lifecycle from any child of `<MujocoProvider>`. Most users won't need this — `useMujoco()` and hooks like `useBeforePhysicsStep` handle the model/data lifecycle for you.
 
 ```tsx
-const { api, mjModelRef, mjDataRef } = useMujocoSim();
+import { useMujocoWasm } from 'mujoco-react';
+
+const { mujoco, status } = useMujocoWasm();
+
+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
+}
 ```
 
 ### `useBeforePhysicsStep(callback)`
@@ -601,7 +584,7 @@ useSceneLights(1.5);
 
 ## MujocoSimAPI
 
-The full API object available via `ref` or `useMujocoSim().api`:
+The full API object available via `ref` or `useMujoco().api`:
 
 ### Simulation Control
 
@@ -679,29 +662,11 @@ 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.
-
-### Graspable Objects
+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.
 
-Objects need specific MuJoCo contact parameters to be picked up by grippers:
-
-```tsx
-sceneObjects: [{
-  name: 'cube',
-  type: 'box',
-  size: [0.025, 0.025, 0.025],
-  position: [0.4, 0, 0.025],
-  rgba: [0.9, 0.2, 0.15, 1],
-  mass: 0.05,
-  freejoint: true,
-  friction: '1.5 0.3 0.1',            // high sliding friction
-  solref: '0.01 1',                    // stiff contact solver
-  solimp: '0.95 0.99 0.001 0.5 2',    // tight impedance
-  condim: 4,                           // elliptic friction cone
-}]
-```
+### Contact Parameters
 
-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.
+Objects that need stable contact (grasping, stacking, etc.) require tuned MuJoCo solver parameters — `friction`, `solref`, `solimp`, and `condim`. See [Contact Parameters](https://dadd.mintlify.app/guides/graspable-objects) for details.
 
 ### Click-to-Select
 
@@ -714,14 +679,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

@@ -491,7 +491,7 @@ interface JointStateResult {
 /**
  * Hook to access the MuJoCo WASM module.
  */
-declare function useMujoco(): MujocoContextValue;
+declare function useMujocoWasm(): MujocoContextValue;
 interface MujocoProviderProps {
     wasmUrl?: string;
     /** Timeout in ms for WASM module load. Default: 30000. */
@@ -573,7 +573,7 @@ interface MujocoSimContextValue {
     resetCallbacks: React.RefObject<Set<() => void>>;
     status: 'loading' | 'ready' | 'error';
 }
-declare function useMujocoSim(): MujocoSimContextValue;
+declare function useMujoco(): MujocoSimContextValue;
 declare function useBeforePhysicsStep(callback: PhysicsStepCallback): void;
 declare function useAfterPhysicsStep(callback: PhysicsStepCallback): void;
 interface MujocoSimProviderProps {
@@ -666,7 +666,7 @@ type ControllerComponent<TConfig> = React.FC<{
  * Factory that produces a typed controller component.
  *
  * Controllers are React components that plug into the MuJoCo simulation tree.
- * Inside `Impl`, use any hooks (`useMujocoSim`, `useBeforePhysicsStep`, etc.)
+ * Inside `Impl`, use any hooks (`useMujoco`, `useBeforePhysicsStep`, etc.)
  * to interact with the physics engine.
  *
  * @example
@@ -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, useMujocoWasm, usePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePosition, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder };