mujoco-react 0.1.0

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "mujoco-react",
+  "version": "0.1.0",
+  "description": "Composable React Three Fiber building blocks for MuJoCo WASM simulations",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "mujoco",
+    "react",
+    "three",
+    "r3f",
+    "react-three-fiber",
+    "physics",
+    "simulation",
+    "robotics",
+    "wasm"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/noah/mujoco-react"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@react-three/drei": ">=9",
+    "@react-three/fiber": ">=8",
+    "react": ">=18",
+    "three": ">=0.160.0"
+  },
+  "dependencies": {
+    "mujoco-js": "0.0.7"
+  },
+  "devDependencies": {
+    "@react-three/drei": "^10.7.7",
+    "@react-three/fiber": "^9.5.0",
+    "@types/react": "^19.0.0",
+    "@types/three": "^0.181.0",
+    "react": "^19.2.0",
+    "three": "^0.181.0",
+    "tsup": "^8.4.0",
+    "typescript": "~5.8.2"
+  }
+}

package/src/components/ContactListener.tsx

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * ContactListener — component form of contact events (spec 2.5)
+ */
+
+import { useContactEvents } from '../hooks/useContacts';
+import type { ContactListenerProps } from '../types';
+
+/**
+ * Component form of useContactEvents.
+ * Fires onContactEnter/onContactExit callbacks when contacts change.
+ */
+export function ContactListener({
+  body,
+  onContactEnter,
+  onContactExit,
+}: ContactListenerProps) {
+  useContactEvents(body, {
+    onEnter: onContactEnter,
+    onExit: onContactExit,
+  });
+
+  return null;
+}

package/src/components/ContactMarkers.tsx

@@ -0,0 +1,81 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * ContactMarkers — instanced sphere visualization of MuJoCo contacts (spec 6.2)
+ *
+ * Fixed from original: reads data.ncon first, accesses contact via .get(i),
+ * limits to maxContacts to avoid WASM heap OOM.
+ */
+
+import { useRef } from 'react';
+import { useFrame } from '@react-three/fiber';
+import * as THREE from 'three';
+import { useMujocoSim } from '../core/MujocoSimProvider';
+
+const _dummy = new THREE.Object3D();
+
+interface ContactMarkersProps {
+  /** Maximum contacts to render. Default: 100. */
+  maxContacts?: number;
+  /** Sphere radius. Default: 0.005. */
+  radius?: number;
+  /** Color. Default: '#4f46e5'. */
+  color?: string;
+  /** Show markers. Default: true. */
+  visible?: boolean;
+}
+
+export function ContactMarkers({
+  maxContacts = 100,
+  radius = 0.005,
+  color = '#4f46e5',
+  visible = true,
+}: ContactMarkersProps = {}) {
+  const { mjDataRef, status } = useMujocoSim();
+  const meshRef = useRef<THREE.InstancedMesh>(null);
+
+  useFrame(() => {
+    const mesh = meshRef.current;
+    const data = mjDataRef.current;
+    if (!mesh || !data || !visible) {
+      if (mesh) mesh.count = 0;
+      return;
+    }
+
+    const ncon = data.ncon;
+    const count = Math.min(ncon, maxContacts);
+
+    for (let i = 0; i < count; i++) {
+      try {
+        const c = (data.contact as { get(i: number): { pos: Float64Array } | undefined }).get(i);
+        if (!c) break;
+        _dummy.position.set(c.pos[0], c.pos[1], c.pos[2]);
+        _dummy.updateMatrix();
+        mesh.setMatrixAt(i, _dummy.matrix);
+      } catch {
+        // Contact access failed — stop here
+        mesh.count = i;
+        mesh.instanceMatrix.needsUpdate = true;
+        return;
+      }
+    }
+
+    mesh.count = count;
+    mesh.instanceMatrix.needsUpdate = true;
+  });
+
+  if (status !== 'ready') return null;
+
+  return (
+    <instancedMesh ref={meshRef} args={[undefined, undefined, maxContacts]}>
+      <sphereGeometry args={[radius, 8, 8]} />
+      <meshStandardMaterial
+        color={color}
+        emissive={color}
+        emissiveIntensity={0.3}
+        roughness={0.5}
+      />
+    </instancedMesh>
+  );
+}

package/src/components/Debug.tsx

