mujoco-react 4.0.0 → 6.0.0

package/README.md

@@ -27,7 +27,7 @@ import type { SceneConfig } from 'mujoco-react';
 import { OrbitControls } from '@react-three/drei';
 
 const config: SceneConfig = {
-  modelId: 'franka_emika_panda',
+  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],
 };
@@ -178,39 +178,28 @@ const ikCtx = useIk({ optional: true });
 
 ## Loading Models
 
-Models are loaded from any HTTP source via `SceneConfig.baseUrl`. Defaults to [MuJoCo Menagerie](https://github.com/google-deepmind/mujoco_menagerie) on GitHub.
+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.
 
 ```tsx
-// Menagerie models: just set modelId
+// MuJoCo Menagerie
 const franka: SceneConfig = {
-  modelId: 'franka_emika_panda',
+  src: 'https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/franka_emika_panda/',
   sceneFile: 'scene.xml',
 };
 
-// Any GitHub repo
-const so101: SceneConfig = {
-  modelId: 'so101',
-  sceneFile: 'SO101.xml',
-  baseUrl: 'https://raw.githubusercontent.com/your-org/your-repo/main/models/',
-};
-
-// Self-hosted
+// Any URL
 const custom: SceneConfig = {
-  modelId: 'my_robot',
-  sceneFile: 'robot.xml',
-  baseUrl: 'http://localhost:3000/models/my_robot/',
+  src: 'http://localhost:3000/models/my_model/',
+  sceneFile: 'model.xml',
 };
 ```
 
-The loader fetches the scene XML, parses it for dependencies (meshes, textures, includes), recursively fetches those too, applies any XML patches, and writes everything to MuJoCo's in-memory WASM filesystem.
-
 ## SceneConfig
 
 ```ts
 interface SceneConfig {
-  modelId: string;                  // e.g. 'franka_emika_panda'
+  src: string;                      // Base URL for model files
   sceneFile: string;                // Entry XML file, e.g. 'scene.xml'
-  baseUrl?: string;                 // Base URL for fetching model files
   sceneObjects?: SceneObject[];     // Objects injected into scene XML at load time
   homeJoints?: number[];            // Initial joint positions
   xmlPatches?: XmlPatch[];          // Patches applied to XML files during loading
@@ -222,7 +211,7 @@ interface SceneConfig {
 
 ```tsx
 const config: SceneConfig = {
-  modelId: 'franka_emika_panda',
+  src: 'https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/franka_emika_panda/',
   sceneFile: 'scene.xml',
   sceneObjects: [
     { name: 'ball', type: 'sphere', size: [0.03, 0.03, 0.03],
@@ -376,10 +365,6 @@ Component wrapper for contact events:
 />
 ```
 
-### `<SelectionHighlight />`
-
-Emissive highlight on selected body meshes. Also available as `useSelectionHighlight(bodyId, options?)` hook.
-
 ### `<TrajectoryPlayer />`
 
 Plays back recorded qpos trajectories with scrubbing.
@@ -566,9 +551,19 @@ Returns actuator metadata for building control UIs.
 
 Ref-based site position/quaternion tracking.
 
+### `useBodyMeshes(bodyId)`
+
+Returns the Three.js meshes belonging to a MuJoCo body. Use for custom selection visuals, outlines, postprocessing, or any per-body mesh manipulation:
+
+```tsx
+const meshes = useBodyMeshes(selectedBodyId);
+
+// Use with drei Outline, or manipulate materials directly
+```
+
 ### `useSelectionHighlight(bodyId, options?)`
 
-Hook form of `<SelectionHighlight>`. Apply emissive highlights imperatively:
+Convenience wrapper around `useBodyMeshes` that applies an emissive highlight:
 
 ```tsx
 useSelectionHighlight(selectedBodyId, { color: '#00ff00', emissiveIntensity: 0.5 });
@@ -670,12 +665,13 @@ Objects that need stable contact (grasping, stacking, etc.) require tuned MuJoCo
 
 ### Click-to-Select
 
-Combine R3F raycasting with `<SelectionHighlight />` for body selection:
+Combine R3F raycasting with `useSelectionHighlight` for body selection:
 
 ```tsx
 function ClickSelectOverlay() {
   const selectedBodyId = useClickSelect(); // your raycasting hook
-  return <SelectionHighlight bodyId={selectedBodyId} />;
+  useSelectionHighlight(selectedBodyId);
+  return null;
 }
 ```
 

package/dist/index.d.ts

@@ -233,9 +233,10 @@ interface XmlPatch {
     replace?: [string, string];
 }
 interface SceneConfig {
-    modelId: string;
+    /** 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'. */
     sceneFile: string;
-    baseUrl?: string;
     sceneObjects?: SceneObject[];
     homeJoints?: number[];
     xmlPatches?: XmlPatch[];
@@ -392,11 +393,6 @@ interface TrajectoryPlayerProps {
     playing?: boolean;
     onFrame?: (frameIdx: number) => void;
 }
-interface SelectionHighlightProps {
-    bodyId: number | null;
-    color?: string;
-    emissiveIntensity?: number;
-}
 interface ContactListenerProps {
     body: string;
     onContactEnter?: (info: ContactInfo) => void;
@@ -815,19 +811,6 @@ declare function ContactListener({ body, onContactEnter, onContactExit, }: Conta
  */
 declare function TrajectoryPlayer({ trajectory, fps, loop, playing, onFrame, }: TrajectoryPlayerProps): null;
 
-/**
- * @license
- * SPDX-License-Identifier: Apache-2.0
- *
- * SelectionHighlight — highlight a selected body with emissive color (spec 6.5)
- */
-
-/**
- * Applies emissive highlight to all meshes belonging to a body.
- * Restores original emissive when bodyId changes or component unmounts.
- */
-declare function SelectionHighlight({ bodyId, color, emissiveIntensity, }: SelectionHighlightProps): null;
-
 /**
  * @license
  * SPDX-License-Identifier: Apache-2.0
@@ -1113,10 +1096,37 @@ declare function useCtrlNoise(config?: CtrlNoiseConfig): void;
  * @license
  * SPDX-License-Identifier: Apache-2.0
  *
- * useSelectionHighlight — hook form of SelectionHighlight (spec 6.5)
+ * useBodyMeshes — returns Three.js meshes belonging to a MuJoCo body.
+ *
+ * Low-level primitive for custom selection visuals, outlines,
+ * postprocessing effects, or any per-body mesh manipulation.
+ */
+
+/**
+ * Returns all Three.js meshes belonging to the given MuJoCo body ID.
+ *
+ * @example
+ * ```tsx
+ * const meshes = useBodyMeshes(selectedBodyId);
+ *
+ * // Use with drei Outline
+ * <Outline selection={meshes} />
+ *
+ * // Or manipulate directly
+ * useFrame(() => {
+ *   meshes.forEach(m => { m.scale.setScalar(1.05); });
+ * });
+ * ```
+ */
+declare function useBodyMeshes(bodyId: number | null): THREE.Mesh[];
+
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * useSelectionHighlight — convenience hook for emissive body highlights.
  *
- * Applies emissive highlight to all meshes belonging to a body.
- * Restores original emissive when bodyId changes or hook unmounts.
+ * Built on useBodyMeshes. For custom visuals, use useBodyMeshes directly.
  */
 declare function useSelectionHighlight(bodyId: number | null, options?: {
     color?: string;
@@ -1154,4 +1164,4 @@ interface CameraAnimationAPI {
  */
 declare function useCameraAnimation(): CameraAnimationAPI;
 
-export { type ActuatorInfo, type BodyInfo, 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, IkController, 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, SelectionHighlight, type SelectionHighlightProps, 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, useBodyState, useCameraAnimation, useContactEvents, useContacts, useCtrl, useCtrlNoise, useGamepad, useGravityCompensation, useIk, useJointState, useKeyboardTeleop, useMujoco, useMujocoWasm, usePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePosition, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder };
+export { type ActuatorInfo, type BodyInfo, 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, IkController, 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, useIk, useJointState, useKeyboardTeleop, useMujoco, useMujocoWasm, usePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePosition, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder };

package/dist/index.js

@@ -400,7 +400,7 @@ async function loadScene(mujoco, config, onProgress) {
     mujoco.FS.mkdir("/working");
   } catch {
   }
-  const baseUrl = config.baseUrl || `https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/${config.modelId}/`;
+  const baseUrl = config.src.endsWith("/") ? config.src : config.src + "/";
   const downloaded = /* @__PURE__ */ new Set();
   const queue = [config.sceneFile];
   const parser = new DOMParser();
@@ -3053,58 +3053,6 @@ function TrajectoryPlayer({
   });
   return null;
 }
-function useSelectionHighlight(bodyId, options = {}) {
-  const { color = "#ff4444", emissiveIntensity = 0.3 } = options;
-  const { scene } = useThree();
-  const prevMeshesRef = useRef([]);
-  useEffect(() => {
-    for (const entry of prevMeshesRef.current) {
-      const mat = entry.mesh.material;
-      if (mat.emissive) {
-        mat.emissive.copy(entry.originalEmissive);
-        mat.emissiveIntensity = entry.originalIntensity;
-      }
-    }
-    prevMeshesRef.current = [];
-    if (bodyId === null || bodyId < 0) return;
-    const highlightColor = new THREE11.Color(color);
-    scene.traverse((obj) => {
-      if (obj.userData.bodyID === bodyId && obj.isMesh) {
-        const mesh = obj;
-        const mat = mesh.material;
-        if (mat.emissive) {
-          prevMeshesRef.current.push({
-            mesh,
-            originalEmissive: mat.emissive.clone(),
-            originalIntensity: mat.emissiveIntensity ?? 0
-          });
-          mat.emissive.copy(highlightColor);
-          mat.emissiveIntensity = emissiveIntensity;
-        }
-      }
-    });
-    return () => {
-      for (const entry of prevMeshesRef.current) {
-        const mat = entry.mesh.material;
-        if (mat.emissive) {
-          mat.emissive.copy(entry.originalEmissive);
-          mat.emissiveIntensity = entry.originalIntensity;
-        }
-      }
-      prevMeshesRef.current = [];
-    };
-  }, [bodyId, color, emissiveIntensity, scene]);
-}
-
-// src/components/SelectionHighlight.tsx
-function SelectionHighlight({
-  bodyId,
-  color = "#ff4444",
-  emissiveIntensity = 0.3
-}) {
-  useSelectionHighlight(bodyId, { color, emissiveIntensity });
-  return null;
-}
 function useActuators() {
   const { mjModelRef, status } = useMujoco();
   return useMemo(() => {
@@ -3651,6 +3599,57 @@ function useCtrlNoise(config = {}) {
     }
   });
 }
+function useBodyMeshes(bodyId) {
+  const { scene } = useThree();
+  return useMemo(() => {
+    if (bodyId === null || bodyId < 0) return [];
+    const meshes = [];
+    scene.traverse((obj) => {
+      if (obj.userData.bodyID === bodyId && obj.isMesh) {
+        meshes.push(obj);
+      }
+    });
+    return meshes;
+  }, [bodyId, scene]);
+}
+function useSelectionHighlight(bodyId, options = {}) {
+  const { color = "#ff4444", emissiveIntensity = 0.3 } = options;
+  const meshes = useBodyMeshes(bodyId);
+  const prevRef = useRef([]);
+  useEffect(() => {
+    for (const entry of prevRef.current) {
+      const mat = entry.mesh.material;
+      if (mat.emissive) {
+        mat.emissive.copy(entry.originalEmissive);
+        mat.emissiveIntensity = entry.originalIntensity;
+      }
+    }
+    prevRef.current = [];
+    const highlightColor = new THREE11.Color(color);
+    for (const mesh of meshes) {
+      const mat = mesh.material;
+      if (mat.emissive) {
+        prevRef.current.push({
+          mesh,
+          originalEmissive: mat.emissive.clone(),
+          originalIntensity: mat.emissiveIntensity ?? 0
+        });
+        mat.emissive.copy(highlightColor);
+        mat.emissiveIntensity = emissiveIntensity;
+      }
+    }
+    return () => {
+      for (const entry of prevRef.current) {
+        const mat = entry.mesh.material;
+        if (mat.emissive) {
+          mat.emissive.copy(entry.originalEmissive);
+          mat.emissiveIntensity = entry.originalIntensity;
+        }
+      }
+      prevRef.current = [];
+    };
+  }, [meshes, color, emissiveIntensity]);
+}
 function useCameraAnimation() {
   const { camera } = useThree();
   const orbitTargetRef = useRef(new THREE11.Vector3(0, 0, 0));
@@ -3825,21 +3824,6 @@ function useCameraAnimation() {
  *
  * TrajectoryPlayer — component form of trajectory playback (spec 13.2)
  */
-/**
- * @license
- * SPDX-License-Identifier: Apache-2.0
- *
- * useSelectionHighlight — hook form of SelectionHighlight (spec 6.5)
- *
- * Applies emissive highlight to all meshes belonging to a body.
- * Restores original emissive when bodyId changes or hook unmounts.
- */
-/**
- * @license
- * SPDX-License-Identifier: Apache-2.0
- *
- * SelectionHighlight — highlight a selected body with emissive color (spec 6.5)
- */
 /**
  * @license
  * SPDX-License-Identifier: Apache-2.0
@@ -3900,6 +3884,23 @@ function useCameraAnimation() {
  *
  * useCtrlNoise — control noise / perturbation hook (spec 3.2)
  */
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * useBodyMeshes — returns Three.js meshes belonging to a MuJoCo body.
+ *
+ * Low-level primitive for custom selection visuals, outlines,
+ * postprocessing effects, or any per-body mesh manipulation.
+ */
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * useSelectionHighlight — convenience hook for emissive body highlights.
+ *
+ * Built on useBodyMeshes. For custom visuals, use useBodyMeshes directly.
+ */
 /**
  * @license
  * SPDX-License-Identifier: Apache-2.0
@@ -3907,6 +3908,6 @@ function useCameraAnimation() {
  * useCameraAnimation — composable camera animation hook.
  */
 
-export { ContactListener, ContactMarkers, Debug, DragInteraction, FlexRenderer, IkController, IkGizmo, MujocoCanvas, MujocoPhysics, MujocoProvider, MujocoSimProvider, SceneLights, SelectionHighlight, TendonRenderer, TrajectoryPlayer, createController, findActuatorByName, findBodyByName, findGeomByName, findJointByName, findKeyframeByName, findSensorByName, findSiteByName, findTendonByName, getContact, getName, loadScene, useActuators, useAfterPhysicsStep, useBeforePhysicsStep, useBodyState, useCameraAnimation, useContactEvents, useContacts, useCtrl, useCtrlNoise, useGamepad, useGravityCompensation, useIk, useJointState, useKeyboardTeleop, useMujoco, useMujocoWasm, usePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePosition, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder };
+export { ContactListener, ContactMarkers, Debug, DragInteraction, FlexRenderer, IkController, IkGizmo, MujocoCanvas, MujocoPhysics, MujocoProvider, MujocoSimProvider, SceneLights, TendonRenderer, TrajectoryPlayer, createController, findActuatorByName, findBodyByName, findGeomByName, findJointByName, findKeyframeByName, findSensorByName, findSiteByName, findTendonByName, getContact, getName, loadScene, useActuators, useAfterPhysicsStep, useBeforePhysicsStep, useBodyMeshes, useBodyState, useCameraAnimation, useContactEvents, useContacts, useCtrl, useCtrlNoise, useGamepad, useGravityCompensation, useIk, useJointState, useKeyboardTeleop, useMujoco, useMujocoWasm, usePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePosition, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map