A Link to the Past (SNES, USA v1.0) — WRAM Map for an AI Harness

Sourced from cloned repositories (read-only research clones, never pushed/starred/forked):

Sourcing rule applied throughout: every fact below cites a file:line in one of the cloned repos. Three-way agreement (zelda3 + usdasm-lineage + JaredBrian, sometimes + jpdasm) is noted explicitly where checked — these are independent naming/authorship lineages that happened to agree byte-for-byte on every address checked, which is strong triangulation. Anything not directly backed by source is flagged UNVERIFIED.

All addresses are given as $7Exxxx (WRAM bank $7E). zelda3's convention g_ram+0xNN is numerically 0xNN = the offset from $7E0000.

1. Game mode / submodule ($7E0010 / $7E0011)

Module enum (main_module_index, values 0–27)

This is the actual dispatch table the game's main loop indexes with main_module_index — kMainRouting[main_module_index](). Source: zelda3 src/misc.c:151-180 (static PlayerHandlerFunc *const kMainRouting[28] = {...}), call site src/misc.c:325.

Correction, 2026-09-20. This table first gave 10 and 11 as the DARK WORLD call sites. They are not: usdasm's dispatch table names them Module0A_OverworldSpecialLoad and Module0B_OverworldSpecial, and the dark world runs in module 9 like the light world. zelda3 points 8/10 and 9/11 at the same two functions, which is what the wrong reading was inferred from. Light or dark is $7EF3CA (§4).

Player-has-control vs. cutscene/transition/dialog — verified, exact rule

The engine names submodule 0 of both gameplay modules literally *_PlayerControl:

• Overworld: Module09_00_PlayerControl — zelda3 src/overworld.c:750
• Dungeon: Module07_00_PlayerControl — zelda3 src/dungeon.c:6594

Rule (from source, both functions gate identically):

player_has_control :=
    (main_module_index == 7 or main_module_index in {9, 11})
    and submodule_index == 0
    and flag_custom_spell_anim_active == 0   ($7E0112)
    and flag_is_link_immobilized == 0        ($7E02E4)
    and flag_block_link_menu == 0            ($7E0FFC)
    and (main_module_index == 7 or trigger_special_entrance == 0)  ($7E04C6, overworld-only gate)

Citations: src/overworld.c:750-758 (the if (!(flag_custom_spell_anim_active | flag_is_link_immobilized | flag_block_link_menu | trigger_special_entrance)) guard); src/dungeon.c:6594-6602 (identical guard minus trigger_special_entrance); addresses from src/variables.h:163 (flag_custom_spell_anim_active), :246 (flag_is_link_immobilized), :507 (trigger_special_entrance), :791 (flag_block_link_menu).

Any other (main_module_index, submodule_index) combination — including main_module_index==14 (dialog/menu, §7), any nonzero submodule of 7/9/11 (screen scroll, warp, cutscene sub-states), or modules 0-6/12-27 — means the player does not have free movement control. This is a precise, code-derived rule, not a heuristic.

2. Link — position, direction, state machine, combat state

All addresses zelda3 src/variables.h:5-95 unless noted. Cross-checked against JaredBrian Other/symbols_wram.asm and jpdasm symbols_wram.asm where marked "3-way".

Link state machine enum (link_player_handler_state, $7E005D)

Complete enum from zelda3 src/player.h:7-34. Gaps (11, 13, 15, 16, 24, 31, 32...) are states with no named C constant in this header — either truly unused values or states the reimplementation didn't need to name; treat unlisted values as unknown/needs field verification, not confirmed-unused.

"Dashing" ⇒ state ∈ {17, 18}. "Swimming" ⇒ state == 4. "Falling" ⇒ state ∈ {1, 12, 14}. "Carrying/lifting" ⇒ state == 21 and flag_is_sprite_to_pick_up set, or inferred from link_item_in_hand/pose fields — this composite is not a single field; state 21 alone is shared by item-get poses too, so distinguish via context (module/submodule + which item fields are nonzero).

3. Health, magic, currency, and the full inventory block ($7EF340..)

Important structural note, confirmed from source: this $7EF3xx block is WRAM that mirrors what gets written to SRAM on save — zelda3 names every field with a link_ prefix directly in variables.h at these live addresses (not a separate "SRAM shadow" struct); i.e. reading $7EF36D from a live emulator gives you Link's current HP right now, same address space, no indirection needed.

Compass/Big-Key/Dungeon-Map bit layout (all three share one bit order; each is 2 bytes, low byte = "SET 1", high byte = "SET 2"). Per jpdasm's explicit documentation (jpdasm/symbols_sram.asm:719-736, comment above COMPASS1/COMPASS2):

   SET 2        SET 1
xced aspm    wihb tg..

• SET 1 (low byte, e.g. $7EF364 for compass): 0x80=SkullWoods(w), 0x40=IcePalace(i), 0x20=TowerOfHera(h), 0x10=ThievesTown(b), 0x08=TurtleRock(t), 0x04=Ganon'sTower(g); low 2 bits unused
• SET 2 (high byte, e.g. $7EF365 for compass): 0x80=Sewers(x), 0x40=HyruleCastle(c), 0x20=EasternPalace(e), 0x10=DesertPalace(d), 0x08=Agahnim'sTower(a), 0x04=SwampPalace(s), 0x02=PalaceOfDarkness(p), 0x01=MiseryMire(m)