@@ -0,0 +1,227 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Debug — visualization overlay for MuJoCo scene elements (spec 6.1)
+ */
+
+import { useEffect, useMemo, useRef } from 'react';
+import { useFrame, useThree } from '@react-three/fiber';
+import * as THREE from 'three';
+import { useMujocoSim } from '../core/MujocoSimProvider';
+import { getName } from '../core/SceneLoader';
+import type { DebugProps } from '../types';
+
+const JOINT_COLORS: Record<number, number> = {
+  0: 0xff0000, // free - red
+  1: 0x00ff00, // ball - green
+  2: 0x0000ff, // slide - blue
+  3: 0xffff00, // hinge - yellow
+};
+
+/**
+ * Declarative debug visualization component.
+ * Renders wireframe geoms, site markers, joint axes, contact forces, COM markers, etc.
+ */
+export function Debug({
+  showGeoms = false,
+  showSites = false,
+  showJoints = false,
+  showContacts = false,
+  showCOM = false,
+  showInertia = false,
+  showTendons = false,
+}: DebugProps) {
+  const { mjModelRef, mjDataRef, status } = useMujocoSim();
+  const { scene } = useThree();
+  const groupRef = useRef<THREE.Group>(null);
+
+  // Build static debug geometry when model loads
+  const debugGeometry = useMemo(() => {
+    const model = mjModelRef.current;
+    if (!model || status !== 'ready') return null;
+
+    const geoms: THREE.Object3D[] = [];
+    const sites: THREE.Object3D[] = [];
+    const joints: THREE.Object3D[] = [];
+    const comMarkers: THREE.Object3D[] = [];
+
+    // Wireframe geoms
+    if (showGeoms) {
+      for (let i = 0; i < model.ngeom; i++) {
+        const type = model.geom_type[i];
+        const s = model.geom_size;
+        let geometry: THREE.BufferGeometry | null = null;
+
+        switch (type) {
+          case 2: // sphere
+            geometry = new THREE.SphereGeometry(s[3 * i], 12, 8);
+            break;
+          case 3: // capsule
+            geometry = new THREE.CapsuleGeometry(s[3 * i], s[3 * i + 1] * 2, 6, 8);
+            break;
+          case 5: // cylinder
+            geometry = new THREE.CylinderGeometry(s[3 * i], s[3 * i], s[3 * i + 1] * 2, 12);
+            break;
+          case 6: // box
+            geometry = new THREE.BoxGeometry(s[3 * i] * 2, s[3 * i + 1] * 2, s[3 * i + 2] * 2);
+            break;
+        }
+
+        if (geometry) {
+          const mat = new THREE.MeshBasicMaterial({ color: 0x00ff00, wireframe: true, transparent: true, opacity: 0.3 });
+          const mesh = new THREE.Mesh(geometry, mat);
+          mesh.userData.geomId = i;
+          mesh.userData.bodyId = model.geom_bodyid[i];
+          geoms.push(mesh);
+        }
+      }
+    }
+
+    // Site markers
+    if (showSites) {
+      for (let i = 0; i < model.nsite; i++) {
+        const geometry = new THREE.OctahedronGeometry(0.01);
+        const mat = new THREE.MeshBasicMaterial({ color: 0xff00ff, transparent: true, opacity: 0.7 });
+        const mesh = new THREE.Mesh(geometry, mat);
+        mesh.userData.siteId = i;
+        sites.push(mesh);
+      }
+    }
+
+    // Joint axes
+    if (showJoints) {
+      for (let i = 0; i < model.njnt; i++) {
+        const type = model.jnt_type[i];
+        const color = JOINT_COLORS[type] ?? 0xffffff;
+        const arrow = new THREE.ArrowHelper(
+          new THREE.Vector3(0, 0, 1), new THREE.Vector3(),
+          0.05, color, 0.01, 0.005
+        );
+        arrow.userData.jointId = i;
+        joints.push(arrow);
+      }
+    }
+
+    // COM markers
+    if (showCOM) {
+      for (let i = 1; i < model.nbody; i++) {
+        const geometry = new THREE.SphereGeometry(0.005, 6, 6);
+        const mat = new THREE.MeshBasicMaterial({ color: 0xff0000 });
+        const mesh = new THREE.Mesh(geometry, mat);
+        mesh.userData.bodyId = i;
+        comMarkers.push(mesh);
+      }
+    }
+
+    return { geoms, sites, joints, comMarkers };
+  }, [status, mjModelRef, showGeoms, showSites, showJoints, showCOM]);
+
+  // Add/remove debug objects from scene
+  useEffect(() => {
+    const group = groupRef.current;
+    if (!group || !debugGeometry) return;
+
+    const allObjects = [
+      ...debugGeometry.geoms,
+      ...debugGeometry.sites,
+      ...debugGeometry.joints,
+      ...debugGeometry.comMarkers,
+    ];
+    for (const obj of allObjects) group.add(obj);
+
+    return () => {
+      for (const obj of allObjects) {
+        group.remove(obj);
+        if ((obj as THREE.Mesh).geometry) (obj as THREE.Mesh).geometry.dispose();
+      }
+    };
+  }, [debugGeometry]);
+
+  // Update positions every frame
+  useFrame(() => {
+    const model = mjModelRef.current;
+    const data = mjDataRef.current;
+    if (!model || !data || !debugGeometry) return;
+
+    // Update geom wireframes
+    for (const mesh of debugGeometry.geoms) {
+      const bid = mesh.userData.bodyId;
+      const i3 = bid * 3;
+      const i4 = bid * 4;
+      mesh.position.set(data.xpos[i3], data.xpos[i3 + 1], data.xpos[i3 + 2]);
+      mesh.quaternion.set(
+        data.xquat[i4 + 1], data.xquat[i4 + 2],
+        data.xquat[i4 + 3], data.xquat[i4]
+      );
+      // Apply local geom offset
+      const gid = mesh.userData.geomId;
+      const gp = model.geom_pos;
+      mesh.position.add(new THREE.Vector3(gp[3 * gid], gp[3 * gid + 1], gp[3 * gid + 2])
+        .applyQuaternion(mesh.quaternion));
+    }
+
+    // Update site markers
+    for (const mesh of debugGeometry.sites) {
+      const sid = mesh.userData.siteId;
+      mesh.position.set(
+        data.site_xpos[3 * sid],
+        data.site_xpos[3 * sid + 1],
+        data.site_xpos[3 * sid + 2],
+      );
+    }
+
+    // Update COM markers
+    for (const mesh of debugGeometry.comMarkers) {
+      const bid = mesh.userData.bodyId;
+      const i3 = bid * 3;
+      mesh.position.set(data.xpos[i3], data.xpos[i3 + 1], data.xpos[i3 + 2]);
+    }
+  });
+
+  // Contact force vectors
+  const contactGroupRef = useRef<THREE.Group>(null);
+  const contactArrowsRef = useRef<THREE.ArrowHelper[]>([]);
+
+  useFrame(() => {
+    if (!showContacts) return;
+    const model = mjModelRef.current;
+    const data = mjDataRef.current;
+    const group = contactGroupRef.current;
+    if (!model || !data || !group) return;
+
+    // Remove old arrows
+    for (const arrow of contactArrowsRef.current) {
+      group.remove(arrow);
+      arrow.dispose();
+    }
+    contactArrowsRef.current = [];
+
+    const ncon = data.ncon;
+    for (let i = 0; i < Math.min(ncon, 50); i++) {
+      try {
+        const c = (data.contact as { get(i: number): { pos: Float64Array; frame: Float64Array; dist: number } }).get(i);
+        const pos = new THREE.Vector3(c.pos[0], c.pos[1], c.pos[2]);
+        const normal = new THREE.Vector3(c.frame[0], c.frame[1], c.frame[2]);
+        const force = Math.abs(c.dist) * 100;
+        const length = Math.min(force * 0.01, 0.1);
+        if (length > 0.001) {
+          const arrow = new THREE.ArrowHelper(normal, pos, length, 0xff4444, length * 0.3, length * 0.15);
+          group.add(arrow);
+          contactArrowsRef.current.push(arrow);
+        }
+      } catch {
+        break;
+      }
+    }
+  });
+
+  if (status !== 'ready') return null;
+
+  return (
+    <>
+      <group ref={groupRef} />
+      {showContacts && <group ref={contactGroupRef} />}
+    </>
+  );
+}

