mujoco-react 8.5.0 → 8.6.0

package/README.md

@@ -306,10 +306,30 @@ 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:
+Use the Vite plugin to generate TanStack-style declaration merging for actuator, sensor, body, joint, site, geom, and keyframe names:
 
 ```ts
-// e.g. in src/mujoco-register.d.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";
@@ -319,7 +339,13 @@ declare module "mujoco-react" {
 }
 ```
 
-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`.
+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
 
@@ -344,7 +370,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 +379,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 +603,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 +916,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 +936,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 +975,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,86 @@
+#!/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]
+
+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" })],
+  });
+`;
+
+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';
+});
+
+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,
+    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 valueAfter(values, flag) {
+  const index = values.indexOf(flag);
+  if (index === -1) return undefined;
+  return values[index + 1];
+}

package/dist/index.d.ts

@@ -275,11 +275,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 +621,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 +648,7 @@ type MujocoCanvasProps = Omit<CanvasProps, 'onError'> & {
     substeps?: number;
     paused?: boolean;
     speed?: number;
+    interpolate?: boolean;
 };
 interface SitePositionResult {
     position: React__default.RefObject<THREE.Vector3>;
@@ -744,6 +760,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 +829,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 +1062,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 +1483,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 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 };