npm - mujoco-react - Versions diffs - 0.1.0 - Mend

mujoco-react 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (42) hide show

package/LICENSE +177 -0
package/README.md +510 -0
package/dist/index.d.ts +1080 -0
package/dist/index.js +3518 -0
package/dist/index.js.map +1 -0
package/package.json +64 -0
package/src/components/ContactListener.tsx +26 -0
package/src/components/ContactMarkers.tsx +81 -0
package/src/components/Debug.tsx +227 -0
package/src/components/DragInteraction.tsx +227 -0
package/src/components/FlexRenderer.tsx +102 -0
package/src/components/IkGizmo.tsx +146 -0
package/src/components/SceneLights.tsx +131 -0
package/src/components/SceneRenderer.tsx +104 -0
package/src/components/SelectionHighlight.tsx +69 -0
package/src/components/TendonRenderer.tsx +84 -0
package/src/components/TrajectoryPlayer.tsx +44 -0
package/src/core/GenericIK.ts +339 -0
package/src/core/MujocoCanvas.tsx +72 -0
package/src/core/MujocoProvider.tsx +78 -0
package/src/core/MujocoSimProvider.tsx +1201 -0
package/src/core/SceneLoader.ts +275 -0
package/src/hooks/useActuators.ts +36 -0
package/src/hooks/useBodyState.ts +56 -0
package/src/hooks/useContacts.ts +125 -0
package/src/hooks/useCtrl.ts +40 -0
package/src/hooks/useCtrlNoise.ts +59 -0
package/src/hooks/useGamepad.ts +77 -0
package/src/hooks/useGravityCompensation.ts +22 -0
package/src/hooks/useJointState.ts +64 -0
package/src/hooks/useKeyboardTeleop.ts +97 -0
package/src/hooks/usePolicy.ts +56 -0
package/src/hooks/useSensor.ts +83 -0
package/src/hooks/useSitePosition.ts +62 -0
package/src/hooks/useTrajectoryPlayer.ts +105 -0
package/src/hooks/useTrajectoryRecorder.ts +97 -0
package/src/hooks/useVideoRecorder.ts +82 -0
package/src/index.ts +108 -0
package/src/rendering/CapsuleGeometry.ts +35 -0
package/src/rendering/GeomBuilder.ts +140 -0
package/src/rendering/Reflector.ts +225 -0
package/src/types.ts +619 -0

package/src/core/SceneLoader.ts ADDED Viewed