package/src/components/DragInteraction.tsx

@@ -0,0 +1,227 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { useFrame, useThree } from '@react-three/fiber';
+import { useEffect, useRef } from 'react';
+import * as THREE from 'three';
+import { useMujocoSim, useBeforePhysicsStep } from '../core/MujocoSimProvider';
+import type { DragInteractionProps } from '../types';
+
+// Preallocated temps to avoid GC pressure
+const _force = new Float64Array(3);
+const _torque = new Float64Array(3); // always [0,0,0]
+const _point = new Float64Array(3);
+const _bodyPos = new THREE.Vector3();
+const _bodyQuat = new THREE.Quaternion();
+const _worldHit = new THREE.Vector3();
+const _raycaster = new THREE.Raycaster();
+const _mouse = new THREE.Vector2();
+
+/**
+ * DragInteraction — Ctrl/Cmd+click-drag to apply spring forces to MuJoCo bodies.
+ *
+ * Raycasts against scene meshes to identify bodies, then applies a spring
+ * force pulling the grabbed point toward the cursor each physics frame.
+ * Requires Ctrl (or Cmd on macOS) to avoid conflicting with OrbitControls.
+ *
+ * - `stiffness` — Spring constant * body mass. Default: 250.
+ * - `showArrow` — Show arrow from grab point toward cursor. Default: true.
+ *
+ * Forces compose with useGravityCompensation — the provider zeros
+ * qfrc_applied each frame, then all consumers add to it.
+ */
+export function DragInteraction({
+  stiffness = 250,
+  showArrow = true,
+}: DragInteractionProps) {
+  const { mjDataRef, mujocoRef, mjModelRef, status } = useMujocoSim();
+  const { gl, camera, scene, controls } = useThree();
+
+  const draggingRef = useRef(false);
+  const bodyIdRef = useRef(-1);
+  const grabDistanceRef = useRef(0);
+  const localHitRef = useRef(new THREE.Vector3());
+  const grabWorldRef = useRef(new THREE.Vector3());
+  const mouseWorldRef = useRef(new THREE.Vector3());
+
+  // Arrow helper for visual feedback (managed imperatively)
+  const arrowRef = useRef<THREE.ArrowHelper | null>(null);
+  const groupRef = useRef<THREE.Group>(null);
+
+  useEffect(() => {
+    if (!showArrow || !groupRef.current) return;
+    const arrow = new THREE.ArrowHelper(
+      new THREE.Vector3(0, 1, 0),
+      new THREE.Vector3(),
+      0.1,
+      0xff4444,
+    );
+    arrow.visible = false;
+    // Make arrow semi-transparent
+    (arrow.line.material as THREE.LineBasicMaterial).transparent = true;
+    (arrow.line.material as THREE.LineBasicMaterial).opacity = 0.6;
+    (arrow.cone.material as THREE.MeshBasicMaterial).transparent = true;
+    (arrow.cone.material as THREE.MeshBasicMaterial).opacity = 0.6;
+    groupRef.current.add(arrow);
+    arrowRef.current = arrow;
+    return () => {
+      if (groupRef.current) groupRef.current.remove(arrow);
+      arrow.dispose();
+      arrowRef.current = null;
+    };
+  }, [showArrow]);
+
+  // Pointer events on the canvas
+  useEffect(() => {
+    const canvas = gl.domElement;
+
+    const onPointerDown = (evt: PointerEvent) => {
+      if (evt.button !== 0) return; // left click only
+      if (!evt.ctrlKey && !evt.metaKey) return; // require Ctrl/Cmd+click
+      const rect = canvas.getBoundingClientRect();
+      _mouse.set(
+        ((evt.clientX - rect.left) / rect.width) * 2 - 1,
+        -((evt.clientY - rect.top) / rect.height) * 2 + 1,
+      );
+      _raycaster.setFromCamera(_mouse, camera);
+
+      const hits = _raycaster.intersectObjects(scene.children, true);
+      for (const hit of hits) {
+        let obj: THREE.Object3D | null = hit.object;
+        while (obj && obj.userData.bodyID === undefined && obj.parent) {
+          obj = obj.parent;
+        }
+        const bid = obj?.userData.bodyID;
+        if (bid !== undefined && bid > 0) {
+          bodyIdRef.current = bid;
+          draggingRef.current = true;
+          grabDistanceRef.current = hit.distance;
+
+          // Store hit point in body-local coords
+          const data = mjDataRef.current;
+          if (data) {
+            const i3 = bid * 3;
+            const i4 = bid * 4;
+            _bodyPos.set(data.xpos[i3], data.xpos[i3 + 1], data.xpos[i3 + 2]);
+            // MuJoCo xquat is [w,x,y,z]; THREE wants (x,y,z,w)
+            _bodyQuat.set(
+              data.xquat[i4 + 1], data.xquat[i4 + 2],
+              data.xquat[i4 + 3], data.xquat[i4]
+            );
+            // World hit → body-local: inverse(bodyRot) * (hitWorld - bodyPos)
+            localHitRef.current.copy(hit.point).sub(_bodyPos);
+            localHitRef.current.applyQuaternion(_bodyQuat.clone().invert());
+          }
+
+          mouseWorldRef.current.copy(hit.point);
+          grabWorldRef.current.copy(hit.point);
+
+          // Disable orbit controls during drag
+          if (controls) (controls as unknown as { enabled: boolean }).enabled = false;
+          break;
+        }
+      }
+    };
+
+    const onPointerMove = (evt: PointerEvent) => {
+      if (!draggingRef.current) return;
+      // Safety: if no buttons are pressed, the pointerup was missed
+      if (evt.buttons === 0) {
+        draggingRef.current = false;
+        bodyIdRef.current = -1;
+        if (controls) (controls as unknown as { enabled: boolean }).enabled = true;
+        return;
+      }
+      const rect = canvas.getBoundingClientRect();
+      _mouse.set(
+        ((evt.clientX - rect.left) / rect.width) * 2 - 1,
+        -((evt.clientY - rect.top) / rect.height) * 2 + 1,
+      );
+      _raycaster.setFromCamera(_mouse, camera);
+      // Project mouse ray to the same grab distance
+      mouseWorldRef.current.copy(_raycaster.ray.origin)
+        .addScaledVector(_raycaster.ray.direction, grabDistanceRef.current);
+    };
+
+    const onPointerUp = () => {
+      if (!draggingRef.current) return;
+      draggingRef.current = false;
+      bodyIdRef.current = -1;
+      if (controls) (controls as unknown as { enabled: boolean }).enabled = true;
+    };
+
+    canvas.addEventListener('pointerdown', onPointerDown);
+    canvas.addEventListener('pointermove', onPointerMove);
+    // Listen on window so we catch releases even if pointer leaves the canvas
+    window.addEventListener('pointerup', onPointerUp);
+    window.addEventListener('pointercancel', onPointerUp);
+    return () => {
+      canvas.removeEventListener('pointerdown', onPointerDown);
+      canvas.removeEventListener('pointermove', onPointerMove);
+      window.removeEventListener('pointerup', onPointerUp);
+      window.removeEventListener('pointercancel', onPointerUp);
+    };
+  }, [gl, camera, scene, controls, mjDataRef]);
+
+  // Apply spring force each physics frame
+  useBeforePhysicsStep((model, data) => {
+    if (!draggingRef.current || bodyIdRef.current <= 0) return;
+
+    const bid = bodyIdRef.current;
+    const mujoco = mujocoRef.current;
+
+    // Reconstruct grab point world position from body's current pose
+    const i3 = bid * 3;
+    const i4 = bid * 4;
+    _bodyPos.set(data.xpos[i3], data.xpos[i3 + 1], data.xpos[i3 + 2]);
+    _bodyQuat.set(
+      data.xquat[i4 + 1], data.xquat[i4 + 2],
+      data.xquat[i4 + 3], data.xquat[i4]
+    );
+    _worldHit.copy(localHitRef.current);
+    _worldHit.applyQuaternion(_bodyQuat);
+    _worldHit.add(_bodyPos);
+    grabWorldRef.current.copy(_worldHit);
+
+    // Compute spring force: F = (mouseWorld - grabWorld) * body_mass * stiffness
+    const mass = model.body_mass[bid];
+    const s = stiffness * mass;
+    _force[0] = (mouseWorldRef.current.x - _worldHit.x) * s;
+    _force[1] = (mouseWorldRef.current.y - _worldHit.y) * s;
+    _force[2] = (mouseWorldRef.current.z - _worldHit.z) * s;
+
+    _point[0] = _worldHit.x;
+    _point[1] = _worldHit.y;
+    _point[2] = _worldHit.z;
+
+    _torque[0] = 0; _torque[1] = 0; _torque[2] = 0;
+
+    mujoco.mj_applyFT(model, data, _force, _torque, _point, bid, data.qfrc_applied);
+  });
+
+  // Update arrow visual
+  useFrame(() => {
+    const arrow = arrowRef.current;
+    if (!arrow) return;
+
+    if (draggingRef.current && bodyIdRef.current > 0) {
+      arrow.visible = true;
+      const dir = mouseWorldRef.current.clone().sub(grabWorldRef.current);
+      const len = dir.length();
+      if (len > 0.001) {
+        dir.normalize();
+        arrow.position.copy(grabWorldRef.current);
+        arrow.setDirection(dir);
+        arrow.setLength(len, Math.min(len * 0.2, 0.05), Math.min(len * 0.1, 0.03));
+      }
+    } else {
+      arrow.visible = false;
+    }
+  });
+
+  if (status !== 'ready') return null;
+
+  return <group ref={groupRef} />;
+}