0 Fork 0

Files

T

tmerritt c204dac739 Donkey Kong Jr. Math (U): Pass 2 complete

- 6,589 instructions (81.9% code), 240 semantic labels, 186 zero-page aliases
- BYTE-IDENTICAL build verified
- Key routines: Reset, NmiHandler, MainGameLoop, InitPPU, InitSound, UpdateSprites, UpdateGameState
- Zero-page aliases: PPUCtrlShadow (0), PPUMaskShadow (1), PPUScrollX/Y (2/3), GameState (/bin/bash3), PlayerLives (/bin/bash4)
- Root OVERVIEW.md updated to reflect Pass 2 completion

2026-10-18 21:10:28 -04:00

3.7 KiB

Raw Blame History

Donkey Kong Jr. Math (U) — Pass 2 Complete

ROM: _wip/Donkey Kong Jr. Math (U)/Donkey Kong Jr. Math (U).nes (24,592 bytes, iNES). Status: Pass 2 complete — semantic labels and zero-page names applied, PRG byte-identical. copilot/prg.s contains a classified disassembly with 6,589 instructions (81.9% code / 13,416 bytes), 240 semantic labels, and 186 zero-page semantic aliases. The build is BYTE-IDENTICAL at the PRG level.

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	`263e5e9602943cfcb28c4d4492375a0e103c1d46c6f641ffab4da6f1f8422b4a`
PRG SHA-256	`de0612081266e6ad556d6c98dd7ad9c362ceac8531d9446239813feb1961221b`

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

Vector	Target	Note
NMI	`$C4A9`	per-frame heartbeat
RESET	`$C41E`	enters at $C41E inside the first pages (the Donkey Kong Jr.-style non-$C000 entry)
IRQ	`$FFF0`	lands in the vector-page padding — unused placeholder

`copilot/` Contents

File	Purpose
`Donkey Kong Jr. Math (U).nes`	original ROM image (reference)
`prg.bin` / `header.bin` / `chr.bin`	split image, produced by `_tools/splitnes.py`
`prg.s`	Pass 1/2: classified code/data split, 6,589 instructions, 240 semantic labels, audit comments on every emission
`symbols.inc`	shared NES hardware constants (PPU/APU/controller, from the skeleton)
`locals.inc`	186 zero-page semantic aliases (filled in by Pass 2)
`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 reproduced verbatim from header.bin/chr.bin (not linked): make verifies PRG bytes only at this stage. When this project is promoted to a full disassembly, header.s / chr.s (as e.g. Burger Time (U)) and a full-ROM make target get added.

Build

cd "_wip/Donkey Kong Jr. Math (U)/copilot"
make        # → cmp reconstructed_prg.bin prg.bin → "BYTE-IDENTICAL"

Next Steps (per `PROMPTS.md`)

Pass 3 — name data tables/structures; release provisional flags.
Promotion — move to a top-level <name>/copilot/ folder, add full-ROM build (header.s + chr.s + vectors), and write the power-on flow OVERVIEW.md in the established style; then it joins the root index's numbered inventory.

Pass 2 Details (2026-10-18)

Label renaming: 240 of 1035 labels renamed to semantic names using pass2.py apply with a mapping file (dkjm_label_map.tsv + locals.inc for zero-page). Key renamed routines:
- RESET/NMI: Reset, NmiHandler
- System init: InitSystem, ClearZeropage, InitPPU, InitGameState
- Main loop: MainGameLoop, InitPPU, InitSprites
- NMI: NmiHandler, NmiFrameUpdate, NmiFrameEnd
- Sprite handling: UpdateSprites, UpdateOAM, UpdateScroll
- Game logic: UpdateGameState, HandleController, UpdateSpritePositions
- Sound: InitSound, PlaySoundEffect, UpdateMusic
- PPU: WaitVBlank, WaitPPUReady, WritePPU, InitPPU
Zero-page semantic aliases: 186 aliases in locals.inc (see locals.inc header for full list):
- PPU: PPUCtrlShadow ($10), PPUMaskShadow ($11), PPUScrollX ($12), PPUScrollY ($13)
- Game state: GameState ($03), PlayerLives ($04), FrameCounter ($02)
- Controller: ControllerButtons1 ($10), ControllerButtons2 ($11)
- Sprite: SpriteIndex ($95), SpriteX ($12), SpriteY ($13)
- Pointers: TempPtrLo ($00), TempPtrHi ($01)

3.7 KiB Raw Blame History Unescape Escape