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.
297 lines
15 KiB
Markdown
297 lines
15 KiB
Markdown
# Balloon Fight (JU) — Game Flow from Power-On
|
||
|
||
This document describes the execution flow of the disassembled Balloon Fight (JU) 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. Reset Vector — CPU $FFFC → $C000
|
||
|
||
**`Reset`** ($C000–$C07E)
|
||
|
||
On power-on or reset, the 6502 jumps to `$C000`. The reset routine performs cold-start hardware initialization:
|
||
|
||
| Step | Code | Purpose |
|
||
|------|------|---------|
|
||
| 1 | `lda #$00 / sta PPUCTRL` | Disable NMI and PPU rendering |
|
||
| 2 | `lda #$00 / sta PPUMASK` | Disable screen output |
|
||
| 3–6 | Poll `$2002` twice | Wait for two full VBlank periods (PPU warm-up) |
|
||
| 7 | `sei / cld` | Disable interrupts, clear decimal mode |
|
||
| 8 | `ldx #$FF / txs` | Initialize stack pointer |
|
||
| 9–13 | Clear Zero Page | Zero all of RAM $00–$FF |
|
||
| 14–21 | Warm-start signature check | Compare RAM `$07FA`–`$07FC` against `"HAL"` ($C082–$C084). If valid, skip full memory clear |
|
||
| 22–31 | Initialize memory | Clear zero page + stack page ($0700–$07FF via `SortedRecordTable`, x = 0), set `SpawnPixelPosition` = $32, run block-init loop (`jsr InitializeOrQueueObject` 50 times), `jsr SortOrInitializeRecords` |
|
||
| 32–44 | Copy initialization data | Copy 15 bytes from $C085 to $0629 (initial game state table) |
|
||
| 45–51 | Clear local variables | Zero the five-byte `CurrentRecord` at $03–$07 |
|
||
| 52–56 | Copy saved signature | Re-store `"HAL"` to $07FA–$07FC |
|
||
| 57 | `jmp MainInitialization` | Transfer control to $F1D4 |
|
||
|
||
**Warm-start signature:** `"HAL"` stored at $C082; RAM copy at $07FA. This lets the game resume state after a soft reset without re-initializing everything.
|
||
|
||
---
|
||
|
||
## 2. Main Initialization
|
||
|
||
**`MainInitialization`** is at **$F1D4** (forward-referenced in `locals.inc`). It sets up the first round, initializes object pools, and enters the main loop. Its body lives in the upper bank region (not fully shown in the decoded $C000–$C07E range).
|
||
|
||
---
|
||
|
||
## 3. Interrupt Vectors — CPU $FFFA–$FFFF
|
||
|
||
Located at the end of the bank (PRG offset $3FFA):
|
||
|
||
| Vector | Address | Handler |
|
||
|--------|---------|---------|
|
||
| NMI | $C094 | `NmiHandler` |
|
||
| RESET | $C000 | `Reset` |
|
||
| IRQ | $C0F7 | `IrqHandler` (self-loop `jmp IrqHandler` — unused) |
|
||
|
||
---
|
||
|
||
## 4. NMI / Frame Heartbeat — `NmiHandler` ($C094)
|
||
|
||
The NMI fires once per frame and drives the frame pacing. It:
|
||
|
||
1. **Preserves registers** (A, X, Y on stack)
|
||
2. **OAM DMA**: writes `$00` to `OAMADDR`, then `$02` to `OAMDMA` (DMA from $0200–$02FF)
|
||
3. **PPU command buffer flush**: compares read/write offsets at $52/$53; if data pending, calls `FlushPpuCommandPreserved` ($C17C)
|
||
4. **Transfer sources**: `jsr UpdatePpuTransferSources` ($D60D)
|
||
5. **Build OAM**: `jsr BuildFrameOam` ($D798)
|
||
6. **Frame counter**: `inc FrameCounter` ($19)
|
||
7. **Scroll/rendering setup**: sets the `PPUADDR`/`PPUSCROLL` registers, conditionally waits for VBlank if rendering disabled (polling `PPUSTATUS`), writes `PPUCTRL`
|
||
8. **Audio**: `jsr UpdateAudioFrame` ($FFF7 bank call → `Sound_F758`)
|
||
9. **Sets `NmiCompletedFlag`** ($02 = $01)
|
||
10. **Restores registers, `rti`**
|
||
|
||
The main game loop runs during VBlank and waits for this flag.
|
||
|
||
---
|
||
|
||
## 5. Main Game Loop — $C209
|
||
|
||
After initialization, control reaches the per-frame loop at **$C209**:
|
||
|
||
```
|
||
UpdateGameplayObjects ($E691) ; update all 20 gameplay-object slots
|
||
UpdateSpecialObjectSystem ($C6F9) ; every other frame (frame counter / 2)
|
||
[round spawner / HUD / spawning logic]
|
||
[object physics & collision]
|
||
[particle system]
|
||
[OAM sorting / sprite setup]
|
||
WaitForFrame ($F465) ; wait for NMI-completed flag
|
||
jmp back to $C209
|
||
```
|
||
|
||
Key flow details:
|
||
|
||
- **Scroll handling** ($C227): if `PpuScrollX` ($17) is non-zero, toggles `PpuControlBase` bit 0 (screen scroll page flip), decrements scroll X.
|
||
- **Carrier/rescue sequence** ($C233): updates carrier position ($0488), target player, sound requests.
|
||
- **Effect object pool** (8 slots, $055D–$0584): updates timers, respawns offscreen.
|
||
- **Gameplay object pool** (20 slots, $0530–$055C): movement, position integration.
|
||
- **Round spawner** ($C790): on frame boundaries, counts down `RoundSpawnDelay`, finds free slots, spawns round objects from tables ($C88F–$C8B5), plays spawn sound.
|
||
- **HUD updates** ($C831): when spawn delay reaches 1, writes round HUD digits to PPU buffer.
|
||
- **Sprite sorting**: `SortOrInitializeRecords` ($C579) maintains a sorted table of up to 50 five-byte records ($0700–$07F9) for OAM priority.
|
||
|
||
---
|
||
|
||
## 6. Subsystems
|
||
|
||
### 6.1 PPU Command Buffer ($C12D–$C1C4)
|
||
|
||
A buffered PPU update system. Commands are staged at $0300 with format:
|
||
- Byte 0: PPU address high | $20
|
||
- Byte 1: PPU address low
|
||
- Byte 2: length (number of data bytes following)
|
||
|
||
Routines:
|
||
- `AppendBytesToPpuBuffer` ($C131) — appends raw bytes
|
||
- `AppendLengthPrefixedPpuData` ($C139) — appends with length prefix
|
||
- `BuildPpuCommand` ($C154, formerly `Sub_C154`) — formats address+length command
|
||
- `FlushPpuCommandPreserved` ($C17C, formerly `Sub_C17C`) — drains buffer to $2006/$2007, preserving X/Y
|
||
- Special handling for palette writes ($3Fxx range)
|
||
|
||
### 6.2 Round Spawning ($C77A–$C88A)
|
||
|
||
- `ChooseRoundSpawnIndex` ($C77A): picks a random spawn index below `RoundSpawnRandomLimit`, rejecting zero
|
||
- `UpdateRoundSpawner` ($C790): timer-driven spawning; initializes object position, velocity (from tables at $C89F–$C8B1), flip flags, aux state; increments `SpawnSelector`; requests spawn sound ($F0 bit $04)
|
||
- `UpdateRoundHud` / `ConfigureRoundPresentation` ($C831–$C88A): writes round number / HUD tiles to PPU buffer
|
||
|
||
**Spawn tables** ($C88F–$C8B5): flip X/Y, X/Y offsets, parameter, velocity Y, position hi, velocity X — six entry types.
|
||
|
||
### 6.3 Gameplay Objects ($C8B7–$C9DC)
|
||
|
||
`UpdateRoundObjectSpritesAndPhysics` ($C8B7) updates slots 1 and 0:
|
||
- Builds 3-sprite OAM per object from tile tables ($C9DD–$CA33)
|
||
- Integrates fixed-point position ($C9B6)
|
||
- Bounds testing (`TestGameplayObjectAgainstBounds`, $CA67) against rectangular regions
|
||
- Velocity reflection on collision (`BounceGameplayObjectX/Y`, $CA4F/$CA37)
|
||
- Object removal when offscreen
|
||
|
||
### 6.4 Bonus Objects ($CB74–$CCCA)
|
||
|
||
- `UpdateBonusObjectSystem` ($CB74): per-frame phase/timer advance for the single active bonus slot
|
||
- `TestBonusObjectPlayerOverlap` ($CBB2): rectangle overlap vs both players; applies horizontal/vertical impulses, collision sound
|
||
- `TestBonusObjectCollection` ($CC3A): phase-3 collection; starts bonus timer
|
||
- `TriggerBonusObjectEffect` ($CCBF): increments effect counter, calls `ApplyBonusEffect` ($E983)
|
||
- `DrawBonusObjectHud` ($CCCB): 3-row HUD tile display from phase tables ($CD26–$D046)
|
||
|
||
### 6.5 Carrier / Rescue Sequence ($C5C3–$C715)
|
||
|
||
- `UpdateCarrierSequence` ($C6F9): advances carrier target X while idle; finds eligible player; starts sequence
|
||
- `FindEligiblePlayerForCarrier` ($C614): scans player slots 7→0, finds one at lower screen boundary ($B4+) matching carrier target X
|
||
- `BeginCarrierTargetSequence` ($C6C4): captures player position/state, resets timer
|
||
- `UpdateCarrierArrivalSequence` ($C658): moves carrier down, checks contact, transitions player to hit/rescue state, sound request
|
||
- `UpdateCarrierObjectDisplay` ($C5C3): builds 8-sprite carrier metasprite, updates target player position relative to carrier
|
||
- Tables: `NormalDisplayModeTable` ($C5B7), `AlternateDisplayModeTable` ($C5BB), `CarrierAnimationSequenceTable` ($C6B8)
|
||
|
||
### 6.6 Particle System ($CD4A–$CEAD)
|
||
|
||
- `InitializeParticleSlots` ($CD4A): 10 slots, offscreen Y ($F0)
|
||
- `SpawnTimedParticle` ($CD5A): random timer, finds free slot, assigns position/velocity from `ParticleInitialVelocityTable` ($CEAE)
|
||
- `UpdateParticleSystem` ($CDAA): integrates signed motion, applies scroll delta, retires offscreen particles
|
||
- `DrawParticleSprites` ($CE2F): 3-sprite OAM per particle with animation/attribute masking
|
||
|
||
### 6.7 Sound Driver ($FFF7 region, bank-switched)
|
||
|
||
- `UpdateAudioFrame` jumps to `Sound_F758` in another bank
|
||
- Sound sequence pointer table at $3BCA (32 entries)
|
||
- Encoded sequence data $3BCA–$3FF1 (note/duration bytes with $02/$FF/$8x control codes)
|
||
- APU channel init at $F7xx region (`InitializeApuChannelState`, `SilencePulseChannels`)
|
||
- Sound request flags: $F0 (flags 0), $F1 (flags 1), $F2 (flags 2), $F3 (flags 3)
|
||
|
||
---
|
||
|
||
## 7. Memory Map (Key Zero Page / RAM)
|
||
|
||
| Address | Name | Use |
|
||
|---------|------|-----|
|
||
| $00 | `PpuControlShadow` | $2000 mirror |
|
||
| $01 | `PpuMaskShadow` | $2001 mirror |
|
||
| $02 | `NmiCompletedFlag` | VBlank sync flag |
|
||
| $12–$13 | `RecordIndex` / `ReverseRecordIndex` | Sorted-record insertion (see reuse note below) |
|
||
| $14–$15 | `SpawnParameter` / `SpawnPixelPosition` | Spawn args |
|
||
| $16 | `RenderingDisabledFlag` | Rendering state |
|
||
| $17 | `PpuScrollX` | Scroll X |
|
||
| $18 | `PpuControlBase` | Base PPU control |
|
||
| $19 | `FrameCounter` | Frame tick |
|
||
| $1B | `RandomState` | PRNG state |
|
||
| $1D–$1E | `RecordPtrLo/Hi` | Record table pointer |
|
||
| $23–$24 | `SpawnCommandPointerLo/Hi` | Command stream pointer |
|
||
| $25–$26 | `DispatchPointerLo/Hi` | Spawn dispatch indirect jump |
|
||
| $52–$53 | Ppu buffer read/write offsets | Command buffer |
|
||
| $54–$56 | Ppu command address/length | Pending PPU command |
|
||
| $7F | `PlayerLifecycleState` | Per-player lifecycle |
|
||
| $88 | `PlayerSlotState` | Per-player active state |
|
||
| $91 | `PlayerPosX` / `Player0PosX` | Player X |
|
||
| $99 | `CarrierTargetX` | Carrier target |
|
||
| $9A | `PlayerPosY` / `Player0PosY` | Player Y |
|
||
| $A2 | `CarrierPosY` | Carrier Y |
|
||
| $BD | `PlayerCollisionDisable` | Collision immunity |
|
||
| $F0–$F3 | Sound request flags 0–3 | Audio requests |
|
||
| $0300–$03FF | PPU command buffer | Staged PPU updates |
|
||
| $0489–$048D | Carrier sequence state | Active, mode, target, drop, timer |
|
||
| $0490–$0530 | Gameplay object pool (20 slots) | State, pos, velocity |
|
||
| $055D–$0584 | Effect object pool (8 slots) | State, pos |
|
||
| $0558–$05CE | Particle / sequence state | 10-slot particle pool |
|
||
| $05D1–$060E | Bonus object state | Timer, phase, pos, HUD |
|
||
| $0700–$07F9 | Sorted record table | 50 × 5-byte OAM sort records |
|
||
| $07FA–$07FC | Warm-start signature | "HAL" |
|
||
|
||
**Alias reuse.** Several zero-page addresses serve more than one subsystem, so `locals.inc`
|
||
defines several names per address; `prg.s` uses whichever fits the routine reading it:
|
||
|
||
| Address | Names used in `prg.s` |
|
||
|---------|---------|
|
||
| $12 | `RecordIndex` (sort), `Temp12` (generic scratch), `CollisionDeltaX`, `MotionDeltaLo` |
|
||
| $13 | `ReverseRecordIndex` (sort), `CollisionDeltaY`, `MotionDeltaHi` |
|
||
| $23–$26 | `SpawnCommandPointerLo/Hi` + `DispatchPointerLo/Hi`, `BoundsLeftPtrLo/Hi` + `BoundsRightPtrLo/Hi` (stage-collision bounds) |
|
||
| $27–$2A | `BoundsTopPtrLo/Hi` + `BoundsBottomPtrLo/Hi` (stage-collision bounds) |
|
||
| $3E | `SequencePlayerIndex` (bonus accumulation) / `CurrentObjectIndex` (object loops) |
|
||
| $57–$5A | `PpuCommandData0/1/2` (PPU command buffer) / `HudCommandTile0`; `RoundHudCommandAddressHi/Lo` + `RoundHudCommandLength` + `RoundHudTile` in `DrawRoundStatusPanel` |
|
||
| $55D/$567/$57B | `EffectObjectState` / `EffectObjectPosX` / `EffectObjectPosY` (spawn effects) vs `ParticleState` / `ParticlePosX` / `ParticlePosY` (particles) |
|
||
|
||
---
|
||
|
||
## 8. Object Pools
|
||
|
||
| Pool | Slots | State array | Purpose |
|
||
|------|-------|-------------|---------|
|
||
| Gameplay objects | 20 ($00–$13) | $0530 | Round enemies/objects, movement & physics |
|
||
| Effect objects | 8 ($00–$07) | $055D | Short-lived spawn effects |
|
||
| Particles | 10 ($00–$09) | $055D | Visual particles (shared state array, different offset interpretation) |
|
||
|
||
Slot state convention: **negative ($FF) = inactive/free**, zero or positive = active.
|
||
|
||
---
|
||
|
||
## 9. Summary of Execution Flow
|
||
|
||
```
|
||
Power On / Reset
|
||
│
|
||
▼
|
||
Reset ($C000) ────► hardware init, clear RAM, validate "HAL" signature
|
||
│
|
||
▼
|
||
jmp MainInitialization ($F1D4)
|
||
│
|
||
▼
|
||
[first-round setup, object pool init]
|
||
│
|
||
▼
|
||
Main Loop ($C209) ──────────────────────────────────────────────┐
|
||
│ │
|
||
├─ UpdateGameplayObjects ($E691) │
|
||
├─ UpdateSpecialObjectSystem ($C6F9) [alt frames] │
|
||
├─ Carrier sequence ($C6F9 family) │
|
||
├─ Round spawner ($C790) + HUD ($C831) │
|
||
├─ Object physics & collision ($C8B7, $CA67) │
|
||
├─ Bonus object system ($CB74) │
|
||
├─ Particle system ($CDAA) │
|
||
├─ OAM sort ($C579) │
|
||
├─ WaitForFrame ($F465) ◄──────── waits for NMI flag ──────┘
|
||
│
|
||
▼ (loop back to $C209)
|
||
|
||
NMI ($C094) [once per frame]
|
||
├─ OAM DMA ($4014)
|
||
├─ Flush PPU command buffer ($C17C)
|
||
├─ Update transfer sources ($D60D)
|
||
├─ Build frame OAM ($D798)
|
||
├─ Frame counter++, scroll setup
|
||
├─ UpdateAudioFrame ($FFF7 → Sound_F758)
|
||
└─ Set NmiCompletedFlag, rti
|
||
```
|
||
|
||
---
|
||
|
||
## 10. Naming and Residue
|
||
|
||
Pass 2 (2026-10-19) replaced every address-derived definition with a semantic name —
|
||
`Sub_Cxxx` for the routines that had no behavioural name yet, `<Routine>_Block[_n]` for
|
||
internal branch targets — so `prg.s` now contains **zero** `Label_` definitions. The 77
|
||
`Sound_Fxxx` entry points keep their addresses as names in the banked audio region.
|
||
|
||
Pass 3 applies the two symbol tables to the instruction stream:
|
||
|
||
- `symbols.inc` — the NES hardware constants (`PPUCTRL` … `APUFRAMECNT`). All **125**
|
||
numeric register operands are now symbolic.
|
||
- `locals.inc` — zero-page/RAM names plus forward-reference aliases for routine
|
||
addresses (`AbsoluteDifference` = $F08E, `MainInitialization` = $F1D4, …). All but
|
||
**16** numeric operands are now symbolic.
|
||
|
||
Placeholder names renamed during the same work:
|
||
|
||
- `Sub_C154` → **`BuildPpuCommand`**
|
||
- `Sub_C17C` → **`FlushPpuCommandPreserved`**
|
||
- `Sub_C40C` → **`SpawnRandomObject`**
|
||
- `SpawnCommandStreamData_C4AD` → **`RoundSpawnCommandStream`** (format documented)
|
||
|
||
**Residue.** `$13` carries three aliases (`ReverseRecordIndex`, `CollisionDeltaY`,
|
||
`MotionDeltaHi`), none of which fits the **16** sites where it is used as an ordinary
|
||
high-byte scratch beside `Temp12` — in `LoadStageObjectData`, `ReadPpuStreamByte`,
|
||
`CreateBonusResultSprites`, `RenderObjectSprites_Load`, `ResolveObjectCollisionPair`
|
||
and `SwapObjectIndexes`. Those operands are deliberately left numeric rather than given
|
||
a speculative name; a neutral `$13` companion to `Temp12` would close them.
|
||
|
||
Build verification: `make` in `copilot/` produces `reconstructed.nes`, compared whole-ROM
|
||
against `rom.nes` (byte-identical). |