useSensor

Read sensor values by name

Read a MuJoCo sensor’s value by name. Returns a handle with read() updated every physics frame.

Signature

useSensor(name: Sensors): SensorHandle

Usage

import { ModelSensors, useSensor } from "mujoco-react";

function ImuDisplay() {
  const angularVelocity = useSensor(
    ModelSensors.g1["imu-torso-angular-velocity"]
  );
  const textRef = useRef<{ text: string } | null>(null);

  useFrame(() => {
    const v = angularVelocity.read();
    const speed = Math.sqrt(v[0] ** 2 + v[1] ** 2 + v[2] ** 2);
    if (textRef.current) textRef.current.text = `${speed.toFixed(2)} rad/s`;
  });

  return <Text ref={textRef} position={[0, 0.5, 0]} />;
}

Return Value

interface SensorHandle {
  read(): Float64Array;
  dim: number;
  name: Sensors;
}

Field	Type	Description
read()	() => Float64Array	Current sensor reading from data.sensordata
dim	number	Number of values (e.g., 3 for a force sensor, 1 for a scalar)
name	Sensors	Sensor name

Sensor Types

Common MuJoCo sensor types and their dimensions:

Sensor Type	dim	Description
touch	1	Contact normal force
accelerometer	3	Linear acceleration
gyro	3	Angular velocity
force	3	Constraint force
torque	3	Constraint torque
jointpos	1	Joint position
jointvel	1	Joint velocity
framepos	3	Frame position
framequat	4	Frame orientation

Notes

• The read() array is updated every frame via useAfterPhysicsStep
• If the sensor doesn’t exist, read() returns an empty Float64Array
• For enumerating all sensors, use api.getSensors()
• The name parameter accepts string by default, or a generated union type if you use mujocoReact()