SCRYMAMEReferenceSequencesperform_exportAlso in DOSBox-X
perform_export
Write the session's calls since start as a script that replays them and checks their answers, with no model.
perform_export(dest, overwrite=false)
Try it
Save what we did in this session as a script that replays and checks it without you.
perform_export(dest="./tmp/demos/tour/two-coins.json"){
"path": "./tmp/demos/tour/two-coins.json",
"steps": 9,
"checks": 3,
"dropped_total": 14,
"cut": {"available": false, "why": "the recording kept every call a replay takes"},
"kept": "2 saved for `promote`; perform/two-coins, start/gridlee: not ... (185 characters)"
}Nine calls replay, three of them as checks, and 14 calls were left out. cut is unavailable because nothing ended the script early; kept says the script is now a candidate for promote.
The whole reply
{
"summary": "perform_export: 9 steps, 3 checks, 14 dropped to ./tmp/demos/tour/two-coins.json",
"status": "ok",
"path": "./tmp/demos/tour/two-coins.json",
"steps": 9,
"checks": 3,
"dropped": [
{"call": 1, "op": "status", "why": "a read the export does not check"},
{"call": 2, "op": "machine_map", "why": "it changes nothing in the emulated machine"},
{"call": 3, "op": "cpu_info", "why": "a read the export does not check"},
{"call": 4, "op": "symbols_find", "why": "a read the export does not check"},
{"call": 6, "op": "disassemble", "why": "a read the export does not check"},
{"call": 7, "op": "find", "why": "a read the export does not check"},
"... 8 more"
],
"dropped_total": 14,
"cut": {"available": false, "why": "the recording kept every call a replay takes"},
"replay": "uv run python -m scry_core.replay ./tmp/demos/tour/two-coins.json",
"kept": "2 saved for `promote`; perform/two-coins, start/gridlee: nothing this session read names its repository: promote(dry_run=true, root=<the repository>) lists what an approval would create"
}Arguments
- dest string, required
- The
.jsonfile to write, required: absolute, or starting with~. Refused when it exists, unlessoverwrite. - overwrite boolean, default
false truereplaces adestthat is already there. Left out, an existing file is refused.
What comes back
- steps
- How many calls the script replays;
pathis the file written. - checks
- How many of them compare a reading with its
recordedvalues, the answer the session got. - dropped
- The last 40 calls left out (reads the script does not check, refused calls, calls that change nothing), each with its
call,opandwhy;dropped_totalcounts all. - cut
- The call the script ends before, with its
call,opandwhy. It isavailable: falsewhen every call a replay can run was kept. - replay
- The command that replays the script, run from this server's repository. It exits 0 when every step gave its
recordedvalues again. - kept
- Says the script was saved as a candidate for
promote: it reads "N saved forpromote", and names a repository that has no.scry/folder yet.
All 8 reply fields
checks(integer)cut(object)dropped(array)dropped_total(integer)path(string)replay(string)steps(integer)kept(string)
What it refuses
- A
destthat does not end in.json, is a directory, or exists withoutoverwrite(bad_argument). - No
startthat succeeded, one that was cancelled, or no call left that a replay could run (no_recording).
Why it works this way
The script keeps the calls that move the program and a few readings as checks, each with the answer it got as recorded. A call that left the program at a new stop is checked on that stop's pc and frame.
The script ends at the first call no replay can reach. A resume, or a run that the clock or a stop ended, stops the cpu at a point inside its frame that no replayed run reaches. Every later stop would inherit the shift.
So move with run_for, run_to and step, which stop at the same point on every run, and keep resume for the end. Leave the dest of a step that writes a file empty: a file the session named is still there on replay, and the step is refused.
More on why
When the frames are known, cut says how many the run took, and a run_for of that many replays it up to that frame's start. The script also ends at a call with no reply, a refusal after the program moved, and a program found elsewhere than the call before left it.
A debug line is replayed and its printed answer never checked; one that moved the program is checked on its stop. An image_compare(method="golden") over files that dropped calls wrote is dropped too.
A reader that steps the program to read is kept as a step. How far a Lua reader steps follows the host's clock, so on a rare run it lands elsewhere and the replay says so at that step.
The script carries start's arguments as given, host paths included; the replay's --binary and --rompath replace them. needs.states lists the saved states it loads and does not save, checked before anything plays. needs.declarations lists the breakpoints, watches and registerpoints saved when the recorded start began, which a replay must find again.
Related tools
The contract your client receives
Write the session's calls since `start` to `dest` as a `perform` document.
Kept: moving calls and checks (`read_memory`, `read_block`, `registers`,
`screen_signature`, `screen_map_find`, `image_compare(method="golden")`), each held to its
`recorded` reply. Other calls drop; the first no replay can place, or past 5000, cuts
the rest.
`dest` (`.json`) is refused if present unless `overwrite`. Reply: `path`, `steps`,
`checks`, `dropped`, `dropped_total`, `cut`, `replay`, and `kept` when the document is kept
for `promote`; `no_recording` if empty.
Reference: REFERENCE.md, From a session to a test that replays itself.