Applies identically to link_bigkey ($7EF366/367) and link_dungeon_map ($7EF368/369). Cite: jpdasm/symbols_sram.asm:719-736.

Bombs vs. arrows asymmetry (confirmed): bombs have no separate "owned" boolean — link_item_bombs at $7EF343 IS the live count (in the same slot layout as boolean-item flags 340-357). Arrows are split: bow-owned is $7EF340, but the actual arrow count lives separately at $7EF377 (link_num_arrows), outside the contiguous item-flag block. This is a real asymmetry in the data model, not a simplification — a harness reading "does Link have arrows to shoot" must check $7EF377 > 0, not $7EF340.

4. Location

Coordinate convention: link_x_coord/link_y_coord ($7E0022/$7E0020) are used identically for overworld and dungeon movement — the same absolute pixel-coordinate fields, just interpreted relative to whichever map (overworld screen vs. dungeon room) is currently active per player_is_indoors. There is no separate "dungeon-local coordinate" field; the room/screen id ($7E00A0 or $7E008A) plus the pixel position together locate Link. This is confirmed structurally by both fields being used unconditionally throughout src/player.c and src/overworld.c/src/dungeon.c without an indoor/outdoor coordinate switch.

5. Sprites, enemies, and ancillae (projectiles)

Researched via a dedicated pass over zelda3 src/sprite.c, src/sprite_main.c, src/ancilla.c, src/tile_detect.c, src/player.c, cross-checked against jpdasm (JP1.0, incl. its resources/memory_usage_sprite.txt sprite-ID list) and JaredBrian/AsarUSALTTPDisassembly (Other/symbols_wram.asm).

5.1 The 16-slot sprite tables

All fields are 16-slot arrays, slot k at base+k (byte stride 1) — confirmed by the main per-frame loop: Sprite_Main() does for (int i = 15; i >= 0; i--) { cur_object_index = i; Sprite_ExecuteSingle(i); } (zelda3 src/sprite.c:1141-1144), and every field below is indexed array[k] throughout sprite.c/sprite_main.c. (The one exception, sprite_N, is also readable as a 16-bit array sprite_N_word over the same base — stride 2 when read as words, used on the overworld.)

