mujoco-react 8.6.0 → 8.8.0

package/README.md

@@ -18,6 +18,83 @@ Composable [React Three Fiber](https://docs.pmnd.rs/react-three-fiber) wrapper a
 npm install mujoco-react three @react-three/fiber @react-three/drei
 ```
 
+## Vite Plugin and Type-Safe Names
+
+Use the Vite plugin to generate TanStack-style declaration merging for actuator, sensor, body, joint, site, geom, and keyframe names:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { mujocoReact } from "mujoco-react/vite";
+
+export default defineConfig({
+  plugins: [
+    mujocoReact({
+      models: {
+        franka: "models/panda/scene.xml",
+        spot: "models/spot/scene.xml",
+      },
+    }),
+  ],
+});
+```
+
+The plugin writes `src/mujoco-register.gen.d.ts` during dev and build. Commit that generated file:
+
+```ts
+// src/mujoco-register.gen.d.ts
+// Auto-generated by mujoco-react. Do not edit.
+
+import "mujoco-react";
+import type { RobotResource } from "mujoco-react";
+
+declare module "mujoco-react" {
+  interface Register {
+    robots: {
+      franka: {
+        actuators: "joint1" | "joint2" | "joint3" | "gripper";
+        sensors: "force_sensor" | "torque_sensor";
+        bodies: "link0" | "link1" | "hand";
+        joints: "joint1" | "joint2" | "joint3";
+        sites: "tcp";
+        geoms: "floor";
+        keyframes: "home";
+      };
+      spot: {
+        actuators: "fl_hx" | "fl_hy" | "fl_kn";
+        sensors: never;
+        bodies: "body" | "fl_hip" | "fl_uleg";
+        joints: "fl_hx" | "fl_hy" | "fl_kn";
+        sites: never;
+        geoms: "floor";
+        keyframes: "home";
+      };
+    };
+    actuators: "joint1" | "joint2" | "joint3" | "gripper" | "fl_hx" | "fl_hy" | "fl_kn";
+    sensors: "force_sensor" | "torque_sensor";
+    bodies: "link0" | "link1" | "hand" | "body" | "fl_hip" | "fl_uleg";
+  }
+
+  export namespace RobotActuators {
+    export type franka = RobotResource<"franka", "actuators">;
+    export type spot = RobotResource<"spot", "actuators">;
+  }
+
+  export namespace RobotSites {
+    export type franka = RobotResource<"franka", "sites">;
+    export type spot = RobotResource<"spot", "sites">;
+  }
+}
+```
+
+Once generated, hooks like `useCtrl`, `useSensor`, `useBodyState`, and API methods like `setCtrl`, `applyForce`, `getSensorData` accept the global union. For robot-scoped reusable code, use generated namespace types such as `RobotActuators.franka`, `RobotSites.franka`, and `RobotBodies.franka`. Generic helpers like `RobotActuators<"franka">` are still available for reusable library code. When no `Register` augmentation is present, names fall back to `string`.
+
+Non-Vite projects can generate the same file with:
+
+```bash
+npx mujoco-react codegen franka=models/panda/scene.xml spot=models/spot/scene.xml
+```
+
 ## Load a Model
 
 ```tsx
@@ -87,6 +164,23 @@ function MyController() {
 
 Controllers are just React children that read sensors, write `data.ctrl`, apply forces, or call the `MujocoSimAPI` at physics-step time.
 
+With generated resource types, reusable controllers can be scoped to one robot. Configure stable robot keys in the Vite plugin, then use those keys in helper types:
+
+```tsx
+import { useCtrl, useIkController } from "mujoco-react";
+import type { RobotActuators, RobotSites } from "mujoco-react";
+
+const frankaGripper: RobotActuators.franka = "gripper";
+const frankaTcp: RobotSites.franka = "tcp";
+
+function FrankaTypedControls() {
+  const gripper = useCtrl(frankaGripper);
+  const ik = useIkController({ siteName: frankaTcp });
+
+  return null;
+}
+```
+
 ## Use the Sim API
 
 ```tsx
@@ -304,49 +398,6 @@ const gripperIk = useIkController({
 });
 ```
 
-## Type-Safe Resource Names
-
-Use the Vite plugin to generate TanStack-style declaration merging for actuator, sensor, body, joint, site, geom, and keyframe names:
-
-```ts
-// vite.config.ts
-import { defineConfig } from "vite";
-import { mujocoReact } from "mujoco-react/vite";
-
-export default defineConfig({
-  plugins: [
-    mujocoReact({
-      models: "models/panda/scene.xml",
-    }),
-  ],
-});
-```
-
-The plugin writes `src/mujoco-register.gen.d.ts` during dev and build. Commit that generated file:
-
-```ts
-// src/mujoco-register.gen.d.ts
-// Auto-generated by mujoco-react. Do not edit.
-
-import "mujoco-react";
-
-declare module "mujoco-react" {
-  interface Register {
-    actuators: "joint1" | "joint2" | "joint3" | "gripper";
-    sensors: "force_sensor" | "torque_sensor";
-    bodies: "link0" | "link1" | "hand";
-  }
-}
-```
-
-Once generated, hooks like `useCtrl`, `useSensor`, `useBodyState`, and API methods like `setCtrl`, `applyForce`, `getSensorData` will only accept the declared names. When no `Register` augmentation is present, names fall back to `string`.
-
-Non-Vite projects can generate the same file with:
-
-```bash
-npx mujoco-react codegen models/panda/scene.xml
-```
-
 ## 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.
@@ -384,15 +435,22 @@ interface SceneConfig {
 Load browser-selected MJCF or URDF files directly. Folder uploads preserve `webkitRelativePath`, and flat uploads fall back to matching referenced mesh/texture assets by basename:
 
 ```tsx
+import { useEffect, useRef } from "react";
+import { useMujoco } from "mujoco-react";
+
 function ModelUpload() {
   const sim = useMujoco();
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  useEffect(() => {
+    inputRef.current?.setAttribute("webkitdirectory", "");
+  }, []);
 
   return (
     <input
+      ref={inputRef}
       type="file"
       multiple
-      // @ts-expect-error Chromium/WebKit folder uploads
-      webkitdirectory=""
       onChange={(event) => {
         if (sim.isReady && event.currentTarget.files) {
           sim.api.loadFromFiles(event.currentTarget.files);

package/bin/mujoco-react.mjs

@@ -6,13 +6,14 @@ import { generateMujocoRegister } from '../dist/vite.js';
 const usage = `
 Usage:
   mujoco-react codegen <scene.xml> [...more.xml] [--out src/mujoco-register.gen.d.ts] [--watch]
+  mujoco-react codegen franka=models/panda/scene.xml spot=models/spot/scene.xml
 
 Vite users usually do not need this command. Prefer:
 
   import { mujocoReact } from "mujoco-react/vite";
 
   export default defineConfig({
-    plugins: [mujocoReact({ models: "models/panda/scene.xml" })],
+    plugins: [mujocoReact({ models: { franka: "models/panda/scene.xml" } })],
   });
 `;
 
@@ -39,6 +40,7 @@ const models = commandArgs.filter((arg, index) => {
   const previous = commandArgs[index - 1];
   return previous !== '--out' && previous !== '--module';
 });
+const modelInput = parseModels(models);
 
 if (!models.length) {
   console.error(usage.trim());
@@ -69,7 +71,7 @@ if (shouldWatch) {
 
 async function generate() {
   const result = await generateMujocoRegister({
-    models,
+    models: modelInput,
     out,
     moduleName,
     root: process.cwd(),
@@ -79,6 +81,16 @@ async function generate() {
   console.log(`[mujoco-react] generated ${path.relative(process.cwd(), result.out)} (${total} names)`);
 }
 
+function parseModels(values) {
+  if (values.every((value) => value.includes('='))) {
+    return Object.fromEntries(values.map((value) => {
+      const index = value.indexOf('=');
+      return [value.slice(0, index), value.slice(index + 1)];
+    }));
+  }
+  return values;
+}
+
 function valueAfter(values, flag) {
   const index = values.indexOf(flag);
   if (index === -1) return undefined;

package/dist/index.d.ts

@@ -16,6 +16,13 @@ import * as THREE from 'three';
  * ```ts
  * declare module 'mujoco-react' {
  *   interface Register {
+ *     robots: {
+ *       panda: {
+ *         actuators: 'joint1' | 'joint2' | 'gripper';
+ *         sensors: 'force_sensor' | 'torque_sensor';
+ *         bodies: 'link0' | 'link1' | 'hand';
+ *       };
+ *     };
  *     actuators: 'joint1' | 'joint2' | 'gripper';
  *     sensors: 'force_sensor' | 'torque_sensor';
  *     bodies: 'link0' | 'link1' | 'hand';
@@ -27,6 +34,20 @@ import * as THREE from 'three';
  */
 interface Register {
 }
+type RegisteredRobotMap = Register extends {
+    robots: infer T extends Record<string, Record<string, string>>;
+} ? T : never;
+type Robots = [RegisteredRobotMap] extends [never] ? string : Extract<keyof RegisteredRobotMap, string>;
+type RobotResource<TRobot extends string, TKey extends string> = [
+    RegisteredRobotMap
+] extends [never] ? string : TRobot extends keyof RegisteredRobotMap ? TKey extends keyof RegisteredRobotMap[TRobot] ? RegisteredRobotMap[TRobot][TKey] : string : never;
+type RobotActuators<TRobot extends string> = RobotResource<TRobot, 'actuators'>;
+type RobotSensors<TRobot extends string> = RobotResource<TRobot, 'sensors'>;
+type RobotBodies<TRobot extends string> = RobotResource<TRobot, 'bodies'>;
+type RobotJoints<TRobot extends string> = RobotResource<TRobot, 'joints'>;
+type RobotSites<TRobot extends string> = RobotResource<TRobot, 'sites'>;
+type RobotGeoms<TRobot extends string> = RobotResource<TRobot, 'geoms'>;
+type RobotKeyframes<TRobot extends string> = RobotResource<TRobot, 'keyframes'>;
 type Actuators = Register extends {
     actuators: infer T extends string;
 } ? T : string;
@@ -1483,4 +1504,4 @@ interface CameraAnimationAPI {
  */
 declare function useCameraAnimation(): CameraAnimationAPI;
 
-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, InstancedGeomRenderer, 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 ObservationConfig, type ObservationHandle, type ObservationLayoutItem, type ObservationOutput, type ObservationResult, 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, buildObservation, 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, useObservation, 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, InstancedGeomRenderer, 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 ObservationConfig, type ObservationHandle, type ObservationLayoutItem, type ObservationOutput, type ObservationResult, type PhysicsConfig, type PhysicsStepCallback, type PlaybackState, type PolicyConfig, type RayHit, type Register, type RegisteredRobotMap, type ResourceSelector, type RobotActuators, type RobotBodies, type RobotGeoms, type RobotJoints, type RobotKeyframes, type RobotResource, type RobotSensors, type RobotSites, type Robots, 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, buildObservation, 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, useObservation, usePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePosition, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder };