mujoco-react 8.5.0 → 8.7.0

package/README.md

@@ -18,6 +18,72 @@ 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";
+
+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";
+  }
+}
+```
+
+Once generated, hooks like `useCtrl`, `useSensor`, `useBodyState`, and API methods like `setCtrl`, `applyForce`, `getSensorData` accept the global union. For robot-scoped reusable code, use helpers such as `RobotActuators<"franka">`, `RobotSites<"franka">`, and `RobotBodies<"franka">`. 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 +153,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 = "gripper" satisfies RobotActuators<"franka">;
+const frankaTcp = "tcp" satisfies RobotSites<"franka">;
+
+function FrankaTypedControls() {
+  const gripper = useCtrl(frankaGripper);
+  const ik = useIkController({ siteName: frankaTcp });
+
+  return null;
+}
+```
+
 ## Use the Sim API
 
 ```tsx
@@ -304,23 +387,6 @@ const gripperIk = useIkController({
 });
 ```
 
-## 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.
@@ -344,7 +410,8 @@ const custom: SceneConfig = {
 ```ts
 interface SceneConfig {
   src: string;                      // Base URL for model files
-  sceneFile: string;                // Entry XML file, e.g. "scene.xml"
+  sceneFile: string;                // Entry XML/URDF file, e.g. "scene.xml"
+  files?: File[];                   // Local files for browser upload workflows
   sceneObjects?: SceneObject[];     // Objects injected into scene XML at load time
   homeJoints?: number[];            // Initial joint positions
   xmlPatches?: XmlPatch[];          // Patches applied to XML files during loading
@@ -352,6 +419,30 @@ interface SceneConfig {
 }
 ```
 
+### Local Files and URDF
+
+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
+function ModelUpload() {
+  const sim = useMujoco();
+
+  return (
+    <input
+      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);
+        }
+      }}
+    />
+  );
+}
+```
+
 ### Adding Objects to Any Scene
 
 ```tsx
@@ -552,6 +643,10 @@ Renders tendons as tube geometry from wrap paths.
 
 Renders deformable flex bodies from `flexvert_xpos`.
 
+### `<InstancedGeomRenderer />`
+
+Opt-in renderer for repeated compatible geoms. It batches matching geom shape/material signatures into Three.js `InstancedMesh` objects and syncs instance transforms from `data.geom_xpos` / `data.geom_xmat`.
+
 ### `<ContactListener />`
 
 Component wrapper for contact events:
@@ -861,6 +956,9 @@ The full API object available via `ref` or `useMujoco()` (when `isReady`):
 |--------|-------------|
 | `setGravity(g)` | Set gravity vector |
 | `setTimestep(dt)` | Set timestep |
+| `addBody(body)` | Add a `SceneObject` and recompile the scene |
+| `removeBody(name)` | Remove a generated `SceneObject` and recompile |
+| `recompile(patches?)` | Recompile current scene, optionally appending XML patches |
 | `setBodyMass(name, mass)` | Domain randomization |
 | `setGeomFriction(name, friction)` | Domain randomization |
 | `setGeomSize(name, size)` | Domain randomization |
@@ -878,6 +976,7 @@ The full API object available via `ref` or `useMujoco()` (when `isReady`):
 | Method | Description |
 |--------|-------------|
 | `loadScene(newConfig)` | Runtime model swap |
+| `loadFromFiles(files, options?)` | Load MJCF/URDF from a browser `FileList` |
 
 ## Guides
 
@@ -916,13 +1015,7 @@ Features planned but not yet implemented:
 
 | Feature | Priority | Description |
 |---------|----------|-------------|
-| **User-uploaded model loading** | P2 | `loadFromFiles(FileList)` -- detect meshdir, write to VFS |
-| **URDF loading** | P2 | Load URDF models via MuJoCo's built-in URDF compiler |
-| **XML mutation / recompile** | P1 | `addBody()`, `removeBody()`, `recompile()` for runtime XML editing |
-| **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/mujoco)
 

package/bin/mujoco-react-codegen.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+process.argv.splice(2, 0, 'codegen');
+await import('./mujoco-react.mjs');

