mujoco-react 9.5.0 → 9.6.0

package/dist/spark.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as _sparkjsdev_spark from '@sparkjsdev/spark';
-import { n as SplatEnvironmentProps, q as PairedSplatEnvironmentConfig, S as SceneConfig, t as SplatEnvironmentReadiness, o as VisualScenarioConfig } from './types-BDB9QT6Z.js';
+import { n as SplatEnvironmentProps, q as PairedSplatEnvironmentConfig, S as SceneConfig, t as SplatEnvironmentReadiness, o as VisualScenarioConfig } from './types-C1rwH74Y.js';
 import 'react';
 import '@react-three/fiber';
 import 'three';

package/dist/spark.js

@@ -1,4 +1,4 @@
-import { useSplatSceneConfig, useSplatEnvironment, SplatEnvironment, CAMERA_FRAME_CAPTURE_RENDER_USER_DATA_KEY } from './chunk-6MOK6ZWB.js';
+import { useSplatSceneConfig, useSplatEnvironment, SplatEnvironment, CAMERA_FRAME_CAPTURE_RENDER_USER_DATA_KEY } from './chunk-4JHALVB2.js';
 import { useThree } from '@react-three/fiber';
 import { useMemo, useState, useEffect, useCallback, useRef } from 'react';
 import * as THREE from 'three';

package/dist/{types-BDB9QT6Z.d.ts → types-C1rwH74Y.d.ts}

@@ -383,6 +383,14 @@ interface IkConfig {
     ikSolveFn?: IKSolveFn;
     /** DLS damping. Default: 0.01. */
     damping?: number;
+    /** Position error weight for the built-in DLS solver. Default: 1. */
+    posWeight?: number;
+    /** Orientation error weight for the built-in DLS solver. Default: 0.3. */
+    rotWeight?: number;
+    /** Solver convergence tolerance. Default: 1e-3. */
+    tolerance?: number;
+    /** Finite-difference step used by the built-in DLS solver. Default: 1e-6. */
+    epsilon?: number;
     /** Max solver iterations. Default: 50. */
     maxIterations?: number;
 }
@@ -659,6 +667,33 @@ interface IkGizmoDragInput {
     position: THREE.Vector3;
     quaternion: THREE.Quaternion;
 }
