mujoco-react 8.1.0 → 8.2.0

package/README.md

@@ -8,7 +8,9 @@
 
 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
 
@@ -111,22 +113,45 @@ Drop it into the tree:
 </MujocoCanvas>
 ```
 
-The `createController<TConfig>()` factory adds typed config and default merging for reusable plugins:
+The `createControllerHook` factory produces a typed hook with config stabilization and default merging. Pass `null` to disable:
+
+```tsx
+import { createControllerHook, useBeforePhysicsStep } from "mujoco-react";
+
+export const useMyController = createControllerHook<{ gain: number }, { value: number }>(
+  { name: "useMyController", defaultConfig: { gain: 1.0 } },
+  (config) => {
+    useBeforePhysicsStep((_model, data) => {
+      if (!config) return;
+      data.ctrl[0] = config.gain * Math.sin(data.time);
+    });
+    if (!config) return null;
+    return { value: config.gain };
+  },
+);
+
+// const result = useMyController({ gain: 2.0 });
+// const disabled = useMyController(null); // returns null
+```
+
+The `createController` factory is the component equivalent — same config stabilization, but returns a component that can render children:
 
 ```tsx
-import { createController, useBeforePhysicsStep } from "mujoco-react";
+import { createController, useBeforePhysicsStep, Debug } from "mujoco-react";
 
 export const MyController = createController<{ gain: number }>(
   { name: "MyController", defaultConfig: { gain: 1.0 } },
-  ({ config }) => {
+  ({ config, children }) => {
     useBeforePhysicsStep((_model, data) => {
       data.ctrl[0] = config.gain * Math.sin(data.time);
     });
-    return null;
+    return <>{children}</>;
   },
 );
 
-// <MyController config={{ gain: 2.0 }} />
+// <MyController config={{ gain: 2.0 }}>
+//   <Debug showJoints />
+// </MyController>
 ```
 
 ## Architecture
@@ -727,7 +752,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

@@ -391,6 +391,18 @@ function sceneObjectToXml(obj) {
   const condim = obj.condim ? ` condim="${obj.condim}"` : "";
   return `<body name="${obj.name}" pos="${pos}">${joint}<geom type="${obj.type}" size="${size}" rgba="${rgba}" contype="1" conaffinity="1"${mass}${friction}${solref}${solimp}${condim}/></body>`;
 }
+function ensureDir(mujoco, fname) {
+  const dirParts = fname.split("/");
+  dirParts.pop();
+  let currentPath = "/working";
+  for (const part of dirParts) {
+    currentPath += "/" + part;
+    try {
+      mujoco.FS.mkdir(currentPath);
+    } catch {
+    }
+  }
+}
 async function loadScene(mujoco, config, onProgress) {
   try {
     mujoco.FS.unmount("/working");
@@ -402,66 +414,75 @@ async function loadScene(mujoco, config, onProgress) {
   }
   const baseUrl = config.src.endsWith("/") ? config.src : config.src + "/";
   const downloaded = /* @__PURE__ */ new Set();
-  const queue = [config.sceneFile];
+  const xmlQueue = [config.sceneFile];
+  const assetFiles = [];
   const parser = new DOMParser();
-  while (queue.length > 0) {
-    const fname = queue.shift();
+  while (xmlQueue.length > 0) {
+    const fname = xmlQueue.shift();
     if (downloaded.has(fname)) continue;
     downloaded.add(fname);
+    if (!fname.endsWith(".xml")) {
+      assetFiles.push(fname);
+      continue;
+    }
     onProgress?.(`Downloading ${fname}...`);
     const res = await fetch(baseUrl + fname);
     if (!res.ok) {
       console.warn(`Failed to fetch ${fname}: ${res.status} ${res.statusText}`);
       continue;
     }
-    const dirParts = fname.split("/");
-    dirParts.pop();
-    let currentPath = "/working";
-    for (const part of dirParts) {
-      currentPath += "/" + part;
-      try {
-        mujoco.FS.mkdir(currentPath);
-      } catch {
-      }
-    }
-    if (fname.endsWith(".xml")) {
-      let text = await res.text();
-      for (const patch of config.xmlPatches ?? []) {
-        if (fname.endsWith(patch.target) || fname === patch.target) {
-          if (patch.replace) {
-            const [from, to] = patch.replace;
-            if (text.includes(from)) {
-              text = text.replace(from, to);
-            } else {
-              const preview = from.length > 80 ? `${from.slice(0, 80)}...` : from;
-              console.warn(`XML patch replace pattern not found in ${fname}: "${preview}"`);
-            }
+    let text = await res.text();
+    for (const patch of config.xmlPatches ?? []) {
+      if (fname.endsWith(patch.target) || fname === patch.target) {
+        if (patch.replace) {
+          const [from, to] = patch.replace;
+          if (text.includes(from)) {
+            text = text.replace(from, to);
+          } else {
+            const preview = from.length > 80 ? `${from.slice(0, 80)}...` : from;
+            console.warn(`XML patch replace pattern not found in ${fname}: "${preview}"`);
           }
-          if (patch.inject && patch.injectAfter) {
-            const idx = text.indexOf(patch.injectAfter);
-            if (idx !== -1) {
-              const tagEnd = text.indexOf(">", idx + patch.injectAfter.length);
-              if (tagEnd !== -1) {
-                text = text.slice(0, tagEnd + 1) + patch.inject + text.slice(tagEnd + 1);
-              } else {
-                console.warn(`XML patch inject failed in ${fname}: could not find tag end after "${patch.injectAfter}"`);
-              }
+        }
+        if (patch.inject && patch.injectAfter) {
+          const idx = text.indexOf(patch.injectAfter);
+          if (idx !== -1) {
+            const tagEnd = text.indexOf(">", idx + patch.injectAfter.length);
+            if (tagEnd !== -1) {
+              text = text.slice(0, tagEnd + 1) + patch.inject + text.slice(tagEnd + 1);
             } else {
-              const preview = patch.injectAfter.length > 80 ? `${patch.injectAfter.slice(0, 80)}...` : patch.injectAfter;
-              console.warn(`XML patch inject anchor not found in ${fname}: "${preview}"`);
+              console.warn(`XML patch inject failed in ${fname}: could not find tag end after "${patch.injectAfter}"`);
             }
+          } else {
+            const preview = patch.injectAfter.length > 80 ? `${patch.injectAfter.slice(0, 80)}...` : patch.injectAfter;
+            console.warn(`XML patch inject anchor not found in ${fname}: "${preview}"`);
           }
         }
       }
-      if (fname === config.sceneFile && config.sceneObjects?.length) {
-        const xml = config.sceneObjects.map((obj) => sceneObjectToXml(obj)).join("");
-        text = text.replace("</worldbody>", xml + "</worldbody>");
-      }
-      mujoco.FS.writeFile(`/working/${fname}`, text);
-      scanDependencies(text, fname, parser, downloaded, queue);
-    } else {
-      const buffer = new Uint8Array(await res.arrayBuffer());
-      mujoco.FS.writeFile(`/working/${fname}`, buffer);
+    }
+    if (fname === config.sceneFile && config.sceneObjects?.length) {
+      const xml = config.sceneObjects.map((obj) => sceneObjectToXml(obj)).join("");
+      text = text.replace("</worldbody>", xml + "</worldbody>");
+    }
+    ensureDir(mujoco, fname);
+    mujoco.FS.writeFile(`/working/${fname}`, text);
+    scanDependencies(text, fname, parser, downloaded, xmlQueue);
+  }
+  if (assetFiles.length > 0) {
+    onProgress?.(`Downloading ${assetFiles.length} assets...`);
+    const results = await Promise.all(
+      assetFiles.map(async (fname) => {
+        const res = await fetch(baseUrl + fname);
+        if (!res.ok) {
+          console.warn(`Failed to fetch ${fname}: ${res.status} ${res.statusText}`);
+          return null;
+        }
+        return { fname, buffer: new Uint8Array(await res.arrayBuffer()) };
+      })
+    );
+    for (const result of results) {
+      if (!result) continue;
+      ensureDir(mujoco, result.fname);
+      mujoco.FS.writeFile(`/working/${result.fname}`, result.buffer);
     }
   }
   onProgress?.("Loading model...");
@@ -4155,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