SCRYMAMEReferenceLuathrottle

MAMELua

throttle

Choose whether the machine runs at real speed or as fast as the host can.

throttle(on, seconds=5.0)

Try it

On Gridlee, a free ROM from mamedev.org, stopped at reset before anything has run. The example session then runs the game five seconds.
Ask

Turn real-speed throttling off so the game fast-forwards, then confirm the switch was applied.

Call
throttle(on=false)
Reply 5 of 7 fields
{
  "summary": "throttle off: pending until the console next reads a line",
  "status": "ok",
  "on": false,
  "pending": true,
  "tag": "MAME_MCP_THROTTLE#1"
}

Then, once the game has run, look for the tag in MAME's log:

Call
log_wait(pattern="MAME_MCP_THROTTLE#1", channel="emulator")
Reply 4 of 12 fields
{
  "summary": "log_wait emulator /MAME_MCP_THROTTLE#1/: matched already there",
  "status": "ok",
  "verdict": "TARGET",
  "line": "[luaengine] MAME_MCP_THROTTLE#1 throttled=false frame=0"
}

pending means the switch waits for the machine to move, and tag is the text it writes to MAME's log once applied. The second call finds that line, throttled=false: TARGET means the pattern matched.

The two replies, whole

The first call's:

JSON
{
  "summary": "throttle off: pending until the console next reads a line",
  "status": "ok",
  "on": false,
  "pending": true,
  "applies": "when the console next reads a line: a step, the next frame emulated, or a debugger command on a stub that refreshes after one",
  "tag": "MAME_MCP_THROTTLE#1",
  "confirmed_by": "its tag in the error log, read by the next stop's survey, by `status` and by `close`; `status` lists it in `throttles_pending` until then, and if the tag never comes, every reply after that says so in `session.throttles_not_applied`"
}

The second call's:

JSON
{
  "summary": "log_wait emulator /MAME_MCP_THROTTLE#1/: matched already there",
  "status": "ok",
  "verdict": "TARGET",
  "pattern": "MAME_MCP_THROTTLE#1",
  "channel": "emulator",
  "line": "[luaengine] MAME_MCP_THROTTLE#1 throttled=false frame=0",
  "already": true,
  "lines_total": 1,
  "lines_before": 4,
  "arrived_during": 0,
  "waited_s": "<volatile>",
  "lines_examined": 6
}

Arguments

on boolean, required
true runs the machine at real speed; false fast-forwards it, as fast as the host can.
seconds number (> 0, <= 600.0), default 5.0
With the machine running, how long to wait for the switch to be confirmed, in real seconds, up to 600. Left out, 5.

What comes back

pending
true when the switch is not applied yet: the machine is stopped, and the console runs the line when it next moves. false once applied.
tag
The text the switch writes in MAME's log when it applies, MAME_MCP_THROTTLE#n. Give it to log_wait on the emulator log to wait for it.
on
The setting asked for.
frame
The frame at which the switch applied, and waited_s how long that took. Only when pending is false.
applies
For a switch not applied yet, when it takes effect; confirmed_by says which later replies confirm it.
All 8 reply fields
  • applies (string)
  • confirmed_by (string)
  • frame (integer)
  • on (boolean)
  • pending (boolean)
  • tag (string)
  • tagged_lines (array)
  • waited_s (number)

What it refuses

Why it works this way

The switch is a line sent to MAME's console, and the console runs a line only when the machine moves. Asked on a stopped machine it cannot wait for its own confirmation, because nothing runs the line while it waits. The reply is pending, with the tag to look for.

So, stopped at a breakpoint, ask and then resume: the machine runs at the new speed from its first frame. A switch not applied yet is looked for again at the next stop, by status and by close. Until then status lists it in throttles_pending.

A switch that never took effect is not forgotten. When the console went past the line without applying it, or the machine reports the other setting, every later reply says so in session.throttles_not_applied, which stays set until close. Asking again fixes the speed and the record stays: this session measured at a speed nobody chose.

More on why

No call is refused over a switch that was not applied. The record is on every reply because the call that would report it is one nobody has to make. Until the console has gone past the line there is no record: the pending you were given is still true.

The console reads a line on a step, on the next frame emulated, or after a debugger command on a MAME build that refreshes after one. A machine that stops again before its next frame leaves the switch waiting.

The tag is text to search the log for, never a mark, which is a position in a log. Its number counts every line this session sent to the console, not the switches. log_wait takes a regular expression, so #1 also matches #10.

start's throttle_from_frame is the same switch decided at launch: fast-forward up to that frame, real speed after it.

tagged_lines, on a refusal, are the log lines that carry the tag.

The contract your client receives
Text
Switch real-speed throttling `on` or off; it applies when the console next reads a line.

Stopped, the reply is `pending: true` with a `tag` for `log_wait` on the `emulator`
channel. Running, it waits up to `seconds` for the tag; a bound that runs out is
`wait_expired`.

Reply: `on`, `pending`, `tag`; pending: `applies`, `confirmed_by`; applied: `frame`,
`waited_s`.

Reference: REFERENCE.md, Input and the screen.
Tools