Chapter 9: apps, the things that run

Chapter 1 was the libraries; this is the programs. Each folder here is one buck2 rust_binary over the libraries in ../packages/, and each owns what a library may not: the window, the clock, the sound device, the network, the filesystem.

There are six, and they are small on purpose. Most of them exist to answer one question separately from everything else, because in the window a failure in any part looks the same: Link stands still.

Question	Program
Does the emulator, built by buck2, run this game at all?	`headless`
Does the bot play, and how far does it get?	`zbanks`
Can I watch it, and poke it?	`native`
Does the Jev key, the TLS, the request and the response all work?	`jevprobe`
Is the machine deterministic enough to rewind?	`replay-probe`
Can a running program be patched with code buck2 just built?	`hotdemo`

flowchart LR
  headless --> console
  zbanks_app["zbanks (app)"] --> zbanks & decisions & console & alttp
  native --> console & alttp & zbanks & decisions & replay & panels & mcp
  jevprobe --> decisions
  replay_probe["replay-probe"] --> console & replay & zbanks
  hotdemo --> subsecond["subsecond (third-party)"]

(An arrow means "is built from".)

Aside: why everything runs at -O3. There is no debug build in this repository. A cycle-accurate SNES at opt-level 0 runs at 24 to 31 frames a second against the console's 60 (measured 2026-09-20), so an unoptimised build is not a slower version of the same program: the game cannot be played in it. Chapter 29 has the rest.

Try it. Every app runs the same way, through the devshell:
nix develop -c buck2 run //apps/<name>:<name> -- <args>
Start with chapter 10's headless, which needs nothing but your cartridge.

For the people who maintain it

In this folder

Path	Chapter	What
headless/	10	Runs a ROM for N frames with no window, checks a snapshot restores the machine exactly, writes the last frame as a PPM and prints the game-state bytes. The smoke test for the core.
zbanks/	11	The zbanks/alttp C bot playing headless: runs of N frames with PNGs and a progress table, Jev optional, and `--make-home`, which makes the state the bot starts from.
native/	12	The SNES in a window, played by the bot, with panels beside the picture, an MCP server, a replay timeline and hot patching.
jevprobe/	13	One real question to the real Jev API, printed in full.
replay-probe/	14	The determinism probe the replay design rests on, and the numbers it was sized by.
hotdemo/	15	A disposable loop-and-print program for proving buck2-built subsecond hot patches, with no window in the way.
README.md		This chapter.
CLAUDE.md		How to build and run apps here, for agents.

← Previous: Chapter 8, mcp/ · Up: jevsnes · Next: Chapter 10, headless/ →