lua
Run a Lua script inside MAME, with all of MAME's Lua interface, and get back what it prints.
lua(script, seconds=5.0, read_only=false)
Try it
Ask MAME itself which machine this is, with one line of Lua that only reads.
lua(script="print(manager.machine.system.description)", read_only=true){
"summary": "lua: 8 chars back, pc 0x0000fd82 after one step",
"status": "ok",
"evaluated_by": "one step",
"pc_before": "0x0000fd80",
"output": "Gridlee\n",
"clipped": false
}The script printed Gridlee, and only what it prints comes back. evaluated_by says the console needed one step of the machine to run the line, which is why the program counter moved on from pc_before.
The whole reply
{
"summary": "lua: 8 chars back, pc 0x0000fd82 after one step",
"status": "ok",
"script_chars": 41,
"evaluated_by": "one step",
"lines_ahead": 0,
"call": "MAME_MCP_LUA_END#39",
"pc_before": "0x0000fd80",
"thread_errors": 0,
"console_reruns": 0,
"output": "Gridlee\n",
"clipped": false,
"cause": "lua: one step",
"stop_seq": 60,
"pc": "0x0000fd82",
"cpu": ":maincpu",
"frame": 630,
"regs": {
"A": "0x00",
"B": "0xd8",
"D": "0x00d8",
"X": "0x0014",
"Y": "0xf2e6",
"U": "0x4071",
"PC": "0xfd82",
"S": "0x07f4",
"CC": "0xd0",
"DP": "0x00"
},
"instruction": {"address": "FD82", "bytes": "96B2", "text": "LDA <$B2", "symbol": "irq", "delta": 2},
"following": ["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", "FD8F: 26 28 BNE $FDB9", "... 9 more"],
"errorlog": "<volatile>"
}Arguments
- script string, required
- The Lua to run: one chunk of at most 16000 characters. Only what it
prints comes back; areturnvalue does not. - seconds number (> 0, <= 600.0), default
5.0 - How long to wait for the console's answer, in real seconds, up to 600. Left out, 5.
- read_only boolean, default
false truesays the script only reads, and nothing checks it. Left out, the session is markedaltered: written to by this session.
What comes back
- output
- What the script printed. Past 4000 characters it is cut:
clippedistrueandoutput_pathnames a file with alloutput_charsof it. - evaluated_by
- How the console came to run the script:
one step, or more steps when other lines were waiting ahead of it. - pc_before
- The program counter before the step that ran the script;
pcis where the machine stopped after it. - lines_ahead
- How many lines were waiting in the console before this one. The machine was stepped once for each.
- console_reruns
- How many earlier scripts the console ran a second time during this call. One that wrote has written twice.
All 26 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)call(string)clipped(boolean)evaluated_by(string)lines_ahead(integer)output(string)output_chars(integer)output_path(string)pc_before(string)pending(boolean)reader_steps(integer)regpoint_hit(object)script_chars(integer)seen_bytes(integer)watch_hit(object)
What it refuses
- A machine that is running (
not_stopped). - An empty script, or one over 16000 characters (
bad_argument). - More than 8 lines still waiting in the console:
run_forone frame runs them (bad_argument). - A script that fails to compile or raises, with the console's own
error:text (bad_argument). - No answer within
seconds; a late answer shows inlog, on theprocesslog (wait_expired). - A console that died before it ran the script; with
pending: truethe script may still run later (reader_died).
Why it works this way
The other tools check what they did: input, throttle, record, state_write. lua is for what none of them does, and it promises less: nothing checks what the script changed, so the session is marked altered unless you say read_only.
The console runs a line only when the machine moves, so the call steps the machine once. The script reads the machine after the instruction at the stop has run. With lines waiting ahead it steps once for each, and the script reads the state after the last step.
The whole script is one chunk: a local on line 1 is seen on line 2, and a script that fails says so in the console's own words. Guard any callback you install with pcall, because its error does not come back to the call that installed it.
More on why
A callback's error goes elsewhere. A write tap's goes nowhere, and the tap keeps firing. A frame notifier's or a periodic callback's is a [LUA ERROR] line per call in log.
MAME's console is a plugin. start refuses a MAME that does not have it, before anything is launched.
call is the line that closes this call's output in the process log. When seconds runs out, the refusal says how many steps were taken, and a late answer shows in log, ending with that line.
MAME reads the console on a thread its own source calls unsafe: a step at the wrong moment can make it run the previous script again, or drop a line. Every reply that reads the console counts what happened:
lines_ahead: lines waiting before this call's own.drain_stepsorevaluated_bysays how they were run first.reader_steps: extra steps given because the console had not picked the line up.resent: the console took the line and never ran it, so it was sent again. A second time is refusedreader_died.thread_errors: how many times the console's reading thread died.console_reruns: earlier scripts run a second time.alteredalone cannot say a write happened twice.thread_errors,console_rerunsandresentare on every reply that read a script's answer back, zero included.- Session totals sit under
session.console. They grow when a call reads its answer back and once more atclose, so athrottleasked while stopped adds none till then.
The tools that send a script of the server's own carry the same counts: input, throttle, record, audio_record, screen_signature, screen_map_find and screen_map_write with method="add". debug does not use this console: it talks to MAME's debugger.
A script of the server's own that raises is refused by its error. A port or field the machine lacks is unknown_ref, a recording with no screen no_channel, anything else unexpected_answer.
Related tools
The contract your client receives
Evaluate a Lua `script` on MAME's Lua console; prefer the typed wrappers. Needs the machine STOPPED (else `not_stopped`).
`script`: one chunk of at most 16000 characters; only what it `print`s comes back.
`seconds` bounds the console's answer. `read_only=True` declares it only reads, else the
session is marked ALTERED. More than
8 lines ahead in the pipe is refused. A chunk that fails to load or raises
is INVALID with the console's `error:`; `reader_died` means it had not run when the reader
died, and with `pending: true` it may still run on a later reader.
Reply: `output`, `clipped`, `output_path` (past 4000 characters), `evaluated_by`,
`pc_before`, `lines_ahead`, `console_reruns`, `note`, the stop survey.
Reference: REFERENCE.md, The console.