SCRYMAMEReferenceRunrun_forAlso in DOSBox-X
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
start.Let the game run for five seconds of its own time, then stop.
run_for(milliseconds=5000, seconds=300){
"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
{
"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 truetakes 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_beforeis 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_sis 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
framesmeans 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
- Both
millisecondsandframes, or neither (bad_argument). frameson a board with no frame counter: run it bymilliseconds(no_channel).- A run during which the counter did not move (
no_progress). - A counter that went backwards: something put the machine back during the run (
frames_went_backwards). - A counter or a clock still moving at the time limit: the machine may still be running, so call
stop(not_settled). - A machine that is running (
not_stopped).
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
frameswhile another cpu is visible. no_progressby frames leaves the machine running untilstopand carries no stop readings. By milliseconds it carries them.- After
not_settled, callstop. Ifstopfails as well,closethenstart. - 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, neverno_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.
Related tools
The contract your client receives
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.