1# Chapter 1: packages, the parts that are not a program
2
3Every folder in here is one Rust library (a *crate*), and none of them can be
4run. A program is something in `apps/` (chapter 9) that picks some of these
5up and adds what only a program may own: a window, a clock, a sound device,
6a socket.
7
8The libraries come in two kinds, and the line between them is the most
9important thing on this page.
10
11**Portable**: `console`, `alttp` and `panels`. These touch no file, no
12network, no thread and no window, so they can compile for a web browser
13(`wasm32-unknown-unknown`) as well as for the desktop. There is no browser
14build yet; keeping these three portable is what will make one cheap.
15
16**Native only**: `zbanks`, `decisions`, `replay` and `mcp`. Each has a
17reason it can never run in a browser: `zbanks` links a C bot and installs a
18signal handler; `decisions` opens an HTTP/2 connection to Jev and writes a
19log; `replay` writes recordings to disk; `mcp` is a web server.
20
21```mermaid
22flowchart LR
23  console["console (portable)"] --> zbanks
24  alttp["alttp (portable)"] --> zbanks
25  zbanks --> decisions
26  zbanks --> replay
27  console --> replay
28  console --> panels["panels (portable)"]
29  alttp --> panels
30  panels --> mcp
31  console --> mcp
32  alttp --> mcp
33```
34
35(An arrow means "is used by".)
36
37> **Aside: why put a web server under `packages/`?** Because `mcp` is a
38> library, used by exactly one program, the window. Pulling it out of the
39> window's own crate made every edit to the window compile faster (chapter
40> 8 says why). The folder says "library"; the missing "(portable)" in the
41> picture says "native only", and both are true.
42
43The chapters that follow take them in the order a frame meets them: the
44console runs (2), its RAM is read as a game (3), the bot plays (4), Jev is
45asked at the bot's goal choice (5), the run is recorded (6), the panels draw
46it (7), and an agent can ask the window about it (8).
47
48> **Try it.** `nix develop -c buck2 test //packages/...` runs every
49> package's tests. They need no ROM, no window and no network.
50
51## For the people who maintain it
52
53### In this folder
54
55| Package | Chapter | What |
56| --- | --- | --- |
57| [console/](console/) | 2 | The SNES as a library: boot a cartridge, step one frame, press buttons, read and write work RAM, snapshot the whole machine. |
58| [alttp/](alttp/) | 3 | A Link to the Past read out of work RAM into named things: mode, step, world, position, hearts, rupees, who follows Link. |
59| [zbanks/](zbanks/) | 4 | The host for the zbanks/alttp C bot: its `base()`, `ap_tick` and savestates over `console/`, the ROM and save changes that make a vanilla cartridge the Randomizer it was written for, the stall detector and recovery, and goal outcomes kept across restarts. |
60| [decisions/](decisions/) | 5 | Every kind of question this project puts to Jev, one module per kind, run by one shared engine; `goal_choice` is the first and so far only one. |
61| [replay/](replay/) | 6 | A run recorded as an input-and-WRAM-diff log with tiered keyframes: seek anywhere, branch, and rebuild the bot at any frame. |
62| [panels/](panels/) | 7 | The egui panels drawn beside the picture: the bot, the game state, Jev, the pad, the replay scrubber, and the layout. |
63| [mcp/](mcp/) | 8 | The MCP server inside the window, the `native mcp` stdio proxy, and the session and snapshot-name files. |
64| [README.md](README.md) | | This chapter. |
65| [CLAUDE.md](CLAUDE.md) | | The portability rule, for agents. |
66
67Each package is a buck2 `rust_library` in its own `BUCK`, and the ones with
68tests also have a `rust_test` named `test` (`//packages/<name>:test`).
69Third-party crates come from `//third-party/rust:<crate>` (chapter 19).
70
71← Previous: [Prologue](../) · Up: [jevsnes](../) · Next: [Chapter 2, console/](console/) →