SCRYMAMEReferenceSequencesdriveAlso in DOSBox-X

MAMESequences

drive

Send an input as a list of steps, then check the program reacted by waiting for a new line in the log.

drive(act, expect="", seconds=null, pattern=".", limit=40, settle_seconds=30.0, summaries=false)

Try it

On Gridlee, a free ROM from mamedev.org, stopped in its attract mode five seconds after power-on.
Ask

Drop a coin and check the game counted it: wait for its coin counter line in the log.

Call
drive(act=[… 2 items], expect=…)
Reply 2 of 5 fields
{
  "summary": "drive: reaction seen",
  "status": "ok"
}

The summary says a new log line matched expect after the coin went in. The line itself is under verify in the whole reply, with the lines looked kept.

The whole reply
JSON
{
  "summary": "drive: reaction seen",
  "status": "ok",
  "act": {
    "ran": [
      {
        "op": "input",
        "cpu": ":maincpu",
        "reply": {
          "summary": "input :IN1 'Coin 1': held 4 frames, active True, released at frame 299",
          "status": "ok",
          "verdict": "ELAPSED",
          "frame_before": 295,
          "frame_after": 300,
          "emulated_before_s": 5.001233,
          "emulated_after_s": 5.085713,
          "cycles": 105600,
          "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": 295,
          "released": true,
          "port_held": "0x000000ce",
          "frame_released": 299,
          "active": true,
          "cause": "the `gvblank` stop of the last frame asked",
          "stop_seq": 4,
          "pc": "0x0000fd80",
          "cpu": ":maincpu",
          "frame": 300,
          "regs": {
            "A": "0x00",
            "B": "0xfe",
            "D": "0x00fe",
            "X": "0x02db",
            "Y": "0xf2e6",
            "U": "0xbef1",
            "PC": "0xfd80",
            "S": "0x07f4",
            "CC": "0xd4",
            "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 300 to 419",
          "status": "ok",
          "verdict": "ELAPSED",
          "frame_before": 300,
          "frame_after": 419,
          "emulated_before_s": 5.085713,
          "emulated_after_s": 7.085713,
          "cycles": 2500000,
          "reads": "<volatile>",
          "cause": "the console's `gtime` stop",
          "stop_seq": 5,
          "pc": "0x0000a7d5",
          "cpu": ":maincpu",
          "frame": 419,
          "regs": {
            "A": "0x00",
            "B": "0x00",
            "D": "0x0000",
            "X": "0x0150",
            "Y": "0x00e1",
            "U": "0x00e3",
            "PC": "0xa7d5",
            "S": "0x07fe",
            "CC": "0x84",
            "DP": "0x00"
          },
          "instruction": {"address": "A7D5", "bytes": "2406", "text": "BCC    $A7DD", "symbol": "wait_frame", "delta": 420},
          "following": ["A7D7: EC A4    LDD    ,Y", "A7D9: AF A4    STX    ,Y", "A7DB: ED C4    STD    ,U", "A7DD: 33 A4    LEAU   ,Y", "A7DF: 31 3E    LEAY   -$2,Y", "A7E1: 11 93 80 CMPU   <$80", "... 8 more"],
          "errorlog": "<volatile>",
          "session": {
            "alive": true,
            "running": false,
            "altered": false,
            "omitted": ["altering_writes", "console"],
            "how": "call `status`"
          }
        }
      }
    ],
    "steps_completed": 2,
    "failed_at": {"available": false, "why": "no step failed"},
    "held": 0
  },
  "verify": {
    "checked": true,
    "seen": true,
    "verdict": "TARGET",
    "expected": "coin counter on",
    "line": "[:] coin counter on",
    "lines_before": 4,
    "lines_total": 1,
    "waited_s": "<volatile>"
  },
  "looked": {
    "emulator": {
      "available": true,
      "since_mark": "<volatile>",
      "lines_written": 13,
      "lines_total": 11,
      "truncated": false,
      "lines": ["[luaengine] MAME_MCP_INPUT#3 set name=\"Coin 1\" player=0 mask=00000001 defvalue=00000001 port_before=000000cf frame=295", "[luaengine] MAME_MCP_INPUT#3 release frame=299 port_held=000000ce", "[:] coin counter on", "[:maincpu] ':maincpu' (FE4A): unmapped program memory read from 9020 & FF", "[:] coin counter off", "[:maincpu] ':maincpu' (A685): unmapped program memory read from 9010 & FF", "... 5 more"],
      "pattern": "."
    }
  }
}

Arguments

act array of object, required
The steps to run, in the shape perform takes: {"op": <tool>, ...}. Required, and never empty.
expect string, default ""
A regular expression: the log line that shows the program reacted, waited for after the steps. Left out, nothing is checked and verify says checked: false.
seconds number (> 0, <= 600.0), optional
How long to wait for the expect line. Left out, 5 seconds; given without expect, the call is refused.
pattern string, default "."
A regular expression that picks which new log lines looked shows. It changes nothing in the check; left out, every line.
limit integer (>= 1, <= 400), default 40
How many of those lines looked shows, the newest: 1 to 400. Left out, 40.
settle_seconds number (>= 0, <= 600.0), default 30.0
As in perform. With expect, the last step's stop is not waited for: waiting for the line is the wait.
summaries boolean, default false
As in perform: true cuts each step's reply but the last to a short row.

What comes back

act
What the steps did, in the fields of a perform reply: ran, steps_completed, failed_at and the rest.
verify
The check: checked says whether one ran and seen whether the line came, with the line, the verdict (TARGET or TIMEOUT) and waited_s.
looked
Under emulator, the newest lines written since the steps began that match pattern, with lines_total and truncated.
All 4 reply fields
  • act (object)
  • looked (object)
  • operations (array)
  • verify (object)

What it refuses

Why it works this way

The log is marked once, before the first step, so a line written before the input is never taken for a reaction.

An arcade board has no debug port to write to, so the line is looked for in the emulator log: what MAME's driver and this server's scripts write with logerror. A driver that logs a lot fills it fast, so keep pattern narrow.

The reply holds no picture of the screen: snapshot takes one, and screen_signature gives a number for it. With no line to wait for, perform is the call to make.

More on why

verify also carries expected, lines_before and lines_total, and a why when no line came or nothing was checked. If the steps ran out their own wait, nothing is checked and it says available: false. looked.emulator adds lines_written, since_mark and pattern; act adds, with summaries, steps_total, truncated, ran_path, replies_path and stops.

The contract your client receives
Text
A sequence that also waits for a line of the emulator log: marks the log, runs `act`
(steps as in `perform`), then checks the log since the mark. With no line to wait for,
`perform` is the call.

`expect` (regex) waits up to `seconds` (default 5, at most 600)
for a matching line, only while the machine runs; `seconds` without `expect` is refused.
`settle_seconds` bounds each wait for a stop before a step that needs one (0: never wait).
`looked.emulator` is the last `limit` (1..400) lines matching `pattern`. A failed
step is INVALID `step_failed`; a stopped machine lacking the line, `wait_stopped`; a bad
`act` step or argument, `bad_argument` before anything ran. With no `expect`, `verify`
is `checked: false`.

Reply: `act`, `verify` (`checked`, `seen`, `verdict` `TARGET` or `TIMEOUT`, `line`,
`waited_s`), `looked` (`emulator`).

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