scry-mame: reference

This page is for a rule that several tools share. It holds the list of tools, the fields every reply carries, and those rules.

Each tool has its own entry, with arguments, reply and example, on its family's page under docs/reference/; a family is a group of tools. To install, see the README.

Each example is a call of the example session: one session on Gridlee, a free ROM from mamedev.org, kept whole in docs/reference/tour/TRANSCRIPT.md.

A path in an example that starts with ./ stands for the folder of your clone, and $TMPDIR for your temporary folder. Write the whole path in your own call: a relative one is refused.

Index

The session

A session is one MAME that start launches and the server keeps until close, so every call reaches the same machine.

Boards with several cpus

MAME's debugger acts on one cpu at a time, the visible one, and every stop makes the cpu that stopped visible.

space is MAME's name for an address space, program by default. A tool refuses a space it cannot read, and io on a cpu that has none.

The orange edge of the window

While a session is live MAME's window has an orange edge, so a person at the computer knows it is in use. It is bright while a call that can run or change the program is in progress, and dim otherwise, even over a program resume left running. start(presence=False) turns it off, and no capture shows it.

The tools: Session, Machine.

What every reply carries

Every reply has the same outer fields, whichever tool answers, so you read any answer the same way.

What each one is for:

The session block

session closes every reply and is read after the tool's work. It says alive (MAME is up), running (the program runs, not stopped at the debugger) and altered.

altered says something wrote to the machine. A write is allowed: write, set_register, a lua script, a debug line that changes the machine. Every later reply then says altered: true, because a measurement on a forced value does not describe the game's own run.

A warning appears only while it holds:

start and status also carry the plain counts, such as altering_writes; other replies may name them in omitted instead.

A refusal

A refused call answers status: INVALID with code and message, and its context in plain fields beside them, such as last_stop.

A field that could not be read is {"available": false, "why": "..."} where its value would be; no reply carries a null. Every tool publishes its reply's shape as outputSchema, and its description says when a field comes only in some cases.

One name for each thing

How a wait ends

A tool that waits answers status: ok with a verdict:

A call that could not finish is a refusal, with no verdict. Zero means no wait in resume(seconds=0) and in settle_seconds=0, a sequence's wait for a stop.

A long wait, and a cancelled call

A long wait reports progress about once a second, as MCP progress notifications: frames done out of N for run_for(frames=N), elapsed seconds with no total otherwise. The value never goes back.

A cancelled call answers nothing, since the protocol sends no response to one. It ends at the next check of its wait, as its own time limit would end it; a tool with no wait finishes first.

The next reply says what it left, once, in summary and in cancelled: tool, after_s, left and earlier. left is stopped, running, closed or unknown; earlier names cancelled calls not yet reported.

A call cancelled while it waited its turn did nothing and leaves no record. One that had already finished is recorded with nothing done to the machine, and a cancel that arrives after its last check is not seen.

End What the cancel leaves Tools
stop The program stopped, as stop leaves it; a stop the call had already reached is recorded as its own. step, run_to, run_for, screen_wait, trace, series_capture, perform, input, record, audio_record
kill MAME ended: asked to quit first when a session is up, which writes cfg/ and nvram/, and killed at once while still booting. start, close
none The machine as the call found it. status, window, cpu_focus, cpu_info, rom_check, resume, stop, breakpoint_at, regpoint_add, watch_add, declaration_list, declaration_clear, comment_list, comment_write, symbols_find, machine_map, read_memory, read_block, registers, disassemble, find, scan, history, write, set_register, reset, memdump, snapshot, screen_signature, screen_map_find, screen_map_write, image_compare, audio_compare, palette, screen_view, gfx_view, gfx_locate, gfx_sweep, gfx_draft, gfx_load, gfx_blits, gfx_blit_source, palette_log, gfx_film, log, log_wait, drive, perform_export, debug, lua, throttle, captures, state_list, state_write, promote

The tools: every one in the Index.

Names for addresses

An address argument, ref in most tools, is a 0x number or a symbol of your program.

The tools: Names, Breakpoints, Read.

Breakpoints and watches

The server saves each breakpoint, watch and registerpoint as you asked for it, and sets it again in later sessions.

You give a symbol or an address, and a condition as typed; MAME's debugger holds what is set now. A rebuild moves an address but not a name, so a breakpoint by name survives it. The tools call a saved one a declaration, and each row they list has a state:

inherited: true marks a row an earlier session saved. foreign lists debugger rows the server did not set, such as one typed through debug; they are never deleted.

What is saved between sessions

