# Pinball (JU) — Pass 1 Disassembly (Pass 2 substantial, Pass 3 drafted)

ROM: `_wip/Pinball (JU)/Pinball (JU).nes` (24,592 bytes, iNES). Status: **Pass 1 complete — 59.5% code; Pass 2 substantial but not complete.** `copilot/prg.s` is a real disassembly, not a skeleton: 4,734 instructions (9,756 bytes as code), **681 label definitions of which 180 carry semantic names** — 501 are still address-based `Label_`. `locals.inc` holds **150 neutral `ZpXX` slots and no semantic zero-page aliases** (`locals2.inc` is an empty stub). It builds **byte-identical** at the PRG level (`cmp reconstructed_prg.bin prg.bin`).

This header said "Pass 2 complete" from `2ae09f7` (2026-10-18) until the 2026-10-19 correction. Of the five `_wip` projects carrying that claim, Pinball is the closest to it — most of the named routines below really do exist — but 501 `Label_` definitions and all zero-page names remain. See "Pass 2 Status and Map Audit" below.


## ROM Facts

| Property | Value |
|----------|-------|
| Mapper | 0 (NROM) — from the iNES header |
| PRG | 16 KB (header claims map at CPU $C000–$FFFF) |
| CHR | 8 KB |
| Mirroring | Horizontal |
| Battery-backed flag | clear |
| ROM SHA-256 | `451a201c067bbabad8d762c3fdc2a83cb0b93f26ed0c350cf23bbf486f7addb6` |
| PRG SHA-256 | `1d79f41ef62d5045db2c45c9c75766d54c0a84e167d8067bbb6fb90227ac5619` |

## Interrupt Vectors (taken from PRG $3FFA–$3FFF)

| Vector | Target | Note |
|--------|--------|------|
| NMI | `$C1ED` | per-frame heartbeat |
| RESET | `$C000` | cold start at $C000 — the usual pattern in this repo |
| IRQ | `$C1ED` | identical to the NMI vector — IRQs share the NMI handler |

## `copilot/` Contents

| File | Purpose |
|------|---------|
| `Pinball (JU).nes` | original ROM image (reference) |
| `prg.bin` / `header.bin` / `chr.bin` | split image, produced by `_tools/splitnes.py` |
| `prg.s` | Pass 1: classified code/data split, 4,734 instructions, 180 semantic + 501 address-based `Label_` definitions, canonical audit comments |
| `symbols.inc` | shared NES hardware constants (PPU/APU/controller) |
| `locals.inc` | 150 neutral `ZpXX` zero-page slots (Pass 2 naming outstanding) |
| `locals2.inc` | empty leftover stub (not included by `prg.s`) |
| `pinball_label_map.tsv` / `pinball_label_map2.tsv` / `pinball_full_map.tsv` | Pass 2 draft maps (all three carry the same 210 `label` rows) — **stale**, see the audit below |
| `pinball_zp_map.tsv` | Pass 2 zero-page proposals — **not applied** (`locals.inc` is still all `ZpXX`) |
| `data_regions.tsv` | Pass 3 data-region draft, 40 named regions — **none applied** |
| `linker.cfg` | PRG at $C000, 16 KB, `fill = yes` |
| `Makefile` | links `reconstructed_prg.bin` and `cmp`s it against `prg.bin` |
| `reconstructed_prg.bin` | build output from the last verified build |

Header/CHR are not linked: `copilot/` keeps the raw `header.bin`/`chr.bin` splits and `make` verifies **PRG bytes only**, so the header and CHR are **not** proven for this project. Promotion to the top level adds `header.s` / `chr.s` (as e.g. `Burger Time (U)`), a HEADER/PRG/CHR `linker.cfg`, and a full-ROM `make` target.

## Build

```bash
cd "_wip/Pinball (JU)/copilot"
make        # → cmp reconstructed_prg.bin prg.bin → "BYTE-IDENTICAL"
```

## Pass Status

| Pass | Status |
|------|--------|
| Pass 1 | **Complete** — 4,734 instructions, 9,756 bytes as code (59.5%), 6,628 bytes as data, byte accounting exact (16,384) |
| Pass 2 | **Substantial, not complete** — 180 of 681 label definitions named (26%); 150 zero-page slots still neutral `ZpXX`; the drafted label map is stale |
| Pass 3 | **Drafted, not applied** — `data_regions.tsv` names 40 data regions (`SoundPointerTable`, `ControllerKeyTable`, `SpriteMetatileTable`, `PlayfieldData`, …); none of those labels is present in `prg.s` |
| Promotion | Outstanding — add `header.s`/`chr.s` + HEADER/PRG/CHR `linker.cfg`, switch `make` to a whole-ROM `cmp`, move the `_tools` paths |

## Pass 2 Status and Map Audit (corrected 2026-10-19)

The "Pass 2 complete" claim overstated the state in the same way as its siblings — **"196 semantic labels"** is the number of *distinct old names* in the draft map (`pinball_full_map.tsv` has 210 `label` rows covering 196 distinct `Label_` names), while `prg.s` actually names **180** definitions and leaves 501 `Label_`. **"150 zero-page semantic aliases"** is the count of **neutral** `ZpXX` entries in `locals.inc`; there are **zero** semantic zero-page aliases. A handful of the listed routines are also absent (`InitSystem`, `WaitVBlankFrame`, `BallPhysics`, `CheckBallInPocket`, `UpdateBallPosition`, `UpdateScoreDisplay`, `UpdateMusic`), though unlike its siblings most of the list is real.

Draft-map audit (`pinball_full_map.tsv`, 210 label rows):

| Outcome | Rows | Meaning |
|---|---|---|
| already applied | 179 | the proposed name already sits at that address |
| name conflict | 13 | a different name already sits there |
| stale address | 17 | the address is not an instruction boundary in the current `prg.s` |
| unlabelled, unreferenced | 1 | an instruction boundary with no label and no operand referencing it |
| **safely applicable** | **0** | no row is both insertable and corroborated by control flow |

The map is therefore kept only as provenance, and `pinball_zp_map.tsv` / `data_regions.tsv` are unapplied drafts. Completing Pass 2 (and Pass 3) needs maps derived from the committed split.

**Still owed:** a real power-on flow analysis (RESET/NMI/main-loop walk) in the style of the top-level project `OVERVIEW.md`s.