tmerritt
71ada15de0
Pass 3 named the 10 data regions in prg.s, then the project was promoted
out of _wip/ so `make` now proves header + PRG + CHR against the original
ROM instead of only the PRG bank.
Data regions named:
LevelPtrTable $C000-$C03B (60 B) level header data
ObjectPtrTable $C03C-$C043 (8 B) 4 pointer pairs
LevelDataPtrTable $C044-$C79D (1882 B) level data pointers
SpriteInitPtrTable labelled at $C4B0 see residue note
UnreachedCode_D650 $D650-$D696 (71 B) unreached code
UnreachedCode_E144 $E144-$E165 (34 B) unreached code
MusicDataTable $F55B-$FA47 (1261 B) music/sound data
APUDataTable $FAE6-$FB74 (143 B) APU pulse/noise tables
SfxDataTable $FE59-$FFEF (407 B) sound-effect data
VectorTable $FFF6-$FFFF (10 B) padding + NMI/RESET/IRQ
Promotion (per the AGENTS.md checklist):
- git mv "_wip/Donkey Kong (JU)" "Donkey Kong (JU)"
- add copilot/rom.nes -> ../Donkey Kong (JU).nes symlink
- add header.s / chr.s (one-line .incbin of header.bin / chr.bin)
- linker.cfg gains HEADER ($0000/16 B) and CHR ($0000/8 KB)
- Makefile switched from `cmp reconstructed_prg.bin prg.bin` to
`cmp reconstructed.nes rom.nes`
- no _tools path change (this Makefile never referenced _tools/)
and no `make regen` pipeline exists for it
Doc corrections:
- project OVERVIEW.md said Mirroring Vertical; header byte 6 = $00
means Horizontal (the root index was right) — fixed
- root OVERVIEW.md: row 18 now BYTE-IDENTICAL, tier paragraph and
summary table refreshed (they had drifted around the Lunar Pool and
Urban Champion promotions), new per-project detail entry
- counts corrected to 19 top-level / 17 _wip in OVERVIEW.md,
TODO.md and AGENTS.md
Residue recorded rather than guessed:
- Pass 2 is partial: 919 Label_ definitions remain (214 semantic
labels applied); noted in TODO.md so nobody reads the promotion as
full semantic naming
- SpriteInitPtrTable's label sits at $C4B0: the routine at $C807 reads
$C4A7,x/$C4A8,x, but that table starts mid-row and a label there
would split the canonical 16-byte audit-comment line
Verification:
make clean && make -> "Byte-identical ROM verified."
verify_pass1.py -> 19/19 top-level build, Donkey Kong (JU) OK
(6014 instr / 12505 B), all comments canonical
Doc-drift sweep: build tiers, mirroring, and stale status tails
Reconciled the docs against verified reality after the Lunar Pool / Urban
Champion / Donkey Kong (JU) promotions and the 2026-10-19 audit-comment
standardization. No source behaviour changed except the two build fixes below.
Build tier (whole-ROM vs PRG-only)
- AGENTS.md: the 17 `_wip/` projects are real disassemblies at the PRG-build
tier, not "skeletons"; header.s/chr.s/rom.nes are promotion additions;
verify_pass1.py covers the top-level projects.
- Root OVERVIEW.md: `_wip` prose, audit-comment narrative and summary table
refreshed (37.5% figure, SEEDED vs OK wording, re-trace false alarm).
- Promoted projects whose build blocks still claimed `make` emits
`reconstructed_prg.bin` compared to `prg.bin` (Balloon Fight, Baseball,
CIRCUS, Clu Clu Land, Excitebike, NES PowerPad, Pac-Man (USA), Tennis):
now describe the whole-ROM `reconstructed.nes` vs `rom.nes`.
- Lunar Pool / Urban Champion / CIRCUS also had stale `cd "_wip/..."`
build paths and "Promotion" items; retargeted to their top-level folders.
Mirroring (header byte 6 bit 0: 0 = Horizontal, 1 = Vertical)
- Corrected DK Jr. prose "horizontal mirroring (flag 6 = $01)" -> vertical,
and both `_wip/Pac-Man` variant notes "Both use vertical mirroring" ->
horizontal (both are byte-6 = $00).
- Re-audited every project OVERVIEW: 0 rows and 0 prose claims now disagree.
Stale status tails
- Retitled/restatused the `_wip` OVERVIEWs to their real `prg.s` (Golf,
Ice Climber (U), Lode Runner, Millipede, Pac-Man Tengen, Pac-Man (U),
Popeye 0/1, Raid, Raid a2, Hogan's Alley, Mario Bros); Golf's
skeleton-era contents rows and Next Steps corrected.
- Dropped the skeleton-era "## Next Steps (per `PROMPTS.md`)" heading and
the "(from the skeleton)" wording across all project OVERVIEWs.
- Rewrote Lunar Pool / Urban Champion Next Steps (both already Pass 1-3
complete and promoted; their tails still described pending Pass 2 and
promotion); fixed root row 13 (Wild Gunman) and row 20 (Duck Hunt).
Also lands two code fixes carried with this sweep:
- `_wip/Hogan's Alley (JU)`: $E9F1-$E9FD and $EA13-$EA14 reclassified as
data with canonical audit comments (the seeded build had decoded a data
table base as code, breaking the build since 2ae09f7). `make` ->
BYTE-IDENTICAL again; reconstructed_prg.bin/.lbl refreshed.
- `_wip/Pyramid (U)`: `Label_D72E` -> `NMI:` (byte-identical).
Verification:
make (Hogan's Alley, Pyramid) -> BYTE-IDENTICAL, BYTE-IDENTICAL
_tools/verify_pass1.py -> 19/19 build, all canonical,
"No truncated or unfaithful Pass 1"
mirroring audit (rows + prose) -> 0 mismatches
Donkey Kong (JU): complete Pass 2 — all 919 Label_ definitions named
The last non-zero Label_ residue in the repo is now gone. Every one of the
919 address-derived definitions in copilot/prg.s is replaced:
* 319 routine entry points (jsr/jmp targets):
- 102 named from observed behaviour (LoadSpriteInitPointerToZp00 $C807,
CopyVramDataToBuffer $CBDF, CheckSpriteListCollision $D8AD,
UpdateRandomSeed $F4ED, ReadControllers $F50E, UpdateSoundEngine $FA48, ...)
- 217 left as SubC<addr> — honest residue where the body is too
context-dependent to name without guessing (Golf: 108, Mario Bros: 223)
- the 77 already-named entries untouched
* 600 internal branch targets named <Routine>_Block / <Routine>_Block_n in
address order within their owning routine (DK Jr./Balloon Fight convention).
Ownership is control-flow containment, so a loop that physically precedes
its own entry lands correctly (FlushPpuBuffer_Block $F1EC under $F228).
* Two proposal collisions disambiguated by indexing zero-page slot:
UpdateObjectListZp5D/DispatchObjectStateZp5E ($DA16/$DA4C) vs
UpdateObjectListZpAE/DispatchObjectStateZpAF ($E1E9/$E250).
jsr/jmp operands stay numeric (Wild Gunman style); only branch operands are
symbolic. Applied with _tools/pass2.py apply (919 defs + 2,622 refs rewritten,
comments re-aligned); the ROM still rebuilds byte-identically and
verify_pass1.py reports 19/19 canonical with no truncated split.
Docs synced: project OVERVIEW.md gains a Pass 2 Details section, root
OVERVIEW.md rows + conventions, TODO.md section 4 closed. dk_full_map.tsv now
records the complete applied map (its zp rows remain unapplied proposals).
_wip status correction: five false "Pass 2 complete" claims + map audit
The `_wip` tier's "Pass 2 complete" headers counted their draft maps' rows, not
the names actually present in `prg.s`, and described the count of *neutral*
`ZpXX` slots in `locals.inc` as "zero-page semantic aliases". Verified against
the sources and corrected in the root inventory rows, the project OVERVIEWs and
TODO:
project named/total Label_ left drafted map
Pinball (JU) 180 / 681 501 210 rows, 179 applied
Ice Climber (JE) 76 / 973 897 255 rows, 76 applied
Donkey Kong Jr. Math 64 / 1035 971 243 rows, 62 applied
Duck Hunt (JUE) 31 / 472 441 272 rows, 31 applied
Ice Climber (U) 2 / 973 971 none - Pass 2 not started
No `_wip` project is Pass 2 complete. Ice Climber (U) was the worst case: the
2026-10-19 sweep itself restated it "Pass 2 complete" while describing its 971
`Label_` definitions in the same paragraph - a copy-paste from (JE); (U) has no
map file at all.
Drafted maps audited row by row against the committed split: they are not
applicable. 100/243 (DK Jr. Math), 96/255 (Ice Climber (JE)) and 17/210
(Pinball) rows point at addresses that are not instruction boundaries - they
were built against an older code/data split - while most of the rest are
unlabelled boundaries that no operand references, or (Duck Hunt) competing
candidate names for one label (`Label_C2BF` alone carries 205). Rows that are
both insertable and corroborated by control flow: 0 in every map. Recorded as
stale and kept for provenance; Pass 2 here needs a fresh map derived from the
committed split.
Also corrected while verifying:
- Mario Bros entry counts (docs said 252 / 90 + 165 / 477 sites / 156 neutral
slots; the file holds 262 distinct `jsr`/`jmp` targets = 39 semantic + 223
`SubC<addr>`, 478 sites, 151 slots).
- root `_wip` prose line/label ranges (4,482-17,180 lines, 192-971 `Label_`,
11,126 total) and the Ice Climber code figure (74.6% / 6,112 instr, not
74.7% / 6,113).
- TODO §4 re-scoped to the promoted tier, with the `_wip` residue table added.
Verification: `make` across all 17 `_wip` projects -> BYTE-IDENTICAL (17/17);
`_tools/verify_pass1.py` -> 19/19 build, all canonical, "No truncated or
unfaithful Pass 1 found". No source bytes changed.
Balloon Fight (JU): apply locals.inc/symbols.inc names to prg.s (Pass 3)
Substitutes symbol names for 922 numeric operands: 125 hardware registers
(symbols.inc) and 797 of 813 zero-page/RAM operands (locals.inc). The 15
multi-alias addresses were resolved per routine; 16 operands stay numeric
because $13 is used there as a plain high-byte scratch beside Temp12 and
none of its three aliases fits.
- _tools/apply_symbols.py: the substitution tool (dry run by default;
--sites supplies per-routine choices for multi-alias addresses, --report
lists the residue). Only the operand token is rewritten, so the
`; CPU:$.... PRG:.... XX XX` audit comments survive byte for byte.
- prg.s: operand tokens only. make prints "Byte-identical ROM verified."
- OVERVIEW.md (project): instruction quotes now match prg.s, new
alias-reuse table, and section 10 rewritten from the stale "497 Label_"
prose to the real naming state and the 16-site residue.
- OVERVIEW.md (root), TODO.md, AGENTS.md: status, counts, tool list.
verify_pass1.py: 19/19 OK, all audit comments canonical.
Bomberman (U): apply locals.inc/symbols.inc names to prg.s (Pass 3)
Substitutes 362 zero-page operands in copilot/prg.s with the names already
declared in copilot/locals.inc: 354 from single-name addresses and 8 from the
two multi-alias addresses, resolved per site:
$E0/$E1 IndirectPtrLo/Hi in the RAM-clear loop
(InitializeSystemAndRunMainLoop -> Main_WriteSoundDispatchIndex_C317,
which writes $00 across $0100-$07FF via (ptr),y),
SoundDelay0 (the base of the per-channel delay table, indexed by X)
in the sound engine;
No symbols.inc substitution was needed: copilot/prg.s contains no numeric
hardware operands ($2000-$4017) at all. All 362 operands were already written
with two hex digits, so no ca65 `a:` prefix was required.
make -> Byte-identical ROM verified. Operand token only; mnemonics, spacing and
the trailing `; CPU:$.... PRG:.... XX XX` audit comments are untouched.
Remaining numeric operands (758) address bytes that no .inc file names:
505 zero-page (133 addresses), 171 RAM $0100-$07FF (46 addresses) and 82
table reads in $8000+ (54 addresses).
Bomberman (U): substitute 24 in-file table labels at ROM operand sites
Uses the new `--labels` option of `apply_symbols.py` with the
ld65 `-Ln` output (`reconstructed.lbl`). Only labels that prg.s
actually defines and that live in the PRG (+) are considered,
so CHR/header segment labels cannot leak in.
24 numeric operands (`lda ,x`, `adc ,y`, etc.) now read
`lda SystemPaletteData,x`, `adc GameplayObjectClassTable,y`, etc.
All 24 point at exact label addresses; the remaining 58 ROM-space
numeric operands point at interior bytes or unlabelled tables and
stay numeric.
make -> Byte-identical ROM verified.
Bomberman (U): update docs for Pass 3 symbol application
- Project OVERVIEW.md: corrected source file from main.s to prg.s/header.s/chr.s;
output name from reconstructed_bomberman.nes to reconstructed.nes;
rewritten §10 Zero-Page/RAM Symbols table to match locals.inc (with aliases
and unnamed residue documented);
fixed §4 step 1/4 to use IndirectPtrLo/Hi and SoundDelay0 names;
fixed §11 InesHeader location (now header.s);
added §2 Pass 3 summary table;
added §13 notes on legacy main.s and Main_WriteSoundDispatchIndex_C317 misnomer.
- Root OVERVIEW.md §3: updated source line count (7,553), file list, and added
Pass 3 summary.
Both builds verified byte-identical.
Pass 3 symbol application to all 19 top-level projects (2026-10-19)
Ran _tools/apply_symbols.py --write on all 19 promoted projects to substitute
symbolic names from symbols.inc (hardware registers) and locals.inc (zero-page
RAM aliases, forward references) into prg.s operands. The tool preserves the
canonical audit comments (; CPU:$XXXX PRG:XXXX AA BB) and preserves byte
identity — all projects still rebuild byte-identical to their original ROMs.
Per-project operand substitutions:
Baseball (UE) 121 (85 single + 36 hardware)
Tennis (JU) 18 (18 single)
Pac-Man (USA) (Namco) 524 (524 single; 727 multi-alias residues)
CIRCUS 118 (38 single + 80 hardware; 23 multi-alias residues)
Wild Gunman (U) 76 (11 single + 65 hardware)
Joypad Test Cartridge (U) 47 (47 hardware)
NES PowerPad Test Card (U) 89 (89 hardware)
MUSCLE (U) 220 (91 single + 129 hardware)
Lunar Pool (U) 45 (18 single + 27 hardware)
Donkey Kong (JU) 75 (17 single + 58 hardware)
Urban Champion (JU) 70 (4 single + 66 hardware)
Already had symbols applied: Balloon Fight, Bomberman, Burger Time,
Clu Clu Land, Defender 2, Donkey Kong 3, Donkey Kong Jr.
Skipped: Excitebike (JU) — inline prg.s definitions conflict with locals.inc
values and source operands don't match ROM byte encodings; automatic
substitution breaks byte identity.
Documentation updated:
OVERVIEW.md — added Pass 3 symbol notes to all 19 project entries,
added Urban Champion as section #36
TODO.md — current state now reflects complete symbol application across
the promoted tier
Verification: python3 _tools/verify_pass1.py reports all 19 projects OK/SEEDED,
all canonical comments, no truncated or unfaithful Pass 1.
222 lines
11 KiB
Markdown
222 lines
11 KiB
Markdown
# NES PowerPad Test Card (U) — Game Flow from Power-On
|
||
|
||
This document describes the execution flow of the disassembled NES PowerPad Test Card (U) PRG bank (16 KB, mapped at CPU **$C000–$FFFF**), starting from power-on. It is based entirely on `copilot/prg.s` in the repository. The rebuild is verified **byte-identical** to the original `prg.bin`.
|
||
|
||
---
|
||
|
||
## 1. ROM and Memory Layout
|
||
|
||
| Property | Value |
|
||
|----------|-------|
|
||
| Format | iNES |
|
||
| PRG | 1 × 16 KB (mapped at CPU $C000–$FFFF) |
|
||
| CHR | 1 × 8 KB |
|
||
| Mirroring | Vertical |
|
||
| PRG bank start | CPU $C000 |
|
||
| Source file | `copilot/prg.s` (~1,650 lines with headers) |
|
||
| Output | `reconstructed.nes` (whole ROM: 16-byte header + 16,384-byte PRG + 8,192-byte CHR) |
|
||
|
||
### Interrupt vectors (CPU $FFFA–$FFFF)
|
||
|
||
| Vector | Address | Handler |
|
||
|--------|---------|---------|
|
||
| NMI | $E06E | `NmiHandler` |
|
||
| RESET | $E000 | `Reset` |
|
||
| IRQ / BRK | $E000 | Reuses `Reset` |
|
||
|
||
---
|
||
|
||
## 2. Build Status
|
||
|
||
`make` in `copilot/` assembles `prg.s` with `ca65`, links with `ld65`, and verifies against `prg.bin`.
|
||
|
||
**Verification result: BYTE-IDENTICAL** — `reconstructed.nes` matches `rom.nes` exactly (header + PRG + CHR).
|
||
|
||
---
|
||
|
||
## 3. Pass Status
|
||
|
||
| Pass | Status | Description |
|
||
|------|--------|-------------|
|
||
| Pass 1 | Complete | Code/data split — entire PRG bank classified as traced code (~7.2%) or explicit `.byte` data (~92.8%) with `; CPU:$xxxx PRG:$xxxx` annotations |
|
||
| Pass 2 | Complete | Routine headers added for all labeled positions; key routines semantically named (`Reset`, `NmiHandler`, `VramWrite`, `ReadPad`, `ProcessPads`, etc.); zero-page aliases in `locals.inc` |
|
||
| Pass 3 | Complete | All data tables named: `VramWriteSourcePointerTable` ($F000, 9 streams), `Player1TileTable`/`Player2TileTable` ($E4B4/$E4C0), `PaletteData` ($E121), and all nine VramWrite payload streams (`PowerPadSideAButtonGraphics`, `PanelFrameTiles`, `StatusMessageText`, `SideATestPromptText`, …). Screen text decoded from CHR. Remaining 46 `Label_Exxxx` are internal loop/branch targets. |
|
||
|
||
---
|
||
|
||
## 4. Reset — CPU $FFFC → $E000
|
||
|
||
**`Reset`** ($E000)
|
||
|
||
On power-on or reset:
|
||
|
||
1. Calls a chain of initialization subroutines in sequence:
|
||
- `ResetInit` ($E09B): sei/cld, disable PPU rendering, wait for two vblanks
|
||
- `ClearRAM` ($E0C9): clear 8 pages of zero-page RAM
|
||
- `ClearVRAM` ($E0EB): clear nametable memory
|
||
- `LoadPalette` ($E107): load 32 bytes of palette data into PPU palette RAM
|
||
- `ClearVRAM_Fill23` ($E142): fill VRAM with $23 (blank tile attribute)
|
||
- `InitAPU` ($E16B): initialize APU pulse/triangle channels
|
||
- `ClearVRAM_FillFF` ($E187): fill VRAM with $FF
|
||
- Five `LoadPatternTable` routines ($E19A–$E1CB): load pattern tables from $F000 region
|
||
- `SetPPUCTRL_NMI` ($E219): enable NMI bit in PPUCTRL
|
||
2. **Main loop** (`Label_E058` at $E058): calls `ClearScreen` ($E4FA), `WaitForVBlank` ($E092), checks `$07` (frame counter high nibble), loops back to $E000 if zero, otherwise calls `ResetScroll` ($E22D) and jumps back to $E058.
|
||
|
||
**Key point:** The main loop is driven by vblank waits and frame counter checks. All per-frame work (controller reading, pad processing, screen drawing) happens inside the NMI handler.
|
||
|
||
---
|
||
|
||
## 5. NMI / Frame Heartbeat — `NmiHandler` ($E06E)
|
||
|
||
The NMI fires once per frame:
|
||
|
||
1. **Save registers** (`PHA / TXA / PHA / TYA / PHA`).
|
||
2. Calls `DisableNMI` ($E1FB) — clears NMI bit in PPUCTRL shadow.
|
||
3. Increments `Zp03` (frame counter).
|
||
4. Reads `PPUSTATUS` ($2002), stores to `Zp02` (vblank flag).
|
||
5. Calls `ReadPad` ($E338) — reads controller pad data.
|
||
6. Calls `ShiftPads` ($E362) — shifts pad data into state variables.
|
||
7. Calls `ProcessPads` ($E398) — processes pad transitions, updates scores.
|
||
8. Calls `DrawScore` ($E3E1) — draws score digits.
|
||
9. Calls `DrawLives` ($E407) — draws lives indicators.
|
||
10. **Restore registers** (`PLA / TAX / PLA / TAY / PLA / RTI`).
|
||
|
||
---
|
||
|
||
## 6. Key Subroutines
|
||
|
||
| Label | Address | Description |
|
||
|-------|---------|-------------|
|
||
| `Reset` | $E000 | Cold-start initialization and main loop entry |
|
||
| `NmiHandler` | $E06E | Per-frame NMI: pad read, process, score/lives draw |
|
||
| `WaitForVBlank` | $E092 | Waits for vblank flag, clears it |
|
||
| `ResetInit` | $E09B | Cold-start hardware init (PPU, APU, vblank waits) |
|
||
| `ClearRAM` | $E0C9 | Clears 8 pages of zero-page RAM |
|
||
| `ClearVRAM` | $E0EB | Clears nametable memory with zeros |
|
||
| `LoadPalette` | $E107 | Loads 32-byte palette into PPU palette RAM |
|
||
| `ClearVRAM_Fill23` | $E142 | Fills VRAM with blank tile value $23 |
|
||
| `InitAPU` | $E16B | Initializes APU pulse/triangle channels |
|
||
| `ClearVRAM_FillFF` | $E187 | Fills VRAM with $FF |
|
||
| `LoadPatternTable1`–`5` | $E19A–$E1CB | Load pattern tables from $F000 region |
|
||
| `VramWrite` | $E1CC | Generic VRAM write via indirect pointer |
|
||
| `EnableNMI` | $E1F1 | Enables NMI bit in PPUCTRL shadow |
|
||
| `DisableNMI` | $E1FB | Disables NMI bit in PPUCTRL shadow |
|
||
| `SetPPUCTRL_NMI` | $E219 | Sets NMI bit ($80) in PPUCTRL shadow |
|
||
| `ResetScroll` | $E22D | Resets PPU scroll X/Y to zero |
|
||
| `InitRoundParams` | $E236 | Initializes round parameters |
|
||
| `DrawPlayer1Pad` | $E270 | Draws player 1 pad indicators |
|
||
| `DrawPlayer2Pad` | $E2B0 | Draws player 2 pad indicators |
|
||
| `ClearRows` | $E2F0 | Clears screen rows with blank tiles |
|
||
| `ClearGameVars` | $E32D | Clears game variables $06–$09 |
|
||
| `ReadPad` | $E338 | Reads controller pad via shift register |
|
||
| `ShiftPads` | $E362 | Shifts pad data into state variables |
|
||
| `ProcessPads` | $E398 | Processes pad transitions, updates scores |
|
||
| `DrawScore` | $E3E1 | Draws score digits on screen |
|
||
| `DrawLives` | $E407 | Draws lives indicators on screen |
|
||
| `ShiftVar1`–`4` | $E433–$E47E | Shift pad bits into score accumulators |
|
||
| `UpdatePads` | $E47F | Updates pad state, checks button transitions |
|
||
| `LoadPatternTable6`–`7` | $E4A0–$E4B3 | Load additional pattern tables |
|
||
| `ProcessPadBits` | $E4FA | Process pad bit data for transitions |
|
||
| `SetAPUNoise` | $E52E | Sets APU noise channel |
|
||
| `ClearAPUNoise` | $E534 | Clears APU noise channel |
|
||
| `ClearScreen` | $E53A | Clears screen with blank tile $5F |
|
||
|
||
---
|
||
|
||
## 7. Zero-Page Aliases (`locals.inc`)
|
||
|
||
| Alias | Address | Role |
|
||
|-------|---------|------|
|
||
| `Zp00` | $00 | PPUCTRL shadow register |
|
||
| `Zp01` | $01 | PPUMASK shadow register |
|
||
| `Zp02` | $02 | VBlank flag |
|
||
| `Zp03` | $03 | Frame counter / NMI tick |
|
||
| `Zp05` | $05 | Score/digit temp |
|
||
| `Zp06` | $06 | Pad 1 state byte 1 |
|
||
| `Zp07` | $07 | Pad 1 state byte 2 |
|
||
| `Zp08` | $08 | Pad 1 state byte 3 |
|
||
| `Zp09` | $09 | Pad 1 state byte 4 |
|
||
| `Zp0A` | $0A | Pad 2 state byte 1 |
|
||
| `Zp0B` | $0B | Pad 2 state byte 2 |
|
||
| `Zp0C` | $0C | Pad temp / swap variable |
|
||
| `Zp0D` | $0D | Pad mode / draw flag |
|
||
| `Zp0E` | $0E | Shift counter / temp |
|
||
| `Zp0F` | $0F | Delay counter |
|
||
| `Zp10` | $10 | VRAM pointer low byte |
|
||
| `Zp11` | $11 | VRAM pointer high byte |
|
||
| `Zp12` | $12 | Score digit 1 accumulator |
|
||
| `Zp13` | $13 | Score digit 2 accumulator |
|
||
| `Zp14` | $14 | Score digit 3 accumulator |
|
||
| `Zp15` | $15 | Score digit 4 accumulator |
|
||
|
||
Full list in `copilot/locals.inc`.
|
||
|
||
---
|
||
|
||
## 8. Data Tables
|
||
|
||
### 8.1 Direct tables
|
||
|
||
| Table | Address | Size | Description |
|
||
|-------|---------|------|-------------|
|
||
| `PaletteData` | $E121 | 32 | Palette loaded into PPU $3F00-$3F1F by `LoadPalette` |
|
||
| `Player1TileTable` | $E4B4 | 12 | PPUADDR low bytes for player 1, indexed Y=0..11 |
|
||
| `Player2TileTable` | $E4C0 | 12 | Same for player 2; `$00` = "skip this button" |
|
||
| `VramWriteSourcePointerTable` | $F000 | 18 | 9 little-endian stream pointers, one per `LoadPatternTable*` / draw call site |
|
||
|
||
### 8.2 VramWrite payload streams
|
||
|
||
`VramWrite` ($E1CC) reads records of `<addr hi> <addr lo> <count> <count bytes>`, terminated by a `$00` at a record boundary. All nine streams tile `$E4CC-$E7C2` with no gaps and no overlaps:
|
||
|
||
| Slot | Ptr | Stream label | Address | Records | Writes to |
|
||
|------|-----|--------------|---------|---------|-----------|
|
||
| 0 | $F000 | `PowerPadSideAButtonGraphics` | $E54F | 2 | $2083, $20A3 — 52 tile graphics in pattern table 0 |
|
||
| 1 | $F002 | `PowerPadButtonLabelTiles` | $E58A | 4 | $2136, $2156, $2236, $2256 — button captions |
|
||
| 2 | $F004 | `PanelFrameTiles` | $E5B3 | 8 | $2124…$22C4 — panel borders for six indicator boxes |
|
||
| 3 | $F006 | `SideAPressedButtonRow` | $E64C | 6 | $2184…$22A4 — side-A button caps |
|
||
| 4 | $F008 | `SideAPanelButtonRow` | $E6BF | 6 | same rows, alternate layout |
|
||
| 5 | $F00A | `StatusMessageText` | $E732 | 3 | $2121, $2163, $2183 — status messages |
|
||
| 6 | $F00C | `Player1ButtonIconStream` | $E4CC | 2 | $2196, $21B6 |
|
||
| 7 | $F00E | `Player2ButtonIconStream` | $E4E3 | 2 | $2296, $22B6 |
|
||
| 8 | $F010 | `SideATestPromptText` | $E790 | 2 | $2304, $2344 — the prompt rows |
|
||
|
||
### 8.3 Screen text (decoded from CHR)
|
||
|
||
Font mapping read directly out of `chr.bin` pattern table 1: digits `$30-$39` = `'0'-'9'`, letters `$3A-$52` = `'A'-'Z'` (note **`W` is absent** from the `A-Z` run), `$57` = `-`, `$58` = `/`, `$59` = `\`, `$5F` = space.
|
||
|
||
| Address | Text |
|
||
|---------|------|
|
||
| $2121 | `CONNECT POWER PAD <$5D> CONTROLLER` |
|
||
| $2163 | `<$60>IF POWER PAD IS CONNECTED<$62>` |
|
||
| $2183 | `<$61> IC MAY BE BAD <$53> <$63>` |
|
||
| $2304 | `PRESS A TO TEST SIDE-A` |
|
||
| $2344 | `PRESS B TO TEST SIDE-B` |
|
||
|
||
Tiles `$53-$5E` are truncated glyph fragments in CHR ROM — including the `W` of `POWER`, which sits at `$5E` and renders incomplete. The original cartridge therefore displays partial marks at those positions; this is a ROM authoring artifact, reproduced faithfully.
|
||
|
||
---
|
||
|
||
## 9. Build
|
||
|
||
```bash
|
||
cd "NES PowerPad Test Card (U)/copilot"
|
||
make # → ca65 + ld65 + cmp reconstructed.nes rom.nes → "Byte-identical ROM verified."
|
||
```
|
||
|
||
---
|
||
|
||
## 10. Notes
|
||
|
||
- **The 16 KiB PRG is two byte-identical 8 KiB halves.** `prg[0x0000:0x2000] == prg[0x2000:0x4000]` is exactly true. Both halves hold the same program, pointer table, and vector set. The vectors point at `$E06E`/`$E000`/`$E000`, so the CPU always enters the `$E000` copy; nothing references `$C000-$DFFF`, so the first copy is dead and is kept as classified `.byte` data rather than disassembled.
|
||
- Unreached gaps inside the live code region decode as valid subroutines (PPUMASK show/hide background, PPUCTRL NMI-disable, frame-counter digit tiles, `ldx #$80 / txs`). Per Pass-1 policy they stay `.byte` data; each is decoded in the `prg.s` header comment block.
|
||
- The PRG is approximately 7.2% code / 92.8% data. Most data is `$FF` padding from `$E7C3-$EFFF` and `$F012-$FFF9`.
|
||
- The NMI handler drives per-frame updates; the main loop spins waiting for vblank and frame-counter changes.
|
||
- IRQ vector points to $E000 (`Reset`) and is effectively unused.
|
||
|
||
---
|
||
|
||
## 11. Next Steps
|
||
|
||
- Optional: refine the `Zp05`–`Zp0F` aliases now that `ProcessPads`/`DrawScore`/`DrawLives` semantics are known (pad-state bytes vs. shift counters).
|
||
- Optional: `$E4CC-$E4F9` holds two near-identical icon streams differing only in two bytes; could be collapsed to a parameterized table in a future reconstruction, but the byte form is preserved as-is.
|