SplatEnvironment

Composable Gaussian splat environment boundaries and optional Spark rendering

mujoco-react treats Gaussian splats as visual environments and MuJoCo XML as physics truth. For realistic robot workflows, pair each .spz, .ply, or .splat visual asset with MJCF collision geometry that provides contacts, friction, and task fixtures.

If a splat is intentionally visual-only, set requiresCollisionProxy: false on the scenario. useSparkSplatEnvironment will still pass the visual src and format to the renderer, while withSplatEnvironment leaves the MuJoCo sceneConfig unchanged because there is no collision XML to add.

Renderer-Agnostic Boundary

Use useSplatSceneConfig and SplatEnvironment from the main package when the app owns the renderer or when you want metadata and collision proxy composition without adding a splat renderer dependency. For scenario-driven apps, pass the scenario directly; the hook resolves the visual asset and MJCF collision proxy metadata without app-side prop reshaping.

import { MujocoCanvas, SplatEnvironment, useSplatSceneConfig } from "mujoco-react";

function Scene({ config, scenario }) {
  const splat = useSplatSceneConfig({ sceneConfig: config, scenario });

  return (
    <MujocoCanvas config={splat.sceneConfig}>
      {splat.environment ? (
        <SplatEnvironment
          environment={splat.environment}
          renderer="custom"
          collisionProxy={<LabCollisionPreview />}
        >
          <MySplatRenderer src={splat.environment.splat.src} />
        </SplatEnvironment>
      ) : null}
    </MujocoCanvas>
  );
}

Use createSplatSceneConfig for the same resolution behavior outside React, such as import validators, codegen, backend handoff metadata, or tests:

import { createSplatSceneConfig } from "mujoco-react";

const splat = createSplatSceneConfig({
  sceneConfig: config,
  scenario,
  renderer: "spark",
});

SplatEnvironment writes stable userData onto its group:

• role: "splat-environment"
• splatSrc
• splatFormat
• collisionProxyStatus
• collisionProxyXmlPath
• collisionProxyPrimitives

Visual Scenario Effects

Use VisualScenarioEffects next to ScenarioLighting to make visual scenario metadata affect the actual Three scene. It applies camera exposure, optional background/fog, and deterministic material variation without changing MuJoCo physics.

import {
  ScenarioLighting,
  VisualScenarioEffects,
} from "mujoco-react";

function Scene({ scenario }) {
  return (
    <MujocoCanvas config={config}>
      <VisualScenarioEffects
        scenario={scenario}
        applyBackground={!scenario.splat?.enabled}
        materialFilter={({ object }) => object.name.startsWith("prop_")}
      />
      <ScenarioLighting preset={scenario.lighting} />
    </MujocoCanvas>
  );
}

Spark Renderer

Install Spark in apps that want first-class .spz rendering:

npm install @sparkjsdev/spark

Then import the optional adapter from mujoco-react/spark:

import { MujocoCanvas } from "mujoco-react";
import {
  SparkSplatEnvironment,
  useSparkSplatEnvironment,
} from "mujoco-react/spark";

function Scene({ scenario }) {
  const splat = useSparkSplatEnvironment({ sceneConfig: config, scenario });

  return (
    <MujocoCanvas config={splat.sceneConfig} gl={{ preserveDrawingBuffer: true }}>
      {splat.props.src ? (
        <SparkSplatEnvironment hideGroundMeshes {...splat.props} />
      ) : null}
      <StatusBadge
        status={splat.lifecycle.status}
        error={splat.lifecycle.error}
      />
    </MujocoCanvas>
  );
}

SparkSplatEnvironment dynamically imports @sparkjsdev/spark, creates a SparkRenderer, adds a SplatMesh to the same Three scene, and leaves MuJoCo bodies in the same render pass. That mirrors the same-scene approach used by MuJoCo-GS-Web: splats provide visuals, while MJCF continues to provide contacts and robot physics.

Spark rendering currently supports .spz assets. If a scenario points at .ply or .splat, SparkSplatEnvironment reports status: "error" through useSparkSplatLifecycle so the app can show a clear unsupported-format state. Keep using SplatEnvironment for renderer-agnostic metadata or when integrating a different splat renderer.

Use renderTuning to adjust the live Spark renderer and captureTuning to adjust offscreen camera-frame capture independently:

<SparkSplatEnvironment
  {...splat.props}
  renderTuning={{ lodSplatScale: 0.75, minSortIntervalMs: 50 }}
  captureTuning={{ lodSplatScale: 1.4, lodRenderScale: 0.45, maxWarmupFrames: 6 }}
/>

The default live tuning favors interactive frame rate. The default capture tuning favors sharper snapshots and retries the first offscreen render if Spark has not produced visible splats yet.

Use useSparkSplatEnvironment for the Spark path. It builds on useSplatSceneConfig, adds paired collision proxy XML to the MuJoCo sceneConfig, and returns lifecycle props for SparkSplatEnvironment. For visual-only scenarios with requiresCollisionProxy: false, it returns the original sceneConfig and passes scenario, src, and format through props so the splat renderer can still load the visual layer.

useSplatSceneConfig, useSparkSplatEnvironment, and getSplatEnvironmentReadiness expose the same readiness contract:

• disabled
• missing-splat
• missing-collision-proxy
• unsupported-format
• ready

Use this status for import screens and scenario editors instead of treating a missing environment as a generic falsey value.

Use createVisualScenarioExecutionContext() when the app needs a serializable record of the visual conditions used for a rollout, dataset episode, or training handoff. The helper resolves camera exposure/noise/blur/jitter, material randomization, splat source, collision proxy metadata, and readiness from the same scenario object used by SplatEnvironment.

import { createVisualScenarioExecutionContext } from "mujoco-react";

const visualExecutionContext = createVisualScenarioExecutionContext({
  scenario,
  renderer: "spark",
  variantId,
});

Use useSparkSplatLifecycle directly when the app owns scene-config composition but still needs status badges, loading affordances, or error messages around the splat renderer. The hook returns:

• status: "idle" | "loading" | "ready" | "error"
• error: Error | null
• isLoading, isReady, and isError
• props, which can be spread onto SparkSplatEnvironment
• reset(), for retry flows

Props

src · string

URL for the visual splat asset.

format · "spz" | "ply" | "splat" · default: "\"spz\""

Format metadata for the splat asset. SparkSplatEnvironment currently renders .spz.

collisionProxyMetadata · SplatCollisionProxyConfig

MJCF/XML collision proxy metadata to preserve alongside scene variants, rollouts, and datasets.

environment · PairedSplatEnvironmentConfig

Paired visual/physics environment config. Use createPairedSplatEnvironment(scenario) when the app stores splat data inside visual scenarios.

scenario · VisualScenarioConfig

Visual scenario metadata with an optional splat block. When present, this is enough for SplatEnvironment and SparkSplatEnvironment to resolve src, format, and collision proxy metadata.

collisionProxy · ReactNode

Optional R3F preview geometry for the collision proxy.

hideGroundMeshes · boolean · default: "false"

Hide meshes whose names include floor, ground, or plane while the splat is active.

onStatusChange · (status: "idle" | "loading" | "ready" | "error") => void

Called as Spark loading progresses.