mujoco-react 7.0.1 → 8.0.0

package/README.md

@@ -85,15 +85,18 @@ function MyComponent() {
 
 ## Writing a Controller
 
-A controller is a React component that calls `useBeforePhysicsStep` to write `data.ctrl` each frame:
+A controller is a React component that uses handle-based hooks for type-safe actuator and sensor access:
 
 ```tsx
-import { useBeforePhysicsStep } from 'mujoco-react';
+import { useCtrl, useSensor, useBeforePhysicsStep } from 'mujoco-react';
 
 function MyController() {
-  useBeforePhysicsStep((_model, data) => {
-    data.ctrl[0] = Math.sin(data.time);        // sine wave on actuator 0
-    data.ctrl[1] = data.sensordata[0] * -0.5;  // feedback from a sensor
+  const joint1 = useCtrl('joint1');
+  const force = useSensor('force_sensor');
+
+  useBeforePhysicsStep(() => {
+    joint1.write(Math.sin(Date.now() / 1000));
+    joint1.write(force.read()[0] * -0.5);
   });
   return null;
 }
@@ -175,6 +178,23 @@ Returns `IkContextValue | null` with methods like `setIkEnabled`, `moveTarget`,
 
 Pass the returned value to `<IkGizmo controller={ik} />` or to your own controller as a prop.
 
+## Type-Safe Resource Names
+
+Use TypeScript module augmentation to get autocomplete and type checking for actuator, sensor, body, joint, site, geom, and keyframe names:
+
+```ts
+// e.g. in src/mujoco-register.d.ts
+declare module 'mujoco-react' {
+  interface Register {
+    actuators: 'joint1' | 'joint2' | 'joint3' | 'gripper';
+    sensors: 'force_sensor' | 'torque_sensor';
+    bodies: 'link0' | 'link1' | 'hand';
+  }
+}
+```
+
+Once declared, hooks like `useCtrl`, `useSensor`, `useBodyState`, and API methods like `setCtrl`, `applyForce`, `getSensorData` will only accept the declared names. When no `Register` augmentation is provided, all names fall back to `string`.
+
 ## Loading Models
 
 The loader fetches `src + sceneFile`, parses the XML for dependencies (meshes, textures, includes), recursively fetches those too, and writes everything to MuJoCo's in-memory WASM filesystem.
@@ -466,10 +486,11 @@ await moveCameraTo(
 
 ### `useSensor(name)` / `useSensors()`
 
-Read sensor values by name (ref-based, no re-renders):
+Read sensor values by name. Returns a `SensorHandle` with `read()`, `dim`, and `name`:
 
 ```tsx
-const { value, size, type } = useSensor('force_sensor_1');
+const force = useSensor('force_sensor_1');
+// force.read() → Float64Array, force.dim → number
 ```
 
 ### `useBodyState(name)`
@@ -490,10 +511,11 @@ const { position, velocity } = useJointState('joint1');
 
 ### `useCtrl(name)`
 
-Read/write actuator control by name:
+Read/write actuator control by name. Returns a `CtrlHandle` with `read()`, `write()`, `name`, and `range`:
 
 ```tsx
-const [value, setValue] = useCtrl('gripper');
+const gripper = useCtrl('gripper');
+// gripper.read() → number, gripper.write(0.04), gripper.range → [min, max]
 ```
 
 ### `useContacts(bodyName?)` / `useContactEvents(bodyName, handlers)`
@@ -732,6 +754,7 @@ Features planned but not yet implemented:
 | **Physics interpolation** | P1 | Smooth rendering between physics ticks for very high refresh displays |
 | **Instanced geom rendering** | P2 | `<InstancedGeomRenderer />` for particle/granular sims |
 | **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)
 

package/dist/index.d.ts

@@ -9,6 +9,45 @@ import * as THREE from 'three';
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/**
+ * Module augmentation interface for type-safe resource names.
+ *
+ * Declare your model's resource names via module augmentation:
+ * ```ts
+ * declare module 'mujoco-react' {
+ *   interface Register {
+ *     actuators: 'joint1' | 'joint2' | 'gripper';
+ *     sensors: 'force_sensor' | 'torque_sensor';
+ *     bodies: 'link0' | 'link1' | 'hand';
+ *   }
+ * }
+ * ```
+ *
+ * When no augmentation is declared, all names fall back to `string`.
+ */
+interface Register {
+}
+type Actuators = Register extends {
+    actuators: infer T extends string;
+} ? T : string;
+type Sensors = Register extends {
+    sensors: infer T extends string;
+} ? T : string;
+type Bodies = Register extends {
+    bodies: infer T extends string;
+} ? T : string;
+type Joints = Register extends {
+    joints: infer T extends string;
+} ? T : string;
+type Sites = Register extends {
+    sites: infer T extends string;
+} ? T : string;
+type Geoms = Register extends {
+    geoms: infer T extends string;
+} ? T : string;
+type Keyframes = Register extends {
+    keyframes: infer T extends string;
+} ? T : string;
 /**
  * A single MuJoCo contact from the WASM module.
  * Accessed via `data.contact.get(i)`.
@@ -245,7 +284,7 @@ interface SceneConfig {
 }
 interface IkConfig {
     /** MuJoCo site name for IK target. */
-    siteName: string;
+    siteName: Sites;
     /** Number of joints to solve for. */
     numJoints: number;
     /** Custom IK solver. When omitted, uses built-in Damped Least-Squares solver. */
@@ -365,7 +404,7 @@ interface TrajectoryData {
     fps: number;
 }
 interface KeyBinding {
-    actuator: string;
+    actuator: Actuators;
     delta?: number;
     toggle?: [number, number];
     set?: number;
@@ -410,12 +449,12 @@ interface TrajectoryPlayerProps {
     onFrame?: (frameIdx: number) => void;
 }
 interface ContactListenerProps {
-    body: string;
+    body: Bodies;
     onContactEnter?: (info: ContactInfo) => void;
     onContactExit?: (info: ContactInfo) => void;
 }
 interface BodyProps {
-    name: string;
+    name: Bodies;
     type: 'box' | 'sphere' | 'cylinder';
     size: [number, number, number];
     position?: [number, number, number];
@@ -438,20 +477,20 @@ interface MujocoSimAPI {
     step(n?: number): void;
     getTime(): number;
     getTimestep(): number;
-    applyKeyframe(nameOrIndex: string | number): void;
+    applyKeyframe(nameOrIndex: Keyframes | number): void;
     saveState(): StateSnapshot;
     restoreState(snapshot: StateSnapshot): void;
     setQpos(values: Float64Array | number[]): void;
     setQvel(values: Float64Array | number[]): void;
     getQpos(): Float64Array;
     getQvel(): Float64Array;
-    setCtrl(nameOrValues: string | Record<string, number>, value?: number): void;
+    setCtrl(nameOrValues: Actuators | Record<Actuators, number>, value?: number): void;
     getCtrl(): Float64Array;
-    applyForce(bodyName: string, force: THREE.Vector3, point?: THREE.Vector3): void;
-    applyTorque(bodyName: string, torque: THREE.Vector3): void;
-    setExternalForce(bodyName: string, force: THREE.Vector3, torque: THREE.Vector3): void;
+    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;
     applyGeneralizedForce(values: Float64Array | number[]): void;
-    getSensorData(name: string): Float64Array | null;
+    getSensorData(name: Sensors): Float64Array | null;
     getContacts(): ContactInfo[];
     getBodies(): BodyInfo[];
     getJoints(): JointInfo[];
@@ -472,9 +511,9 @@ interface MujocoSimAPI {
         bodyId: number;
         geomId: number;
     } | null;
-    setBodyMass(name: string, mass: number): void;
-    setGeomFriction(name: string, friction: [number, number, number]): void;
-    setGeomSize(name: string, size: [number, number, number]): void;
+    setBodyMass(name: Bodies, mass: number): void;
+    setGeomFriction(name: Geoms, friction: [number, number, number]): void;
+    setGeomSize(name: Geoms, size: [number, number, number]): void;
     readonly mjModelRef: React__default.RefObject<MujocoModel | null>;
     readonly mjDataRef: React__default.RefObject<MujocoData | null>;
 }
@@ -499,10 +538,29 @@ interface MujocoContextValue {
     status: 'loading' | 'ready' | 'error';
     error: string | null;
 }
+/** @deprecated Use `SensorHandle` instead. */
 interface SensorResult {
     value: React__default.RefObject<Float64Array>;
     size: number;
 }
+interface CtrlHandle {
+    /** Read the current ctrl value. */
+    read(): number;
+    /** Write a ctrl value (goes directly to data.ctrl). */
+    write(value: number): void;
+    /** Actuator name. */
+    name: Actuators;
+    /** Actuator control range [min, max]. */
+    range: [number, number];
+}
+interface SensorHandle {
+    /** Read the current sensor data. */
+    read(): Float64Array;
+    /** Sensor dimensionality. */
+    dim: number;
+    /** Sensor name. */
+    name: Sensors;
+}
 interface BodyStateResult {
     position: React__default.RefObject<THREE.Vector3>;
     quaternion: React__default.RefObject<THREE.Quaternion>;
@@ -862,7 +920,7 @@ declare function useActuators(): ActuatorInfo[];
  * Returns reactive refs for a MuJoCo site's world position and orientation.
  * Refs are updated every frame without triggering React re-renders.
  */
-declare function useSitePosition(siteName: string): SitePositionResult;
+declare function useSitePosition(siteName: Sites): SitePositionResult;
 
 /**
  * @license
@@ -885,10 +943,11 @@ declare function useGravityCompensation(enabled?: boolean): void;
  */
 
 /**
- * Access a single MuJoCo sensor by name. Returns a ref-based value
- * updated every physics frame without causing React re-renders.
+ * Access a single MuJoCo sensor by name. Returns a `SensorHandle` with
+ * `read()`, `dim`, and `name`. The backing array is updated every physics
+ * frame without causing React re-renders.
  */
-declare function useSensor(name: string): SensorResult;
+declare function useSensor(name: Sensors): SensorHandle;
 /**
  * Enumerate all sensors in the loaded MuJoCo model.
  * Returns a stable array recomputed only when the model changes.
@@ -910,7 +969,7 @@ declare function useSensors(): SensorInfo[];
  * For ball joints, position is quat (4), velocity is angular vel (3).
  * For free joints, position is pos+quat (7), velocity is lin+ang vel (6).
  */
-declare function useJointState(name: string): JointStateResult;
+declare function useJointState(name: Joints): JointStateResult;
 
 /**
  * @license
@@ -923,22 +982,22 @@ declare function useJointState(name: string): JointStateResult;
  * Track a MuJoCo body's world position, quaternion, and velocities.
  * All values are ref-based — updated every physics frame without re-renders.
  */
-declare function useBodyState(name: string): BodyStateResult;
+declare function useBodyState(name: Bodies): BodyStateResult;
 
 /**
  * @license
  * SPDX-License-Identifier: Apache-2.0
  *
- * useCtrl — clean read/write access to a named actuator's ctrl value (spec 3.1)
+ * useCtrl — handle-based read/write access to a named actuator's ctrl value (spec 3.1)
  */
+
 /**
  * Access a single actuator's control value by name.
  *
- * Returns [currentValue, setValue]:
- * - `currentValue` is a ref updated every frame (no re-renders).
- * - `setValue` writes directly to `data.ctrl[actuatorId]`.
+ * Returns a `CtrlHandle` with `read()` and `write()` methods that
+ * operate directly on `data.ctrl` without causing React re-renders.
  */
-declare function useCtrl(name: string): [React.RefObject<number>, (value: number) => void];
+declare function useCtrl(name: Actuators): CtrlHandle;
 
 /**
  * @license
@@ -953,13 +1012,13 @@ declare function useCtrl(name: string): [React.RefObject<number>, (value: number
  * Calls the callback every physics frame with current contact list.
  * Reads `data.ncon` first to avoid allocating for zero contacts.
  */
-declare function useContacts(bodyName?: string, callback?: (contacts: ContactInfo[]) => void): React.RefObject<ContactInfo[]>;
+declare function useContacts(bodyName?: Bodies, callback?: (contacts: ContactInfo[]) => void): React.RefObject<ContactInfo[]>;
 /**
  * Contact enter/exit events for a specific body (spec 2.5).
  * Tracks which geom pairs are in contact frame-to-frame and fires
  * onEnter/onExit callbacks on transitions.
  */
-declare function useContactEvents(bodyName: string, handlers: {
+declare function useContactEvents(bodyName: Bodies, handlers: {
     onEnter?: (info: ContactInfo) => void;
     onExit?: (info: ContactInfo) => void;
 }): void;
@@ -1195,4 +1254,4 @@ interface CameraAnimationAPI {
  */
 declare function useCameraAnimation(): CameraAnimationAPI;
 
-export { type ActuatorInfo, Body, type BodyInfo, type BodyProps, type BodyStateResult, type CameraAnimationAPI, type ContactInfo, ContactListener, type ContactListenerProps, ContactMarkers, type ControllerComponent, type ControllerOptions, Debug, type DebugProps, DragInteraction, type DragInteractionProps, FlexRenderer, type GeomInfo, type IKSolveFn, type IkConfig, type IkContextValue, IkGizmo, type IkGizmoProps, type JointInfo, type JointStateResult, type KeyBinding, type KeyboardTeleopConfig, 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 PolicyConfig, type RayHit, type SceneConfig, SceneLights, type SceneLightsProps, type SceneMarker, type SceneObject, type SensorInfo, type SensorResult, type SiteInfo, type SitePositionResult, type StateSnapshot, TendonRenderer, type TrajectoryData, type TrajectoryFrame, 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 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, 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 };

package/dist/index.js

@@ -3305,7 +3305,15 @@ function useSensor(name) {
       valueRef.current[i] = data.sensordata[adr + i];
     }
   });
-  return { value: valueRef, size: sensorDimRef.current };
+  return useMemo(() => ({
+    read() {
+      return valueRef.current;
+    },
+    get dim() {
+      return sensorDimRef.current;
+    },
+    name
+  }), [name]);
 }
 function useSensors() {
   const { mjModelRef, status } = useMujocoContext();
@@ -3439,19 +3447,35 @@ function useBodyState(name) {
 function useCtrl(name) {
   const { mjModelRef, mjDataRef, status } = useMujocoContext();
   const actuatorIdRef = useRef(-1);
-  const valueRef = useRef(0);
+  const rangeRef = useRef([0, 0]);
   useEffect(() => {
     const model = mjModelRef.current;
     if (!model || status !== "ready") return;
-    actuatorIdRef.current = findActuatorByName(model, name);
+    const id = findActuatorByName(model, name);
+    actuatorIdRef.current = id;
+    if (id >= 0) {
+      rangeRef.current = [
+        model.actuator_ctrlrange[id * 2],
+        model.actuator_ctrlrange[id * 2 + 1]
+      ];
+    }
   }, [name, status, mjModelRef]);
-  const setValue = useCallback((value) => {
-    const data = mjDataRef.current;
-    if (!data || actuatorIdRef.current < 0) return;
-    data.ctrl[actuatorIdRef.current] = value;
-    valueRef.current = value;
-  }, [mjDataRef]);
-  return [valueRef, setValue];
+  return useMemo(() => ({
+    read() {
+      const data = mjDataRef.current;
+      if (!data || actuatorIdRef.current < 0) return 0;
+      return data.ctrl[actuatorIdRef.current];
+    },
+    write(value) {
+      const data = mjDataRef.current;
+      if (!data || actuatorIdRef.current < 0) return;
+      data.ctrl[actuatorIdRef.current] = value;
+    },
+    name,
+    get range() {
+      return rangeRef.current;
+    }
+  }), [name, mjDataRef]);
 }
 function useKeyboardTeleop(config) {
   const { mjModelRef, mjDataRef, status } = useMujocoContext();
@@ -3975,7 +3999,7 @@ function useCameraAnimation() {
  * @license
  * SPDX-License-Identifier: Apache-2.0
  *
- * useCtrl — clean read/write access to a named actuator's ctrl value (spec 3.1)
+ * useCtrl — handle-based read/write access to a named actuator's ctrl value (spec 3.1)
  */
 /**
  * @license