+type KeyboardIkTargetAction = 'x+' | 'x-' | 'y+' | 'y-' | 'z+' | 'z-' | 'pitch+' | 'pitch-' | 'yaw+' | 'yaw-' | 'roll+' | 'roll-';
+interface KeyboardIkTargetBinding {
+    /** KeyboardEvent.code, e.g. `KeyW`, `ArrowUp`, `Space`. */
+    code: string;
+    action: KeyboardIkTargetAction;
+    /** Override translation speed in meters/second for this binding. */
+    translateSpeed?: number;
+    /** Override rotation speed in radians/second for this binding. */
+    rotateSpeed?: number;
+}
+interface KeyboardIkTargetConfig {
+    controller: IkContextValue | null;
+    bindings: KeyboardIkTargetBinding[];
+    enabled?: boolean;
+    /** Default translation speed in meters/second. Default: 0.25. */
+    translateSpeed?: number;
+    /** Default rotation speed in radians/second. Default: 1.0. */
+    rotateSpeed?: number;
+    /** Apply translation and rotation axes in world or current target space. Default: `world`. */
+    frame?: 'world' | 'target';
+    /** Enable IK while keys are active. Default: true. */
+    autoEnableIk?: boolean;
+    /** Sync target to current site when keyboard control starts. Default: true. */
+    syncOnStart?: boolean;
+    /** Prevent browser default behavior for bound keys. Default: true. */
+    preventDefault?: boolean;
+}
 interface DragInteractionProps {
     stiffness?: number;
     showArrow?: boolean;
@@ -1165,4 +1200,4 @@ interface JointStateResult {
     velocity: React__default.RefObject<number | Float64Array>;
 }
 
-export { type Bodies as $, type ActuatedJointInfo as A, type BodyProps as B, type ControlGroupInfo as C, type DragInteractionProps as D, type ScenarioLightingPreset as E, type SplatEnvironmentMetadataInput as F, type SplatEnvironmentMetadata as G, type SplatSceneInput as H, type IkConfig as I, type DebugProps as J, type GeomInfo as K, type ContactListenerProps as L, type MujocoContextValue as M, type ActuatorInfo as N, type ObservationConfig as O, type PhysicsStepCallback as P, type Sites as Q, type ReadyCallbackInput as R, type SceneConfig as S, type TrajectoryPlayerProps as T, type SitePositionResult as U, type VisualScenarioEffectsProps as V, type Sensors as W, type SensorHandle as X, type SensorInfo as Y, type Joints as Z, type JointStateResult as _, type MujocoCanvasProps as a, RobotActuators as a$, type BodyStateResult as a0, type Actuators as a1, type CtrlHandle as a2, type ContactInfo as a3, type KeyboardTeleopConfig as a4, type PolicyConfig as a5, type PolicyVector as a6, type ObservationHandle as a7, type TrajectoryInput as a8, type TrajectoryStateChangeInput as a9, type FrameCaptureTarget as aA, type FrameCaptureTargetRef as aB, type Geoms as aC, type IKSolveFn as aD, type IkGizmoDragInput as aE, type IkSolveInput as aF, type JointInfo as aG, type KeyBinding as aH, type Keyframes as aI, type ModelOptions as aJ, type MujocoContact as aK, type MujocoContactArray as aL, type MujocoFrameCaptureOptions as aM, type ObservationLayoutItem as aN, type ObservationOutput as aO, type PhysicsConfig as aP, type PhysicsStepInput as aQ, type PolicyActionInput as aR, type PolicyInferenceInput as aS, type PolicyObservationInput as aT, type RayHit as aU, type Register as aV, type RegisteredRobotMap as aW, type ResetCallbackInput as aX, type ResolvedScenarioCameraConfig as aY, type ResolvedScenarioMaterialConfig as aZ, type ResourceSelector as a_, type PlaybackState as aa, type TrajectoryFrame as ab, type FrameCaptureOptions as ac, type FrameCaptureResult as ad, type FrameCaptureBlobResult as ae, type FrameCaptureAPI as af, type CameraFrameCaptureOptions as ag, type CameraFrameCaptureAPI as ah, type CameraFrameSequenceRecorderAPI as ai, type Cameras as aj, type CameraFrameSequenceCamera as ak, type CameraFrameCaptureSource as al, type CameraFrameSequenceOptions as am, type CameraFrameSequenceResult as an, type CameraFrameCaptureResult as ao, type CameraFrameCaptureBlobResult as ap, type BodyInfo as aq, type CameraFrameCaptureQuaternion as ar, type CameraFrameCaptureVector3 as as, type CameraFrameSequenceCameraSummary as at, type CameraFrameSequenceFrame as au, type CameraFrameSequenceSampleInput as av, type CameraFrameSequenceStepInput as aw, type CameraInfo as ax, type ControlJointInfo as ay, type FrameCaptureStatus as az, type MujocoSimAPI as b, RobotBodies as b0, RobotCameras as b1, RobotGeoms as b2, RobotJoints as b3, RobotKeyframes as b4, type RobotResource as b5, RobotResources as b6, RobotSensors as b7, RobotSites as b8, type Robots as b9, type ScenarioCameraConfig as ba, type ScenarioMaterialConfig as bb, type SceneMarker as bc, type SceneObject as bd, type SensorResult as be, type SiteInfo as bf, type SplatAssetConfig as bg, type SplatScenarioConfig as bh, type StateSnapshot as bi, type TrajectoryData as bj, type TrajectoryFrameCallbackInput as bk, type VisualScenarioMaterialFilterInput as bl, type XmlPatch as bm, getContact as bn, registerRobotResources as bo, type StepCallbackInput as c, type SelectionCallbackInput as d, type MujocoModule as e, type MujocoModel as f, type MujocoData as g, type ControlGroupSelector as h, type ObservationResult as i, type IkContextValue as j, type IkGizmoProps as k, type SceneLightsProps as l, type ScenarioLightingProps as m, type SplatEnvironmentProps as n, type VisualScenarioConfig as o, type SplatRendererKind as p, type PairedSplatEnvironmentConfig as q, type SplatFormat as r, type SplatCollisionProxyConfig as s, type SplatEnvironmentReadiness as t, type SplatCollisionPrimitive as u, SplatEnvironmentReadinessStatus as v, type SplatSceneConfigInput as w, type SplatSceneConfigState as x, type VisualScenarioExecutionContextInput as y, type VisualScenarioExecutionContext as z };
+export { type Bodies as $, type ActuatedJointInfo as A, type BodyProps as B, type ControlGroupInfo as C, type DragInteractionProps as D, type ScenarioLightingPreset as E, type SplatEnvironmentMetadataInput as F, type SplatEnvironmentMetadata as G, type SplatSceneInput as H, type IkConfig as I, type DebugProps as J, type GeomInfo as K, type ContactListenerProps as L, type MujocoContextValue as M, type ActuatorInfo as N, type ObservationConfig as O, type PhysicsStepCallback as P, type Sites as Q, type ReadyCallbackInput as R, type SceneConfig as S, type TrajectoryPlayerProps as T, type SitePositionResult as U, type VisualScenarioEffectsProps as V, type Sensors as W, type SensorHandle as X, type SensorInfo as Y, type Joints as Z, type JointStateResult as _, type MujocoCanvasProps as a, type ResolvedScenarioCameraConfig as a$, type BodyStateResult as a0, type Actuators as a1, type CtrlHandle as a2, type ContactInfo as a3, type KeyboardTeleopConfig as a4, type KeyboardIkTargetConfig as a5, type PolicyConfig as a6, type PolicyVector as a7, type ObservationHandle as a8, type TrajectoryInput as a9, type FrameCaptureStatus as aA, type FrameCaptureTarget as aB, type FrameCaptureTargetRef as aC, type Geoms as aD, type IKSolveFn as aE, type IkGizmoDragInput as aF, type IkSolveInput as aG, type JointInfo as aH, type KeyBinding as aI, type KeyboardIkTargetAction as aJ, type KeyboardIkTargetBinding as aK, type Keyframes as aL, type ModelOptions as aM, type MujocoContact as aN, type MujocoContactArray as aO, type MujocoFrameCaptureOptions as aP, type ObservationLayoutItem as aQ, type ObservationOutput as aR, type PhysicsConfig as aS, type PhysicsStepInput as aT, type PolicyActionInput as aU, type PolicyInferenceInput as aV, type PolicyObservationInput as aW, type RayHit as aX, type Register as aY, type RegisteredRobotMap as aZ, type ResetCallbackInput as a_, type TrajectoryStateChangeInput as aa, type PlaybackState as ab, type TrajectoryFrame as ac, type FrameCaptureOptions as ad, type FrameCaptureResult as ae, type FrameCaptureBlobResult as af, type FrameCaptureAPI as ag, type CameraFrameCaptureOptions as ah, type CameraFrameCaptureAPI as ai, type CameraFrameSequenceRecorderAPI as aj, type Cameras as ak, type CameraFrameSequenceCamera as al, type CameraFrameCaptureSource as am, type CameraFrameSequenceOptions as an, type CameraFrameSequenceResult as ao, type CameraFrameCaptureResult as ap, type CameraFrameCaptureBlobResult as aq, type BodyInfo as ar, type CameraFrameCaptureQuaternion as as, type CameraFrameCaptureVector3 as at, type CameraFrameSequenceCameraSummary as au, type CameraFrameSequenceFrame as av, type CameraFrameSequenceSampleInput as aw, type CameraFrameSequenceStepInput as ax, type CameraInfo as ay, type ControlJointInfo as az, type MujocoSimAPI as b, type ResolvedScenarioMaterialConfig as b0, type ResourceSelector as b1, RobotActuators as b2, RobotBodies as b3, RobotCameras as b4, RobotGeoms as b5, RobotJoints as b6, RobotKeyframes as b7, type RobotResource as b8, RobotResources as b9, RobotSensors as ba, RobotSites as bb, type Robots as bc, type ScenarioCameraConfig as bd, type ScenarioMaterialConfig as be, type SceneMarker as bf, type SceneObject as bg, type SensorResult as bh, type SiteInfo as bi, type SplatAssetConfig as bj, type SplatScenarioConfig as bk, type StateSnapshot as bl, type TrajectoryData as bm, type TrajectoryFrameCallbackInput as bn, type VisualScenarioMaterialFilterInput as bo, type XmlPatch as bp, getContact as bq, registerRobotResources as br, type StepCallbackInput as c, type SelectionCallbackInput as d, type MujocoModule as e, type MujocoModel as f, type MujocoData as g, type ControlGroupSelector as h, type ObservationResult as i, type IkContextValue as j, type IkGizmoProps as k, type SceneLightsProps as l, type ScenarioLightingProps as m, type SplatEnvironmentProps as n, type VisualScenarioConfig as o, type SplatRendererKind as p, type PairedSplatEnvironmentConfig as q, type SplatFormat as r, type SplatCollisionProxyConfig as s, type SplatEnvironmentReadiness as t, type SplatCollisionPrimitive as u, SplatEnvironmentReadinessStatus as v, type SplatSceneConfigInput as w, type SplatSceneConfigState as x, type VisualScenarioExecutionContextInput as y, type VisualScenarioExecutionContext as z };

package/package.json

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

package/src/hooks/useIkController.ts

@@ -94,7 +94,14 @@ export const useIkController = createControllerHook<IkConfig, IkContextValue>(
         return genericIkRef.current.solve(
           model, data, siteIdRef.current, controlGroup.qposAdr,
           position, quaternion, currentQ,
-          { damping: config.damping, maxIterations: config.maxIterations },
+          {
+            damping: config.damping,
+            epsilon: config.epsilon,
+            maxIterations: config.maxIterations,
+            posWeight: config.posWeight,
+            rotWeight: config.rotWeight,
+            tolerance: config.tolerance,
+          },
         );
       },
       [config, mjModelRef, mjDataRef],

package/src/hooks/useKeyboardIkTarget.ts

@@ -0,0 +1,170 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { useFrame } from '@react-three/fiber';
+import { useEffect, useMemo, useRef } from 'react';
+import * as THREE from 'three';
+import type { KeyboardIkTargetAction, KeyboardIkTargetBinding, KeyboardIkTargetConfig } from '../types';
+
+const DEFAULT_TRANSLATE_SPEED = 0.25;
+const DEFAULT_ROTATE_SPEED = 1.0;
+
+const _translation = new THREE.Vector3();
+const _axis = new THREE.Vector3();
+const _quat = new THREE.Quaternion();
+
+function actionSign(action: KeyboardIkTargetAction): 1 | -1 {
+  return action.endsWith('+') ? 1 : -1;
+}
+
+function actionBase(action: KeyboardIkTargetAction) {
+  return action.slice(0, -1);
+}
+
+function applyRotation(
+  target: THREE.Object3D,
+  action: KeyboardIkTargetAction,
+  amount: number,
+  frame: 'world' | 'target',
+) {
+  const base = actionBase(action);
+  if (base === 'pitch') {
+    _axis.set(1, 0, 0);
+  } else if (base === 'yaw') {
+    _axis.set(0, 1, 0);
+  } else if (base === 'roll') {
+    _axis.set(0, 0, 1);
+  } else {
+    return;
+  }
+
+  _quat.setFromAxisAngle(_axis, amount);
+  if (frame === 'target') {
+    target.quaternion.multiply(_quat);
+  } else {
+    target.quaternion.premultiply(_quat);
+  }
+}
+
+function addTranslation(action: KeyboardIkTargetAction, amount: number) {
+  switch (action) {
+    case 'x+':
+      _translation.x += amount;
+      break;
+    case 'x-':
+      _translation.x -= amount;
+      break;
+    case 'y+':
+      _translation.y += amount;
+      break;
+    case 'y-':
+      _translation.y -= amount;
+      break;
+    case 'z+':
+      _translation.z += amount;
+      break;
+    case 'z-':
+      _translation.z -= amount;
+      break;
+  }
+}
+
+/**
+ * Moves an existing IK target from keyboard input.
+ *
+ * This hook is intentionally robot-agnostic: it only edits the target owned by
+ * `useIkController`, then lets the normal IK solver write robot controls.
+ */
+export function useKeyboardIkTarget(config: KeyboardIkTargetConfig | null) {
+  const pressedRef = useRef(new Set<string>());
+  const wasActiveRef = useRef(false);
+  const configRef = useRef(config);
+  configRef.current = config;
+
+  const boundCodes = useMemo(() => {
+    return new Set((config?.bindings ?? []).map((binding) => binding.code));
+  }, [config?.bindings]);
+
+  useEffect(() => {
+    const onKeyDown = (event: KeyboardEvent) => {
+      const current = configRef.current;
+      if (!current || current.enabled === false || !boundCodes.has(event.code)) return;
+      if (current.preventDefault !== false) event.preventDefault();
+      pressedRef.current.add(event.code);
+    };
+    const onKeyUp = (event: KeyboardEvent) => {
+      const current = configRef.current;
+      if (boundCodes.has(event.code) && current?.preventDefault !== false) {
+        event.preventDefault();
+      }
+      pressedRef.current.delete(event.code);
+    };
+    const onBlur = () => {
+      pressedRef.current.clear();
+      wasActiveRef.current = false;
+    };
+
+    window.addEventListener('keydown', onKeyDown);
+    window.addEventListener('keyup', onKeyUp);
+    window.addEventListener('blur', onBlur);
+
+    return () => {
+      window.removeEventListener('keydown', onKeyDown);
+      window.removeEventListener('keyup', onKeyUp);
+      window.removeEventListener('blur', onBlur);
+    };
+  }, [boundCodes]);
+
+  useFrame((_state, delta) => {
+    const current = configRef.current;
+    const controller = current?.controller;
+    if (!current || current.enabled === false || !controller) {
+      wasActiveRef.current = false;
+      return;
+    }
+
+    const activeBindings: KeyboardIkTargetBinding[] = [];
+    for (const binding of current.bindings) {
+      if (pressedRef.current.has(binding.code)) activeBindings.push(binding);
+    }
+
+    if (activeBindings.length === 0) {
+      wasActiveRef.current = false;
+      return;
+    }
+
+    if (!wasActiveRef.current) {
+      if (current.syncOnStart !== false) controller.syncTargetToSite();
+      if (current.autoEnableIk !== false && !controller.ikEnabledRef.current) {
+        controller.setIkEnabled(true);
+      }
+    }
+    wasActiveRef.current = true;
+
+    const target = controller.ikTargetRef.current;
+    if (!target) return;
+
+    const frame = current.frame ?? 'world';
+    _translation.set(0, 0, 0);
+
+    for (const binding of activeBindings) {
+      const translateSpeed = binding.translateSpeed ?? current.translateSpeed ?? DEFAULT_TRANSLATE_SPEED;
+      const rotateSpeed = binding.rotateSpeed ?? current.rotateSpeed ?? DEFAULT_ROTATE_SPEED;
+      const amount = actionSign(binding.action) * delta;
+      const base = actionBase(binding.action);
+
+      if (base === 'x' || base === 'y' || base === 'z') {
+        addTranslation(binding.action, translateSpeed * delta);
+      } else {
+        applyRotation(target, binding.action, rotateSpeed * amount, frame);
+      }
+    }
+
+    if (_translation.lengthSq() > 0) {
+      if (frame === 'target') _translation.applyQuaternion(target.quaternion);
+      target.position.add(_translation);
+    }
+  });
+}

package/src/index.ts

@@ -91,6 +91,7 @@ export { useBodyState } from './hooks/useBodyState';
 export { useCtrl } from './hooks/useCtrl';
 export { useContacts, useContactEvents } from './hooks/useContacts';
 export { useKeyboardTeleop } from './hooks/useKeyboardTeleop';
+export { useKeyboardIkTarget } from './hooks/useKeyboardIkTarget';
 export { usePolicy } from './hooks/usePolicy';
 export { useObservation } from './hooks/useObservation';
 export { useTrajectoryPlayer } from './hooks/useTrajectoryPlayer';
@@ -211,6 +212,9 @@ export type {
   // Keyboard teleop
   KeyBinding,
   KeyboardTeleopConfig,
+  KeyboardIkTargetAction,
+  KeyboardIkTargetBinding,
+  KeyboardIkTargetConfig,
   // Policy
   PolicyConfig,
   PolicyVector,

package/src/types.ts

@@ -516,6 +516,14 @@ export interface IkConfig {
   ikSolveFn?: IKSolveFn;
   /** DLS damping. Default: 0.01. */
   damping?: number;
+  /** Position error weight for the built-in DLS solver. Default: 1. */
+  posWeight?: number;
+  /** Orientation error weight for the built-in DLS solver. Default: 0.3. */
+  rotWeight?: number;
+  /** Solver convergence tolerance. Default: 1e-3. */
+  tolerance?: number;
+  /** Finite-difference step used by the built-in DLS solver. Default: 1e-6. */
+  epsilon?: number;
   /** Max solver iterations. Default: 50. */
   maxIterations?: number;
 }
@@ -864,6 +872,48 @@ export interface IkGizmoDragInput {
   quaternion: THREE.Quaternion;
 }
 
+export type KeyboardIkTargetAction =
+  | 'x+'
+  | 'x-'
+  | 'y+'
+  | 'y-'
+  | 'z+'
+  | 'z-'
+  | 'pitch+'
+  | 'pitch-'
+  | 'yaw+'
+  | 'yaw-'
+  | 'roll+'
+  | 'roll-';
+
+export interface KeyboardIkTargetBinding {
+  /** KeyboardEvent.code, e.g. `KeyW`, `ArrowUp`, `Space`. */
+  code: string;
+  action: KeyboardIkTargetAction;
+  /** Override translation speed in meters/second for this binding. */
+  translateSpeed?: number;
+  /** Override rotation speed in radians/second for this binding. */
+  rotateSpeed?: number;
+}
+
+export interface KeyboardIkTargetConfig {
+  controller: IkContextValue | null;
+  bindings: KeyboardIkTargetBinding[];
+  enabled?: boolean;
+  /** Default translation speed in meters/second. Default: 0.25. */
+  translateSpeed?: number;
+  /** Default rotation speed in radians/second. Default: 1.0. */
+  rotateSpeed?: number;
+  /** Apply translation and rotation axes in world or current target space. Default: `world`. */
+  frame?: 'world' | 'target';
+  /** Enable IK while keys are active. Default: true. */
+  autoEnableIk?: boolean;
+  /** Sync target to current site when keyboard control starts. Default: true. */
+  syncOnStart?: boolean;
+  /** Prevent browser default behavior for bound keys. Default: true. */
+  preventDefault?: boolean;
+}
+
 export interface DragInteractionProps {
   stiffness?: number;
   showArrow?: boolean;