package/bin/mujoco-react.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+import { watch } from 'node:fs';
+import path from 'node:path';
+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: { franka: "models/panda/scene.xml" } })],
+  });
+`;
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (!command || command === '--help' || command === '-h') {
+  console.log(usage.trim());
+  process.exit(command ? 0 : 1);
+}
+
+if (command !== 'codegen') {
+  console.error(`Unknown command: ${command}`);
+  console.error(usage.trim());
+  process.exit(1);
+}
+
+const commandArgs = args.slice(1);
+const out = valueAfter(commandArgs, '--out') ?? 'src/mujoco-register.gen.d.ts';
+const moduleName = valueAfter(commandArgs, '--module') ?? 'mujoco-react';
+const shouldWatch = commandArgs.includes('--watch');
+const models = commandArgs.filter((arg, index) => {
+  if (arg.startsWith('--')) return false;
+  const previous = commandArgs[index - 1];
+  return previous !== '--out' && previous !== '--module';
+});
+const modelInput = parseModels(models);
+
+if (!models.length) {
+  console.error(usage.trim());
+  process.exit(1);
+}
+
+let watchedFiles = [];
+await generate();
+
+if (shouldWatch) {
+  console.log('[mujoco-react] watching model files...');
+  let timer;
+  const refreshWatchers = () => {
+    for (const file of watchedFiles) {
+      watch(file, { persistent: true }, () => {
+        clearTimeout(timer);
+        timer = setTimeout(() => {
+          generate().catch((error) => {
+            console.error('[mujoco-react] register generation failed');
+            console.error(error);
+          });
+        }, 50);
+      });
+    }
+  };
+  refreshWatchers();
+}
+
+async function generate() {
+  const result = await generateMujocoRegister({
+    models: modelInput,
+    out,
+    moduleName,
+    root: process.cwd(),
+  });
+  watchedFiles = result.files;
+  const total = Object.values(result.counts).reduce((sum, count) => sum + count, 0);
+  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;
+  return values[index + 1];
+}

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;
@@ -275,11 +296,22 @@ interface XmlPatch {
     injectAfter?: string;
     replace?: [string, string];
 }
+type LocalMujocoFile = File;
+interface LoadFromFilesOptions {
+    /** Entry MJCF/URDF file. Inferred from scene.xml, model.xml, robot.xml, or the first XML/URDF file when omitted. */
+    sceneFile?: string;
+    homeJoints?: number[];
+    xmlPatches?: XmlPatch[];
+    sceneObjects?: SceneObject[];
+    onReset?: (model: MujocoModel, data: MujocoData) => void;
+}
 interface SceneConfig {
     /** Base URL for fetching model files. The loader fetches `src + sceneFile` and follows dependencies. */
     src: string;
-    /** Entry MJCF XML file name, e.g. 'scene.xml'. */
+    /** Entry MJCF XML or URDF file name, e.g. 'scene.xml' or 'robot.urdf'. */
     sceneFile: string;
+    /** Browser-selected files for local MJCF/URDF loading. Preserves webkitRelativePath when available. */
+    files?: readonly LocalMujocoFile[];
     sceneObjects?: SceneObject[];
     homeJoints?: number[];
     xmlPatches?: XmlPatch[];
@@ -610,6 +642,10 @@ interface MujocoSimAPI {
     getKeyframeNames(): string[];
     getKeyframeCount(): number;
     loadScene(newConfig: SceneConfig): Promise<void>;
+    loadFromFiles(files: FileList | readonly LocalMujocoFile[], options?: LoadFromFilesOptions): Promise<void>;
+    addBody(body: SceneObject): Promise<void>;
+    removeBody(name: Bodies): Promise<void>;
+    recompile(patches?: XmlPatch[]): Promise<void>;
     getCanvasSnapshot(width?: number, height?: number, mimeType?: string): string;
     project2DTo3D(x: number, y: number, cameraPos: THREE.Vector3, lookAt: THREE.Vector3): {
         point: THREE.Vector3;
@@ -633,6 +669,7 @@ type MujocoCanvasProps = Omit<CanvasProps, 'onError'> & {
     substeps?: number;
     paused?: boolean;
     speed?: number;
+    interpolate?: boolean;
 };
 interface SitePositionResult {
     position: React__default.RefObject<THREE.Vector3>;
@@ -744,6 +781,8 @@ interface MujocoPhysicsProps {
     paused?: boolean;
     /** Simulation speed multiplier. */
     speed?: number;
+    /** Interpolate rendered body poses between fixed physics steps. */
+    interpolate?: boolean;
     children: React.ReactNode;
 }
 /**
@@ -811,9 +850,10 @@ interface MujocoSimProviderProps {
     substeps?: number;
     paused?: boolean;
     speed?: number;
+    interpolate?: boolean;
     children: React.ReactNode;
 }
-declare function MujocoSimProvider({ mujoco, config, apiRef: externalApiRef, onReady, onError, onStep, onSelection, gravity, timestep, substeps, paused, speed, children, }: MujocoSimProviderProps): react_jsx_runtime.JSX.Element;
+declare function MujocoSimProvider({ mujoco, config, apiRef: externalApiRef, onReady, onError, onStep, onSelection, gravity, timestep, substeps, paused, speed, interpolate, children, }: MujocoSimProviderProps): react_jsx_runtime.JSX.Element;
 
 /**
  * @license
@@ -1043,6 +1083,20 @@ declare function TendonRenderer(props: Omit<ThreeElements['group'], 'ref'>): rea
  */
 declare function FlexRenderer(props: Omit<ThreeElements['group'], 'ref'>): react_jsx_runtime.JSX.Element | null;
 
+interface InstancedGeomRendererProps extends Omit<ThreeElements['group'], 'ref'> {
+    /** Only render geoms from this MuJoCo geom group. */
+    geomGroup?: number;
+    /** Predicate for selecting geoms. */
+    filter?: (geom: GeomInfo) => boolean;
+    /** Optional material override for every instanced batch. */
+    material?: THREE.Material;
+    /** Hide or show the instanced batches. */
+    visible?: boolean;
+    castShadow?: boolean;
+    receiveShadow?: boolean;
+}
+declare function InstancedGeomRenderer({ geomGroup, filter, material, visible, castShadow, receiveShadow, ...groupProps }?: InstancedGeomRendererProps): react_jsx_runtime.JSX.Element | null;
+
 /**
  * @license
  * SPDX-License-Identifier: Apache-2.0
@@ -1450,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, 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 };