mujoco-react 8.1.1 → 8.2.1

package/README.md

@@ -4,11 +4,13 @@
 
 # mujoco-react
 
-> **Beta** — This library is under active development. The API may change between minor versions until 1.0.
+> **Beta** — This library is under active development. The API may change between minor versions until 10.0.
 
 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.
 
-**[Demo](https://mujoco-react-example.pages.dev)** | **[Docs](https://dadd.mintlify.app)** | **[Example Source](https://github.com/noah-wardlow/mujoco-react-example)** | **[llms.txt](https://dadd.mintlify.app/llms.txt)**
+[![npm](https://img.shields.io/npm/v/mujoco-react)](https://www.npmjs.com/package/mujoco-react)
+
+**[Demo](https://mujoco-react-example.pages.dev)** | **[Docs](https://dadd.mintlify.app)** | **[npm](https://www.npmjs.com/package/mujoco-react)** | **[Example Source](https://github.com/noah-wardlow/mujoco-react-example)** | **[llms.txt](https://dadd.mintlify.app/llms.txt)**
 
 ## Install
 
@@ -85,50 +87,48 @@ function MyComponent() {
 
 ## Writing a Controller
 
-A controller is a React component that uses handle-based hooks for type-safe actuator and sensor access:
+A controller is a hook that reads sensors and writes actuators each physics step:
 
 ```tsx
 import { useCtrl, useSensor, useBeforePhysicsStep } from "mujoco-react";
 
-function MyController() {
+function useMyController(gain: number) {
   const shoulder = useCtrl("shoulder");
   const elbow = useCtrl("elbow");
   const force = useSensor("force_sensor");
 
   useBeforePhysicsStep(() => {
-    shoulder.write(Math.sin(Date.now() / 1000));
+    shoulder.write(gain * Math.sin(Date.now() / 1000));
     elbow.write(force.read()[0] * -0.5);
   });
-  return null;
 }
 ```
 
-Drop it into the tree:
+For reusable controllers with typed config, default merging, and children, use the `createController` factory:
 
 ```tsx
-<MujocoCanvas config={config}>
-  <MyController />
-</MujocoCanvas>
-```
-
-The `createController<TConfig>()` factory adds typed config and default merging for reusable plugins:
-
-```tsx
-import { createController, useBeforePhysicsStep } from "mujoco-react";
+import { createController, useCtrl, useBeforePhysicsStep } from "mujoco-react";
 
 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);
+  ({ config, children }) => {
+    const shoulder = useCtrl("shoulder");
+
+    useBeforePhysicsStep(() => {
+      shoulder.write(config.gain * Math.sin(Date.now() / 1000));
     });
-    return null;
+
+    return <>{children}</>;
   },
 );
 
-// <MyController config={{ gain: 2.0 }} />
+// <MyController config={{ gain: 2.0 }}>
+//   <Debug showJoints />
+// </MyController>
 ```
 
+A `createControllerHook` factory is also available for the hook equivalent — see the [Building Controllers](https://dadd.mintlify.app/guides/building-controllers) guide.
+
 ## 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:
@@ -727,7 +727,7 @@ The full API object available via `ref` or `useMujoco()` (when `isReady`):
 
 ### Building Controllers
 
-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.
+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 `createControllerHook`/`createController` factories.
 
 ### Contact Parameters
 

package/dist/index.d.ts

@@ -790,6 +790,33 @@ declare function createController<TConfig>(options: ControllerOptions<TConfig>,
     config: TConfig;
     children?: React.ReactNode;
 }>): ControllerComponent<TConfig>;
+/**
+ * Factory that produces a typed controller hook.
+ *
+ * Same config stabilization and default merging as `createController`,
+ * but returns a hook instead of a component. Pass `null` to disable.
+ *
+ * @example
+ * ```tsx
+ * const useMyController = createControllerHook<MyConfig, MyValue>(
+ *   { name: 'useMyController', defaultConfig: { gain: 1.0 } },
+ *   function useMyControllerImpl(config) {
+ *     // config is MyConfig | null — hooks must be called unconditionally
+ *     useBeforePhysicsStep((_model, data) => {
+ *       if (!config) return;
+ *       data.ctrl[0] = config.gain * Math.sin(data.time);
+ *     });
+ *     if (!config) return null;
+ *     return { /* value *\/ };
+ *   },
+ * );
+ *
+ * // Usage:
+ * const value = useMyController({ gain: 2.0 });
+ * const disabled = useMyController(null); // returns null
+ * ```
+ */
+declare function createControllerHook<TConfig, TValue>(options: ControllerOptions<TConfig>, useImpl: (config: TConfig | null) => TValue | null): (config: TConfig | null) => TValue | null;
 
 /**
  * @license
@@ -1274,4 +1301,4 @@ interface CameraAnimationAPI {
  */
 declare function useCameraAnimation(): CameraAnimationAPI;
 
-export { type ActuatorInfo, type Actuators, type Bodies, Body, type BodyInfo, type BodyProps, type BodyStateResult, type CameraAnimationAPI, type ContactInfo, ContactListener, type ContactListenerProps, ContactMarkers, type ControllerComponent, type ControllerOptions, type CtrlHandle, Debug, type DebugProps, DragInteraction, type DragInteractionProps, FlexRenderer, type GeomInfo, type Geoms, type IKSolveFn, type IkConfig, type IkContextValue, IkGizmo, type IkGizmoProps, type JointInfo, type JointStateResult, type Joints, type KeyBinding, type KeyboardTeleopConfig, type Keyframes, 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 PlaybackState, type PolicyConfig, type RayHit, type Register, type SceneConfig, SceneLights, type SceneLightsProps, type SceneMarker, type SceneObject, type SensorHandle, type SensorInfo, type SensorResult, type Sensors, type SiteInfo, type SitePositionResult, type Sites, type StateSnapshot, TendonRenderer, type TrajectoryData, type TrajectoryFrame, type TrajectoryInput, TrajectoryPlayer, type TrajectoryPlayerProps, type XmlPatch, createController, findActuatorByName, findBodyByName, findGeomByName, findJointByName, findKeyframeByName, findSensorByName, findSiteByName, findTendonByName, getContact, getName, loadScene, useActuators, useAfterPhysicsStep, useBeforePhysicsStep, useBodyMeshes, useBodyState, useCameraAnimation, useContactEvents, useContacts, useCtrl, useCtrlNoise, useGamepad, useGravityCompensation, useIkController, useJointState, useKeyboardTeleop, useMujoco, useMujocoWasm, usePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePosition, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder };
+export { type ActuatorInfo, type Actuators, type Bodies, Body, type BodyInfo, type BodyProps, type BodyStateResult, type CameraAnimationAPI, type ContactInfo, ContactListener, type ContactListenerProps, ContactMarkers, type ControllerComponent, type ControllerOptions, type CtrlHandle, Debug, type DebugProps, DragInteraction, type DragInteractionProps, FlexRenderer, type GeomInfo, type Geoms, type IKSolveFn, type IkConfig, type IkContextValue, IkGizmo, type IkGizmoProps, type JointInfo, type JointStateResult, type Joints, type KeyBinding, type KeyboardTeleopConfig, type Keyframes, 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 PlaybackState, type PolicyConfig, type RayHit, type Register, type SceneConfig, SceneLights, type SceneLightsProps, type SceneMarker, type SceneObject, type SensorHandle, type SensorInfo, type SensorResult, type Sensors, type SiteInfo, type SitePositionResult, type Sites, type StateSnapshot, TendonRenderer, type TrajectoryData, type TrajectoryFrame, type TrajectoryInput, TrajectoryPlayer, type TrajectoryPlayerProps, type XmlPatch, createController, createControllerHook, findActuatorByName, findBodyByName, findGeomByName, findJointByName, findKeyframeByName, findSensorByName, findSiteByName, findTendonByName, getContact, getName, loadScene, useActuators, useAfterPhysicsStep, useBeforePhysicsStep, useBodyMeshes, useBodyState, useCameraAnimation, useContactEvents, useContacts, useCtrl, useCtrlNoise, useGamepad, useGravityCompensation, useIkController, useJointState, useKeyboardTeleop, useMujoco, useMujocoWasm, usePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePosition, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder };

package/dist/index.js

@@ -4176,6 +4176,6 @@ function useCameraAnimation() {
  * useCameraAnimation — composable camera animation hook.
  */
 
-export { Body, ContactListener, ContactMarkers, Debug, DragInteraction, FlexRenderer, IkGizmo, MujocoCanvas, MujocoPhysics, MujocoProvider, MujocoSimProvider, SceneLights, TendonRenderer, TrajectoryPlayer, createController, findActuatorByName, findBodyByName, findGeomByName, findJointByName, findKeyframeByName, findSensorByName, findSiteByName, findTendonByName, getContact, getName, loadScene, useActuators, useAfterPhysicsStep, useBeforePhysicsStep, useBodyMeshes, useBodyState, useCameraAnimation, useContactEvents, useContacts, useCtrl, useCtrlNoise, useGamepad, useGravityCompensation, useIkController, useJointState, useKeyboardTeleop, useMujoco, useMujocoWasm, usePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePosition, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder };
+export { Body, ContactListener, ContactMarkers, Debug, DragInteraction, FlexRenderer, IkGizmo, MujocoCanvas, MujocoPhysics, MujocoProvider, MujocoSimProvider, SceneLights, TendonRenderer, TrajectoryPlayer, createController, createControllerHook, findActuatorByName, findBodyByName, findGeomByName, findJointByName, findKeyframeByName, findSensorByName, findSiteByName, findTendonByName, getContact, getName, loadScene, useActuators, useAfterPhysicsStep, useBeforePhysicsStep, useBodyMeshes, useBodyState, useCameraAnimation, useContactEvents, useContacts, useCtrl, useCtrlNoise, useGamepad, useGravityCompensation, useIkController, useJointState, useKeyboardTeleop, useMujoco, useMujocoWasm, usePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePosition, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mujoco-react",
-  "version": "8.1.1",
+  "version": "8.2.1",
   "description": "Composable React Three Fiber building blocks for MuJoCo WASM simulations",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -23,7 +23,7 @@ export {
 } from './core/SceneLoader';
 
 // Controller factory
-export { createController } from './core/createController';
+export { createController, createControllerHook } from './core/createController';
 export type { ControllerOptions, ControllerComponent } from './core/createController';
 
 // IK controller hook