mujoco-react 8.2.1 → 8.4.0

package/README.md

@@ -6,7 +6,7 @@
 
 > **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)
 
@@ -37,7 +37,7 @@ const config: SceneConfig = {
 };
 
 function Scene() {
-  const ik = useIkController({ siteName: "tcp", numJoints: 7 });
+  const ik = useIkController({ siteName: "tcp" });
   return (
     <>
       <OrbitControls enableDamping makeDefault />
@@ -104,6 +104,91 @@ function useMyController(gain: number) {
 }
 ```
 
+### 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
+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 `api.applyForce(bodyName, force)` convenience method also works for one-off interactions (e.g. button clicks) but does a name lookup each call.
+
+### WebSocket Control
+
+Stream actuator commands over a WebSocket and send simulation state back. Use a schema validator such as Zod at this boundary because socket messages are untrusted app input (`npm install zod` for this example):
+
+```tsx
+import { useEffect, useRef } from "react";
+import { z } from "zod";
+import { useMujoco, useBeforePhysicsStep, useAfterPhysicsStep } from "mujoco-react";
+
+const CtrlCommand = z.object({
+  type: z.literal("ctrl_command"),
+  ctrl: z.array(z.number()),
+});
+
+type CtrlCommand = z.infer<typeof CtrlCommand>;
+
+function parseSocketMessage(data: string): CtrlCommand | null {
+  try {
+    const parsed = CtrlCommand.safeParse(JSON.parse(data));
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+}
+
+function useWebSocketControls(url: string) {
+  const wsRef = useRef<WebSocket | null>(null);
+  const latestCommandRef = useRef<CtrlCommand | null>(null);
+
+  useEffect(() => {
+    const ws = new WebSocket(url);
+    wsRef.current = ws;
+
+    ws.onmessage = (evt) => {
+      latestCommandRef.current = parseSocketMessage(evt.data);
+    };
+
+    return () => ws.close();
+  }, [url]);
+
+  // Apply incoming actuator controls each physics step.
+  useBeforePhysicsStep((model, data) => {
+    const command = latestCommandRef.current;
+    if (!command) return;
+    for (let i = 0; i < Math.min(command.ctrl.length, model.nu); i++) {
+      data.ctrl[i] = command.ctrl[i];
+    }
+  });
+
+  // Send simulation 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),
+    }));
+  });
+}
+```
+
 For reusable controllers with typed config, default merging, and children, use the `createController` factory:
 
 ```tsx
@@ -155,7 +240,7 @@ const myIK: IKSolveFn = (pos, quat, currentQ) => {
   return myAnalyticalSolver(pos, currentQ); // return joint angles or null
 };
 
-const ik = useIkController({ siteName: "tcp", numJoints: 7, ikSolveFn: myIK });
+const ik = useIkController({ siteName: "tcp", ikSolveFn: myIK });
 ```
 
 ### `useIkController(config | null)`
@@ -163,14 +248,16 @@ const ik = useIkController({ siteName: "tcp", numJoints: 7, ikSolveFn: myIK });
 Hook for interactive end-effector control. Pass `null` to disable IK (safe to call unconditionally):
 
 ```tsx
