mujoco-react 8.3.3 → 8.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mujoco-react",
-  "version": "8.3.3",
+  "version": "8.4.0",
   "description": "Composable React Three Fiber building blocks for MuJoCo WASM simulations",
   "type": "module",
   "main": "./dist/index.js",

package/src/core/GenericIK.ts

@@ -41,10 +41,10 @@ export class GenericIK {
      * @param model       MuJoCo model
      * @param data        MuJoCo data (qpos will be temporarily modified, then restored)
      * @param siteId      Index of the end-effector site to control
-     * @param numJoints   Number of arm joints (assumes qpos[0..numJoints-1])
+     * @param qposAdr     qpos addresses for scalar joints in solve order
      * @param targetPos   Target position in world frame
      * @param targetQuat  Target orientation in world frame
-     * @param currentQ    Current joint angles (length = numJoints)
+     * @param currentQ    Current joint angles matching qposAdr order
      * @param opts        Optional solver parameters
      * @returns Joint angles array, or null if solver diverged
      */
@@ -52,14 +52,14 @@ export class GenericIK {
         model: MujocoModel,
         data: MujocoData,
         siteId: number,
-        numJoints: number,
+        qposAdr: ArrayLike<number>,
         targetPos: THREE.Vector3,
         targetQuat: THREE.Quaternion,
-        currentQ: number[],
+        currentQ: ArrayLike<number>,
         opts?: Partial<GenericIKOptions>
     ): number[] | null {
         const o = { ...DEFAULTS, ...opts };
-        const n = numJoints;
+        const n = qposAdr.length;
 
         // Save full qpos so we can restore after solving
         const savedQpos = new Float64Array(data.qpos.length);
@@ -86,9 +86,11 @@ export class GenericIK {
         let bestQ: number[] | null = null;
         let bestErr = Infinity;
 
+        if (n === 0) return null;
+
         for (let iter = 0; iter < o.maxIterations; iter++) {
             // Set joints and run FK
-            for (let i = 0; i < n; i++) data.qpos[i] = q[i];
+            for (let i = 0; i < n; i++) data.qpos[qposAdr[i]] = q[i];
             this.mujoco.mj_forward(model, data);
 
             // Read current site pose
@@ -130,8 +132,9 @@ export class GenericIK {
 
             // Compute Jacobian via finite differences
             for (let j = 0; j < n; j++) {
-                const saved = data.qpos[j];
-                data.qpos[j] = q[j] + o.epsilon;
+                const adr = qposAdr[j];
+                const saved = data.qpos[adr];
+                data.qpos[adr] = q[j] + o.epsilon;
                 this.mujoco.mj_forward(model, data);
 
                 for (let i = 0; i < 3; i++) pertSitePos[i] = sp[off3 + i];
@@ -150,11 +153,11 @@ export class GenericIK {
                 J[5 * n + j] = (dRot[2] / o.epsilon) * o.rotWeight;
 
                 // Restore joint
-                data.qpos[j] = saved;
+                data.qpos[adr] = saved;
             }
 
             // Restore base FK state for next iteration
-            for (let i = 0; i < n; i++) data.qpos[i] = q[i];
+            for (let i = 0; i < n; i++) data.qpos[qposAdr[i]] = q[i];
 
             // Damped least squares: Δq = Jᵀ (J Jᵀ + λI)⁻¹ error
             // 1. Compute JJᵀ (6×6)

package/src/core/MujocoProvider.tsx

@@ -6,7 +6,7 @@
 import loadMujoco from '@mujoco/mujoco';
 import defaultMujocoWasmUrl from '@mujoco/mujoco/mujoco.wasm?url';
 import { createContext, useContext, useEffect, useRef, useState } from 'react';
-import { MujocoModule, MujocoContextValue } from '../types';
+import type { MujocoModule, MujocoContextValue } from '../types';
 
 const MujocoContext = createContext<MujocoContextValue>({
   mujoco: null,
@@ -21,19 +21,77 @@ export function useMujocoWasm(): MujocoContextValue {
   return useContext(MujocoContext);
 }
 
-interface MujocoProviderProps {
+export type MujocoWasmVariant = 'single' | 'threaded' | 'auto';
+
+export interface MujocoLoaderOptions {
+  locateFile?: (path: string) => string;
+  printErr?: (text: string) => void;
+}
+
+export type MujocoLoader = (options?: MujocoLoaderOptions) => Promise<unknown>;
+
+export interface MujocoProviderProps {
   wasmUrl?: string;
+  /** Optional URL for the multi-threaded WASM asset. */
+  mtWasmUrl?: string;
+  /**
+   * Optional official multi-threaded loader, usually imported from
+   * `@mujoco/mujoco/mt`. It is supplied by the app so the default package path
+   * does not force every bundler to process the threaded Emscripten build.
+   */
+  threadedLoader?: MujocoLoader;
+  /**
+   * MuJoCo WASM build to load. `single` is the default and works everywhere.
+   * `threaded` requires `threadedLoader` and cross-origin isolation. `auto`
+   * uses threaded only when both conditions are satisfied.
+   */
+  wasmVariant?: MujocoWasmVariant;
   /** Timeout in ms for WASM module load. Default: 30000. */
   timeout?: number;
   children: React.ReactNode;
   onError?: (error: Error) => void;
 }
 
+function canUseThreadedWasm(): boolean {
+  return typeof globalThis !== 'undefined' && globalThis.crossOriginIsolated === true;
+}
+
+function isMujocoModule(value: unknown): value is MujocoModule {
+  return typeof value === 'object'
+    && value !== null
+    && 'FS' in value
+    && 'MjModel' in value
+    && 'MjData' in value
+    && 'mj_step' in value;
+}
+
+function hasWasmUrl(value: string | undefined): value is string {
+  return typeof value === 'string' && value.length > 0;
+}
+
+function resolveWasmVariant(
+  variant: MujocoWasmVariant | undefined,
+  threadedLoader: MujocoLoader | undefined,
+  mtWasmUrl: string | undefined
+): 'single' | 'threaded' {
+  if (variant === 'threaded') return 'threaded';
+  if (variant === 'auto' && threadedLoader && mtWasmUrl && canUseThreadedWasm()) return 'threaded';
+  return 'single';
+}
+
 /**
  * MujocoProvider — WASM / module lifecycle.
  * Loads the MuJoCo WASM module on mount and provides it to children via context.
  */
-export function MujocoProvider({ wasmUrl, timeout = 30000, children, onError }: MujocoProviderProps) {
+export function MujocoProvider({
+  wasmUrl,
+  mtWasmUrl,
+  threadedLoader,
+  wasmVariant = 'single',
+  timeout = 30000,
+  children,
+  onError,
+}: MujocoProviderProps) {
   const [status, setStatus] = useState<'loading' | 'ready' | 'error'>('loading');
   const [error, setError] = useState<string | null>(null);
   const moduleRef = useRef<MujocoModule | null>(null);
@@ -42,8 +100,31 @@ export function MujocoProvider({ wasmUrl, timeout = 30000, children, onError }:
   useEffect(() => {
     isMounted.current = true;
 
-    const wasmPromise = loadMujoco({
-      locateFile: (path: string) => path.endsWith('.wasm') ? (wasmUrl ?? defaultMujocoWasmUrl) : path,
+    const variant = resolveWasmVariant(wasmVariant, threadedLoader, mtWasmUrl);
+    if (variant === 'threaded' && !threadedLoader) {
+      const err = new Error('MujocoProvider wasmVariant="threaded" requires a threadedLoader from @mujoco/mujoco/mt');
+      setError(err.message);
+      setStatus('error');
+      onError?.(err);
+      return;
+    }
+    let selectedWasmUrl = wasmUrl ?? defaultMujocoWasmUrl;
+
+    if (variant === 'threaded') {
+      if (!hasWasmUrl(mtWasmUrl)) {
+        const err = new Error('MujocoProvider wasmVariant="threaded" requires mtWasmUrl from @mujoco/mujoco/mt/mujoco.wasm?url');
+        setError(err.message);
+        setStatus('error');
+        onError?.(err);
+        return;
+      }
+      selectedWasmUrl = mtWasmUrl;
+    }
+
+    const load: MujocoLoader = variant === 'threaded' && threadedLoader ? threadedLoader : loadMujoco;
+
+    const wasmPromise = load({
+      locateFile: (path: string) => path.endsWith('.wasm') ? selectedWasmUrl : path,
       printErr: (text: string) => {
         if (text.includes('Aborted') && isMounted.current) {
           setError('Simulation crashed. Reload page.');
@@ -59,7 +140,10 @@ export function MujocoProvider({ wasmUrl, timeout = 30000, children, onError }:
     Promise.race([wasmPromise, timeoutPromise])
       .then((inst: unknown) => {
         if (isMounted.current) {
-          moduleRef.current = inst as MujocoModule;
+          if (!isMujocoModule(inst)) {
+            throw new Error('MuJoCo WASM module initialized with an unexpected shape');
+          }
+          moduleRef.current = inst;
           setStatus('ready');
         }
       })
@@ -75,7 +159,7 @@ export function MujocoProvider({ wasmUrl, timeout = 30000, children, onError }:
     return () => {
       isMounted.current = false;
     };
-  }, [wasmUrl, timeout]);
+  }, [wasmUrl, mtWasmUrl, threadedLoader, wasmVariant, timeout, onError]);
 
   return (
     <MujocoContext.Provider

package/src/core/MujocoSimProvider.tsx

@@ -17,8 +17,11 @@ import * as THREE from 'three';
 import { MujocoData, MujocoModel, MujocoModule, getContact, withContacts } from '../types';
 import { SceneRenderer } from '../components/SceneRenderer';
 import {
+  ActuatedJointInfo,
   ActuatorInfo,
   BodyInfo,
+  ControlGroupInfo,
+  ControlGroupSelector,
   ContactInfo,
   GeomInfo,
   JointInfo,
@@ -40,7 +43,10 @@ import {
   findSensorByName,
   findActuatorByName,
   getActuatedScalarQposAdr,
+  getActuatedJoints as getActuatedJointsFromModel,
+  getControlMap as getControlMapFromModel,
   getName,
+  resolveControlGroup as resolveControlGroupFromModel,
 } from './SceneLoader';
 
 // ---- Joint type names ----
@@ -65,6 +71,24 @@ const SENSOR_TYPE_NAMES: Record<number, string> = {
   45: 'clock', 46: 'tactile', 47: 'plugin', 48: 'user',
 };
 
+const EMPTY_CONTROL_GROUP: ControlGroupInfo = {
+  joints: [],
+  actuators: [],
+  qposAdr: [],
+  dofAdr: [],
+  ctrlAdr: [],
+  readQpos: () => new Float64Array(0),
+  readCtrl: () => new Float64Array(0),
+  writeQpos: () => {},
+  writeCtrl: () => {},
+};
+
+function isMutableApiRef(
+  ref: React.ForwardedRef<MujocoSimAPI>
+): ref is React.MutableRefObject<MujocoSimAPI | null> {
+  return typeof ref === 'object' && ref !== null && 'current' in ref;
+}
+
 // Preallocated force/torque temps for applyForce/applyTorque
 const _applyForce = new Float64Array(3);
 const _applyTorque = new Float64Array(3);
@@ -329,8 +353,8 @@ export function MujocoSimProvider({
       if (externalApiRef) {
         if (typeof externalApiRef === 'function') {
           externalApiRef(api);
-        } else {
-          (externalApiRef as React.MutableRefObject<MujocoSimAPI | null>).current = api;
+        } else if (isMutableApiRef(externalApiRef)) {
+          externalApiRef.current = api;
         }
       }
     }
@@ -614,14 +638,14 @@ export function MujocoSimProvider({
     const result: JointInfo[] = [];
     for (let i = 0; i < model.njnt; i++) {
       const type = model.jnt_type[i];
-      const limited = model.jnt_limited ? model.jnt_limited[i] !== 0 : false;
+      const range: [number, number] = [model.jnt_range[2 * i], model.jnt_range[2 * i + 1]];
       result.push({
         id: i,
         name: getName(model, model.name_jntadr[i]),
         type,
         typeName: JOINT_TYPE_NAMES[type] ?? `unknown(${type})`,
-        range: [model.jnt_range[2 * i], model.jnt_range[2 * i + 1]],
-        limited,
+        range,
+        limited: range[0] < range[1],
         bodyId: model.jnt_bodyid[i],
         qposAdr: model.jnt_qposadr[i],
         dofAdr: model.jnt_dofadr[i],
@@ -679,6 +703,21 @@ export function MujocoSimProvider({
     return result;
   }, []);
 
+  const getControlMapApi = useCallback((): ControlGroupInfo => {
+    const model = mjModelRef.current;
+    return model ? getControlMapFromModel(model) : EMPTY_CONTROL_GROUP;
+  }, []);
+
+  const getActuatedJointsApi = useCallback((): ActuatedJointInfo[] => {
+    const model = mjModelRef.current;
+    return model ? getActuatedJointsFromModel(model) : [];
+  }, []);
+
+  const resolveControlGroupApi = useCallback((selector: ControlGroupSelector): ControlGroupInfo | null => {
+    const model = mjModelRef.current;
+    return model ? resolveControlGroupFromModel(model, selector) : null;
+  }, []);
+
   const getSensors = useCallback((): SensorInfo[] => {
     const model = mjModelRef.current;
     if (!model) return [];
@@ -939,6 +978,9 @@ export function MujocoSimProvider({
       getQvel,
       setCtrl,
       getCtrl,
+      getControlMap: getControlMapApi,
+      getActuatedJoints: getActuatedJointsApi,
+      resolveControlGroup: resolveControlGroupApi,
       applyForce,
       applyTorque: applyTorqueApi,
       setExternalForce,
@@ -970,6 +1012,7 @@ export function MujocoSimProvider({
       status, config, reset, setSpeed, togglePause, setPaused, step,
       getTime, getTimestep, applyKeyframe, saveState, restoreState,
       setQpos, setQvel, getQpos, getQvel, setCtrl, getCtrl,
+      getControlMapApi, getActuatedJointsApi, resolveControlGroupApi,
       applyForce, applyTorqueApi, setExternalForce, applyGeneralizedForce,
       getSensorData, getContacts, getBodies, getJoints, getGeoms, getSites,
       getActuatorsApi, getSensors, getModelOption, setGravity, setTimestepApi,

package/src/core/SceneLoader.ts

@@ -3,9 +3,27 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { MujocoData, MujocoModel, MujocoModule } from '../types';
+import type {
+  ActuatedJointInfo,
+  ActuatorInfo,
+  ControlGroupInfo,
+  ControlGroupSelector,
+  ControlJointInfo,
+  JointInfo,
+  MujocoData,
+  MujocoModel,
+  MujocoModule,
+  ResourceSelector,
+} from '../types';
 import { SceneConfig, SceneObject, XmlPatch } from '../types';
 
+const JOINT_TYPE_NAMES: Record<number, string> = {
+  0: 'free',
+  1: 'ball',
+  2: 'slide',
+  3: 'hinge',
+};
+
 /**
  * Reads a null-terminated C string from MuJoCo's WASM memory.
  */
@@ -120,6 +138,330 @@ export function getActuatedScalarQposAdr(mjModel: MujocoModel, actuatorId: numbe
   return mjModel.jnt_qposadr[jointId];
 }
 
+function getScalarJointDim(jointType: number): 0 | 1 {
+  return jointType === 2 || jointType === 3 ? 1 : 0;
+}
+
+function unlimitedRange(): [number, number] {
+  return [-Infinity, Infinity];
+}
+
+function isScalarJoint(mjModel: MujocoModel, jointId: number): boolean {
+  return jointId >= 0 && jointId < mjModel.njnt && getScalarJointDim(mjModel.jnt_type[jointId]) === 1;
+}
+
+function getActuatorJointId(mjModel: MujocoModel, actuatorId: number): number {
+  if (actuatorId < 0 || actuatorId >= mjModel.nu) return -1;
+  const trnType = mjModel.actuator_trntype?.[actuatorId];
+  if (trnType !== undefined && trnType !== 0 && trnType !== 1) return -1;
+  const jointId = mjModel.actuator_trnid[2 * actuatorId];
+  return isScalarJoint(mjModel, jointId) ? jointId : -1;
+}
+
+function getJointInfo(mjModel: MujocoModel, jointId: number): JointInfo {
+  const type = mjModel.jnt_type[jointId];
+  const range: [number, number] = [mjModel.jnt_range[2 * jointId], mjModel.jnt_range[2 * jointId + 1]];
+  return {
+    id: jointId,
+    name: getName(mjModel, mjModel.name_jntadr[jointId]),
+    type,
+    typeName: JOINT_TYPE_NAMES[type] ?? `unknown(${type})`,
+    range,
+    limited: range[0] < range[1],
+    bodyId: mjModel.jnt_bodyid[jointId],
+    qposAdr: mjModel.jnt_qposadr[jointId],
+    dofAdr: mjModel.jnt_dofadr[jointId],
+  };
+}
+
+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(),
+  };
+}
+
+function includesResourceName(names: readonly string[], name: string): boolean {
+  return names.includes(name);
+}
+
+function matchesSelector<TInfo extends { name: string }, TName extends string>(
+  info: TInfo,
+  selector: ResourceSelector<TInfo, TName>
+): boolean {
+  if (typeof selector === 'string') return info.name === selector;
+  if (selector instanceof RegExp) return selector.test(info.name);
+  if (Array.isArray(selector)) return includesResourceName(selector, info.name);
+  if (typeof selector === 'function') return selector(info);
+  return false;
+}
+
+function orderedJointIdsFromSelector(
+  mjModel: MujocoModel,
+  selector: ResourceSelector<JointInfo, string>
+): number[] {
+  if (typeof selector === 'string') {
+    const id = findJointByName(mjModel, selector);
+    return id >= 0 && isScalarJoint(mjModel, id) ? [id] : [];
+  }
+  if (Array.isArray(selector)) {
+    return selector
+      .map((name) => findJointByName(mjModel, name))
+      .filter((id) => id >= 0 && isScalarJoint(mjModel, id));
+  }
+  const ids: number[] = [];
+  for (let i = 0; i < mjModel.njnt; i++) {
+    if (!isScalarJoint(mjModel, i)) continue;
+    const info = getJointInfo(mjModel, i);
+    if (matchesSelector(info, selector)) ids.push(i);
+  }
+  return ids;
+}
+
+function orderedActuatorIdsFromSelector(
+  mjModel: MujocoModel,
+  selector: ResourceSelector<ActuatorInfo, string>
+): number[] {
+  if (typeof selector === 'string') {
+    const id = findActuatorByName(mjModel, selector);
+    return id >= 0 && getActuatorJointId(mjModel, id) >= 0 ? [id] : [];
+  }
+  if (Array.isArray(selector)) {
+    return selector
+      .map((name) => findActuatorByName(mjModel, name))
+      .filter((id) => id >= 0 && getActuatorJointId(mjModel, id) >= 0);
+  }
+  const ids: number[] = [];
+  for (let i = 0; i < mjModel.nu; i++) {
+    if (getActuatorJointId(mjModel, i) < 0) continue;
+    const info = getActuatorInfo(mjModel, i);
+    if (matchesSelector(info, selector)) ids.push(i);
+  }
+  return ids;
+}
+
+function inferScalarJointChain(mjModel: MujocoModel, bodyId: number): number[] {
+  if (bodyId < 0 || bodyId >= mjModel.nbody) return [];
+  const chainByBody: number[][] = [];
+  let current = bodyId;
+  const seen = new Set<number>();
+
+  while (current >= 0 && current < mjModel.nbody && !seen.has(current)) {
+    seen.add(current);
+    const joints: number[] = [];
+    const jointCount = mjModel.body_jntnum[current] ?? 0;
+    const jointStart = mjModel.body_jntadr[current] ?? -1;
+    for (let i = 0; i < jointCount; i++) {
+      const jointId = jointStart + i;
+      if (isScalarJoint(mjModel, jointId)) joints.push(jointId);
+    }
+    if (joints.length) chainByBody.push(joints);
+    const parent = mjModel.body_parentid[current];
+    if (parent === current) break;
+    current = parent;
+  }
+
+  return chainByBody.reverse().flat();
+}
+
+function unique(values: number[]): number[] {
+  const seen = new Set<number>();
+  const result: number[] = [];
+  for (const value of values) {
+    if (seen.has(value)) continue;
+    seen.add(value);
+    result.push(value);
+  }
+  return result;
+}
+
+function findActuatorForJoint(mjModel: MujocoModel, jointId: number, preferredActuatorIds?: number[]): number {
+  const search = preferredActuatorIds ?? Array.from({ length: mjModel.nu }, (_, i) => i);
+  for (const actuatorId of search) {
+    if (getActuatorJointId(mjModel, actuatorId) === jointId) return actuatorId;
+  }
+  return -1;
+}
+
+function buildControlGroup(
+  mjModel: MujocoModel,
+  jointIds: number[],
+  preferredActuatorIds?: number[]
+): ControlGroupInfo | null {
+  const ids = unique(jointIds).filter((id) => isScalarJoint(mjModel, id));
+  if (!ids.length) return null;
+
+  const joints: ControlJointInfo[] = [];
+  const actuators: ActuatorInfo[] = [];
+  const qposAdr: number[] = [];
+  const dofAdr: number[] = [];
+  const ctrlAdr: number[] = [];
+
+  for (const jointId of ids) {
+    const actuatorId = findActuatorForJoint(mjModel, jointId, preferredActuatorIds);
+    const joint = getJointInfo(mjModel, jointId);
+    qposAdr.push(joint.qposAdr);
+    dofAdr.push(joint.dofAdr);
+
+    if (actuatorId >= 0) {
+      const actuator = getActuatorInfo(mjModel, actuatorId);
+      actuators.push(actuator);
+      ctrlAdr.push(actuatorId);
+      joints.push({
+        ...joint,
+        actuatorId,
+        actuatorName: actuator.name,
+        ctrlAdr: actuatorId,
+        ctrlRange: actuator.range,
+      });
+    } else {
+      joints.push({
+        ...joint,
+        actuatorId: null,
+        actuatorName: null,
+        ctrlAdr: null,
+        ctrlRange: null,
+      });
+    }
+  }
+
+  return {
+    joints,
+    actuators,
+    qposAdr,
+    dofAdr,
+    ctrlAdr,
+    readQpos(data: MujocoData) {
+      return new Float64Array(qposAdr.map((adr) => data.qpos[adr] ?? 0));
+    },
+    readCtrl(data: MujocoData) {
+      return new Float64Array(joints.map((joint) => joint.ctrlAdr === null ? 0 : data.ctrl[joint.ctrlAdr] ?? 0));
+    },
+    writeQpos(data: MujocoData, values: ArrayLike<number>) {
+      for (let i = 0; i < Math.min(values.length, qposAdr.length); i++) {
+        data.qpos[qposAdr[i]] = values[i];
+      }
+    },
+    writeCtrl(data: MujocoData, values: ArrayLike<number>) {
+      for (let i = 0; i < Math.min(values.length, joints.length); i++) {
+        const adr = joints[i].ctrlAdr;
+        if (adr !== null) data.ctrl[adr] = values[i];
+      }
+    },
+  };
+}
+
+export function getActuatedJoints(mjModel: MujocoModel): ActuatedJointInfo[] {
+  const result: ActuatedJointInfo[] = [];
+  for (let actuatorId = 0; actuatorId < mjModel.nu; actuatorId++) {
+    const jointId = getActuatorJointId(mjModel, actuatorId);
+    if (jointId < 0) continue;
+    const actuator = getActuatorInfo(mjModel, actuatorId);
+    result.push({
+      ...getJointInfo(mjModel, jointId),
+      actuatorId,
+      actuatorName: actuator.name,
+      ctrlAdr: actuatorId,
+      ctrlRange: actuator.range,
+    });
+  }
+  return result;
+}
+
+export function getControlMap(mjModel: MujocoModel): ControlGroupInfo {
+  const actuatorIds = Array.from({ length: mjModel.nu }, (_, i) => i)
+    .filter((id) => getActuatorJointId(mjModel, id) >= 0);
+  const jointIds = actuatorIds.map((id) => getActuatorJointId(mjModel, id));
+  return buildControlGroup(mjModel, jointIds, actuatorIds) ?? createContiguousControlGroup(mjModel, 0);
+}
+
+export function resolveControlGroup(
+  mjModel: MujocoModel,
+  selector: ControlGroupSelector
+): ControlGroupInfo | null {
+  if (selector.actuators) {
+    const actuatorIds = orderedActuatorIdsFromSelector(mjModel, selector.actuators);
+    const jointIds = actuatorIds.map((id) => getActuatorJointId(mjModel, id));
+    return buildControlGroup(mjModel, jointIds, actuatorIds);
+  }
+
+  if (selector.joints) {
+    return buildControlGroup(mjModel, orderedJointIdsFromSelector(mjModel, selector.joints));
+  }
+
+  if (selector.siteName) {
+    const siteId = findSiteByName(mjModel, selector.siteName);
+    const bodyId = siteId >= 0 ? (mjModel.site_bodyid?.[siteId] ?? -1) : -1;
+    return buildControlGroup(mjModel, inferScalarJointChain(mjModel, bodyId));
+  }
+
+  if (selector.bodyName) {
+    return buildControlGroup(mjModel, inferScalarJointChain(mjModel, findBodyByName(mjModel, selector.bodyName)));
+  }
+
+  return getControlMap(mjModel);
+}
+
+export function createContiguousControlGroup(mjModel: MujocoModel, count: number): ControlGroupInfo {
+  const n = Math.max(0, Math.min(count, mjModel.nq, mjModel.nu));
+  const joints: ControlJointInfo[] = [];
+  const actuators: ActuatorInfo[] = [];
+  const qposAdr: number[] = [];
+  const dofAdr: number[] = [];
+  const ctrlAdr: number[] = [];
+
+  for (let i = 0; i < n; i++) {
+    qposAdr.push(i);
+    dofAdr.push(i);
+    ctrlAdr.push(i);
+    const jointId = Array.from({ length: mjModel.njnt }, (_, id) => id)
+      .find((id) => mjModel.jnt_qposadr[id] === i);
+    const actuator = getActuatorInfo(mjModel, i);
+    actuators.push(actuator);
+    joints.push({
+      ...(jointId !== undefined ? getJointInfo(mjModel, jointId) : {
+        id: i,
+        name: `qpos${i}`,
+        type: 3,
+        typeName: 'hinge',
+        range: unlimitedRange(),
+        limited: false,
+        bodyId: -1,
+        qposAdr: i,
+        dofAdr: i,
+      }),
+      actuatorId: i,
+      actuatorName: actuator.name,
+      ctrlAdr: i,
+      ctrlRange: actuator.range,
+    });
+  }
+
+  return {
+    joints,
+    actuators,
+    qposAdr,
+    dofAdr,
+    ctrlAdr,
+    readQpos(data: MujocoData) {
+      return new Float64Array(qposAdr.map((adr) => data.qpos[adr] ?? 0));
+    },
+    readCtrl(data: MujocoData) {
+      return new Float64Array(ctrlAdr.map((adr) => data.ctrl[adr] ?? 0));
+    },
+    writeQpos(data: MujocoData, values: ArrayLike<number>) {
+      for (let i = 0; i < Math.min(values.length, qposAdr.length); i++) data.qpos[qposAdr[i]] = values[i];
+    },
+    writeCtrl(data: MujocoData, values: ArrayLike<number>) {
+      for (let i = 0; i < Math.min(values.length, ctrlAdr.length); i++) data.ctrl[ctrlAdr[i]] = values[i];
+    },
+  };
+}
+
 /**
  * Convert a SceneObject config to MuJoCo XML.
  */