mujoco-react 8.5.0 → 8.6.0

package/dist/index.js

@@ -742,7 +742,152 @@ function loadModelFromPath(mujoco, path) {
   }
   throw new Error("MuJoCo WASM module does not expose an XML path loader");
 }
+function isModelTextFile(fname) {
+  const lower = fname.toLowerCase();
+  return lower.endsWith(".xml") || lower.endsWith(".urdf") || lower.endsWith(".mjcf");
+}
+function normalizeVfsPath(path) {
+  const parts = path.replace(/\\/g, "/").split("/");
+  const norm = [];
+  for (const part of parts) {
+    if (!part || part === ".") continue;
+    if (part === "..") norm.pop();
+    else norm.push(part);
+  }
+  return norm.join("/");
+}
+function localFilePath(file) {
+  return normalizeVfsPath(file.webkitRelativePath || file.name);
+}
+function inferSceneFile(files, options) {
+  if (options?.sceneFile) return normalizeVfsPath(options.sceneFile);
+  const paths = files.map(localFilePath);
+  const preferred = ["scene.xml", "model.xml", "robot.xml", "scene.urdf", "model.urdf", "robot.urdf"];
+  for (const name of preferred) {
+    const match = paths.find((path) => path.endsWith(name));
+    if (match) return match;
+  }
+  const firstModel = paths.find(isModelTextFile);
+  if (!firstModel) throw new Error("No MJCF XML or URDF file found in FileList");
+  return firstModel;
+}
+function createSceneConfigFromFiles(files, options = {}) {
+  const fileArray = Array.from(files);
+  return {
+    src: "",
+    sceneFile: inferSceneFile(fileArray, options),
+    files: fileArray,
+    homeJoints: options.homeJoints,
+    xmlPatches: options.xmlPatches,
+    sceneObjects: options.sceneObjects,
+    onReset: options.onReset
+  };
+}
+function applyXmlPatches(text, fname, config) {
+  let result = text;
+  for (const patch of config.xmlPatches ?? []) {
+    if (fname.endsWith(patch.target) || fname === patch.target) {
+      if (patch.replace) {
+        const [from, to] = patch.replace;
+        if (result.includes(from)) {
+          result = result.replace(from, to);
+        } else {
+          const preview = from.length > 80 ? `${from.slice(0, 80)}...` : from;
+          console.warn(`XML patch replace pattern not found in ${fname}: "${preview}"`);
+        }
+      }
+      if (patch.inject && patch.injectAfter) {
+        const idx = result.indexOf(patch.injectAfter);
+        if (idx !== -1) {
+          const tagEnd = result.indexOf(">", idx + patch.injectAfter.length);
+          if (tagEnd !== -1) {
+            result = result.slice(0, tagEnd + 1) + patch.inject + result.slice(tagEnd + 1);
+          } else {
+            console.warn(`XML patch inject failed in ${fname}: could not find tag end after "${patch.injectAfter}"`);
+          }
+        } else {
+          const preview = patch.injectAfter.length > 80 ? `${patch.injectAfter.slice(0, 80)}...` : patch.injectAfter;
+          console.warn(`XML patch inject anchor not found in ${fname}: "${preview}"`);
+        }
+      }
+    }
+  }
+  if (fname === config.sceneFile && config.sceneObjects?.length && result.includes("</worldbody>")) {
+    const xml = config.sceneObjects.map((obj) => sceneObjectToXml(obj)).join("");
+    result = result.replace("</worldbody>", xml + "</worldbody>");
+  }
+  return result;
+}
+async function loadSceneFromFiles(mujoco, config, onProgress) {
+  const files = config.files ?? [];
+  if (!files.length) throw new Error("loadFromFiles requires at least one File");
+  try {
+    mujoco.FS.unmount("/working");
+  } catch {
+  }
+  try {
+    mujoco.FS.mkdir("/working");
+  } catch {
+  }
+  const parser = new DOMParser();
+  const byPath = /* @__PURE__ */ new Map();
+  const byBasename = /* @__PURE__ */ new Map();
+  const written = /* @__PURE__ */ new Set();
+  const textByPath = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    const path = localFilePath(file);
+    byPath.set(path, file);
+    byBasename.set(path.split("/").pop() ?? path, file);
+  }
+  for (const [path, file] of byPath) {
+    onProgress?.(`Reading ${path}...`);
+    ensureDir(mujoco, path);
+    if (isModelTextFile(path)) {
+      const text = applyXmlPatches(await file.text(), path, config);
+      textByPath.set(path, text);
+      mujoco.FS.writeFile(`/working/${path}`, text);
+    } else {
+      mujoco.FS.writeFile(`/working/${path}`, new Uint8Array(await file.arrayBuffer()));
+    }
+    written.add(path);
+  }
+  for (const [path, text] of textByPath) {
+    const deps = collectDependencyPaths(text, path, parser);
+    for (const dep of deps) {
+      if (written.has(dep)) continue;
+      const file = byPath.get(dep) ?? byBasename.get(dep.split("/").pop() ?? dep);
+      if (!file) continue;
+      ensureDir(mujoco, dep);
+      if (isModelTextFile(dep)) {
+        mujoco.FS.writeFile(`/working/${dep}`, applyXmlPatches(await file.text(), dep, config));
+      } else {
+        mujoco.FS.writeFile(`/working/${dep}`, new Uint8Array(await file.arrayBuffer()));
+      }
+      written.add(dep);
+    }
+  }
+  onProgress?.("Loading model...");
+  const mjModel = loadModelFromPath(mujoco, `/working/${config.sceneFile}`);
+  const mjData = new mujoco.MjData(mjModel);
+  applyInitialPose(mjModel, mjData, config);
+  mujoco.mj_forward(mjModel, mjData);
+  return { mjModel, mjData };
+}
+function applyInitialPose(mjModel, mjData, config) {
+  if (!config.homeJoints) return;
+  const homeCount = Math.min(config.homeJoints.length, Math.max(mjModel.nu, mjModel.nq));
+  for (let i = 0; i < homeCount; i++) {
+    if (i < mjModel.nu) mjData.ctrl[i] = config.homeJoints[i];
+    if (i < mjModel.nq) {
+      const qposAdr = i < mjModel.nu ? getActuatedScalarQposAdr(mjModel, i) : -1;
+      mjData.qpos[qposAdr !== -1 ? qposAdr : i] = config.homeJoints[i];
+    }
+  }
+}
 async function loadScene(mujoco, config, onProgress) {
+  if (config.files?.length) {
+    return loadSceneFromFiles(mujoco, config, onProgress);
+  }
   try {
     mujoco.FS.unmount("/working");
   } catch {
@@ -760,7 +905,7 @@ async function loadScene(mujoco, config, onProgress) {
     const fname = xmlQueue.shift();
     if (downloaded.has(fname)) continue;
     downloaded.add(fname);
-    if (!fname.endsWith(".xml")) {
+    if (!isModelTextFile(fname)) {
       assetFiles.push(fname);
       continue;
     }
@@ -770,38 +915,7 @@ async function loadScene(mujoco, config, onProgress) {
       console.warn(`Failed to fetch ${fname}: ${res.status} ${res.statusText}`);
       continue;
     }
-    let text = await res.text();
-    for (const patch of config.xmlPatches ?? []) {
-      if (fname.endsWith(patch.target) || fname === patch.target) {
-        if (patch.replace) {
-          const [from, to] = patch.replace;
-          if (text.includes(from)) {
-            text = text.replace(from, to);
-          } else {
-            const preview = from.length > 80 ? `${from.slice(0, 80)}...` : from;
-            console.warn(`XML patch replace pattern not found in ${fname}: "${preview}"`);
-          }
-        }
-        if (patch.inject && patch.injectAfter) {
-          const idx = text.indexOf(patch.injectAfter);
-          if (idx !== -1) {
-            const tagEnd = text.indexOf(">", idx + patch.injectAfter.length);
-            if (tagEnd !== -1) {
-              text = text.slice(0, tagEnd + 1) + patch.inject + text.slice(tagEnd + 1);
-            } else {
-              console.warn(`XML patch inject failed in ${fname}: could not find tag end after "${patch.injectAfter}"`);
-            }
-          } else {
-            const preview = patch.injectAfter.length > 80 ? `${patch.injectAfter.slice(0, 80)}...` : patch.injectAfter;
-            console.warn(`XML patch inject anchor not found in ${fname}: "${preview}"`);
-          }
-        }
-      }
-    }
-    if (fname === config.sceneFile && config.sceneObjects?.length) {
-      const xml = config.sceneObjects.map((obj) => sceneObjectToXml(obj)).join("");
-      text = text.replace("</worldbody>", xml + "</worldbody>");
-    }
+    const text = applyXmlPatches(await res.text(), fname, config);
     ensureDir(mujoco, fname);
     mujoco.FS.writeFile(`/working/${fname}`, text);
     scanDependencies(text, fname, parser, downloaded, xmlQueue);
@@ -827,48 +941,49 @@ async function loadScene(mujoco, config, onProgress) {
   onProgress?.("Loading model...");
   const mjModel = loadModelFromPath(mujoco, `/working/${config.sceneFile}`);
   const mjData = new mujoco.MjData(mjModel);
-  if (config.homeJoints) {
-    const homeCount = Math.min(config.homeJoints.length, mjModel.nu);
-    for (let i = 0; i < homeCount; i++) {
-      mjData.ctrl[i] = config.homeJoints[i];
-      const qposAdr = getActuatedScalarQposAdr(mjModel, i);
-      if (qposAdr !== -1) {
-        mjData.qpos[qposAdr] = config.homeJoints[i];
-      }
-    }
-  }
+  applyInitialPose(mjModel, mjData, config);
   mujoco.mj_forward(mjModel, mjData);
   return { mjModel, mjData };
 }
 function scanDependencies(xmlString, currentFile, parser, downloaded, queue) {
+  for (const fullPath of collectDependencyPaths(xmlString, currentFile, parser)) {
+    if (!downloaded.has(fullPath)) queue.push(fullPath);
+  }
+}
+function collectDependencyPaths(xmlString, currentFile, parser) {
   const xmlDoc = parser.parseFromString(xmlString, "text/xml");
   const compiler = xmlDoc.querySelector("compiler");
   const assetDir = compiler?.getAttribute("assetdir") || "";
   const meshDir = compiler?.getAttribute("meshdir") || assetDir;
   const textureDir = compiler?.getAttribute("texturedir") || assetDir;
   const currentDir = currentFile.includes("/") ? currentFile.substring(0, currentFile.lastIndexOf("/") + 1) : "";
-  xmlDoc.querySelectorAll("[file]").forEach((el) => {
-    const fileAttr = el.getAttribute("file");
+  const paths = [];
+  xmlDoc.querySelectorAll("[file], [filename]").forEach((el) => {
+    const fileAttr = el.getAttribute("file") ?? el.getAttribute("filename");
     if (!fileAttr) return;
+    if (/^[a-z]+:\/\//i.test(fileAttr) || fileAttr.startsWith("package://")) 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 = [];
-    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);
+    const fullPath = normalizeVfsPath(currentDir + prefix + fileAttr);
+    paths.push(fullPath);
   });
+  return paths;
 }
 function SceneRenderer(props) {
-  const { mjModelRef, mjDataRef, mujocoRef, onSelectionRef, hiddenBodiesRef, status } = useMujocoContext();
+  const {
+    mjModelRef,
+    mjDataRef,
+    mujocoRef,
+    onSelectionRef,
+    hiddenBodiesRef,
+    interpolateRef,
+    interpolationStateRef,
+    status
+  } = useMujocoContext();
   const groupRef = useRef(null);
   const bodyRefs = useRef([]);
   const prevModelRef = useRef(null);
@@ -908,20 +1023,46 @@ function SceneRenderer(props) {
     const data = mjDataRef.current;
     if (!data) return;
     const bodies = bodyRefs.current;
+    const interpolation = interpolationStateRef.current;
+    const useInterpolation = interpolateRef.current && interpolation.valid;
     for (let i = 0; i < bodies.length; i++) {
       const ref = bodies[i];
       if (!ref) continue;
-      ref.position.set(
-        data.xpos[i * 3],
-        data.xpos[i * 3 + 1],
-        data.xpos[i * 3 + 2]
-      );
-      ref.quaternion.set(
-        data.xquat[i * 4 + 1],
-        data.xquat[i * 4 + 2],
-        data.xquat[i * 4 + 3],
-        data.xquat[i * 4]
-      );
+      if (useInterpolation) {
+        const alpha = interpolation.alpha;
+        const i3 = i * 3;
+        ref.position.set(
+          THREE11.MathUtils.lerp(interpolation.previousXpos[i3], interpolation.currentXpos[i3], alpha),
+          THREE11.MathUtils.lerp(interpolation.previousXpos[i3 + 1], interpolation.currentXpos[i3 + 1], alpha),
+          THREE11.MathUtils.lerp(interpolation.previousXpos[i3 + 2], interpolation.currentXpos[i3 + 2], alpha)
+        );
+        const i4 = i * 4;
+        _previousQuat.set(
+          interpolation.previousXquat[i4 + 1],
+          interpolation.previousXquat[i4 + 2],
+          interpolation.previousXquat[i4 + 3],
+          interpolation.previousXquat[i4]
+        );
+        _currentQuat.set(
+          interpolation.currentXquat[i4 + 1],
+          interpolation.currentXquat[i4 + 2],
+          interpolation.currentXquat[i4 + 3],
+          interpolation.currentXquat[i4]
+        );
+        ref.quaternion.copy(_previousQuat).slerp(_currentQuat, alpha);
+      } else {
+        ref.position.set(
+          data.xpos[i * 3],
+          data.xpos[i * 3 + 1],
+          data.xpos[i * 3 + 2]
+        );
+        ref.quaternion.set(
+          data.xquat[i * 4 + 1],
+          data.xquat[i * 4 + 2],
+          data.xquat[i * 4 + 3],
+          data.xquat[i * 4]
+        );
+      }
     }
   });
   return /* @__PURE__ */ jsx(
@@ -948,6 +1089,8 @@ function SceneRenderer(props) {
     }
   );
 }
+var _previousQuat = new THREE11.Quaternion();
+var _currentQuat = new THREE11.Quaternion();
 var JOINT_TYPE_NAMES2 = ["free", "ball", "slide", "hinge"];
 var GEOM_TYPE_NAMES = ["plane", "hfield", "sphere", "capsule", "ellipsoid", "cylinder", "box", "mesh"];
 var SENSOR_TYPE_NAMES = {
@@ -1106,6 +1249,7 @@ function MujocoSimProvider({
   substeps,
   paused,
   speed,
+  interpolate,
   children
 }) {
   const { gl, camera } = useThree();
@@ -1117,6 +1261,16 @@ function MujocoSimProvider({
   const pausedRef = useRef(paused ?? false);
   const speedRef = useRef(speed ?? 1);
   const substepsRef = useRef(substeps ?? 1);
+  const interpolateRef = useRef(interpolate ?? false);
+  const interpolationStateRef = useRef({
+    alpha: 1,
+    previousXpos: new Float64Array(0),
+    previousXquat: new Float64Array(0),
+    currentXpos: new Float64Array(0),
+    currentXquat: new Float64Array(0),
+    valid: false
+  });
+  const physicsAccumulatorRef = useRef(0);
   const stepsToRunRef = useRef(0);
   const loadGenRef = useRef(0);
   const onSelectionRef = useRef(onSelection);
@@ -1130,7 +1284,9 @@ function MujocoSimProvider({
   const bodyRegistryRef = useRef(/* @__PURE__ */ new Map());
   const hiddenBodiesRef = useRef(/* @__PURE__ */ new Set());
   const bodyReloadTimerRef = useRef(null);
-  configRef.current = config;
+  useEffect(() => {
+    configRef.current = config;
+  }, [config]);
   useEffect(() => {
     pausedRef.current = paused ?? false;
   }, [paused]);
@@ -1140,6 +1296,9 @@ function MujocoSimProvider({
   useEffect(() => {
     substepsRef.current = substeps ?? 1;
   }, [substeps]);
+  useEffect(() => {
+    interpolateRef.current = interpolate ?? false;
+  }, [interpolate]);
   useEffect(() => {
     if (!gravity) return;
     const model = mjModelRef.current;
@@ -1177,6 +1336,8 @@ function MujocoSimProvider({
         }
         mjModelRef.current = result.mjModel;
         mjDataRef.current = result.mjData;
+        physicsAccumulatorRef.current = 0;
+        interpolationStateRef.current.valid = false;
         if (gravity && result.mjModel.opt?.gravity) {
           result.mjModel.opt.gravity[0] = gravity[0];
           result.mjModel.opt.gravity[1] = gravity[1];
@@ -1201,6 +1362,8 @@ function MujocoSimProvider({
       mjDataRef.current?.delete();
       mjModelRef.current = null;
       mjDataRef.current = null;
+      physicsAccumulatorRef.current = 0;
+      interpolationStateRef.current.valid = false;
       try {
         mujoco.FS.unmount("/working");
       } catch {
@@ -1233,19 +1396,56 @@ function MujocoSimProvider({
       cb(model, data);
     }
     const numSubsteps = substepsRef.current;
-    if (stepsToRunRef.current > 0) {
+    if (!interpolateRef.current) {
+      if (stepsToRunRef.current > 0) {
+        for (let s = 0; s < stepsToRunRef.current; s++) {
+          mujoco.mj_step(model, data);
+        }
+        stepsToRunRef.current = 0;
+      } else {
+        const startSimTime = data.time;
+        const clampedDelta = Math.min(delta, 1 / 15);
+        const frameTime = clampedDelta * speedRef.current;
+        while (data.time - startSimTime < frameTime) {
+          for (let s = 0; s < numSubsteps; s++) {
+            mujoco.mj_step(model, data);
+          }
+        }
+      }
+    } else if (stepsToRunRef.current > 0) {
+      ensureInterpolationBuffers(model);
+      copyBodyPose(data, interpolationStateRef.current.previousXpos, interpolationStateRef.current.previousXquat);
       for (let s = 0; s < stepsToRunRef.current; s++) {
         mujoco.mj_step(model, data);
       }
+      copyBodyPose(data, interpolationStateRef.current.currentXpos, interpolationStateRef.current.currentXquat);
+      interpolationStateRef.current.alpha = 1;
+      interpolationStateRef.current.valid = true;
       stepsToRunRef.current = 0;
     } else {
-      const startSimTime = data.time;
+      ensureInterpolationBuffers(model);
       const clampedDelta = Math.min(delta, 1 / 15);
-      const frameTime = clampedDelta * speedRef.current;
-      while (data.time - startSimTime < frameTime) {
+      physicsAccumulatorRef.current += clampedDelta * speedRef.current;
+      const stepDt = Math.max((model.opt?.timestep ?? 2e-3) * Math.max(1, numSubsteps), 1e-6);
+      let stepped = false;
+      while (physicsAccumulatorRef.current >= stepDt) {
+        copyBodyPose(data, interpolationStateRef.current.previousXpos, interpolationStateRef.current.previousXquat);
         for (let s = 0; s < numSubsteps; s++) {
           mujoco.mj_step(model, data);
         }
+        copyBodyPose(data, interpolationStateRef.current.currentXpos, interpolationStateRef.current.currentXquat);
+        physicsAccumulatorRef.current -= stepDt;
+        stepped = true;
+      }
+      if (!interpolationStateRef.current.valid) {
+        copyBodyPose(data, interpolationStateRef.current.previousXpos, interpolationStateRef.current.previousXquat);
+        copyBodyPose(data, interpolationStateRef.current.currentXpos, interpolationStateRef.current.currentXquat);
+      }
+      interpolationStateRef.current.alpha = Math.min(Math.max(physicsAccumulatorRef.current / stepDt, 0), 1);
+      interpolationStateRef.current.valid = true;
+      if (!stepped) {
+        onStepRef.current?.(data.time);
+        return;
       }
     }
     for (const cb of afterStepCallbacks.current) {
@@ -1253,6 +1453,19 @@ function MujocoSimProvider({
     }
     onStepRef.current?.(data.time);
   }, -1);
+  function ensureInterpolationBuffers(model) {
+    const state = interpolationStateRef.current;
+    const xposLength = model.nbody * 3;
+    const xquatLength = model.nbody * 4;
+    if (state.previousXpos.length !== xposLength) state.previousXpos = new Float64Array(xposLength);
+    if (state.currentXpos.length !== xposLength) state.currentXpos = new Float64Array(xposLength);
+    if (state.previousXquat.length !== xquatLength) state.previousXquat = new Float64Array(xquatLength);
+    if (state.currentXquat.length !== xquatLength) state.currentXquat = new Float64Array(xquatLength);
+  }
+  function copyBodyPose(data, xpos, xquat) {
+    xpos.set(data.xpos.subarray(0, xpos.length));
+    xquat.set(data.xquat.subarray(0, xquat.length));
+  }
   const reset = useCallback(() => {
     const model = mjModelRef.current;
     const data = mjDataRef.current;
@@ -1660,7 +1873,7 @@ function MujocoSimProvider({
       mjModelRef.current = null;
       mjDataRef.current = null;
       setStatus("loading");
-      const result = await loadScene(mujoco, newConfig);
+      const result = await loadScene(mujoco, buildMergedConfig(newConfig));
       if (gen !== loadGenRef.current) {
         result.mjModel.delete();
         result.mjData.delete();
@@ -1668,6 +1881,8 @@ function MujocoSimProvider({
       }
       mjModelRef.current = result.mjModel;
       mjDataRef.current = result.mjData;
+      physicsAccumulatorRef.current = 0;
+      interpolationStateRef.current.valid = false;
       configRef.current = newConfig;
       setStatus("ready");
     } catch (e) {
@@ -1681,9 +1896,36 @@ function MujocoSimProvider({
     if (bodyReloadTimerRef.current) clearTimeout(bodyReloadTimerRef.current);
     bodyReloadTimerRef.current = setTimeout(() => {
       bodyReloadTimerRef.current = null;
-      loadSceneApi(buildMergedConfig(configRef.current));
+      loadSceneApi(configRef.current);
     }, 0);
   }, [loadSceneApi]);
+  const loadFromFilesApi = useCallback(
+    async (files, options) => {
+      await loadSceneApi(createSceneConfigFromFiles(files, options));
+    },
+    [loadSceneApi]
+  );
+  const addBodyApi = useCallback(async (body) => {
+    const current = configRef.current;
+    const sceneObjects = [
+      ...(current.sceneObjects ?? []).filter((obj) => obj.name !== body.name),
+      body
+    ];
+    await loadSceneApi({ ...current, sceneObjects });
+  }, [loadSceneApi]);
+  const removeBodyApi = useCallback(async (name) => {
+    const current = configRef.current;
+    bodyRegistryRef.current.delete(name);
+    const sceneObjects = (current.sceneObjects ?? []).filter((obj) => obj.name !== name);
+    await loadSceneApi({ ...current, sceneObjects });
+  }, [loadSceneApi]);
+  const recompileApi = useCallback(async (patches = []) => {
+    const current = configRef.current;
+    await loadSceneApi({
+      ...current,
+      xmlPatches: patches.length ? [...current.xmlPatches ?? [], ...patches] : current.xmlPatches
+    });
+  }, [loadSceneApi]);
   const getCanvasSnapshot = useCallback(
     (width, height, mimeType = "image/jpeg") => {
       if (width && height) {
@@ -1761,7 +2003,9 @@ function MujocoSimProvider({
       get status() {
         return status;
       },
-      config,
+      get config() {
+        return configRef.current;
+      },
       reset,
       setSpeed,
       togglePause,
@@ -1800,6 +2044,10 @@ function MujocoSimProvider({
       getKeyframeNames,
       getKeyframeCount,
       loadScene: loadSceneApi,
+      loadFromFiles: loadFromFilesApi,
+      addBody: addBodyApi,
+      removeBody: removeBodyApi,
+      recompile: recompileApi,
       getCanvasSnapshot,
       project2DTo3D,
       setBodyMass,
@@ -1810,7 +2058,6 @@ function MujocoSimProvider({
     }),
     [
       status,
-      config,
       reset,
       setSpeed,
       togglePause,
@@ -1849,6 +2096,10 @@ function MujocoSimProvider({
       getKeyframeNames,
       getKeyframeCount,
       loadSceneApi,
+      loadFromFilesApi,
+      addBodyApi,
+      removeBodyApi,
+      recompileApi,
       getCanvasSnapshot,
       project2DTo3D,
       setBodyMass,
@@ -1868,6 +2119,8 @@ function MujocoSimProvider({
       pausedRef,
       speedRef,
       substepsRef,
+      interpolateRef,
+      interpolationStateRef,
       onSelectionRef,
       beforeStepCallbacks,
       afterStepCallbacks,
@@ -1898,6 +2151,7 @@ var MujocoCanvas = forwardRef(
     substeps,
     paused,
     speed,
+    interpolate,
     children,
     ...canvasProps
   }, ref) {
@@ -1925,6 +2179,7 @@ var MujocoCanvas = forwardRef(
         substeps,
         paused,
         speed,
+        interpolate,
         children
       }
     ) });
@@ -3476,6 +3731,128 @@ function FlexRenderer(props) {
   if (status !== "ready") return null;
   return /* @__PURE__ */ jsx("group", { ...props, ref: groupRef });
 }
+var GEOM_TYPE_NAMES2 = ["plane", "hfield", "sphere", "capsule", "ellipsoid", "cylinder", "box", "mesh"];
+var _matrix = new THREE11.Matrix4();
+function getGeomInfo(model, geomId) {
+  const size = model.geom_size.subarray(geomId * 3, geomId * 3 + 3);
+  const type = model.geom_type[geomId];
+  return {
+    id: geomId,
+    name: getName(model, model.name_geomadr[geomId]),
+    type,
+    typeName: GEOM_TYPE_NAMES2[type] ?? `type-${type}`,
+    size: [size[0], size[1], size[2]],
+    bodyId: model.geom_bodyid[geomId]
+  };
+}
+function geomSignature(model, geomId) {
+  const type = model.geom_type[geomId];
+  const size = Array.from(model.geom_size.subarray(geomId * 3, geomId * 3 + 3)).join(",");
+  const mat = model.geom_matid[geomId];
+  const data = model.geom_dataid[geomId];
+  const rgba = Array.from(model.geom_rgba.subarray(geomId * 4, geomId * 4 + 4)).join(",");
+  return [type, size, mat, data, rgba].join("|");
+}
+function firstMesh(object) {
+  if (object instanceof THREE11.Mesh) return object;
+  let mesh = null;
+  object.traverse((child) => {
+    if (!mesh && child instanceof THREE11.Mesh) mesh = child;
+  });
+  return mesh;
+}
+function InstancedGeomRenderer({
+  geomGroup,
+  filter,
+  material,
+  visible = true,
+  castShadow = true,
+  receiveShadow = true,
+  ...groupProps
+} = {}) {
+  const { mjModelRef, mjDataRef, mujocoRef, status } = useMujocoContext();
+  const meshRefs = useRef([]);
+  const batches = useMemo(() => {
+    if (status !== "ready") return [];
+    const model = mjModelRef.current;
+    if (!model) return [];
+    const builder = new GeomBuilder(mujocoRef.current);
+    const grouped = /* @__PURE__ */ new Map();
+    for (let geomId = 0; geomId < model.ngeom; geomId++) {
+      if (model.geom_group[geomId] === 3) continue;
+      if (geomGroup !== void 0 && model.geom_group[geomId] !== geomGroup) continue;
+      const info = getGeomInfo(model, geomId);
+      if (filter && !filter(info)) continue;
+      const key = geomSignature(model, geomId);
+      const ids = grouped.get(key);
+      if (ids) ids.push(geomId);
+      else grouped.set(key, [geomId]);
+    }
+    const next = [];
+    for (const [key, geomIds] of grouped) {
+      if (geomIds.length < 2) continue;
+      const object = builder.create(model, geomIds[0]);
+      if (!object) continue;
+      const mesh = firstMesh(object);
+      if (!mesh) continue;
+      const sourceMaterial = Array.isArray(mesh.material) ? mesh.material[0] : mesh.material;
+      next.push({
+        key,
+        geomIds,
+        geometry: mesh.geometry.clone(),
+        material: material ?? sourceMaterial.clone()
+      });
+    }
+    return next;
+  }, [filter, geomGroup, material, mjModelRef, mujocoRef, status]);
+  useFrame(() => {
+    const data = mjDataRef.current;
+    if (!data || !visible) return;
+    batches.forEach((batch, batchIndex) => {
+      const mesh = meshRefs.current[batchIndex];
+      if (!mesh) return;
+      batch.geomIds.forEach((geomId, instanceId) => {
+        const p = geomId * 3;
+        const r = geomId * 9;
+        _matrix.set(
+          data.geom_xmat[r],
+          data.geom_xmat[r + 1],
+          data.geom_xmat[r + 2],
+          data.geom_xpos[p],
+          data.geom_xmat[r + 3],
+          data.geom_xmat[r + 4],
+          data.geom_xmat[r + 5],
+          data.geom_xpos[p + 1],
+          data.geom_xmat[r + 6],
+          data.geom_xmat[r + 7],
+          data.geom_xmat[r + 8],
+          data.geom_xpos[p + 2],
+          0,
+          0,
+          0,
+          1
+        );
+        mesh.setMatrixAt(instanceId, _matrix);
+      });
+      mesh.count = batch.geomIds.length;
+      mesh.instanceMatrix.needsUpdate = true;
+    });
+  });
+  if (status !== "ready" || batches.length === 0) return null;
+  return /* @__PURE__ */ jsx("group", { ...groupProps, visible, children: batches.map((batch, index) => /* @__PURE__ */ jsx(
+    "instancedMesh",
+    {
+      ref: (mesh) => {
+        meshRefs.current[index] = mesh;
+      },
+      args: [batch.geometry, batch.material, batch.geomIds.length],
+      castShadow,
+      receiveShadow,
+      frustumCulled: false
+    },
+    batch.key
+  )) });
+}
 var geomNameCacheByModel = /* @__PURE__ */ new WeakMap();
 function getGeomNameCached(model, geomId) {
   let perModel = geomNameCacheByModel.get(model);
@@ -4668,6 +5045,6 @@ function useCameraAnimation() {
  * useCameraAnimation — composable camera animation hook.
  */
 
-export { Body, ContactListener, ContactMarkers, Debug, DragInteraction, FlexRenderer, IkGizmo, MujocoCanvas, MujocoPhysics, MujocoProvider, MujocoSimProvider, SceneLights, TendonRenderer, TrajectoryPlayer, buildObservation, createContiguousControlGroup, createController, createControllerHook, findActuatorByName, findBodyByName, findGeomByName, findJointByName, findKeyframeByName, findSensorByName, findSiteByName, findTendonByName, getActuatedJoints, getContact, getControlMap, getName, loadScene, resolveControlGroup, useActuators, useAfterPhysicsStep, useBeforePhysicsStep, useBodyMeshes, useBodyState, useCameraAnimation, useContactEvents, useContacts, useCtrl, useCtrlNoise, useGamepad, useGravityCompensation, useIkController, useJointState, useKeyboardTeleop, useMujoco, useMujocoWasm, useObservation, usePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePosition, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder };
+export { Body, ContactListener, ContactMarkers, Debug, DragInteraction, FlexRenderer, IkGizmo, InstancedGeomRenderer, MujocoCanvas, MujocoPhysics, MujocoProvider, MujocoSimProvider, SceneLights, TendonRenderer, TrajectoryPlayer, buildObservation, createContiguousControlGroup, createController, createControllerHook, findActuatorByName, findBodyByName, findGeomByName, findJointByName, findKeyframeByName, findSensorByName, findSiteByName, findTendonByName, getActuatedJoints, getContact, getControlMap, getName, loadScene, resolveControlGroup, useActuators, useAfterPhysicsStep, useBeforePhysicsStep, useBodyMeshes, useBodyState, useCameraAnimation, useContactEvents, useContacts, useCtrl, useCtrlNoise, useGamepad, useGravityCompensation, useIkController, useJointState, useKeyboardTeleop, useMujoco, useMujocoWasm, useObservation, usePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePosition, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map