SCRYMAMEReferenceLualua

MAMELua

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

On Gridlee, a free ROM from mamedev.org, stopped anywhere. The example session asks this late in a game.
Ask

Ask MAME itself which machine this is, with one line of Lua that only reads.

Call
lua(script="print(manager.machine.system.description)", read_only=true)
Reply 6 of 20 fields
{
  "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
JSON
{
  "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; a return value 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
true says the script only reads, and nothing checks it. Left out, the session is marked altered: written to by this session.

What comes back

output
What the script printed. Past 4000 characters it is cut: clipped is true and output_path names a file with all output_chars of 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; pc is 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

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_steps or evaluated_by says 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 refused reader_died.
  • thread_errors: how many times the console's reading thread died.
  • console_reruns: earlier scripts run a second time. altered alone cannot say a write happened twice.
  • thread_errors, console_reruns and resent are 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 at close, so a throttle asked 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.

The contract your client receives
Text
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.
Tools