SCRYMAMEReferenceLuainput

MAMELua

input

Press one of the board's inputs by name (a coin, a start button), hold it for some frames and let go.

input(port, field, value=1, frames=4, seconds=30.0)

Try it

On Gridlee, a free ROM from mamedev.org, stopped about seven seconds after power-on. The example session drops this coin as the first step of a perform.
Ask

Drop a coin into the first slot and keep it pressed for four frames.

Call
input(port=":IN1", field="Coin 1", frames=4, seconds=300)
Reply 7 of 36 fields
{
  "summary": "input :IN1 'Coin 1': held 4 frames, active True, released at frame 423",
  "status": "ok",
  "port_before": "0x000000cf",
  "port_held": "0x000000ce",
  "frame_set": 419,
  "frame_released": 423,
  "active": true
}

Bit 0 of the port went low while pressed (0xcf to 0xce), from frame 419 to frame 423. active confirms the port showed the press; whether the game counted the coin is for its memory to say.

The whole reply
JSON
{
  "summary": "input :IN1 'Coin 1': held 4 frames, active True, released at frame 423",
  "status": "ok",
  "verdict": "ELAPSED",
  "frame_before": 419,
  "frame_after": 424,
  "emulated_before_s": 7.096336,
  "emulated_after_s": 7.180818,
  "cycles": 105602,
  "polls": 6,
  "lines_ahead": 0,
  "thread_errors": 0,
  "console_reruns": 0,
  "route": "ioport",
  "port": ":IN1",
  "field": "Coin 1",
  "value": "0x00000001",
  "frames": 4,
  "name": "Coin 1",
  "player": 0,
  "mask": "0x00000001",
  "defvalue": "0x00000001",
  "port_before": "0x000000cf",
  "frame_set": 419,
  "released": true,
  "port_held": "0x000000ce",
  "frame_released": 423,
  "active": true,
  "cause": "the `gvblank` stop of the last frame asked",
  "stop_seq": 7,
  "pc": "0x0000fd80",
  "cpu": ":maincpu",
  "frame": 424,
  "regs": {
    "A": "0x00",
    "B": "0x00",
    "D": "0x0000",
    "X": "0x0150",
    "Y": "0x00e3",
    "U": "0x00e5",
    "PC": "0xfd80",
    "S": "0x07f2",
    "CC": "0x90",
    "DP": "0x00"
  },
  "instruction": {"address": "FD80", "bytes": "0CB2", "text": "INC    <$B2", "symbol": "irq", "delta": 0},
  "following": ["FD82: 96 B2    LDA    <$B2", "FD84: 84 03    ANDA   #$03", "FD86: 26 04    BNE    $FD8C", "FD88: 0C B3    INC    <$B3", "FD8A: 0C B4    INC    <$B4", "FD8C: B6 03 BE LDA    $03BE", "... 9 more"],
  "errorlog": "<volatile>"
}

Arguments

port string, required
The input port that has the field, as MAME names it: :P1.
field string, required
The field of that port to press, as MAME names it: Coin 1.
value integer or string, default 1
What the field is set to: non-zero presses a digital field, an analog one takes a value in its range. Left out, 1; a string is a 0x number.
frames integer, default 4
How many frames the field stays pressed: one or more. Left out, 4.
seconds number (> 0, <= 600.0), default 30.0
The time limit of the whole call, in real seconds, up to 600. Left out, 30.

What comes back

released
true when the field was let go. false when another stop cut the run first: the field is still pressed, and frame_release_planned is the frame that lets it go.
active
Whether the port showed the press, read back as the field was let go. false means the press never reached the port.
frame_set
The frame at which the field was pressed; frame_released is the frame at which it was let go.
port_before
The port's value before the press. port_held is its value while pressed, and mask the field's bits in it.
verdict
How the run of frames ended: ELAPSED when every frame asked ran, OTHER_STOP when a breakpoint or a watch stopped it first.
pending
true when the script got no answer: the press has not happened, and may still happen when the console next runs a line.
All 45 reply fields
  • console_reruns (integer)
  • cpu (string)
  • following (array of string)
  • instruction (StopInstruction)
  • errorlog (object)
  • frame (integer)
  • pc (string)
  • regs (object)
  • resent (integer)
  • stop_seq (integer)
  • thread_errors (integer)
  • watches (array)
  • emulated_after_s (number or object)
  • emulated_before_s (number or object)
  • active (boolean or object)
  • cycles (integer)
  • defvalue (string)
  • drain_steps (integer)
  • field (string)
  • frame_after (integer)
  • frame_before (integer)
  • frame_release_planned (integer)
  • frame_released (integer)
  • frame_set (integer)
  • frames (integer)
  • instructions_completed (integer)
  • lines_ahead (integer)
  • mask (string)
  • mode (string)
  • name (string)
  • pending (boolean)
  • player (integer)
  • polls (integer)
  • port (string)
  • port_before (string)
  • port_held (string or object)
  • reader_steps (integer)
  • regpoint_hit (object)
  • released (boolean)
  • route (string)
  • seen_bytes (integer)
  • tagged_lines (array)
  • value (string)
  • verdict (string)
  • watch_hit (object)

What it refuses

Why it works this way

An arcade board has no keyboard. Its coin slots, buttons and switches are named fields of input ports, so pressing a field by name works on any board.

A game that detects the edge of a press needs the field let go between two presses: two coins are two calls.

A press is play, not a write. It leaves altered, the mark that this session has written to the machine, as it was.

More on why

seconds covers the whole call: every run of frames and every wait for the console takes what is left of it.

Only one press waits at a time. A new input first lets go of a field an earlier call left pressed.

Before its own line the call steps the machine once for each line still waiting in the console (lines_ahead, drain_steps). The console's other counts are described under lua.

route says which way the press went in: always ioport here, MAME's input ports. name, player and defvalue are what MAME says of the field: its name, its player and its value when not pressed.

The reply ends with what every stop returns, described in Running and stopping.

The contract your client receives
Text
Press input `field` of `port` by name, hold it `frames` frames, release it, stop one frame
later. Needs the machine STOPPED (else `not_stopped`).

A non-zero `value` activates a digital field. `seconds` bounds the whole call. A press
leaves `altered` as it was; an edge-detecting game needs a release between presses: call
twice.

Reply, once answered: `verdict`, `frame_before`, `frame_after`, `port_before`, `frame_set`,
`released`, `frame_released`, `active` (read back at release), `name`, `mask`, `note`, the
stop survey. Without an answer, `pending`.

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