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
perform.Drop a coin into the first slot and keep it pressed for four frames.
input(port=":IN1", field="Coin 1", frames=4, seconds=300){
"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
{
"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
0xnumber. - 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
truewhen the field was let go.falsewhen another stop cut the run first: the field is still pressed, andframe_release_plannedis the frame that lets it go.- active
- Whether the port showed the press, read back as the field was let go.
falsemeans the press never reached the port. - frame_set
- The frame at which the field was pressed;
frame_releasedis the frame at which it was let go. - port_before
- The port's value before the press.
port_heldis its value while pressed, andmaskthe field's bits in it. - verdict
- How the run of frames ended:
ELAPSEDwhen every frame asked ran,OTHER_STOPwhen a breakpoint or a watch stopped it first. - pending
truewhen 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
- A machine that is running (
not_stopped). - An empty
portorfield, orframesbelow 1 (bad_argument). - A port the machine does not have, or a field that port does not have (
unknown_ref). - A machine with no screen, a vector display for one: the press is timed by counting frames (
no_channel). - More than 8 lines still waiting in the console (
bad_argument). - A script the console ran twice, which pressed the field twice, so the reply would describe neither press (
console_rerun). - A script that ran and logged no press: the field was not shown pressed (
readback_refused). - A time limit that ran out before the frames ran (
wait_expired). - A run that was not confirmed stopped: the field may still be pressed (
not_settled). - A console that died before it ran the script (
reader_died).
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.
Related tools
The contract your client receives
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.