> ## Documentation Index
> Fetch the complete documentation index at: https://dadd.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```tsx theme={null}
const snapshot = api.saveState();
```

**Returns:** `StateSnapshot`

```tsx theme={null}
interface StateSnapshot {
  time: number;
  qpos: Float64Array;
  qvel: Float64Array;
  ctrl: Float64Array;
  act: Float64Array;
  qfrc_applied: Float64Array;
}
```

## restoreState(snapshot)

Restore a previously saved state.

```tsx theme={null}
const snapshot = api.saveState();
// ... simulation runs ...
api.restoreState(snapshot); // Back to saved state
```

<ParamField body="snapshot" type="StateSnapshot" required>
  Snapshot from a previous `saveState()` call.
</ParamField>

## setQpos(values)

Set all generalized positions.

```tsx theme={null}
api.setQpos(new Float64Array([0, 0, 0.5, 1, 0, 0, 0])); // Free joint
```

<ParamField body="values" type="Float64Array | number[]" required>
  Array of length `model.nq`.
</ParamField>

## getQpos()

Get all generalized positions.

```tsx theme={null}
const qpos = api.getQpos(); // Float64Array of length nq
```

**Returns:** `Float64Array`

## setQvel(values)

Set all generalized velocities.

```tsx theme={null}
api.setQvel(new Float64Array(model.nv).fill(0)); // Zero all velocities
```

<ParamField body="values" type="Float64Array | number[]" required>
  Array of length `model.nv`.
</ParamField>

## getQvel()

Get all generalized velocities.

```tsx theme={null}
const qvel = api.getQvel(); // Float64Array of length nv
```

**Returns:** `Float64Array`

## applyKeyframe(nameOrIndex)

Apply a named or indexed keyframe from the model.

```tsx theme={null}
api.applyKeyframe("home");  // By name
api.applyKeyframe(0);       // By index
```

<ParamField body="nameOrIndex" type="string | number" required>
  Keyframe name or index. Keyframes are defined in MJCF with `<key>` elements.
</ParamField>

## getKeyframeNames()

Get all keyframe names.

```tsx theme={null}
const names = api.getKeyframeNames(); // ["home", "pose1", ...]
```

**Returns:** `string[]`

## getKeyframeCount()

Get the number of keyframes.

```tsx theme={null}
const count = api.getKeyframeCount(); // e.g., 3
```

**Returns:** `number`

## Example: Checkpoint System

```tsx theme={null}
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>
  );
}
```