SCRYDOSBox-XReferenceRunwait

DOSBox-XRun

wait

Let a running program play for a while and see where it is after, without stopping it.

wait(seconds=30.0)

Try it

On Bricks, the game this repository builds, running after a resume.
Ask

Let the game play for one more second without stopping it.

Call
wait(seconds=1)
Reply 2 of 4 fields
{
  "status": "ok",
  "note": "the machine is still running after 1 s; a deliberate wait th ... (100 characters)"
}

The second ran out with the game still running. That is the answer a wait is for, so status is ok.

The whole reply
JSON
{
  "summary": "<volatile>",
  "status": "ok",
  "waited_s": "<volatile>",
  "note": "the machine is still running after 1 s; a deliberate wait that expires is this answer, not a failure"
}

Arguments

seconds number (> 0, <= 600.0), default 30.0
How long to let it run, in real seconds. Left out, 30.

What comes back

waited_s
How long the call waited.
verdict
Only when the machine stopped during the wait: OTHER_STOP, a breakpoint or a watch stopped it, and the stop's readings follow.
All 13 reply fields
  • cause (string)
  • regpoint_hit (object)
  • cpu_mode (string or object)
  • e9 (object)
  • enrichment (object)
  • frame (integer or object)
  • instruction (DosboxInstruction)
  • pc (string or object)
  • regs (object)
  • stop_seq (integer)
  • verdict (string)
  • waited_s (number)
  • watches (array)

What it refuses

Why it works this way

The wait is deliberate, so running out of seconds is the answer and not a failure: the reply is ok, with a note that the machine is still running. wait neither resumes nor stops. resume lets a stopped machine run, and stop brings a running one back.

The contract your client receives
Text
Let a running guest play for `seconds` and answer where it is after, without releasing or
stopping it. The wait is deliberate, so its expiry is the answer, never a failure; if the
machine stops on its own during the wait (a breakpoint), the stop reply comes back.

Reply: `waited_s`, and with a stop during the wait `verdict` `OTHER_STOP` with the stop reply
of `run_to`; else a `note` that the machine is still running. Refused (`not_running`) when the
machine is stopped: `wait` lets a running guest play, `resume` releases a stopped one.

Reference: REFERENCE.md, Running and stopping.
Tools