1# Chapter 9: apps, the things that run
2
3Chapter 1 was the libraries; this is the programs. Each folder here is one
4buck2 `rust_binary` over the libraries in `../packages/`, and each owns what
5a library may not: the window, the clock, the sound device, the network, the
6filesystem.
7
8There are six, and they are small on purpose. Most of them exist to answer
9one question separately from everything else, because in the window a
10failure in any part looks the same: Link stands still.
11
12| Question | Program |
13| --- | --- |
14| Does the emulator, built by buck2, run this game at all? | `headless` |
15| Does the bot play, and how far does it get? | `zbanks` |
16| Can I watch it, and poke it? | `native` |
17| Does the Jev key, the TLS, the request and the response all work? | `jevprobe` |
18| Is the machine deterministic enough to rewind? | `replay-probe` |
19| Can a running program be patched with code buck2 just built? | `hotdemo` |
20
21```mermaid
22flowchart LR
23  headless --> console
24  zbanks_app["zbanks (app)"] --> zbanks & decisions & console & alttp
25  native --> console & alttp & zbanks & decisions & replay & panels & mcp
26  jevprobe --> decisions
27  replay_probe["replay-probe"] --> console & replay & zbanks
28  hotdemo --> subsecond["subsecond (third-party)"]
29```
30
31(An arrow means "is built from".)
32
33> **Aside: why everything runs at `-O3`.** There is no debug build in this
34> repository. A cycle-accurate SNES at opt-level 0 runs at 24 to 31 frames a
35> second against the console's 60 (measured 2026-09-20), so an unoptimised
36> build is not a slower version of the same program: the game cannot be
37> played in it. Chapter 29 has the rest.
38
39> **Try it.** Every app runs the same way, through the devshell:
40>
41>     nix develop -c buck2 run //apps/<name>:<name> -- <args>
42>
43> Start with chapter 10's `headless`, which needs nothing but your
44> cartridge.
45
46## For the people who maintain it
47
48### In this folder
49
50| Path | Chapter | What |
51| --- | --- | --- |
52| [headless/](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. |
53| [zbanks/](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. |
54| [native/](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. |
55| [jevprobe/](jevprobe/) | 13 | One real question to the real Jev API, printed in full. |
56| [replay-probe/](replay-probe/) | 14 | The determinism probe the replay design rests on, and the numbers it was sized by. |
57| [hotdemo/](hotdemo/) | 15 | A disposable loop-and-print program for proving buck2-built subsecond hot patches, with no window in the way. |
58| [README.md](README.md) | | This chapter. |
59| [CLAUDE.md](CLAUDE.md) | | How to build and run apps here, for agents. |
60
61← Previous: [Chapter 8, mcp/](../packages/mcp/) · Up: [jevsnes](../) · Next: [Chapter 10, headless/](headless/) →