1# Chapter 17: c, the bot's own source, built as upstream built it
2
3[zbanks/alttp](https://github.com/zbanks/alttp) lives here at upstream
4commit `bcb2537` ("Hammer/sword/lift obstacles in path in
5ap_follow_targets", upstream's last, 2020-02-06), vendored with `git
6read-tree --prefix` and kept byte-identical to upstream. Its README credits
7the reverse engineering it stands on: MathOnNapkins' Zelda 3 RAM/ROM/SRAM
8documentation and annotated disassembly, and wiiqwertyuiop's annotated
9disassembly.
10
11Its pieces, roughly: `alttp.c` is `ap_tick`, the per-frame entry point;
12`ap_snes.c`/`ap_snes.h` read the game out of memory (sprites, tiles, rooms);
13`ap_map.c` builds a map of everything seen and pathfinds across it with A\*;
14`ap_plan.c` holds the goals and tasks and picks what to do next; `ap_req.c`
15and `ap_item.c` track what Link has and what each goal requires. The rest
16are small data structures: a pointer map (`pm`), a min-heap priority queue
17(`pq`, the pathfinder's frontier), bitmask helpers (`bm`), and a bitmask for
18bipartite matching (`lb`).
19
20**How it is built.** Not with its own Makefile, but the Makefile's flags are
21copied into [BUCK](BUCK), with a comment on each change:
22
23```mermaid
24flowchart LR
25  src["zbanks-alttp/ (upstream, untouched)"] --> patched[":patched (a genrule)"]
26  patches["patches/*.patch"] --> patched
27  patched --> lib["//third-party/c:zbanks-alttp (cxx_library)"]
28  lib --> shim["packages/zbanks: shim/host.c and the Rust host"]
29```
30
31`:patched` copies upstream's sources and applies every patch in
32`patches/`, in name order, with `patch --batch --forward -p4`. A patch that
33no longer applies fails the build, so a refresh can never silently lose one.
34
35The few flags a different compiler and host force:
36
37- **`-fcommon`**: `ap_snes.h` *defines* `bool ap_manual_mode;` and every `.c`
38  includes it. The gcc of upstream's era merged such definitions; clang 11+
39  and gcc 10+ refuse to link them.
40- **No `-Werror`**: upstream was warning-clean on its compiler; clang 21
41  warns about things gcc of 2020 did not, and a warning is not a behaviour
42  change.
43- **`-Dfopen=zb_fopen` and `-Drename=zb_rename`**: the bot writes its debug
44  files with bare relative names, into whatever directory the process runs
45  in, which for us is the repository root. These send them through the host
46  instead, into `run/...`.
47- **`-Dap_goal_add=zb_goal_add`, on `ap_map.c` only**: every goal the bot
48  makes is made in `ap_map.c`, so this routes them through the host, which
49  declines the ones the save says are done and calls the real `ap_goal_add`
50  (in `ap_plan.c`, compiled without the rename) for the rest.
51
52> **Aside: the debugger that isn't there.** The bot was written to run under
53> gdb. Its `assert_bp` is an `int3` breakpoint instruction, and the author
54> pressed `continue`. Outside a debugger the kernel turns `int3` into
55> SIGTRAP, which kills the process. The host's shim installs a SIGTRAP
56> handler that counts the trap and returns, which is exactly gdb's
57> `continue`. The Bot panel shows the count. It fires tens of times a run,
58> always at the same place.
59
60> **Try it.** `nix develop -c buck2 build //third-party/c:zbanks-alttp` builds
61> the bot with every patch applied. `nix develop -c buck2 build
62> //third-party/c:patched` stops after patching, if you want to read the
63> sources as compiled.
64
65## For the people who maintain it
66
67### In this folder
68
69| Path | What |
70| --- | --- |
71| [patches/](patches/) | Chapter 18: the carried patches, the only changes to the bot's own code. |
72| [BUCK](BUCK) | `:patched` (upstream's sources with `patches/` applied) and `:zbanks-alttp`, the `cxx_library`, with every flag change commented. |
73| [README.md](README.md) | This chapter. |
74| [CLAUDE.md](CLAUDE.md) | How to make a patch and refresh from upstream, for agents. |
75| `zbanks-alttp/` | Upstream's tree, byte for byte. No chapter: a refresh replaces the directory wholesale, and its README is upstream's. |
76
77The host the bot plugs into is `packages/zbanks` (chapter 4). How it differs
78from upstream's patched Snes9x, and why:
79[research/zbanks-alttp.md](../../research/zbanks-alttp.md).
80
81← Previous: [Chapter 16, third-party/](../) · Up: [third-party](../) · Next: [Chapter 18, patches/](patches/) →