Promotes Donkey Kong Jr
Adds remaining NROM as _wip Update gitignore to not keep object files Adds AGENTS.md as this is an AI helped project
This commit is contained in:
tmerritt committed
1 parent
a29b03b00b
commit
9aef410424
412 files changed
+33427
-221
No files matched your search
+64
-3
@@ -1,6 +1,6 @@
|
||||
# Disassembly Project Index — /home/tmerritt/Projects/disassembly/
|
||||
|
||||
This document provides a consolidated overview of all NES disassembly projects in this directory. Each project has its own folder containing a `copilot/` subdirectory with the full source, build tooling, and an individual `OVERVIEW.md` with a detailed power-on execution flow analysis.
|
||||
This document provides a consolidated overview of all NES disassembly projects in this directory. Each project has its own folder containing a `copilot/` subdirectory with the full source, build tooling, and an individual `OVERVIEW.md` (at the project folder root) with a detailed power-on execution flow analysis.
|
||||
|
||||
---
|
||||
|
||||
@@ -16,6 +16,9 @@ This document provides a consolidated overview of all NES disassembly projects i
|
||||
| 6 | Defender 2 (U) | USA | 16 KB | 8 KB | Vertical | BYTE-IDENTICAL | $CAA1 / $C983 / $CA9E |
|
||||
| 7 | Excitebike (JU) | Japan | 16 KB | 8 KB | Vertical | BYTE-IDENTICAL | $C1F1 / $FD24 / $FD24 |
|
||||
| 8 | Tennis (JU) | Japan | 16 KB | 8 KB | Vertical | BYTE-IDENTICAL | $C07D / $C000 / $C000 |
|
||||
| 9 | Pac-Man (USA) (Namco) | USA | 16 KB | 8 KB | Horizontal | BYTE-IDENTICAL | $C10E / $C000 / $C17E |
|
||||
| 10 | Donkey Kong 3 (JUE) | Japan | 16 KB | 8 KB | Horizontal | BYTE-IDENTICAL | $C07D / $C000 / $C000 |
|
||||
| 11 | Donkey Kong Jr. (JU) | Japan | 16 KB | 8 KB | Horizontal | BYTE-IDENTICAL (Pass 1) | $C6E6 / $C66E / $FFF0 |
|
||||
|
||||
---
|
||||
|
||||
@@ -101,8 +104,40 @@ This document provides a consolidated overview of all NES disassembly projects i
|
||||
- **Build fix:** None needed; byte-identical out of the box
|
||||
- **Details:** `Tennis (JU)/OVERVIEW.md`
|
||||
|
||||
### 9. Pac-Man (USA) (Namco)
|
||||
- **Folder:** `Pac-Man (USA) (Namco)/`
|
||||
- **ROM:** `rom.nes` (24,592 bytes)
|
||||
- **Source:** `copilot/prg.s` (9,268 lines)
|
||||
- **Linker:** PRG at $C000, 16 KB; single segment
|
||||
- **Vectors:** NMI → $C10E (`NmiHandler`), RESET → $C000 (`Reset`), IRQ → $C17E (`IrqHandler`)
|
||||
- **Key subsystems:** NMI-synchronized main loop (`MainLoop` at $C04F), game state machine via `MainStateHandlerTable` ($C101, 12 states), game mode state machine via `GameModeStateTable` ($CAD7, 8 states), object/sprite system with fixed-point physics, audio engine ($F8DE) with serial I/O over controller port
|
||||
- **Build fix:** None needed; byte-identical out of the box
|
||||
- **Details:** `Pac-Man (USA) (Namco)/OVERVIEW.md`
|
||||
|
||||
### 10. Donkey Kong 3 (JUE)
|
||||
- **Folder:** `Donkey Kong 3 (JUE)/`
|
||||
- **ROM:** `Donkey Kong 3 (JUE).nes` (24,592 bytes)
|
||||
- **Source:** `copilot/prg.s` (9,952 lines)
|
||||
- **Linker:** HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
|
||||
- **Vectors:** NMI → $C07D (`NmiHandler`), RESET → $C000 (`Reset`), IRQ → $C000 (`Reset` reused)
|
||||
- **Key subsystems:** Main loop with object/game state management at $C02E–$C18D, object movement and geometry calculations ($C28E–$C683), audio engine ($F8DE+) with sound channels ($F0–$FF), PPU command buffer streaming ($C3F4+)
|
||||
- **Build fix:** Build split `main.s` into `header.s`, `prg.s`, `chr.s`; added `RandomStateAlt = $E4` for `dec $E4` at CPU $E71B (zero-page reuse with `RandomState0 = $54`)
|
||||
- **Details:** `Donkey Kong 3 (JUE)/copilot/OVERVIEW.md`
|
||||
|
||||
### 11. Donkey Kong Jr. (JU)
|
||||
- **Folder:** `Donkey Kong Jr. (JU)/`
|
||||
- **ROM:** `Donkey Kong Jr. (JU).nes` (24,592 bytes)
|
||||
- **Source:** `copilot/prg.s` (12,807 lines; 6,135 instructions, 266 routines, 68 data labels, 0 conflicts)
|
||||
- **Linker:** HEADER at $0000 (16 bytes), PRG at $C000 (16 KB), CHR at $0000 (8 KB)
|
||||
- **Vectors:** NMI → $C6E6 (`NmiHandler`), RESET → $C66E (`ResetHandler`), IRQ → $FFF0 (stray byte, effectively unused)
|
||||
- **Key subsystems:** Reset idles in a PRNG-advance loop — the entire frame state machine (title/attract/gameplay/sound) runs inside the NMI handler; VRAM/event queue at $0300 with dispatch table at $BFFE; 8-byte PRNG at $18–$1F; sound timers at $F1AF
|
||||
- **Build fix:** None needed; byte-identical out of the box (`make` in `copilot/`). Pass-1 status — unresolved bytes preserved as `.incbin` blocks pending Pass 2/3 renaming and table decoding
|
||||
- **Details:** `Donkey Kong Jr. (JU)/OVERVIEW.md`
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
## Common Patterns Across All Projects
|
||||
|
||||
### Memory Map
|
||||
@@ -114,6 +149,10 @@ All projects follow the same NES interrupt pattern:
|
||||
- **RESET** performs cold-start hardware init, RAM clearing, and enters the main loop.
|
||||
- **IRQ** is almost always unused (either `rti` or a self-loop).
|
||||
|
||||
Two exceptions worth noting from branches of this family:
|
||||
- **Excitebike** uses a state-dispatch table at $C000 rather than a conventional inline main loop, and its IRQ vector points into a data region (unused).
|
||||
- **Donkey Kong Jr.** is the extreme case: its reset path idles forever in a PRNG-advance loop, and the *entire* frame state machine (title, attract, gameplay, sound) executes inside the NMI handler itself. Its reset entry is also at $C66E rather than $C000.
|
||||
|
||||
### Build Toolchain
|
||||
All projects use the same toolchain:
|
||||
- **ca65** (6502 assembler)
|
||||
@@ -133,7 +172,7 @@ All sources are "Pass-1" style disassemblies:
|
||||
|
||||
Each project folder contains:
|
||||
- `copilot/` — disassembly source, build config, and build artifacts
|
||||
- `copilot/OVERVIEW.md` — detailed per-project power-on execution flow analysis
|
||||
- `OVERVIEW.md` (at the project folder root) — detailed per-project power-on execution flow analysis
|
||||
- `<rom>.nes` — original NES ROM image (for reference)
|
||||
|
||||
To rebuild any project:
|
||||
@@ -145,4 +184,26 @@ make
|
||||
To verify byte-identity:
|
||||
```bash
|
||||
make verify # (where supported by the Makefile)
|
||||
```
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
All 11 projects in this repository rebuild **byte-identical** to their original ROMs:
|
||||
|
||||
| # | Project | Build Status |
|
||||
|---|---------|--------------|
|
||||
| 1 | Balloon Fight (JU) | BYTE-IDENTICAL |
|
||||
| 2 | Baseball (UE) | BYTE-IDENTICAL |
|
||||
| 3 | Bomberman (U) | BYTE-IDENTICAL |
|
||||
| 4 | Burger Time (U) | BYTE-IDENTICAL |
|
||||
| 5 | Clu Clu Land (JU) | BYTE-IDENTICAL |
|
||||
| 6 | Defender 2 (U) | BYTE-IDENTICAL |
|
||||
| 7 | Excitebike (JU) | BYTE-IDENTICAL |
|
||||
| 8 | Tennis (JU) | BYTE-IDENTICAL |
|
||||
| 9 | Pac-Man (USA) (Namco) | BYTE-IDENTICAL |
|
||||
| 10 | Donkey Kong 3 (JUE) | BYTE-IDENTICAL |
|
||||
| 11 | Donkey Kong Jr. (JU) | BYTE-IDENTICAL (Pass 1) |
|
||||
|
||||
Every project builds successfully with `make` in the `copilot/` folder, and every reconstructed ROM matches the original byte-for-byte. Donkey Kong Jr. shares the same byte-identical build guarantee; its remaining Pass 2/3 work is semantic renaming and table decoding, not build-correctness.
|
||||
Reference in new issue
Block a user