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 {
  integration?: { signature: number; values: Float64Array; model: MujocoModel };
  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>
  );
}

New snapshots include the full mjSTATE_INTEGRATION vector: mocap poses, external forces, solver warmstart, history, equality activation, and plugin state. Restore requires the same loaded model; snapshots are in-memory objects, not portable serialized assets. Legacy fields remain editable and are applied after the packed state. Legacy snapshots without integration restore only their explicit fields. MuJoCo’s experimental IPC flex contact retains additional private state, so exact replay of IPC contact is unsupported.