nyuller/GAME.md

GAME.md — Whack Hare!

A two-player reaction-time duel for the Commodore 64. Two players stand back-to-back, take ten paces, and the first one to hit fire when the signal appears wins the round. First to 5 wins wins the match.

The two players are Hare (player 1, on the left — a white rabbit with claws and a bad attitude) and Scoot (player 2, on the right — a kid on a kick scooter). The two facing-off screens, the win screens, and the title screen all come from the artwork in ./source_images/.

1. The cast

Player	Side	C64 control port	Artwork on the title
Hare (the rabbit)	Left	Joystick port 1 ($DC01)	Lower-left of screen_title.png
Scoot (the kid on a scooter)	Right	Joystick port 2 ($DC00)	Lower-right of screen_title.png

Fire is the only button used. Both ports are read every frame; the joystick value is the standard J = PEEK(0xDC00/0xDC01) byte with bit 4 (mask $10) as the fire button (active low — pressed when bit 4 is clear).

2. Artwork

All artwork lives in ./source_images/ as 1390×1130 PNGs (8-bit RGB, dithered down to the C64's 16-color palette by whoever made them — the colors in the files are the colors the C64 will display):

File	Resolution	Used for
source_images/screen_title.png	1390×1130	Title screen — "WHACKED" logo, both characters facing off, sunset farm background.
source_images/screen_waiting1.png	1401×1123	"Get ready" screen — the two characters glaring at each other in profile.
source_images/screen_waiting_2.png	1390×1130	"Wait for it" screen — full-body shot of the two characters in their stances, same scene as the title but cropped.
source_images/screen_win_hare.png	1391×1131	Hare won — Hare punching Scoot in the face mid-scooter.
source_images/screen_win_scoot.png	1389×1132	Scoot won — Scoot has ridden over Hare, who is sprawled on the ground.

A practical note for converting to C64: the originals are 1390×1130, but the C64 hires screen is 320×200. We'll have to either:

• Pre-crop / pre-scale the assets in a tool (recommended) to 320×200 before embedding them, or
• Pick a 320×200 region of the original (the center 320×200 crop is usually the most interesting part) and embed that.

We'll do the cropping in an image tool (ImageMagick, GIMP, or a small Python script) and let the C64 just blit the resulting 320×200 hires bitmap. The Oscar64 #embed lzo directive is what pulls the cropped .bin into the binary.

3. The screens (in play order)

The game is a simple state machine. The screens, in the order a player sees them during one round:

1. Title (TITLE state) — screen_title.png. Static background. A short, flashing "PRESS FIRE ON BOTH PORTS" banner across the bottom half. The score is shown at the top: a row of "0"s on the left (Hare) and right (Scoot), reading 0 0. No music, or a very low-key idle loop on voice 1.

2. "Get ready" (READY state) — screen_waiting1.png. Up for exactly ~1.2 seconds. A short two-note "ping" jingle (e.g. SID voice 1 plays A4 then A5 with a quick attack/decay envelope). The score at the top is visible. The text "READY…" or just the screen alone is fine.

3. "Wait…" (WAIT state) — screen_waiting_2.png. The suspense state. Stays up for a random duration between 2.0 and 5.0 seconds, uniform. A looping suspenseful bassline plays on SID voice 1 (a slow two-note pulse, say C2–G1 alternating every ~16 jiffies), with voice 2 doing a quiet pulse-width "heartbeat" arpeggio. No indication of how long is left — that's the point.

4. "DRAW!" (DRAW state) — white screen, large black digits (described below), a sharp percussive stab on the SID (voice 3, noise waveform, attack=0, decay=1, sustain=0, release=2, gated off after 4 frames). The counter starts at 001 and increments once per frame so a fast eye + finger can win in single-digit milliseconds.

5. Win screen (WIN_P1 or WIN_P2 state) — screen_win_hare.png or screen_win_scoot.png. Up for exactly 2.0 seconds. A short 3-4 note "winner" jingle on the SID (e.g. C–E–G–C, major triad arpeggio, fast attack, long release, voices 1 and 2 stacked). The score at the top updates immediately (you see the new digit the moment the win screen appears).

6. Loop or game-over. If the winner's score is now < 5, jump back to step 2 (READY) for the next round. If the winner's score is 5, go to step 7.

7. Game over (GAMEOVER state) — same as the title screen, but with a "GAME OVER — HARE WINS!" / "GAME OVER — SCOOT WINS!" banner instead of "PRESS FIRE", and a 5–6 note "match over" fanfare. Stays up for 6 seconds (long enough to be appreciated), then resets to step 1 (TITLE) with scores at 0/0.

4. The "DRAW!" screen — what to draw

The C64 hires screen is 320×200 with a 16-color palette. The DRAW screen is:

• Background: solid white ($D021 = white, bitmap all 0s).

• A huge number in black, centered, drawn with the standard 8×8 ROM character set scaled up. The counter is 3 digits (001..999) so it stays in the visible screen at any size.

• Implementation: easiest is to use the 8×8 ROM font, scaled 4× (so each character is 32×32 pixels), centered. That gives 3 chars × 32px = 96px wide on a 320px screen, so each digit is huge but fits. Redrawing the screen is just "redraw the 3 screen memory cells with the new counter value". The VIC's redraw of a 96×32 region in character mode takes one frame's worth of work in the worst case; the counter is updated once per frame, in sync with the raster IRQ, so there's no flicker.

  A nicer version would use a custom multicolor font (the C64 has 4 colors per 8×8 cell in multicolor character mode), but hires character mode is simpler and the white-with-black-text look is the classic quick-draw visual.

• Each frame, in the raster IRQ handler, the game logic does:

  counter++;
  if (counter > 999) counter = 999;   // cap it
  screen[40 * 11 + 13] = '0' + (counter / 100);
  screen[40 * 11 + 14] = '0' + ((counter / 10) % 10);
  screen[40 * 11 + 15] = '0' + (counter % 10);
  

  (and similarly for the colors at $D800+, but they're all black, so set once at the start of the DRAW state).

• Optionally: each digit can have a small horizontal "shake" applied per frame to give a stressed-out look. Or a small black bar across the screen to make it look like a flash.

5. The score bar (top of every game screen)

• 1 character row, top of the screen. In hires + char mode, that means using the top 8 pixels of the bitmap as character cells, and the rest of the screen (200-8 = 192 pixels) as a hires image below. The easiest implementation is to set the VIC's video matrix pointer to start at a screen memory address that visually aligns with the top of the screen but in practice is wherever we want. Concretely: screen memory at $0400, but the screen "rows" we use for the score are just the very top 8 pixels of the bitmap (we draw the characters there by hand in the bitmap, OR we use a hybrid mode where the top 8 rows are character cells and the rest is hires — but C64 character rows are always 8 pixels high, so we'd have an 8-pixel score bar and a 192-pixel art area. Good enough.)
• Layout, top row, left to right:
  • Cols 0-15: "HARE " (label) + 5 small icons or just "HARE: " + the digit, centered on the left half.
  • Cols 24-39: "SCOOT: " + the digit, centered on the right half.
  • Total format: HARE * SCOOT * where the * is the number of filled-in score pip (0..5). Pips are simpler than digits: 5 small squares per side, filled or empty.
• Score pip rendering: a custom character for "filled pip" (a solid block in the foreground color) and "empty pip" (an outline or a blank). Each side takes 5 character cells of width.

The cleanest implementation: have two pre-loaded custom character sets for the pip characters (filled and empty), and the rest of the score bar is the standard ROM character set. Switch between them with $D018. But that adds complexity — for the first pass, drawing the pips as solid filled blocks in the bitmap is fine (the score bar is only 8 pixels high and the pips are 6×6 blocks).

6. Audio (SID 6581) — the five cues

The SID has 3 voices. The game uses voice 1 for music, voice 2 for harmony, voice 3 for sound effects. The filter is bypassed (volume $0F, no filter routing) for the first pass — we can add filter sweeps later for polish.

State	Voice 1	Voice 2	Voice 3	Notes
TITLE	(silent, or a low idle pulse)	—	—
READY	triangle A4 then A5, attack 0, decay 9, release 0, no sustain, gated off after 8 frames each	—	—	Two notes, ~0.6s total
WAIT	square wave C2, pulse width 50%, slow envelope (attack 0, decay 15, sustain 8, release 15)	triangle 1 octave up, same envelope, slightly delayed	—	Looping, every ~16 jiffies re-trigger
DRAW	—	—	noise, attack 0, decay 1, sustain 0, release 2, gated on for 4 frames	Sharp stab
WIN	triangle C5–E5–G5–C6 arpeggio, fast attack, slow release, ~0.8s	triangle a third below, same notes, very quiet (volume 4)	—	Major chord jingle
GAMEOVER	triangle, fanfare notes (G4–C5–E5–G5–C6), long notes, ~3s	triangle, sustained fifth below	—	End-of-match feel

(The actual note frequencies in Hz are listed in the SID 6581 datasheet — freq = 16.777216 * note_hz / 16777216 in the 16-bit frequency register. We'll define them in a notes.h lookup table in the source.)

Voice 1 waveform is set per state; voice 2 is on only for WAIT and WIN. The voice 3 noise in DRAW is the only sound effect that's not a musical note.

The music is driven by a raster IRQ that updates the SID registers on a per-note schedule. Since each state has a small, fixed set of notes, the IRQ can be very simple — a "next note time" jiffy counter and a pointer into a per-state note table.

7. Inputs

Action	Player 1 (Hare)	Player 2 (Scoot)
Fire	PEEK(0xDC01) & 0x10 == 0	PEEK(0xDC00) & 0x10 == 0
(other directions unused)	(ignore)	(ignore)

PEEK(0xDC00) and PEEK(0xDC01) are the active-low joystick bytes on CIA 1 ports A and B. Bit 4 is the fire button; the lower 4 bits are the directions (up/down/left/right). In the title screen the game also has to read both ports every frame to see if either player has pressed fire.

Note: the C64's keyboard is wired in parallel with the joystick matrix, so PEEK(0xDC00/0xDC01) will also return "pressed" if you hold a key in the right column. For our purposes this is fine (most players use joysticks), but if we want to be strict we can disable the keyboard with POKE 0xDC02, 0xE0 (set keyboard columns as inputs) during gameplay and re-enable with POKE 0xDC02, 0xFF when returning to BASIC.

8. Timing (PAL C64, 50 Hz / 312 lines)

The game runs at the PAL frame rate: 50 fields per second, 312 lines per field. We use a single raster IRQ set to fire on a stable line (line 311, the one right after vertical blank and before any badlines) on every frame, so we have a 50 Hz tick to update game state, read joysticks, update the SID, and redraw the screen.

• TITLE state: update at 25 Hz (every other frame) to flash the prompt. Read joysticks every frame so the input is responsive.
• READY state: fixed-duration, ~1.2 sec = 60 frames. Use a frame counter, not a real-time timer.
• WAIT state: random 100-250 frames. The random number is from the SID's $D41B oscillator register (read-only noise that's effectively random).
• DRAW state: indefinite. Counter increments every frame. The first fire press wins. If for some reason neither player presses for 10 seconds (500 frames), declare it a "fault" and go to TITLE with no point awarded.
• WIN state: fixed 2.0 sec = 100 frames.
• GAMEOVER state: fixed 6.0 sec = 300 frames.

9. The state machine

                  both fire
        +-------------------------+
        |                         v
      TITLE  ----- fire1 only ---->  TITLE  (wait for player 2)
        |                         ^
        |  both still holding? no
        v
      READY   (fixed 60 frames, "ping" jingle)
        |
        v
      WAIT    (random 100..250 frames, suspense music)
        |
        v
      DRAW    (counter++, play stab, wait for fire)
        |    \
        |     \-- both never fire in 500 frames --> fault back to TITLE
        |
        v  fire1 first
      WIN_P1  (100 frames, jingle, +1 to player 1)
        |  \
        |   \-- player 1 score == 5 --> GAMEOVER
        v
      WIN_P2  (100 frames, jingle, +1 to player 2)
        |  \
        |   \-- player 2 score == 5 --> GAMEOVER
        v
      (back to READY for next round)

States are stored in a single byte or enum variable. Each frame, the IRQ handler runs the state machine, updates the SID, and updates the score / counter display.

10. Asset preparation pipeline

Before the C64 ever sees these PNGs, we have to:

1. Crop each PNG to 320×200 (or pick a 320×200 region that looks good). The center 320×200 of each is usually what we want; the aspect ratio is close to 16:10 which is what the C64 has, so a direct crop with no scaling works.
2. Reduce colors to the C64's 16-color palette. The originals look like they were already done with a C64 palette in mind (the orange/purple/yellow/brown/green range is classic C64), but we should still quantize to a 16-color palette that matches the VIC's actual 16 fixed colors. Tools: ImageMagick (-colors 16 +dither or similar), GIMP (Image → Mode → Indexed), or a small Python/PIL script.
3. Convert to 320×200 hires bitmap format — a single .bin file of 8000 bytes (320×200 / 8 bits per byte, row-major, MSB first).
4. Compress with LZO at build time via Oscar64's #embed lzo "file.bin" directive. The decompressed bitmap is stored in a RAM region at startup.
5. Copy to $E000-$FF40 (or wherever the hires area is) at the start of each state transition. Since all 4 screens are different bitmaps, we either keep them all in RAM (4 × 8000 = 32 KB, way too much) or we stream one in at a time from the .prg file at each state transition.

The practical solution: embed all 4 screens with #embed lzo, store them in a reserved region of the .prg file (after the program code and before the runtime data), and at each state transition, decompress the right one into the hires area using oscar_expand_lzo. This is the same pattern Oscar64 samples use for the charsets and sprites.

11. Memory budget (rough)

Item	Size	Where
Compiled C code (logic, IRQ, audio)	~4-6 KB	$0900-$1F00
Stack (C locals, IRQ save area)	1 KB	BSS
Heap (no malloc)	0 KB	n/a
One decompressed hires bitmap	8000 bytes	$6000-$7F40 (or similar 8 KB-aligned window)
4 compressed bitmaps in .prg	~10-15 KB total	After code, in ROM/loaded region
Character set (1 KB) + Color RAM (1 KB)	2 KB	RAM
Custom font (pips, counter digits)	256 bytes	RAM
SID note tables	~200 bytes	ROM
Total loaded	~25-30 KB	Fits comfortably in $0900-$A000 (38 KB) or in a no-ROM build

The game is comfortably within C64 limits. We can even use the default $0900-$A000 region with all ROMs banked in (so the KERNAL ISR trampoline still works), leaving the full 38 KB available for code, data, and one decompressed bitmap at a time.

12. What's not in scope (yet)

• Sound test menu (no — the audio is fixed per state).
• Player name entry (no — pure 2-player hot-seat).
• Difficulty levels (no — the WAIT duration is fixed; we can vary it per round if we want a "tiebreaker" round).
• AIs (no — strictly 2-player).
• Save/load high scores (no — sessions are short).
• NTSC (50 Hz vs 60 Hz) — PAL is the target. NTSC is a small port: different raster line counts, different stable-raster line numbers. The raster IRQ line (311) and frame rate (50 Hz) are the only numbers that need to change.
• The score bar's exact pixel layout — we'll iterate on the visual design after we have the gameplay working.

13. Source layout (proposed)

src/
├── main.c              # entry point, main loop
├── game.c / game.h     # state machine
├── screens.c / .h      # 4 compressed bitmaps + show_screen(N) helper
├── audio.c / .h        # SID note tables + play_state(N) helper
├── input.c / .h        # joystick read helpers
├── score.c / .h        # score bar renderer
├── draw.c / .h         # the white-screen + counter rendering
├── rasterirq.c / .h    # 50 Hz frame tick
├── notes.h             # SID frequency table
├── build.sh            # (already exists)
└── build/              # (gitignored) output

The plan is to keep the code as flat as possible — no region / section pragmas in the first pass, just the default Oscar64 layout, and we reach for #pragma region(…) if the linker complains.

---

The art is striking, the gameplay is dead simple, and the SID has plenty of room for the audio we want. This should be a fun first C64 project.