SCRYDOSBox-XReferenceRunscreen_waitAlso in MAME

DOSBox-XRun

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

On Bricks, the game this repository builds, right after start, with the game's screen map loaded.
Ask

Run until the game's play screen is up.

Call
screen_wait(screen="play", seconds=60)
Reply 6 of 18 fields
{
  "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
JSON
{
  "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 ""
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: its ref, as declaration_list lists it.
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.
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 text, screen, palette or changed was waited on.
polls
How many frames ran; sampled_every repeats every.
point
With text: where it was found, as [column, row]. line is that row's whole text.
screen
The screen found, as name and layer. With changed, started_on is 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

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_on repeats what was waited on: its kind, its ref, and the condition if any.
  • Under on_breakpoint or on_watch, firings and frames_examined (the frames looked at after a firing) replace polls and sampled_every, in refusals too.
  • fired_line is unavailable here, with why: the debugger reports no screen line at a stop.
  • palette and entries come with a black palette: the value asked for, and how many palette entries were read.
  • On a TIMEOUT, text holds the rows of the last text screen read, and retrace_pending says whether a retrace stop is still armed.
  • A note on a TARGET means 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 polls and stop_seq. wait_stopped adds retrace_pending and text.
  • enrichment comes where stop_seq was due and the stop could not be read.
The contract your client receives
Text
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.
Tools