SCRYMAMEReferenceRunscreen_waitAlso in DOSBox-X

MAMERun

screen_wait

Run until the screen shows a mapped screen, a black palette or a change of screen, and stop there.

screen_wait(text="", screen="", palette="", changed=false, every=0, on_breakpoint="", on_watch="", condition="", cpu="", seconds=30.0)

Try it

On Gridlee, a free ROM from mamedev.org, with a screen map that names its level card, stopped right after START is pressed with two credits.
Ask

Run until the level card is on screen.

Call
screen_wait(screen="level_card", seconds=300)
Reply 6 of 24 fields
{
  "summary": "screen_wait screen 'level_card': found after 13 frames",
  "verdict": "TARGET",
  "predicate": "screen",
  "already": false,
  "polls": 13,
  "screen": {"name": "level_card", "layer": "session"}
}

The map's level_card screen was not up at the call, which is already: false. It came up 13 frames later, and the machine stopped there.

The whole reply
JSON
{
  "summary": "screen_wait screen 'level_card': found after 13 frames",
  "status": "ok",
  "verdict": "TARGET",
  "frame_before": 560,
  "frame_after": 561,
  "emulated_before_s": 9.478676,
  "emulated_after_s": 9.495568,
  "cycles": 21115,
  "polls": 13,
  "cause": "the `gvblank` stop of the last frame asked",
  "stop_seq": 55,
  "pc": "0x0000fd80",
  "cpu": ":maincpu",
  "frame": 561,
  "regs": {
    "A": "0x01",
    "B": "0x1d",
    "D": "0x011d",
    "X": "0x0014",
    "Y": "0xf2e6",
    "U": "0x4071",
    "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>",
  "predicate": "screen",
  "already": false,
  "sampled_every": 0,
  "frames": 13,
  "waited_s": "<volatile>",
  "screen": {"name": "level_card", "layer": "session"}
}

Arguments

text string, default ""
Not available here: MAME gives the screen as pixels, so waiting for text is refused. Map the screen with screen_map_write and wait on screen.
screen string, default ""
Wait until this screen of the loaded screen map, the file naming a program's screens, is the one shown.
palette one of "", "black", default ""
black waits until every palette entry is black, which is how a fade ends.
changed boolean, default false
true waits until the screen map names a different screen from the one it named at the start. A frame it cannot name counts as in between.
every integer (>= 0, <= 600), default 0
How many frames to run between two looks at the screen. Left at 0, every frame; a screen shown for fewer frames than this can be missed.
on_breakpoint string, default ""
Look at the screen only at the end of a frame in which this breakpoint fired: the ref of a stop breakpoint you set.
on_watch string, default ""
The same for a watch: the ref of a change watch you set.
condition string, default ""
Counts only the firings where this holds. Up to four terms joined by &&, each a register or a memory read (b@ref, w@ref, d@ref) compared with a hex value.
cpu string, default ""
The cpu whose breakpoint or watch on_breakpoint and on_watch name. Left empty, the visible one.
seconds number (> 0, <= 600.0), default 30.0
How long to keep looking, in real seconds, counted from the first look. Left out, 30.

What comes back

verdict
TARGET when what you waited for is on screen. TIMEOUT when the wait gave up, with a note and the machine stopped.
already
true when it was on screen at the call, so the machine did not move.
predicate
Which of screen, palette or changed was waited on.
polls
How many frames ran, also given as frames; sampled_every repeats every.
screen
The screen found, as name and layer. With changed, started_on is the screen it replaced.
firings
With on_breakpoint or on_watch: how many times it fired. frames_examined counts the frames looked at after a firing.
All 34 reply fields
  • command_chars (integer)
  • cpu (string or object)
  • cycles (integer or object)
  • following (array of string)
  • instruction (StopInstruction)
  • emulated_after_s (number or object)
  • emulated_before_s (number or object)
  • errorlog (object)
  • frame (integer or object)
  • frame_after (integer or object)
  • frame_before (integer or object)
  • limit_chars (integer)
  • pc (string)
  • polls (integer)
  • reads (integer)
  • regpoint_hit (object)
  • regs (object)
  • stop_seq (integer)
  • verdict (string)
  • watch_hit (object)
  • watches (array)
  • waited_on (object)
  • firings (integer)
  • frames_examined (integer)
  • fired_line (integer or object)
  • already (boolean)
  • entries (integer)
  • frames (integer)
  • palette (string)
  • predicate (string)
  • sampled_every (integer)
  • screen (object)
  • started_on (string or object)
  • waited_s (number)

What it refuses

Why it works this way

The server looks at the screen itself, at a stop at the end of a frame. MAME's own frame notifier is not used: it reads the screen a frame late and sometimes in the middle of a draw.

Without on_breakpoint or on_watch the wait looks every frame, or every every frames, which is how a screen that is slow to read is waited on in reasonable time. With one, MAME counts the firings and stops only at a picture this wait has not yet rejected.

A wait that gives up never leaves the machine running: the last run is stopped first. If the screen is already there the reply comes at once, except under on_breakpoint or on_watch, where the first firing is awaited even so.

More on why
  • waited_on repeats what was waited on: its kind, its ref, and the condition if any.
  • fired_line is the screen line being drawn at the firing that counted, or unavailable when no firing met the condition.
  • palette and entries come with a black palette: the value asked for, and how many palette entries were read.
  • Under on_breakpoint or on_watch, these fields replace polls and sampled_every.
The contract your client receives
Text
Run the machine until ONE predicate holds, and stop there.

`screen`: the loaded map's screen is on the frame (`screen_map_write`; enters it). `palette`
(`black`: every DAC entry black, which is how a fade ends). `changed`: the map names a
screen other than the one it named at the start; a frame it names nothing is a transition.
Exactly one, or `bad_argument`; `text` is refused `no_channel`, because this server hands
the screen as pixels and a text mode's characters are DOSBox-X's to read.

`on_breakpoint` / `on_watch`: judge only at the frame's end after a firing of that declared
`stop` breakpoint or `change` watch (its `ref`, on `cpu`), never sampling; `condition`
(up to 4 terms joined by `&&`, each a register of the stopped cpu or a memory read (`b@ref`, `w@ref`, `d@ref`), a comparison (`==`, `!=`, `<`, `<=`, `>`, `>=`) and a hex value (`0x` allowed)) filters the firings first. MAME's Lua counts the firings and stops
only on a picture this wait has not rejected; the first firing is awaited even when the
predicate already holds.

`every`: 0 judges every frame; N runs N frames per poll, which is how a screen whose read
costs a console round trip is waited on in reasonable time, and a screen alive for fewer
than N is passed over. `seconds` bounds the polls, counted from the opening judge; the
recovery stop comes after it. Needs a stopped machine. Already true: answered at once, the
machine not moved. The emulator's own frame notifier is not used: it reads the screen a
frame late and sometimes mid-draw, so the judge is the server's at the stop.

Reply: `verdict` `TARGET` (`predicate`, `already`, `waited_s`, `polls`, `sampled_every`;
screen adds `screen`, palette adds `entries`, `changed` adds `screen` and `started_on`) or
`TIMEOUT` (the same, with `note` and the stop survey of `run_for`), the stop's own fields;
under `on_*`, `waited_on`, `firings`, `frames_examined` (the frames looked at after a firing) and `fired_line` in place of `polls` and `sampled_every`. A poll the bound itself cut is
stopped there first, so the machine is never left running under a wait that gave up.
Refused: `bad_argument`, `unknown_ref` (no such mapped screen or declared row), `needs_call`
(`changed` with no map loaded), `no_channel`, `never_fired` (the row never fired within
`seconds`), and `wait_stopped` when a stop nobody asked for ends the wait before the bound
(its `cause` and the stop's fields ride beside it).

Reference: REFERENCE.md, Input and the screen.
Tools