The tools: Breakpoints, and Comments for the comments saved beside them.

Running and stopping

The program is either stopped at the debugger or running, and most tools need it stopped.

start leaves it stopped; run_to, run_for and step run it and stop it again; resume lets it run and returns. Every reply that ends at a stop carries the same readings, listed on the Run page.

While it runs, a tool that reads the machine refuses not_stopped, with last_stop and answers_while_running. A value read off a moving machine belongs to no moment. These answer:

A tool that answers may still refuse one of its modes while the program runs: its entry says which.

A breakpoint set while it runs works at once, and the reply's while_running says whether the program ran when the call came in. A stop nobody waited for is reported once, in stopped_on_its_own. A run typed through debug, such as g or step N, counts as running until stop.

When a stop cannot be confirmed

not_settled means the server cannot tell whether the program stopped: a run ended where it could not see, or stop got no answer. Call stop; if stop fails as well, close then start.

A broken session stays broken until close

session_broken stays set until close. A session breaks when the server can no longer match MAME's answers to its requests. That is a request with no answer in time, something other than a stop where one was due, or a failed connection.

Whichever tool meets the failure, every tool reports it. From then on each tool but status and close answers session_broken, with what broke it and the way out: close, then start. No answer can be trusted after it, not even stop's, so session shows running: false beside broken.

A MAME that died answers session_broken with its exit_code. Call close first: it returns MAME's last output before the temporary folder is deleted. On a broken session close kills MAME without asking it to quit, so MAME writes nothing to a state_dir.

Two refusals leave the session usable: readback_refused, where the debugger answered no, and no_channel, where this MAME or this cpu lacks what the call needs.

The tools: Run.

Reading and writing

Every tool that reads or writes memory takes a ref and works at the address the running board uses.

An answer that is a file

A memory dump, a recording or a picture does not fit in a conversation, so those tools write a file and answer with its path.

The tools: Read, Scan, Write, and machine_map on Machine.

The log

MAME writes two logs, and log and log_wait search them by pattern, since a busy driver fills a log fast.

The tools: Machine for log and log_wait, Sequences for drive.

Several calls as one

perform runs a list of calls in order as one call, and drive runs a list and then waits for a line of the log.

The tools: Sequences.

From a session to a test that replays itself

A session can be written out as a list of steps and played back later with no model, as a test.

Every session is recorded from the start that succeeds; the next start clears the recording and close keeps it. perform_export writes it as a document perform can run, and this command plays it back from this repository:

Shell
$ uv run python -m scry_core.replay <document> [--binary PATH] [--rompath DIR] [--transcript PATH]

A step's expected values are its recorded field, and a step that gives others is diverged. Both a failed step and a diverged one set failed_at; code says which.

The tools: Sequences.

The .scry/ folder

A repository can keep how a session starts on its program in a .scry/ folder it tracks, so a session gives only what belongs to its own run.

A session writes nothing there by itself. It saves what it learned as drafts; promote shows them for review and writes the ones you approve. Paths in these files use placeholders, by this rule, so a file reads the same on any computer.

Each draft belongs to one repository: the one a call read it from, else the one whose profile start read. Without root, promote writes a draft only there, never into another repository or the server's own clone. A start with no profile names no repository, so its drafts need root.

The tools: Project.

Input and the screen

Input goes in inside the emulated machine and the screen is read from it, so neither depends on your window, keyboard or mouse.

The tools: Lua for input and throttle, Captures, Screen, Timeline.

Media files

The tools that answer about pictures and sound give the cheapest answer that settles the question.

A fingerprint or a number comes first: "is it the same screen" is two strings compared, never two pictures sent. The whole picture comes last, only from a tool made to show one. A reply of numbers says what it compared, over which region, and each file's path.

The tools: Captures, Files, Screen.

Screen maps

A screen map is a file that names a program's screens and the areas of each, so you ask "which screen is this" and get a name.

Its format is on the Read page.

The tools: Read for screen_map_find and screen_map_write.

Saved states

A saved state goes through MAME's debugger console, where MAME can hold a save or a load back while a timer is pending.

state_write completes a held save or load and checks the state's file, since the console refuses a bad state in silence. A statesave or stateload typed through debug is completed the same way.

The tools: States.

The console

Two tools reach MAME's own consoles, for what no other tool covers.

debug sends one line to the debugger console and returns what it printed. lua runs a script on MAME's Lua console, which the server feeds through MAME's standard input, so no terminal is needed. input, record, audio_record and throttle use that console too, and the Lua page holds the rules they share.

The tools: Write for debug, Lua for lua, input and throttle.