mujoco-react 9.2.0 → 9.4.0

package/src/components/VisualScenario.tsx

@@ -8,20 +8,26 @@ import type { ThreeElements } from '@react-three/fiber';
 import type { ReactNode } from 'react';
 import { useEffect, useMemo } from 'react';
 import * as THREE from 'three';
+import { SplatEnvironmentReadinessStatus } from '../types';
 import type {
   PairedSplatEnvironmentConfig,
   ScenarioMaterialConfig,
   SceneConfig,
   SplatCollisionProxyConfig,
+  SplatEnvironmentReadiness,
   SplatEnvironmentMetadata,
   SplatEnvironmentMetadataInput,
   SplatFormat,
   SplatRendererKind,
+  SplatSceneConfigInput,
+  SplatSceneConfigState,
   SplatSceneInput,
   ScenarioLightingPreset,
   ScenarioLightingProps,
   SplatEnvironmentProps,
   VisualScenarioConfig,
+  VisualScenarioExecutionContext,
+  VisualScenarioExecutionContextInput,
   VisualScenarioEffectsProps,
 } from '../types';
 
@@ -110,6 +116,84 @@ export function getScenarioCameraPosition(
   ];
 }
 
+export function useVisualScenarioExecutionContext({
+  scenario,
+  environment,
+  renderer,
+  variantId,
+  enabled,
+}: VisualScenarioExecutionContextInput): VisualScenarioExecutionContext {
+  return useMemo(
+    () =>
+      createVisualScenarioExecutionContext({
+        scenario,
+        environment,
+        renderer,
+        variantId,
+        enabled,
+      }),
+    [enabled, environment, renderer, scenario, variantId]
+  );
+}
+
+export function createVisualScenarioExecutionContext({
+  scenario,
+  environment,
+  renderer,
+  variantId,
+  enabled = true,
+}: VisualScenarioExecutionContextInput): VisualScenarioExecutionContext {
+  const pairedEnvironment =
+    environment ??
+    (scenario ? createPairedSplatEnvironment(scenario, { renderer }) : undefined);
+  const splat = scenario?.splat;
+  const collisionProxy =
+    pairedEnvironment?.collisionProxy ?? splat?.collisionProxy ?? undefined;
+  const readiness = getSplatEnvironmentReadiness({
+    environment: pairedEnvironment,
+    scenario,
+    renderer,
+    enabled,
+  });
+  const format =
+    pairedEnvironment?.splat.format ?? splat?.format ?? readiness.format ?? 'spz';
+
+  return {
+    scenarioId: scenario?.id ?? pairedEnvironment?.id ?? 'visual-scenario',
+    scenarioLabel:
+      scenario?.label ?? pairedEnvironment?.label ?? 'Visual scenario',
+    variantId,
+    seed: scenario?.seed ?? 0,
+    lighting: scenario?.lighting ?? 'studio',
+    environment: scenario?.environment,
+    camera: {
+      jitter: scenario?.camera?.jitter ?? 0,
+      exposure: scenario?.camera?.exposure ?? 1,
+      noise: scenario?.camera?.noise ?? 0,
+      blur: scenario?.camera?.blur ?? 0,
+    },
+    materials: {
+      randomizeObjectColors: Boolean(
+        scenario?.materials?.randomizeObjectColors
+      ),
+      randomizeTableMaterial: Boolean(
+        scenario?.materials?.randomizeTableMaterial
+      ),
+      roughness: scenario?.materials?.roughness,
+      metalness: scenario?.materials?.metalness,
+    },
+    splatEnabled: Boolean(splat?.enabled || pairedEnvironment),
+    splatSrc: pairedEnvironment?.splat.src ?? splat?.src,
+    splatFormat: format,
+    splatRenderer: renderer ?? pairedEnvironment?.splat.renderer,
+    collisionProxyXmlPath: collisionProxy?.xmlPath,
+    collisionProxyStatus: collisionProxy?.status,
+    collisionProxyPrimitives: collisionProxy?.primitives ?? [],
+    readiness,
+    transformSource: 'visualScenario.camera',
+  };
+}
+
 export function VisualScenarioEffects(props: VisualScenarioEffectsProps) {
   useVisualScenarioEffects(props);
   return null;
@@ -277,27 +361,208 @@ export function useSplatEnvironment({
     scenarioEnvironment?.collisionProxy ??
     scenario?.splat?.collisionProxy ??
     undefined;
+  const readiness = useMemo(
+    () =>
+      getSplatEnvironmentReadiness({
+        environment: scenarioEnvironment,
+        scenario,
+        renderer,
+        src: resolvedSrc,
+        format: resolvedFormat,
+        collisionProxy: resolvedCollisionProxy,
+      }),
+    [
+      collisionProxy,
+      renderer,
+      resolvedCollisionProxy,
+      resolvedFormat,
+      resolvedSrc,
+      scenario,
+      scenarioEnvironment,
+    ]
+  );
 
   return useMemo(
     () => ({
       src: resolvedSrc,
       format: resolvedFormat,
       collisionProxy: resolvedCollisionProxy,
+      readiness,
       userData: createSplatEnvironmentUserData({
         environment: scenarioEnvironment,
         src: resolvedSrc,
         format: resolvedFormat,
         collisionProxy: resolvedCollisionProxy,
+        readiness,
       }),
     }),
-    [scenarioEnvironment, resolvedSrc, resolvedFormat, resolvedCollisionProxy]
+    [
+      scenarioEnvironment,
+      resolvedSrc,
+      resolvedFormat,
+      resolvedCollisionProxy,
+      readiness,
+    ]
+  );
+}
+
+/**
+ * Resolve a visual scenario's paired splat environment and compose its MJCF
+ * collision proxy into a MuJoCo scene config.
+ *
+ * This hook is renderer-agnostic: apps can use it with Spark, another 3DGS
+ * renderer, or their own Three scene objects while keeping physics collision
+ * files paired with the visual splat metadata.
+ */
+export function useSplatSceneConfig({
+  sceneConfig,
+  scenario,
+  environment,
+  enabled = true,
+  renderer,
+}: SplatSceneConfigInput): SplatSceneConfigState {
+  return useMemo(
+    () =>
+      createSplatSceneConfig({
+        sceneConfig,
+        scenario,
+        environment,
+        enabled,
+        renderer,
+      }),
+    [enabled, environment, renderer, scenario, sceneConfig]
   );
 }
 
 /**
- * Convert a generic visual scenario splat block into a paired visual/physics
- * environment config. Returns undefined until both the splat asset and MJCF
- * collision proxy are present.
+ * Resolve a visual scenario's paired splat environment without requiring React.
+ *
+ * Use this in codegen, import validators, backend handoff metadata, or app code
+ * that needs the same behavior as `useSplatSceneConfig` outside a component.
+ */
+export function createSplatSceneConfig({
+  sceneConfig,
+  scenario,
+  environment,
+  enabled = true,
+  renderer,
+}: SplatSceneConfigInput): SplatSceneConfigState {
+  const resolvedEnvironment = enabled
+    ? environment ??
+      (scenario
+        ? createPairedSplatEnvironment(scenario, { renderer })
+        : undefined)
+    : undefined;
+  const readiness = getSplatEnvironmentReadiness({
+    environment: resolvedEnvironment,
+    scenario,
+    renderer,
+    enabled,
+  });
+  const resolvedSceneConfig = resolvedEnvironment
+    ? withSplatEnvironment(sceneConfig, resolvedEnvironment, { renderer })
+    : sceneConfig;
+
+  return {
+    environment: resolvedEnvironment,
+    sceneConfig: resolvedSceneConfig,
+    enabled:
+      enabled && readiness.status !== SplatEnvironmentReadinessStatus.Disabled,
+    readiness,
+  };
+}
+
+export function getSplatEnvironmentReadiness({
+  environment,
+  scenario,
+  renderer,
+  src,
+  format,
+  collisionProxy,
+  enabled = true,
+}: {
+  environment?: PairedSplatEnvironmentConfig;
+  scenario?: Pick<VisualScenarioConfig, 'splat'>;
+  renderer?: SplatRendererKind;
+  src?: string;
+  format?: SplatFormat;
+  collisionProxy?: SplatCollisionProxyConfig;
+  enabled?: boolean;
+}): SplatEnvironmentReadiness {
+  const splat = scenario?.splat;
+  const resolvedSrc = src ?? environment?.splat.src ?? splat?.src;
+  const resolvedFormat =
+    format ?? environment?.splat.format ?? splat?.format ?? 'spz';
+  const resolvedRenderer = renderer ?? environment?.splat.renderer;
+  const resolvedCollisionProxy =
+    collisionProxy ?? environment?.collisionProxy ?? splat?.collisionProxy ?? undefined;
+  const requiresCollisionProxy = splat?.requiresCollisionProxy ?? true;
+
+  if (!enabled || (splat && splat.enabled === false && !environment)) {
+    return {
+      status: SplatEnvironmentReadinessStatus.Disabled,
+      ready: false,
+      requiresCollisionProxy,
+      missing: [],
+      format: resolvedFormat,
+      renderer: resolvedRenderer,
+      message: 'Splat environment is disabled.',
+    };
+  }
+
+  if (!resolvedSrc) {
+    return {
+      status: SplatEnvironmentReadinessStatus.MissingSplat,
+      ready: false,
+      requiresCollisionProxy,
+      missing: ['splat'],
+      format: resolvedFormat,
+      renderer: resolvedRenderer,
+      message: 'Splat environment is missing a visual asset source.',
+    };
+  }
+
+  if (resolvedRenderer === 'spark' && resolvedFormat !== 'spz') {
+    return {
+      status: SplatEnvironmentReadinessStatus.UnsupportedFormat,
+      ready: false,
+      requiresCollisionProxy,
+      missing: [],
+      format: resolvedFormat,
+      renderer: resolvedRenderer,
+      message: `Spark splat rendering requires .spz assets; received ${resolvedFormat}.`,
+    };
+  }
+
+  if (requiresCollisionProxy && !resolvedCollisionProxy?.xmlPath) {
+    return {
+      status: SplatEnvironmentReadinessStatus.MissingCollisionProxy,
+      ready: false,
+      requiresCollisionProxy,
+      missing: ['collisionProxy'],
+      format: resolvedFormat,
+      renderer: resolvedRenderer,
+      message: 'Splat environment is missing paired MJCF collision proxy XML.',
+    };
+  }
+
+  return {
+    status: SplatEnvironmentReadinessStatus.Ready,
+    ready: true,
+    requiresCollisionProxy,
+    missing: [],
+    format: resolvedFormat,
+    renderer: resolvedRenderer,
+    message: requiresCollisionProxy
+      ? 'Splat environment has visual asset and collision proxy metadata.'
+      : 'Splat environment has a visual asset and does not require collision proxy metadata.',
+  };
+}
+
+/**
+ * Convert a generic visual scenario splat block into a composable splat
+ * environment config. Visual-only splats are valid; readiness reports whether
+ * a paired MJCF collision proxy is required before training/physics handoff.
  */
 export function createPairedSplatEnvironment(
   scenario: Pick<VisualScenarioConfig, 'id' | 'label' | 'environment' | 'splat'>,
@@ -311,7 +576,7 @@ export function createPairedSplatEnvironment(
   const splat = scenario.splat;
   const collisionProxy = splat?.collisionProxy;
 
-  if (!splat?.enabled || !splat.src || !collisionProxy?.xmlPath) {
+  if (!splat?.enabled || !splat.src) {
     return undefined;
   }
 
@@ -328,15 +593,22 @@ export function createPairedSplatEnvironment(
       format: splat.format ?? 'spz',
       renderer: options.renderer,
     },
-    collisionProxy: {
-      ...collisionProxy,
-      xmlPath: collisionProxy.xmlPath,
-    },
+    collisionProxy: collisionProxy?.xmlPath
+      ? {
+          ...collisionProxy,
+          xmlPath: collisionProxy.xmlPath,
+        }
+      : undefined,
   };
 }
 
 function isPairedSplatEnvironment(input: SplatSceneInput): input is PairedSplatEnvironmentConfig {
-  return !!input && 'collisionProxy' in input && 'splat' in input;
+  return (
+    !!input &&
+    'splat' in input &&
+    !!input.splat &&
+    !('enabled' in input.splat)
+  );
 }
 
 function sceneRelativePath(sceneConfig: SceneConfig, path: string): string {
@@ -376,7 +648,7 @@ export function withSplatEnvironment(
     : input
       ? createPairedSplatEnvironment(input, options)
       : undefined;
-  const xmlPath = environment?.collisionProxy.xmlPath;
+  const xmlPath = environment?.collisionProxy?.xmlPath;
   if (!xmlPath) return sceneConfig;
 
   return {
@@ -393,11 +665,13 @@ export function createSplatEnvironmentUserData({
   src,
   format = 'spz',
   collisionProxy,
+  readiness,
 }: {
   environment?: PairedSplatEnvironmentConfig;
   src?: string;
   format?: SplatFormat;
   collisionProxy?: SplatCollisionProxyConfig;
+  readiness?: SplatEnvironmentReadiness;
 }) {
   return {
     role: 'splat-environment',
@@ -409,6 +683,8 @@ export function createSplatEnvironmentUserData({
     collisionProxyStatus: collisionProxy?.status ?? 'missing',
     collisionProxyXmlPath: collisionProxy?.xmlPath,
     collisionProxyPrimitives: collisionProxy?.primitives ?? [],
+    readinessStatus: readiness?.status,
+    readinessMessage: readiness?.message,
   };
 }