SCRYMAMEReferenceSequencesperformAlso in DOSBox-X
perform
Run a list of this server's tools in one call, in order, stopping at the first step that fails.
perform(steps=null, path="", settle_seconds=30.0, summaries=false, until_frame=0)
Try it
scan of the first 2 KB open.Drop a second coin, let the game run two seconds, then keep only the scanned bytes that now hold 2.
perform(steps=[… 3 items], settle_seconds=…){
"summary": "perform: 3 steps completed",
"steps_completed": 3,
"failed_at": {"available": false, "why": "no step failed"},
"held": 0
}All three steps ran and none failed, so failed_at only says why it holds no number. held is 0 because no step carried recorded values to give again.
The whole reply
{
"summary": "perform: 3 steps completed",
"status": "ok",
"ran": [
{
"op": "input",
"cpu": ":maincpu",
"reply": {
"summary": "input :IN1 'Coin 1': held 4 frames, active True, released at frame 423",
"status": "ok",
"verdict": "ELAPSED",
"frame_before": 419,
"frame_after": 424,
"emulated_before_s": 7.096336,
"emulated_after_s": 7.180818,
"cycles": 105602,
"polls": 6,
"lines_ahead": 0,
"thread_errors": 0,
"console_reruns": 0,
"route": "ioport",
"port": ":IN1",
"field": "Coin 1",
"value": "0x00000001",
"frames": 4,
"name": "Coin 1",
"player": 0,
"mask": "0x00000001",
"defvalue": "0x00000001",
"port_before": "0x000000cf",
"frame_set": 419,
"released": true,
"port_held": "0x000000ce",
"frame_released": 423,
"active": true,
"cause": "the `gvblank` stop of the last frame asked",
"stop_seq": 7,
"pc": "0x0000fd80",
"cpu": ":maincpu",
"frame": 424,
"regs": {
"A": "0x00",
"B": "0x00",
"D": "0x0000",
"X": "0x0150",
"Y": "0x00e3",
"U": "0x00e5",
"PC": "0xfd80",
"S": "0x07f2",
"CC": "0x90",
"DP": "0x00"
},
"instruction": {"address": "FD80", "bytes": "0CB2", "text": "INC <$B2", "symbol": "irq", "delta": 0},
"following": ["FD82: 96 B2 LDA <$B2", "FD84: 84 03 ANDA #$03", "FD86: 26 04 BNE $FD8C", "FD88: 0C B3 INC <$B3", "FD8A: 0C B4 INC <$B4", "FD8C: B6 03 BE LDA $03BE", "... 9 more"],
"errorlog": "<volatile>",
"session": {
"alive": true,
"running": false,
"altered": false,
"omitted": ["altering_writes", "console"],
"how": "call `status`"
}
}
},
{
"op": "run_for",
"cpu": ":maincpu",
"reply": {
"summary": "run_for 2000 ms: ELAPSED, frame 424 to 543",
"status": "ok",
"verdict": "ELAPSED",
"frame_before": 424,
"frame_after": 543,
"emulated_before_s": 7.180818,
"emulated_after_s": 9.180819,
"cycles": 2500002,
"reads": "<volatile>",
"cause": "the console's `gtime` stop",
"stop_seq": 8,
"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>",
"session": {
"alive": true,
"running": false,
"altered": false,
"omitted": ["altering_writes", "console"],
"how": "call `status`"
}
}
},
{
"op": "scan",
"cpu": ":maincpu",
"reply": {
"summary": "scan filter: = 0x02, 11 left",
"status": "ok",
"operator": "=",
"value": "0x02",
"iterations": 1,
"closed": false,
"hits": [
{"addr": "0x00000084", "value": "0x02"},
{"addr": "0x000000da", "value": "0x02"},
{"addr": "0x000000ed", "value": "0x02"},
{"addr": "0x000000ef", "value": "0x02"},
{"addr": "0x000001b6", "value": "0x02"},
{"addr": "0x00000299", "value": "0x02"},
"... 5 more"
],
"hits_total": 11,
"truncated": false,
"cpu": ":maincpu",
"space": "program",
"session": {
"alive": true,
"running": false,
"altered": false,
"omitted": ["altering_writes", "console"],
"how": "call `status`"
}
}
}
],
"steps_completed": 3,
"failed_at": {"available": false, "why": "no step failed"},
"held": 0
}Arguments
- steps array of object, optional
- The list to run: each step is
{"op": <tool>, ...}with that tool's own arguments. Give this orpath, never both. - path string, default
"" - A saved step list to replay in place of
steps: a file under.scry/perform/or oneperform_exportwrote. Absolute, or starting with~. - settle_seconds number (>= 0, <= 600.0), default
30.0 - How long each wait for the program to stop may take, before a step that needs it stopped. 0 never waits; left out, 30 seconds.
- summaries boolean, default
false truecuts each step's reply but the last to a short row and writes the full replies to a file. Left out, every reply comes back whole.- until_frame integer, default
0 - A frame number: the list repeats until a stop reads that frame. Needs
summariesand arun_forstep; left at 0, the list runs once.
What comes back
- ran
- One row per step that ran: its
op, itsreplyand thecputhat reply names. Withsummariesa row adds itsstep, andran_pathandreplies_pathhold them all. - held
- How many steps carried
recorded, the values a replayed step must give again, and gave them. 0 when no step carried any. - failed_at
- The step that failed, counted from 0, with its
opandreplyinfailed. When none failed it isavailable: falsewith awhy. - errors
- Every step refused before anything ran, each with its
step,op,codeandmessage. - verdict
- Comes once the list waited for a stop:
TARGETwith the stop instopped, orTIMEOUTwith anote. A list that waited for none saysstill_running. - stops
- With
summaries, the server's own count of the stops:stop_seq_first,stop_seq_last,surveyed(how many a reply described),by_causeandunaccounted.
All 22 reply fields
errors(array)failed(object)field(string)got(any)ran_path(string or object)recorded(any)replies_path(string or object)steps_total(integer)still_running(boolean)stopped(object)stops(object)truncated(boolean)verdict(string)failed_at(integer or object)held(integer)ran(array)steps_completed(integer)frame_reached(integer or object)operations(array)until_frame(integer)visible_cpu(string or object)visible_cpu_kept(object)
What it refuses
- A step that names no tool, an argument its tool does not take or a value it refuses. Nothing runs, and
operationslists the tools a step may name (bad_argument). - A step's
cputhe machine does not have, or a bare hexrefthat names no symbol, also before anything runs (unknown_ref). - Both
stepsandpath, neither, or an empty list (bad_argument). - A step that answers INVALID: the list ends there (
step_failed). - A step whose reply differs from its
recordedvalues; the reply names thefield, therecordedvalue and what itgot(diverged). - A step that needs the program stopped while it still runs and
settle_secondsis 0 (not_stopped). until_framewithoutsummaries, without arun_forstep, or at a frame the program has already reached (bad_argument).until_frameon a machine with no screen device, which has no frame to count (no_channel).- A stop that reads no frame under
until_frame, since nothing then says whether the frame came (unexpected_answer). - The emulator gone before a step could run (
session_broken).
Why it works this way
The whole list is checked before its first step runs, so a refusal never arrives after earlier steps changed the machine. What only a running step can know refuses at that step: a symbol against the table loaded by then, a file an earlier step writes.
A step that needs the program stopped waits up to settle_seconds for the stop. A wait that runs out ends the list TIMEOUT: the steps after it were built on what it waited for. So does a step whose own wait missed, a log_wait or screen_wait that timed out.
A step may carry recorded, a {field: value} object of its own reply, and a reply with other values ends the list. That turns a list into a test, and perform_export writes such lists from a session.
More on why
until_frame counts what happens before a frame when nobody can know how many steps that takes. Every stop a watch makes takes a step without moving the frame, so a list sized by guessing ends short, with a smaller count that looks right.
The call ends right after the first step whose stop reads the frame, even mid-list, and frame_reached says which. It needs a run_for step because run_for carries on past a watch's stop, where run_to and step end at the first.
On a running program the first stop starts the count. Running out of steps or seconds is a TIMEOUT that names the last frame read.
Every pass compares each step with its recorded values again, so a stop recorded on the first pass diverges on the second. A document perform_export writes carries no until_frame.
With summaries, steps_total counts the rows and truncated says the reply shows fewer. Read stops for a count and ran_path for the whole table: a count made by hand from cut rows comes out wrong and looks right.
On a machine with several cpus the list leaves the visible cpu, the one the debugger shows, as it found it. At its end, failed or not, it puts back the cpu visible before the first step, or the one the last cpu_focus step chose, running nothing. Once the program runs, the next stop decides.
visible_cpu is that cpu after the list, and visible_cpu_kept tells how it was kept: before, asked, after, restored, moved_to, and a why when it was not put back.
Related tools
The contract your client receives
A sequence of this server's operations in one call, in order, stopping at the first
failure; `drive` is this plus a wait for a line of the emulator log.
`steps`: `{"op": <tool>, ...}`, any tool but `start`, `close`, `rom_check`, `perform`,
`drive`, `perform_export`, `window`, `promote`. `path`: a `perform` document (absolute or `~`-led:
`.scry/perform/<name>.json`, or a file `perform_export` wrote) whose steps are replayed; give
`steps` or `path`, never both.
`until_frame=F` needs `summaries=True` (a window is hundreds of steps) and a `run_for` step, and repeats the list until a stop reads frame F, within 5000 steps and 600 s; `no_channel` if there is no frame counter. A step's `recorded`, `{field: value}` of its own reply,
must hold, else INVALID `diverged`. A refused step: INVALID `errors`, nothing run.
`settle_seconds` bounds each wait for a stop before a step that needs one (0: never wait).
Reply: `ran`, `steps_completed`, `held`, `failed_at`, `failed` (INVALID `step_failed`),
`verdict` (once the list waited; `TARGET` adds `stopped`, `TIMEOUT` `note`), else
`still_running`; `frame_reached` (with `until_frame`).
Reference: REFERENCE.md, Several calls as one.
summaries: True (of the call, never of a step) makes each step but the last a compact row; `ran` shows the first 24 (`truncated`), `ran_path` and `replies_path` hold all; `stops` counts the stops.