SCRYDOSBox-XReferenceRunscreen_waitAlso in MAME
screen_wait
Run until the screen shows a text, 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="", seconds=30.0)
Try it
start, with the game's screen map loaded.Run until the game's play screen is up.
screen_wait(screen="play", seconds=60){
"summary": "screen_wait screen 'play': found after 2 frames",
"verdict": "TARGET",
"predicate": "screen",
"already": false,
"polls": 2,
"screen": {"name": "play", "layer": "file"}
}The map's play screen was not up at the call, which is already: false. It came up 2 frames later, and the machine stopped there.
The whole reply
{
"summary": "screen_wait screen 'play': found after 2 frames",
"status": "ok",
"verdict": "TARGET",
"predicate": "screen",
"already": false,
"waited_s": "<volatile>",
"polls": 2,
"sampled_every": 0,
"screen": {"name": "play", "layer": "file"},
"pc": "<volatile>",
"cpu_mode": "real",
"frame": 2,
"regs": "<volatile>",
"watches": [],
"cause": "<volatile>",
"e9": {
"lines_total": 2,
"truncated": false,
"lines": ["Bochs port E9h: STUB . scry device=present proto=7 motion=1", "Bochs port E9h: BRICKS ready"],
"mark": "<volatile>"
},
"stop_seq": 2,
"instruction": "<volatile>"
}Arguments
- text string, default
"" - Wait until this text is on the text screen: 1 to 132 characters of code page 437, matched exactly, case included, inside one row.
- 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: its
ref, asdeclaration_listlists it. - 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. - 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
text,screen,paletteorchangedwas waited on. - polls
- How many frames ran;
sampled_everyrepeatsevery. - point
- With
text: where it was found, as[column, row].lineis that row's whole text. - screen
- The screen found, as
nameandlayer. Withchanged,started_onis the screen it replaced.
All 29 reply fields
waited_on(object)firings(integer)frames_examined(integer)fired_line(integer or object)already(boolean)cause(string)regpoint_hit(object)cpu_mode(string)e9(object)enrichment(object)entries(integer)frame(integer or object)instruction(DosboxInstruction)line(string)palette(string)pc(string)point(array)polls(integer)predicate(string)regs(object)retrace_pending(boolean)sampled_every(integer)screen(object)started_on(string or object)stop_seq(integer)text(array)verdict(string)waited_s(number)watches(array)
What it refuses
- None or several of
text,screen,paletteandchanged(bad_argument). - 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
causecomes with it (wait_stopped). - A screen that cannot be read, or a DOSBox-X whose debugger has no
RUNSTATEcommand (no_channel). - A machine that is running (
not_stopped).
Why it works this way
The wait runs the machine one frame at a time, to each vertical retrace, and looks at the screen there. Each look costs a stop and a read, so for a screen that is far away use run_for first.
seconds is counted from after the first read so that a short one still reaches the first frame; a frame read under way when it passes is finished. A wait that gives up never leaves the machine running: a VRT still running is interrupted where it stands.
If what you wait for is already on screen the reply comes at once and the machine does not move. Under on_breakpoint or on_watch the first firing is awaited even so. With text, a frame that is not in a text mode is no match.
More on why
waited_onrepeats what was waited on: itskind, itsref, and theconditionif any.- Under
on_breakpointoron_watch,firingsandframes_examined(the frames looked at after a firing) replacepollsandsampled_every, in refusals too. fired_lineis unavailable here, with why: the debugger reports no screen line at a stop.paletteandentriescome with a black palette: the value asked for, and how many palette entries were read.- On a
TIMEOUT,textholds the rows of the last text screen read, andretrace_pendingsays whether a retrace stop is still armed. - A
noteon aTARGETmeans a watch or an interrupt breakpoint is set whose stop the wait could have taken for a retrace. - A refusal after the machine ran carries
pollsandstop_seq.wait_stoppedaddsretrace_pendingandtext. enrichmentcomes wherestop_seqwas due and the stop could not be read.
Related tools
The contract your client receives
Run the machine retrace by retrace until ONE predicate holds, and stop there.
Exactly one of: `text` (1 to 132 code page 437 characters, matched literally and
case-sensitive inside one row as `screen_view` reads it), `screen` (a name of the loaded
screen map, `screen_map_write`; the frame it names), `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). None or several is
`bad_argument`.
`on_breakpoint` / `on_watch`: judge only at the retrace after a firing of that declared
breakpoint or `change` watch (its `ref` as `declaration_list` lists it), 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. The first firing is awaited even
when the predicate already holds.
`every`: 0 judges every retrace; N judges every Nth, for a predicate whose read is a full
frame, and a screen that lasts fewer than N retraces is passed over. `seconds` bounds the
polls, counted from the opening read; the stop at the bound comes after it. Needs a stopped
machine and `RUNSTATE`. Already true: answered at once, the machine not moved. Each poll
costs a stop and a read, so `run_for` first for a distant screen.
Reply: `verdict` `TARGET` (`predicate`, `already`, `waited_s`, `polls`, `sampled_every`;
text adds `point` `[column, row]` and `line`, screen adds `screen`, palette adds `entries`) or
`TIMEOUT` (the same, with `retrace_pending`), `note`, the stop reply of `run_to` with its
`frame` (unless the predicate was already true); under `on_*`, `waited_on`, `firings`, `frames_examined` (the frames looked at after a firing) and `fired_line` in place of `polls` and `sampled_every`, and `changed` adds `screen` and
`started_on`. Refused: `bad_argument`,
`unknown_ref` (no such mapped screen or declared row), `needs_call` (`changed` with no map
loaded), `wait_stopped` (another declared breakpoint stopped it), `never_fired` (the row
never fired within `seconds`), `no_channel` (a screen it cannot read, or a build with no
`RUNSTATE`).
Reference: REFERENCE.md, Input and the screen.