1# Chapter 22: research, the notes it was built from
2
3Almost nothing in this repository was written from memory. Where the code
4says "`$7EF374` bit `0x04` is the green pendant", somebody read it in a
5disassembly first, and the note they wrote cites the file and line. This
6folder is those notes. They are the slow, careful half of the work: an
7afternoon reading a 20,000-line vendor document or a Super Nintendo game's
8source, so that the code can be short and right.
9
10Each note cites its sources (vendor docs, emulator source, game
11disassemblies) by file and line, so a claim can be re-checked rather than
12re-derived. When a note and the running game disagree, the note is wrong,
13and it is corrected with the measurement that found it.
14
15> **Aside: a game has source code now.** A Link to the Past was taken apart
16> by its fans over two decades, and the results are good enough to build
17> on: [snesrev/zelda3](https://github.com/snesrev/zelda3) is a C
18> reimplementation that compiles to a bit-exact match of the USA ROM, and
19> [spannerisms/usdasm](https://github.com/spannerisms/usdasm) is a full,
20> byte-exact disassembly. Most of the RAM map is read from those two, cross
21> checked against [spannerisms/jpdasm](https://github.com/spannerisms/jpdasm),
22> [JaredBrian/AsarUSALTTPDisassembly](https://github.com/JaredBrian/AsarUSALTTPDisassembly)
23> and MathOnNapkins' original
24> [walkingeyerobot/alttp-disassembly](https://github.com/walkingeyerobot/alttp-disassembly).
25
26Three of the notes come from before 2026-09-21, when a Rust "brain" (since
27deleted) drove Link directly: the breaker trip and the two Hyrule Castle
28notes. The code they name (`packages/brain`, `apps/walkcheck`) is gone, but
29what they found about the game and about the spend guards is still true,
30and they are kept for that.
31
32> **Try it.** Open [zbanks-alttp.md](zbanks-alttp.md) at "How far it plays"
33> and follow one run's table row back to the carried patch that made it
34> possible (chapter 18 has the map).
35
36## For the people who maintain it
37
38### In this folder
39
40| Path | What it answers |
41| --- | --- |
42| [fixtures/](fixtures/) | Chapter 23: situations captured from a running game, kept as evidence. |
43| [zbanks-alttp.md](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. |
44| [alttp-ram-map.md](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. |
45| [jev-api-digest.md](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. |
46| [subsecond-patch-build.md](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. |
47| [mesen-automation.md](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. |
48| [breaker-trip-2026-09-20.md](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. |
49| [castle-inside.md](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. |
50| [castle-passage.md](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. |
51| [README.md](README.md) | This chapter. |
52| [CLAUDE.md](CLAUDE.md) | How to keep the notes true, for agents. |
53
54← Previous: [Chapter 21, top/](../third-party/rust/top/) · Up: [jevsnes](../) · Next: [Chapter 23, fixtures/](fixtures/) →