State Management

Save, restore, and manipulate simulation state

Methods for saving/restoring simulation snapshots and manipulating joint state.

saveState()

Capture a snapshot of the current simulation state.

const snapshot = api.saveState();

Returns: StateSnapshot

interface StateSnapshot {
  time: number;
  qpos: Float64Array;
  qvel: Float64Array;
  ctrl: Float64Array;
  act: Float64Array;
  qfrc_applied: Float64Array;
}

restoreState(snapshot)

Restore a previously saved state.

const snapshot = api.saveState();
// ... simulation runs ...
api.restoreState(snapshot); // Back to saved state

snapshot · StateSnapshot · required

Snapshot from a previous saveState() call.

setQpos(values)

Set all generalized positions.

api.setQpos(new Float64Array([0, 0, 0.5, 1, 0, 0, 0])); // Free joint

values · Float64Array | number[] · required

Array of length model.nq.

getQpos()

Get all generalized positions.

const qpos = api.getQpos(); // Float64Array of length nq

Returns: Float64Array

setQvel(values)

Set all generalized velocities.

api.setQvel(new Float64Array(model.nv).fill(0)); // Zero all velocities

values · Float64Array | number[] · required

Array of length model.nv.

getQvel()

Get all generalized velocities.

const qvel = api.getQvel(); // Float64Array of length nv

Returns: Float64Array

applyKeyframe(nameOrIndex)

Apply a named or indexed keyframe from the model.

api.applyKeyframe("home");  // By name
api.applyKeyframe(0);       // By index

nameOrIndex · string | number · required

Keyframe name or index. Keyframes are defined in MJCF with <key> elements.

getKeyframeNames()

Get all keyframe names.

const names = api.getKeyframeNames(); // ["home", "pose1", ...]

Returns: string[]

getKeyframeCount()

Get the number of keyframes.

const count = api.getKeyframeCount(); // e.g., 3

Returns: number

Example: Checkpoint System

function CheckpointControls() {
  const { api } = useMujoco();
  const snapshots = useRef<StateSnapshot[]>([]);

  return (
    <div>
      <button onClick={() => snapshots.current.push(api.saveState())}>
        Save Checkpoint ({snapshots.current.length})
      </button>
      <button onClick={() => {
        const snap = snapshots.current.pop();
        if (snap) api.restoreState(snap);
      }}>
        Restore
      </button>
    </div>
  );
}