useCtrl

Read/write a single actuator control by name

Provides handle-based read/write access to a single actuator’s control value by name.

Signature

useCtrl(name: Actuators): CtrlHandle

Usage

import { ModelActuators, useCtrl } from "mujoco-react";

function GripperControl() {
  const gripper = useCtrl(ModelActuators.franka.gripper);

  return (
    <div>
      <button onClick={() => gripper.write(0.04)}>Open</button>
      <button onClick={() => gripper.write(0.0)}>Close</button>
    </div>
  );
}

Reading in useFrame

function GripperDisplay() {
  const gripper = useCtrl(ModelActuators.franka.gripper);
  const textRef = useRef<{ text: string } | null>(null);

  useFrame(() => {
    if (textRef.current) {
      textRef.current.text = `Gripper: ${gripper.read().toFixed(3)}`;
    }
  });

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

Inside useBeforePhysicsStep

import { ModelActuators, useBeforePhysicsStep, useCtrl } from "mujoco-react";

function MyController() {
  const shoulder = useCtrl(ModelActuators.franka.actuator1);
  const elbow = useCtrl(ModelActuators.franka.actuator2);

  useBeforePhysicsStep(({ data }) => {
    shoulder.write(Math.sin(data.time));
    elbow.write(Math.cos(data.time) * 0.5);
  });
  return null;
}

Return Value

interface CtrlHandle {
  read(): number;
  write(value: number): void;
  name: Actuators;
  range: [number, number];
}

Field	Type	Description
read()	() => number	Read the current control value from data.ctrl
write()	(v: number) => void	Write a control value directly to data.ctrl
name	Actuators	Actuator name
range	[number, number]	Control range [min, max] from actuator_ctrlrange

Notes

• read() and write() operate directly on data.ctrl — no re-renders
• For setting multiple actuators at once, use api.setCtrl({ name: value, ... })
• The actuator index is resolved once on mount
• The name parameter accepts string by default, or a generated union type if you use mujocoReact()

Actuator IDs identify metadata; control addresses index data.ctrl. New actuator metadata includes ctrlAdr, ctrlCount, and ranges. A PID or orientation actuator can own multiple inputs. Write a complete vector with api.setCtrl(name, values) or access one input with useCtrl(name, inputIndex). Calling scalar-only controls on a multi-input actuator without an input selector throws an actionable error.