mgba_save_state
Save the full emulator state to a numbered slot or file path for rollback, bookmarking, or sharing replay states.
Instructions
PURPOSE: Save the entire emulator state (RAM, CPU/PPU/APU registers, mapper state, sound chip state, timing, in-flight DMA) to either an mGBA-managed numbered slot OR an arbitrary file path. USAGE: Use as a rollback point before risky writes, to bookmark interesting game states, to share repro states, or — on Game Boy — to seed cartridge SRAM cleanly without fighting MBC bus semantics that mgba_write* would bypass. EXACTLY ONE of slot or path must be supplied (passing both, or neither, returns an error). Slots 0-9 are managed by mGBA in its data directory and are ideal for ad-hoc rollback during a session; explicit paths are better for long-term storage and sharing across sessions/machines. The companion mgba_load_state restores from either form. BEHAVIOR: When path is supplied, DESTRUCTIVE TO TARGET FILE: overwrites the file at path if it exists, with no prompt or backup. When slot is supplied, DESTRUCTIVE TO THE NAMED SLOT: overwrites whatever was previously stored in that slot. The state is bound to the EXACT ROM and a compatible mGBA version that produced it — loading it on a different ROM or an incompatible mGBA version typically produces a corrupt run or a hard error. Returns an error if neither slot nor path is supplied, the path's parent directory doesn't exist, the path isn't writable, the slot is out of range, or the relevant bridge save-state method (saveStateSlot vs saveStateFile) is missing on this build (check capabilities in mgba_get_info). RETURNS: Single line 'Saved state to PATH' or 'Saved state to slot N' depending on which form you used.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| slot | No | Save state slot number (0-9). Slot files are managed by mGBA in its data directory. Mutually exclusive with `path` — supply exactly one. Out-of-range slot numbers return an error. | |
| path | No | Absolute filesystem path to write the state to (e.g. C:/temp/checkpoint.ss0 on Windows, /tmp/checkpoint.ss0 on Linux/macOS). Mutually exclusive with `slot` — supply exactly one. Parent directory must exist; file is overwritten without prompt if present. Only works on mGBA builds that expose the saveStateFile capability. |