mujoco-react 8.9.2 → 8.10.0

package/dist/spark.d.ts

@@ -0,0 +1,32 @@
+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 'react';
+import '@react-three/fiber';
+import 'three';
+
+type SparkModule = typeof _sparkjsdev_spark;
+type SparkSplatMeshInstance = InstanceType<SparkModule['SplatMesh']>;
+type SparkSplatStatus = 'idle' | 'loading' | 'ready' | 'error';
+interface SparkSplatEnvironmentProps extends SplatEnvironmentProps {
+    /** Enable Spark LoD handling for large splat assets. Default: true. */
+    lod?: boolean | 'quality';
+    /**
+     * Hide meshes whose names include floor, ground, or plane while the splat is
+     * active. This mirrors the common hybrid-rendering setup where MJCF keeps
+     * collision geometry but the splat owns the visual environment.
+     */
+    hideGroundMeshes?: boolean;
+    onStatusChange?: (status: SparkSplatStatus) => void;
+    onLoad?: (mesh: SparkSplatMeshInstance) => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * 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;
+
+export { SparkSplatEnvironment, type SparkSplatEnvironmentProps, type SparkSplatStatus };

package/dist/spark.js

@@ -0,0 +1,150 @@
+import { useSplatEnvironment, SplatEnvironment } from './chunk-KGFRKPLS.js';
+import { useThree } from '@react-three/fiber';
+import { useRef, useState, useEffect } from 'react';
+import * as THREE from 'three';
+import { jsxs, jsx } from 'react/jsx-runtime';
+
+function SparkSplatEnvironment({
+  environment,
+  src,
+  format,
+  collisionProxy,
+  collisionProxyMetadata,
+  showPlaceholder,
+  children,
+  lod = true,
+  hideGroundMeshes = false,
+  onStatusChange,
+  onLoad,
+  onError,
+  ...groupProps
+}) {
+  const groupRef = useRef(null);
+  const sparkRef = useRef(null);
+  const meshRef = useRef(null);
+  const hiddenMeshesRef = useRef([]);
+  const onStatusChangeRef = useRef(onStatusChange);
+  const onLoadRef = useRef(onLoad);
+  const onErrorRef = useRef(onError);
+  const [status, setStatus] = useState("idle");
+  const { gl, invalidate } = useThree();
+  const metadata = useSplatEnvironment({
+    environment,
+    src,
+    format,
+    collisionProxy: collisionProxyMetadata
+  });
+  useEffect(() => {
+    onStatusChangeRef.current = onStatusChange;
+  }, [onStatusChange]);
+  useEffect(() => {
+    onLoadRef.current = onLoad;
+  }, [onLoad]);
+  useEffect(() => {
+    onErrorRef.current = onError;
+  }, [onError]);
+  useEffect(() => {
+    let disposed = false;
+    function setLifecycleStatus(nextStatus) {
+      setStatus(nextStatus);
+      onStatusChangeRef.current?.(nextStatus);
+    }
+    function restoreHiddenMeshes() {
+      for (const mesh of hiddenMeshesRef.current) {
+        mesh.visible = true;
+      }
+      hiddenMeshesRef.current = [];
+    }
+    async function loadSplat() {
+      if (!metadata.src || metadata.format !== "spz") {
+        setLifecycleStatus("idle");
+        return;
+      }
+      setLifecycleStatus("loading");
+      try {
+        const sparkModule = await import('@sparkjsdev/spark');
+        if (disposed || !groupRef.current) return;
+        const spark = new sparkModule.SparkRenderer({
+          renderer: gl,
+          onDirty: invalidate
+        });
+        const mesh = new sparkModule.SplatMesh({
+          url: metadata.src,
+          lod
+        });
+        mesh.name = "GaussianSplatMesh";
+        groupRef.current.add(spark);
+        groupRef.current.add(mesh);
+        sparkRef.current = spark;
+        meshRef.current = mesh;
+        if (hideGroundMeshes && groupRef.current.parent) {
+          groupRef.current.parent.traverse((object) => {
+            if (!(object instanceof THREE.Mesh) || object === mesh) {
+              return;
+            }
+            const name = object.name.toLowerCase();
+            if (name.includes("floor") || name.includes("ground") || name.includes("plane")) {
+              object.visible = false;
+              hiddenMeshesRef.current.push(object);
+            }
+          });
+        }
+        await mesh.initialized;
+        if (disposed) return;
+        setLifecycleStatus("ready");
+        onLoadRef.current?.(mesh);
+        invalidate();
+      } catch (error) {
+        const normalizedError = error instanceof Error ? error : new Error(String(error));
+        setLifecycleStatus("error");
+        onErrorRef.current?.(normalizedError);
+      }
+    }
+    void loadSplat();
+    return () => {
+      disposed = true;
+      restoreHiddenMeshes();
+      if (meshRef.current) {
+        groupRef.current?.remove(meshRef.current);
+        meshRef.current.dispose?.();
+        meshRef.current = null;
+      }
+      if (sparkRef.current) {
+        groupRef.current?.remove(sparkRef.current);
+        sparkRef.current.dispose?.();
+        sparkRef.current = null;
+      }
+    };
+  }, [
+    gl,
+    hideGroundMeshes,
+    invalidate,
+    lod,
+    metadata.format,
+    metadata.src
+  ]);
+  return /* @__PURE__ */ jsxs(
+    SplatEnvironment,
+    {
+      ...groupProps,
+      environment,
+      src: metadata.src,
+      format: metadata.format,
+      collisionProxyMetadata: metadata.collisionProxy,
+      collisionProxy,
+      showPlaceholder: showPlaceholder ?? status !== "ready",
+      children: [
+        /* @__PURE__ */ jsx("group", { ref: groupRef }),
+        children
+      ]
+    }
+  );
+}
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export { SparkSplatEnvironment };
+//# sourceMappingURL=spark.js.map
+//# sourceMappingURL=spark.js.map

package/dist/spark.js.map

@@ -0,0 +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"]}