Two single-byte (non-array) fields worth noting: sprite_graphics_index ($7E0AA3, variables.h:601) is a global sprite-graphics-load index unrelated to the per-slot block, and sprite_limit_instance ($7E0B6A, variables.h:659) is a global counter some sprite types (Beamos, Blind's phase) use to index among their own instances.

A cached/"alt" mirror of the eight most important sprite fields exists at $7E1D00 (alt_sprite_state, variables.h:836, one 16-slot array per field through $7E1DF0), used by ExecuteCachedSprites() (src/sprite.c:4130-4193) to save and restore sprite state outside the main per-frame loop — confirmed primary (src/sprite.c:3574,4167) and secondary-labeled "CACHE_0DD0"/"CACHE_0E20" in AsarUSA Other/symbols_wram.asm:5093-5094. A handful of sprite_unk3/unk4/unk5-style fields (variables.h:1216-1221) remain undocumented in all four cloned repos and are marked unverified rather than guessed.

5.2 Alive/active detection — verified from the dispatcher itself

// src/sprite.c:1212-1217
void Sprite_ExecuteSingle(int k) {
  uint8 st = sprite_state[k];
  if (st != 0)
    Sprite_TimersAndOam(k);
  kSprite_ExecuteSingle[st](k);
}

sprite_state[k] != 0 = "slot occupied." sprite_state dispatches into kSprite_ExecuteSingle[12] (src/sprite.c:462-475): 0=inactive, 1=Fall1, 2=Poof, 3=Drown, 4=Explode, 5=Fall2, 6=Die, 7=Burn, 8=Initialize, 9=Active (normal AI), 10=Carried, 11=Stunned. So "alive and running its normal AI" specifically means sprite_state[k]==9, which then dispatches by sprite_type[k] into the per-type handler table (5.4).

5.3 Three-tier alive/dead/never-spawned — verified, matches the harness's needs exactly

Beyond the per-frame sprite_state, there is a persistent per-room permanent-kill bitmask, separate from any live slot:

// src/sprite.c:3632-3636
void Sprite_ManuallySetDeathFlagUW(int k) {
  if (!player_is_indoors || sprite_defl_bits[k] & 1 || sign8(sprite_N[k]))
    return;
  sprite_where_in_room[dungeon_room_index2] |= 1 << sprite_N[k];
}

sprite_where_in_room ((uint16*)(g_ram+0x1DF80) = $7FDF80 — WRAM offset 0x1DF80, which is the form Mesen's snesWorkRam memory type takes; variables.h:1201; overworld alias sprite_where_in_overworld, variables.h:1407) is a bitmask per dungeon room, one bit per spawn-list slot; Dungeon_LoadSingleSprite consults it on room load and never allocates a live slot for an already-permanently-killed spawn. So there are three real states: not-yet-spawned-or-permanently-dead-this-visit (bit set in sprite_where_in_room[room], no live slot at all) / occupies a live slot, sprite_state∈{1-8,10,11} (dying/transitional/carried/stunned) / occupies a live slot, sprite_state==9 (normal alive AI).

Health — a real, generic, shared field exists: sprite_health ($7E0E50). Initialized per sprite type from kSpriteInit_Health[243] (src/sprite.c:138) inside SpritePrep_LoadProperties (src/sprite.c:3967-3971: sprite_health[k] = kSpriteInit_Health[sprite_type[k]]), and decremented by the common idiom sprite_health[k] -= sprite_give_damage[k] used by many (not all) handlers (e.g. src/sprite.c:2409-2413, :2312, :4010; kill-precheck if (sprite_health[k] <= sprite_give_damage[k]), src/sprite.c:779). Individual handlers remain free to repurpose or ignore it for scripted/multi-phase bosses (e.g. Giant Moldorm tests sprite_health[k] < 3 for a phase change, src/sprite_main.c:8262-8289) — the mechanism is generic, per-type usage is bespoke on top of it. Whether the various soldier-guard handlers use only this generic path was not exhaustively confirmed for every soldier function; flagged partially-verified.

5.4 Sprite type ID → name (verified, primary, exhaustively indexed)

Dispatch table kSpriteActiveRoutines[243] (src/sprite_main.c:465-710), indexed directly by sprite_type[k] (SpriteActive_Main, src/sprite_main.c:8257-8260). The array position is the type ID — confirmed by counting entries and cross-matching several IDs embedded in function names (e.g. position 0x41=65 → Sprite_41_BlueGuard; position 0xD8=216 → Sprite_D8_Heart), and independently cross-checked against jpdasm/resources/memory_usage_sprite.txt, which lists the same IDs/names for the JP1.0 build (confirming the ID table is region-invariant).

Pots, bushes, and ordinary dungeon chests are confirmed map/tile objects, NOT sprites — no pot/bush entry exists anywhere in the 243-entry table. Primary evidence: src/tile_detect.c:391-404 handles tile IDs 0x50-0x56 under // TileBehavior_Liftable; src/player.c:35's kLink_Lift_tab[9] = {0x54,0x52,0x50,0xFF,0x51,0x53,0x55,0x56,0x57} keys Link's lift action directly off these tile IDs. Ordinary dungeon chests are likewise tile-driven: src/tile_detect.c:410-422, tile IDs 0x58-0x5D/0x63, gated by array dung_chest_locations ((uint16*)(g_ram+0x6E0) = $7E06E0, variables.h:581) — not the sprite table. (Sprite_B4_PurpleChest above is the one deliberate exception: a roaming quest-item chest, not the per-room treasure mechanic.) When a lifted pot/bush/rock hides a secret, the reveal spawns a genuine new sprite via Sprite_SpawnSecret (src/sprite.c:1065), and a destroyed bush's poof is ancilla type 63 (Ancilla3F_BushPoof, §5.6).

5.5 Ancilla (projectile) table — verified, primary, exhaustive

grep -n "ancilla" src/variables.h: single 10-slot table (loop bound confirmed for (int i = 9; i >= 0; i--), src/ancilla.c:662), base $7E0BF0, stride 0x0A (10) per field:

5.6 Ancilla type IDs — complete, from kAncilla_Funcs[67] (src/ancilla.c:252-320, 1-indexed via ancilla_type-1)

(Full 1-67 table available in the underlying research; this is the subset most relevant to early-game automation. No web search was needed for either the sprite or ancilla ID tables — src/sprite_main.c and src/ancilla.c gave complete, cleanly-named primary tables directly.)

6. Dungeon room state and tile-attribute/collision maps

Researched via a dedicated pass over zelda3 src/dungeon.c, src/tile_detect.c, src/overworld.c, cross-checked against jpdasm/usdasm and JaredBrian/AsarUSALTTPDisassembly/Logs/Zelda_3_SRM.log.

6.1 SRAM room-flags mirror ($7EF000)

save_dung_info ((uint16*)(g_ram+0xF000)) = $7EF000, one 16-bit word per dungeon room (room index 0-0x13F used of a 0x500-byte/0x280-room table — size confirmed by memcpy(..., save_dung_info, 0x500), src/messaging.c:259). Zelda3 src/variables.h:1060.

Bit layout (derived from the save/load code, src/dungeon.c:8059-8064 and :3724-3727), confirmed independently by JaredBrian's Logs/Zelda_3_SRM.log:92-125 which diagrams the identical structure:

bit: 15 14 13 12 | 11  10 | 9  8  7  6  5  4 | 3  2  1  0
      d  d  d  d |  b   k | u  t  s  e  h  c | q  q  q  q

(Corrected/reconciled diagram: an earlier draft of this table mis-split bits 4-9 into "cccc"+"ck"+"cr", which undercounted the chest bits and used undefined labels; the letters above follow jpdasm's own bit-comment, jpdasm/symbols_sram.asm:56-69, and are independently reproduced by the zelda3 evidence below — the two fully agree once read carefully.)

• bits 0-3 (qqqq) = quadrant-visited flags (dung_quadrants_visited, live at $7E0408)
• bits 4-9 (cehstu) = kChestOpenMasks[] = {0x100,0x200,0x400,0x800,0x1000,0x2000} (src/dungeon.c:112, pre-shift bits 8-13, landing at post-shift bits 4-9) — 6 chest-open flags, set in OpenChestForItem (src/dungeon.c:5717-5752). Per jpdasm's naming these are chest slots 0-5 (c,h,e,s,t,u); zelda3's own evidence shows two of the six slots doing double duty in specific rooms — bit 0x800 (chest slot "t"/bit 7... correction, see below) is also reused as water-gate/torches-lit puzzle solved in rooms tagged for it (src/dungeon.c:4772,4809,4828,4840), and bit 0x1000 ("u"/bit 9-equivalent pre-shift) doubles as "special rupee tile obtained" (src/dungeon.c:5698) — jpdasm's own comment says the same thing in different words ("chest 4 / rupee floor / swamp drains / bombable floor / mire wall" for t, "chest 5 / 2nd key / heart piece" for u). This is genuine room-tag-dependent polymorphism, not a labeling error: the same bit means "chest" in a room that has a chest there and something else in a room that doesn't.
• bit 10 (k) = key / heart piece / crystal taken (crystal bit unused for the actual crystal per jpdasm, but still prevents it re-dropping) — pre-shift bit 0x4000
• bit 11 (b) = boss defeated / heart container taken — one single consistent meaning, pre-shift bit 0x8000, set in PrepareDungeonExitFromBossFight (src/dungeon.c:2497), read for crystal/pendant rewards (src/dungeon.c:4584,4596)
• bits 12-15 (dddd) = dung_door_opened — up to 4 unlockable/breakable doors in the room (live at $7E0400)

Live working-register addresses these mirror to/from (loaded from SRAM on room entry, written back on exit/quadrant-cross): dung_door_opened=$7E0400 (variables.h:400), dung_savegame_state_bits=$7E0402 (variables.h:401), dung_quadrants_visited=$7E0408 (variables.h:403), plus a derived (non-persisted) dung_door_opened_incl_adjacent=$7E068C (variables.h:569) that merges in currently-open doors of adjacent rooms. Overworld one-time-event-flags mirror: save_ow_event_info ((uint8*)(g_ram+0xF280)) = $7EF280, one byte per overworld screen (variables.h:1061).

6.2 Current room/dungeon ID — confirmed exactly, with one nuance

dungeon_room_index=$7E00A0, overworld_screen_index=$7E008A, cur_palace_index_x2=$7E040C — all exactly as expected (§4). Nuance: cur_palace_index_x2's raw stored value is the dungeon/palace index already multiplied by 2 (used directly as a word-table index elsewhere, e.g. src/dungeon.c:5717); the real dungeon number is WRAM[$7E040C] >> 1. Independently confirmed by jpdasm's own comment: symbols_wram.asm:2007 — DUNGEON = $7E040C ; "Dungeon IDs, multiples of 2." dungeon_room_index_prev=$7E00A2 (variables.h:113) holds the room being transitioned from, valid during a transition rather than a general history slot.

Cache-vs-live distinction: save_dung_info[room] (§6.1) is the persistent record; dung_door_opened/dung_savegame_state_bits/dung_quadrants_visited are the live working copy for whichever room Link currently occupies, reloaded from the SRAM mirror on room entry and flushed back on exit — reading the SRAM mirror for the current room can be one frame stale; for any other room it's authoritative.

6.3 Dungeon tile attribute / collision map — the core walkability-grid mechanism

Base addresses, both independently confirmed (jpdasm symbols_wram.asm:6002-6003, usdasm bank files):

• dung_bg2_attr_table = $7F2000 (variables.h:1161)
• dung_bg1_attr_table = $7F3000 (variables.h:1162)

(Naming discrepancy only, not a value discrepancy: the disassemblies call $7F2000/$7F3000 "COLMAPA/COLMAPB" or "Layer 1/Layer 2" with the opposite BG-layer label from zelda3's bg2/bg1 naming — the addresses and one-byte-per-8×8-tile mechanism agree exactly across all sources.)

Dimensions: a flat 64×64 grid, one byte per 8×8-pixel cell = 4096 bytes per table (0x1000), the two tables back-to-back ($7F2000-$7F2FFF then $7F3000-$7F3FFF) — i.e. each dungeon room is 512×512 pixels. Confirmed via tilemap_location_calc_mask = 0x1f8 for dungeons (src/dungeon.c:8340,8384).

Encoding: direct byte value read straight into the tile-behavior switch — tile = dung_bg2_attr_table[offs]; TileDetect_ExecuteInner(tile, ...) (src/tile_detect.c:246,253) — not an extra indirection at read time. (It IS populated from a separate ROM-driven lookup, attributes_for_tile = $7EFE00, variables.h:1138, during room construction — confirmed via attributes_for_tile[dung_bg2[i] & 0x3ff], src/dungeon.c:3842 — but by the time Link's tile-detection code runs, the byte in the $7F2000/$7F3000 grid is already the final behavior value, ready to switch on directly.)

Pixel → index formula (exact, from TileDetection_Execute, src/tile_detect.c:240-254):

index = (pixelY >> 3) * 64 + (pixelX >> 3)          // row-major, 64-wide
addr  = $7F2000 + index + (link_is_on_lower_level ? 0x1000 : 0)

Correction, 2026-09-20 — the coordinate must be folded into the room FIRST, and this formula alone will not tell you so. link_x_coord/link_y_coord are absolute across the whole dungeon map, not room-local: Link standing in his own house reads x = 2413, y = 8528. The grid is 512×512 pixels, one room. The engine masks before it indexes — ((link_x + offset) & tilemap_location_calc_mask) >> 3, with the mask set to 0x1f8 for indoors (src/tile_detect.c:37-40; mask at src/dungeon.c:8340,8384) — so the whole formula is:

column = ((x & 0x1F8) >> 3)        // 0..63
row    = ((y & 0x1F8) >> 3)        // 0..63
index  = row * 64 + column

Measured cost of not doing this: every direction reported "wall" and the nearest doorway was "8289 px up and left". The harness was asking a coherent question about a room that did not exist, and nothing in the answers showed it.

Where the engine samples, when Link tries to move (src/tile_detect.c:7-10, 30-61): going up, the row at y + 8; going down, the row at y + 24; going left or right, the column at x + 0 or x + 15. Three points each time — across his width (x + 0, +8, +15) for vertical movement, down his body (y + 8, +16, +23) for horizontal — which it then resolves with sliding rules of its own. A harness that reports the worst of the three makes Link's own shoulder into a wall: standing beside a wall on his right, up, down and right all come back solid. The middle point is the honest one-value summary. link_is_on_lower_level ($7E00EE, §2) is exactly the flag selecting the $7F2000 vs. $7F3000 half.

Attribute value meanings — the switch is real and primary-verified (TileDetect_ExecuteInner, src/tile_detect.c:261-525, a complete switch(tile) over 0x00-0xFF), cross-checked against jpdasm's fully-annotated values.asm:663-870 tile-type comment table:

6.4 Overworld tile attribute / collision — structurally DIFFERENT from dungeons, verified

There is no flat pre-resolved attribute grid for the overworld the way $7F2000/$7F3000 exist for dungeons. Instead: overworld_tileattr = $7E2000 (u16 array, variables.h:1416; aliases the dungeon's dung_bg2 address — mutually exclusive by mode) holds map16 tile IDs, not attribute bytes, in a 32×32 grid (normal screen, 512×512px) or 64×64 grid (a "big" overworld area, 1024×1024px), selected via overworld_area_is_big. Turning a map16 ID into a walkability value requires a two-stage ROM-asset lookup, not WRAM: GetMap16toMap8Table()/GetMap8toTileAttr() (src/overworld.c:246-251, decompressed ROM data via g_asset_ptrs), final value GetMap8toTileAttr()[t & 0x1ff] (src/tile_detect.c:24). The resulting byte feeds into the same TileDetect_ExecuteInner switch as §6.3, just with is_indoors=false selecting a few overworld-only cases (tall grass 0x04, gravestones 0x42). Practical implication for the harness: an overworld walkability grid cannot be read as a single WRAM byte array the way a dungeon room can — either replicate the two ROM lookup tables once (they appear to be static, not verified whether they vary per overworld area) or call the equivalent lookup logic.

Done, 2026-09-20 — the lookup is ported, and the tables are plain ROM. packages/alttp/src/outside.rs implements Overworld_GetTileAttributeAtLocation (zelda3 src/overworld.c:14-28) against whichever ROM the app booted, so nothing is hard-coded:

Both are uncompressed — zelda3's asset build reads them with a bare ROM.get_words/get_bytes, with no decompression step, which is what makes replicating the lookup a dozen lines rather than a project. LoROM stepping is offset = ((addr >> 16) & 0x7F) * 0x8000 + (addr & 0x7FFF), and a read that walks off the top of a bank continues at the NEXT bank's $8000, never its $0000 (assets/util.py:89-116); getting that second half wrong reads eight kilobytes of the wrong bank and yields a map that is almost right.

The coordinate frame comes from WRAM: overworld_offset_base_y = $7E0708, overworld_offset_mask_y = $7E070A, overworld_offset_base_x = $7E070C, overworld_offset_mask_x = $7E070E (zelda3 src/variables.h:584-587), with the map16 ids at $7E2000 (variables.h:1416).

A handful of attribute values mean something else outdoors, and reading them the indoor way makes the overworld unwalkable: 0x04 is tall grass rather than a wall, 0x42 is a gravestone, and the long TileBehavior_NothingOW case list (src/tile_detect.c:261: 0x05-0x07, 0x14-0x17, 0x21, 0x23-0x25, 0x38-0x3C, 0x41, 0x45, 0x47, 0x49, 0x5E-0x5F, 0x61-0x62, 0x64-0x66, 0xA6-0xA7, 0xBE-0xBF, 0xD0-0xEF) is plain ground out there. Verified against the real USA ROM 2026-09-20: standing outside Link's house the harness reads a bush to the left, floor to the right and the stream as deep water to the east.

6.5 Door/stairs tables — ROM-resident per room, not a persistent WRAM table (verified, not assumed)

GetRoomDoorInfo(room) reads from ROM asset tables kDungeonRoom/kDungeonRoomDoorOffs (src/dungeon.c:2256-2258) — confirmed doors are reloaded from ROM per room. A transient per-current-room cache does exist: dung_door_tilemap_address = $7E19A0 (u16 array, variables.h:799), populated from the room's ROM door list until a 0xFFFF terminator on room load (src/dungeon.c:3728-3732) — useful if the harness only needs the doors of the room Link is in right now (exact per-entry bit-packing of position/type not decoded in this pass). Regular-door destinations are structural (the adjacent room in the dungeon's grid layout, via Dungeon_CheckAdjacentRoomsForOpenDoors, src/dungeon.c:3746-3803) rather than an explicit stored target. Explicit non-adjacent warp targets (staircases, holes, block-push warps) ARE WRAM-cached: dung_hdr_travel_destinations = $7EC000 (5 bytes, from room header, src/dungeon.c:3715-3719; address independently re-verified: variables.h:930, (uint8*)(g_ram+0xC000)), consumed at transition points e.g. dungeon_room_index = dung_hdr_travel_destinations[3] (src/dungeon.c:2067) — the index-to-staircase-slot correspondence was not fully traced in this pass, flagged partially-verified. Related staircase-position caches: dung_hdr_staircase_plane=$7E063D (variables.h — 4 entries, 2-bit plane each), dung_stairs_table_1=$7E06B8, dung_stairs_table_2=$7E06EC (variables.h:582,1421) — addresses and stated purpose confirmed, exact per-entry format not fully traced.

7. Dialog / text box / menu detection

Text box open/closed — exact rule, verified from source:

text_box_open := (main_module_index == 14) and (submodule_index == 2)

submodule_index == 2 for module 14 dispatches to RenderText (kMessagingSubmodules[12], index 2 → &RenderText, src/messaging.c:184-197; dispatch RunInterface() at src/messaging.c:308-310). When the box closes, RenderText_Draw_Finish (src/messaging.c:2499-2509) sets submodule_index = 0 and restores main_module_index = saved_module_for_menu — i.e. control returns to whatever gameplay module (7/9/11) was active before the text triggered, confirming saved_module_for_menu ($7E010C) is exactly "the module to check for post-dialog."

Awaiting a button press to advance/close — verified, but not a single flag: the in-message byte-stream commands kTextCmd_Waitkey (23) and kTextCmd_EndMessage (24) are handled inline inside RenderText_Draw_MessageCharacters (src/messaging.c:2469-2490): execution stalls at that command, checking (filtered_joypad_H | filtered_joypad_L) & 0xc0 (Waitkey, A/B mask) or any button at all (EndMessage), and only advances/sets text_render_state = 4 once pressed. There is no separate WRAM boolean meaning "awaiting input" — the practical, reliable harness heuristic is: text_box_open == true and text_render_state has not changed for ≥1 frame while dialogue_msg_read_pos (message byte cursor, not separately tabulated above) is also unchanged — i.e. render is stalled. This is a legitimate engine property (the pause commands are literally spin-loops on joypad state), not a guess, but it is a derived condition rather than one memory cell — flagged accordingly.

Menu/pause-related submodules of module 14 (table kMessagingSubmodules[12], src/messaging.c:184-196, dispatch src/messaging.c:308-310 kMessagingSubmodules[submodule_index]()):

How Start/Select enter module 14 (both confirmed by the same source lines that establish the player-control rule in §1): pressing Start while player_has_control sets submodule_index = 1, saved_module_for_menu = main_module_index, main_module_index = 14 (src/overworld.c:751-758, src/dungeon.c:6595-6601 — identical pattern); pressing the map button similarly sets submodule_index to 3 (dungeon map) or 7 (world map).

Item-get / "fanfare" indicator: not independently isolated as a single dedicated flag in this pass — link_disable_sprite_damage and link_player_handler_state == kPlayerState_HoldUpItem (21) co-occur during an item pickup, but neither is exclusive to that moment (both are shared with other cutscene-like states). Flagged as not cleanly resolved from source in this session — a harness wanting a crisp "item-get fanfare active" signal should treat main_module_index==14 (dialog open, since most item-get text boxes route through the messaging system) combined with link_player_handler_state==21 as the best available composite, not a single verified flag.

8. Intro sequence (file select → rescuing Zelda)

Modules, all verified in §1's table (zelda3 src/misc.c:151-180): Title/attract = module 0 (Module00_Intro) or module 20 (Module14_Attract, entered after idling on the title screen); File select = module 1; Copy file = module 2; Delete file = module 3; Name entry (new file) = module 4; Load file = module 5; first real gameplay module after loading = module 6 (Module_PreDungeon, a brief transition) then module 7 or 9/11 depending on where the save point is.

The opening "asleep in bed" state: kPlayerState_AsleepInBed (value 22, §2) is a named, explicit state in the same enum as Ground/Swimming/etc — this is Link's link_player_handler_state ($7E005D) value during the rainy-night opening in his house before Zelda's telepathic message wakes him. This is a solid, source-named signal for "we're in the very-opening cutscene," found by direct enum inspection (src/player.h:27) rather than a targeted intro-specific search — the mechanism is verified, but this pass did not trace the exact function that sets/clears it (e.g. src/misc.c or a dedicated opening-sequence file) to confirm timing relative to the rain/telepathy dialogue, so treat "state==22 ⇒ specifically the opening bed cutscene" as highly likely but not 100%-source-traced in this pass (the value is real; its exclusivity to the intro specifically, vs. any other "asleep in bed" moment such as a later inn/house sleep, was not separately checked).

Room/entrance/area IDs for the opening segment (Link's house, secret passage, Uncle, Hyrule Castle, rescuing Zelda): UNVERIFIED in this pass. Neither the zelda3 C source (no dedicated "opening sequence" file with named room/entrance constants was located — the intro's room transitions are driven by generic entrance-table data loaded from ROM, not hardcoded named constants in the reimplementation) nor the disassemblies' bank files were searched down to the specific numeric room/entrance IDs for this segment within this session's time budget. This is exactly the kind of fact this estate's sourcing rules require flagging rather than guessing: do not trust any specific numeric value for "Link's house room id" or "secret passage entrance id" until a follow-up pass greps usdasm's rooms.asm/overworlds.asm and/or JaredBrian's per-room files for the vanilla intro's actual constants, or the harness empirically logs $7E00A0/$7E008A/$7E010E while manually playing the opening on a real emulator. The practical, robust alternative already fully verified above: an automation harness can detect "intro complete, first free control granted" purely from state transitions already nailed down here — main_module_index reaching 7/9/11 with submodule_index==0 and the player-control gate flags all clear (§1) — without needing any hardcoded room-id table at all, which is arguably the more robust design for a harness than pinning specific IDs.

First required actions (per the well-known, non-controversial structure of the vanilla opening, not itself a WRAM fact needing citation): wake up → leave the house → go around to the castle's secret passage (bush-covered entrance on the north wall) → navigate to find Uncle wounded → receive sword and shield from him → proceed into the castle → rescue Zelda from the dungeon cell → escape via the sewers/secret passage back out. This sequence description is common knowledge about the game's structure, not a memory-address claim, so it carries no file:line citation and is not treated as equivalent in rigor to the address tables above.

9. ROM identification (verified: zelda3 source code + spannerisms/usdasm README + web search attributed to No-Intro — three independent agreements)

How to apply for the harness: read the loaded file's size; if size % 0x100000 == 0x200, skip the first 512 bytes before treating offsets as raw ROM offsets (WRAM addresses in this document are unaffected either way — WRAM is emulator RAM, not ROM, and has no header). SHA-1 of the (header-stripped) file should equal 6D4F10A8B10E10DBE624CB23CF03B88BB8252973 to guarantee USA v1.0.

Open items — not resolved in this pass, do not treat as answered

1. Exact direction-value mapping for link_direction_facing ($7E002F) — RESOLVED 2026-09-20, from source, not empirically. 0 = up, 2 = down, 4 = left, 6 = right. Two independent places in zelda3 pin it: kDashTab2[] = {8, 4, 2, 1} is indexed by link_direction_facing >> 1 and used as the joypad bits that would continue a dash (src/player.c:1184,1212), and those bits are Up/Down/Left/Right (src/zelda_rtl.h:89-92); and src/misc.c:706-708 sets link_direction = 8 (up) and link_direction_facing = 0 in the same breath. (kGrabWallDirs[] = {4, 8, 1, 2} is indexed the same way and looks inverted; it is the direction that must be HELD to keep a wall grab, not the facing, and is not evidence against the above.) Implemented as alttp::Direction::facing.
2. Intro-segment numeric room/entrance/area IDs (Link's house, secret passage, Uncle's room, Hyrule Castle interior, Zelda's cell) — flagged unverified in §8; the reimplementation drives the intro from generic ROM entrance-table data with no named constants, and this pass did not chase the numeric values down in usdasm's rooms.asm/overworlds.asm. The player-control detection rule in §1 gives a room-id-free way to detect "intro complete" for a harness, which may make this item lower priority than it first appears.
3. Door/staircase entry bit-packing — dung_door_tilemap_address ($7E19A0) and dung_hdr_travel_destinations ($7EC000) addresses and top-level purpose are confirmed (§6.5), but the exact per-entry field-packing (position/type within each door word; which travel-destination array index corresponds to which staircase/hole) was not decoded in this pass.
4. Overworld map16→attribute ROM tables (kMap16ToMap8/kMap8DataToTileAttr, §6.4) — confirmed to be ROM-asset-resident rather than WRAM, but whether they vary per overworld area index (vs. one fixed table for the whole overworld) was not confirmed.
5. A handful of obscure dungeon door sub-type tile values (0x88, 0x8A-0x8D, most of 0x90-0xAF, §6.3) — even jpdasm's own annotated tile-type table marks these uncertain ("(?)"); only the general "this is a door" category is solid for these specific values.
6. Some sprite_unk3/unk4/unk5-style scratch fields (variables.h:1216-1221) and a few alt_sprite_* cache fields in the $7E1FA6C-$7E1FADC range (§5.1) — undocumented in all four cloned repos, not guessed at.
7. Whether every soldier-guard sprite handler uses only the generic sprite_health damage path (§5.3) — no bespoke HP override was found in the handlers read, but not every soldier function body was read exhaustively.
8. Item-get/"fanfare" as a single clean flag (§7) — no dedicated WRAM boolean was isolated; the best available composite (main_module_index==14 + link_player_handler_state==21) is flagged as non-exclusive to that moment.

Everything else in this document — game mode/module enum, the player-has-control rule, Link's position/state-machine fields, the full $7EF340.. inventory block (including the now fully-resolved pendant, crystal, and ability-flag bitfields), location fields, the complete 16-slot sprite and 10-slot ancilla tables with type-ID names, the dungeon room-flag SRAM mirror and its bit layout, the dungeon tile-attribute collision-grid address/formula/value table, dialog/text-box detection, and ROM identification — is verified against at least one primary source (usually two or three independent ones in exact agreement) and cited by file:line above.

10. The way off the overworld — entrance and hole tables (2026-09-20)

A doorway is not a tile. Nothing in the overworld attribute table marks one: 0x8E/0x8F never occur outdoors at all (counted over the 512-entry OverworldTileTypes table in spannerisms/usdasm bank_0E.asm), and 0x8E is an INDOOR attribute meaning "this tile takes Link out to the overworld" (zelda3 src/dungeon.c:2106, :2149, written by door objects at src/dungeon.c:4152, 4166, 4211). What makes a doorway is two table lookups on Link's POSITION, in Overworld_UseEntrance (src/overworld.c:3217-3260) and LookupInOwEntranceTab2 (:263-268).

pos is a map16 index inside the area: pos = tile_y << 7 | tile_x << 1 (assets/compile_resources.py:310, taken apart at assets/extract_resources.py:132), so

x = kOverworld_OffsetBaseX[area & 0x3F] + ((pos & 0x7E) >> 1) * 16
y = kOverworld_OffsetBaseY[area & 0x3F] + (pos >> 7) * 16

The area matched is the HEAD of a big area (overworld_area_index, $7E040A, set from kOverworldAreaHeads, src/overworld.c:840), not the 512-grid quadrant in $7E008A. Matching on the quadrant finds nothing, and finds it silently.

The castle's secret-passage hole, which the whole opening turns on: kFallHole_Area[12] = $001B, kFallHole_Pos[12] = $0170, kFallHole_Entrances[12] = $7D (usdasm $9BB818 / $9BB83E / $9BB858) → tile 56 across, 2 down of the castle's big area → world (2432, 1568), leading to room $0055. Cross-check: the castle's walk-in secret entrance (id $32, world (2240, 1744)) opens into the same room, and the exit table puts Link back beside the DOOR, not the hole - you fall in one way and walk out the other.

The overworld's area geometry

kOverworld_OffsetBaseX/Y[64] (zelda3 src/overworld.c:15-33, ROM $82A8C4/$82A944) give the origin of the AREA a screen belongs to, so a quadrant of a big area returns the big area's corner. A big area is exactly four screens sharing an origin, which is how packages/nav/src/world.rs derives it rather than carrying kOverworldMapIsSmall as a second source that could disagree. $7E070C (base_x) is in EIGHTHS of a pixel-column while $7E0708 (base_y) is in pixels (src/overworld.c:868), and masks are 0x3F0/0x7E big, 0x1F0/0x3E small (:870-872).

Walking off an edge: OverworldHandleTransitions (src/overworld.c:790-852) adds ±1 or ±8 to the area index and then collapses it through kOverworldAreaHeads; a big area transitions only at its outer 1024-pixel boundary, never at an internal quadrant seam.

Liftables, named and gated

kTile50data (src/tile_detect.c:392) orders the seven, and kGetBestActionToPerformOnTile_a[i] - link_item_gloves <= 0 (src/player.c:5496, 5531) decides whether Link is strong enough. usdasm's id list at $07DE70 and LiftableGloveLevels at $07D375 name them and agree byte for byte:

Pots are NOT in this range: a dungeon's liftables are $70-$7F, whose low nibble indexes dung_replacement_tile_state, translated back into this family by kDungeon_QueryIfTileLiftable_rv (src/dungeon.c:125).

Ledges are one-way, and the tile says which way

TileBehavior_Ledge_*, src/tile_detect.c:346-365: $28 north, $29 south, $2A/$2B east-west (one shared case, so the tile alone does not say left from right - the engine takes the direction from which probe hit), $2C/$2E north-diagonal, $2D/$2F south-diagonal. The commonly cited alttp.run wiki split of $2A-$2E into four separate directions does not match the ROM.

Overworld holes

Only $20 occurs outdoors. $B0-$BD share the pit case in TileDetect_ExecuteInner but never appear in the overworld attribute table - they are the Cane of Somaria's platform tracks, and are dungeon-only. The pit handler reads no destination from the byte; the destination is Overworld_GetPitDestination's position-plus-area lookup above.

Chests: opened or not

A chest tile is $58-$5D (plus $63), and tile - 0x58 is its slot. dung_chest_locations[slot] & 0x8000 distinguishes a big-key LOCK from a chest (src/tile_detect.c:413, set at src/dungeon.c:4043). Whether it has been opened is bit 4 + slot of the room's save word (§6.1, kChestOpenMasks, src/dungeon.c:112).