mujoco-react 8.2.0 → 8.3.3

package/README.md

@@ -4,9 +4,9 @@
 
 # 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.
+Composable [React Three Fiber](https://docs.pmnd.rs/react-three-fiber) wrapper around the official [@mujoco/mujoco](https://www.npmjs.com/package/@mujoco/mujoco) WASM bindings. Load any MuJoCo model, step physics, render bodies, and write controllers as React components.
 
 [![npm](https://img.shields.io/npm/v/mujoco-react)](https://www.npmjs.com/package/mujoco-react)
 
@@ -87,64 +87,109 @@ 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:
+### Applying Forces
+
+Write directly to `xfrc_applied` in a physics callback for per-frame forces. The layout is `[torque_x, torque_y, torque_z, force_x, force_y, force_z]` per body:
 
 ```tsx
-<MujocoCanvas config={config}>
-  <MyController />
-</MujocoCanvas>
+import { useBeforePhysicsStep } from "mujoco-react";
+
+function useSpringForce(bodyId: number, target: [number, number, number], stiffness = 100) {
+  useBeforePhysicsStep((_model, data) => {
+    const i3 = bodyId * 3;
+    const i6 = bodyId * 6;
+    data.xfrc_applied[i6 + 3] = (target[0] - data.xpos[i3]) * stiffness;
+    data.xfrc_applied[i6 + 4] = (target[1] - data.xpos[i3 + 1]) * stiffness;
+    data.xfrc_applied[i6 + 5] = (target[2] - data.xpos[i3 + 2]) * stiffness;
+  });
+}
 ```
 
-The `createControllerHook` factory produces a typed hook with config stabilization and default merging. Pass `null` to disable:
+The `api.applyForce(bodyName, force)` convenience method also works for one-off interactions (e.g. button clicks) but does a name lookup each call.
+
+### WebSocket Joint Control
+
+Stream joint commands over a WebSocket and send simulation state back:
 
 ```tsx
-import { createControllerHook, useBeforePhysicsStep } from "mujoco-react";
+import { useEffect, useRef } from "react";
+import { useMujoco, useBeforePhysicsStep, useAfterPhysicsStep } 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 };
-  },
-);
+function useWebSocketJoints(url: string) {
+  const { api } = useMujoco();
+  const wsRef = useRef<WebSocket | null>(null);
+  const latestJointsRef = useRef<number[] | null>(null);
 
-// const result = useMyController({ gain: 2.0 });
-// const disabled = useMyController(null); // returns null
+  useEffect(() => {
+    const ws = new WebSocket(url);
+    wsRef.current = ws;
+
+    ws.onmessage = (evt) => {
+      const msg = JSON.parse(evt.data);
+      if (msg.type === "joint_command") {
+        latestJointsRef.current = msg.qpos;
+      }
+    };
+
+    return () => ws.close();
+  }, [url]);
+
+  // Apply incoming joint positions each physics step
+  useBeforePhysicsStep((model, data) => {
+    const joints = latestJointsRef.current;
+    if (!joints) return;
+    for (let i = 0; i < Math.min(joints.length, model.nu); i++) {
+      data.ctrl[i] = joints[i];
+    }
+  });
+
+  // Send sensor feedback back after physics
+  useAfterPhysicsStep((model, data) => {
+    const ws = wsRef.current;
+    if (!ws || ws.readyState !== WebSocket.OPEN) return;
+
+    ws.send(JSON.stringify({
+      type: "feedback",
+      time: data.time,
+      qpos: Array.from(data.qpos),
+      qvel: Array.from(data.qvel),
+      sensordata: Array.from(data.sensordata),
+    }));
+  });
+}
 ```
 
-The `createController` factory is the component equivalent — same config stabilization, but returns a component that can render children:
+For reusable controllers with typed config, default merging, and children, use the `createController` factory:
 
 ```tsx
-import { createController, useBeforePhysicsStep, Debug } from "mujoco-react";
+import { createController, useCtrl, useBeforePhysicsStep } from "mujoco-react";
 
 export const MyController = createController<{ gain: number }>(
   { name: "MyController", defaultConfig: { gain: 1.0 } },
   ({ config, children }) => {
-    useBeforePhysicsStep((_model, data) => {
-      data.ctrl[0] = config.gain * Math.sin(data.time);
+    const shoulder = useCtrl("shoulder");
+
+    useBeforePhysicsStep(() => {
+      shoulder.write(config.gain * Math.sin(Date.now() / 1000));
     });
+
     return <>{children}</>;
   },
 );
@@ -154,6 +199,8 @@ export const MyController = createController<{ gain: number }>(
 // </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:
@@ -470,7 +517,7 @@ import { useMujocoWasm } from "mujoco-react";
 const { mujoco, status } = useMujocoWasm();
 
 if (mujoco) {
-  const model = mujoco.MjModel.loadFromXML("/path/to/scene.xml");
+  const model = mujoco.MjModel.from_xml_path("/path/to/scene.xml");
   const data = new mujoco.MjData(model);
   mujoco.mj_step(model, data);
   console.log(data.qpos);  // joint positions after one step
@@ -794,7 +841,7 @@ Features planned but not yet implemented:
 | **Web Worker physics** | P2 | Run `mj_step` off main thread via SharedArrayBuffer |
 | **Register codegen** | P2 | CLI to auto-generate `Register` type augmentation from MJCF XML |
 
-### WASM Limitations (mujoco-js 0.0.7)
+### WASM Limitations (@mujoco/mujoco)
 
 These MuJoCo features are not yet exposed in the WASM binding:
 

package/dist/index.d.ts

@@ -64,12 +64,13 @@ interface MujocoContact {
  */
 interface MujocoContactArray {
     get(i: number): MujocoContact | undefined;
+    delete?: () => void;
 }
 /**
- * Read a single contact from the WASM contact array.
+ * Read a single contact from an already-acquired WASM contact array.
  * Returns undefined if the access fails (WASM heap issue, bad index, etc.).
  */
-declare function getContact(data: MujocoData, i: number): MujocoContact | undefined;
+declare function getContact(contacts: MujocoContactArray, i: number): MujocoContact | undefined;
 /**
  * Minimal interface for MuJoCo Model to avoid 'any'.
  */
@@ -217,7 +218,9 @@ interface MujocoData {
  */
 interface MujocoModule {
     MjModel: {
-        loadFromXML: (path: string) => MujocoModel;
+        from_xml_path?: (path: string) => MujocoModel;
+        from_xml_string?: (xml: string, vfs?: unknown) => MujocoModel;
+        loadFromXML?: (path: string) => MujocoModel;
         [key: string]: unknown;
     };
     MjData: new (model: MujocoModel) => MujocoData;

package/dist/index.js

@@ -1,4 +1,5 @@
-import loadMujoco from 'mujoco-js';
+import loadMujoco from '@mujoco/mujoco';
+import defaultMujocoWasmUrl from '@mujoco/mujoco/mujoco.wasm?url';
 import { createContext, forwardRef, useEffect, useContext, useState, useRef, useCallback, useMemo, useLayoutEffect } from 'react';
 import { jsx, jsxs } from 'react/jsx-runtime';
 import { Canvas, useThree, useFrame } from '@react-three/fiber';
@@ -22,7 +23,7 @@ function MujocoProvider({ wasmUrl, timeout = 3e4, children, onError }) {
   useEffect(() => {
     isMounted.current = true;
     const wasmPromise = loadMujoco({
-      ...wasmUrl ? { locateFile: (path) => path.endsWith(".wasm") ? wasmUrl : path } : {},
+      locateFile: (path) => path.endsWith(".wasm") ? wasmUrl ?? defaultMujocoWasmUrl : path,
       printErr: (text) => {
         if (text.includes("Aborted") && isMounted.current) {
           setError("Simulation crashed. Reload page.");
@@ -60,13 +61,21 @@ function MujocoProvider({ wasmUrl, timeout = 3e4, children, onError }) {
 }
 
 // src/types.ts
-function getContact(data, i) {
+function getContact(contacts, i) {
   try {
-    return data.contact.get(i);
+    return contacts.get(i);
   } catch {
     return void 0;
   }
 }
+function withContacts(data, read) {
+  const contacts = data.contact;
+  try {
+    return read(contacts);
+  } finally {
+    contacts.delete?.();
+  }
+}
 var CapsuleGeometry = class extends THREE11.BufferGeometry {
   parameters;
   constructor(radius = 1, length = 1, capSegments = 4, radialSegments = 8) {
@@ -403,6 +412,15 @@ function ensureDir(mujoco, fname) {
     }
   }
 }
+function loadModelFromPath(mujoco, path) {
+  if (mujoco.MjModel.from_xml_path) {
+    return mujoco.MjModel.from_xml_path(path);
+  }
+  if (mujoco.MjModel.loadFromXML) {
+    return mujoco.MjModel.loadFromXML(path);
+  }
+  throw new Error("MuJoCo WASM module does not expose an XML path loader");
+}
 async function loadScene(mujoco, config, onProgress) {
   try {
     mujoco.FS.unmount("/working");
@@ -486,7 +504,7 @@ async function loadScene(mujoco, config, onProgress) {
     }
   }
   onProgress?.("Loading model...");
-  const mjModel = mujoco.MjModel.loadFromXML(`/working/${config.sceneFile}`);
+  const mjModel = loadModelFromPath(mujoco, `/working/${config.sceneFile}`);
   const mjData = new mujoco.MjData(mjModel);
   if (config.homeJoints) {
     const homeCount = Math.min(config.homeJoints.length, mjModel.nu);
@@ -1080,18 +1098,20 @@ function MujocoSimProvider({
     if (!model || !data) return [];
     const contacts = [];
     const ncon = data.ncon;
-    for (let i = 0; i < ncon; i++) {
-      const c = getContact(data, i);
-      if (!c) break;
-      contacts.push({
-        geom1: c.geom1,
-        geom1Name: getName(model, model.name_geomadr[c.geom1]),
-        geom2: c.geom2,
-        geom2Name: getName(model, model.name_geomadr[c.geom2]),
-        pos: [c.pos[0], c.pos[1], c.pos[2]],
-        depth: c.dist
-      });
-    }
+    withContacts(data, (contactArray) => {
+      for (let i = 0; i < ncon; i++) {
+        const c = getContact(contactArray, i);
+        if (!c) break;
+        contacts.push({
+          geom1: c.geom1,
+          geom1Name: getName(model, model.name_geomadr[c.geom1]),
+          geom2: c.geom2,
+          geom2Name: getName(model, model.name_geomadr[c.geom2]),
+          pos: [c.pos[0], c.pos[1], c.pos[2]],
+          depth: c.dist
+        });
+      }
+    });
     return contacts;
   }, []);
   const getBodies = useCallback(() => {
@@ -2255,18 +2275,20 @@ function ContactMarkers({
     }
     const ncon = data.ncon;
     const count = Math.min(ncon, maxContacts);
-    for (let i = 0; i < count; i++) {
-      const c = getContact(data, i);
-      if (!c) {
-        mesh.count = i;
-        mesh.instanceMatrix.needsUpdate = true;
-        return;
+    let resolvedCount = count;
+    withContacts(data, (contactArray) => {
+      for (let i = 0; i < count; i++) {
+        const c = getContact(contactArray, i);
+        if (!c) {
+          resolvedCount = i;
+          return;
+        }
+        _dummy.position.set(c.pos[0], c.pos[1], c.pos[2]);
+        _dummy.updateMatrix();
+        mesh.setMatrixAt(i, _dummy.matrix);
       }
-      _dummy.position.set(c.pos[0], c.pos[1], c.pos[2]);
-      _dummy.updateMatrix();
-      mesh.setMatrixAt(i, _dummy.matrix);
-    }
-    mesh.count = count;
+    });
+    mesh.count = resolvedCount;
     mesh.instanceMatrix.needsUpdate = true;
   });
   if (status !== "ready") return null;
@@ -2807,22 +2829,24 @@ function Debug({
     if (!data || pool.length === 0) return;
     const ncon = data.ncon;
     let arrowIdx = 0;
-    for (let i = 0; i < Math.min(ncon, MAX_CONTACT_ARROWS); i++) {
-      const c = getContact(data, i);
-      if (!c) break;
-      _contactPos.set(c.pos[0], c.pos[1], c.pos[2]);
-      _contactNormal.set(c.frame[0], c.frame[1], c.frame[2]);
-      const force = Math.abs(c.dist) * 100;
-      const length = Math.min(force * 0.01, 0.1);
-      if (length > 1e-3 && arrowIdx < pool.length) {
-        const arrow = pool[arrowIdx];
-        arrow.position.copy(_contactPos);
-        arrow.setDirection(_contactNormal);
-        arrow.setLength(length, length * 0.3, length * 0.15);
-        arrow.visible = true;
-        arrowIdx++;
+    withContacts(data, (contactArray) => {
+      for (let i = 0; i < Math.min(ncon, MAX_CONTACT_ARROWS); i++) {
+        const c = getContact(contactArray, i);
+        if (!c) break;
+        _contactPos.set(c.pos[0], c.pos[1], c.pos[2]);
+        _contactNormal.set(c.frame[0], c.frame[1], c.frame[2]);
+        const force = Math.abs(c.dist) * 100;
+        const length = Math.min(force * 0.01, 0.1);
+        if (length > 1e-3 && arrowIdx < pool.length) {
+          const arrow = pool[arrowIdx];
+          arrow.position.copy(_contactPos);
+          arrow.setDirection(_contactNormal);
+          arrow.setLength(length, length * 0.3, length * 0.15);
+          arrow.visible = true;
+          arrowIdx++;
+        }
       }
-    }
+    });
     for (let i = arrowIdx; i < pool.length; i++) {
       pool[i].visible = false;
     }
@@ -3053,23 +3077,25 @@ function useContacts(bodyName, callback) {
     }
     const contacts = [];
     const filterBody = bodyIdRef.current;
-    for (let i = 0; i < ncon; i++) {
-      const c = getContact(data, i);
-      if (!c) break;
-      if (filterBody >= 0) {
-        const b1 = model.geom_bodyid[c.geom1];
-        const b2 = model.geom_bodyid[c.geom2];
-        if (b1 !== filterBody && b2 !== filterBody) continue;
+    withContacts(data, (contactArray) => {
+      for (let i = 0; i < ncon; i++) {
+        const c = getContact(contactArray, i);
+        if (!c) break;
+        if (filterBody >= 0) {
+          const b1 = model.geom_bodyid[c.geom1];
+          const b2 = model.geom_bodyid[c.geom2];
+          if (b1 !== filterBody && b2 !== filterBody) continue;
+        }
+        contacts.push({
+          geom1: c.geom1,
+          geom1Name: getGeomNameCached(model, c.geom1),
+          geom2: c.geom2,
+          geom2Name: getGeomNameCached(model, c.geom2),
+          pos: [c.pos[0], c.pos[1], c.pos[2]],
+          depth: c.dist
+        });
       }
-      contacts.push({
-        geom1: c.geom1,
-        geom1Name: getGeomNameCached(model, c.geom1),
-        geom2: c.geom2,
-        geom2Name: getGeomNameCached(model, c.geom2),
-        pos: [c.pos[0], c.pos[1], c.pos[2]],
-        depth: c.dist
-      });
-    }
+    });
     contactsRef.current = contacts;
     callbackRef.current?.(contacts);
   });
@@ -4058,7 +4084,7 @@ function useCameraAnimation() {
  * WASM fields used: model.ntendon, model.ten_wrapadr, model.ten_wrapnum
  * data.wrap_xpos, data.ten_wrapadr (runtime)
  *
- * Note: ten_rgba and ten_width are NOT available in mujoco-js 0.0.7.
+ * Note: ten_rgba and ten_width may not be available in all MuJoCo WASM builds.
  * Tendons use a default color and width.
  */
 /**