SCRYMAMEReferenceSequencesdriveAlso in DOSBox-X
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
Drop a coin and check the game counted it: wait for its coin counter line in the log.
drive(act=[… 2 items], expect=…){
"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
{
"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
performtakes:{"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
verifysayschecked: false. - seconds number (> 0, <= 600.0), optional
- How long to wait for the
expectline. Left out, 5 seconds; given withoutexpect, the call is refused. - pattern string, default
"." - A regular expression that picks which new log lines
lookedshows. It changes nothing in the check; left out, every line. - limit integer (>= 1, <= 400), default
40 - How many of those lines
lookedshows, the newest: 1 to 400. Left out, 40. - settle_seconds number (>= 0, <= 600.0), default
30.0 - As in
perform. Withexpect, the last step's stop is not waited for: waiting for the line is the wait. - summaries boolean, default
false - As in
perform:truecuts each step's reply but the last to a short row.
What comes back
- act
- What the steps did, in the fields of a
performreply:ran,steps_completed,failed_atand the rest. - verify
- The check:
checkedsays whether one ran andseenwhether the line came, with theline, theverdict(TARGETorTIMEOUT) andwaited_s. - looked
- Under
emulator, the newestlineswritten since the steps began that matchpattern, withlines_totalandtruncated.
All 4 reply fields
act(object)looked(object)operations(array)verify(object)
What it refuses
secondswithoutexpect, or an emptyact(bad_argument).- A bad step or argument in
act, before anything runs;operationslists the tools a step may name (bad_argument). - A step's
cputhe machine does not have, answered with itscpu_tags(unknown_ref). - A step that answers INVALID (
step_failed). - The program stopped at the debugger without the line: a stopped program logs nothing more, so waiting would not help (
wait_stopped). - A refusal of the steps themselves comes back with its own code, such as
not_stopped,session_brokenordiverged.
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.
Related tools
The contract your client receives
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.