SCRYMAMEReferenceSequencesperformAlso in DOSBox-X

MAMESequences

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

On Gridlee, a free ROM from mamedev.org, stopped with one coin in and a scan of the first 2 KB open.
Ask

Drop a second coin, let the game run two seconds, then keep only the scanned bytes that now hold 2.

Call
perform(steps=[… 3 items], settle_seconds=…)
Reply 4 of 6 fields
{
  "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
JSON
{
  "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 or path, never both.
path string, default ""
A saved step list to replay in place of steps: a file under .scry/perform/ or one perform_export wrote. 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
true cuts 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 summaries and a run_for step; left at 0, the list runs once.

What comes back

ran
One row per step that ran: its op, its reply and the cpu that reply names. With summaries a row adds its step, and ran_path and replies_path hold 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 op and reply in failed. When none failed it is available: false with a why.
errors
Every step refused before anything ran, each with its step, op, code and message.
verdict
Comes once the list waited for a stop: TARGET with the stop in stopped, or TIMEOUT with a note. A list that waited for none says still_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_cause and unaccounted.
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

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.

The contract your client receives
Text
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.
Tools