Chapter 22: research, the notes it was built from

Almost nothing in this repository was written from memory. Where the code says "$7EF374 bit 0x04 is the green pendant", somebody read it in a disassembly first, and the note they wrote cites the file and line. This folder is those notes. They are the slow, careful half of the work: an afternoon reading a 20,000-line vendor document or a Super Nintendo game's source, so that the code can be short and right.

Each note cites its sources (vendor docs, emulator source, game disassemblies) by file and line, so a claim can be re-checked rather than re-derived. When a note and the running game disagree, the note is wrong, and it is corrected with the measurement that found it.

Aside: a game has source code now. A Link to the Past was taken apart by its fans over two decades, and the results are good enough to build on: snesrev/zelda3 is a C reimplementation that compiles to a bit-exact match of the USA ROM, and spannerisms/usdasm is a full, byte-exact disassembly. Most of the RAM map is read from those two, cross checked against spannerisms/jpdasm, JaredBrian/AsarUSALTTPDisassembly and MathOnNapkins' original walkingeyerobot/alttp-disassembly.

Three of the notes come from before 2026-09-21, when a Rust "brain" (since deleted) drove Link directly: the breaker trip and the two Hyrule Castle notes. The code they name (packages/brain, apps/walkcheck) is gone, but what they found about the game and about the spend guards is still true, and they are kept for that.

Try it. Open zbanks-alttp.md at "How far it plays" and follow one run's table row back to the carried patch that made it possible (chapter 18 has the map).

For the people who maintain it

In this folder

Path	What it answers
fixtures/	Chapter 23: situations captured from a running game, kept as evidence.
zbanks-alttp.md	The zbanks/alttp C bot on our console: the host contract its patched Snes9x gave it and ours; every way vanilla USA 1.0 differs from the Japanese-based Randomizer it was written for (ROM addresses, open mode, uncle's text, item text, cheats, the missing map file); every carried patch and host fix with its evidence; Jev at the goal choice and its cost; how far it plays; the window's own stalls and their recovery; and what is still outstanding.
alttp-ram-map.md	A Link to the Past (USA 1.0) work RAM: game mode, the exact player-has-control rule, Link's position and state machine, inventory, location, sprite and ancilla tables, the dungeon walkability grid, dialog detection, liftables and their gloves, ROM identification. Ends with what is still unverified.
jev-api-digest.md	The Jev HTTP API and Python SDK: endpoints, the `Choice`/`Score`/`Noul` primitives, request and response shapes, limits, errors, retry semantics, and how the reference agent samples a pick.
subsecond-patch-build.md	How Dioxus' `dx` builds a subsecond hot patch, and how to rebuild that under buck2: the flags, the object files, the jump table, and the traps that make a patch apply and do nothing.
mesen-automation.md	Driving Mesen 2 from outside: command-line switches, `--testRunner`, the Lua API (memory, input, frame callbacks, screenshots), LuaSocket and the two settings that gate it.
breaker-trip-2026-09-20.md	Why the live window (then driven by the Rust brain) asked 17 questions in 7.4 s and tripped the 30-a-minute breaker: a soldier within 56 px cleared the plan on every decision; proved from the spend ledger and two snapshots' work RAM.
castle-inside.md	The route from uncle's room `$55` to Zelda's cell `$80`, room by room: how edges, stairs, warp doors and holes pick the next room, the room header and door tables in the ROM, the keys and shutters that gate it, and what `$7EF3CC` vs `$7EF3C5` mean.
castle-passage.md	Hyrule Castle's secret passage: why the hole's own table stores a position 128 pixels above it, the bush over it that grows back on every area load, and the ledge directions the engine allows.
README.md	This chapter.
CLAUDE.md	How to keep the notes true, for agents.

← Previous: Chapter 21, top/ · Up: jevsnes · Next: Chapter 23, fixtures/ →