Chapter 10: headless, does it even boot?

Before anything clever, one question: does the core, built by buck2, run this game? headless answers it with no window, no bot and no Jev:

nix develop -c buck2 run //apps/headless:headless -- \
  "roms/Legend of Zelda, The - A Link to the Past (USA).sfc" 1500 run/out.ppm

It boots the cartridge and runs the number of frames you ask for, tapping Start for 4 frames out of every 60 (enough to get through the title screens without holding the button down). Then it writes the last frame as a binary PPM and checks the one property everything else in the repository leans on: it takes a snapshot, runs 300 frames, goes back to the snapshot, runs the same 300 frames again, and asserts the two futures are the same picture and the same work RAM. Finally it prints the frame size, the audio sample count, and the handful of work-RAM bytes the rest of the code keys on (game mode, submode, Link's position, health).

Aside: four times faster than a SNES. Measured 2026-09-20: 1,500 frames in 5.6 s and 3,600 in 14.5 s, about four times real time, reaching the title screen by frame 900 and the name-registration screen by frame 1,500. That margin is what lets the headless bot (chapter 11) play 30,000 frames, eight minutes of game, in about two and a half.

Try it. Run the command above, then ffmpeg -i run/out.ppm run/out.png and open the picture. You should see the name-registration screen, and a line saying the snapshot was identical after 300 frames.

For the people who maintain it

In this folder

Usage: headless <rom.sfc> <frames> <out.ppm>. Link's position reads 0 until a save is loaded and the game is in play, so zeros at the title or the name-registration screen are correct.

← Previous: Chapter 9, apps/ · Up: apps · Next: Chapter 11, zbanks/ →