Emu198x

One run, start to finish

This script drew that frame.

Three steps: run 300 Game Boy frames, read the program counter, save a PNG. No window opens and nobody watches it happen. The cartridge is built from source in this project, so the run needs no firmware and no software you have to go and find.

[
  {"action":"run_frames","frames":300},
  {"action":"query","path":"cpu.pc"},
  {"action":"save_screenshot","path":"game-boy.png"}
]

Hand it to the Game Boy binary, with the cartridge from the checkout:

./emu198x-game-boy \
  --rom test-data/synthetic-cartridges/nintendo-game-boy-logo.gb \
  --script boot.json

One JSON report comes back on standard output. Every step that has something to report answers with what the machine did, rather than a promise that it did something. Its two observations, wrapped to fit this column:

{"kind":"run_frames","frames":300,
 "reached":5285633,"stop_reason":"ReachedTarget"}
{"kind":"query",
 "result":{"path":"cpu.pc","value":408}}

That frame is the PNG the run wrote, and it is the file this site publishes for the Game Boy. Run the script again and the report comes back identical, down to the tick the machine stopped on, and the image matches byte for byte.

Scripting covers the step vocabulary and where an open-loop file stops being enough. MCP covers the same session when the next step depends on the last answer, and capture covers what a machine can hand back besides a screenshot.