SCRYMAMEReferenceRunrun_forAlso in DOSBox-X

MAMERun

run_for

Run for a number of frames or milliseconds of emulated time and come back stopped.

run_for(milliseconds=0, frames=0, seconds=30.0, disarm_watches=false)

Try it

On Gridlee, a free ROM from mamedev.org, right after start.
Ask

Let the game run for five seconds of its own time, then stop.

Call
run_for(milliseconds=5000, seconds=300)
Reply 6 of 18 fields
{
  "summary": "run_for 5000 ms: ELAPSED, frame 0 to 295",
  "verdict": "ELAPSED",
  "frame_before": 0,
  "frame_after": 295,
  "emulated_after_s": 5.000003,
  "cycles": 6250000
}

ELAPSED says the five seconds ran out as asked. The frame counter went from 0 to 295, the emulated clock reads a little over 5 seconds, and the cpu spent 6250000 cycles.

The whole reply
JSON
{
  "summary": "run_for 5000 ms: ELAPSED, frame 0 to 295",
  "status": "ok",
  "verdict": "ELAPSED",
  "frame_before": 0,
  "frame_after": 295,
  "emulated_before_s": 3e-06,
  "emulated_after_s": 5.000003,
  "cycles": 6250000,
  "reads": "<volatile>",
  "cause": "the console's `gtime` stop",
  "stop_seq": 2,
  "pc": "0x0000a631",
  "cpu": ":maincpu",
  "frame": 295,
  "regs": {
    "A": "0x0a",
    "B": "0x4b",
    "D": "0x0a4b",
    "X": "0xc901",
    "Y": "0xf2e6",
    "U": "0xbef1",
    "PC": "0xa631",
    "S": "0x0800",
    "CC": "0xc4",
    "DP": "0x00"
  },
  "instruction": {"address": "A631", "bytes": "04B4", "text": "LSR    <$B4", "symbol": "wait_frame", "delta": 0},
  "following": ["A633: 24 FC    BCC    $A631", "A635: B7 93 80 STA    $9380", "A638: B6 97 00 LDA    $9700", "A63B: 43       COMA", "A63C: 85 20    BITA   #$20", "A63E: 27 03    BEQ    $A643", "... 7 more"],
  "errorlog": "<volatile>"
}

Arguments

milliseconds integer, default 0
How much emulated time to run, in milliseconds. Give this or frames, never both.
frames integer, default 0
How many frames to run, counted on MAME's frame counter. Give this or milliseconds, never both.
seconds number (> 0, <= 600.0), default 30.0
How long to wait for the run to end, in real seconds. Left out, 30.
disarm_watches boolean, default false
true takes your watches off for this run, so none of them stops it, and sets them again at the end.

What comes back

verdict
How the run ended: ELAPSED, the frames or time asked for ran out, as asked; TIMEOUT, the wait gave up; OTHER_STOP, a breakpoint or a watch stopped it first.
frame_after
The frame counter after the run; frame_before is the one before. Unavailable, with why, on a board with no frame counter.
emulated_after_s
The emulated clock after the run, in seconds; emulated_before_s is the one before.
cycles
The cpu cycles the run took, for what was asked and nothing else. Unavailable, with why, when they cannot be counted.
polls
By frames: how many single-frame runs were sent. One more than frames means the run began in the middle of a frame.
reads
By milliseconds: how many times the counter was read until it stood still.
All 23 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)
  • disarmed_watches (array)
  • not_rearmed (array)

What it refuses

Why it works this way

A run by frames counts MAME's frame counter itself, so a capture can be taken again at the same frame; N milliseconds is not N frames. A run is ELAPSED only once several readings spaced apart agree the machine has stopped: one handed back still running is the worst state for a session.

By frames the run goes through the first cpu: MAME keeps "a vblank happened", the end of a frame's drawing, as one flag. The first cpu to run after it consumes the flag, so only that cpu stops there. note says when that cpu had to be made visible.

cycles spans what was asked for. A run that starts in the middle of a frame first spends one single-frame run reaching the vblank it is inside. That one moves no counter, and polls is how it shows.

More on why

cycles is unavailable on the first run after a load, a rewind or a reset typed through debug. MAME's debugger refreshes its cycle counter only when the cpu executes, so the span would be off by the distance between the two states. It is also unavailable when the run was counted on one cpu and stopped on another.

A board with no screen device has no frame counter and is run by milliseconds. MAME registers frame on a machine with one screen device and frame0, frame1 and so on with several, where the first one is used. start asks MAME and reports the name as frame_symbol.

A vector board has a display and no screen device, so the screens machine_map lists are no guide. There a stop's frame is unavailable and the emulated clock confirms the stop. An expression MAME's console refuses there is no_channel: an answer about the machine, not a broken session.

  • A MAME without one debugger thread per cpu cannot change the visible cpu without running, so it refuses frames while another cpu is visible.
  • no_progress by frames leaves the machine running until stop and carries no stop readings. By milliseconds it carries them.
  • After not_settled, call stop. If stop fails as well, close then start.
  • The call reports progress to the client while it waits.
  • A run started while a registerpoint's condition still holds stops one instruction later as OTHER_STOP, never no_progress.
  • A single-frame run MAME refused, or whose landing was not read, may still have been taken: the session is marked running and the call is not_settled.
The contract your client receives
Text
Run for `milliseconds` of emulated time or `frames` of the frame counter (exactly one) and
wait until STOPPED. `disarm_watches=true` disarms the watches for this pass, so none of them cuts it. Needs the machine STOPPED (else `not_stopped`).

Reply: `verdict` (`ELAPSED`, `TIMEOUT`, `OTHER_STOP`; a control never cuts), `frame_before`,
`frame_after`, `emulated_before_s`, `emulated_after_s`, `cycles` (each unavailable with
why), `polls` (by frames) or `reads` (by milliseconds), and the stop survey of `run_to`.
INVALID has no `verdict`: `no_progress`, `frames_went_backwards`, `not_settled`,
`session_broken`; `no_channel` on a board with no counter.

Reference: REFERENCE.md, Running and stopping.
Tools