Add tasks.md: phased implementation plan

2026-07-17 00:45:46 +02:00
parent 9242dca9e7
commit cb3a8c4a2e
1 changed files with 516 additions and 0 deletions
@@ -0,0 +1,516 @@
 # Tasks — Whack Hare! 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/`.
 > **Prerequisite correction to GAME.md**: I said the screens would be
 > 320×200 standard hires. That's wrong for these images — they have
 > well more than 2 colors per 8×8 cell. The correct target is
 > **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.
 - [x] ✅ Repo initialized, oscar64 is a submodule at `./oscar64/`.
 - [x] ✅ `src/helloworld.c` + `src/build.sh` produce
  `src/build/helloworld.prg`.
 - [x] ✅ `GAME.md` written.
 - [x] ✅ Source artwork in `./source_images/`.
 - [ ] ⏳ **Verify:** `cd src && ./build.sh -e` runs the hello-world
  program in the oscar64 built-in emulator.
 **Done means:** `src/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
 - [ ] Create `src/data/raw/` and `src/data/processed/`.
 - [ ] Create `tools/convert_screens.py`. Inputs: a source PNG.
  Outputs: two files — `<name>.bin` (8000-byte multicolor bitmap)
  and `<name>.attr` (1000-byte screen memory with the foreground
  color per cell). The script:
  1. Crops the source to 160×200 (or 320×200 with a 2× horizontal
     scale, depending on what gives the best result — see
     decision point below).
  2. For each 4×8 cell, quantizes to 4 colors from the fixed
     16-color C64 palette (black, white, red, cyan, purple, green,
     blue, yellow, orange, brown, light red, dark grey, medium
     grey, light green, light blue, light grey).
  3. Picks the most common color in the cell as the
     "background" (one of $D021-$D024, encoded as 2 bits in the
     screen memory high nibble).
  4. Picks the 2nd, 3rd, 4th most common as the foreground
     (the cell's screen memory low nibble), and the two multicolor
     registers (D022, D023) — encoded in screen memory high bits 4-5
     and 6-7.
  5. Writes the 2-bit-per-pixel bitmap (MSB-first within each 4-pixel
     pair) to `<name>.bin` and the 1000-cell attribute table to
     `<name>.attr`.
 - [ ] **Decision point:** which of two crop strategies gives better
  results?
  - Strategy A: crop to 160×200 directly (loses horizontal detail).
  - Strategy B: crop to 320×200 and 2× downscale to 160×200 with
    area averaging.
  Try both on `screen_waiting1.png` and pick whichever looks better
  on the actual screen.
 - [ ] Run the script on all 5 source images. Verify each output
  is exactly 8000 + 1000 = 9000 bytes.
 - [ ] Commit the script and the generated `.bin`/`.attr` files.
  Generated files are checked in (not gitignored) so the build
  doesn't depend on Python being installed.
 **Verify:**
 - `python3 tools/convert_screens.py source_images/screen_title.png src/data/processed/title`
  produces `title.bin` (8000 B) and `title.attr` (1000 B).
 - `file src/data/processed/title.bin` reports "data".
 - Opening one of the .bin files in a hex editor shows it's not all
  zeros (sanity check that the script actually ran).
 **Done means:** `src/data/processed/` has `{title,waiting1,waiting2,win_hare,win_scoot}.{bin,attr}` 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 320×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
 - [ ] Create `src/screens.h` and `src/screens.c` with the .bin
  data as `const char ScreenTitleBin[8000]` etc., using
  `#embed "../data/processed/title.bin"`. The .attr data similarly:
  `const char ScreenTitleAttr[1000]`.
 - [ ] Create `src/memmap_setup()` helper that calls
  `mmap_trampoline()` then `mmap_set(MMAP_RAM)` (so the
  $E000-$FFFF region is available for the bitmap), then `mmap_set(MMAP_NO_ROM)`
  to also bank out CHAR ROM (so $D000 is I/O, not character data).
  This gives us 8 KB free at $E000-$FFFF for the active bitmap.
 - [ ] Create `src/show_screen(int n)` helper that takes a screen
  ID, copies the right `.bin` to $E000-$FFFF, copies the `.attr`
  to $D800-$DBE7, sets the VIC bank bits to point to the right
  RAM, sets the bitmap base to $E000 via $D018 VM bits, sets
  `vic_ctrl1` for BMM=1 (bit 5), `vic_ctrl2` for MCM=1 (bit 4),
  CSEL=1 (40 columns), and `vic.color_back` ($D021) to black.
 - [ ] Modify `src/helloworld.c` (or replace with a new `src/main.c`)
  to call `memmap_setup()`, then `show_screen(SCREEN_TITLE)`,
  then poll joystick port 1 — when fire is pressed, restore
  `mmap_set(MMAP_ROM)` and exit.
 - [ ] Add a joystick-read helper `input_fire(int port)` in
  `src/input.c` / `src/input.h`. Returns 1 if fire is currently
  pressed (active low: `(PEEK(0xDC00+port) & 0x10) == 0`).
 **Verify:**
 - `cd src && ./build.sh -e` displays the title screen in the
  emulator for 5 seconds (or until fire is pressed) then exits.
 - The .map file shows our code is in $0900-$1100-ish, well within
  the 38 KB main region.
 - The .prg loads and runs in `x64` (VICE) on real timings.
 **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 (the
 top 8 pixels of the hires bitmap, which is one character row in
 character mode). Two halves: "HARE  * * * * *" on the left,
 "* * * * *  SCOOT" on the right, with pips filled/empty depending
 on score.
 ### Tasks
 - [ ] Create `src/score.h` and `src/score.c` with a 5-element
  `byte score_p1`, `byte score_p2`, and a `score_render()` function
  that draws the pips directly into the top of the bitmap
  (the first 8×320 = 320 bytes of the active screen at $E000).
 - [ ] Pip rendering: a filled pip is a 6×6 black block with a
  1-pixel white border. An empty pip is just the border.
  Center the 5 pips in the left half (col 0-159) and right half
  (col 160-319).
 - [ ] Add a small text "HARE" / "SCOOT" label above each pip group
  (centered, in the same 8-row band). Implement with a 4-character
  custom font (just H, A, R, E, S, C, O, T — 8 chars total, 1 KB
  char ROM, but only 8 bytes per character needed so 64 bytes
  total; we can keep it in a `char` array).
 - [ ] Initialize scores to 0 in `main()`. Call `score_render()`
  after each `show_screen()`.
 **Verify:**
 - Title screen now shows "HARE 0    0 SCOOT" (or pip equivalent)
  at the top.
 - Changing `score_p1 = 3` in main() shows 3 filled pips on the
  left (manually verify by hardcoding the score and rebuilding).
 **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 (not random)
 durations, no score updates. Just the screens in the right order
 at the right times.
 ### Tasks
 - [ ] Create `src/game.h` and `src/game.c` with an enum:
  `STATE_TITLE, STATE_READY, STATE_WAIT, STATE_DRAW,
  STATE_WIN_P1, STATE_WIN_P2, STATE_GAMEOVER`. A `byte state`
  global, and a `game_init()`, `game_step()` pair.
 - [ ] Each state has an `enter` action (set the screen, start any
  audio, reset a frame counter) and a `step` action (check inputs,
  advance the frame counter, transition to the next state).
 - [ ] Without an IRQ yet, the main loop polls joysticks and
  advances state. This is fine for testing the flow.
 - [ ] TITLE: loop, flash "PRESS FIRE" text at 25 Hz, exit when
  both ports have fire pressed simultaneously (de-bounced: both
  must be pressed within ~8 frames of each other; otherwise wait
  for both to release and re-press).
 - [ ] READY: show `screen_waiting1`, count 60 frames, → WAIT.
 - [ ] WAIT: show `screen_waiting2`, count 100 frames (later:
  random 100-250), → DRAW.
 - [ ] DRAW: show a white screen (just fill the bitmap with 0s
  and set $D021 to white). No counter yet, no audio. Just
  watch for fire on either port; first to fire → WIN_P1 or
  WIN_P2 respectively. If no fire for 500 frames → back to
  TITLE (the "fault" case).
 - [ ] WIN_P1 / WIN_P2: show the appropriate 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).
 - [ ] Update `score_render()` to be called on entry to each state.
 **Verify:**
 - Run the program: it shows the title with flashing text. Press
  both fire buttons → READY screen for 1 sec → WAIT screen for
  ~1.6 sec → white DRAW screen. Press fire on port 1 → win_hare
  screen for 2 sec → READY again (loop). 5 wins → title reset.
 - The state transitions are visible and predictable.
 **Done means:** the game loops. No audio, no fancy DRAW screen, no
 random WAIT duration, no score update on win — 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. Every screen, every animation, every input poll is now
 synchronized to a stable frame tick. Also implement the random
 WAIT duration using the SID's $D41B oscillator register as a
 random source.
 ### Tasks
 - [ ] Create `src/rasterirq.c` / `src/rasterirq.h` with a single
  RIRQ at line 311 (PAL stable line). The handler:
  - Increments a global `frame_count` (16-bit, 50 Hz).
  - Calls `game_step()`.
  - Reads both joysticks, updates the input state.
  - Calls any per-frame "redraw" functions needed (counter,
    flashing text).
  - Re-arms the IRQ for the next frame.
 - [ ] Replace the busy-wait frame counter in `game_step()` with
  comparisons against `frame_count` and a per-state
  `enter_frame` timestamp.
 - [ ] Use `PEEK(0xD41B)` (SID oscillator 3) for the WAIT random
  duration: 100 + (PEEK(0xD41B) % 150) frames, sampled at
  READY enter.
 - [ ] Mask CIA 1 and CIA 2 IRQs in the IRQ setup so the
  jiffy-clock handler doesn't fire nested. (The oscar64
  `rasterirq` library does this for us, but doing it by hand
  teaches us what's happening.)
 - [ ] Add a "fault counter" — if neither player fires in 500
  frames in DRAW state, go back to TITLE with a short stinger
  sound (a low square wave burst, ~0.2 sec) and no point awarded.
 **Verify:**
 - The game still works in the emulator.
 - WAIT duration varies visibly across multiple rounds (use the
  oscar64 `-e` emulator's deterministic timing: even with
  randomness, the 50 Hz tick is rock-solid).
 - Press fire during WAIT (cheating) — nothing happens, we
  ignore inputs in WAIT state. (Add this as an explicit
  assertion in the test plan.)
 **Done means:** the game has a proper 50 Hz frame tick. The
 "feel" of the game (the timing of the READY → WAIT → DRAW
 transitions) is now under our control via frame counts rather
 than wall-clock waits.
 ---
 ## Phase 6 — SID audio
 **Goal:** implement the 5 audio cues from GAME.md §6. The game
 becomes audible.
 ### Tasks
 - [ ] Create `src/notes.h` with a frequency lookup table for one
  octave of equal-tempered notes (C2..C7) as 16-bit SID
  frequency values. Or just define the few specific notes we
  need by hand: A4, A5, C2, G1, C5, E5, G5, C6, G4.
 - [ ] Create `src/audio.h` and `src/audio.c` with:
  - `audio_init()` — set master volume $0F, no filter.
  - `audio_state_enter(int state)` — called from each state's
    `enter` action. Sets up the SID voices for the cue
    appropriate to that state.
  - `audio_state_step(int state)` — called from the raster
    IRQ. Advances notes per the per-state schedule.
  - `audio_stop()` — silence all 3 voices.
 - [ ] Implement the 5 cues per the table in GAME.md §6.
  Start with the simplest: the DRAW stab (voice 3 noise,
  attack=0, decay=1, gated for 4 frames). Add the others
  one at a time.
 - [ ] The WAIT suspense loop is the trickiest — implement it
  as a fixed schedule (every 16 jiffies, retrigger voice 1
  with the next note). Keep voice 2 doing a quieter
  arpeggio offset by 8 jiffies.
 - [ ] Make sure the audio doesn't "leak" between states:
  when transitioning out of WAIT, gate off both voices
  before starting the DRAW stab.
 **Verify:**
 - Each state has its cue, in isolation (by hardcoding the
  state in main and rebuilding):
  - TITLE: silent (or very subtle).
  - READY: ping-ping.
  - WAIT: pulse-pulse-pulse-pulse (about 3-4 pulses per
    second).
  - DRAW: staaaab.
  - WIN: arpeggio up.
  - GAMEOVER: longer fanfare.
 - The cues are recognizable and feel right (timing, volume).
 **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, and the per-frame timing is
 tied to the raster IRQ so the digits never flicker.
 ### Tasks
 - [ ] Add a `draw_render_counter(int value)` function that writes
  3 digit characters to the screen memory (which is in character
  mode, not multicolor, during the DRAW state — so we'll need
  a "switch VIC to hires char mode briefly" helper or just write
  the digits directly into the bitmap as 32×32 pixel blocks).
 - [ ] Decide on the implementation:
  - Option A: switch to hires char mode for DRAW, use the
    standard 8×8 ROM font, scale 4×. Simpler code.
  - Option B: keep multicolor bitmap mode, render the digits
    as a 4-color 4×8 cell layout. More code, looks more
    consistent with the rest of the game.
  - Start with Option A (simpler, ship faster).
 - [ ] On entering DRAW, fill the bitmap with 0s and set
  $D021 (background) to white. Then call
  `draw_render_counter(0)` once.
 - [ ] Each frame, increment the counter (cap at 999) and call
  `draw_render_counter(counter)`.
 - [ ] Add a "flash" effect: for the first 2 frames of DRAW,
  invert the colors (white background, black border, screen
  briefly all black). Or simpler: the border $D020 is set
  to white for the first 4 frames, then back to black.
 **Verify:**
 - When DRAW starts, the screen goes white with a brief flash.
 - A 3-digit counter starts at 001 and ticks up by 1 each frame.
 - The counter caps at 999 and stays there.
 - The screen doesn't flicker (counter updates happen in the
  raster IRQ, on the same line each frame).
 **Done means:** the DRAW screen looks right and feels right.
 This is the most visually exciting moment of the game, so it
 matters.
 ---
 ## Phase 8 — Polish and end-to-end test
 **Goal:** the game is fully playable from power-on to match-end,
 with no rough edges. We also do the real-hardware test.
 ### Tasks
 - [ ] On TITLE, flash "PRESS FIRE" at 1 Hz (50 on, 50 off).
 - [ ] On GAMEOVER, show a "HARE WINS!" or "SCOOT WINS!" banner
  in place of the flashing prompt. (Same custom font as the
  score bar; needs 6 more chars: W, I, N, !, S, space — some
  are already in there.)
 - [ ] Add a brief stinger sound (0.1 sec) on each state
  transition. Just a quick low square wave.
 - [ ] Make sure scores are reset on entering GAMEOVER → TITLE.
 - [ ] Run the full game in VICE (`x64src/build/whack_hare.prg`)
  multiple times, including:
  - P1 wins 5 in a row (cheat test: hold fire on port 1 the
    whole DRAW).
  - P2 wins 5 in a row.
  - Tie game: both fire on the same frame (impossible to test
    deliberately, but log it if it happens).
  - "Fault" case: nobody fires for 10 sec.
 - [ ] Build with `-O3` and verify the .prg still works
  (optimization can change timing subtly).
 - [ ] If we have a real C64 or a Turbo Everdrive, test on
  real hardware. Otherwise document that we tested in VICE
  cycle-exact mode (`x64sc`).
 - [ ] Strip `-g` from the release build. Add a `-O3` build
  target to build.sh.
 - [ ] Final pass: review the .map file, check no section is
  larger than expected, check no RAM region is over-allocated.
 **Verify:**
 - The game plays end-to-end on real timings.
 - A typical match takes 30-60 seconds.
 - No crashes, no hangs, no leftover sound.
 - The .prg is < 32 KB and fits in the C64's BASIC area
  (i.e. the standard 202-block load via `LOAD"*",8,1`).
 **Done means:** the game ships.
 ---
 ## Phase 9 — (Optional) extra features
 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.
 ---
 ## 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".