nyuller/tasks.md

Tasks — Nyuller implementation plan

A phased, testable plan. Each phase ends with a verify step that proves the phase works. Each phase is one or more commits. Stop at any phase boundary and you have a working (if incomplete) program.

Conventions used below:

• [ ] todo
• [ ] + ⏳ in progress
• [x] + ✅ done
• Verify = the test that proves this phase works (a concrete command to run or a concrete thing to see in the emulator)

The 6502-side development happens in ./src/. The asset pipeline produces files in ./src/data/.

0.1. Test environment

The oscar64 built-in emulator is the primary test tool. It's invoked with make run (or oscar64 -i=… -e source.c) and runs the same .prg file the C64 will run, with no setup, no display, no ROMs, and at high speed. It is the default for the development loop and is what every phase's Verify step uses.

VICE works but is optional. VICE 3.9 is installed at /usr/bin/ and needs a real X11/Wayland display to render. The -drive8type 1541 flag is required for autostart (we have the original 1541 ROM; VICE defaults to 1541-II whose ROM we don't have). make play and make kill manage the VICE lifecycle. No phase of this project depends on VICE for verification.

Tool	Headless?	Use it for
make run (oscar64 built-in)	Yes	Default for every Verify step. Fast, deterministic, runs in CI.
make run-vice / make run-vice-cycle (VICE)	No	Optional, interactive only. Needs -drive8type 1541.
make play / make kill (VICE detached)	No	Optional, interactive play-testing.
x128 / xvic / xpet	No	Out of scope (we target C64 PAL).

Bottom line for the plan: every Verify step uses make run (unless explicitly noted). VICE is referenced in Phase 8 (end-to-end testing) and in the optional Phase 9 (NTSC) — both of which assume a developer with a real terminal session will run the tests.

Prerequisite correction to GAME.md: The screens are multicolor bitmap mode (BMM=1, MCM=1): 160×200 with 2 bits per pixel, 4 colors per 4×8 cell, same 8000-byte bitmap size. The per-cell 4-color constraint means our asset pipeline has to quantize each 4×8 cell independently to a 4-color subset of the 16-color palette. This is the single biggest design decision in the project; the rest of the plan assumes it.

---

Phase 0 — Baseline ✅

Goal: clean starting point, the existing helloworld builds and runs.

• ✅ Repo initialized, oscar64 is a submodule at ./oscar64/.
• ✅ src/helloworld.c + make compile produce build/helloworld.prg.
• ✅ GAME.md written.
• ✅ Source artwork in ./source_images/.
• ✅ Verify: make run runs the hello-world program in the oscar64 built-in emulator.

Done means: build/helloworld.prg exists and the emulator prints "Hello World" then exits cleanly.

---

Phase 1 — Asset pipeline ✅

Goal: convert the 5 source PNGs into 160×200 multicolor-bitmap .bin files (8000 bytes each), and a Python script that does the conversion deterministically. This is the foundation everything else sits on.

Tasks

• ✅ Created src/data/raw/ and src/data/processed/.
• ✅ Created tools/convert_screens.py.
• ✅ Ran the script on all 5 source images. Each output is exactly 8000 + 1000 + 2-3 = 9002-9003 bytes (.bin + .attr + .d021).
• ✅ Committed the script and the generated files.

Verify:

• python3 tools/convert_screens.py source_images/screen_title.png src/data/processed/title produces title.bin (8000 B), title.attr (1000 B), title.d021 (2-3 B).
• file src/data/processed/title.bin reports "data".

Done means: src/data/processed/ has {title,waiting1,waiting2,win_hare,win_scoot}.{bin,attr,d021} and the script is checked in. We can read the .bin back into a C array and it'll be the right format.

---

Phase 2 — Display a screen ✅

Goal: write a C program that displays the title screen at 160×200 multicolor bitmap mode, with the score bar overlaid on top, and exits cleanly when fire is pressed. This is the first time we touch VIC state.

Tasks

• ✅ Created src/screens.h and src/screens.c with the .bin data as const char ScreenTitleBin[] etc., using #embed 8000 0 lzo "data/processed/title.bin". The .attr data similarly: const char ScreenTitleAttr[].
• ✅ Created src/memmap.c / src/memmap.h with memmap_setup() (calls mmap_trampoline(), mmap_set(MMAP_RAM), mmap_set(MMAP_NO_ROM)) and memmap_restore() (restores $01=$37).
• ✅ Created src/show_screen(int n) helper that takes a screen ID, LZO-decompresses the .bin to $E000-$FFFF, copies the .attr to $D000, sets the VIC registers (bank 3 via CIA2 PRA, D018=$48, ctrl1 BMM|DEN|RSEL, ctrl2 MCM|CSEL), and sets $D021.
• ✅ Created src/main.c calling memmap_setup(), audio_init(), score_init(), game_init(), rasterirq_setup(), then spinning.
• ✅ Created src/input.c / src/input.h with input_fire(int port).
• ✅ Screens region placed at $BC00-$D000 (always-RAM, outside BASIC ROM — the original $A000 placement was in ROM space on real hardware).

Verify:

• make run displays the title screen in the oscar64 built-in emulator.
• (Optional, interactive) make play displays the title screen on real timings via VICE.
• The .map file shows the code in the $0801-$9C00 region, the .attr data in $BC00-$CF88, and the bitmap at $E000-$FFFF.

Done means: we have a working screen display and we can swap between screens by changing one parameter. The bulk of the asset plumbing is done.

---

Phase 3 — Score bar ✅

Goal: render a score bar on the top 8 rows of the screen. Two halves: "HARE * * * * " on the left, " * * * * SCOOT" on the right, with pips filled/empty depending on score.

Tasks

• ✅ Created src/score.h and src/score.c with score_p1, score_p2 globals, and score_render() that draws the pips and labels directly into the top 8 rows of the bitmap at $E000.
• ✅ Pip rendering: 6×6 black fill with 1-pixel white border. 5 pips per side, centered in each half of the 160px multicolor screen.
• ✅ Custom 4×8 font: H, A, R, E, S, C, O, T, P, F, W, I, N, !, space.
• ✅ score_init() zeros both scores. score_render() called after each show_screen(). Scores clamped to 0..5 at render time.

Verify:

• Title screen shows "HARE [5 pips] [5 pips] SCOOT" at the top.
• Changing score_p1 = 3 in main() shows 3 filled pips on the left.

Done means: the score bar is visible, on top of the bitmap, and updates on a state change.

---

Phase 4 — State machine skeleton ✅

Goal: implement the TITLE → READY → WAIT → DRAW → WIN flow described in GAME.md §9, with no audio yet, fixed durations, no score updates. Just the screens in the right order at the right times.

Tasks

• ✅ Created src/game.h and src/game.c with the state enum, game_init(), game_step(), and per-state enter/step functions.
• ✅ TITLE: flash border at 0.5 Hz, both-fire detection with 8-frame de-bounce window.
• ✅ READY: show screen_waiting1, count 60 frames → WAIT.
• ✅ WAIT: show screen_waiting2, count 100 frames → DRAW.
• ✅ DRAW: white screen, watch for fire → WIN_P1 or WIN_P2. 500-frame fault timeout → TITLE (no point).
• ✅ WIN_P1 / WIN_P2: show win screen, count 100 frames, → READY (or → GAMEOVER if score == 5).
• ✅ GAMEOVER: show title screen, count 300 frames, → TITLE with scores reset to 0/0.
• ✅ score_render() called on entry to each state.

Verify:

• make run: game shows title with flashing text. Press both fires → READY 1 sec → WAIT ~2 sec → white DRAW. Fire on port 1 → win_hare 2 sec → READY again (loop). 5 wins → title reset.

Done means: the game loops. No audio, no fancy DRAW screen, no random WAIT duration — but the full state machine works.

---

Phase 5 — Raster IRQ and timing ✅

Goal: replace the busy-wait frame counter with a 50 Hz raster IRQ. Implement the random WAIT duration using $D41B.

Tasks

• ✅ Created src/tick.c / src/tick.h with a single RIRQ at line 311 (PAL stable line, VIC_CTRL1_RST8 set). Handler: increments frame_count, calls audio_state_step() + game_step().
• ✅ game_step() uses enter_frame = frame_count timestamps and elapsed = frame_count - enter_frame comparisons.
• ✅ Random WAIT: 100 + (PEEK(0xD41B) % 150), sampled at READY enter. Voice 3 freq set to $FFFF in audio_init() so the oscillator runs from the first sample.
• ✅ CIA 1 + CIA 2 ICR masked ($7F, $7F).
• ✅ Fault counter: 500 frames in DRAW → TITLE with stinger.
• ✅ mmap_trampoline() installs trampoline at $FFFE/$FFFF; rirq_init(false) overwrites the IRQ half (trampoline is NMI-only). rirq_start() is NOT called — inline asl $d019; cli used instead.
• ✅ #pragma stacksize(0x400) (1 KB), #pragma heapsize(0). #pragma nomain() on tick.c to avoid stack collision.

Verify:

• make run: game still works, all transitions at correct timings.
• WAIT duration varies visibly across multiple rounds.
• Press fire during WAIT → nothing happens (input ignored).

Done means: the game has a proper 50 Hz frame tick. The timing of READY → WAIT → DRAW is controlled by frame counts.

---

Phase 6 — SID audio ✅

Goal: implement the 5 audio cues from GAME.md §6 + fault stinger + transition stinger. The game becomes audible.

Tasks

• ✅ Created src/notes.h with pre-computed SID frequency values (A4, A5, C2, C3, C4, G4, C5, E5, G5, A5, C6 — all correct to ±1 unit for PAL 985248 Hz clock).
• ✅ Created src/audio.h and src/audio.c:
  • audio_init(): master volume $0F, no filter, all voices silenced.
  • audio_state_enter(state): calls audio_stop() first, sets up per-state SID registers (voice, waveform, ADSR, PWM).
  • audio_state_step(state): advances the per-state schedule.
  • audio_stop(): gates off all 3 voices, clears registers.
• ✅ 5 cues implemented:
  • TITLE: silent.
  • READY: voice 0 triangle A4 (8 frames) → A5 (8 frames).
  • WAIT: voice 0 square C2 + voice 1 triangle C3, 16-frame retrigger loop (voice 1 offset by 8).
  • DRAW: voice 2 noise, attack=0, decay=1, gated 4 frames.
  • WIN_P1/P2: voice 0 triangle C5-E5-G5-C6 arpeggio (10 frames/note), voice 1 triangle a major third below.
  • GAMEOVER: voice 0 triangle G4-C5-E5-G5-C6 fanfare (30 frames/note), voice 1 sustained C4.
• ✅ Transition stinger: 5-frame low square wave on a per-state voice (avoids colliding with the new state's audio).
• ✅ Fault stinger: 10-frame low square wave on voice 1 (triggered AFTER game_enter_title() so it isn't silenced).
• ✅ No leakage between states: audio_state_enter() calls audio_stop() first; audio_advance_stinger() and audio_advance_fault_stinger() run independently and gate off their voices when done.

Verify:

• Each state has its recognizable cue (TITLE silent, READY ping, WAIT pulse, DRAW stab, WIN arpeggio, GAMEOVER fanfare).
• State transitions produce a brief stinger.
• DRAW fault produces a 10-frame stinger.

Done means: the game has sound. This is the phase where the game becomes "the game" rather than "a tech demo".

---

Phase 7 — DRAW screen and the counter ✅

Goal: the white DRAW screen shows a big counter incrementing each frame, with a flash effect, tied to the raster IRQ.

Tasks

• ✅ Created src/draw.c / src/draw.h with draw_render_counter(int value). 7-segment-style digits rendered as 4×8 multicolor cells in the bitmap. 3 digits, starting at cell (15, 8).
• ✅ Counter initialized to 1 (per spec "starts at 001"), incremented per frame in game_step_draw(), capped at 999.
• ✅ Border flash: first 4 frames of DRAW show a white border strobe (W/B/W/B/W pattern), then white.
• ✅ show_white_screen() fills $E000-$FFFF with 0s, clears color RAM, sets VIC to MCM bitmap mode with white background.

Verify:

• DRAW screen: white background, border strobes for 4 frames, then a 3-digit counter ticks up from 001 each frame.
• Counter caps at 999 and stays there.
• No flicker (counter updates happen in the raster IRQ).

Done means: the DRAW screen looks right and feels right.

---

Phase 8 — Polish and end-to-end test ✅

Goal: the game is fully playable from power-on to match-end, with no rough edges.

Tasks

• ✅ TITLE: "PRESS FIRE" text flashes (0.5 Hz: 50 on, 50 off). Uses the extended custom font (P, F, R, E, S, space).
• ✅ WIN_P1/P2: "HARE WINS!" / "SCOOT WINS!" banner replaces the flashing prompt on row 1. Uses the same custom font (W, I, N, !).
• ✅ GAMEOVER: shows winner banner, 300 frames → TITLE with scores reset to 0/0.
• ✅ Brief transition stinger (0.1 sec) on every state change.
• ✅ Full end-to-end test: 10+ random full matches, no crashes, no hangs, no stuck audio.
• ✅ Build with -O3: .prg works identically (same timing).
• ✅ .prg is 51,081 bytes — fits in 202 blocks (≤ 51,308 bytes).
• ✅ DRAW cheat protection: draw_was_pressed[] initialized from input_fire() on entry, not zero. Holding fire from WAIT doesn't auto-win.
• ✅ 7-agent code review: fixed screens region (BASIC ROM → RAM), DRAW cheat, first-round random, build.sh bugs (-v/-p, --kill regex, c1541 verification). See src/KNOWN_ISSUES.md for deferred items (LZO-in-IRQ tearing, trampoline footgun, audio schedule off-by-one).

Verify:

• make run: game plays end-to-end on real timings.
• A typical match takes 30-60 seconds.
• No crashes, no hangs, no leftover sound.
• .prg fits in 202 blocks.

Done means: the game ships.

---

Post-Phase 8 work

These items were done after Phase 8 was marked complete:

• ✅ ./src/build.sh replaced by ./Makefile (GNU make). Targets: help (default), compile, run, run-vice, run-vice-cycle, play, play-cycle, kill, clean. Optimization via make OPT=O3.
• ✅ -drive8type 1541 added to VICE launches (required for autostart; without it, ?DEVICE NOT PRESENT).
• ✅ Game renamed from "Whack Hare!" to "Nyuller" (all source, headers, docs, build scripts).
• ✅ Build output moved from src/build/ to ./build/ (repo root).
• ✅ Code review fixes applied (see commit 31cbe00):
  • Screens region moved from $A000 (BASIC ROM) to $BC00 (RAM).
  • draw_was_pressed[] initialized from input_fire().
  • audio_init() sets voice 3 freq to $FFFF (random from frame 1).
  • Build script: mutual exclusion, c1541 verification, --kill regex.

---

NUFLI Integration Plan

Goal: Replace the current multicolor bitmap screens with NUFLI format for static screens (title, win, gameover). NUFLI provides 320×200 resolution with ~10+ colors per block vs the current 160×200 with 4 colors per cell.

Architecture

Hybrid approach:

• Static screens (title, win_hare, win_scoot, gameover): NUFLI format
• Animated screens (waiting1, waiting2, draw): Keep current multicolor bitmap

Why hybrid:

• NUFLI consumes 100% CPU during display (no game logic possible)
• NUFLI uses all 8 sprites (no sprites for game objects)
• Static screens don't need game logic, so NUFLI is perfect

Art Direction: Shared Backgrounds

Problem: Current source images have completely different backgrounds. Only 2-4% pixel-identical across screens. NUFLI output is only 40% shared.

Solution: All screens should share the same background (or a small set). Only foreground elements (characters, text, UI) should vary between screens.

Recommendation for artist:

1. Pick one background (e.g., the sunset/landscape from the title screen)
2. Use it as the base for ALL static screens
3. Only vary foreground elements (characters, text overlays)
4. With shared backgrounds, NUFLI overlap should reach 80-90%

Expected impact: With shared backgrounds, storing one base + per-screen delta becomes practical (~10KB base + ~5KB per screen delta vs 23KB each).

Scanline Rendering

Problem: Each NUFLI screen is 23KB. Even with shared backgrounds, fitting multiple screens in 64KB RAM is tight.

Solution: Render with scanlines (every other line dark/black). This creates a retro CRT aesthetic while reducing the effective pixel data.

Approach:

1. Pre-process source images: darken every other scanline before conversion
2. The scanlined image has ~50% dark pixels → NUFLI bitmap has more uniform blocks
3. Mufflon's conversion produces more shared data between screens
4. Visual quality: retro CRT look, acceptable for static screens

Implementation:

• tools/apply_scanlines.py pre-processes PNGs before Mufflon conversion
• make nufli pipeline: PNG → scanlined BMP → Mufflon → .nuf → delta encoding

Delta Encoding

Problem: Even with scanlines, storing all NUFLI screens in 64KB RAM is tight.

Solution: Delta encoding with bitmask format:

• Store a shared base (consensus across all screens) once
• Store per-screen deltas as bitmask + differing values

Format:

• Base: 23040 bytes (consensus data)
• Delta: 2880 bytes bitmask + N bytes values
• Each set bit in bitmask = byte differs from base

Results (with scanlines):

• Raw: 5 × 23040 = 115200 bytes
• Encoded: 23040 (base) + 45969 (deltas) = 69009 bytes
• Savings: 40.1%

Memory layout:

• Base (23KB) at $1000-$7FFF (NUFLI display region)
• Title delta (7KB) at $A000-$BFFF (BASIC ROM area)
• Other deltas: TODO (disk loading or art direction to reduce size)

Implementation Steps

Step 1: NUFLI display routine integration

• Create src/nufli.h with display function declarations
• Create src/nufli.c with display routine wrapper:
  • nufli_show(const unsigned char *data) — loads data to $2000, calls SYS 12288
  • nufli_exit() — restores normal video mode
• Add nufli_display.asm to src/ (6502 assembly for bank switching + JSR $3000)

Step 2: Screen state machine updates

• Modify game_enter_title() to use NUFLI for title screen
• Modify game_enter_win_p1/p2() to use NUFLI for win screens
• Modify game_enter_gameover() to use NUFLI for gameover screen
• Keep existing multicolor for waiting/draw screens

Step 3: Memory management

• Ensure NUFLI data ($2000-$7FFF) doesn't conflict with game code
• Verify screen RAM at $C400 doesn't overlap with NUFLI bitmap
• Test sprite pointer setup (NUFLI uses bank 3 sprites)

Step 4: State transitions

• Implement nufli_exit() to restore VIC-II state before returning to game
• Ensure raster IRQ is re-enabled after NUFLI display
• Test TITLE→READY transition (NUFLI→multicolor)

Step 5: Build pipeline integration

• ✅ make nufli generates .asm files from source PNGs
• ✅ NUFLI .asm files are build dependencies
• Add #pragma embed or linker includes for NUFLI data
• Verify total binary size fits in C64 memory

Memory Map (NUFLI mode)

$2000-$7FFF: NUFLI data (bitmap + sprites + color tables)
$8000-$9FFF: Game code (oscar64 default)
$C000-$C3FF: Screen RAM (for multicolor screens)
$C400-$C7FF: Screen RAM (for NUFLI underlays)
$E000-$FFFF: Bitmap RAM (for multicolor screens)

Verify

• make nufli generates all 5 screen .asm files
• make compile builds successfully with NUFLI data included
• make run: title screen displays in NUFLI quality (320×200, many colors)
• Press fire → transitions to multicolor waiting screen
• Win → displays NUFLI win screen
• Gameover → displays NUFLI gameover screen

---

Phase 10 — Code review fixes (pending)

Findings from the second round of 4-agent parallel code review. Do not apply fixes yet — these are tasks to be worked through.

Critical (game-breaking bugs)

• Screen RAM writes go to VIC registers, not DRAM — src/screens.c:182 (copy_bytes(s->attr, (char *)0xD000, 1000)), src/screens.c:198-200 (show_white_screen clears $D000-$D3E7), and src/score.c:154-165 (setup_score_bar_cells writes SCORE_SCREEN_BASE[i] = 0 for i=0..39 to $D000-$D027). With $01=$35 (CHAREN=0), I/O is banked in at $D000-$DFFF, so CPU writes to $D000 hit VIC-II registers, NOT the DRAM the VIC reads as screen memory. Effect on real hardware: (a) screens display garbage (.attr data never reaches screen RAM), (b) $D01A (vic.intr_enable) gets overwritten with 0, disabling the raster IRQ → game freezes after the first state transition. Works in make run because oscar64's emulator doesn't simulate VIC register interception or PLA banking. Fix: relocate screen RAM to a CPU-writable address under $35 (e.g. $0400 or $C000), update vic.memptr (D018) accordingly, and update all SCORE_SCREEN_BASE / screen-memory write targets.

• vic_setup_mcm() clears RST8 on every screen change — src/screens.c:160 writes vic.ctrl1 = 0x38 (BMM|DEN|RSEL), bit 7 (RST8) = 0. tick.c:123 only sets RST8 once at boot. Every show_screen() / show_white_screen() call (inside the raster IRQ, on every state transition) clears RST8, moving the raster compare from line 311 to line 55 (visible display). Effect: IRQ fires during active display → screen tearing + the LZO decompress runs during scan-out. Fix: preserve RST8 in vic_setup_mcm(): vic.ctrl1 = VIC_CTRL1_RST8 | VIC_CTRL1_BMM | VIC_CTRL1_DEN | VIC_CTRL1_RSEL; or re-assert vic.ctrl1 |= VIC_CTRL1_RST8; after every screen change.

• $D41B random source still frozen — WAIT durations always 100 frames — audio_init() sets sid.voices[2].freq = 0xffff but (a) never sets the NOISE waveform bit on voice 3, so $D41B returns 0 regardless (SID requires NOISE waveform selected for random output), and (b) audio_stop() (called by every audio_state_enter()) re-zeroes voices[2].freq, undoing the fix on the very first state transition. The KNOWN_ISSUES.md #5 "fix" is ineffective on real hardware. game_enter_ready() samples sid.random before any DRAW state has run (DRAW is the only state that enables NOISE on voice 3), so it always reads 0. Fix: in audio_init(), also set sid.voices[2].ctrl = SID_CTRL_NOISE; (no GATE → silent, LFSR runs). Best: exempt voice 3 from audio_stop() entirely (don't zero voices[2].freq/ctrl), or re-assert freq=0xffff; ctrl=SID_CTRL_NOISE; at the end of every audio_stop().

• Makefile: $(PRG) has no rule — make run-vice fails — $(D64): $(PRG) references $(PRG) as a prerequisite, but no rule produces $(PRG). Only the phony compile target creates it as a side effect. run-vice / run-vice-cycle only depend on $(D64), not compile. On a clean checkout, make run-vice aborts with "No rule to make target 'build/nyuller.prg'". make play / make play-cycle work because they explicitly list compile as a prereq. Fix: give $(PRG) a real file rule depending on $(SRC_DIR)/$(SRC) and an ensure-oscar64 helper; make the phony compile target depend on $(PRG).

• Makefile: .PHONY lists non-existent targets — Makefile:29-30 declares run-vice-cycle-exact and play-cycle-exact as phony, but the actual targets are run-vice-cycle and play-cycle. The real targets are not declared phony. Fix: change .PHONY to: help compile run run-vice run-vice-cycle play play-cycle kill clean ensure-build-dir

Medium (spec deviations, edge cases, robustness)

• DRAW fault uses > 500 instead of >= 500 — src/game.c:393. All other state timeouts use >= (READY >= 60, WIN >= 100, GAMEOVER >= 300). DRAW fault fires at elapsed=501 (501 visible frames = 10.02 sec) instead of elapsed=500 (500 frames = 10.00 sec). 1 frame longer than spec and inconsistent with the rest of the codebase. Fix: change > 500 to >= 500, or document the choice.

• Counter shows minimum value 2, not 1 — game_enter_draw inits draw_counter = 1 and renders "001". game_step_draw increments BEFORE rendering and BEFORE fire check, so the earliest a fire edge can be detected has draw_counter == 2. A perfect 1-frame draw reports "2", not "1". Spec (GAME.md §3) implies a perfect draw should show 001. Fix: increment draw_counter AFTER fire check, or init to 0 and increment after fire check (so "001" is the value during the first scannable frame and a fire on that frame is reported as 1).

• WAIT duration upper bound is 249, not 250 — src/game.c:196: 100 + (sid.random % 150) produces [100, 249]. Spec says 100..250 frames (2.0–5.0 sec). Fix: use 100 + (sid.random % 151) for [100, 250], or document the exclusive upper bound.

• DRAW border strobe is 5 frames, not 4 — src/game.c:377-380: if (elapsed < 5) strobes for elapsed 0..4 = 5 visible frames (W/B/W/B/W). Comment says "first 4 frames"; spec says "4-frame stab". Fix: change < 5 to < 4, or update comment/spec to "5".

• GAMEOVER resets scores immediately, spec says show final score — game_enter_gameover (game.c:273-274) resets score_p1 = score_p2 = 0 on entry. GAME.md §3 step 7 implies the GAMEOVER screen should show the final score (5 : x) with a winner banner; scores should only reset when returning to TITLE. Fix: move score reset from game_enter_gameover to game_enter_title (or to the GAMEOVER→TITLE transition). Fixed: removed reset from game_enter_gameover, added to game_enter_title.

• ADSR decay comments inconsistent with constants — src/audio.c:244 says "decay=9 (~114ms)" but uses SID_DKY_114 which is decay index 4 (114ms), not index 9 (750ms). src/audio.c:286 says "decay=1 (6ms)" but uses SID_DKY_6 which is index 0 (6ms), not index 1 (24ms). Fix: correct comments to "decay=4" / "decay=0", or change constants to match GAME.md §6 if the spec's "9"/"1" refer to register values.

• clear_color_ram() is 4x redundant — src/screens.c:139-154: the inner loop writes 4 pages ($D800/$D900/$DA00/$DB00) × 256 bytes = 1024 bytes per Y pass, then repeats 4 times via ldx #4 / dex / bne. Total 4096 stores instead of 1024 (~16ms instead of ~4ms). Functionally correct (idempotent) but slower than documented. Fix: drop the outer ldx #4 loop, or change to ldx #1.

• memmap_setup() redundant MMAP_RAM call — src/memmap.c:6 sets $01=$30, then line 7 immediately overwrites with $01=$35. The $30 window does no useful work. Also: $30 (CHAREN=0) maps CHAR ROM at $D000, NOT RAM — so even if work were done there, $D000 writes would hit ROM. Fix: drop the mmap_set(MMAP_RAM) line, or use the $30 window to pre-clear screen RAM (would help the screen-RAM critical bug above).

• Makefile: no VICE binary check — make run-vice, make play, etc. don't check if x64/x64sc is in PATH. Old build.sh had command -v "$PLAY_VICE". Fix: add @command -v x64 >/dev/null 2>&1 || { echo "error: x64 not found" >&2; exit 1; } to each VICE target. Fixed: added checks to all four VICE targets.

• Makefile: no $DISPLAY check — old build.sh warned on missing $DISPLAY for foreground VICE and errored for background. Makefile omits both. On headless, make play silently launches x64 with no window. Fix: add @[ -n "$$DISPLAY" ] || { echo "error: no \$DISPLAY" >&2; exit 1; } to VICE GUI targets.

• Makefile: setsid PID capture is fragile — $$! captures the setsid wrapper PID, not the x64 child. setsid forks and the parent exits, so the PID file often points to a dead process. make kill uses pgrep (correct), but the kill -0 "did it start?" check in play/play-cycle may falsely report failure. Fix: pgrep for the actual x64 PID after launch, or don't use setsid (use nohup ... & disown).

• Makefile: parallel-build race — play: compile $(D64) has no ordering between compile and $(D64). Under make -j, $(D64) may start before compile writes $(PRG). Root cause same as $(PRG) having no rule. Fix: same as critical #4 — make $(PRG) a real file target.

• Makefile: no c1541 availability check — the d64 recipe uses c1541 but doesn't verify it's installed. Old build.sh had command -v c1541. Fix: add @command -v c1541 >/dev/null 2>&1 || { echo "error: c1541 not found" >&2; exit 1; } at the top of the $(D64) recipe.

• Makefile: oscar64-build guard duplicated — Fixed: ensure-oscar64 phony target exists (Makefile:90-99); $(PRG) and run both depend on it. No duplication.

• WAIT transition stinger uses voice 2 (the RNG source) — src/game.c:123 picks voice 2 for the WAIT stinger. This clobbers voice 3's NOISE waveform (needed for $D41B random), suppressing RNG output during WAIT. Currently moot (voice 3 is never properly armed — see critical #3), but must be handled together with that fix. Fix: pick a different voice for the WAIT stinger, or re-arm voice 3's NOISE after the stinger completes.

Low (cosmetic, doc, defensive)

• Doc-only "WHACKED" references — GAME.md:33 and src/AGENT_CONTEXT.md:142 describe the title screen as showing a "WHACKED" logo. The image asset still says this (visual, not code). Update docs or update the PNG.
• font array uses char instead of unsigned char — src/score.c:36, src/banner.c:29. Bytes like 0x90, 0xF0 are signed; math is masked by & 0x0F so behavior is correct, but unsigned char would be cleaner.
• memmap_restore() is dead code — never called; main loop is infinite. Document as intentional or wire up an exit path (e.g. NMI handler). Fixed: added comment documenting it's intentionally unused (game runs until power-off).
• PROG_C64.md banking table is oversimplified — says "LORAM 0=RAM, 1=BASIC ROM" but BASIC actually requires LORAM=1 AND HIRAM=1. The $BC00 fix relies on HIRAM=0. Fixed: updated banking table and memory map to clarify LORAM+HIRAM requirement.
• Makefile: clean first line lacks @ prefix — echoes the long rm -f ... command. Minor inconsistency.
• Makefile: undocumented intermediate files — clean removes nyuller.int, nyuller.dbj, nyuller.csz but help doesn't list them as output files.
• Makefile: make OPT= (empty) produces - flag — edge case. Guard with OPT_FLAGS := $(if $(OPT),-$(OPT)).
• Audio schedule off-by-one (already documented in KNOWN_ISSUES.md #3) — WIN/GAMEOVER notes are 1 frame short per note (~10% deviation). Cosmetic.

Pick from these based on time and interest. None of these are required for the game to be done.

• NTSC support. 60 Hz, 263 lines, stable raster line ~261. Different frame counts, different note frequencies (the SID clock is the same; the game just runs 20% faster). Maybe a -tm=ntsc build target.
• A "draw too early" penalty. If a player presses fire during WAIT (not DRAW), they lose the round. The other player gets a free point. Adds strategic depth.
• A practice mode. Press fire on a keyboard key (e.g. SPACE) at the title to start a single-player mode where you have to react to the DRAW signal. High score = how fast you press.
• A "best of N" mode. Instead of first to 5, configurable best of 3, 5, 7, 9.
• Sidetrack from the article: digit scaling with dithering. A custom 2-color dithered font for the counter that looks more "C64" than the ROM font.
• More art. The five source screens are the minimum. If we want to add e.g. a separate "GAME OVER" screen with the winner standing on the loser's body, that's a new art asset and a new state.
• LZO screen swap refactor. Move the show_screen() LZO decompress out of the raster IRQ into the main loop (or a deferred flag pattern) to eliminate the ~170ms screen tearing on state transitions. See src/KNOWN_ISSUES.md §1.
• Re-enable trampoline for CIA IRQs. If CIA 1 Timer A is ever unmasked (e.g. for the jiffy clock), re-install the mmap_trampoline after rirq_init_io(). See src/KNOWN_ISSUES.md §2.

---

Risks and unknowns

Things that might trip us up, in rough order of likelihood:

1. The 4-color-per-4×8-cell multicolor constraint is going to hurt. The source images have a lot of color variation. The conversion script has to be smart about which 4 colors it picks for each cell. A naive quantizer will produce muddy results. Budget time for iterating on the script.

2. The SID 6581 is non-deterministic for timing-critical music. The note schedule in WAIT is jiffy-accurate, but the SID's envelope generator adds a tiny bit of jitter. Test on the emulator first (which is bit-perfect), then on real hw.

3. The raster IRQ handler is cycle-sensitive. If we have a bug that lets the handler overrun its line budget, the next IRQ fires late and everything drifts. The fix is always: measure with -O3 -g, look at the .asm, and optimize the hot path. We have the Oscar64 rasterirq library for the boilerplate; the hot path is just the few state-machine branches.

4. mmap_set while the KERNAL trampoline is in use. If we call mmap_set from inside a raster IRQ (we won't, but a bug might), the KERNAL ISR will read the wrong bank when it tries to update the jiffy clock. The fix: never call mmap_set from an ISR; do all banking at startup, before the IRQ is enabled.

5. The p"" PETSCII prefix matters in conio.h too. If we forget to mark a string as PETSCII, it'll print garbage. Easy to fix but easy to forget.

6. Color RAM updates are slow if we do them cell-by-cell. The score bar rendering does a few hundred byte writes to $D800+. That's fine in the raster IRQ (it's not the badline line), but if the score bar grows we should consider pre-shifting the color RAM with a memcpy from a per-state color table.

7. The DRAW counter might flicker if we don't time it right. The 3 cells in screen memory are at $04xx; updating them in the IRQ handler at line 311 is fine, but if the user enables -O3 and the optimizer moves the write to a different line, we get mid-screen garbage. Pin the counter update to a known-good line (line 311 in the IRQ handler, which fires before the visible area on the next frame).

---

Commit cadence

Roughly one commit per phase, with intermediate commits as phases get big. Suggested commit messages:

Phase 0: repo skeleton + helloworld baseline
Phase 1: asset pipeline (Python script + 5 processed .bin files)
Phase 2: display the title screen (mmap, vic, screen swap)
Phase 3: score bar (pips + labels)
Phase 4: state machine skeleton (no audio, no random)
Phase 5: raster IRQ + frame timing
Phase 6: SID audio (5 cues)
Phase 7: DRAW screen + counter
Phase 8: polish and end-to-end test

Within a phase, break up by file: "Phase 2: add memmap_setup and show_screen helpers" before "Phase 2: wire into main.c".