@@ -0,0 +1,275 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { MujocoData, MujocoModel, MujocoModule } from '../types';
+import { SceneConfig, SceneObject, XmlPatch } from '../types';
+/**
+ * Reads a null-terminated C string from MuJoCo's WASM memory.
+ */
+export function getName(mjModel: MujocoModel, address: number): string {
+  let name = '';
+  let idx = address;
+  let safety = 0;
+  while (mjModel.names[idx] !== 0 && safety < 100) {
+    name += String.fromCharCode(mjModel.names[idx++]);
+    safety++;
+  }
+  return name;
+}
+/**
+ * Find a site by name in the MuJoCo model. Returns -1 if not found.
+ */
+export function findSiteByName(mjModel: MujocoModel, name: string): number {
+  for (let i = 0; i < mjModel.nsite; i++) {
+    if (getName(mjModel, mjModel.name_siteadr[i]).includes(name)) return i;
+  }
+  return -1;
+}
+/**
+ * Find an actuator by name in the MuJoCo model. Returns -1 if not found.
+ */
+export function findActuatorByName(mjModel: MujocoModel, name: string): number {
+  for (let i = 0; i < mjModel.nu; i++) {
+    if (getName(mjModel, mjModel.name_actuatoradr[i]).includes(name)) return i;
+  }
+  return -1;
+}
+/**
+ * Find a keyframe by name in the MuJoCo model. Returns -1 if not found.
+ */
+export function findKeyframeByName(mjModel: MujocoModel, name: string): number {
+  for (let i = 0; i < mjModel.nkey; i++) {
+    if (getName(mjModel, mjModel.name_keyadr[i]) === name) return i;
+  }
+  return -1;
+}
+/**
+ * Find a body by name in the MuJoCo model. Returns -1 if not found.
+ */
+export function findBodyByName(mjModel: MujocoModel, name: string): number {
+  for (let i = 0; i < mjModel.nbody; i++) {
+    if (getName(mjModel, mjModel.name_bodyadr[i]) === name) return i;
+  }
+  return -1;
+}
+/**
+ * Find a joint by name in the MuJoCo model. Returns -1 if not found.
+ */
+export function findJointByName(mjModel: MujocoModel, name: string): number {
+  for (let i = 0; i < mjModel.njnt; i++) {
+    if (getName(mjModel, mjModel.name_jntadr[i]) === name) return i;
+  }
+  return -1;
+}
+/**
+ * Find a geom by name in the MuJoCo model. Returns -1 if not found.
+ */
+export function findGeomByName(mjModel: MujocoModel, name: string): number {
+  for (let i = 0; i < mjModel.ngeom; i++) {
+    if (getName(mjModel, mjModel.name_geomadr[i]) === name) return i;
+  }
+  return -1;
+}
+/**
+ * Find a sensor by name in the MuJoCo model. Returns -1 if not found.
+ */
+export function findSensorByName(mjModel: MujocoModel, name: string): number {
+  for (let i = 0; i < mjModel.nsensor; i++) {
+    if (getName(mjModel, mjModel.name_sensoradr[i]) === name) return i;
+  }
+  return -1;
+}
+/**
+ * Find a tendon by name in the MuJoCo model. Returns -1 if not found.
+ */
+export function findTendonByName(mjModel: MujocoModel, name: string): number {
+  for (let i = 0; i < (mjModel.ntendon ?? 0); i++) {
+    if (getName(mjModel, mjModel.name_tendonadr[i]) === name) return i;
+  }
+  return -1;
+}
+/**
+ * Convert a SceneObject config to MuJoCo XML.
+ */
+function sceneObjectToXml(obj: SceneObject): string {
+  const joint = obj.freejoint ? '<freejoint/>' : '';
+  const pos = obj.position.map((v) => v.toFixed(3)).join(' ');
+  const size = obj.size.map((v) => v.toFixed(3)).join(' ');
+  const rgba = obj.rgba.join(' ');
+  const mass = obj.mass ? ` mass="${obj.mass}"` : '';
+  const friction = obj.friction ? ` friction="${obj.friction}"` : '';
+  const solref = obj.solref ? ` solref="${obj.solref}"` : '';
+  const solimp = obj.solimp ? ` solimp="${obj.solimp}"` : '';
+  const condim = obj.condim ? ` condim="${obj.condim}"` : '';
+  // Always set contype/conaffinity=1 so objects collide regardless of model defaults
+  return `<body name="${obj.name}" pos="${pos}">${joint}<geom type="${obj.type}" size="${size}" rgba="${rgba}" contype="1" conaffinity="1"${mass}${friction}${solref}${solimp}${condim}/></body>`;
+}
+interface LoadResult {
+  mjModel: MujocoModel;
+  mjData: MujocoData;
+  siteId: number;
+  gripperId: number;
+}
+/**
+ * Config-driven scene loader — replaces the old RobotLoader + patchSingleRobot approach.
+ */
+export async function loadScene(
+  mujoco: MujocoModule,
+  config: SceneConfig,
+  onProgress?: (msg: string) => void
+): Promise<LoadResult> {
+  // 1. Clean up virtual filesystem
+  try { mujoco.FS.unmount('/working'); } catch { /* ignore */ }
+  try { mujoco.FS.mkdir('/working'); } catch { /* ignore */ }
+  const baseUrl =
+    config.baseUrl ||
+    `https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/${config.robotId}/`;
+  const downloaded = new Set<string>();
+  const queue: string[] = [config.sceneFile];
+  const parser = new DOMParser();
+  // 2. Download all model files
+  while (queue.length > 0) {
+    const fname = queue.shift()!;
+    if (downloaded.has(fname)) continue;
+    downloaded.add(fname);
+    onProgress?.(`Downloading ${fname}...`);
+    const res = await fetch(baseUrl + fname);
+    if (!res.ok) {
+      console.warn(`Failed to fetch ${fname}: ${res.status} ${res.statusText}`);
+      continue;
+    }
+    // Create virtual directory structure
+    const dirParts = fname.split('/');
+    dirParts.pop();
+    let currentPath = '/working';
+    for (const part of dirParts) {
+      currentPath += '/' + part;
+      try { mujoco.FS.mkdir(currentPath); } catch { /* ignore */ }
+    }
+    if (fname.endsWith('.xml')) {
+      let text = await res.text();
+      // 3. Apply XML patches from config
+      for (const patch of config.xmlPatches ?? []) {
+        if (fname.endsWith(patch.target) || fname === patch.target) {
+          if (patch.replace) {
+            text = text.replace(patch.replace[0], patch.replace[1]);
+          }
+          if (patch.inject && patch.injectAfter) {
+            const idx = text.indexOf(patch.injectAfter);
+            if (idx !== -1) {
+              // Find the end of the opening tag (next '>') after the match
+              const tagEnd = text.indexOf('>', idx + patch.injectAfter.length);
+              if (tagEnd !== -1) {
+                text = text.slice(0, tagEnd + 1) + patch.inject + text.slice(tagEnd + 1);
+              }
+            }
+          }
+        }
+      }
+      // 4. Inject scene objects into the scene file
+      if (fname === config.sceneFile && config.sceneObjects?.length) {
+        const xml = config.sceneObjects.map((obj) => sceneObjectToXml(obj)).join('');
+        text = text.replace('</worldbody>', xml + '</worldbody>');
+      }
+      mujoco.FS.writeFile(`/working/${fname}`, text);
+      scanDependencies(text, fname, parser, downloaded, queue);
+    } else {
+      const buffer = new Uint8Array(await res.arrayBuffer());
+      mujoco.FS.writeFile(`/working/${fname}`, buffer);
+    }
+  }
+  // 5. Load model
+  onProgress?.('Loading model...');
+  const mjModel = mujoco.MjModel.loadFromXML(`/working/${config.sceneFile}`);
+  const mjData = new mujoco.MjData(mjModel);
+  // 6. Find TCP site and gripper actuator
+  const siteId = findSiteByName(mjModel, config.tcpSiteName ?? 'tcp');
+  const gripperId = findActuatorByName(mjModel, config.gripperActuatorName ?? 'gripper');
+  // 7. Set initial pose
+  if (config.homeJoints) {
+    for (let i = 0; i < config.homeJoints.length; i++) {
+      mjData.ctrl[i] = config.homeJoints[i];
+      if (mjModel.actuator_trnid[2 * i + 1] === 1) {
+        const jointId = mjModel.actuator_trnid[2 * i];
+        if (jointId >= 0 && jointId < mjModel.njnt) {
+          const qposAdr = mjModel.jnt_qposadr[jointId];
+          mjData.qpos[qposAdr] = config.homeJoints[i];
+        }
+      }
+    }
+  }
+  mujoco.mj_forward(mjModel, mjData);
+  return { mjModel, mjData, siteId, gripperId };
+}
+/**
+ * Scan XML for file dependencies (meshes, textures, includes).
+ */
+function scanDependencies(
+  xmlString: string,
+  currentFile: string,
+  parser: DOMParser,
+  downloaded: Set<string>,
+  queue: string[]
+) {
+  const xmlDoc = parser.parseFromString(xmlString, 'text/xml');
+  const compiler = xmlDoc.querySelector('compiler');
+  const meshDir = compiler?.getAttribute('meshdir') || '';
+  const textureDir = compiler?.getAttribute('texturedir') || '';
+  const currentDir = currentFile.includes('/')
+    ? currentFile.substring(0, currentFile.lastIndexOf('/') + 1)
+    : '';
+  xmlDoc.querySelectorAll('[file]').forEach((el) => {
+    const fileAttr = el.getAttribute('file');
+    if (!fileAttr) return;
+    let prefix = '';
+    if (el.tagName.toLowerCase() === 'mesh') {
+      prefix = meshDir ? meshDir + '/' : '';
+    } else if (['texture', 'hfield'].includes(el.tagName.toLowerCase())) {
+      prefix = textureDir ? textureDir + '/' : '';
+    }
+    let fullPath = (currentDir + prefix + fileAttr).replace(/\/\//g, '/');
+    const parts = fullPath.split('/');
+    const norm: string[] = [];
+    for (const p of parts) {
+      if (p === '..') norm.pop();
+      else if (p !== '.') norm.push(p);
+    }
+    fullPath = norm.join('/');
+    if (!downloaded.has(fullPath)) queue.push(fullPath);
+  });
+}

package/src/hooks/useActuators.ts ADDED Viewed

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { useMemo } from 'react';
+import { useMujocoSim } from '../core/MujocoSimProvider';
+import { getName } from '../core/SceneLoader';
+import type { ActuatorInfo } from '../types';
+/**
+ * Returns a stable array of actuator metadata for building control UIs.
+ * Computed once when the model loads. Consumer reads/writes data.ctrl[id] directly.
+ */
+export function useActuators(): ActuatorInfo[] {
+  const { mjModelRef, status } = useMujocoSim();
+  return useMemo(() => {
+    if (status !== 'ready') return [];
+    const model = mjModelRef.current;
+    if (!model) return [];
+    const actuators: ActuatorInfo[] = [];
+    for (let i = 0; i < model.nu; i++) {
+      const name = getName(model, model.name_actuatoradr[i]);
+      const lo = model.actuator_ctrlrange[i * 2];
+      const hi = model.actuator_ctrlrange[i * 2 + 1];
+      const hasRange = lo < hi;
+      const range: [number, number] = hasRange
+        ? [lo, hi]
+        : [-Infinity, Infinity];
+      actuators.push({ id: i, name, range });
+    }
+    return actuators;
+  }, [status, mjModelRef]);
+}

package/src/hooks/useBodyState.ts ADDED Viewed

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * useBodyState — per-body position/velocity tracking (spec 2.2)
+ */
+import { useEffect, useRef } from 'react';
+import * as THREE from 'three';
+import { useMujocoSim, useAfterPhysicsStep } from '../core/MujocoSimProvider';
+import { findBodyByName } from '../core/SceneLoader';
+import type { 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 {
+  const { mjModelRef, status } = useMujocoSim();
+  const bodyIdRef = useRef(-1);
+  const position = useRef(new THREE.Vector3());
+  const quaternion = useRef(new THREE.Quaternion());
+  const linearVelocity = useRef(new THREE.Vector3());
+  const angularVelocity = useRef(new THREE.Vector3());
+  useEffect(() => {
+    const model = mjModelRef.current;
+    if (!model || status !== 'ready') return;
+    bodyIdRef.current = findBodyByName(model, name);
+  }, [name, status, mjModelRef]);
+  useAfterPhysicsStep((_model, data) => {
+    const bid = bodyIdRef.current;
+    if (bid < 0) return;
+    // Position from xpos (3 per body)
+    const i3 = bid * 3;
+    position.current.set(data.xpos[i3], data.xpos[i3 + 1], data.xpos[i3 + 2]);
+    // Quaternion from xquat (4 per body, MuJoCo order: w,x,y,z)
+    const i4 = bid * 4;
+    quaternion.current.set(
+      data.xquat[i4 + 1], data.xquat[i4 + 2],
+      data.xquat[i4 + 3], data.xquat[i4]
+    );
+    // Velocity from cvel (6 per body: [angular(3), linear(3)])
+    if (data.cvel) {
+      const i6 = bid * 6;
+      angularVelocity.current.set(data.cvel[i6], data.cvel[i6 + 1], data.cvel[i6 + 2]);
+      linearVelocity.current.set(data.cvel[i6 + 3], data.cvel[i6 + 4], data.cvel[i6 + 5]);
+    }
+  });
+  return { position, quaternion, linearVelocity, angularVelocity };
+}

package/src/hooks/useContacts.ts ADDED Viewed

@@ -0,0 +1,125 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * useContacts — structured contact query hook (spec 2.4)
+ * useContactEvents — contact enter/exit events (spec 2.5)
+ */
+import { useCallback, useEffect, useRef } from 'react';
+import { useMujocoSim, useAfterPhysicsStep } from '../core/MujocoSimProvider';
+import { findBodyByName, getName } from '../core/SceneLoader';
+import type { ContactInfo } from '../types';
+/**
+ * Track contacts for a specific body (or all contacts if no body specified).
+ * Calls the callback every physics frame with current contact list.
+ * Reads `data.ncon` first to avoid allocating for zero contacts.
+ */
+export function useContacts(
+  bodyName?: string,
+  callback?: (contacts: ContactInfo[]) => void,
+): React.RefObject<ContactInfo[]> {
+  const { mjModelRef } = useMujocoSim();
+  const contactsRef = useRef<ContactInfo[]>([]);
+  const bodyIdRef = useRef(-1);
+  const callbackRef = useRef(callback);
+  callbackRef.current = callback;
+  useEffect(() => {
+    if (!bodyName) { bodyIdRef.current = -1; return; }
+    const model = mjModelRef.current;
+    if (!model) return;
+    bodyIdRef.current = findBodyByName(model, bodyName);
+  }, [bodyName, mjModelRef]);
+  useAfterPhysicsStep((model, data) => {
+    const ncon = data.ncon;
+    if (ncon === 0) {
+      if (contactsRef.current.length > 0) contactsRef.current = [];
+      callbackRef.current?.([]);
+      return;
+    }
+    const contacts: ContactInfo[] = [];
+    const filterBody = bodyIdRef.current;
+    for (let i = 0; i < ncon; i++) {
+      try {
+        const c = (data.contact as { get(i: number): { geom1: number; geom2: number; pos: Float64Array; dist: number } }).get(i);
+        // Filter by body if specified
+        if (filterBody >= 0) {
+          const b1 = model.geom_bodyid[c.geom1];
+          const b2 = model.geom_bodyid[c.geom2];
+          if (b1 !== filterBody && b2 !== filterBody) continue;
+        }
+        contacts.push({
+          geom1: c.geom1,
+          geom1Name: getName(model, model.name_geomadr[c.geom1]),
+          geom2: c.geom2,
+          geom2Name: getName(model, model.name_geomadr[c.geom2]),
+          pos: [c.pos[0], c.pos[1], c.pos[2]],
+          depth: c.dist,
+        });
+      } catch {
+        break;
+      }
+    }
+    contactsRef.current = contacts;
+    callbackRef.current?.(contacts);
+  });
+  return contactsRef;
+}
+/**
+ * Contact enter/exit events for a specific body (spec 2.5).
+ * Tracks which geom pairs are in contact frame-to-frame and fires
+ * onEnter/onExit callbacks on transitions.
+ */
+export function useContactEvents(
+  bodyName: string,
+  handlers: {
+    onEnter?: (info: ContactInfo) => void;
+    onExit?: (info: ContactInfo) => void;
+  },
+) {
+  const prevPairsRef = useRef(new Set<string>());
+  const onEnterRef = useRef(handlers.onEnter);
+  const onExitRef = useRef(handlers.onExit);
+  onEnterRef.current = handlers.onEnter;
+  onExitRef.current = handlers.onExit;
+  const prevContactMapRef = useRef(new Map<string, ContactInfo>());
+  const onContacts = useCallback((contacts: ContactInfo[]) => {
+    const currentPairs = new Set<string>();
+    const currentMap = new Map<string, ContactInfo>();
+    for (const c of contacts) {
+      const key = `${Math.min(c.geom1, c.geom2)}_${Math.max(c.geom1, c.geom2)}`;
+      currentPairs.add(key);
+      currentMap.set(key, c);
+    }
+    // New contacts (enter)
+    for (const key of currentPairs) {
+      if (!prevPairsRef.current.has(key)) {
+        onEnterRef.current?.(currentMap.get(key)!);
+      }
+    }
+    // Lost contacts (exit)
+    for (const key of prevPairsRef.current) {
+      if (!currentPairs.has(key)) {
+        const prev = prevContactMapRef.current.get(key);
+        if (prev) onExitRef.current?.(prev);
+      }
+    }
+    prevPairsRef.current = currentPairs;
+    prevContactMapRef.current = currentMap;
+  }, []);
+  useContacts(bodyName, onContacts);
+}

package/src/hooks/useCtrl.ts ADDED Viewed

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * useCtrl — clean read/write access to a named actuator's ctrl value (spec 3.1)
+ */
+import { useCallback, useEffect, useRef } from 'react';
+import { useMujocoSim } from '../core/MujocoSimProvider';
+import { findActuatorByName } from '../core/SceneLoader';
+/**
+ * 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]`.
+ */
+export function useCtrl(name: string): [React.RefObject<number>, (value: number) => void] {
+  const { mjModelRef, mjDataRef, status } = useMujocoSim();
+  const actuatorIdRef = useRef(-1);
+  const valueRef = useRef(0);
+  useEffect(() => {
+    const model = mjModelRef.current;
+    if (!model || status !== 'ready') return;
+    actuatorIdRef.current = findActuatorByName(model, name);
+  }, [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];
+}

package/src/hooks/useCtrlNoise.ts ADDED Viewed

@@ -0,0 +1,59 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * useCtrlNoise — control noise / perturbation hook (spec 3.2)
+ */
+import { useRef } from 'react';
+import { useMujocoSim, useBeforePhysicsStep } from '../core/MujocoSimProvider';
+interface CtrlNoiseConfig {
+  /** Exponential filter rate (0-1). Higher = faster noise changes. Default: 0.01. */
+  rate?: number;
+  /** Standard deviation of Gaussian noise. Default: 0.05. */
+  std?: number;
+  /** Enable/disable. Default: true. */
+  enabled?: boolean;
+}
+/**
+ * Apply Gaussian noise with exponential filtering to all ctrl values.
+ * Useful for robustness testing and domain randomization.
+ *
+ * noise[i] = (1 - rate) * noise[i] + rate * N(0, std)
+ * data.ctrl[i] += noise[i]
+ */
+export function useCtrlNoise(config: CtrlNoiseConfig = {}) {
+  const { mjModelRef } = useMujocoSim();
+  const configRef = useRef(config);
+  configRef.current = config;
+  const noiseRef = useRef<Float64Array | null>(null);
+  useBeforePhysicsStep((_model, data) => {
+    const cfg = configRef.current;
+    if (cfg.enabled === false) return;
+    const rate = cfg.rate ?? 0.01;
+    const std = cfg.std ?? 0.05;
+    const nu = mjModelRef.current?.nu ?? 0;
+    if (nu === 0) return;
+    // Initialize noise buffer
+    if (!noiseRef.current || noiseRef.current.length !== nu) {
+      noiseRef.current = new Float64Array(nu);
+    }
+    const noise = noiseRef.current;
+    for (let i = 0; i < nu; i++) {
+      // Box-Muller transform for Gaussian noise
+      const u1 = Math.random();
+      const u2 = Math.random();
+      const gaussian = Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+      // Exponential filter
+      noise[i] = (1 - rate) * noise[i] + rate * gaussian * std;
+      data.ctrl[i] += noise[i];
+    }
+  });
+}

package/src/hooks/useGamepad.ts ADDED Viewed

@@ -0,0 +1,77 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * useGamepad — gamepad teleoperation hook (spec 12.2)
+ */
+import { useEffect, useRef } from 'react';
+import { useMujocoSim, useBeforePhysicsStep } from '../core/MujocoSimProvider';
+import { findActuatorByName } from '../core/SceneLoader';
+interface GamepadConfig {
+  /** Map gamepad axis index to actuator name. */
+  axes?: Record<number, string>;
+  /** Map gamepad button index to actuator name. */
+  buttons?: Record<number, string>;
+  /** Axis deadzone. Default: 0.1. */
+  deadzone?: number;
+  /** Scale factor for axis values. Default: 1.0. */
+  scale?: number;
+  /** Gamepad index. Default: 0 (first connected). */
+  gamepadIndex?: number;
+  enabled?: boolean;
+}
+/**
+ * Map gamepad axes and buttons to actuator controls.
+ * Axes map their -1..1 value (scaled) to the actuator.
+ * Buttons map their 0..1 pressed value to the actuator.
+ */
+export function useGamepad(config: GamepadConfig) {
+  const { mjModelRef, status } = useMujocoSim();
+  const configRef = useRef(config);
+  configRef.current = config;
+  // Cache actuator IDs
+  const axisCacheRef = useRef(new Map<number, number>());
+  const buttonCacheRef = useRef(new Map<number, number>());
+  useEffect(() => {
+    const model = mjModelRef.current;
+    if (!model || status !== 'ready') return;
+    axisCacheRef.current.clear();
+    buttonCacheRef.current.clear();
+    for (const [idx, name] of Object.entries(config.axes ?? {})) {
+      axisCacheRef.current.set(Number(idx), findActuatorByName(model, name));
+    }
+    for (const [idx, name] of Object.entries(config.buttons ?? {})) {
+      buttonCacheRef.current.set(Number(idx), findActuatorByName(model, name));
+    }
+  }, [config.axes, config.buttons, status, mjModelRef]);
+  useBeforePhysicsStep((_model, data) => {
+    const cfg = configRef.current;
+    if (cfg.enabled === false) return;
+    const gamepads = navigator.getGamepads?.();
+    if (!gamepads) return;
+    const gp = gamepads[cfg.gamepadIndex ?? 0];
+    if (!gp) return;
+    const deadzone = cfg.deadzone ?? 0.1;
+    const scale = cfg.scale ?? 1.0;
+    for (const [axisIdx, actId] of axisCacheRef.current) {
+      if (actId < 0 || axisIdx >= gp.axes.length) continue;
+      let val = gp.axes[axisIdx];
+      if (Math.abs(val) < deadzone) val = 0;
+      data.ctrl[actId] = val * scale;
+    }
+    for (const [btnIdx, actId] of buttonCacheRef.current) {
+      if (actId < 0 || btnIdx >= gp.buttons.length) continue;
+      data.ctrl[actId] = gp.buttons[btnIdx].value;
+    }
+  });
+}

package/src/hooks/useGravityCompensation.ts ADDED Viewed

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { useBeforePhysicsStep } from '../core/MujocoSimProvider';
+/**
+ * Applies gravity compensation each physics frame by adding qfrc_bias
+ * (gravity + Coriolis forces) to qfrc_applied for each DOF.
+ *
+ * The provider zeros qfrc_applied at the start of each frame, so this
+ * hook (and DragInteraction) compose correctly — both add to a clean slate.
+ */
+export function useGravityCompensation(enabled = true): void {
+  useBeforePhysicsStep((model, data) => {
+    if (!enabled) return;
+    for (let i = 0; i < model.nv; i++) {
+      data.qfrc_applied[i] += data.qfrc_bias[i];
+    }
+  });
+}