mujoco-react 0.2.0 → 1.0.0

package/src/components/TendonRenderer.tsx

@@ -11,20 +11,27 @@
  * Tendons use a default color and width.
  */
 
-import { useRef } from 'react';
+import { useEffect, useRef } from 'react';
 import { useFrame } from '@react-three/fiber';
+import type { ThreeElements } from '@react-three/fiber';
 import * as THREE from 'three';
 import { useMujocoSim } from '../core/MujocoSimProvider';
 
 const DEFAULT_TENDON_COLOR = new THREE.Color(0.3, 0.3, 0.8);
 const DEFAULT_TENDON_WIDTH = 0.002;
 
-export function TendonRenderer() {
+// Preallocated temp vector to avoid per-frame allocations
+const _tmpVec = new THREE.Vector3();
+
+export function TendonRenderer(props: Omit<ThreeElements['group'], 'ref'>) {
   const { mjModelRef, mjDataRef, status } = useMujocoSim();
   const groupRef = useRef<THREE.Group>(null);
   const meshesRef = useRef<THREE.Mesh[]>([]);
+  const curvesRef = useRef<THREE.CatmullRomCurve3[]>([]);
+  const materialRef = useRef<THREE.MeshStandardMaterial | null>(null);
 
-  useFrame(() => {
+  // Build tendon meshes once when model loads
+  useEffect(() => {
     const model = mjModelRef.current;
     const data = mjDataRef.current;
     const group = groupRef.current;
@@ -33,52 +40,110 @@ export function TendonRenderer() {
     const ntendon = model.ntendon ?? 0;
     if (ntendon === 0) return;
 
-    // Clean up old meshes
-    for (const mesh of meshesRef.current) {
-      group.remove(mesh);
-      mesh.geometry.dispose();
-      (mesh.material as THREE.Material).dispose();
+    // Shared material for all tendons
+    const material = new THREE.MeshStandardMaterial({
+      color: DEFAULT_TENDON_COLOR,
+      roughness: 0.6,
+      metalness: 0.1,
+    });
+    materialRef.current = material;
+
+    const meshes: THREE.Mesh[] = [];
+    const curves: THREE.CatmullRomCurve3[] = [];
+
+    for (let t = 0; t < ntendon; t++) {
+      const wrapNum = model.ten_wrapnum[t];
+      if (wrapNum < 2) {
+        meshes.push(null!);
+        curves.push(null!);
+        continue;
+      }
+
+      // Initial dummy points — will be overwritten in useFrame
+      const points = Array.from({ length: wrapNum }, () => new THREE.Vector3());
+      const curve = new THREE.CatmullRomCurve3(points, false);
+      const segments = Math.max(wrapNum * 2, 4);
+      const geometry = new THREE.TubeGeometry(curve, segments, DEFAULT_TENDON_WIDTH, 6, false);
+      const mesh = new THREE.Mesh(geometry, material);
+      mesh.frustumCulled = false;
+      group.add(mesh);
+      meshes.push(mesh);
+      curves.push(curve);
     }
-    meshesRef.current = [];
+
+    meshesRef.current = meshes;
+    curvesRef.current = curves;
+
+    return () => {
+      for (const mesh of meshes) {
+        if (!mesh) continue;
+        group.remove(mesh);
+        mesh.geometry.dispose();
+      }
+      material.dispose();
+      meshesRef.current = [];
+      curvesRef.current = [];
+      materialRef.current = null;
+    };
+  }, [status, mjModelRef, mjDataRef]);
+
+  // Update curve control points and rebuild geometry each frame
+  useFrame(() => {
+    const model = mjModelRef.current;
+    const data = mjDataRef.current;
+    if (!model || !data) return;
+
+    const ntendon = model.ntendon ?? 0;
+    const meshes = meshesRef.current;
+    const curves = curvesRef.current;
 
     for (let t = 0; t < ntendon; t++) {
+      const mesh = meshes[t];
+      const curve = curves[t];
+      if (!mesh || !curve) continue;
+
       const wrapAdr = model.ten_wrapadr[t];
       const wrapNum = model.ten_wrapnum[t];
-      if (wrapNum < 2) continue;
 
-      // Get wrap path points from data
-      const points: THREE.Vector3[] = [];
+      // Update existing control points in-place
+      let validCount = 0;
       for (let w = 0; w < wrapNum; w++) {
         const idx = (wrapAdr + w) * 3;
         if (data.wrap_xpos && idx + 2 < data.wrap_xpos.length) {
           const x = data.wrap_xpos[idx];
           const y = data.wrap_xpos[idx + 1];
           const z = data.wrap_xpos[idx + 2];
-          // Skip zero points (uninitialized wrap points)
           if (x !== 0 || y !== 0 || z !== 0) {
-            points.push(new THREE.Vector3(x, y, z));
+            if (validCount < curve.points.length) {
+              curve.points[validCount].set(x, y, z);
+            }
+            validCount++;
           }
         }
       }
 
-      if (points.length < 2) continue;
+      if (validCount < 2) {
+        mesh.visible = false;
+        continue;
+      }
 
-      const curve = new THREE.CatmullRomCurve3(points, false);
-      const geometry = new THREE.TubeGeometry(
-        curve, Math.max(points.length * 2, 4), DEFAULT_TENDON_WIDTH, 6, false
-      );
+      // Trim or pad points array to match valid count
+      if (curve.points.length !== validCount) {
+        curve.points.length = validCount;
+        while (curve.points.length < validCount) {
+          curve.points.push(new THREE.Vector3());
+        }
+      }
 
-      const material = new THREE.MeshStandardMaterial({
-        color: DEFAULT_TENDON_COLOR,
-        roughness: 0.6,
-        metalness: 0.1,
-      });
-      const mesh = new THREE.Mesh(geometry, material);
-      group.add(mesh);
-      meshesRef.current.push(mesh);
+      // Rebuild geometry from updated curve
+      mesh.geometry.dispose();
+      mesh.geometry = new THREE.TubeGeometry(
+        curve, Math.max(validCount * 2, 4), DEFAULT_TENDON_WIDTH, 6, false
+      );
+      mesh.visible = true;
     }
   });
 
   if (status !== 'ready') return null;
-  return <group ref={groupRef} />;
+  return <group {...props} ref={groupRef} />;
 }

package/src/components/TrajectoryPlayer.tsx

@@ -5,7 +5,8 @@
  * TrajectoryPlayer — component form of trajectory playback (spec 13.2)
  */
 
-import { useEffect } from 'react';
+import { useEffect, useRef } from 'react';
+import { useFrame } from '@react-three/fiber';
 import { useTrajectoryPlayer } from '../hooks/useTrajectoryPlayer';
 import type { TrajectoryPlayerProps } from '../types';
 
@@ -21,6 +22,9 @@ export function TrajectoryPlayer({
   onFrame,
 }: TrajectoryPlayerProps) {
   const player = useTrajectoryPlayer(trajectory, { fps, loop });
+  const onFrameRef = useRef(onFrame);
+  onFrameRef.current = onFrame;
+  const lastReportedFrameRef = useRef(-1);
 
   useEffect(() => {
     if (playing) {
@@ -28,17 +32,17 @@ export function TrajectoryPlayer({
     } else {
       player.pause();
     }
-  }, [playing]);
+  }, [playing, player]);
 
-  useEffect(() => {
-    if (onFrame) {
-      // Poll frame changes (lightweight, no extra useFrame needed)
-      const interval = setInterval(() => {
-        if (player.playing) onFrame(player.frame);
-      }, 1000 / fps);
-      return () => clearInterval(interval);
+  // Use useFrame instead of setInterval to sync with the render loop
+  useFrame(() => {
+    if (!onFrameRef.current) return;
+    const currentFrame = player.frame;
+    if (currentFrame !== lastReportedFrameRef.current && player.playing) {
+      lastReportedFrameRef.current = currentFrame;
+      onFrameRef.current(currentFrame);
     }
-  }, [onFrame, fps]);
+  });
 
   return null;
 }

package/src/core/IkContext.tsx

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * IkContext — React context for the IK controller plugin.
+ */
+
+import { createContext, useContext } from 'react';
+import * as THREE from 'three';
+
+export interface IkContextValue {
+  ikEnabledRef: React.RefObject<boolean>;
+  ikCalculatingRef: React.RefObject<boolean>;
+  ikTargetRef: React.RefObject<THREE.Group>;
+  siteIdRef: React.RefObject<number>;
+  setIkEnabled(enabled: boolean): void;
+  moveTarget(pos: THREE.Vector3, duration?: number): void;
+  syncTargetToSite(): void;
+  solveIK(pos: THREE.Vector3, quat: THREE.Quaternion, currentQ: number[]): number[] | null;
+  getGizmoStats(): { pos: THREE.Vector3; rot: THREE.Euler } | null;
+}
+
+export const IkContext = createContext<IkContextValue | null>(null);
+
+/**
+ * Access the IK controller context.
+ *
+ * - `useIk()` — throws if no `<IkController>` ancestor (use inside `<IkController>`)
+ * - `useIk({ optional: true })` — returns `null` if no ancestor (use in components
+ *   that optionally interact with IK, e.g. keyboard controllers that disable IK)
+ */
+export function useIk(): IkContextValue;
+export function useIk(options: { optional: true }): IkContextValue | null;
+export function useIk(options?: { optional?: boolean }): IkContextValue | null {
+  const ctx = useContext(IkContext);
+  if (!ctx && !options?.optional) {
+    throw new Error('useIk() must be used inside an <IkController>');
+  }
+  return ctx;
+}

package/src/core/MujocoCanvas.tsx

@@ -24,15 +24,12 @@ export const MujocoCanvas = forwardRef<MujocoSimAPI, MujocoCanvasProps>(
       onError,
       onStep,
       onSelection,
-      // Declarative physics config (spec 1.1)
+      // Declarative physics config
       gravity,
       timestep,
       substeps,
       paused,
       speed,
-      interpolate,
-      gravityCompensation,
-      mjcfLights,
       children,
       ...canvasProps
     },
@@ -65,7 +62,6 @@ export const MujocoCanvas = forwardRef<MujocoSimAPI, MujocoCanvasProps>(
           substeps={substeps}
           paused={paused}
           speed={speed}
-          interpolate={interpolate}
         >
           {children}
         </MujocoSimProvider>

package/src/core/MujocoPhysics.tsx

@@ -0,0 +1,79 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { forwardRef, useEffect } from 'react';
+import { useMujoco } from './MujocoProvider';
+import { MujocoSimProvider } from './MujocoSimProvider';
+import type { MujocoSimAPI, SceneConfig } from '../types';
+
+export interface MujocoPhysicsProps {
+  /** Scene/robot configuration. */
+  config: SceneConfig;
+  /** Fires when model is loaded and API is ready. */
+  onReady?: (api: MujocoSimAPI) => void;
+  /** Fires on scene load failure. */
+  onError?: (error: Error) => void;
+  /** Called each physics step. */
+  onStep?: (time: number) => void;
+  /** Called on body double-click selection. */
+  onSelection?: (bodyId: number, name: string) => void;
+  /** Override model gravity. */
+  gravity?: [number, number, number];
+  /** Override model.opt.timestep. */
+  timestep?: number;
+  /** mj_step calls per frame. */
+  substeps?: number;
+  /** Declarative pause. */
+  paused?: boolean;
+  /** Simulation speed multiplier. */
+  speed?: number;
+  children: React.ReactNode;
+}
+
+/**
+ * MujocoPhysics — physics provider for use inside a user-owned R3F Canvas.
+ *
+ * This is the R3F-idiomatic alternative to MujocoCanvas. Instead of wrapping
+ * the Canvas, place this inside your own <Canvas>:
+ *
+ * ```tsx
+ * <MujocoProvider>
+ *   <Canvas shadows camera={...}>
+ *     <MujocoPhysics config={config} paused={paused}>
+ *       <SceneRenderer />
+ *       <OrbitControls />
+ *     </MujocoPhysics>
+ *   </Canvas>
+ * </MujocoProvider>
+ * ```
+ *
+ * Forward ref exposes MujocoSimAPI.
+ */
+export const MujocoPhysics = forwardRef<MujocoSimAPI, MujocoPhysicsProps>(
+  function MujocoPhysics({ onError, children, ...props }, ref) {
+    const { mujoco, status: wasmStatus, error: wasmError } = useMujoco();
+
+    useEffect(() => {
+      if (wasmStatus === 'error' && onError) {
+        onError(new Error(wasmError ?? 'WASM load failed'));
+      }
+    }, [wasmStatus, wasmError, onError]);
+
+    if (wasmStatus === 'error' || wasmStatus === 'loading' || !mujoco) {
+      return null;
+    }
+
+    return (
+      <MujocoSimProvider
+        mujoco={mujoco}
+        apiRef={ref}
+        onError={onError}
+        {...props}
+      >
+        {children}
+      </MujocoSimProvider>
+    );
+  }
+);

package/src/core/MujocoProvider.tsx

@@ -22,6 +22,8 @@ export function useMujoco(): MujocoContextValue {
 
 interface MujocoProviderProps {
   wasmUrl?: string;
+  /** Timeout in ms for WASM module load. Default: 30000. */
+  timeout?: number;
   children: React.ReactNode;
   onError?: (error: Error) => void;
 }
@@ -30,7 +32,7 @@ interface MujocoProviderProps {
  * MujocoProvider — WASM / module lifecycle.
  * Loads the MuJoCo WASM module on mount and provides it to children via context.
  */
-export function MujocoProvider({ wasmUrl, children, onError }: MujocoProviderProps) {
+export function MujocoProvider({ wasmUrl, timeout = 30000, children, onError }: MujocoProviderProps) {
   const [status, setStatus] = useState<'loading' | 'ready' | 'error'>('loading');
   const [error, setError] = useState<string | null>(null);
   const moduleRef = useRef<MujocoModule | null>(null);
@@ -39,7 +41,7 @@ export function MujocoProvider({ wasmUrl, children, onError }: MujocoProviderPro
   useEffect(() => {
     isMounted.current = true;
 
-    loadMujoco({
+    const wasmPromise = loadMujoco({
       ...(wasmUrl ? { locateFile: (path: string) => path.endsWith('.wasm') ? wasmUrl : path } : {}),
       printErr: (text: string) => {
         if (text.includes('Aborted') && isMounted.current) {
@@ -47,7 +49,13 @@ export function MujocoProvider({ wasmUrl, children, onError }: MujocoProviderPro
           setStatus('error');
         }
       },
-    })
+    });
+
+    const timeoutPromise = new Promise<never>((_, reject) =>
+      setTimeout(() => reject(new Error(`WASM module load timed out after ${timeout}ms`)), timeout)
+    );
+
+    Promise.race([wasmPromise, timeoutPromise])
       .then((inst: unknown) => {
         if (isMounted.current) {
           moduleRef.current = inst as MujocoModule;
@@ -66,7 +74,7 @@ export function MujocoProvider({ wasmUrl, children, onError }: MujocoProviderPro
     return () => {
       isMounted.current = false;
     };
-  }, [wasmUrl]);
+  }, [wasmUrl, timeout]);
 
   return (
     <MujocoContext.Provider