Model Introspection

Query bodies, joints, geoms, sensors, and actuators

Methods for querying the structure of the loaded MuJoCo model.

getBodies()

Get all bodies in the model.

const bodies = api.getBodies();
// [{ id: 0, name: "world", mass: 0, parentId: -1 }, ...]

Returns: BodyInfo[]

interface BodyInfo {
  id: number;
  name: string;
  mass: number;
  parentId: number;
}

getJoints()

Get all joints in the model.

const joints = api.getJoints();
joints.forEach(j => {
  console.log(`${j.name}: ${j.typeName}, range [${j.range}]`);
});

Returns: JointInfo[]

interface JointInfo {
  id: number;
  name: string;
  type: number;
  typeName: "free" | "ball" | "slide" | "hinge";
  range: [number, number];
  limited: boolean;
  bodyId: number;
  qposAdr: number;
  dofAdr: number;
}

getGeoms()

Get all geoms in the model.

const geoms = api.getGeoms();

Returns: GeomInfo[]

interface GeomInfo {
  id: number;
  name: string;
  type: number;
  typeName: string;
  size: [number, number, number];
  bodyId: number;
}

getSites()

Get all sites in the model.

const sites = api.getSites();
const tcp = sites.find(s => s.name === "tcp");

Returns: SiteInfo[]

interface SiteInfo {
  id: number;
  name: string;
  bodyId: number;
}

getActuators()

Get all actuators in the model.

const actuators = api.getActuators();
actuators.forEach(a => {
  console.log(`${a.name}: range [${a.range[0]}, ${a.range[1]}]`);
});

Returns: ActuatorInfo[]

interface ActuatorInfo {
  id: number;
  name: string;
  range: [number, number];
}

getActuatedJoints()

Get scalar hinge/slide joints that are directly driven by actuators.

const actuated = api.getActuatedJoints();
actuated.forEach(j => {
  console.log(`${j.name} <= ${j.actuatorName} ctrl[${j.ctrlAdr}]`);
});

Returns: ActuatedJointInfo[]

interface ActuatedJointInfo extends JointInfo {
  actuatorId: number;
  actuatorName: string;
  ctrlAdr: number;
  ctrlRange: [number, number];
}

getControlMap()

Get a writable control group for all directly actuated scalar joints.

const group = api.getControlMap();
const q = group.readQpos(data);
group.writeCtrl(data, q);

Returns: ControlGroupInfo

interface ControlGroupInfo {
  joints: ControlJointInfo[];
  actuators: ActuatorInfo[];
  qposAdr: number[];
  dofAdr: number[];
  ctrlAdr: number[];
  readQpos(data: MujocoData): Float64Array;
  readCtrl(data: MujocoData): Float64Array;
  writeQpos(data: MujocoData, values: ArrayLike<number>): void;
  writeCtrl(data: MujocoData, values: ArrayLike<number>): void;
}

resolveControlGroup(selector)

Resolve the same mapping for a site, body, joint selector, or actuator selector.

import { ModelSites } from "mujoco-react";

const arm = api.resolveControlGroup({ siteName: ModelSites.franka.tcp });
const named = api.resolveControlGroup({
  joints: ["shoulder", "elbow", "wrist"],
});
const panda = api.resolveControlGroup({ actuators: /^actuator/ });

Use this when a model’s actuator order does not match qpos order, or when a scene contains multiple robots.

getSensors()

Get all sensors in the model.

const sensors = api.getSensors();
sensors.forEach(s => {
  console.log(`${s.name}: ${s.typeName}, dim=${s.dim}`);
});

Returns: SensorInfo[]

interface SensorInfo {
  id: number;
  name: string;
  type: number;
  typeName: string;
  dim: number;
  adr: number;
}

getSensorData(name)

Read a specific sensor’s current values.

const force = api.getSensorData("wrist_force");
if (force) {
  console.log("Force:", force[0], force[1], force[2]);
}

name · string · required

Sensor name.

Returns: Float64Array | null — sensor values, or null if not found.

getContacts()

Get all current contacts.

const contacts = api.getContacts();
contacts.forEach(c => {
  console.log(`${c.geom1Name} ↔ ${c.geom2Name} at depth ${c.depth}`);
});

Returns: ContactInfo[]

interface ContactInfo {
  geom1: number;
  geom1Name: string;
  geom2: number;
  geom2Name: string;
  pos: [number, number, number];
  depth: number;
}

getModelOption()

Get simulation options.

const opts = api.getModelOption();
console.log("Timestep:", opts.timestep);
console.log("Gravity:", opts.gravity);

Returns: ModelOptions

interface ModelOptions {
  timestep: number;
  gravity: [number, number, number];
  integrator: number;
}

Example: Model Summary

function ModelInfo() {
  const { api } = useMujoco();
  const [info, setInfo] = useState("");

  useEffect(() => {
    const bodies = api.getBodies();
    const joints = api.getJoints();
    const actuators = api.getActuators();
    const sensors = api.getSensors();
    setInfo(`${bodies.length} bodies, ${joints.length} joints, ${actuators.length} actuators, ${sensors.length} sensors`);
  }, []);

  return <div>{info}</div>;
}