SCRYMAMEReferenceStatesstate_writeAlso in DOSBox-X
state_write
Save the emulated machine to a file under a name, or load a saved one back.
state_write(method, name)
Try it
Save the machine here under the name two_credits, so I can come back to it.
state_write(method="save", name="two_credits"){
"status": "ok",
"name": "two-credits",
"path": "./tmp/demos/tour/gridlee-states/sta/gridlee/two-credits.sta",
"frame": 543,
"pc": "0x0000b502"
}Later, with the game on its level card, the load:
state_write(method="load", name="two_credits"){
"summary": "state_write load: two-credits, rom_check OK, verified True, frame 543, pc 0x0000b502",
"rom_check": "OK",
"verified": true,
"saved": {"frame": 543, "pc": "0x0000b502"},
"frame": 543
}The name is kept as two-credits, saved at frame 543. The load puts the machine back at that frame: verified says it reads as it did at the save, and rom_check that the ROM still matches.
The two replies, whole
The first call's:
{
"summary": "<volatile>",
"status": "ok",
"name": "two-credits",
"path": "./tmp/demos/tour/gridlee-states/sta/gridlee/two-credits.sta",
"bytes": "<volatile>",
"frame": 543,
"pc": "0x0000b502",
"errorlog": "<volatile>"
}The second call's:
{
"summary": "state_write load: two-credits, rom_check OK, verified True, frame 543, pc 0x0000b502",
"status": "ok",
"name": "two-credits",
"path": "./tmp/demos/tour/gridlee-states/sta/gridlee/two-credits.sta",
"rom_check": "OK",
"verified": true,
"saved": {"frame": 543, "pc": "0x0000b502"},
"output": "State load attempted. Please refer to window message popup for results.",
"mark": "<volatile>",
"taps_across": [
{"ref": "film", "cpu": ":maincpu"}
],
"cause": "stateload two-credits",
"stop_seq": 28,
"pc": "0x0000b502",
"cpu": ":maincpu",
"frame": 543,
"regs": {
"A": "0x02",
"B": "0x70",
"D": "0x0270",
"X": "0xda5c",
"Y": "0x0101",
"U": "0xab79",
"PC": "0xb502",
"S": "0x07fc",
"CC": "0xa9",
"DP": "0x00"
},
"instruction": {
"address": "B502",
"bytes": "26F4",
"text": "BNE $B4F8",
"symbol": "write_sprites",
"delta": 3340
},
"following": ["B504: DC 86 LDD <$86", "B506: 8E DA 62 LDX #$DA62", "B509: 10 A3 81 CMPD ,X++", "B50C: 23 07 BLS $B515", "B50E: 0C 81 INC <$81", "B510: 8C DA 6A CMPX #$DA6A", "... 9 more"],
"errorlog": "<volatile>"
}The two methods
| method | what it does |
|---|---|
save |
Writes the machine to a new file. It never overwrites one. |
load |
Replaces the machine with a saved one. Every later reply then carries altered: this session has written to the machine. |
Arguments
- method one of
"save","load", required saveorload, as above.- name string, required
- The state's name, spelled as a file name is:
Boss_1becomesboss-1. At most 64 characters, with at least one letter or digit.
What comes back
- path
- The state's file:
<name>.stain the state folder. - frame
- The frame the machine is at. On
saveit is the frame the file holds, kept withpcto check a laterload. - verified
- On
load:truewhen the machine reads as it did at the save. Unavailable, saying why, when nothing could prove the load. - saved
- On
load: theframeandpcthe save recorded. Unavailable for a state this session did not save. - rom_check
- On
load:OKwhen the ROM still matches thereference_romgiven tostart. Unavailable when the session has none. - held
- Set when MAME held the save or load for a pending timer: one instruction was stepped to complete it, and this says where the machine stopped.
All 23 reply fields
bytes(integer)cpu(string)following(array of string)instruction(StopInstruction)differs(object)errorlog(object)frame(integer or object)held(string)mark(object)name(string)output(string)path(string)pc(string)regpoint_hit(object)regs(object)rom_check(string or object)saved(object)stop_seq(integer)system(string)taps_across(array)verified(boolean or object)watch_hit(object)watches(array)
What it refuses
- A machine that is running (
not_stopped). - A name with no letter or digit, or longer than 64 characters (
bad_argument). - A
saveunder a name that already has a file (bad_argument). - A
loadof a name with no state, or whose.stais no regular file (unknown_ref). - A
savethat leaves no file, a file that is not a MAME state, or a state of another machine, whichsystemnames (readback_refused). - A
loadafter which the ROM no longer matches, or the machine does not read as saved:differsgives thecpu, theregister, and itssavedandloadedvalues (readback_refused). - A save or load MAME still holds after one instruction: it would land inside the next run (
not_settled).
Why it works this way
MAME's console refuses a bad state in silence: a damaged file and another machine's state both come back as attempted, with nothing in the log. So the file's header is checked before the console sees it, and after a load the machine is compared with what the save recorded.
verified is true only when that comparison could tell a load from no load. For a state this session did not save, or a machine that already read as saved, it is unavailable and says why.
MAME can also hold a save or a load instead of running it, when a timer is pending on the stopped machine. Left alone it would run inside your next run, so the tool steps one instruction to complete it and says so in held.
More on why
Both methods use the debugger console's statesave and stateload, which work on a stopped machine. MAME is started with -statename %g, so the file is in sta/<system> whatever an ini file says.
A stopped machine gets a pending timer when a memory write runs a driver handler that synchronizes. On a MAME build that redraws the screen after a console command, a redraw that raises an input line does it too. Nothing can end the one step early: while a save or load is pending, MAME stops at no breakpoint or watchpoint.
A held save's frame, pc and registers are read after that step, so they are the file's, and stop_seq numbers the stop the step made.
MAME's emulated clock runs on across a load: it does not go back with the state.
A recording repeats from one saved state only on a driver whose game logic does not run while the screen is drawn. Logic run from the screen update depends on when the screen was last drawn, which a state does not hold, so load then record can give two different recordings. Compare such recordings against a tolerance.
mark is where each log ended as the load was sent, one position for emulator and one for process. log and log_wait take it as since_mark to read what came after. It is a position in the file, not a moment, so a line written before the load and not yet flushed lands after it.
A load is a stop of its own, with the readings every stop returns, described on the Run page. Its errorlog is the lines MAME's log gained (lines_total, truncated, lines, mark), not what the log tool reads. taps_across lists each count or capture that was running across the load, as reset does.
Related tools
The contract your client receives
Save or load a savestate `name`, kept as a file name is (`Boss_1` is `boss-1`, at most
64 characters), through the debugger console. `method`: `save` or `load`, the
only two it takes. Needs the machine stopped.
`save`: write it, never overwriting. Reply: `name`, `path`, `bytes`, `frame`, `pc`,
`errorlog`, `held`, `stop_seq` (held for a timer).
`load`: restore it, altering the session; the header, the ROM and the stop are checked first.
Reply: `name`, `path`, `rom_check`, `verified` (true, or INVALID `readback_refused` with
`differs`), `saved`, `output`, `mark`, `held`, `taps_across` (a tap was live), and the stop
survey (`cause`, `stop_seq`, `cpu`, `pc`, `regs`, `frame`, `instruction`, `following`,
`errorlog`, `watches`, `watch_hit`, `regpoint_hit`).
Refused: a name with no letter or digit; `load` of a `.sta` that is no regular file
(`unknown_ref`).
Reference: REFERENCE.md, Saved states.