SCRYDOSBox-XReferenceSequencesperform_exportAlso in MAME

DOSBox-XSequences

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

On Bricks, the game this repository builds, in a session that ran to the first brick hit, forced a register and stepped.
Ask

Save what we did in this session as a script that replays and checks it without you.

Call
perform_export(dest="./tmp/demos/tour/files/session.json")
Reply 6 of 10 fields
{
  "path": "./tmp/demos/tour/files/session.json",
  "steps": 15,
  "checks": 4,
  "dropped_total": 13,
  "cut": {"available": false, "why": "the recording kept every call a replay takes"},
  "kept": "2 saved for `promote`"
}

Fifteen calls replay, four of them as checks, and 13 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
JSON
{
  "summary": "perform_export: 15 steps, 4 checks, 13 dropped to ./tmp/demos/tour/files/session.json",
  "status": "ok",
  "path": "./tmp/demos/tour/files/session.json",
  "steps": 15,
  "checks": 4,
  "dropped": [
    {"call": 1, "op": "status", "why": "a read the export does not check"},
    {"call": 5, "op": "machine_map", "why": "it changes nothing in the emulated machine"},
    {"call": 7, "op": "symbols_find", "why": "a read the export does not check"},
    {"call": 8, "op": "interrupt_vectors", "why": "it changes nothing in the emulated machine"},
    {"call": 9, "op": "screen_view", "why": "it changes nothing in the emulated machine"},
    {"call": 10, "op": "palette", "why": "it changes nothing in the emulated machine"},
    "... 7 more"
  ],
  "dropped_total": 13,
  "cut": {"available": false, "why": "the recording kept every call a replay takes"},
  "replay": "uv run python -m scry_core.replay ./tmp/demos/tour/files/session.json",
  "kept": "2 saved for `promote`"
}

Arguments

dest string, required
The .json file to write: absolute, or starting with ~. Refused when it exists, unless overwrite.
overwrite boolean, default false
true replaces a dest that is already there. Left out, an existing file is refused.

What comes back

steps
How many calls the script replays; path is the file written.
checks
How many of them compare a reading with its recorded values, 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, op and why; dropped_total counts all.
cut
The call the script ends before, with its call, op and why. It is available: false when 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 recorded values again.
kept
Says the script was saved as a candidate for promote: it reads "N saved for promote", 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

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 regs 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 screen_wait that found its text becomes a run_for of as many frames as it polled, which a replay reaches. A send_keys or send_mouse to a stopped program is kept as a step: it runs frame by frame to a stop a replay reaches.

  • A debug command the script keeps is never checked against its answer, and a state_write(method="load") is checked against nothing either.
  • The file names what a replay needs: needs.states, the saved states it loads and does not save itself.
  • And needs.declarations: the breakpoints and watches saved when the recorded start began, so a replay under others says so before it plays.
The contract your client receives
Text
Write the session's calls since `start` to `dest` as a `perform` document.

Kept: moving calls and checks (`read_memory`, `registers`, `screen_signature`,
`screen_map_find`, `guest_file`, `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.
Tools