mujoco-react 8.9.1 → 8.10.0

package/src/spark.tsx

@@ -0,0 +1,202 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { useThree } from '@react-three/fiber';
+import { useEffect, useRef, useState } from 'react';
+import * as THREE from 'three';
+import {
+  SplatEnvironment,
+  useSplatEnvironment,
+} from './components/VisualScenario';
+import type {
+  SplatEnvironmentProps,
+} from './types';
+
+type SparkModule = typeof import('@sparkjsdev/spark');
+type SparkRendererInstance = InstanceType<SparkModule['SparkRenderer']>;
+type SparkSplatMeshInstance = InstanceType<SparkModule['SplatMesh']>;
+
+export type SparkSplatStatus = 'idle' | 'loading' | 'ready' | 'error';
+
+export 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.
+ */
+export function SparkSplatEnvironment({
+  environment,
+  src,
+  format,
+  collisionProxy,
+  collisionProxyMetadata,
+  showPlaceholder,
+  children,
+  lod = true,
+  hideGroundMeshes = false,
+  onStatusChange,
+  onLoad,
+  onError,
+  ...groupProps
+}: SparkSplatEnvironmentProps) {
+  const groupRef = useRef<THREE.Group>(null);
+  const sparkRef = useRef<SparkRendererInstance | null>(null);
+  const meshRef = useRef<SparkSplatMeshInstance | null>(null);
+  const hiddenMeshesRef = useRef<THREE.Mesh[]>([]);
+  const onStatusChangeRef = useRef(onStatusChange);
+  const onLoadRef = useRef(onLoad);
+  const onErrorRef = useRef(onError);
+  const [status, setStatus] = useState<SparkSplatStatus>('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: SparkSplatStatus) {
+      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 as unknown as THREE.Object3D)
+            ) {
+              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 (
+    <SplatEnvironment
+      {...groupProps}
+      environment={environment}
+      src={metadata.src}
+      format={metadata.format}
+      collisionProxyMetadata={metadata.collisionProxy}
+      collisionProxy={collisionProxy}
+      showPlaceholder={showPlaceholder ?? status !== 'ready'}
+    >
+      <group ref={groupRef} />
+      {children}
+    </SplatEnvironment>
+  );
+}

package/src/types.ts

@@ -5,7 +5,7 @@
 
 import type React from 'react';
 import type { ReactNode } from 'react';
-import type { CanvasProps } from '@react-three/fiber';
+import type { CanvasProps, ThreeElements } from '@react-three/fiber';
 import * as THREE from 'three';
 
 // ---- Register (type-safe named resources) ----
@@ -791,6 +791,97 @@ export interface SceneLightsProps {
   intensity?: number;
 }
 
+// ---- Visual scenarios / 3DGS composition ----
+
+export type ScenarioLightingPreset = 'studio' | 'warehouse' | 'low-light' | 'splat';
+export type SplatFormat = 'spz' | 'ply' | 'splat';
+export type SplatRendererKind = 'spark' | 'custom';
+export type SplatCollisionPrimitive = 'plane' | 'box' | 'sphere' | 'capsule' | 'mesh';
+
+export interface ScenarioCameraConfig {
+  jitter?: number;
+  exposure?: number;
+  noise?: number;
+  blur?: number;
+}
+
+export interface SplatAssetConfig {
+  src: string;
+  /** Common browser-friendly splat format. Renderer-specific loaders may accept more. */
+  format?: SplatFormat;
+  /** Optional renderer hint. The library does not import renderer-specific code. */
+  renderer?: SplatRendererKind;
+}
+
+export interface SplatScenarioConfig {
+  enabled: boolean;
+  /** Common browser-friendly splat format. Renderer-specific loaders may accept more. */
+  format?: SplatFormat;
+  src?: string;
+  requiresCollisionProxy?: boolean;
+  collisionProxy?: SplatCollisionProxyConfig;
+}
+
+export interface SplatCollisionProxyConfig {
+  /** MJCF/XML file or artifact path that provides physics collision for the visual splat. */
+  xmlPath?: string;
+  /** Human-readable status for authoring and validation flows. */
+  status?: 'missing' | 'planned' | 'generated' | 'validated';
+  /** Primitive proxy shapes expected in the MJCF collision proxy. */
+  primitives?: SplatCollisionPrimitive[];
+  /** Optional notes that should travel with scene variants and rollout metadata. */
+  notes?: string[];
+}
+
+export interface PairedSplatEnvironmentConfig {
+  id: string;
+  label: string;
+  description?: string;
+  /** Visual-only Gaussian splat asset. */
+  splat: SplatAssetConfig;
+  /** MJCF/XML contact geometry paired with the visual splat. */
+  collisionProxy: SplatCollisionProxyConfig & { xmlPath: string };
+}
+
+export interface SplatEnvironmentMetadataInput {
+  environment?: PairedSplatEnvironmentConfig;
+  src?: string;
+  format?: SplatFormat;
+  collisionProxy?: SplatCollisionProxyConfig;
+}
+
+export interface SplatEnvironmentMetadata {
+  src?: string;
+  format: SplatFormat;
+  collisionProxy?: SplatCollisionProxyConfig;
+  userData: Record<string, unknown>;
+}
+
+export interface VisualScenarioConfig {
+  id?: string;
+  label?: string;
+  seed?: number;
+  lighting?: ScenarioLightingPreset;
+  environment?: string;
+  camera?: ScenarioCameraConfig;
+  splat?: SplatScenarioConfig;
+}
+
+export interface ScenarioLightingProps {
+  preset?: ScenarioLightingPreset;
+  intensity?: number;
+  castShadow?: boolean;
+}
+
+export interface SplatEnvironmentProps extends Omit<ThreeElements['group'], 'ref'> {
+  environment?: PairedSplatEnvironmentConfig;
+  src?: string;
+  format?: SplatFormat;
+  collisionProxy?: ReactNode;
+  collisionProxyMetadata?: SplatCollisionProxyConfig;
+  showPlaceholder?: boolean;
+}
+
 export type TrajectoryInput = TrajectoryFrame[] | number[][];
 
 export interface TrajectoryPlayerProps {

package/src/vite.ts

@@ -86,6 +86,14 @@ export function mujocoReact(options: MujocoReactPluginOptions) {
   return {
     name: 'mujoco-react',
     enforce: 'pre' as const,
+    config(userConfig: { build?: { chunkSizeWarningLimit?: number } }) {
+      // three + drei + MuJoCo WASM glue are inherently large; the large-chunk
+      // warning is expected, not a failure. Raise the limit so consumers don't
+      // see it. Vite merges plugin config on top of user config, so only set a
+      // default when the consumer hasn't specified their own limit.
+      if (userConfig.build?.chunkSizeWarningLimit !== undefined) return;
+      return { build: { chunkSizeWarningLimit: 4000 } };
+    },
     configResolved(config: ViteConfig) {
       root = config.root;
       generatedRegister = path.resolve(root, generatedRegister);