mujoco-react 10.9.0 → 11.0.0

package/src/core/MujocoSimProvider.tsx

@@ -3,6 +3,10 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { captureSimulationState, restoreSimulationState } from './engineState';
+import { getActuatorInfo, writeActuatorControl } from './SceneLoader';
+import type { ActuatorControlValue, MujocoIntegrator } from '../types';
+
 import { useFrame, useThree } from '@react-three/fiber';
 import {
   createContext,
@@ -544,6 +548,7 @@ interface MujocoSimProviderProps {
   // Declarative physics config props
   gravity?: [number, number, number];
   timestep?: number;
+  integrator?: MujocoIntegrator;
   substeps?: number;
   paused?: boolean;
   speed?: number;
@@ -563,6 +568,7 @@ export function MujocoSimProvider({
   onSelection,
   gravity,
   timestep,
+  integrator,
   substeps,
   paused,
   speed,
@@ -627,6 +633,16 @@ export function MujocoSimProvider({
     model.opt.gravity[2] = gravity[2];
   }, [gravity]);
 
+  const integratorRef = useRef(integrator);
+  integratorRef.current = integrator;
+  const applyIntegrator = (model: MujocoModel) => {
+    const value = integratorRef.current;
+    if (value !== undefined) model.opt.integrator = { Euler: 0, RK4: 1, implicit: 2, implicitfast: 3, discrete: 4 }[value];
+  };
+  useEffect(() => {
+    if (mjModelRef.current) applyIntegrator(mjModelRef.current);
+  }, [integrator]);
+
   // Sync timestep prop
   useEffect(() => {
     if (timestep === undefined) return;
@@ -683,12 +699,13 @@ export function MujocoSimProvider({
       try {
         const result = await loadScene(mujoco, buildMergedConfig(config));
         if (disposed) {
-          result.mjModel.delete();
           result.mjData.delete();
+          result.mjModel.delete();
           return;
         }
 
         mujocoRef.current = mujoco;
+        applyIntegrator(result.mjModel);
         mjModelRef.current = result.mjModel;
         mjDataRef.current = result.mjData;
         physicsAccumulatorRef.current = 0;
@@ -717,8 +734,8 @@ export function MujocoSimProvider({
 
     return () => {
       disposed = true;
-      mjModelRef.current?.delete();
       mjDataRef.current?.delete();
+      mjModelRef.current?.delete();
       mjModelRef.current = null;
       mjDataRef.current = null;
       physicsAccumulatorRef.current = 0;
@@ -927,27 +944,16 @@ export function MujocoSimProvider({
   const saveState = useCallback((): StateSnapshot => {
     const data = mjDataRef.current;
     if (!data) return { time: 0, qpos: new Float64Array(0), qvel: new Float64Array(0), ctrl: new Float64Array(0), act: new Float64Array(0), qfrc_applied: new Float64Array(0) };
-    return {
-      time: data.time,
-      qpos: new Float64Array(data.qpos),
-      qvel: new Float64Array(data.qvel),
-      ctrl: new Float64Array(data.ctrl),
-      act: new Float64Array(data.act),
-      qfrc_applied: new Float64Array(data.qfrc_applied),
-    };
+    return captureSimulationState(mujocoRef.current, mjModelRef.current!, data);
   }, []);
 
   const restoreState = useCallback((snapshot: StateSnapshot) => {
     const model = mjModelRef.current;
     const data = mjDataRef.current;
     if (!model || !data) return;
-    data.time = snapshot.time;
-    data.qpos.set(snapshot.qpos);
-    data.qvel.set(snapshot.qvel);
-    data.ctrl.set(snapshot.ctrl);
-    if (snapshot.act.length > 0) data.act.set(snapshot.act);
-    data.qfrc_applied.set(snapshot.qfrc_applied);
-    mujocoRef.current.mj_forward(model, data);
+    restoreSimulationState(mujocoRef.current, model, data, snapshot);
+    physicsAccumulatorRef.current = 0;
+    interpolationStateRef.current.valid = false;
   }, [mujoco]);
 
   const setQpos = useCallback((values: Float64Array | number[]) => {
@@ -974,18 +980,18 @@ export function MujocoSimProvider({
     return mjDataRef.current ? new Float64Array(mjDataRef.current.qvel) : new Float64Array(0);
   }, []);
 
-  const setCtrl = useCallback((nameOrValues: string | Record<string, number>, value?: number) => {
+  const setCtrl = useCallback((nameOrValues: string | Record<string, ActuatorControlValue>, value?: ActuatorControlValue) => {
     const model = mjModelRef.current;
     const data = mjDataRef.current;
     if (!model || !data) return;
 
     if (typeof nameOrValues === 'string') {
       const id = findActuatorByName(model, nameOrValues);
-      if (id >= 0 && value !== undefined) data.ctrl[id] = value;
+      if (value !== undefined) writeActuatorControl(model, data, id, value);
     } else {
       for (const [name, val] of Object.entries(nameOrValues)) {
         const id = findActuatorByName(model, name);
-        if (id >= 0) data.ctrl[id] = val;
+        writeActuatorControl(model, data, id, val);
       }
     }
   }, []);
@@ -1152,17 +1158,7 @@ export function MujocoSimProvider({
   const getActuatorsApi = useCallback((): ActuatorInfo[] => {
     const model = mjModelRef.current;
     if (!model) return [];
-    const result: ActuatorInfo[] = [];
-    for (let i = 0; i < model.nu; i++) {
-      const hasRange = model.actuator_ctrlrange[2 * i] < model.actuator_ctrlrange[2 * i + 1];
-      result.push({
-        id: i,
-        name: getName(model, model.name_actuatoradr[i]),
-        range: hasRange
-          ? [model.actuator_ctrlrange[2 * i], model.actuator_ctrlrange[2 * i + 1]]
-          : [-Infinity, Infinity],
-      });
-    }
+    const result = Array.from({ length: model.nactuator }, (_, id) => getActuatorInfo(model, id));
     return result;
   }, []);
 
@@ -1466,8 +1462,8 @@ export function MujocoSimProvider({
   const loadSceneApi = useCallback(async (newConfig: SceneConfig): Promise<void> => {
     const gen = ++loadGenRef.current;
     try {
-      mjModelRef.current?.delete();
       mjDataRef.current?.delete();
+      mjModelRef.current?.delete();
       mjModelRef.current = null;
       mjDataRef.current = null;
       setStatus('loading');
@@ -1475,12 +1471,13 @@ export function MujocoSimProvider({
       const result = await loadScene(mujoco, buildMergedConfig(newConfig));
 
       if (gen !== loadGenRef.current) {
-        result.mjModel.delete();
         result.mjData.delete();
+        result.mjModel.delete();
         return;
       }
 
-      mjModelRef.current = result.mjModel;
+      applyIntegrator(result.mjModel);
+        mjModelRef.current = result.mjModel;
       mjDataRef.current = result.mjData;
       physicsAccumulatorRef.current = 0;
       interpolationStateRef.current.valid = false;

package/src/core/SceneLoader.ts

@@ -3,6 +3,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { initializeDataThreads } from './engineState';
+
 import type {
   ActuatedJointInfo,
   ActuatorInfo,
@@ -54,7 +56,7 @@ export function findSiteByName(mjModel: MujocoModel, name: string): number {
  * Find an actuator by name in the MuJoCo model. Returns -1 if not found.
  */
 export function findActuatorByName(mjModel: MujocoModel, name: string): number {
-  for (let i = 0; i < mjModel.nu; i++) {
+  for (let i = 0; i < mjModel.nactuator; i++) {
     if (getName(mjModel, mjModel.name_actuatoradr[i]).includes(name)) return i;
   }
   return -1;
@@ -138,7 +140,7 @@ export function findTendonByName(mjModel: MujocoModel, name: string): number {
  * Returns -1 for non-joint transmissions and multi-DOF joints.
  */
 export function getActuatedScalarQposAdr(mjModel: MujocoModel, actuatorId: number): number {
-  if (actuatorId < 0 || actuatorId >= mjModel.nu) return -1;
+  if (actuatorId < 0 || actuatorId >= mjModel.nactuator) return -1;
 
   // mjTRN_JOINT=0, mjTRN_JOINTINPARENT=1. Other transmission types don't map ctrl to a single qpos.
   const trnType = mjModel.actuator_trntype?.[actuatorId];
@@ -166,7 +168,7 @@ function isScalarJoint(mjModel: MujocoModel, jointId: number): boolean {
 }
 
 function getActuatorJointId(mjModel: MujocoModel, actuatorId: number): number {
-  if (actuatorId < 0 || actuatorId >= mjModel.nu) return -1;
+  if (actuatorId < 0 || actuatorId >= mjModel.nactuator) return -1;
   const trnType = mjModel.actuator_trntype?.[actuatorId];
   if (trnType !== undefined && trnType !== 0 && trnType !== 1) return -1;
   const jointId = mjModel.actuator_trnid[2 * actuatorId];
@@ -189,15 +191,35 @@ function getJointInfo(mjModel: MujocoModel, jointId: number): JointInfo {
   };
 }
 
-function getActuatorInfo(mjModel: MujocoModel, actuatorId: number): ActuatorInfo {
-  const hasRange = mjModel.actuator_ctrlrange[2 * actuatorId] < mjModel.actuator_ctrlrange[2 * actuatorId + 1];
-  return {
-    id: actuatorId,
-    name: getName(mjModel, mjModel.name_actuatoradr[actuatorId]),
-    range: hasRange
-      ? [mjModel.actuator_ctrlrange[2 * actuatorId], mjModel.actuator_ctrlrange[2 * actuatorId + 1]]
-      : unlimitedRange(),
-  };
+export function getActuatorInfo(mjModel: MujocoModel, actuatorId: number): ActuatorInfo {
+  const ctrlAdr = mjModel.actuator_ctrladr[actuatorId];
+  const ctrlCount = mjModel.actuator_ctrlnum[actuatorId];
+  const ranges = Array.from({ length: ctrlCount }, (_, input): [number, number] => {
+    const adr = ctrlAdr + input;
+    const lo = mjModel.actuator_ctrlrange[2 * adr], hi = mjModel.actuator_ctrlrange[2 * adr + 1];
+    return lo < hi ? [lo, hi] : [-Infinity, Infinity];
+  });
+  return { id: actuatorId, name: getName(mjModel, mjModel.name_actuatoradr[actuatorId]),
+    ctrlAdr, ctrlCount, ranges, range: ranges[0] ?? [-Infinity, Infinity] };
+}
+
+/** Resolve one input; scalar-only callers reject ambiguous multi-input actuators. */
+export function getActuatorControlAddress(model: MujocoModel, id: number, input?: number): number {
+  if (id < 0) return -1;
+  const count = model.actuator_ctrlnum[id];
+  if (input === undefined && count !== 1) throw new Error('This actuator requires an explicit input index or a complete control vector');
+  const index = input ?? 0;
+  if (!Number.isInteger(index) || index < 0 || index >= count) throw new Error('Actuator input index out of range');
+  return model.actuator_ctrladr[id] + index;
+}
+
+export function writeActuatorControl(model: MujocoModel, data: MujocoData, id: number, value: number | readonly number[]): void {
+  if (id < 0) return;
+  const values = typeof value === 'number' ? [value] : value;
+  if (values.length !== model.actuator_ctrlnum[id] || !values.every(Number.isFinite)) {
+    throw new Error('Actuator control must contain one finite value per input');
+  }
+  data.ctrl.set(values, model.actuator_ctrladr[id]);
 }
 
 function includesResourceName(names: readonly string[], name: string): boolean {
@@ -251,7 +273,7 @@ function orderedActuatorIdsFromSelector(
       .filter((id) => id >= 0 && getActuatorJointId(mjModel, id) >= 0);
   }
   const ids: number[] = [];
-  for (let i = 0; i < mjModel.nu; i++) {
+  for (let i = 0; i < mjModel.nactuator; i++) {
     if (getActuatorJointId(mjModel, i) < 0) continue;
     const info = getActuatorInfo(mjModel, i);
     if (matchesSelector(info, selector)) ids.push(i);
@@ -295,9 +317,9 @@ function unique(values: number[]): number[] {
 }
 
 function findActuatorForJoint(mjModel: MujocoModel, jointId: number, preferredActuatorIds?: number[]): number {
-  const search = preferredActuatorIds ?? Array.from({ length: mjModel.nu }, (_, i) => i);
+  const search = preferredActuatorIds ?? Array.from({ length: mjModel.nactuator }, (_, i) => i);
   for (const actuatorId of search) {
-    if (getActuatorJointId(mjModel, actuatorId) === jointId) return actuatorId;
+    if (mjModel.actuator_ctrlnum[actuatorId] === 1 && getActuatorJointId(mjModel, actuatorId) === jointId) return actuatorId;
   }
   return -1;
 }
@@ -325,12 +347,12 @@ function buildControlGroup(
     if (actuatorId >= 0) {
       const actuator = getActuatorInfo(mjModel, actuatorId);
       actuators.push(actuator);
-      ctrlAdr.push(actuatorId);
+      ctrlAdr.push(getActuatorControlAddress(mjModel, actuatorId));
       joints.push({
         ...joint,
         actuatorId,
         actuatorName: actuator.name,
-        ctrlAdr: actuatorId,
+        ctrlAdr: getActuatorControlAddress(mjModel, actuatorId),
         ctrlRange: actuator.range,
       });
     } else {
@@ -372,15 +394,15 @@ function buildControlGroup(
 
 export function getActuatedJoints(mjModel: MujocoModel): ActuatedJointInfo[] {
   const result: ActuatedJointInfo[] = [];
-  for (let actuatorId = 0; actuatorId < mjModel.nu; actuatorId++) {
+  for (let actuatorId = 0; actuatorId < mjModel.nactuator; actuatorId++) {
     const jointId = getActuatorJointId(mjModel, actuatorId);
-    if (jointId < 0) continue;
+    if (jointId < 0 || mjModel.actuator_ctrlnum[actuatorId] !== 1) continue;
     const actuator = getActuatorInfo(mjModel, actuatorId);
     result.push({
       ...getJointInfo(mjModel, jointId),
       actuatorId,
       actuatorName: actuator.name,
-      ctrlAdr: actuatorId,
+      ctrlAdr: getActuatorControlAddress(mjModel, actuatorId),
       ctrlRange: actuator.range,
     });
   }
@@ -388,8 +410,8 @@ export function getActuatedJoints(mjModel: MujocoModel): ActuatedJointInfo[] {
 }
 
 export function getControlMap(mjModel: MujocoModel): ControlGroupInfo {
-  const actuatorIds = Array.from({ length: mjModel.nu }, (_, i) => i)
-    .filter((id) => getActuatorJointId(mjModel, id) >= 0);
+  const actuatorIds = Array.from({ length: mjModel.nactuator }, (_, i) => i)
+    .filter((id) => mjModel.actuator_ctrlnum[id] === 1 && getActuatorJointId(mjModel, id) >= 0);
   const jointIds = actuatorIds.map((id) => getActuatorJointId(mjModel, id));
   return buildControlGroup(mjModel, jointIds, actuatorIds) ?? createContiguousControlGroup(mjModel, 0);
 }
@@ -400,6 +422,7 @@ export function resolveControlGroup(
 ): ControlGroupInfo | null {
   if (selector.actuators) {
     const actuatorIds = orderedActuatorIdsFromSelector(mjModel, selector.actuators);
+    for (const id of actuatorIds) getActuatorControlAddress(mjModel, id);
     const jointIds = actuatorIds.map((id) => getActuatorJointId(mjModel, id));
     return buildControlGroup(mjModel, jointIds, actuatorIds);
   }
@@ -422,6 +445,9 @@ export function resolveControlGroup(
 }
 
 export function createContiguousControlGroup(mjModel: MujocoModel, count: number): ControlGroupInfo {
+  if (count > 0 && (mjModel.nactuator !== mjModel.nu || Array.from(mjModel.actuator_ctrlnum).some((n) => n !== 1))) {
+    throw new Error('Legacy numJoints control groups require scalar-input actuators; use named controls');
+  }
   const n = Math.max(0, Math.min(count, mjModel.nq, mjModel.nu));
   const joints: ControlJointInfo[] = [];
   const actuators: ActuatorInfo[] = [];
@@ -837,14 +863,18 @@ async function loadSceneFromFiles(
   onProgress?.('Loading model...');
   const mjModel = loadModelFromPath(mujoco, `/working/${config.sceneFile}`);
   const mjData = new mujoco.MjData(mjModel);
-  applyInitialPose(mjModel, mjData, config);
-  mujoco.mj_forward(mjModel, mjData);
+  try {
+    initializeDataThreads(mujoco, mjData);
+    applyInitialPose(mjModel, mjData, config);
+    mujoco.mj_forward(mjModel, mjData);
 
-  return { mjModel, mjData };
+    return { mjModel, mjData };
+  } catch (error) { mjData.delete(); mjModel.delete(); throw error; }
 }
 
 function applyInitialPose(mjModel: MujocoModel, mjData: MujocoData, config: SceneConfig) {
   if (!config.homeJoints) return;
+  if (config.homeJoints.length && (mjModel.nactuator !== mjModel.nu || Array.from(mjModel.actuator_ctrlnum).some((n) => n !== 1))) throw new Error('homeJoints requires scalar-input actuators; use a keyframe for multi-input models');
   const homeCount = Math.min(config.homeJoints.length, Math.max(mjModel.nu, mjModel.nq));
   for (let i = 0; i < homeCount; i++) {
     if (i < mjModel.nu) mjData.ctrl[i] = config.homeJoints[i];
@@ -946,14 +976,17 @@ export async function loadScene(
   onProgress?.('Loading model...');
   const mjModel = loadModelFromPath(mujoco, `/working/${config.sceneFile}`);
   const mjData = new mujoco.MjData(mjModel);
+  try {
+    initializeDataThreads(mujoco, mjData);
 
-  // 6. Set initial pose — set both ctrl and qpos so robot starts at home.
-  //    If homeJoints is not provided, keep raw MuJoCo defaults.
-  applyInitialPose(mjModel, mjData, config);
+    // 6. Set initial pose — set both ctrl and qpos so robot starts at home.
+    //    If homeJoints is not provided, keep raw MuJoCo defaults.
+    applyInitialPose(mjModel, mjData, config);
 
-  mujoco.mj_forward(mjModel, mjData);
+    mujoco.mj_forward(mjModel, mjData);
 
-  return { mjModel, mjData };
+    return { mjModel, mjData };
+  } catch (error) { mjData.delete(); mjModel.delete(); throw error; }
 }
 
 /**

package/src/core/engineState.ts

@@ -0,0 +1,58 @@
+import type { MujocoModule, MujocoModel, MujocoData, StateSnapshot } from '../types';
+
+const threadCounts = new WeakMap<MujocoModule, number>();
+export function configureModuleThreads(module: MujocoModule, count: number) {
+  threadCounts.set(module, count);
+}
+export function initializeDataThreads(module: MujocoModule, data: MujocoData) {
+  const count = threadCounts.get(module) ?? 0;
+  if (count > 0) module.mju_threadpool(data, count);
+}
+
+export function captureSimulationState(
+  module: MujocoModule,
+  model: MujocoModel,
+  data: MujocoData,
+): StateSnapshot {
+  const signature = module.mjtState.mjSTATE_INTEGRATION.value;
+  const buffer = new module.DoubleBuffer(module.mj_stateSize(model, signature));
+  try {
+    module.mj_getState(model, data, buffer, signature);
+    return {
+      time: data.time,
+      qpos: new Float64Array(data.qpos),
+      qvel: new Float64Array(data.qvel),
+      ctrl: new Float64Array(data.ctrl),
+      act: new Float64Array(data.act),
+      qfrc_applied: new Float64Array(data.qfrc_applied),
+      integration: { signature, values: new Float64Array(buffer.GetView()), model },
+    };
+  } finally {
+    buffer.delete();
+  }
+}
+
+export function restoreSimulationState(
+  module: MujocoModule,
+  model: MujocoModel,
+  data: MujocoData,
+  snapshot: StateSnapshot,
+) {
+  const integration = snapshot.integration;
+  if (
+    integration &&
+    (integration.model !== model ||
+      integration.values.length !== module.mj_stateSize(model, integration.signature))
+  ) {
+    throw new Error('Snapshot belongs to a different model; capture a new snapshot after loading a scene');
+  }
+  for (const key of ['qpos', 'qvel', 'ctrl', 'act', 'qfrc_applied'] as const) {
+    if (snapshot[key].length !== data[key].length)
+      throw new Error(`Snapshot ${key} size does not match model`);
+  }
+  if (integration) module.mj_setState(model, data, Array.from(integration.values), integration.signature);
+  // Preserve editable legacy fields; the packed state supplies mocap/history/etc.
+  data.time = snapshot.time;
+  for (const key of ['qpos', 'qvel', 'ctrl', 'act', 'qfrc_applied'] as const) data[key].set(snapshot[key]);
+  module.mj_forward(model, data);
+}

package/src/hooks/useActuators.ts

@@ -5,12 +5,12 @@
 
 import { useMemo } from 'react';
 import { useMujocoContext } from '../core/MujocoSimProvider';
-import { getName } from '../core/SceneLoader';
+import { getActuatorInfo } from '../core/SceneLoader';
 import type { ActuatorInfo } from '../types';
 
 /**
  * Returns a stable array of actuator metadata for building control UIs.
- * Computed once when the model loads. Consumer reads/writes data.ctrl[id] directly.
+ * Computed once when the model loads. Use ctrlAdr and ctrlCount to address controls.
  */
 export function useActuators(): ActuatorInfo[] {
   const { mjModelRef, status } = useMujocoContext();
@@ -20,17 +20,7 @@ export function useActuators(): ActuatorInfo[] {
     const model = mjModelRef.current;
     if (!model) return [];
 
-    const actuators: ActuatorInfo[] = [];
-    for (let i = 0; i < model.nu; i++) {
-      const name = getName(model, model.name_actuatoradr[i]);
-      const lo = model.actuator_ctrlrange[i * 2];
-      const hi = model.actuator_ctrlrange[i * 2 + 1];
-      const hasRange = lo < hi;
-      const range: [number, number] = hasRange
-        ? [lo, hi]
-        : [-Infinity, Infinity];
-      actuators.push({ id: i, name, range });
-    }
+    const actuators = Array.from({ length: model.nactuator }, (_, id) => getActuatorInfo(model, id));
     return actuators;
   }, [status, mjModelRef]);
 }

package/src/hooks/useControlGroup.ts

@@ -8,7 +8,7 @@
  */
 
 import { useCallback, useEffect, useId, useMemo, useRef } from 'react';
-import { findActuatorByName } from '../core/SceneLoader';
+import { findActuatorByName, getActuatorControlAddress } from '../core/SceneLoader';
 import { useMujocoContext } from '../core/MujocoSimProvider';
 import { useControlWriter, type ControlWriterOptions } from './useControlWriter';
 import type { Actuators } from '../types';
@@ -150,7 +150,7 @@ export function useControlGroup<K extends Actuators>(
       if (id < 0) {
         console.warn(`[mujoco-react] useControlGroup: actuator "${name}" was not found.`);
       }
-      return id;
+      return getActuatorControlAddress(model, id);
     });
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [mjModelRef, status, namesKey]);

package/src/hooks/useCtrl.ts

@@ -7,7 +7,7 @@
 
 import { useEffect, useRef, useMemo } from 'react';
 import { useMujocoContext } from '../core/MujocoSimProvider';
-import { findActuatorByName } from '../core/SceneLoader';
+import { findActuatorByName, getActuatorControlAddress } from '../core/SceneLoader';
 import type { Actuators, CtrlHandle } from '../types';
 
 /**
@@ -16,7 +16,7 @@ import type { Actuators, CtrlHandle } from '../types';
  * Returns a `CtrlHandle` with `read()` and `write()` methods that
  * operate directly on `data.ctrl` without causing React re-renders.
  */
-export function useCtrl(name: Actuators): CtrlHandle {
+export function useCtrl(name: Actuators, input?: number): CtrlHandle {
   const { mjModelRef, mjDataRef, status } = useMujocoContext();
   const actuatorIdRef = useRef(-1);
   const rangeRef = useRef<[number, number]>([0, 0]);
@@ -25,14 +25,15 @@ export function useCtrl(name: Actuators): CtrlHandle {
     const model = mjModelRef.current;
     if (!model || status !== 'ready') return;
     const id = findActuatorByName(model, name);
-    actuatorIdRef.current = id;
+    const adr = getActuatorControlAddress(model, id, input);
+    actuatorIdRef.current = adr;
     if (id >= 0) {
       rangeRef.current = [
-        model.actuator_ctrlrange[id * 2],
-        model.actuator_ctrlrange[id * 2 + 1],
+        model.actuator_ctrlrange[adr * 2],
+        model.actuator_ctrlrange[adr * 2 + 1],
       ];
     }
-  }, [name, status, mjModelRef]);
+  }, [name, input, status, mjModelRef]);
 
   return useMemo<CtrlHandle>(() => ({
     read() {

package/src/hooks/useGamepad.ts

@@ -7,7 +7,7 @@
 
 import { useEffect, useRef } from 'react';
 import { useMujocoContext, useBeforePhysicsStep } from '../core/MujocoSimProvider';
-import { findActuatorByName } from '../core/SceneLoader';
+import { findActuatorByName, getActuatorControlAddress } from '../core/SceneLoader';
 
 interface GamepadConfig {
   /** Map gamepad axis index to actuator name. */
@@ -43,10 +43,10 @@ export function useGamepad(config: GamepadConfig) {
     axisCacheRef.current.clear();
     buttonCacheRef.current.clear();
     for (const [idx, name] of Object.entries(config.axes ?? {})) {
-      axisCacheRef.current.set(Number(idx), findActuatorByName(model, name));
+      axisCacheRef.current.set(Number(idx), getActuatorControlAddress(model, findActuatorByName(model, name)));
     }
     for (const [idx, name] of Object.entries(config.buttons ?? {})) {
-      buttonCacheRef.current.set(Number(idx), findActuatorByName(model, name));
+      buttonCacheRef.current.set(Number(idx), getActuatorControlAddress(model, findActuatorByName(model, name)));
     }
   }, [config.axes, config.buttons, status, mjModelRef]);
 

package/src/hooks/useKeyboardTeleop.ts

@@ -7,7 +7,7 @@
 
 import { useEffect, useRef } from 'react';
 import { useMujocoContext, useBeforePhysicsStep } from '../core/MujocoSimProvider';
-import { findActuatorByName } from '../core/SceneLoader';
+import { findActuatorByName, getActuatorControlAddress } from '../core/SceneLoader';
 import type { KeyboardTeleopConfig } from '../types';
 
 /**
@@ -37,7 +37,7 @@ export function useKeyboardTeleop(config: KeyboardTeleopConfig) {
     const cache = new Map<string, number>();
     for (const binding of Object.values(config.bindings)) {
       if (!cache.has(binding.actuator)) {
-        cache.set(binding.actuator, findActuatorByName(model, binding.actuator));
+        cache.set(binding.actuator, getActuatorControlAddress(model, findActuatorByName(model, binding.actuator)));
       }
     }
     actuatorCacheRef.current = cache;

package/src/index.ts

@@ -313,6 +313,7 @@ export type {
   GeomInfo,
   SiteInfo,
   ActuatorInfo,
+  ActuatorControlValue,
   SensorInfo,
   CameraInfo,
   // Contacts
@@ -324,6 +325,7 @@ export type {
   ImagePointProjectionResult,
   // Model options
   ModelOptions,
+  MujocoIntegrator,
   // Trajectory
   TrajectoryFrame,
   TrajectoryData,

package/src/rendering/flexTopology.ts

@@ -0,0 +1,24 @@
+import type { MujocoModel } from '../types';
+
+/** MuJoCo flex topology uses vertex indices local to each flex. */
+export function getFlexTopology(
+  model: MujocoModel,
+  id: number,
+): { kind: 'mesh' | 'lines' | 'points'; indices: number[] } {
+  const dim = model.flex_dim[id];
+  if (dim === 3) {
+    const start = model.flex_shelldataadr[id];
+    return {
+      kind: 'mesh',
+      indices: Array.from(model.flex_shell.subarray(start, start + 3 * model.flex_shellnum[id])),
+    };
+  }
+  if (dim === 1 || dim === 2) {
+    const start = model.flex_elemdataadr[id];
+    return {
+      kind: dim === 2 ? 'mesh' : 'lines',
+      indices: Array.from(model.flex_elem.subarray(start, start + (dim + 1) * model.flex_elemnum[id])),
+    };
+  }
+  return { kind: 'points', indices: [] };
+}