mujoco-react 8.3.3 → 8.4.1

package/README.md

@@ -18,149 +18,138 @@ Composable [React Three Fiber](https://docs.pmnd.rs/react-three-fiber) wrapper a
 npm install mujoco-react three @react-three/fiber @react-three/drei
 ```
 
-## Quick Start
+## Load a Model
 
 ```tsx
-import {
-  MujocoProvider,
-  MujocoCanvas,
-  useIkController,
-  IkGizmo,
-} from "mujoco-react";
+import { MujocoProvider, MujocoCanvas } from "mujoco-react";
 import type { SceneConfig } from "mujoco-react";
-import { OrbitControls } from "@react-three/drei";
 
-const config: SceneConfig = {
+const panda: SceneConfig = {
   src: "https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/franka_emika_panda/",
   sceneFile: "scene.xml",
   homeJoints: [1.707, -1.754, 0.003, -2.702, 0.003, 0.951, 2.490],
 };
 
-function Scene() {
-  const ik = useIkController({ siteName: "tcp", numJoints: 7 });
-  return (
-    <>
-      <OrbitControls enableDamping makeDefault />
-      {ik && <IkGizmo controller={ik} />}
-      <ambientLight intensity={0.7} />
-      <directionalLight position={[1, 2, 5]} intensity={1.2} castShadow />
-    </>
-  );
-}
-
-function App() {
+export function App() {
   return (
     <MujocoProvider>
       <MujocoCanvas
-        config={config}
+        config={panda}
         camera={{ position: [2, -1.5, 2.5], up: [0, 0, 1], fov: 45 }}
-        shadows
         style={{ width: "100%", height: "100vh" }}
-      >
-        <Scene />
-      </MujocoCanvas>
+      />
     </MujocoProvider>
   );
 }
 ```
 
-## `useMujoco()`
-
-Inside `<MujocoCanvas>` or `<MujocoPhysics>`, `useMujoco()` gives you the simulation API, refs to the live model/data, and status:
+## Add Scene Tools
 
 ```tsx
-import { useMujoco } from "mujoco-react";
-
-function MyComponent() {
-  const { isPending, isError, error, api, mjModelRef } = useMujoco();
+import { OrbitControls } from "@react-three/drei";
+import { IkGizmo, useIkController } from "mujoco-react";
 
-  if (isPending) return <span>Loading...</span>;
-  if (isError) return <span>Error: {error}</span>;
+function PandaTools() {
+  const ik = useIkController({ siteName: "tcp" });
 
   return (
-    <button onClick={() => api.reset()}>
-      Reset ({mjModelRef.current?.nq} joints)
-    </button>
+    <>
+      <OrbitControls makeDefault />
+      {ik && <IkGizmo controller={ik} />}
+      <ambientLight intensity={0.7} />
+      <directionalLight position={[1, 2, 5]} intensity={1.2} />
+    </>
   );
 }
 ```
 
-## Writing a Controller
-
-A controller is a hook that reads sensors and writes actuators each physics step:
+Use it as a child of `<MujocoCanvas>`:
 
 ```tsx
-import { useCtrl, useSensor, useBeforePhysicsStep } from "mujoco-react";
+<MujocoCanvas config={panda}>
+  <PandaTools />
+</MujocoCanvas>
+```
 
-function useMyController(gain: number) {
-  const shoulder = useCtrl("shoulder");
-  const elbow = useCtrl("elbow");
-  const force = useSensor("force_sensor");
+## Write Controllers
 
-  useBeforePhysicsStep(() => {
-    shoulder.write(gain * Math.sin(Date.now() / 1000));
-    elbow.write(force.read()[0] * -0.5);
+```tsx
+import { useBeforePhysicsStep } from "mujoco-react";
+
+function MyController() {
+  useBeforePhysicsStep((_model, data) => {
+    data.ctrl[0] = Math.sin(data.time);
   });
+
+  return null;
 }
 ```
 
-### Applying Forces
+Controllers are just React children that read sensors, write `data.ctrl`, apply forces, or call the `MujocoSimAPI` at physics-step time.
 
-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:
+## Use the Sim API
 
 ```tsx
-import { useBeforePhysicsStep } from "mujoco-react";
+import { useMujoco } 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;
-  });
+function ResetButton() {
+  const sim = useMujoco();
+  if (!sim.isReady) return null;
+
+  return <button onClick={() => sim.api.reset()}>Reset</button>;
 }
 ```
 
-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
+## WebSocket Control
 
-Stream joint commands over a WebSocket and send simulation state back:
+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";
 
-function useWebSocketJoints(url: string) {
-  const { api } = useMujoco();
+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 latestJointsRef = useRef<number[] | null>(null);
+  const latestCommandRef = useRef<CtrlCommand | null>(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;
-      }
+      latestCommandRef.current = parseSocketMessage(evt.data);
     };
 
     return () => ws.close();
   }, [url]);
 
-  // Apply incoming joint positions each physics step
+  // Apply incoming actuator controls 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];
+    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 sensor feedback back after physics
+  // Send simulation feedback back after physics.
   useAfterPhysicsStep((model, data) => {
     const ws = wsRef.current;
     if (!ws || ws.readyState !== WebSocket.OPEN) return;
@@ -227,7 +216,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)`
@@ -235,14 +224,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 |
@@ -251,6 +242,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:
@@ -334,8 +339,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:

package/dist/index.d.ts

@@ -285,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. */
@@ -323,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;
@@ -368,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;
@@ -495,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;
@@ -585,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;
@@ -596,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.
@@ -740,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;
@@ -1304,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 };