-const ik = useIkController({ siteName: "tcp", numJoints: 7 });
+const ik = useIkController({ siteName: "tcp" });
 return ik ? <IkGizmo controller={ik} /> : null;
 ```
 
 | Config | Type | Default | Description |
 |--------|------|---------|-------------|
 | `siteName` | `string` | **required** | MuJoCo site to track |
-| `numJoints` | `number` | **required** | Number of joints for IK |
+| `joints` | `string \| string[] \| RegExp \| (joint) => boolean` | inferred | Explicit hinge/slide joints for IK |
+| `actuators` | `string \| string[] \| RegExp \| (actuator) => boolean` | inferred | Explicit actuators for IK output |
+| `numJoints` | `number` | legacy only | Contiguous qpos/ctrl count from older examples |
 | `ikSolveFn` | `IKSolveFn` | built-in DLS | Custom solver function |
 | `damping` | `number` | `0.01` | DLS damping |
 | `maxIterations` | `number` | `50` | Max solver iterations |
@@ -179,6 +266,20 @@ Returns `IkContextValue | null` with methods like `setIkEnabled`, `moveTarget`,
 
 Pass the returned value to `<IkGizmo controller={ik} />` or to your own controller as a prop.
 
+By default the controller infers scalar hinge/slide joints by walking from the site body toward the model root. For robots where the MJCF control layout is not a simple chain, pass explicit names:
+
+```tsx
+const leftArmIk = useIkController({
+  siteName: "left_tcp",
+  joints: ["left_shoulder", "left_elbow", "left_wrist"],
+});
+
+const gripperIk = useIkController({
+  siteName: "tcp",
+  actuators: /^actuator/,
+});
+```
+
 ## Type-Safe Resource Names
 
 Use TypeScript module augmentation to get autocomplete and type checking for actuator, sensor, body, joint, site, geom, and keyframe names:
@@ -262,8 +363,29 @@ Loads the MuJoCo WASM module. Wrap your entire app in this.
 | Prop | Type | Description |
 |------|------|-------------|
 | `wasmUrl` | `string?` | Custom WASM URL override |
+| `mtWasmUrl` | `string?` | Custom multi-threaded WASM URL override |
+| `threadedLoader` | `(options?) => Promise<unknown>` | Optional loader imported from `@mujoco/mujoco/mt` |
+| `wasmVariant` | `"single" \| "threaded" \| "auto"` | MuJoCo WASM build. Defaults to `"single"` |
+| `timeout` | `number` | WASM load timeout in ms |
 | `onError` | `(error: Error) => void` | Called if WASM fails to load |
 
+The official `@mujoco/mujoco` package also ships a multi-threaded WASM build. Import it only in apps that opt into it:
+
+```tsx
+import loadMujocoMt from "@mujoco/mujoco/mt";
+import mtWasmUrl from "@mujoco/mujoco/mt/mujoco.wasm?url";
+
+<MujocoProvider
+  wasmVariant="auto"
+  threadedLoader={loadMujocoMt}
+  mtWasmUrl={mtWasmUrl}
+>
+  <App />
+</MujocoProvider>
+```
+
+`"auto"` uses the threaded build only when `threadedLoader` and `mtWasmUrl` are provided and `globalThis.crossOriginIsolated` is true. Forced `"threaded"` mode requires `threadedLoader`, `mtWasmUrl`, `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp`.
+
 ### `<MujocoCanvas>`
 
 Thin wrapper around R3F `<Canvas>`. Accepts all R3F Canvas props plus:
@@ -445,7 +567,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
@@ -769,7 +891,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;
@@ -282,11 +285,22 @@ interface SceneConfig {
     xmlPatches?: XmlPatch[];
     onReset?: (model: MujocoModel, data: MujocoData) => void;
 }
+type ResourceSelector<TInfo, TName extends string = string> = TName | readonly TName[] | RegExp | ((info: TInfo) => boolean);
 interface IkConfig {
     /** MuJoCo site name for IK target. */
     siteName: Sites;
-    /** Number of joints to solve for. */
-    numJoints: number;
+    /**
+     * Explicit joints for IK. When omitted, the controller infers scalar hinge/slide
+     * joints by walking from the site body to the model root.
+     */
+    joints?: ResourceSelector<JointInfo, Joints>;
+    /** Explicit actuators for IK control output. */
+    actuators?: ResourceSelector<ActuatorInfo, Actuators>;
+    /**
+     * Number of joints to solve for, assuming legacy contiguous qpos/ctrl layout
+     * starting at index 0. Prefer inferred IK or `joints`/`actuators`.
+     */
+    numJoints?: number;
     /** Custom IK solver. When omitted, uses built-in Damped Least-Squares solver. */
     ikSolveFn?: IKSolveFn;
     /** DLS damping. Default: 0.01. */
@@ -320,7 +334,13 @@ interface PhysicsConfig {
     paused?: boolean;
     speed?: number;
 }
-type IKSolveFn = (pos: THREE.Vector3, quat: THREE.Quaternion, currentQ: number[]) => number[] | null;
+type IKSolveFn = (pos: THREE.Vector3, quat: THREE.Quaternion, currentQ: number[], context?: IKSolveContext) => number[] | null;
+interface IKSolveContext {
+    model: MujocoModel;
+    data: MujocoData;
+    siteId: number;
+    controlGroup: ControlGroupInfo;
+}
 type PhysicsStepCallback = (model: MujocoModel, data: MujocoData) => void;
 interface StateSnapshot {
     time: number;
@@ -365,6 +385,44 @@ interface ActuatorInfo {
     name: string;
     range: [number, number];
 }
+interface ActuatedJointInfo extends JointInfo {
+    actuatorId: number;
+    actuatorName: string;
+    ctrlAdr: number;
+    ctrlRange: [number, number];
+}
+interface ControlJointInfo extends JointInfo {
+    actuatorId: number | null;
+    actuatorName: string | null;
+    ctrlAdr: number | null;
+    ctrlRange: [number, number] | null;
+}
+interface ControlGroupSelector {
+    /** Infer a kinematic chain from a MuJoCo site. */
+    siteName?: Sites;
+    /** Infer a kinematic chain from a body. */
+    bodyName?: Bodies;
+    /** Select joints by name, names, regex, or predicate. */
+    joints?: ResourceSelector<JointInfo, Joints>;
+    /** Select actuators by name, names, regex, or predicate. */
+    actuators?: ResourceSelector<ActuatorInfo, Actuators>;
+}
+interface ControlGroupInfo {
+    /** Joints in solve/control order. */
+    joints: ControlJointInfo[];
+    /** Actuators in control output order. */
+    actuators: ActuatorInfo[];
+    /** qpos addresses for scalar hinge/slide joints. */
+    qposAdr: number[];
+    /** dof addresses for scalar hinge/slide joints. */
+    dofAdr: number[];
+    /** ctrl addresses matching writable actuators. */
+    ctrlAdr: number[];
+    readQpos(data: MujocoData): Float64Array;
+    readCtrl(data: MujocoData): Float64Array;
+    writeQpos(data: MujocoData, values: ArrayLike<number>): void;
+    writeCtrl(data: MujocoData, values: ArrayLike<number>): void;
+}
 interface SensorInfo {
     id: number;
     name: string;
@@ -492,6 +550,9 @@ interface MujocoSimAPI {
     getQvel(): Float64Array;
     setCtrl(nameOrValues: Actuators | Record<Actuators, number>, value?: number): void;
     getCtrl(): Float64Array;
+    getControlMap(): ControlGroupInfo;
+    getActuatedJoints(): ActuatedJointInfo[];
+    resolveControlGroup(selector: ControlGroupSelector): ControlGroupInfo | null;
     applyForce(bodyName: Bodies, force: THREE.Vector3, point?: THREE.Vector3): void;
     applyTorque(bodyName: Bodies, torque: THREE.Vector3): void;
     setExternalForce(bodyName: Bodies, force: THREE.Vector3, torque: THREE.Vector3): void;
@@ -582,8 +643,28 @@ interface JointStateResult {
  * Hook to access the MuJoCo WASM module.
  */
 declare function useMujocoWasm(): MujocoContextValue;
+type MujocoWasmVariant = 'single' | 'threaded' | 'auto';
+interface MujocoLoaderOptions {
+    locateFile?: (path: string) => string;
+    printErr?: (text: string) => void;
+}
+type MujocoLoader = (options?: MujocoLoaderOptions) => Promise<unknown>;
 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;
@@ -593,7 +674,7 @@ interface MujocoProviderProps {
  * MujocoProvider — WASM / module lifecycle.
  * Loads the MuJoCo WASM module on mount and provides it to children via context.
  */
-declare function MujocoProvider({ wasmUrl, timeout, children, onError }: MujocoProviderProps): react_jsx_runtime.JSX.Element;
+declare function MujocoProvider({ wasmUrl, mtWasmUrl, threadedLoader, wasmVariant, timeout, children, onError, }: MujocoProviderProps): react_jsx_runtime.JSX.Element;
 
 /**
  * MujocoCanvas — thin R3F Canvas wrapper for MuJoCo scenes.
@@ -737,6 +818,10 @@ declare function findSensorByName(mjModel: MujocoModel, name: string): number;
  * Find a tendon by name in the MuJoCo model. Returns -1 if not found.
  */
 declare function findTendonByName(mjModel: MujocoModel, name: string): number;
+declare function getActuatedJoints(mjModel: MujocoModel): ActuatedJointInfo[];
+declare function getControlMap(mjModel: MujocoModel): ControlGroupInfo;
+declare function resolveControlGroup(mjModel: MujocoModel, selector: ControlGroupSelector): ControlGroupInfo | null;
+declare function createContiguousControlGroup(mjModel: MujocoModel, count: number): ControlGroupInfo;
 interface LoadResult {
     mjModel: MujocoModel;
     mjData: MujocoData;
@@ -1301,4 +1386,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, 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 };
+export { type ActuatedJointInfo, type ActuatorInfo, type Actuators, type Bodies, Body, type BodyInfo, type BodyProps, type BodyStateResult, type CameraAnimationAPI, type ContactInfo, ContactListener, type ContactListenerProps, ContactMarkers, type ControlGroupInfo, type ControlGroupSelector, type ControlJointInfo, 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 MujocoLoader, type MujocoLoaderOptions, type MujocoModel, type MujocoModule, MujocoPhysics, type MujocoPhysicsProps, MujocoProvider, type MujocoProviderProps, type MujocoSimAPI, MujocoSimProvider, type MujocoWasmVariant, type PhysicsConfig, type PhysicsStepCallback, type PlaybackState, type PolicyConfig, type RayHit, type Register, type ResourceSelector, 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, createContiguousControlGroup, createController, createControllerHook, findActuatorByName, findBodyByName, findGeomByName, findJointByName, findKeyframeByName, findSensorByName, findSiteByName, findTendonByName, getActuatedJoints, getContact, getControlMap, getName, loadScene, resolveControlGroup, 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 };