mujoco-react 8.2.1 → 8.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mujoco-react",
-  "version": "8.2.1",
+  "version": "8.4.0",
   "description": "Composable React Three Fiber building blocks for MuJoCo WASM simulations",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,7 +34,7 @@
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/noah-wardlow/mujoco-react"
+    "url": "git+https://github.com/noah-wardlow/mujoco-react.git"
   },
   "scripts": {
     "build": "tsup",
@@ -48,7 +48,7 @@
     "three": ">=0.160.0"
   },
   "dependencies": {
-    "mujoco-js": "0.0.7"
+    "@mujoco/mujoco": "^3.9.0"
   },
   "devDependencies": {
     "@react-three/drei": "^10.7.7",

package/src/components/ContactMarkers.tsx

@@ -13,7 +13,7 @@ import { useFrame } from '@react-three/fiber';
 import type { ThreeElements } from '@react-three/fiber';
 import * as THREE from 'three';
 import { useMujocoContext } from '../core/MujocoSimProvider';
-import { getContact } from '../types';
+import { getContact, withContacts } from '../types';
 
 const _dummy = new THREE.Object3D();
 
@@ -49,19 +49,21 @@ export 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;
   });
 

package/src/components/Debug.tsx

@@ -11,7 +11,7 @@ import type { ThreeElements } from '@react-three/fiber';
 import * as THREE from 'three';
 import { useMujocoContext } from '../core/MujocoSimProvider';
 import { getName } from '../core/SceneLoader';
