SCRYMAMEReferenceRunscreen_waitAlso in DOSBox-X
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
Run until the level card is on screen.
screen_wait(screen="level_card", seconds=300){
"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
{
"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_writeand wait onscreen. - 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"" blackwaits until every palette entry is black, which is how a fade ends.- changed boolean, default
false truewaits 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
refof astopbreakpoint you set. - on_watch string, default
"" - The same for a watch: the
refof achangewatch 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_breakpointandon_watchname. 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
TARGETwhen what you waited for is on screen.TIMEOUTwhen the wait gave up, with anoteand the machine stopped.- already
truewhen it was on screen at the call, so the machine did not move.- predicate
- Which of
screen,paletteorchangedwas waited on. - polls
- How many frames ran, also given as
frames;sampled_everyrepeatsevery. - screen
- The screen found, as
nameandlayer. Withchanged,started_onis the screen it replaced. - firings
- With
on_breakpointoron_watch: how many times it fired.frames_examinedcounts 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
- None or several of
screen,paletteandchanged(bad_argument). text, or a palette that cannot be read at a stop (no_channel).- A screen the map does not name, or a breakpoint or watch you did not set (
unknown_ref). changedwith no screen map loaded (needs_call).- A breakpoint or watch that never fired within
seconds: no screen was looked at (never_fired). - A stop nobody asked for that ends the wait early; its
causeand the stop's readings come with it (wait_stopped).
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_onrepeats what was waited on: itskind, itsref, and theconditionif any.fired_lineis the screen line being drawn at the firing that counted, or unavailable when no firing met thecondition.paletteandentriescome with a black palette: the value asked for, and how many palette entries were read.- Under
on_breakpointoron_watch, these fields replacepollsandsampled_every.
Related tools
The contract your client receives
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.