mujoco-react 8.10.0 → 8.11.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 { l as SplatEnvironmentProps } from './types-FFW7ykBu.js';
+import { l as SplatEnvironmentProps } from './types-BmneHLBM.js';
 import 'react';
 import '@react-three/fiber';
 import 'three';
@@ -8,6 +8,15 @@ import 'three';
 type SparkModule = typeof _sparkjsdev_spark;
 type SparkSplatMeshInstance = InstanceType<SparkModule['SplatMesh']>;
 type SparkSplatStatus = 'idle' | 'loading' | 'ready' | 'error';
+interface SparkSplatLifecycle {
+    status: SparkSplatStatus;
+    error: Error | null;
+    isLoading: boolean;
+    isReady: boolean;
+    isError: boolean;
+    props: Pick<SparkSplatEnvironmentProps, 'onStatusChange' | 'onError'>;
+    reset: () => void;
+}
 interface SparkSplatEnvironmentProps extends SplatEnvironmentProps {
     /** Enable Spark LoD handling for large splat assets. Default: true. */
     lod?: boolean | 'quality';
@@ -21,12 +30,24 @@ interface SparkSplatEnvironmentProps extends SplatEnvironmentProps {
     onLoad?: (mesh: SparkSplatMeshInstance) => void;
     onError?: (error: Error) => void;
 }
+/**
+ * Tracks Spark 3DGS loading state for UI that wraps `SparkSplatEnvironment`.
+ *
+ * Use the returned `props` with `<SparkSplatEnvironment {...lifecycle.props} />`
+ * to avoid repeating status/error state in app code.
+ */
+declare function useSparkSplatLifecycle({ enabled, initialStatus, onError, onStatusChange, }?: {
+    enabled?: boolean;
+    initialStatus?: SparkSplatStatus;
+    onError?: (error: Error) => void;
+    onStatusChange?: (status: SparkSplatStatus) => void;
+}): SparkSplatLifecycle;
 /**
  * Optional SparkJS-backed Gaussian splat renderer for React Three Fiber scenes.
  *
  * Import from `mujoco-react/spark` and install `@sparkjsdev/spark` in the app
  * that uses it. The core `mujoco-react` entrypoint does not depend on Spark.
  */
-declare function SparkSplatEnvironment({ environment, src, format, collisionProxy, collisionProxyMetadata, showPlaceholder, children, lod, hideGroundMeshes, onStatusChange, onLoad, onError, ...groupProps }: SparkSplatEnvironmentProps): react_jsx_runtime.JSX.Element;
+declare function SparkSplatEnvironment({ environment, scenario, renderer, src, format, collisionProxy, collisionProxyMetadata, showPlaceholder, children, lod, hideGroundMeshes, onStatusChange, onLoad, onError, ...groupProps }: SparkSplatEnvironmentProps): react_jsx_runtime.JSX.Element;
 
-export { SparkSplatEnvironment, type SparkSplatEnvironmentProps, type SparkSplatStatus };
+export { SparkSplatEnvironment, type SparkSplatEnvironmentProps, type SparkSplatLifecycle, type SparkSplatStatus, useSparkSplatLifecycle };

package/dist/spark.js

@@ -1,11 +1,65 @@
-import { useSplatEnvironment, SplatEnvironment } from './chunk-KGFRKPLS.js';
+import { useSplatEnvironment, SplatEnvironment } from './chunk-SEWQULWO.js';
 import { useThree } from '@react-three/fiber';
-import { useRef, useState, useEffect } from 'react';
+import { useState, useEffect, useCallback, useMemo, useRef } from 'react';
 import * as THREE from 'three';
 import { jsxs, jsx } from 'react/jsx-runtime';
 
+function useSparkSplatLifecycle({
+  enabled = true,
+  initialStatus,
+  onError,
+  onStatusChange
+} = {}) {
+  const [status, setStatus] = useState(
+    initialStatus ?? (enabled ? "loading" : "idle")
+  );
+  const [error, setError] = useState(null);
+  useEffect(() => {
+    setStatus(enabled ? initialStatus ?? "loading" : "idle");
+    setError(null);
+  }, [enabled, initialStatus]);
+  const handleStatusChange = useCallback(
+    (nextStatus) => {
+      setStatus(nextStatus);
+      if (nextStatus !== "error") {
+        setError(null);
+      }
+      onStatusChange?.(nextStatus);
+    },
+    [onStatusChange]
+  );
+  const handleError = useCallback(
+    (nextError) => {
+      setError(nextError);
+      setStatus("error");
+      onError?.(nextError);
+    },
+    [onError]
+  );
+  const reset = useCallback(() => {
+    setStatus(enabled ? initialStatus ?? "loading" : "idle");
+    setError(null);
+  }, [enabled, initialStatus]);
+  return useMemo(
+    () => ({
+      status,
+      error,
+      isLoading: status === "loading",
+      isReady: status === "ready",
+      isError: status === "error",
+      props: {
+        onStatusChange: handleStatusChange,
+        onError: handleError
+      },
+      reset
+    }),
+    [error, handleError, handleStatusChange, reset, status]
+  );
+}
 function SparkSplatEnvironment({
   environment,
+  scenario,
+  renderer = "spark",
   src,
   format,
   collisionProxy,
@@ -30,6 +84,8 @@ function SparkSplatEnvironment({
   const { gl, invalidate } = useThree();
   const metadata = useSplatEnvironment({
     environment,
+    scenario,
+    renderer,
     src,
     format,
     collisionProxy: collisionProxyMetadata
@@ -56,10 +112,18 @@ function SparkSplatEnvironment({
       hiddenMeshesRef.current = [];
     }
     async function loadSplat() {
-      if (!metadata.src || metadata.format !== "spz") {
+      if (!metadata.src) {
         setLifecycleStatus("idle");
         return;
       }
+      if (metadata.format !== "spz") {
+        const unsupportedFormatError = new Error(
+          `SparkSplatEnvironment only supports .spz assets; received "${metadata.format}".`
+        );
+        setLifecycleStatus("error");
+        onErrorRef.current?.(unsupportedFormatError);
+        return;
+      }
       setLifecycleStatus("loading");
       try {
         const sparkModule = await import('@sparkjsdev/spark');
@@ -106,12 +170,12 @@ function SparkSplatEnvironment({
       restoreHiddenMeshes();
       if (meshRef.current) {
         groupRef.current?.remove(meshRef.current);
-        meshRef.current.dispose?.();
+        safelyDisposeSparkResource(meshRef.current);
         meshRef.current = null;
       }
       if (sparkRef.current) {
         groupRef.current?.remove(sparkRef.current);
-        sparkRef.current.dispose?.();
+        safelyDisposeSparkResource(sparkRef.current);
         sparkRef.current = null;
       }
     };
@@ -128,6 +192,8 @@ function SparkSplatEnvironment({
     {
       ...groupProps,
       environment,
+      scenario,
+      renderer,
       src: metadata.src,
       format: metadata.format,
       collisionProxyMetadata: metadata.collisionProxy,
@@ -140,11 +206,30 @@ function SparkSplatEnvironment({
     }
   );
 }
+function safelyDisposeSparkResource(resource) {
+  try {
+    const result = resource.dispose?.();
+    if (isPromiseLike(result)) {
+      void Promise.resolve(result).catch(handleSparkDisposeError);
+    }
+  } catch (error) {
+    handleSparkDisposeError(error);
+  }
+}
+function isPromiseLike(value) {
+  return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
+}
+function handleSparkDisposeError(error) {
+  if (error instanceof Error && error.message.toLowerCase().includes("worker terminate")) {
+    return;
+  }
+  console.warn("[mujoco-react] Spark resource disposal failed.", error);
+}
 /**
  * @license
  * SPDX-License-Identifier: Apache-2.0
  */
 
-export { SparkSplatEnvironment };
+export { SparkSplatEnvironment, useSparkSplatLifecycle };
 //# sourceMappingURL=spark.js.map
 //# sourceMappingURL=spark.js.map

package/dist/spark.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/spark.tsx"],"names":[],"mappings":"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","file":"spark.js","sourcesContent":["/**\n * @license\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport { useThree } from '@react-three/fiber';\nimport { useEffect, useRef, useState } from 'react';\nimport * as THREE from 'three';\nimport {\n  SplatEnvironment,\n  useSplatEnvironment,\n} from './components/VisualScenario';\nimport type {\n  SplatEnvironmentProps,\n} from './types';\n\ntype SparkModule = typeof import('@sparkjsdev/spark');\ntype SparkRendererInstance = InstanceType<SparkModule['SparkRenderer']>;\ntype SparkSplatMeshInstance = InstanceType<SparkModule['SplatMesh']>;\n\nexport type SparkSplatStatus = 'idle' | 'loading' | 'ready' | 'error';\n\nexport interface SparkSplatEnvironmentProps extends SplatEnvironmentProps {\n  /** Enable Spark LoD handling for large splat assets. Default: true. */\n  lod?: boolean | 'quality';\n  /**\n   * Hide meshes whose names include floor, ground, or plane while the splat is\n   * active. This mirrors the common hybrid-rendering setup where MJCF keeps\n   * collision geometry but the splat owns the visual environment.\n   */\n  hideGroundMeshes?: boolean;\n  onStatusChange?: (status: SparkSplatStatus) => void;\n  onLoad?: (mesh: SparkSplatMeshInstance) => void;\n  onError?: (error: Error) => void;\n}\n\n/**\n * Optional SparkJS-backed Gaussian splat renderer for React Three Fiber scenes.\n *\n * Import from `mujoco-react/spark` and install `@sparkjsdev/spark` in the app\n * that uses it. The core `mujoco-react` entrypoint does not depend on Spark.\n */\nexport function SparkSplatEnvironment({\n  environment,\n  src,\n  format,\n  collisionProxy,\n  collisionProxyMetadata,\n  showPlaceholder,\n  children,\n  lod = true,\n  hideGroundMeshes = false,\n  onStatusChange,\n  onLoad,\n  onError,\n  ...groupProps\n}: SparkSplatEnvironmentProps) {\n  const groupRef = useRef<THREE.Group>(null);\n  const sparkRef = useRef<SparkRendererInstance | null>(null);\n  const meshRef = useRef<SparkSplatMeshInstance | null>(null);\n  const hiddenMeshesRef = useRef<THREE.Mesh[]>([]);\n  const onStatusChangeRef = useRef(onStatusChange);\n  const onLoadRef = useRef(onLoad);\n  const onErrorRef = useRef(onError);\n  const [status, setStatus] = useState<SparkSplatStatus>('idle');\n  const { gl, invalidate } = useThree();\n  const metadata = useSplatEnvironment({\n    environment,\n    src,\n    format,\n    collisionProxy: collisionProxyMetadata,\n  });\n\n  useEffect(() => {\n    onStatusChangeRef.current = onStatusChange;\n  }, [onStatusChange]);\n\n  useEffect(() => {\n    onLoadRef.current = onLoad;\n  }, [onLoad]);\n\n  useEffect(() => {\n    onErrorRef.current = onError;\n  }, [onError]);\n\n  useEffect(() => {\n    let disposed = false;\n\n    function setLifecycleStatus(nextStatus: SparkSplatStatus) {\n      setStatus(nextStatus);\n      onStatusChangeRef.current?.(nextStatus);\n    }\n\n    function restoreHiddenMeshes() {\n      for (const mesh of hiddenMeshesRef.current) {\n        mesh.visible = true;\n      }\n      hiddenMeshesRef.current = [];\n    }\n\n    async function loadSplat() {\n      if (!metadata.src || metadata.format !== 'spz') {\n        setLifecycleStatus('idle');\n        return;\n      }\n\n      setLifecycleStatus('loading');\n\n      try {\n        const sparkModule = await import('@sparkjsdev/spark');\n        if (disposed || !groupRef.current) return;\n\n        const spark = new sparkModule.SparkRenderer({\n          renderer: gl,\n          onDirty: invalidate,\n        });\n        const mesh = new sparkModule.SplatMesh({\n          url: metadata.src,\n          lod,\n        });\n        mesh.name = 'GaussianSplatMesh';\n\n        groupRef.current.add(spark);\n        groupRef.current.add(mesh);\n        sparkRef.current = spark;\n        meshRef.current = mesh;\n\n        if (hideGroundMeshes && groupRef.current.parent) {\n          groupRef.current.parent.traverse((object) => {\n            if (\n              !(object instanceof THREE.Mesh) ||\n              object === (mesh as unknown as THREE.Object3D)\n            ) {\n              return;\n            }\n            const name = object.name.toLowerCase();\n            if (\n              name.includes('floor') ||\n              name.includes('ground') ||\n              name.includes('plane')\n            ) {\n              object.visible = false;\n              hiddenMeshesRef.current.push(object);\n            }\n          });\n        }\n\n        await mesh.initialized;\n        if (disposed) return;\n        setLifecycleStatus('ready');\n        onLoadRef.current?.(mesh);\n        invalidate();\n      } catch (error) {\n        const normalizedError =\n          error instanceof Error ? error : new Error(String(error));\n        setLifecycleStatus('error');\n        onErrorRef.current?.(normalizedError);\n      }\n    }\n\n    void loadSplat();\n\n    return () => {\n      disposed = true;\n      restoreHiddenMeshes();\n\n      if (meshRef.current) {\n        groupRef.current?.remove(meshRef.current);\n        meshRef.current.dispose?.();\n        meshRef.current = null;\n      }\n\n      if (sparkRef.current) {\n        groupRef.current?.remove(sparkRef.current);\n        sparkRef.current.dispose?.();\n        sparkRef.current = null;\n      }\n    };\n  }, [\n    gl,\n    hideGroundMeshes,\n    invalidate,\n    lod,\n    metadata.format,\n    metadata.src,\n  ]);\n\n  return (\n    <SplatEnvironment\n      {...groupProps}\n      environment={environment}\n      src={metadata.src}\n      format={metadata.format}\n      collisionProxyMetadata={metadata.collisionProxy}\n      collisionProxy={collisionProxy}\n      showPlaceholder={showPlaceholder ?? status !== 'ready'}\n    >\n      <group ref={groupRef} />\n      {children}\n    </SplatEnvironment>\n  );\n}\n"]}
+{"version":3,"sources":["../src/spark.tsx"],"names":[],"mappings":";;;;;;AA6DO,SAAS,sBAAA,CAAuB;AAAA,EACrC,OAAA,GAAU,IAAA;AAAA,EACV,aAAA;AAAA,EACA,OAAA;AAAA,EACA;AACF,CAAA,GAKI,EAAC,EAAwB;AAC3B,EAAA,MAAM,CAAC,MAAA,EAAQ,SAAS,CAAA,GAAI,QAAA;AAAA,IAC1B,aAAA,KAAkB,UAAU,SAAA,GAAY,MAAA;AAAA,GAC1C;AACA,EAAA,MAAM,CAAC,KAAA,EAAO,QAAQ,CAAA,GAAI,SAAuB,IAAI,CAAA;AAErD,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,SAAA,CAAU,OAAA,GAAU,aAAA,IAAiB,SAAA,GAAY,MAAM,CAAA;AACvD,IAAA,QAAA,CAAS,IAAI,CAAA;AAAA,EACf,CAAA,EAAG,CAAC,OAAA,EAAS,aAAa,CAAC,CAAA;AAE3B,EAAA,MAAM,kBAAA,GAAqB,WAAA;AAAA,IACzB,CAAC,UAAA,KAAiC;AAChC,MAAA,SAAA,CAAU,UAAU,CAAA;AACpB,MAAA,IAAI,eAAe,OAAA,EAAS;AAC1B,QAAA,QAAA,CAAS,IAAI,CAAA;AAAA,MACf;AACA,MAAA,cAAA,GAAiB,UAAU,CAAA;AAAA,IAC7B,CAAA;AAAA,IACA,CAAC,cAAc;AAAA,GACjB;AAEA,EAAA,MAAM,WAAA,GAAc,WAAA;AAAA,IAClB,CAAC,SAAA,KAAqB;AACpB,MAAA,QAAA,CAAS,SAAS,CAAA;AAClB,MAAA,SAAA,CAAU,OAAO,CAAA;AACjB,MAAA,OAAA,GAAU,SAAS,CAAA;AAAA,IACrB,CAAA;AAAA,IACA,CAAC,OAAO;AAAA,GACV;AAEA,EAAA,MAAM,KAAA,GAAQ,YAAY,MAAM;AAC9B,IAAA,SAAA,CAAU,OAAA,GAAU,aAAA,IAAiB,SAAA,GAAY,MAAM,CAAA;AACvD,IAAA,QAAA,CAAS,IAAI,CAAA;AAAA,EACf,CAAA,EAAG,CAAC,OAAA,EAAS,aAAa,CAAC,CAAA;AAE3B,EAAA,OAAO,OAAA;AAAA,IACL,OAAO;AAAA,MACL,MAAA;AAAA,MACA,KAAA;AAAA,MACA,WAAW,MAAA,KAAW,SAAA;AAAA,MACtB,SAAS,MAAA,KAAW,OAAA;AAAA,MACpB,SAAS,MAAA,KAAW,OAAA;AAAA,MACpB,KAAA,EAAO;AAAA,QACL,cAAA,EAAgB,kBAAA;AAAA,QAChB,OAAA,EAAS;AAAA,OACX;AAAA,MACA;AAAA,KACF,CAAA;AAAA,IACA,CAAC,KAAA,EAAO,WAAA,EAAa,kBAAA,EAAoB,OAAO,MAAM;AAAA,GACxD;AACF;AAQO,SAAS,qBAAA,CAAsB;AAAA,EACpC,WAAA;AAAA,EACA,QAAA;AAAA,EACA,QAAA,GAAW,OAAA;AAAA,EACX,GAAA;AAAA,EACA,MAAA;AAAA,EACA,cAAA;AAAA,EACA,sBAAA;AAAA,EACA,eAAA;AAAA,EACA,QAAA;AAAA,EACA,GAAA,GAAM,IAAA;AAAA,EACN,gBAAA,GAAmB,KAAA;AAAA,EACnB,cAAA;AAAA,EACA,MAAA;AAAA,EACA,OAAA;AAAA,EACA,GAAG;AACL,CAAA,EAA+B;AAC7B,EAAA,MAAM,QAAA,GAAW,OAAoB,IAAI,CAAA;AACzC,EAAA,MAAM,QAAA,GAAW,OAAqC,IAAI,CAAA;AAC1D,EAAA,MAAM,OAAA,GAAU,OAAsC,IAAI,CAAA;AAC1D,EAAA,MAAM,eAAA,GAAkB,MAAA,CAAqB,EAAE,CAAA;AAC/C,EAAA,MAAM,iBAAA,GAAoB,OAAO,cAAc,CAAA;AAC/C,EAAA,MAAM,SAAA,GAAY,OAAO,MAAM,CAAA;AAC/B,EAAA,MAAM,UAAA,GAAa,OAAO,OAAO,CAAA;AACjC,EAAA,MAAM,CAAC,MAAA,EAAQ,SAAS,CAAA,GAAI,SAA2B,MAAM,CAAA;AAC7D,EAAA,MAAM,EAAE,EAAA,EAAI,UAAA,EAAW,GAAI,QAAA,EAAS;AACpC,EAAA,MAAM,WAAW,mBAAA,CAAoB;AAAA,IACnC,WAAA;AAAA,IACA,QAAA;AAAA,IACA,QAAA;AAAA,IACA,GAAA;AAAA,IACA,MAAA;AAAA,IACA,cAAA,EAAgB;AAAA,GACjB,CAAA;AAED,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,iBAAA,CAAkB,OAAA,GAAU,cAAA;AAAA,EAC9B,CAAA,EAAG,CAAC,cAAc,CAAC,CAAA;AAEnB,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,SAAA,CAAU,OAAA,GAAU,MAAA;AAAA,EACtB,CAAA,EAAG,CAAC,MAAM,CAAC,CAAA;AAEX,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,UAAA,CAAW,OAAA,GAAU,OAAA;AAAA,EACvB,CAAA,EAAG,CAAC,OAAO,CAAC,CAAA;AAEZ,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,IAAI,QAAA,GAAW,KAAA;AAEf,IAAA,SAAS,mBAAmB,UAAA,EAA8B;AACxD,MAAA,SAAA,CAAU,UAAU,CAAA;AACpB,MAAA,iBAAA,CAAkB,UAAU,UAAU,CAAA;AAAA,IACxC;AAEA,IAAA,SAAS,mBAAA,GAAsB;AAC7B,MAAA,KAAA,MAAW,IAAA,IAAQ,gBAAgB,OAAA,EAAS;AAC1C,QAAA,IAAA,CAAK,OAAA,GAAU,IAAA;AAAA,MACjB;AACA,MAAA,eAAA,CAAgB,UAAU,EAAC;AAAA,IAC7B;AAEA,IAAA,eAAe,SAAA,GAAY;AACzB,MAAA,IAAI,CAAC,SAAS,GAAA,EAAK;AACjB,QAAA,kBAAA,CAAmB,MAAM,CAAA;AACzB,QAAA;AAAA,MACF;AAEA,MAAA,IAAI,QAAA,CAAS,WAAW,KAAA,EAAO;AAC7B,QAAA,MAAM,yBAAyB,IAAI,KAAA;AAAA,UACjC,CAAA,2DAAA,EAA8D,SAAS,MAAM,CAAA,EAAA;AAAA,SAC/E;AACA,QAAA,kBAAA,CAAmB,OAAO,CAAA;AAC1B,QAAA,UAAA,CAAW,UAAU,sBAAsB,CAAA;AAC3C,QAAA;AAAA,MACF;AAEA,MAAA,kBAAA,CAAmB,SAAS,CAAA;AAE5B,MAAA,IAAI;AACF,QAAA,MAAM,WAAA,GAAc,MAAM,OAAO,mBAAmB,CAAA;AACpD,QAAA,IAAI,QAAA,IAAY,CAAC,QAAA,CAAS,OAAA,EAAS;AAEnC,QAAA,MAAM,KAAA,GAAQ,IAAI,WAAA,CAAY,aAAA,CAAc;AAAA,UAC1C,QAAA,EAAU,EAAA;AAAA,UACV,OAAA,EAAS;AAAA,SACV,CAAA;AACD,QAAA,MAAM,IAAA,GAAO,IAAI,WAAA,CAAY,SAAA,CAAU;AAAA,UACrC,KAAK,QAAA,CAAS,GAAA;AAAA,UACd;AAAA,SACD,CAAA;AACD,QAAA,IAAA,CAAK,IAAA,GAAO,mBAAA;AAEZ,QAAA,QAAA,CAAS,OAAA,CAAQ,IAAI,KAAK,CAAA;AAC1B,QAAA,QAAA,CAAS,OAAA,CAAQ,IAAI,IAAI,CAAA;AACzB,QAAA,QAAA,CAAS,OAAA,GAAU,KAAA;AACnB,QAAA,OAAA,CAAQ,OAAA,GAAU,IAAA;AAElB,QAAA,IAAI,gBAAA,IAAoB,QAAA,CAAS,OAAA,CAAQ,MAAA,EAAQ;AAC/C,UAAA,QAAA,CAAS,OAAA,CAAQ,MAAA,CAAO,QAAA,CAAS,CAAC,MAAA,KAAW;AAC3C,YAAA,IACE,EAAE,MAAA,YAAwB,KAAA,CAAA,IAAA,CAAA,IAC1B,MAAA,KAAY,IAAA,EACZ;AACA,cAAA;AAAA,YACF;AACA,YAAA,MAAM,IAAA,GAAO,MAAA,CAAO,IAAA,CAAK,WAAA,EAAY;AACrC,YAAA,IACE,IAAA,CAAK,QAAA,CAAS,OAAO,CAAA,IACrB,IAAA,CAAK,QAAA,CAAS,QAAQ,CAAA,IACtB,IAAA,CAAK,QAAA,CAAS,OAAO,CAAA,EACrB;AACA,cAAA,MAAA,CAAO,OAAA,GAAU,KAAA;AACjB,cAAA,eAAA,CAAgB,OAAA,CAAQ,KAAK,MAAM,CAAA;AAAA,YACrC;AAAA,UACF,CAAC,CAAA;AAAA,QACH;AAEA,QAAA,MAAM,IAAA,CAAK,WAAA;AACX,QAAA,IAAI,QAAA,EAAU;AACd,QAAA,kBAAA,CAAmB,OAAO,CAAA;AAC1B,QAAA,SAAA,CAAU,UAAU,IAAI,CAAA;AACxB,QAAA,UAAA,EAAW;AAAA,MACb,SAAS,KAAA,EAAO;AACd,QAAA,MAAM,eAAA,GACJ,iBAAiB,KAAA,GAAQ,KAAA,GAAQ,IAAI,KAAA,CAAM,MAAA,CAAO,KAAK,CAAC,CAAA;AAC1D,QAAA,kBAAA,CAAmB,OAAO,CAAA;AAC1B,QAAA,UAAA,CAAW,UAAU,eAAe,CAAA;AAAA,MACtC;AAAA,IACF;AAEA,IAAA,KAAK,SAAA,EAAU;AAEf,IAAA,OAAO,MAAM;AACX,MAAA,QAAA,GAAW,IAAA;AACX,MAAA,mBAAA,EAAoB;AAEpB,MAAA,IAAI,QAAQ,OAAA,EAAS;AACnB,QAAA,QAAA,CAAS,OAAA,EAAS,MAAA,CAAO,OAAA,CAAQ,OAAO,CAAA;AACxC,QAAA,0BAAA,CAA2B,QAAQ,OAAO,CAAA;AAC1C,QAAA,OAAA,CAAQ,OAAA,GAAU,IAAA;AAAA,MACpB;AAEA,MAAA,IAAI,SAAS,OAAA,EAAS;AACpB,QAAA,QAAA,CAAS,OAAA,EAAS,MAAA,CAAO,QAAA,CAAS,OAAO,CAAA;AACzC,QAAA,0BAAA,CAA2B,SAAS,OAAO,CAAA;AAC3C,QAAA,QAAA,CAAS,OAAA,GAAU,IAAA;AAAA,MACrB;AAAA,IACF,CAAA;AAAA,EACF,CAAA,EAAG;AAAA,IACD,EAAA;AAAA,IACA,gBAAA;AAAA,IACA,UAAA;AAAA,IACA,GAAA;AAAA,IACA,QAAA,CAAS,MAAA;AAAA,IACT,QAAA,CAAS;AAAA,GACV,CAAA;AAED,EAAA,uBACE,IAAA;AAAA,IAAC,gBAAA;AAAA,IAAA;AAAA,MACE,GAAG,UAAA;AAAA,MACJ,WAAA;AAAA,MACA,QAAA;AAAA,MACA,QAAA;AAAA,MACA,KAAK,QAAA,CAAS,GAAA;AAAA,MACd,QAAQ,QAAA,CAAS,MAAA;AAAA,MACjB,wBAAwB,QAAA,CAAS,cAAA;AAAA,MACjC,cAAA;AAAA,MACA,eAAA,EAAiB,mBAAmB,MAAA,KAAW,OAAA;AAAA,MAE/C,QAAA,EAAA;AAAA,wBAAA,GAAA,CAAC,OAAA,EAAA,EAAM,KAAK,QAAA,EAAU,CAAA;AAAA,QACrB;AAAA;AAAA;AAAA,GACH;AAEJ;AAEA,SAAS,2BAA2B,QAAA,EAA2B;AAC7D,EAAA,IAAI;AACF,IAAA,MAAM,MAAA,GAAS,SAAS,OAAA,IAAU;AAClC,IAAA,IAAI,aAAA,CAAc,MAAM,CAAA,EAAG;AACzB,MAAA,KAAK,OAAA,CAAQ,OAAA,CAAQ,MAAM,CAAA,CAAE,MAAM,uBAAuB,CAAA;AAAA,IAC5D;AAAA,EACF,SAAS,KAAA,EAAO;AACd,IAAA,uBAAA,CAAwB,KAAK,CAAA;AAAA,EAC/B;AACF;AAEA,SAAS,cAAc,KAAA,EAA+C;AACpE,EAAA,OACE,OAAO,UAAU,QAAA,IACjB,KAAA,KAAU,QACV,MAAA,IAAU,KAAA,IACV,OAAQ,KAAA,CAA6B,IAAA,KAAS,UAAA;AAElD;AAEA,SAAS,wBAAwB,KAAA,EAAgB;AAC/C,EAAA,IACE,KAAA,YAAiB,SACjB,KAAA,CAAM,OAAA,CAAQ,aAAY,CAAE,QAAA,CAAS,kBAAkB,CAAA,EACvD;AACA,IAAA;AAAA,EACF;AAEA,EAAA,OAAA,CAAQ,IAAA,CAAK,kDAAkD,KAAK,CAAA;AACtE","file":"spark.js","sourcesContent":["/**\n * @license\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport { useThree } from '@react-three/fiber';\nimport {\n  useCallback,\n  useEffect,\n  useMemo,\n  useRef,\n  useState,\n} from 'react';\nimport * as THREE from 'three';\nimport {\n  SplatEnvironment,\n  useSplatEnvironment,\n} from './components/VisualScenario';\nimport type {\n  SplatEnvironmentProps,\n} from './types';\n\ntype SparkModule = typeof import('@sparkjsdev/spark');\ntype SparkRendererInstance = InstanceType<SparkModule['SparkRenderer']>;\ntype SparkSplatMeshInstance = InstanceType<SparkModule['SplatMesh']>;\ntype SparkDisposable = {\n  dispose?: () => unknown;\n};\n\nexport type SparkSplatStatus = 'idle' | 'loading' | 'ready' | 'error';\n\nexport interface SparkSplatLifecycle {\n  status: SparkSplatStatus;\n  error: Error | null;\n  isLoading: boolean;\n  isReady: boolean;\n  isError: boolean;\n  props: Pick<SparkSplatEnvironmentProps, 'onStatusChange' | 'onError'>;\n  reset: () => void;\n}\n\nexport interface SparkSplatEnvironmentProps extends SplatEnvironmentProps {\n  /** Enable Spark LoD handling for large splat assets. Default: true. */\n  lod?: boolean | 'quality';\n  /**\n   * Hide meshes whose names include floor, ground, or plane while the splat is\n   * active. This mirrors the common hybrid-rendering setup where MJCF keeps\n   * collision geometry but the splat owns the visual environment.\n   */\n  hideGroundMeshes?: boolean;\n  onStatusChange?: (status: SparkSplatStatus) => void;\n  onLoad?: (mesh: SparkSplatMeshInstance) => void;\n  onError?: (error: Error) => void;\n}\n\n/**\n * Tracks Spark 3DGS loading state for UI that wraps `SparkSplatEnvironment`.\n *\n * Use the returned `props` with `<SparkSplatEnvironment {...lifecycle.props} />`\n * to avoid repeating status/error state in app code.\n */\nexport function useSparkSplatLifecycle({\n  enabled = true,\n  initialStatus,\n  onError,\n  onStatusChange,\n}: {\n  enabled?: boolean;\n  initialStatus?: SparkSplatStatus;\n  onError?: (error: Error) => void;\n  onStatusChange?: (status: SparkSplatStatus) => void;\n} = {}): SparkSplatLifecycle {\n  const [status, setStatus] = useState<SparkSplatStatus>(\n    initialStatus ?? (enabled ? 'loading' : 'idle')\n  );\n  const [error, setError] = useState<Error | null>(null);\n\n  useEffect(() => {\n    setStatus(enabled ? initialStatus ?? 'loading' : 'idle');\n    setError(null);\n  }, [enabled, initialStatus]);\n\n  const handleStatusChange = useCallback(\n    (nextStatus: SparkSplatStatus) => {\n      setStatus(nextStatus);\n      if (nextStatus !== 'error') {\n        setError(null);\n      }\n      onStatusChange?.(nextStatus);\n    },\n    [onStatusChange]\n  );\n\n  const handleError = useCallback(\n    (nextError: Error) => {\n      setError(nextError);\n      setStatus('error');\n      onError?.(nextError);\n    },\n    [onError]\n  );\n\n  const reset = useCallback(() => {\n    setStatus(enabled ? initialStatus ?? 'loading' : 'idle');\n    setError(null);\n  }, [enabled, initialStatus]);\n\n  return useMemo(\n    () => ({\n      status,\n      error,\n      isLoading: status === 'loading',\n      isReady: status === 'ready',\n      isError: status === 'error',\n      props: {\n        onStatusChange: handleStatusChange,\n        onError: handleError,\n      },\n      reset,\n    }),\n    [error, handleError, handleStatusChange, reset, status]\n  );\n}\n\n/**\n * Optional SparkJS-backed Gaussian splat renderer for React Three Fiber scenes.\n *\n * Import from `mujoco-react/spark` and install `@sparkjsdev/spark` in the app\n * that uses it. The core `mujoco-react` entrypoint does not depend on Spark.\n */\nexport function SparkSplatEnvironment({\n  environment,\n  scenario,\n  renderer = 'spark',\n  src,\n  format,\n  collisionProxy,\n  collisionProxyMetadata,\n  showPlaceholder,\n  children,\n  lod = true,\n  hideGroundMeshes = false,\n  onStatusChange,\n  onLoad,\n  onError,\n  ...groupProps\n}: SparkSplatEnvironmentProps) {\n  const groupRef = useRef<THREE.Group>(null);\n  const sparkRef = useRef<SparkRendererInstance | null>(null);\n  const meshRef = useRef<SparkSplatMeshInstance | null>(null);\n  const hiddenMeshesRef = useRef<THREE.Mesh[]>([]);\n  const onStatusChangeRef = useRef(onStatusChange);\n  const onLoadRef = useRef(onLoad);\n  const onErrorRef = useRef(onError);\n  const [status, setStatus] = useState<SparkSplatStatus>('idle');\n  const { gl, invalidate } = useThree();\n  const metadata = useSplatEnvironment({\n    environment,\n    scenario,\n    renderer,\n    src,\n    format,\n    collisionProxy: collisionProxyMetadata,\n  });\n\n  useEffect(() => {\n    onStatusChangeRef.current = onStatusChange;\n  }, [onStatusChange]);\n\n  useEffect(() => {\n    onLoadRef.current = onLoad;\n  }, [onLoad]);\n\n  useEffect(() => {\n    onErrorRef.current = onError;\n  }, [onError]);\n\n  useEffect(() => {\n    let disposed = false;\n\n    function setLifecycleStatus(nextStatus: SparkSplatStatus) {\n      setStatus(nextStatus);\n      onStatusChangeRef.current?.(nextStatus);\n    }\n\n    function restoreHiddenMeshes() {\n      for (const mesh of hiddenMeshesRef.current) {\n        mesh.visible = true;\n      }\n      hiddenMeshesRef.current = [];\n    }\n\n    async function loadSplat() {\n      if (!metadata.src) {\n        setLifecycleStatus('idle');\n        return;\n      }\n\n      if (metadata.format !== 'spz') {\n        const unsupportedFormatError = new Error(\n          `SparkSplatEnvironment only supports .spz assets; received \"${metadata.format}\".`\n        );\n        setLifecycleStatus('error');\n        onErrorRef.current?.(unsupportedFormatError);\n        return;\n      }\n\n      setLifecycleStatus('loading');\n\n      try {\n        const sparkModule = await import('@sparkjsdev/spark');\n        if (disposed || !groupRef.current) return;\n\n        const spark = new sparkModule.SparkRenderer({\n          renderer: gl,\n          onDirty: invalidate,\n        });\n        const mesh = new sparkModule.SplatMesh({\n          url: metadata.src,\n          lod,\n        });\n        mesh.name = 'GaussianSplatMesh';\n\n        groupRef.current.add(spark);\n        groupRef.current.add(mesh);\n        sparkRef.current = spark;\n        meshRef.current = mesh;\n\n        if (hideGroundMeshes && groupRef.current.parent) {\n          groupRef.current.parent.traverse((object) => {\n            if (\n              !(object instanceof THREE.Mesh) ||\n              object === (mesh as unknown as THREE.Object3D)\n            ) {\n              return;\n            }\n            const name = object.name.toLowerCase();\n            if (\n              name.includes('floor') ||\n              name.includes('ground') ||\n              name.includes('plane')\n            ) {\n              object.visible = false;\n              hiddenMeshesRef.current.push(object);\n            }\n          });\n        }\n\n        await mesh.initialized;\n        if (disposed) return;\n        setLifecycleStatus('ready');\n        onLoadRef.current?.(mesh);\n        invalidate();\n      } catch (error) {\n        const normalizedError =\n          error instanceof Error ? error : new Error(String(error));\n        setLifecycleStatus('error');\n        onErrorRef.current?.(normalizedError);\n      }\n    }\n\n    void loadSplat();\n\n    return () => {\n      disposed = true;\n      restoreHiddenMeshes();\n\n      if (meshRef.current) {\n        groupRef.current?.remove(meshRef.current);\n        safelyDisposeSparkResource(meshRef.current);\n        meshRef.current = null;\n      }\n\n      if (sparkRef.current) {\n        groupRef.current?.remove(sparkRef.current);\n        safelyDisposeSparkResource(sparkRef.current);\n        sparkRef.current = null;\n      }\n    };\n  }, [\n    gl,\n    hideGroundMeshes,\n    invalidate,\n    lod,\n    metadata.format,\n    metadata.src,\n  ]);\n\n  return (\n    <SplatEnvironment\n      {...groupProps}\n      environment={environment}\n      scenario={scenario}\n      renderer={renderer}\n      src={metadata.src}\n      format={metadata.format}\n      collisionProxyMetadata={metadata.collisionProxy}\n      collisionProxy={collisionProxy}\n      showPlaceholder={showPlaceholder ?? status !== 'ready'}\n    >\n      <group ref={groupRef} />\n      {children}\n    </SplatEnvironment>\n  );\n}\n\nfunction safelyDisposeSparkResource(resource: SparkDisposable) {\n  try {\n    const result = resource.dispose?.();\n    if (isPromiseLike(result)) {\n      void Promise.resolve(result).catch(handleSparkDisposeError);\n    }\n  } catch (error) {\n    handleSparkDisposeError(error);\n  }\n}\n\nfunction isPromiseLike(value: unknown): value is PromiseLike<unknown> {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    'then' in value &&\n    typeof (value as { then?: unknown }).then === 'function'\n  );\n}\n\nfunction handleSparkDisposeError(error: unknown) {\n  if (\n    error instanceof Error &&\n    error.message.toLowerCase().includes('worker terminate')\n  ) {\n    return;\n  }\n\n  console.warn('[mujoco-react] Spark resource disposal failed.', error);\n}\n"]}

package/dist/{types-FFW7ykBu.d.ts → types-BmneHLBM.d.ts}

@@ -309,6 +309,8 @@ interface SceneObject {
     solref?: string;
     solimp?: string;
     condim?: number;
+    /** MuJoCo geom group. Group 3 is conventionally used for collision-only helper geoms. */
+    group?: number;
 }
 interface XmlPatch {
     target: string;
@@ -320,6 +322,8 @@ type LocalMujocoFile = File;
 interface LoadFromFilesOptions {
     /** Entry MJCF/URDF file. Inferred from scene.xml, model.xml, robot.xml, or the first XML/URDF file when omitted. */
     sceneFile?: string;
+    /** Additional MJCF environment XML files merged into the entry scene before MuJoCo compilation. */
+    environmentFiles?: string[];
     homeJoints?: number[];
     xmlPatches?: XmlPatch[];
     sceneObjects?: SceneObject[];
@@ -332,6 +336,14 @@ interface SceneConfig {
     sceneFile: string;
     /** Browser-selected files for local MJCF/URDF loading. Preserves webkitRelativePath when available. */
     files?: readonly LocalMujocoFile[];
+    /**
+     * Additional MJCF environment XML files merged into the entry scene before compilation.
+     *
+     * Use this for static collision/physics layers such as a Gaussian-splat
+     * environment's proxy `scene.xml`; render the splat itself as a separate
+     * visual layer.
+     */
+    environmentFiles?: string[];
     sceneObjects?: SceneObject[];
     homeJoints?: number[];
     xmlPatches?: XmlPatch[];
@@ -524,10 +536,24 @@ interface KeyboardTeleopConfig {
     bindings: Record<string, KeyBinding>;
     enabled?: boolean;
 }
+type PolicyVector = Float32Array | Float64Array | number[];
+interface PolicyObservationInput {
+    model: MujocoModel;
+    data: MujocoData;
+}
+interface PolicyInferenceInput extends PolicyObservationInput {
+    observation: PolicyVector;
+}
+interface PolicyActionInput extends PolicyInferenceInput {
+    action: PolicyVector;
+}
 interface PolicyConfig {
     frequency: number;
-    onObservation: (model: MujocoModel, data: MujocoData) => Float32Array | Float64Array | number[];
-    onAction: (action: Float32Array | Float64Array | number[], model: MujocoModel, data: MujocoData) => void;
+    enabled?: boolean;
+    onObservation: (input: PolicyObservationInput) => PolicyVector;
+    /** Run policy inference. Omit to pass observations directly to `onAction` for custom inline controllers. */
+    infer?: (input: PolicyInferenceInput) => PolicyVector;
+    onAction: (input: PolicyActionInput) => void;
 }
 type ObservationOutput = 'float32' | 'float64';
 interface ObservationConfig {
@@ -600,6 +626,12 @@ interface ScenarioCameraConfig {
     noise?: number;
     blur?: number;
 }
+interface ScenarioMaterialConfig {
+    randomizeObjectColors?: boolean;
+    randomizeTableMaterial?: boolean;
+    roughness?: number;
+    metalness?: number;
+}
 interface SplatAssetConfig {
     src: string;
     /** Common browser-friendly splat format. Renderer-specific loaders may accept more. */
@@ -613,7 +645,7 @@ interface SplatScenarioConfig {
     format?: SplatFormat;
     src?: string;
     requiresCollisionProxy?: boolean;
-    collisionProxy?: SplatCollisionProxyConfig;
+    collisionProxy?: SplatCollisionProxyConfig | null;
 }
 interface SplatCollisionProxyConfig {
     /** MJCF/XML file or artifact path that provides physics collision for the visual splat. */
@@ -638,6 +670,8 @@ interface PairedSplatEnvironmentConfig {
 }
 interface SplatEnvironmentMetadataInput {
     environment?: PairedSplatEnvironmentConfig;
+    scenario?: VisualScenarioConfig;
+    renderer?: SplatRendererKind;
     src?: string;
     format?: SplatFormat;
     collisionProxy?: SplatCollisionProxyConfig;
@@ -648,6 +682,7 @@ interface SplatEnvironmentMetadata {
     collisionProxy?: SplatCollisionProxyConfig;
     userData: Record<string, unknown>;
 }
+type SplatSceneInput = PairedSplatEnvironmentConfig | VisualScenarioConfig | undefined | null;
 interface VisualScenarioConfig {
     id?: string;
     label?: string;
@@ -655,7 +690,8 @@ interface VisualScenarioConfig {
     lighting?: ScenarioLightingPreset;
     environment?: string;
     camera?: ScenarioCameraConfig;
-    splat?: SplatScenarioConfig;
+    materials?: ScenarioMaterialConfig;
+    splat?: SplatScenarioConfig | null;
 }
 interface ScenarioLightingProps {
     preset?: ScenarioLightingPreset;
@@ -664,12 +700,26 @@ interface ScenarioLightingProps {
 }
 interface SplatEnvironmentProps extends Omit<ThreeElements['group'], 'ref'> {
     environment?: PairedSplatEnvironmentConfig;
+    scenario?: VisualScenarioConfig;
+    renderer?: SplatRendererKind;
     src?: string;
     format?: SplatFormat;
     collisionProxy?: ReactNode;
     collisionProxyMetadata?: SplatCollisionProxyConfig;
     showPlaceholder?: boolean;
 }
+interface VisualScenarioEffectsProps {
+    scenario?: VisualScenarioConfig;
+    enabled?: boolean;
+    applyBackground?: boolean;
+    applyFog?: boolean;
+    applyRenderer?: boolean;
+    applyMaterials?: boolean;
+    background?: THREE.ColorRepresentation;
+    fogNear?: number;
+    fogFar?: number;
+    materialFilter?: (object: THREE.Object3D, material: THREE.Material) => boolean;
+}
 type TrajectoryInput = TrajectoryFrame[] | number[][];
 interface TrajectoryPlayerProps {
     trajectory: TrajectoryInput;
@@ -699,6 +749,8 @@ interface BodyProps {
     solref?: string;
     solimp?: string;
     condim?: number;
+    /** MuJoCo geom group. Group 3 is conventionally used for collision-only helper geoms. */
+    group?: number;
     children?: ReactNode;
 }
 interface MujocoSimAPI {
@@ -760,6 +812,8 @@ interface MujocoSimAPI {
 }
 type MujocoCanvasProps = Omit<CanvasProps, 'onError'> & {
     config: SceneConfig;
+    /** R3F content rendered while the MuJoCo WASM module is still loading. */
+    loadingFallback?: ReactNode;
     onReady?: (api: MujocoSimAPI) => void;
     onError?: (error: Error) => void;
     onStep?: (time: number) => void;
@@ -814,4 +868,4 @@ interface JointStateResult {
     velocity: React__default.RefObject<number | Float64Array>;
 }
 
-export { type BodyInfo as $, type ActuatedJointInfo as A, type BodyProps as B, type ControlGroupInfo as C, type DragInteractionProps as D, type SensorHandle as E, type SensorInfo as F, type GeomInfo as G, type JointStateResult as H, type IkConfig as I, type Joints as J, type Bodies as K, type BodyStateResult as L, type MujocoContextValue as M, type Actuators as N, type ObservationConfig as O, type PhysicsStepCallback as P, type CtrlHandle as Q, type ContactInfo as R, type SceneConfig as S, type TrajectoryPlayerProps as T, type KeyboardTeleopConfig as U, type VisualScenarioConfig as V, type PolicyConfig as W, type ObservationHandle as X, type TrajectoryInput as Y, type PlaybackState as Z, type TrajectoryFrame as _, type MujocoCanvasProps as a, type ControlJointInfo as a0, type Geoms as a1, type IKSolveFn as a2, type JointInfo as a3, type KeyBinding as a4, type Keyframes as a5, type ModelOptions as a6, type MujocoContact as a7, type MujocoContactArray as a8, type ObservationLayoutItem as a9, getContact as aA, registerRobotResources as aB, type ObservationOutput as aa, type PhysicsConfig as ab, type RayHit as ac, type Register as ad, type RegisteredRobotMap as ae, type ResourceSelector as af, RobotActuators as ag, RobotBodies as ah, RobotGeoms as ai, RobotJoints as aj, RobotKeyframes as ak, type RobotResource as al, RobotResources as am, RobotSensors as an, RobotSites as ao, type Robots as ap, type ScenarioCameraConfig as aq, type SceneMarker as ar, type SceneObject as as, type SensorResult as at, type SiteInfo as au, type SplatAssetConfig as av, type SplatScenarioConfig as aw, type StateSnapshot as ax, type TrajectoryData as ay, type XmlPatch as az, type MujocoSimAPI as b, type MujocoModule as c, type MujocoModel as d, type MujocoData as e, type ControlGroupSelector as f, type ObservationResult as g, type IkContextValue as h, type IkGizmoProps as i, type SceneLightsProps as j, type ScenarioLightingProps as k, type SplatEnvironmentProps as l, type PairedSplatEnvironmentConfig as m, type SplatFormat as n, type SplatCollisionProxyConfig as o, type SplatRendererKind as p, type SplatCollisionPrimitive as q, type ScenarioLightingPreset as r, type SplatEnvironmentMetadataInput as s, type SplatEnvironmentMetadata as t, type DebugProps as u, type ContactListenerProps as v, type ActuatorInfo as w, type Sites as x, type SitePositionResult as y, type Sensors as z };
+export { type TrajectoryInput as $, type ActuatedJointInfo as A, type BodyProps as B, type ControlGroupInfo as C, type DragInteractionProps as D, type SitePositionResult as E, type Sensors as F, type GeomInfo as G, type SensorHandle as H, type IkConfig as I, type SensorInfo as J, type Joints as K, type JointStateResult as L, type MujocoContextValue as M, type Bodies as N, type ObservationConfig as O, type PhysicsStepCallback as P, type BodyStateResult as Q, type Actuators as R, type SceneConfig as S, type TrajectoryPlayerProps as T, type CtrlHandle as U, type VisualScenarioEffectsProps as V, type ContactInfo as W, type KeyboardTeleopConfig as X, type PolicyConfig as Y, type PolicyVector as Z, type ObservationHandle as _, type MujocoCanvasProps as a, type PlaybackState as a0, type TrajectoryFrame as a1, type BodyInfo as a2, type ControlJointInfo as a3, type Geoms as a4, type IKSolveFn as a5, type JointInfo as a6, type KeyBinding as a7, type Keyframes as a8, type ModelOptions as a9, type SensorResult as aA, type SiteInfo as aB, type SplatAssetConfig as aC, type SplatScenarioConfig as aD, type StateSnapshot as aE, type TrajectoryData as aF, type XmlPatch as aG, getContact as aH, registerRobotResources as aI, type MujocoContact as aa, type MujocoContactArray as ab, type ObservationLayoutItem as ac, type ObservationOutput as ad, type PhysicsConfig as ae, type PolicyActionInput as af, type PolicyInferenceInput as ag, type PolicyObservationInput as ah, type RayHit as ai, type Register as aj, type RegisteredRobotMap as ak, type ResourceSelector as al, RobotActuators as am, RobotBodies as an, RobotGeoms as ao, RobotJoints as ap, RobotKeyframes as aq, type RobotResource as ar, RobotResources as as, RobotSensors as at, RobotSites as au, type Robots as av, type ScenarioCameraConfig as aw, type ScenarioMaterialConfig as ax, type SceneMarker as ay, type SceneObject as az, type MujocoSimAPI as b, type MujocoModule as c, type MujocoModel as d, type MujocoData as e, type ControlGroupSelector as f, type ObservationResult as g, type IkContextValue as h, type IkGizmoProps as i, type SceneLightsProps as j, type ScenarioLightingProps as k, type SplatEnvironmentProps as l, type VisualScenarioConfig as m, type SplatRendererKind as n, type PairedSplatEnvironmentConfig as o, type SplatFormat as p, type SplatCollisionProxyConfig as q, type SplatCollisionPrimitive as r, type ScenarioLightingPreset as s, type SplatEnvironmentMetadataInput as t, type SplatEnvironmentMetadata as u, type SplatSceneInput as v, type DebugProps as w, type ContactListenerProps as x, type ActuatorInfo as y, type Sites as z };

package/package.json

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

package/src/components/Body.tsx

@@ -30,6 +30,7 @@ export function Body({
   solref,
   solimp,
   condim,
+  group,
   children,
 }: BodyProps) {
   const { bodyRegistryRef, hiddenBodiesRef, requestBodyReload, mjDataRef, mjModelRef, status } =
@@ -53,6 +54,7 @@ export function Body({
       solref,
       solimp,
       condim,
+      group,
     };
     bodyRegistryRef.current.set(name, { definition, hasCustomChildren: hasChildren });
     if (hasChildren) {
@@ -66,7 +68,7 @@ export function Body({
         requestBodyReload();
       }
     };
-  }, [name, type, size, position, rgba, mass, freejoint, friction, solref, solimp, condim, hasChildren, bodyRegistryRef, hiddenBodiesRef, requestBodyReload]);
+  }, [name, type, size, position, rgba, mass, freejoint, friction, solref, solimp, condim, group, hasChildren, bodyRegistryRef, hiddenBodiesRef, requestBodyReload]);
 
   // Resolve body ID once the scene is ready
   useEffect(() => {