-import { getContact } from '../types';
+import { getContact, withContacts } from '../types';
 import type { DebugProps } from '../types';
 
 const JOINT_COLORS: Record<number, number> = {
@@ -330,22 +330,24 @@ export function Debug({
     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 > 0.001 && 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 > 0.001 && 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++;
+        }
       }
-    }
+    });
 
     // Hide unused arrows
     for (let i = arrowIdx; i < pool.length; i++) {

package/src/components/FlexRenderer.tsx

@@ -39,7 +39,7 @@ export function FlexRenderer(props: Omit<ThreeElements['group'], 'ref'>) {
       const positions = new Float32Array(vertNum * 3);
       geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
 
-      // Note: flex_faceadr/flex_facenum/flex_face are NOT available in mujoco-js WASM.
+      // Note: flex_faceadr/flex_facenum/flex_face may not be available in all MuJoCo WASM builds.
       // Without face data we render as a point cloud. If future WASM versions expose
       // face arrays, index-based triangle rendering can be added here.
 

package/src/components/TendonRenderer.tsx

@@ -7,7 +7,7 @@
  * 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.
  */
 

package/src/core/GenericIK.ts

@@ -41,10 +41,10 @@ export class GenericIK {
      * @param model       MuJoCo model
      * @param data        MuJoCo data (qpos will be temporarily modified, then restored)
      * @param siteId      Index of the end-effector site to control
-     * @param numJoints   Number of arm joints (assumes qpos[0..numJoints-1])
+     * @param qposAdr     qpos addresses for scalar joints in solve order
      * @param targetPos   Target position in world frame
      * @param targetQuat  Target orientation in world frame
-     * @param currentQ    Current joint angles (length = numJoints)
+     * @param currentQ    Current joint angles matching qposAdr order
      * @param opts        Optional solver parameters
      * @returns Joint angles array, or null if solver diverged
      */
@@ -52,14 +52,14 @@ export class GenericIK {
         model: MujocoModel,
         data: MujocoData,
         siteId: number,
-        numJoints: number,
+        qposAdr: ArrayLike<number>,
         targetPos: THREE.Vector3,
         targetQuat: THREE.Quaternion,
-        currentQ: number[],
+        currentQ: ArrayLike<number>,
         opts?: Partial<GenericIKOptions>
     ): number[] | null {
         const o = { ...DEFAULTS, ...opts };
-        const n = numJoints;
+        const n = qposAdr.length;
 
         // Save full qpos so we can restore after solving
         const savedQpos = new Float64Array(data.qpos.length);
@@ -86,9 +86,11 @@ export class GenericIK {
         let bestQ: number[] | null = null;
         let bestErr = Infinity;
 
+        if (n === 0) return null;
+
         for (let iter = 0; iter < o.maxIterations; iter++) {
             // Set joints and run FK
-            for (let i = 0; i < n; i++) data.qpos[i] = q[i];
+            for (let i = 0; i < n; i++) data.qpos[qposAdr[i]] = q[i];
             this.mujoco.mj_forward(model, data);
 
             // Read current site pose
@@ -130,8 +132,9 @@ export class GenericIK {
 
             // Compute Jacobian via finite differences
             for (let j = 0; j < n; j++) {
-                const saved = data.qpos[j];
-                data.qpos[j] = q[j] + o.epsilon;
+                const adr = qposAdr[j];
+                const saved = data.qpos[adr];
+                data.qpos[adr] = q[j] + o.epsilon;
                 this.mujoco.mj_forward(model, data);
 
                 for (let i = 0; i < 3; i++) pertSitePos[i] = sp[off3 + i];
@@ -150,11 +153,11 @@ export class GenericIK {
                 J[5 * n + j] = (dRot[2] / o.epsilon) * o.rotWeight;
 
                 // Restore joint
-                data.qpos[j] = saved;
+                data.qpos[adr] = saved;
             }
 
             // Restore base FK state for next iteration
-            for (let i = 0; i < n; i++) data.qpos[i] = q[i];
+            for (let i = 0; i < n; i++) data.qpos[qposAdr[i]] = q[i];
 
             // Damped least squares: Δq = Jᵀ (J Jᵀ + λI)⁻¹ error
             // 1. Compute JJᵀ (6×6)

package/src/core/MujocoProvider.tsx

@@ -3,9 +3,10 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import loadMujoco from 'mujoco-js';
+import loadMujoco from '@mujoco/mujoco';
+import defaultMujocoWasmUrl from '@mujoco/mujoco/mujoco.wasm?url';
 import { createContext, useContext, useEffect, useRef, useState } from 'react';
-import { MujocoModule, MujocoContextValue } from '../types';
+import type { MujocoModule, MujocoContextValue } from '../types';
 
 const MujocoContext = createContext<MujocoContextValue>({
   mujoco: null,
@@ -20,19 +21,77 @@ export function useMujocoWasm(): MujocoContextValue {
   return useContext(MujocoContext);
 }
 
-interface MujocoProviderProps {
+export type MujocoWasmVariant = 'single' | 'threaded' | 'auto';
+
+export interface MujocoLoaderOptions {
+  locateFile?: (path: string) => string;
+  printErr?: (text: string) => void;
+}
+
+export type MujocoLoader = (options?: MujocoLoaderOptions) => Promise<unknown>;
+
+export interface MujocoProviderProps {
   wasmUrl?: string;
+  /** Optional URL for the multi-threaded WASM asset. */
+  mtWasmUrl?: string;
+  /**
+   * Optional official multi-threaded loader, usually imported from
+   * `@mujoco/mujoco/mt`. It is supplied by the app so the default package path
+   * does not force every bundler to process the threaded Emscripten build.
+   */
+  threadedLoader?: MujocoLoader;
+  /**
+   * MuJoCo WASM build to load. `single` is the default and works everywhere.
+   * `threaded` requires `threadedLoader` and cross-origin isolation. `auto`
+   * uses threaded only when both conditions are satisfied.
+   */
+  wasmVariant?: MujocoWasmVariant;
   /** Timeout in ms for WASM module load. Default: 30000. */
   timeout?: number;
   children: React.ReactNode;
   onError?: (error: Error) => void;
 }
 
+function canUseThreadedWasm(): boolean {
+  return typeof globalThis !== 'undefined' && globalThis.crossOriginIsolated === true;
+}
+
+function isMujocoModule(value: unknown): value is MujocoModule {
+  return typeof value === 'object'
+    && value !== null
+    && 'FS' in value
+    && 'MjModel' in value
+    && 'MjData' in value
+    && 'mj_step' in value;
+}
+
+function hasWasmUrl(value: string | undefined): value is string {
+  return typeof value === 'string' && value.length > 0;
+}
+
+function resolveWasmVariant(
+  variant: MujocoWasmVariant | undefined,
+  threadedLoader: MujocoLoader | undefined,
+  mtWasmUrl: string | undefined
+): 'single' | 'threaded' {
+  if (variant === 'threaded') return 'threaded';
+  if (variant === 'auto' && threadedLoader && mtWasmUrl && canUseThreadedWasm()) return 'threaded';
+  return 'single';
+}
+
 /**
  * MujocoProvider — WASM / module lifecycle.
  * Loads the MuJoCo WASM module on mount and provides it to children via context.
  */
-export function MujocoProvider({ wasmUrl, timeout = 30000, children, onError }: MujocoProviderProps) {
+export function MujocoProvider({
+  wasmUrl,
+  mtWasmUrl,
+  threadedLoader,
+  wasmVariant = 'single',
+  timeout = 30000,
+  children,
+  onError,
+}: MujocoProviderProps) {
   const [status, setStatus] = useState<'loading' | 'ready' | 'error'>('loading');
   const [error, setError] = useState<string | null>(null);
   const moduleRef = useRef<MujocoModule | null>(null);
@@ -41,8 +100,31 @@ export function MujocoProvider({ wasmUrl, timeout = 30000, children, onError }:
   useEffect(() => {
     isMounted.current = true;
 
-    const wasmPromise = loadMujoco({
-      ...(wasmUrl ? { locateFile: (path: string) => path.endsWith('.wasm') ? wasmUrl : path } : {}),
+    const variant = resolveWasmVariant(wasmVariant, threadedLoader, mtWasmUrl);
+    if (variant === 'threaded' && !threadedLoader) {
+      const err = new Error('MujocoProvider wasmVariant="threaded" requires a threadedLoader from @mujoco/mujoco/mt');
+      setError(err.message);
+      setStatus('error');
+      onError?.(err);
+      return;
+    }
+    let selectedWasmUrl = wasmUrl ?? defaultMujocoWasmUrl;
+
+    if (variant === 'threaded') {
+      if (!hasWasmUrl(mtWasmUrl)) {
+        const err = new Error('MujocoProvider wasmVariant="threaded" requires mtWasmUrl from @mujoco/mujoco/mt/mujoco.wasm?url');
+        setError(err.message);
+        setStatus('error');
+        onError?.(err);
+        return;
+      }
+      selectedWasmUrl = mtWasmUrl;
+    }
+
+    const load: MujocoLoader = variant === 'threaded' && threadedLoader ? threadedLoader : loadMujoco;
+
+    const wasmPromise = load({
+      locateFile: (path: string) => path.endsWith('.wasm') ? selectedWasmUrl : path,
       printErr: (text: string) => {
         if (text.includes('Aborted') && isMounted.current) {
           setError('Simulation crashed. Reload page.');
@@ -58,7 +140,10 @@ export function MujocoProvider({ wasmUrl, timeout = 30000, children, onError }:
     Promise.race([wasmPromise, timeoutPromise])
       .then((inst: unknown) => {
         if (isMounted.current) {
-          moduleRef.current = inst as MujocoModule;
+          if (!isMujocoModule(inst)) {
+            throw new Error('MuJoCo WASM module initialized with an unexpected shape');
+          }
+          moduleRef.current = inst;
           setStatus('ready');
         }
       })
@@ -74,7 +159,7 @@ export function MujocoProvider({ wasmUrl, timeout = 30000, children, onError }:
     return () => {
       isMounted.current = false;
     };
-  }, [wasmUrl, timeout]);
+  }, [wasmUrl, mtWasmUrl, threadedLoader, wasmVariant, timeout, onError]);
 
   return (
     <MujocoContext.Provider

package/src/core/MujocoSimProvider.tsx

@@ -14,11 +14,14 @@ import {
   useState,
 } from 'react';
 import * as THREE from 'three';
-import { MujocoData, MujocoModel, MujocoModule, getContact } from '../types';
+import { MujocoData, MujocoModel, MujocoModule, getContact, withContacts } from '../types';
 import { SceneRenderer } from '../components/SceneRenderer';
 import {
+  ActuatedJointInfo,
   ActuatorInfo,
   BodyInfo,
+  ControlGroupInfo,
+  ControlGroupSelector,
   ContactInfo,
   GeomInfo,
   JointInfo,
@@ -40,7 +43,10 @@ import {
   findSensorByName,
   findActuatorByName,
   getActuatedScalarQposAdr,
+  getActuatedJoints as getActuatedJointsFromModel,
+  getControlMap as getControlMapFromModel,
   getName,
+  resolveControlGroup as resolveControlGroupFromModel,
 } from './SceneLoader';
 
 // ---- Joint type names ----
@@ -65,6 +71,24 @@ const SENSOR_TYPE_NAMES: Record<number, string> = {
   45: 'clock', 46: 'tactile', 47: 'plugin', 48: 'user',
 };
 
+const EMPTY_CONTROL_GROUP: ControlGroupInfo = {
+  joints: [],
+  actuators: [],
+  qposAdr: [],
+  dofAdr: [],
+  ctrlAdr: [],
+  readQpos: () => new Float64Array(0),
+  readCtrl: () => new Float64Array(0),
+  writeQpos: () => {},
+  writeCtrl: () => {},
+};
+
+function isMutableApiRef(
+  ref: React.ForwardedRef<MujocoSimAPI>
+): ref is React.MutableRefObject<MujocoSimAPI | null> {
+  return typeof ref === 'object' && ref !== null && 'current' in ref;
+}
+
 // Preallocated force/torque temps for applyForce/applyTorque
 const _applyForce = new Float64Array(3);
 const _applyTorque = new Float64Array(3);
@@ -329,8 +353,8 @@ export function MujocoSimProvider({
       if (externalApiRef) {
         if (typeof externalApiRef === 'function') {
           externalApiRef(api);
-        } else {
-          (externalApiRef as React.MutableRefObject<MujocoSimAPI | null>).current = api;
+        } else if (isMutableApiRef(externalApiRef)) {
+          externalApiRef.current = api;
         }
       }
     }
@@ -576,18 +600,20 @@ export function MujocoSimProvider({
     if (!model || !data) return [];
     const contacts: ContactInfo[] = [];
     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;
   }, []);
 
@@ -612,14 +638,14 @@ export function MujocoSimProvider({
     const result: JointInfo[] = [];
     for (let i = 0; i < model.njnt; i++) {
       const type = model.jnt_type[i];
-      const limited = model.jnt_limited ? model.jnt_limited[i] !== 0 : false;
+      const range: [number, number] = [model.jnt_range[2 * i], model.jnt_range[2 * i + 1]];
       result.push({
         id: i,
         name: getName(model, model.name_jntadr[i]),
         type,
         typeName: JOINT_TYPE_NAMES[type] ?? `unknown(${type})`,
-        range: [model.jnt_range[2 * i], model.jnt_range[2 * i + 1]],
-        limited,
+        range,
+        limited: range[0] < range[1],
         bodyId: model.jnt_bodyid[i],
         qposAdr: model.jnt_qposadr[i],
         dofAdr: model.jnt_dofadr[i],
@@ -677,6 +703,21 @@ export function MujocoSimProvider({
     return result;
   }, []);
 
+  const getControlMapApi = useCallback((): ControlGroupInfo => {
+    const model = mjModelRef.current;
+    return model ? getControlMapFromModel(model) : EMPTY_CONTROL_GROUP;
+  }, []);
+
+  const getActuatedJointsApi = useCallback((): ActuatedJointInfo[] => {
+    const model = mjModelRef.current;
+    return model ? getActuatedJointsFromModel(model) : [];
+  }, []);
+
+  const resolveControlGroupApi = useCallback((selector: ControlGroupSelector): ControlGroupInfo | null => {
+    const model = mjModelRef.current;
+    return model ? resolveControlGroupFromModel(model, selector) : null;
+  }, []);
+
   const getSensors = useCallback((): SensorInfo[] => {
     const model = mjModelRef.current;
     if (!model) return [];
@@ -937,6 +978,9 @@ export function MujocoSimProvider({
       getQvel,
       setCtrl,
       getCtrl,
+      getControlMap: getControlMapApi,
+      getActuatedJoints: getActuatedJointsApi,
+      resolveControlGroup: resolveControlGroupApi,
       applyForce,
       applyTorque: applyTorqueApi,
       setExternalForce,
@@ -968,6 +1012,7 @@ export function MujocoSimProvider({
       status, config, reset, setSpeed, togglePause, setPaused, step,
       getTime, getTimestep, applyKeyframe, saveState, restoreState,
       setQpos, setQvel, getQpos, getQvel, setCtrl, getCtrl,
+      getControlMapApi, getActuatedJointsApi, resolveControlGroupApi,
       applyForce, applyTorqueApi, setExternalForce, applyGeneralizedForce,
       getSensorData, getContacts, getBodies, getJoints, getGeoms, getSites,
       getActuatorsApi, getSensors, getModelOption, setGravity, setTimestepApi,