SCRYMAMEReferenceRunstopAlso in DOSBox-X

MAMERun

stop

Stop a running machine where it is and read where it stopped.

stop()

Try it

On Gridlee, a free ROM from mamedev.org, running after a resume.
Ask

Stop the game where it is.

Call
stop()
Reply 4 of 13 fields
{
  "interrupted": true,
  "cause": "interrupt",
  "stop_seq": 62,
  "cpu": ":maincpu"
}

interrupted: true means this call stopped the machine. It is the session's stop number 62, on the main cpu; where it lands differs from run to run.

The whole reply
JSON
{
  "summary": "<volatile>",
  "status": "ok",
  "interrupted": true,
  "cause": "interrupt",
  "stop_seq": 62,
  "pc": "<volatile>",
  "cpu": ":maincpu",
  "frame": "<volatile>",
  "regs": "<volatile>",
  "instruction": "<volatile>",
  "following": "<volatile>",
  "errorlog": "<volatile>",
  "average_speed": "<volatile>"
}

Arguments

Takes no argument.

What comes back

interrupted
true when this call stopped the machine, with the stop's readings. false when it was already stopped, with a note.
average_speed
How fast the machine ran since it was resumed: percent of real time, over emulated_s and wall_s.
All 13 reply fields
  • average_speed (object)
  • cpu (string)
  • following (array of string)
  • instruction (StopInstruction)
  • errorlog (object)
  • frame (integer or object)
  • interrupted (boolean)
  • pc (string)
  • regpoint_hit (object)
  • regs (object)
  • stop_seq (integer)
  • watch_hit (object)
  • watches (array)

What it refuses

Why it works this way

stop is the way back from any run that ended without knowing whether the machine stopped. A run by frames refused as no_progress is brought back here: the interrupt is what confirms the stop.

Nothing counts the attempts. If stop fails as well, close then start.

More on why

not_settled also covers a run started from MAME's console, through debug, whose frame counter still moves.

The contract your client receives
Text
Stop a running machine where it is and survey the stop.

Reply: `interrupted` (`true` with the stop survey and `average_speed`; `false` when already
stopped, with a `note`). INVALID: `not_settled` (the machine stays marked RUNNING; ask
again), `session_broken`.

Reference: REFERENCE.md, Running and stopping.
Tools