mujoco-react 7.0.1 → 8.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mujoco-react",
-  "version": "7.0.1",
+  "version": "8.1.0",
   "description": "Composable React Three Fiber building blocks for MuJoCo WASM simulations",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/TrajectoryPlayer.tsx

@@ -17,15 +17,30 @@ import type { TrajectoryPlayerProps } from '../types';
 export function TrajectoryPlayer({
   trajectory,
   fps = 30,
+  speed = 1.0,
   loop = false,
   playing = false,
+  mode = 'kinematic',
   onFrame,
+  onComplete,
+  onStateChange,
 }: TrajectoryPlayerProps) {
-  const player = useTrajectoryPlayer(trajectory, { fps, loop });
+  const player = useTrajectoryPlayer(trajectory, {
+    fps,
+    speed,
+    loop,
+    mode,
+    onComplete,
+    onStateChange,
+  });
   const onFrameRef = useRef(onFrame);
   onFrameRef.current = onFrame;
   const lastReportedFrameRef = useRef(-1);
 
+  useEffect(() => {
+    player.setSpeed(speed);
+  }, [speed, player]);
+
   useEffect(() => {
     if (playing) {
       player.play();
@@ -34,7 +49,6 @@ export function TrajectoryPlayer({
     }
   }, [playing, player]);
 
-  // Use useFrame instead of setInterval to sync with the render loop
   useFrame(() => {
     if (!onFrameRef.current) return;
     const currentFrame = player.frame;

package/src/hooks/useBodyState.ts

@@ -9,13 +9,13 @@ import { useEffect, useRef } from 'react';
 import * as THREE from 'three';
 import { useMujocoContext, useAfterPhysicsStep } from '../core/MujocoSimProvider';
 import { findBodyByName } from '../core/SceneLoader';
-import type { BodyStateResult } from '../types';
+import type { Bodies, BodyStateResult } from '../types';
 
 /**
  * Track a MuJoCo body's world position, quaternion, and velocities.
  * All values are ref-based — updated every physics frame without re-renders.
  */
-export function useBodyState(name: string): BodyStateResult {
+export function useBodyState(name: Bodies): BodyStateResult {
   const { mjModelRef, status } = useMujocoContext();
   const bodyIdRef = useRef(-1);
   const position = useRef(new THREE.Vector3());

package/src/hooks/useContacts.ts

@@ -10,7 +10,7 @@ import { useCallback, useEffect, useRef } from 'react';
 import { useMujocoContext, useAfterPhysicsStep } from '../core/MujocoSimProvider';
 import { findBodyByName, getName } from '../core/SceneLoader';
 import { getContact } from '../types';
-import type { ContactInfo, MujocoModel } from '../types';
+import type { Bodies, ContactInfo, MujocoModel } from '../types';
 
 // Cache geom names per model to avoid cross-model id collisions.
 const geomNameCacheByModel = new WeakMap<MujocoModel, Map<number, string>>();
@@ -36,7 +36,7 @@ function getGeomNameCached(model: MujocoModel, geomId: number): string {
  * Reads `data.ncon` first to avoid allocating for zero contacts.
  */
 export function useContacts(
-  bodyName?: string,
+  bodyName?: Bodies,
   callback?: (contacts: ContactInfo[]) => void,
 ): React.RefObject<ContactInfo[]> {
   const { mjModelRef, status } = useMujocoContext();
@@ -108,7 +108,7 @@ export function useContacts(
  * onEnter/onExit callbacks on transitions.
  */
 export function useContactEvents(
-  bodyName: string,
+  bodyName: Bodies,
   handlers: {
     onEnter?: (info: ContactInfo) => void;
     onExit?: (info: ContactInfo) => void;

package/src/hooks/useCtrl.ts

@@ -2,39 +2,52 @@
  * @license
  * SPDX-License-Identifier: Apache-2.0
  *
- * useCtrl — clean read/write access to a named actuator's ctrl value (spec 3.1)
+ * useCtrl — handle-based read/write access to a named actuator's ctrl value (spec 3.1)
  */
 
-import { useCallback, useEffect, useRef } from 'react';
+import { useEffect, useRef, useMemo } from 'react';
 import { useMujocoContext } from '../core/MujocoSimProvider';
 import { findActuatorByName } from '../core/SceneLoader';
+import type { Actuators, CtrlHandle } from '../types';
 
 /**
  * Access a single actuator's control value by name.
  *
- * Returns [currentValue, setValue]:
- * - `currentValue` is a ref updated every frame (no re-renders).
- * - `setValue` writes directly to `data.ctrl[actuatorId]`.
+ * Returns a `CtrlHandle` with `read()` and `write()` methods that
+ * operate directly on `data.ctrl` without causing React re-renders.
  */
-export function useCtrl(name: string): [React.RefObject<number>, (value: number) => void] {
+export function useCtrl(name: Actuators): CtrlHandle {
   const { mjModelRef, mjDataRef, status } = useMujocoContext();
   const actuatorIdRef = useRef(-1);
-  const valueRef = useRef(0);
+  const rangeRef = useRef<[number, number]>([0, 0]);
 
   useEffect(() => {
     const model = mjModelRef.current;
     if (!model || status !== 'ready') return;
-    actuatorIdRef.current = findActuatorByName(model, name);
+    const id = findActuatorByName(model, name);
+    actuatorIdRef.current = id;
+    if (id >= 0) {
+      rangeRef.current = [
+        model.actuator_ctrlrange[id * 2],
+        model.actuator_ctrlrange[id * 2 + 1],
+      ];
+    }
   }, [name, status, mjModelRef]);
 
-  // Read current value each frame (via afterStep would be ideal but
-  // useCtrl is primarily for writing; reading can use the ref)
-  const setValue = useCallback((value: number) => {
-    const data = mjDataRef.current;
-    if (!data || actuatorIdRef.current < 0) return;
-    data.ctrl[actuatorIdRef.current] = value;
-    valueRef.current = value;
-  }, [mjDataRef]);
-
-  return [valueRef, setValue];
+  return useMemo<CtrlHandle>(() => ({
+    read() {
+      const data = mjDataRef.current;
+      if (!data || actuatorIdRef.current < 0) return 0;
+      return data.ctrl[actuatorIdRef.current];
+    },
+    write(value: number) {
+      const data = mjDataRef.current;
+      if (!data || actuatorIdRef.current < 0) return;
+      data.ctrl[actuatorIdRef.current] = value;
+    },
+    name,
+    get range(): [number, number] {
+      return rangeRef.current;
+    },
+  }), [name, mjDataRef]);
 }

package/src/hooks/useJointState.ts

@@ -8,7 +8,7 @@
 import { useEffect, useRef } from 'react';
 import { useMujocoContext, useAfterPhysicsStep } from '../core/MujocoSimProvider';
 import { getName } from '../core/SceneLoader';
-import type { JointStateResult } from '../types';
+import type { Joints, JointStateResult } from '../types';
 
 /**
  * Track a MuJoCo joint's position and velocity by name.
@@ -18,7 +18,7 @@ import type { JointStateResult } from '../types';
  * For ball joints, position is quat (4), velocity is angular vel (3).
  * For free joints, position is pos+quat (7), velocity is lin+ang vel (6).
  */
-export function useJointState(name: string): JointStateResult {
+export function useJointState(name: Joints): JointStateResult {
   const { mjModelRef, mjDataRef, status } = useMujocoContext();
   const jointIdRef = useRef(-1);
   const qposAdrRef = useRef(0);

package/src/hooks/useSensor.ts

@@ -8,13 +8,14 @@
 import { useEffect, useRef, useMemo } from 'react';
 import { useMujocoContext, useAfterPhysicsStep } from '../core/MujocoSimProvider';
 import { getName } from '../core/SceneLoader';
-import type { SensorInfo, SensorResult } from '../types';
+import type { Sensors, SensorHandle, SensorInfo } from '../types';
 
 /**
- * Access a single MuJoCo sensor by name. Returns a ref-based value
- * updated every physics frame without causing React re-renders.
+ * Access a single MuJoCo sensor by name. Returns a `SensorHandle` with
+ * `read()`, `dim`, and `name`. The backing array is updated every physics
+ * frame without causing React re-renders.
  */
-export function useSensor(name: string): SensorResult {
+export function useSensor(name: Sensors): SensorHandle {
   const { mjModelRef, mjDataRef, status } = useMujocoContext();
   const sensorIdRef = useRef(-1);
   const sensorAdrRef = useRef(0);
@@ -47,7 +48,15 @@ export function useSensor(name: string): SensorResult {
     }
   });
 
-  return { value: valueRef, size: sensorDimRef.current };
+  return useMemo<SensorHandle>(() => ({
+    read() {
+      return valueRef.current;
+    },
+    get dim() {
+      return sensorDimRef.current;
+    },
+    name,
+  }), [name]);
 }
 
 /**

package/src/hooks/useSitePosition.ts

@@ -8,7 +8,7 @@ import { useFrame } from '@react-three/fiber';
 import * as THREE from 'three';
 import { useMujocoContext } from '../core/MujocoSimProvider';
 import { findSiteByName } from '../core/SceneLoader';
-import type { SitePositionResult } from '../types';
+import type { Sites, SitePositionResult } from '../types';
 
 // Preallocated temp for rotation matrix extraction
 const _mat4 = new THREE.Matrix4();
@@ -17,7 +17,7 @@ const _mat4 = new THREE.Matrix4();
  * Returns reactive refs for a MuJoCo site's world position and orientation.
  * Refs are updated every frame without triggering React re-renders.
  */
-export function useSitePosition(siteName: string): SitePositionResult {
+export function useSitePosition(siteName: Sites): SitePositionResult {
   const { mjModelRef, mjDataRef, status } = useMujocoContext();
   const siteIdRef = useRef(-1);
   const positionRef = useRef(new THREE.Vector3());

package/src/hooks/useTrajectoryPlayer.ts

@@ -7,65 +7,153 @@
 
 import { useCallback, useRef } from 'react';
 import { useFrame } from '@react-three/fiber';
-import { useMujocoContext } from '../core/MujocoSimProvider';
+import { useMujocoContext, useBeforePhysicsStep } from '../core/MujocoSimProvider';
+import type { PlaybackState, TrajectoryFrame, TrajectoryInput } from '../types';
 
-interface TrajectoryPlayerOptions {
+export interface TrajectoryPlayerOptions {
   fps?: number;
+  speed?: number;
   loop?: boolean;
+  mode?: 'kinematic' | 'physics';
+  onComplete?: () => void;
+  onStateChange?: (state: PlaybackState) => void;
+}
+
+/** Check if input is TrajectoryFrame[] (vs number[][]) */
+function isTrajectoryFrames(input: TrajectoryInput): input is TrajectoryFrame[] {
+  return input.length > 0 && typeof (input[0] as TrajectoryFrame).time === 'number'
+    && 'qpos' in (input[0] as TrajectoryFrame);
+}
+
+/** Extract qpos as plain number array from a frame */
+function getQpos(input: TrajectoryInput, idx: number): ArrayLike<number> | null {
+  const item = input[idx];
+  if (!item) return null;
+  if (Array.isArray(item)) return item;
+  return (item as TrajectoryFrame).qpos;
+}
+
+/** Extract ctrl values from a TrajectoryFrame, if available */
+function getCtrl(input: TrajectoryInput, idx: number): ArrayLike<number> | null {
+  const item = input[idx];
+  if (!item || Array.isArray(item)) return null;
+  return (item as TrajectoryFrame).ctrl ?? null;
 }
 
 /**
- * Play back a sequence of qpos frames, overriding simulation state.
+ * Play back a trajectory, overriding simulation state.
  *
- * When playing, the simulation is effectively paused and qpos is set
- * from the trajectory each render frame at the specified FPS.
+ * Accepts either `TrajectoryFrame[]` (from useTrajectoryRecorder) or
+ * `number[][]` (raw qpos arrays).
+ *
+ * In `kinematic` mode (default), the simulation is paused and qpos is
+ * set directly each frame with mj_forward for rendering.
+ *
+ * In `physics` mode, the simulation keeps running and ctrl values from
+ * the trajectory are applied each physics step via useBeforePhysicsStep.
  */
 export function useTrajectoryPlayer(
-  trajectory: number[][],
+  trajectory: TrajectoryInput,
   options: TrajectoryPlayerOptions = {},
 ) {
   const { mjModelRef, mjDataRef, mujocoRef, pausedRef } = useMujocoContext();
-  const fps = options.fps ?? 30;
-  const loop = options.loop ?? false;
 
-  const playingRef = useRef(false);
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+
+  const stateRef = useRef<PlaybackState>('idle');
   const frameRef = useRef(0);
   const lastFrameTimeRef = useRef(0);
+  const speedRef = useRef(options.speed ?? 1.0);
+  const wasPausedRef = useRef(false);
+
+  // Stable ref to trajectory to avoid stale closures in useBeforePhysicsStep
+  const trajectoryRef = useRef(trajectory);
+  trajectoryRef.current = trajectory;
+
+  const setState = useCallback((next: PlaybackState) => {
+    if (stateRef.current === next) return;
+    stateRef.current = next;
+    optionsRef.current.onStateChange?.(next);
+  }, []);
 
   const play = useCallback(() => {
-    playingRef.current = true;
-    pausedRef.current = true; // Pause sim during playback
+    const traj = trajectoryRef.current;
+    if (traj.length === 0) return;
+
+    const mode = optionsRef.current.mode ?? 'kinematic';
+
+    if (stateRef.current === 'completed') {
+      frameRef.current = 0;
+    }
+
+    if (mode === 'kinematic') {
+      wasPausedRef.current = pausedRef.current;
+      pausedRef.current = true;
+    }
+
     lastFrameTimeRef.current = performance.now();
-  }, [pausedRef]);
+    setState('playing');
+  }, [pausedRef, setState]);
 
   const pause = useCallback(() => {
-    playingRef.current = false;
-  }, []);
+    if (stateRef.current !== 'playing') return;
+    setState('paused');
+  }, [setState]);
 
   const seek = useCallback((frameIdx: number) => {
-    frameRef.current = Math.max(0, Math.min(frameIdx, trajectory.length - 1));
+    const traj = trajectoryRef.current;
+    if (traj.length === 0) return;
+
+    frameRef.current = Math.max(0, Math.min(frameIdx, traj.length - 1));
+
     const model = mjModelRef.current;
     const data = mjDataRef.current;
-    if (!model || !data || !trajectory[frameRef.current]) return;
-    const qpos = trajectory[frameRef.current];
+    if (!model || !data) return;
+
+    const qpos = getQpos(traj, frameRef.current);
+    if (!qpos) return;
+
     for (let i = 0; i < Math.min(qpos.length, model.nq); i++) {
       data.qpos[i] = qpos[i];
     }
     mujocoRef.current.mj_forward(model, data);
-  }, [trajectory, mjModelRef, mjDataRef, mujocoRef]);
+  }, [mjModelRef, mjDataRef, mujocoRef]);
 
   const reset = useCallback(() => {
+    const mode = optionsRef.current.mode ?? 'kinematic';
+    if (mode === 'kinematic' && stateRef.current !== 'idle') {
+      pausedRef.current = wasPausedRef.current;
+    }
     frameRef.current = 0;
-    playingRef.current = false;
-    pausedRef.current = false;
-  }, [pausedRef]);
+    setState('idle');
+  }, [pausedRef, setState]);
+
+  const setSpeed = useCallback((s: number) => {
+    speedRef.current = s;
+  }, []);
 
+  const complete = useCallback(() => {
+    const mode = optionsRef.current.mode ?? 'kinematic';
+    if (mode === 'kinematic') {
+      pausedRef.current = wasPausedRef.current;
+    }
+    setState('completed');
+    optionsRef.current.onComplete?.();
+  }, [pausedRef, setState]);
+
+  // --- Kinematic mode: drive qpos directly from useFrame ---
   useFrame(() => {
-    if (!playingRef.current || trajectory.length === 0) return;
+    if (stateRef.current !== 'playing') return;
+    if ((optionsRef.current.mode ?? 'kinematic') !== 'kinematic') return;
+
+    const traj = trajectoryRef.current;
+    if (traj.length === 0) return;
 
     const now = performance.now();
+    const fps = optionsRef.current.fps ?? 30;
+    const frameInterval = 1000 / (fps * speedRef.current);
     const elapsed = now - lastFrameTimeRef.current;
-    const frameInterval = 1000 / fps;
 
     if (elapsed < frameInterval) return;
     lastFrameTimeRef.current = now;
@@ -74,7 +162,7 @@ export function useTrajectoryPlayer(
     const data = mjDataRef.current;
     if (!model || !data) return;
 
-    const qpos = trajectory[frameRef.current];
+    const qpos = getQpos(traj, frameRef.current);
     if (!qpos) return;
 
     for (let i = 0; i < Math.min(qpos.length, model.nq); i++) {
@@ -83,12 +171,44 @@ export function useTrajectoryPlayer(
     mujocoRef.current.mj_forward(model, data);
 
     frameRef.current++;
-    if (frameRef.current >= trajectory.length) {
-      if (loop) {
+    if (frameRef.current >= traj.length) {
+      if (optionsRef.current.loop) {
+        frameRef.current = 0;
+      } else {
+        complete();
+      }
+    }
+  });
+
+  // --- Physics mode: set ctrl values each physics step ---
+  useBeforePhysicsStep((model, data) => {
+    if (stateRef.current !== 'playing') return;
+    if ((optionsRef.current.mode ?? 'kinematic') !== 'physics') return;
+
+    const traj = trajectoryRef.current;
+    if (traj.length === 0) return;
+
+    // Advance frame based on sim time vs trajectory time
+    const fps = optionsRef.current.fps ?? 30;
+    const targetFrame = Math.floor(data.time * fps * speedRef.current);
+    frameRef.current = Math.min(targetFrame, traj.length - 1);
+
+    // Apply ctrl from trajectory
+    const ctrl = getCtrl(traj, frameRef.current);
+    if (ctrl) {
+      for (let i = 0; i < Math.min(ctrl.length, model.nu); i++) {
+        data.ctrl[i] = ctrl[i];
+      }
+    }
+
+    // Check completion
+    if (frameRef.current >= traj.length - 1) {
+      if (optionsRef.current.loop) {
+        // Reset sim time to restart
+        data.time = 0;
         frameRef.current = 0;
       } else {
-        playingRef.current = false;
-        pausedRef.current = false;
+        complete();
       }
     }
   });
@@ -98,8 +218,11 @@ export function useTrajectoryPlayer(
     pause,
     seek,
     reset,
+    setSpeed,
+    get state() { return stateRef.current; },
     get frame() { return frameRef.current; },
-    get playing() { return playingRef.current; },
+    get playing() { return stateRef.current === 'playing'; },
     get totalFrames() { return trajectory.length; },
+    get progress() { return trajectory.length > 1 ? frameRef.current / (trajectory.length - 1) : 0; },
   };
 }

package/src/index.ts

@@ -95,6 +95,8 @@ export type {
   // Trajectory
   TrajectoryFrame,
   TrajectoryData,
+  TrajectoryInput,
+  PlaybackState,
   // Keyboard teleop
   KeyBinding,
   KeyboardTeleopConfig,
@@ -115,8 +117,19 @@ export type {
   // Hook return types
   SitePositionResult,
   SensorResult,
+  CtrlHandle,
+  SensorHandle,
   BodyStateResult,
   JointStateResult,
+  // Register (type-safe named resources)
+  Register,
+  Actuators,
+  Sensors,
+  Bodies,
+  Joints,
+  Sites,
+  Geoms,
+  Keyframes,
 } from './types';
 
 // Re-export MuJoCo types for convenience