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.
348 lines
19 KiB
Markdown
348 lines
19 KiB
Markdown
# Bomberman (U) — Game Flow from Power-On
|
||
|
||
This document describes the execution flow of the disassembled Bomberman (U) PRG bank (16 KB, mapped at CPU **$C000–$FFFF**), starting from power-on. It is based entirely on `copilot/prg.s` (with `header.s` and `chr.s` for the iNES header and CHR data) in the repository.
|
||
|
||
---
|
||
|
||
## 1. ROM and Memory Layout
|
||
|
||
| Property | Value |
|
||
|----------|-------|
|
||
| Format | iNES / NES 2.0 |
|
||
| PRG | 1 × 16 KB (mapped at CPU $C000–$FFFF) |
|
||
| CHR | 1 × 8 KB |
|
||
| Mirroring | Vertical |
|
||
| PRG bank start | CPU $C000 |
|
||
| Source files | `copilot/prg.s` (7,553 lines, ~493 KB), `header.s`, `chr.s` |
|
||
| Output | `reconstructed.nes` (24,592 bytes) |
|
||
|
||
### Interrupt vectors (CPU $FFFA–$FFFF)
|
||
|
||
| Vector | Address | Handler |
|
||
|--------|---------|---------|
|
||
| NMI | $C01A | `NmiHandler` |
|
||
| RESET | $C000 | `Reset` |
|
||
| IRQ / BRK | $FFF9 | `IrqHandler` (just `rti` — unused) |
|
||
|
||
---
|
||
|
||
## 2. Build Status
|
||
|
||
`make` in `copilot/` assembles and links successfully, producing `reconstructed.nes` (24,592 bytes).
|
||
|
||
**Verification result:** The reconstructed ROM is **byte-identical** to `bomberman.nes` — headers, CHR, and all 16,384 PRG bytes match exactly.
|
||
|
||
### Naming fixes applied
|
||
|
||
| Change | Location | Reason |
|
||
|--------|----------|--------|
|
||
| `RandomState0` kept at `$54`; added `RandomStateAlt = $E4` | `locals.inc` | Zero-page reuse: `$54` is the random-state byte used by most code; `$E4` is a distinct byte decremented at CPU `$E71B` |
|
||
| `dec RandomState0` → `dec RandomStateAlt` | `prg.s` (was `main.s:6972`) | The original ROM has `dec $E4` at CPU `$E71B`, not `dec $54` |
|
||
| `ControllerState` → `ControllerState1` | `prg.s` (16 refs) | Clarifies this is controller port 1; added `ControllerState2 = $13` for port 2 |
|
||
| `Main_HandleControl_C368` → `MainGameLoop` | `prg.s` (3 refs) | Main per-frame game loop entry point |
|
||
| `Gameplay_HandleControl_C79D` → `GameplayUpdate` | `prg.s` (4 refs) | Gameplay object dispatcher/update |
|
||
| `Sound_HandleControl_E65F` → `SoundUpdate` | `prg.s` (3 refs) | Sound engine update called from NMI |
|
||
|
||
### Pass 3 symbol application (2026-10-19)
|
||
|
||
| Pass | Substitutions | Detail |
|
||
|------|---------------|--------|
|
||
| locals.inc (single-name) | 354 operands | All zero-page addresses with exactly one name in `locals.inc` |
|
||
| locals.inc (multi-alias, site-resolved) | 8 operands | `$E0/$E1`: `IndirectPtrLo/Hi` in the RAM-clear loop (`InitializeSystemAndRunMainLoop` → `Main_WriteSoundDispatchIndex_C317`); `SoundDelay0` (indexed, `$E1,x`) in sound engine (`Gameplay_ReadSoundDelay0_E57B`, `InitializeApu`, `Sound_ReadSoundDelay0_E661`) |
|
||
| symbols.inc (hardware) | 0 operands | `prg.s` already contains no numeric hardware operands ($2000–$4017) |
|
||
| In-file data-table labels | 24 operands | 24 ROM-space table reads (`lda $C2E7,x` → `lda SystemPaletteData,x`, etc.) substituted via `reconstructed.lbl` |
|
||
|
||
**Residue:** 758 numeric operands remain, addressing bytes not named in either `.inc` file: 505 zero-page (133 distinct addresses), 171 RAM $0100–$07FF (46 addresses), and 82 ROM table reads (54 addresses, 34 of which are interior bytes of labelled tables).
|
||
|
||
---
|
||
|
||
## 3. Reset — CPU $FFFC → $C000
|
||
|
||
**`Reset`** ($C000)
|
||
|
||
On power-on or reset:
|
||
|
||
1. `sei` — disable maskable interrupts.
|
||
2. `lda #$00 / sta PPUMASK / sta PPUCTRL` — disable PPU rendering and NMI.
|
||
3. `cld` — clear decimal mode.
|
||
4. `ldx #$FF / txs` — initialize stack pointer to $FF.
|
||
5. **Wait for two startup VBlanks** — `WaitForFirstStartupVBlank` ($C00D) and `WaitForSecondStartupVBlank` ($C012) each poll `PPUSTATUS` ($2002) for the VBlank bit.
|
||
6. `jmp InitializeSystemAndRunMainLoop` ($C30C) — transfer control to the system initializer.
|
||
|
||
---
|
||
|
||
## 4. System Initialization — `InitializeSystemAndRunMainLoop` ($C30C)
|
||
|
||
This is the main entry point after reset:
|
||
|
||
1. **Clear RAM** — writes $00 to zero page via `Main_WriteZp00_C333` ($C333) and to $0100–$07FF via an indirect pointer `IndirectPtrLo`/`IndirectPtrHi` ($E0/$E1) in a 7-page loop (`Main_WriteSoundDispatchIndex_C317` at $C317).
|
||
2. `jsr InitializeVideoSystem` ($C1F2) — disables rendering, clears shadow OAM, uploads the system palette, enables NMI.
|
||
3. `jsr InitializeApu` ($E642) — silences all APU channels, resets sound delay/state variables (`SoundDelay0`–`SoundDelay2` at $E1–$E3).
|
||
4. Writes zero to sound state variables ($E0–$E3).
|
||
5. Sets stack pointer to $FF, enables APU ($4015 = $0F).
|
||
6. `jsr ComposeStatusScreen` ($DE83) — draws the initial status/title screen.
|
||
7. `jsr EnableNmiInPpuControl` ($C2B0) — enables NMI via PPUCTRL shadow.
|
||
8. Sets `ScreenState` ($72) = $01.
|
||
9. Enters the main loop at `MainGameLoop` ($C368).
|
||
|
||
---
|
||
|
||
## 5. NMI / Frame Heartbeat — `NmiHandler` ($C01A)
|
||
|
||
The NMI fires once per frame and is the central real-time driver:
|
||
|
||
1. **Save registers** (A, X, Y on stack).
|
||
2. Set `FrameSyncFlag` ($0B) = $00.
|
||
3. Set OAM address to $00.
|
||
4. **Sprite DMA path** — if $60 is zero, write OAM entry $0700–$0703 (sprite #0 at Y=$F8) and trigger OAMDMA ($4014 = $07).
|
||
5. **VRAM transfer path** — if `VramReadOffset` ($14) ≠ `VramWriteLimit` ($15), transfer VRAM data from a table at $0600–$0607, indexing into pointer data at $D9C6–$D9C9. Handles both write and read packet types.
|
||
6. **Screen state / NMI work pending** — based on `ScreenState` ($72) and `NmiWorkPending` ($60), transfers various VRAM data blocks (title screen, gameplay screen, etc.) using `SetPpuAddress` ($C196).
|
||
7. **PPU status / audio** — reads PPUSTATUS, commits PPU state and scroll via `CommitPpuStateAndScroll` ($C296), increments `FrameCounter` ($33), handles audio channel timing at $69/$6A.
|
||
8. `jsr Ppu_WriteZp10_C19D` ($C19D) — reads and debounces both controller ports, stores results in `ControllerState1` ($12) and `ControllerState2` ($13).
|
||
9. `jsr Gameplay_ReadZpB2_E4C7` ($E4C7) — gameplay input handling.
|
||
10. `jsr SoundUpdate` ($E65F) — sound engine update.
|
||
11. **DMC control** — if $38 and `GameMode` ($59) are zero, starts DMC playback ($4010 = $0E, DMC address $C000, length $FF, enable channels).
|
||
12. **PPU scroll wait** — if $60 is set, waits for VBlank (polls PPUSTATUS bit 6), then applies scroll from $0E/$0F.
|
||
13. Toggles `FrameParity` ($DB) with `EOR #$05` (frame parity / flip-flop flag).
|
||
14. **Restore registers, `rti`.**
|
||
|
||
### Controller reading (`Ppu_ReadControllerAndReturnA_C1BF` / $C1BF)
|
||
- Strobes `JOY1` ($4016) with $01 then $00.
|
||
- Reads 8 bits per controller, shifting into X.
|
||
- `Ppu_HandleControl_C1EB` masks to the low 2 bits ($03) and increments X if non-zero (button press detection).
|
||
- Port 1 result → `ControllerState1` ($12); port 2 result → $13 (`ControllerState2`).
|
||
|
||
---
|
||
|
||
## 6. Main Loop
|
||
|
||
The main loop starts at **`MainGameLoop`** ($C368):
|
||
|
||
```
|
||
MainGameLoop ($C368):
|
||
wait until ControllerState1 ($12) is nonzero (button pressed)
|
||
└─ branch on SELECT ($20) to toggle $5F
|
||
└─ decrement sub-delay $71 / main delay $70
|
||
└─ when delays expire, increment $59 (game mode / screen state)
|
||
```
|
||
|
||
Based on `$59` and `$5F`, the loop dispatches to:
|
||
- `RunMenuSelectionScreen` ($DA8E) — title/menu screen
|
||
- Gameplay initialization paths ($C3B6–$C5FF) — sets up object positions, stage, sound
|
||
- `Main_WriteStageCounter_C613` ($C613) — stage counter display
|
||
|
||
The core per-frame gameplay dispatch uses a **state table** at `MainStateDispatchTable` ($C75D–$C79C), which maps state indices to handler sub-indices ($00–$27). Gameplay object processing walks arrays at $03E6 (state), $0436, $0486 (X/Y position), $04D6, $0526 (timer/flags), with up to 80 ($4F) object slots.
|
||
|
||
Key main-loop subroutines:
|
||
- `Main_ReadGameMode_C60B` ($C60B) — waits for `FrameDelay` ($B5) to reach zero.
|
||
- `Main_WriteStageCounter_C613` ($C613) — updates stage counter, handles START button to begin gameplay.
|
||
- `GameplayUpdate` ($C79D) — main gameplay object dispatcher (80 slots).
|
||
- `Gameplay_Dispatch_C7A4` / `Gameplay_Dispatch_C835` — object state dispatch.
|
||
- `Stage_WriteObjectWorkX_D8FC` ($D8FC) — object work initialization.
|
||
|
||
---
|
||
|
||
## 7. Gameplay Systems
|
||
|
||
### Object management
|
||
- Up to 80 object slots ($00–$4F), tracked by state at $03E6,X.
|
||
- Position arrays: $0436,X / $0486,X (X/Y), $04D6,X (state/flags), $0526,X (timer/direction).
|
||
- `Stage_WriteObjectWorkX_D8FC` ($D8FC) initializes object work fields.
|
||
- Objects are processed in a loop with `dex`/index retreat patterns ($C756, $C8A6).
|
||
|
||
### Bomb / explosion / player mechanics
|
||
Referenced throughout the gameplay code:
|
||
- `Gameplay_HandleControl_C96A`, `Gameplay_HandleControl_CA1B`, `GameplayUpdate` — player/bomb input and state.
|
||
- `Object_WriteStageProgress_CFB0` ($CFB0) — stage progress tracking.
|
||
- `Frame_ReadObjectIndex_CE5B` ($CE5B), `Frame_ReadObjectX_CDD4` ($CDD4) — frame-based object reading.
|
||
|
||
### Stage system
|
||
- `Stage_ReadZp58_D69A` ($D69A) — stage data lookup.
|
||
- Stage counter display via `Main_WriteStageCounter_C613`.
|
||
|
||
---
|
||
|
||
## 8. Audio / Sound Engine
|
||
|
||
### `InitializeApu` ($E642)
|
||
- Clears DMC direct register ($4011), sound delays `SoundDelay0`–`SoundDelay2` ($E1–$E3).
|
||
- Silences pulse 1, pulse 2, triangle, noise channel controls ($4000, $4004, $4008, $400C).
|
||
- Enables APU channels ($4015 = $0F).
|
||
|
||
### `SoundUpdate` ($E65F)
|
||
- Loops over 3 sound channels (X = 2 down to 0).
|
||
- Decrements per-channel delay at `SoundDelay0,x` ($E1,X).
|
||
- When delay expires, reads sound command state from `SoundCommandState` ($DF):
|
||
- If $DF < 0 → read sound RAM pointer ($E6BC table).
|
||
- If $DF == 3 → write sound command state.
|
||
- Otherwise → return or handle based on $E0 (indirect pointer).
|
||
- Calls into sound dispatch via `SoundDispatchAddressTable` ($E6AD–$E6C8).
|
||
|
||
### Sound dispatch table (`SoundDispatchAddressTable`, $E6AD)
|
||
A jump table of 14 sound handler addresses (e.g., $E641, $E6C8, $E6CC, $E6DE, $E727, $E766, $E792, $E7AB, etc.), each handling a specific sound effect or music channel.
|
||
|
||
### Channel-specific sound paths
|
||
- `Sound_UpdateAudioChannelPath_E6CF` ($E6CF) — noise channel ($400E–$400F).
|
||
- `Sound_UpdateAudioChannelPath_E6DF` ($E6DF) — pulse 2 channel: sets sweep ($4005 = $84), timer lo/hi ($4006/$4007), noise period/length.
|
||
- `Sound_UpdateAudioChannelPath_E70B` ($E70B) — decrements `RandomState0`, reconfigures pulse 2 when expired.
|
||
|
||
### Sound state (zero page)
|
||
| Address | Symbol | Use |
|
||
|---------|--------|-----|
|
||
| $DF | `SoundCommandState` | Sound command / state |
|
||
| $E0 | `IndirectPtrLo` / `SoundDispatchIndex` | Indirect pointer low; sound dispatch index |
|
||
| $E1–$E3 | `SoundDelay0`–`SoundDelay2` | Per-channel sound delays |
|
||
|
||
---
|
||
|
||
## 9. PPU / Rendering
|
||
|
||
### `InitializeVideoSystem` ($C1F2)
|
||
- `jsr DisableRendering` ($C257) — wait for VBlank, turn off PPUMASK.
|
||
- `jsr Ppu_HandleControl_C2B9` ($C2B9) — apply PPUCTRL shadow with NMI disabled.
|
||
- Set `PpuCtrlShadow` ($0C) = $10, clear $0E/$0F/$14/$15.
|
||
- `jsr HideAllSprites` ($C268) — fills $0700–$07FF with $F8 (offscreen) in 32-byte strides.
|
||
- `jsr UploadSystemPalette` ($C2C3) — uploads 32 bytes of palette data from `SystemPaletteData` ($C2E7) to $3F00–$3F1F.
|
||
- `jsr EnableNmiInPpuControl` ($C2B0) — enable NMI.
|
||
|
||
### `CommitPpuStateAndScroll` ($C296)
|
||
- Writes `PpuMaskShadow` ($0D) to PPUMASK ($2001).
|
||
- Sets PPU address to $0000, writes $00 to $2005 twice (scroll).
|
||
- Writes `PpuCtrlShadow` ($0C) to PPUCTRL ($2000).
|
||
|
||
### Palette data (`SystemPaletteData`, $C2E7)
|
||
32 bytes of NES palette colors starting at $3F00.
|
||
|
||
---
|
||
|
||
## 10. Zero-Page / RAM Symbols
|
||
|
||
The symbol table lives in `copilot/locals.inc` (hardware constants are in `copilot/symbols.inc`). Every address it names is used by name in `prg.s`:
|
||
|
||
| Address | Symbol | Use |
|
||
|---------|--------|-----|
|
||
| $0B | `FrameSyncFlag` | Main-thread/NMI frame handoff |
|
||
| $0C | `PpuCtrlShadow` | Software copy of PPUCTRL |
|
||
| $0D | `PpuMaskShadow` | Software copy of PPUMASK |
|
||
| $12 | `ControllerState1` | Controller port 1 sample |
|
||
| $13 | `ControllerState2` | Controller port 2 sample |
|
||
| $14 | `VramReadOffset` | NMI VRAM-transfer index into the $0600 table |
|
||
| $15 | `VramWriteLimit` | Upper limit compared against $14 |
|
||
| $16 | `NmiPathSelector` | $60=0 → sprite DMA path; $60≠0 → VRAM data path |
|
||
| $1F | `ObjectScreenX` | Object coordinate temporaries used by object processing |
|
||
| $20 | `ObjectScreenY` | |
|
||
| $28 | `ObjectSpawnParam` | Object spawn parameters |
|
||
| $29 | `ObjectSpawnY` | |
|
||
| $2A | `ObjectSpawnX` | |
|
||
| $2B | `ObjectSpawnWidth` | |
|
||
| $2C | `ObjectSpawnHeight` | |
|
||
| $33 | `FrameCounter` | Frame counter |
|
||
| $54–$57 | `RandomState0`–`RandomState3` | Four-byte PRNG state used by `AdvanceRandomState` |
|
||
| $59 | `GameMode` | Game mode / screen selector |
|
||
| $5C | `ObjectStateFlags` | Object state trio |
|
||
| $5D | `ObjectStateTimer` | |
|
||
| $5E | `ObjectStateExtra` | |
|
||
| $60 | `NmiWorkPending` | Nonzero → the NMI performs VRAM transfers |
|
||
| $70 | `MainDelay` | Main-loop delay counter |
|
||
| $71 | `SubDelay` | Secondary delay counter |
|
||
| $72 | `ScreenState` | Screen state flag |
|
||
| $73 | `ObjectXLimit` | Object X limit |
|
||
| $93 | `StageCounter` | Stage counter |
|
||
| $9C–$9F | `ObjectWork0`–`ObjectWork3` | Object work fields |
|
||
| $A4 | `BonusTimer` | Bonus timer |
|
||
| $AC–$AF | `AudioPtrLo/Hi`, `AudioArgLo/Hi` | Audio data / argument pointers |
|
||
| $B0 | `GameModeCounter` | Game-mode counter |
|
||
| $B1 | `ObjectType` | Object type |
|
||
| $B5 | `FrameDelay` | Frame delay |
|
||
| $DB | `FrameParity` | Frame-parity toggle, flipped by the NMI each frame |
|
||
| $DF | `SoundCommandState` | Sound command state |
|
||
| $E0 | `IndirectPtrLo` / `SoundDispatchIndex` | Indirect pointer for the RAM-clear loop; sound dispatch index in the sound engine |
|
||
| $E1 | `IndirectPtrHi` / `SoundDelay0` | Indirect pointer high byte; per-channel delay base (indexed by X) |
|
||
| $E2–$E3 | `SoundDelay1` / `SoundDelay2` | Remaining per-channel delays |
|
||
| $E4 | `RandomStateAlt` | Distinct byte decremented at CPU $E71B (zero-page reuse) |
|
||
|
||
**Aliases.** Two addresses carry two names each; `prg.s` uses the one that matches the calling routine. `$E0`/`$E1` are `IndirectPtrLo/Hi` in the RAM-clear loop (`InitializeSystemAndRunMainLoop` / `Main_WriteSoundDispatchIndex_C317`) and in the sound engine's pointer work, but `$E1` is `SoundDelay0` wherever the sound engine indexes the per-channel delay table (`SoundDelay0,x`, i.e. `$E1`–`$E3`).
|
||
|
||
**Unnamed residue.** Most zero-page/RAM bytes the game touches have no entry in `locals.inc` and stay numeric — 758 operands address 179 distinct addresses outside the table above (e.g. the `$34`/`$35` indirect pointer used by gameplay data writes). Naming them is Pass-3 semantic work, not a substitution.
|
||
|
||
---
|
||
|
||
## 11. Data Tables
|
||
|
||
| Label | Address | Description |
|
||
|-------|---------|-------------|
|
||
| `InesHeader` | $000000–$00000F (header segment) | iNES header (in `header.s`) |
|
||
| `SystemPaletteData` | $C2E7–$C306 | 32-byte palette for $3F00 |
|
||
| `MainStateDispatchTable` | $C75D–$C79C | 64-byte gameplay state dispatch table |
|
||
| `SoundDispatchAddressTable` | $E6AD–$E6C8 | 14-entry sound handler jump table |
|
||
| `PatternTableGraphics` | $004010+ (CHR segment) | CHR pattern table data (in `chr.s`) |
|
||
|
||
---
|
||
|
||
## 12. Summary of Execution Flow
|
||
|
||
```
|
||
Power On / Reset
|
||
│
|
||
▼
|
||
Reset ($C000) ───────────────────────────────────────┐
|
||
│ sei, disable PPU, cld, stack=$FF │
|
||
│ wait 2× VBlank │
|
||
▼ │
|
||
jmp InitializeSystemAndRunMainLoop ($C30C) │
|
||
│ │
|
||
├─ clear RAM ($0000–$07FF) │
|
||
├─ InitializeVideoSystem ($C1F2) │
|
||
│ ├─ DisableRendering │
|
||
│ ├─ HideAllSprites │
|
||
│ ├─ UploadSystemPalette ($3F00–$3F1F) │
|
||
│ └─ EnableNmiInPpuControl │
|
||
├─ InitializeApu ($E642) — silence all channels │
|
||
├─ ComposeStatusScreen ($DE83) │
|
||
├─ EnableNmiInPpuControl │
|
||
└─ MainGameLoop ($C368) ◄─────────────┘
|
||
│
|
||
MainGameLoop ($C368) ─────────────────────────────────┤
|
||
│ │
|
||
├─ wait for controller button press │
|
||
├─ handle SELECT / delay counters ($70,$71) │
|
||
├─ increment game mode ($59) │
|
||
├─ RunMenuSelectionScreen ($DA8E) [title] │
|
||
├─ gameplay init ($C3B6–$C5FF) │
|
||
├─ GameplayUpdate ($C79D) │
|
||
│ │ 80 object slots ($03E6 state array) │
|
||
│ ├─ object position ($0436/$0486) │
|
||
│ ├─ object timer ($0526) │
|
||
│ └─ object dispatch via StateDispatchTable │
|
||
└─ eventually → back to MainGameLoop │
|
||
│
|
||
NMI ($C01A) [every frame] │
|
||
│ │
|
||
├─ OAM setup + DMA ($4014) │
|
||
├─ VRAM transfer from $0600 table │
|
||
├─ screen state transfer ($D9C6–$D9C9 pointers) │
|
||
├─ controller read & debounce ($C1BF) │
|
||
├─ Gameplay_ReadZpB2_E4C7 ($E4C7) │
|
||
├─ SoundUpdate ($E65F) │
|
||
├─ DMC start ($4010–$4013) │
|
||
├─ PPU state & scroll commit ($C296) │
|
||
├─ frame parity toggle ($DB) │
|
||
└─ rti │
|
||
│
|
||
Sound Engine ($E65F) [from NMI] │
|
||
├─ per-channel delay countdown ($E1–$E3) │
|
||
├─ SoundDispatchAddressTable ($E6AD) │
|
||
├─ pulse 2, noise, DMC channel control │
|
||
└─ RandomStateAlt ($E4) decrement │
|
||
```
|
||
|
||
---
|
||
|
||
## 13. Notes
|
||
|
||
- **Build is byte-identical:** The apparent one-byte difference (`dec $E4` vs `dec $54` at CPU $E71B) was resolved by recognizing zero-page reuse — `$54` is `RandomState0` used by most code, while `$E4` is a distinct byte (`RandomStateAlt`) decremented at that one location. Both are now separately named in `locals.inc`.
|
||
- **Source annotation:** `prg.s` uses the canonical `; CPU:$C123 PRG:0123 AD 21 03` audit comment format on every instruction, enabling direct comparison with the binary.
|
||
- **Code organization:** Code is organized as reachable routines traced from the NMI/RESET/IRQ control-flow graph; unreachable bytes are classified as explicit data regions.
|
||
- **Legacy file:** `copilot/main.s` (8,070 lines) is a pre-standardization duplicate kept for reference; the build uses `prg.s` + `header.s` + `chr.s`.
|
||
- **Vectors confirm** NMI at $C01A and RESET at $C000, matching the reset handler location.
|
||
- **Known misnomer:** `Main_WriteSoundDispatchIndex_C317` ($C317) is actually the RAM-clear loop (writes $00 to $0100–$07FF via `IndirectPtrLo/Hi`), not a sound-dispatch write. The name reflects a prior pass's assumption; the operands now correctly use `IndirectPtrLo/Hi`. Renaming the label is a follow-up task. |