mujoco-react 11.0.0 → 12.1.0

package/README.md

@@ -10,26 +10,25 @@ Composable [React Three Fiber](https://docs.pmnd.rs/react-three-fiber) wrapper a
 
 **[Demo](https://mujoco-react-example.pages.dev)** | **[Docs](https://dadd.mintlify.app)** | **[npm](https://www.npmjs.com/package/mujoco-react)** | **[Example Source](https://github.com/noah-wardlow/mujoco-react-example)** | **[llms.txt](https://dadd.mintlify.app/llms.txt)**
 
-## MuJoCo 3.15 and analytic IK
-
-The engine dependency is pinned to `@mujoco/mujoco@3.15.0` so upstream minor releases
-cannot silently change model behavior.
-
-- `GenericIK` uses `mj_jacSite`; `solveJoints()` supports ball/free joints through `mj_integratePos` (see [IK docs](docs/api/ik-control.mdx)). Existing scalar solve calls remain supported; `epsilon` is ignored.
-- Actuator IDs and control addresses are distinct. `useActuators()` / `getActuators()` expose `ctrlAdr`, `ctrlCount`, and per-input `ranges`. Use `api.setCtrl('pid_servo', [position, velocity, feedforward])` or `useCtrl(name, inputIndex)` for multi-input actuators. Scalar hooks/groups reject ambiguous multi-input commands; low-level policy vectors remain flat control vectors.
-- `<MujocoProvider threadCount={2} ...>` initializes an engine thread pool for each simulation when using the opt-in threaded build. This parallelizes engine work; the main `mj_step` call still runs on the UI thread.
-- `<MujocoCanvas integrator="discrete">` and `<MujocoPhysics integrator="discrete">` support the new integrator without changing MJCF defaults when omitted.
-- Snapshots include MuJoCo integration state, including mocap, history, applied forces, and warmstart. They belong to the loaded model; save again after a scene reload. Legacy snapshots remain accepted. Experimental IPC flex contact is not exactly replayable because MuJoCo does not expose all of its state.
-- `FlexRenderer` draws indexed 2D surfaces and 3D boundary surfaces, plus 1D lines.
-
-Review [upstream migration notes](https://mujoco.readthedocs.io/en/3.15.0/changelog.html): actuator damping and flex integration have changed since 3.9. Scalar `data.ctrl[actuator.id]` consumers should use `data.ctrl[actuator.ctrlAdr]`; multi-input controls occupy `ctrlCount` consecutive entries. `homeJoints` is limited to scalar-input models; use MJCF initial poses/keyframes and explicit controls for multi-input models.
-
 ## Install
 
 ```bash
 npm install mujoco-react three @react-three/fiber @react-three/drei
 ```
 
+## Running policies and simulation workloads
+
+Use `const runtime = await api.createRuntime()` after `onReady`, then await
+`runtime.observe()` and `runtime.advance({ steps, controls })`. Physics runs in a
+dedicated worker; commands reject when busy instead of accumulating. The runtime
+supports cancellation, reset, full snapshots, synchronized camera observations,
+and separate physics/capture timing. Use `<CameraView>` for GPU-only previews.
+
+The viewer has an 8 ms / 100-step per-frame budget. Equivalent inline scene
+configs preserve the loaded model. See the [simulation runtime guide](https://dadd.mintlify.app/guides/simulation-runtime)
+for ownership, VLA loops, bundling, and performance limits, or try the
+[worker demo](https://mujoco-react-example.pages.dev/?demo=runtime).
+
 ## Vite Plugin and Type-Safe Names
 
 Use the Vite plugin to generate declaration merging for actuator, sensor, body, joint, site, geom, and keyframe names:
@@ -50,6 +49,10 @@ export default defineConfig({
 });
 ```
 
+The plugin also preserves worker asset URLs in Vite development by excluding
+`mujoco-react` from dependency prebundling. Without it, set
+`optimizeDeps: { exclude: ["mujoco-react"] }` when using the worker runtime.
+
 The plugin writes `src/mujoco-register.gen.ts` during dev and build. Commit that generated file. Vite auto-loads it, so app code imports generated values from `mujoco-react`, not from the generated file:
 
 ```ts
@@ -1167,8 +1170,8 @@ const frame = await apiRef.current?.captureCameraFrame({
 ```
 
 **Live streams.** `useCameraStream(canvasRef, options)` renders a camera into a
-DOM `<canvas>` every frame (offscreen render → blit: no PNG round-trip, no render-
-loop takeover, splat scenes stream safely). Call it inside `<MujocoCanvas>`; the
+DOM `<canvas>` at 10 FPS by default (offscreen render → GPU readback → blit).
+It avoids PNG encoding but still pays readback and pixel-conversion costs. Call it inside `<MujocoCanvas>`; the
 canvas can live anywhere in your DOM:
 
 ```tsx
@@ -1181,8 +1184,8 @@ function WristStream({ canvasRef }) {
 For a transparent picture-in-picture overlay, use `<CameraView>` (or
 `useCameraViewport` to track your own element). It scissors into the main canvas —
 cheaper, but it takes over the render loop while mounted (incompatible with
-postprocessing, occluded by opaque DOM), so prefer `useCameraStream` for panel
-tiles:
+postprocessing, occluded by opaque DOM), so use `useCameraStream` only when HTML compositing requires a separate canvas.
+Prefer GPU viewports for live simulation previews:
 
 ```tsx
 <MujocoCanvas config={config}>
@@ -1427,3 +1430,7 @@ These MuJoCo features are not yet exposed in the WASM binding:
 ## License
 
 Apache-2.0
+
+## Contacts and plasticity
+
+Use MJCF speculative contacts for fast rigid objects and yielding springs for permanent deformation. The existing model/data interface exposes enable flags and plastic state; full snapshots preserve plastic history. See the [guide](docs/guides/engine-features.mdx) and [interactive demos](https://mujoco-react-example.pages.dev/?demo=speculative).

package/dist/chunk-U2Y2BODT.js

@@ -0,0 +1,137 @@
+// src/runtime/engine.ts
+var displayFields = [
+  "qpos",
+  "qvel",
+  "ctrl",
+  "act",
+  "plastic",
+  "sensordata",
+  "xpos",
+  "xquat",
+  "xmat",
+  "geom_xpos",
+  "geom_xmat",
+  "site_xpos",
+  "site_xmat",
+  "cam_xpos",
+  "cam_xmat",
+  "flexvert_xpos",
+  "ten_length",
+  "wrap_xpos",
+  "cvel",
+  "cfrc_ext",
+  "qfrc_applied",
+  "xfrc_applied",
+  "qfrc_bias",
+  "ten_wrapadr",
+  "ten_wrapnum"
+];
+var SimulationEngine = class {
+  constructor(mj, initial) {
+    this.mj = mj;
+    this.initial = initial;
+    mj.FS.writeFile("/runtime.mjb", initial.model);
+    const vfs = new mj.MjVFS();
+    try {
+      this.model = mj.MjModel.from_binary_path("/runtime.mjb", vfs);
+    } finally {
+      vfs.delete();
+      mj.FS.unlink("/runtime.mjb");
+    }
+    this.data = new mj.MjData(this.model);
+    try {
+      this.reset();
+    } catch (error) {
+      this.dispose();
+      throw error;
+    }
+  }
+  model;
+  data;
+  reset() {
+    this.mj.mj_resetData(this.model, this.data);
+    this.restore(this.initial.state);
+  }
+  restore(state) {
+    if (state.signature !== this.mj.mjtState.mjSTATE_INTEGRATION.value || state.values.length !== this.mj.mj_stateSize(this.model, state.signature) || !state.values.every(Number.isFinite)) throw new Error("Invalid runtime snapshot");
+    this.mj.mj_setState(this.model, this.data, Array.from(state.values), state.signature);
+    this.mj.mj_forward(this.model, this.data);
+  }
+  setControls(controls) {
+    if (controls) {
+      if (controls.length !== this.data.ctrl.length || !controls.every(Number.isFinite)) throw new Error("Invalid runtime controls");
+      this.data.ctrl.set(controls);
+    }
+  }
+  step() {
+    const expected = this.data.time + this.model.opt.timestep;
+    this.mj.mj_step(this.model, this.data);
+    if (Math.abs(this.data.time - expected) > 1e-7 || !this.data.qpos.every(Number.isFinite)) {
+      throw new Error("Physics became unstable or reset unexpectedly");
+    }
+  }
+  save() {
+    const signature = this.mj.mjtState.mjSTATE_INTEGRATION.value;
+    const buffer = new this.mj.DoubleBuffer(this.mj.mj_stateSize(this.model, signature));
+    try {
+      this.mj.mj_getState(this.model, this.data, buffer, signature);
+      return { signature, values: new Float64Array(buffer.GetView()) };
+    } finally {
+      buffer.delete();
+    }
+  }
+  snapshot(complete = true) {
+    const integration = complete ? this.save() : void 0;
+    if (integration) this.mj.mj_forward(this.model, this.data);
+    try {
+      return {
+        time: this.data.time,
+        fields: Object.fromEntries(displayFields.map((key) => [key, new Float64Array(this.data[key])])),
+        contacts: complete ? this.contacts() : [],
+        ...integration ? { integration } : {}
+      };
+    } finally {
+      if (integration) this.mj.mj_setState(this.model, this.data, Array.from(integration.values), integration.signature);
+    }
+  }
+  contacts() {
+    const result = [], vector = this.data.contact;
+    const names = this.model.names, addresses = this.model.name_geomadr;
+    const name = (id) => {
+      if (id < 0) return "flex";
+      const start = addresses[id];
+      let end = start;
+      while (end < names.length && names[end]) end++;
+      return new TextDecoder().decode(names.subarray(start, end));
+    };
+    try {
+      for (let i = 0; i < this.data.ncon; i++) {
+        const c = vector.get(i);
+        if (!c) continue;
+        try {
+          result.push({
+            geom1: c.geom1,
+            geom2: c.geom2,
+            geom1Name: name(c.geom1),
+            geom2Name: name(c.geom2),
+            pos: Array.from(c.pos),
+            depth: c.dist
+          });
+        } finally {
+          c.delete();
+        }
+      }
+    } finally {
+      vector.delete();
+    }
+    return result;
+  }
+  dispose() {
+    this.data.delete();
+    this.model.delete();
+  }
+};
+
+export { SimulationEngine, displayFields };
+//# sourceMappingURL=chunk-U2Y2BODT.js.map
+//# sourceMappingURL=chunk-U2Y2BODT.js.map

package/dist/chunk-U2Y2BODT.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/runtime/engine.ts"],"names":[],"mappings":"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","file":"chunk-U2Y2BODT.js","sourcesContent":["import type { MainModule, MjModel, MjData } from '@mujoco/mujoco';\nimport type { ContactInfo } from '../types';\n\nexport const displayFields = ['qpos', 'qvel', 'ctrl', 'act', 'plastic', 'sensordata', 'xpos', 'xquat', 'xmat',\n  'geom_xpos', 'geom_xmat', 'site_xpos', 'site_xmat', 'cam_xpos', 'cam_xmat',\n  'flexvert_xpos', 'ten_length', 'wrap_xpos', 'cvel', 'cfrc_ext', 'qfrc_applied', 'xfrc_applied', 'qfrc_bias', 'ten_wrapadr', 'ten_wrapnum'] as const;\nexport interface EngineState { signature: number; values: Float64Array }\nexport interface EngineInitialization { model: Uint8Array; state: EngineState }\nexport interface DisplayState {\n  time: number;\n  fields: Record<typeof displayFields[number], Float64Array>;\n  contacts: ContactInfo[];\n  integration?: EngineState;\n}\nexport class SimulationEngine {\n  readonly model: MjModel;\n  readonly data: MjData;\n  constructor(private mj: MainModule, private initial: EngineInitialization) {\n    mj.FS.writeFile('/runtime.mjb', initial.model);\n    const vfs = new mj.MjVFS();\n    try { this.model = mj.MjModel.from_binary_path('/runtime.mjb', vfs); }\n    finally { vfs.delete(); mj.FS.unlink('/runtime.mjb'); }\n    this.data = new mj.MjData(this.model);\n    try { this.reset(); } catch (error) { this.dispose(); throw error; }\n  }\n  reset() {\n    this.mj.mj_resetData(this.model, this.data);\n    this.restore(this.initial.state);\n  }\n  restore(state: EngineState) {\n    if (state.signature !== this.mj.mjtState.mjSTATE_INTEGRATION.value ||\n      state.values.length !== this.mj.mj_stateSize(this.model, state.signature) ||\n      !state.values.every(Number.isFinite)) throw new Error('Invalid runtime snapshot');\n    this.mj.mj_setState(this.model, this.data, Array.from(state.values), state.signature);\n    this.mj.mj_forward(this.model, this.data);\n  }\n  setControls(controls?: Float64Array) {\n    if (controls) {\n      if (controls.length !== this.data.ctrl.length || !controls.every(Number.isFinite)) throw new Error('Invalid runtime controls');\n      this.data.ctrl.set(controls);\n    }\n  }\n  step() {\n    const expected = this.data.time + this.model.opt.timestep;\n    this.mj.mj_step(this.model, this.data);\n    if (Math.abs(this.data.time - expected) > 1e-7 || !this.data.qpos.every(Number.isFinite)) {\n      throw new Error('Physics became unstable or reset unexpectedly');\n    }\n  }\n  save(): EngineState {\n    const signature = this.mj.mjtState.mjSTATE_INTEGRATION.value;\n    const buffer = new this.mj.DoubleBuffer(this.mj.mj_stateSize(this.model, signature));\n    try {\n      this.mj.mj_getState(this.model, this.data, buffer, signature);\n      return { signature, values: new Float64Array(buffer.GetView()) };\n    } finally { buffer.delete(); }\n  }\n  snapshot(complete = true): DisplayState {\n    const integration = complete ? this.save() : undefined;\n    // mj_step integrates qpos after computing derived fields. Refresh completed\n    // observations at their reported time, preserving solver warmstart exactly.\n    if (integration) this.mj.mj_forward(this.model, this.data);\n    try { return {\n      time: this.data.time,\n      fields: Object.fromEntries(displayFields.map(key => [key, new Float64Array(this.data[key])])) as DisplayState['fields'],\n      contacts: complete ? this.contacts() : [],\n      ...(integration ? { integration } : {}),\n    }; } finally {\n      if (integration) this.mj.mj_setState(this.model, this.data, Array.from(integration.values), integration.signature);\n    }\n  }\n  private contacts(): ContactInfo[] {\n    const result: ContactInfo[] = [], vector = this.data.contact;\n    const names = this.model.names, addresses = this.model.name_geomadr;\n    const name = (id: number) => {\n      if (id < 0) return 'flex';\n      const start = addresses[id]; let end = start;\n      while (end < names.length && names[end]) end++;\n      return new TextDecoder().decode(names.subarray(start, end));\n    };\n    try {\n      for (let i = 0; i < this.data.ncon; i++) {\n        const c = vector.get(i);\n        if (!c) continue;\n        try { result.push({ geom1: c.geom1, geom2: c.geom2, geom1Name: name(c.geom1), geom2Name: name(c.geom2),\n          pos: Array.from(c.pos) as [number, number, number], depth: c.dist }); }\n        finally { c.delete(); }\n      }\n    } finally { vector.delete(); }\n    return result;\n  }\n  dispose() { this.data.delete(); this.model.delete(); }\n}\n"]}

package/dist/{chunk-UCQ5MJP4.js → chunk-XD3AY7XZ.js}

@@ -315,8 +315,8 @@ function prepareCaptureCamera(camera, options, fallbackCamera, width, height) {
   applyProjectionMatrix(camera, options.projectionMatrix);
   applyCameraPose(camera, options, fallbackCamera);
 }
-function readRenderTargetToCanvas(renderer, target, canvas, context, pixels, imageData, width, height, outputColorSpace, flipX = false) {
-  renderer.readRenderTargetPixels(target, 0, 0, width, height, pixels);
+function readRenderTargetToCanvas(renderer, target, canvas, context, pixels, imageData, width, height, outputColorSpace, flipX = false, readback = true) {
+  if (readback) renderer.readRenderTargetPixels(target, 0, 0, width, height, pixels);
   const rowBytes = width * 4;
   const encodeSrgb = outputColorSpace === THREE.SRGBColorSpace;
   for (let y = 0; y < height; y += 1) {
@@ -532,6 +532,15 @@ function createCameraFrameCaptureSession(renderer, scene, fallbackCamera, option
   const drawContext = context;
   const pixels = new Uint8Array(width * height * 4);
   const imageData = drawContext.createImageData(width, height);
+  let inFlight = false, disposed = false;
+  function assertAvailable() {
+    if (disposed) throw new Error("Camera capture session is disposed");
+    if (inFlight) throw new Error("Camera capture session is busy; await the current capture");
+  }
+  function releaseResources() {
+    target.dispose();
+    if (isolatedRenderer && !isolatedRenderer.cached) isolatedRenderer.renderer.dispose();
+  }
   function resolveCaptureOptions(nextOptions = {}) {
     const captureOptions = { ...options, ...nextOptions };
     if (shouldUseRenderIsolation(captureOptions) !== shouldUseRenderIsolation(options)) {
@@ -614,9 +623,11 @@ function createCameraFrameCaptureSession(renderer, scene, fallbackCamera, option
     };
   }
   function capture(nextOptions = {}) {
+    assertAvailable();
     return renderPreparedCapture(resolveCaptureOptions(nextOptions));
   }
   function capturePixels(nextOptions = {}) {
+    assertAvailable();
     const captureOptions = resolveCaptureOptions(nextOptions);
     renderCaptureToTarget(captureOptions, () => {
       sessionRenderer.readRenderTargetPixels(target, 0, 0, width, height, pixels);
@@ -643,6 +654,16 @@ function createCameraFrameCaptureSession(renderer, scene, fallbackCamera, option
     return { ...tensor, camera, source: result.source };
   }
   async function captureAsync(nextOptions = {}) {
+    assertAvailable();
+    inFlight = true;
+    try {
+      return await captureAsyncInternal(nextOptions);
+    } finally {
+      inFlight = false;
+      if (disposed) releaseResources();
+    }
+  }
+  async function captureAsyncInternal(nextOptions = {}) {
     const captureOptions = resolveCaptureOptions(nextOptions);
     runCapturePreRenderHooks(scene);
     scene.updateMatrixWorld(true);
@@ -707,7 +728,25 @@ function createCameraFrameCaptureSession(renderer, scene, fallbackCamera, option
         restoreRendererState(sessionRenderer, previousState);
       }
     }
-    return renderPreparedCapture(captureOptions);
+    let readback;
+    renderCaptureToTarget(captureOptions, () => {
+      readback = sessionRenderer.readRenderTargetPixelsAsync(target, 0, 0, width, height, pixels);
+    });
+    await readback;
+    readRenderTargetToCanvas(
+      sessionRenderer,
+      target,
+      canvas,
+      drawContext,
+      pixels,
+      imageData,
+      width,
+      height,
+      sessionRenderer.outputColorSpace,
+      captureOptions.flipX ?? false,
+      false
+    );
+    return { canvas, camera, width, height, source: getCameraFrameCaptureSource(captureOptions) };
   }
   return {
     width,
@@ -756,10 +795,9 @@ function createCameraFrameCaptureSession(renderer, scene, fallbackCamera, option
       return { ...result, blob, type };
     },
     dispose() {
-      target.dispose();
-      if (isolatedRenderer && !isolatedRenderer.cached) {
-        isolatedRenderer.renderer.dispose();
-      }
+      if (disposed) return;
+      disposed = true;
+      if (!inFlight) releaseResources();
     }
   };
 }
@@ -1433,5 +1471,5 @@ function clamp01(value) {
  */
 
 export { CAMERA_FRAME_CAPTURE_PRE_RENDER_USER_DATA_KEY, CAMERA_FRAME_CAPTURE_RENDER_USER_DATA_KEY, CAPTURE_EXCLUDE_KEY, ModelActuators, ModelBodies, ModelCameras, ModelGeoms, ModelJoints, ModelKeyframes, ModelResources, ModelSensors, ModelSites, ScenarioLighting, SplatEnvironment, SplatEnvironmentReadinessStatus, VisualScenarioEffects, captureCameraFrame, captureCameraFrameBlob, captureCameraFrameTensor, createCameraFrameCaptureSession, createCaptureCamera, createPairedSplatEnvironment, createSparkSplatViewerUrl, createSplatEnvironmentUserData, createSplatSceneConfig, createVisualScenarioExecutionContext, dataUrlToPolicyImageTensor, getContact, getScenarioBackground, getScenarioCameraPosition, getSplatEnvironmentReadiness, imageDataToPolicyImageTensor, pixelsToPolicyImageTensor, prepareCaptureCamera, registerModelResources, renderCameraFrameToCanvas, useSplatEnvironment, useSplatSceneConfig, useVisualScenarioEffects, useVisualScenarioExecutionContext, withContacts, withSplatEnvironment };
-//# sourceMappingURL=chunk-UCQ5MJP4.js.map
-//# sourceMappingURL=chunk-UCQ5MJP4.js.map
+//# sourceMappingURL=chunk-XD3AY7XZ.js.map
+//# sourceMappingURL=chunk-XD3AY7XZ.js.map