Chapter 1: packages, the parts that are not a program

Every folder in here is one Rust library (a crate), and none of them can be run. A program is something in apps/ (chapter 9) that picks some of these up and adds what only a program may own: a window, a clock, a sound device, a socket.

The libraries come in two kinds, and the line between them is the most important thing on this page.

Portable: console, alttp and panels. These touch no file, no network, no thread and no window, so they can compile for a web browser (wasm32-unknown-unknown) as well as for the desktop. There is no browser build yet; keeping these three portable is what will make one cheap.

Native only: zbanks, decisions, replay and mcp. Each has a reason it can never run in a browser: zbanks links a C bot and installs a signal handler; decisions opens an HTTP/2 connection to Jev and writes a log; replay writes recordings to disk; mcp is a web server.

flowchart LR
  console["console (portable)"] --> zbanks
  alttp["alttp (portable)"] --> zbanks
  zbanks --> decisions
  zbanks --> replay
  console --> replay
  console --> panels["panels (portable)"]
  alttp --> panels
  panels --> mcp
  console --> mcp
  alttp --> mcp

(An arrow means "is used by".)

Aside: why put a web server under packages/? Because mcp is a library, used by exactly one program, the window. Pulling it out of the window's own crate made every edit to the window compile faster (chapter 8 says why). The folder says "library"; the missing "(portable)" in the picture says "native only", and both are true.

The chapters that follow take them in the order a frame meets them: the console runs (2), its RAM is read as a game (3), the bot plays (4), Jev is asked at the bot's goal choice (5), the run is recorded (6), the panels draw it (7), and an agent can ask the window about it (8).

Try it. nix develop -c buck2 test //packages/... runs every package's tests. They need no ROM, no window and no network.

For the people who maintain it

In this folder

Package	Chapter	What
console/	2	The SNES as a library: boot a cartridge, step one frame, press buttons, read and write work RAM, snapshot the whole machine.
alttp/	3	A Link to the Past read out of work RAM into named things: mode, step, world, position, hearts, rupees, who follows Link.
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.
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.
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.
panels/	7	The egui panels drawn beside the picture: the bot, the game state, Jev, the pad, the replay scrubber, and the layout.
mcp/	8	The MCP server inside the window, the `native mcp` stdio proxy, and the session and snapshot-name files.
README.md		This chapter.
CLAUDE.md		The portability rule, for agents.

Each package is a buck2 rust_library in its own BUCK, and the ones with tests also have a rust_test named test (//packages/<name>:test). Third-party crates come from //third-party/rust:<crate> (chapter 19).

← Previous: Prologue · Up: jevsnes · Next: Chapter 2, console/ →