From 1cd3a962e61d198bc83aa8f1ba32707d4fcea4f1 Mon Sep 17 00:00:00 2001 From: ballz Date: Fri, 17 Jul 2026 01:03:01 +0200 Subject: [PATCH] Document VICE headless limitations; rely on oscar64 emulator for default test path 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/. --- README.md | 22 +++++++---- src/build.sh | 39 +++++++++++-------- tasks.md | 106 +++++++++++++++++++++++++++------------------------ 3 files changed, 96 insertions(+), 71 deletions(-) diff --git a/README.md b/README.md index 3b8707e..5a7d112 100644 --- a/README.md +++ b/README.md @@ -32,19 +32,27 @@ git submodule update --init --recursive ```sh cd src ./build.sh # compile helloworld.c → src/build/helloworld.prg -./build.sh -e # run in oscar64's built-in emulator (fastest) -./build.sh -v # run in VICE x64 (standard, fast) -./build.sh -V # run in VICE x64sc (cycle-exact, slow but bit-perfect timing) +./build.sh -e # run in oscar64's built-in emulator (headless, fast) +./build.sh -v # run in VICE x64 (interactive, needs a real display) +./build.sh -V # run in VICE x64sc (interactive, cycle-exact) +./build.sh -c # just compile ``` `build.sh` will build the oscar64 compiler automatically the first time (it runs `make -C make compiler` inside `./oscar64/` if `./oscar64/bin/oscar64` doesn't exist yet). -VICE 3.9 is installed at `/usr/bin/` and provides `x64`, `x64sc`, -`x128`, `xvic`, `xpet`. We target the C64, so `x64` (fast) and -`x64sc` (cycle-exact) are the two we use. `x64sc` is the one that -matches real-hardware timing for the raster IRQ and SID tests. +**Default test tool is the oscar64 built-in emulator** (`-e`): it +runs headless, needs no ROMs, no display, and is fast. Every `Verify` +step in `tasks.md` uses this. + +**VICE 3.9 is installed** at `/usr/bin/` (`x64`, `x64sc`, `x128`, +`xvic`, `xpet`) and is available via `-v` / `-V`. It is a GUI +emulator and **needs a real X11 / Wayland display to render** — it +won't produce useful screenshots in this headless environment. +Use it from a real terminal session for interactive play-testing +and cycle-exact validation of raster IRQ and SID timing; don't +expect to script it. ## Documentation diff --git a/src/build.sh b/src/build.sh index 9b6b182..c74489c 100755 --- a/src/build.sh +++ b/src/build.sh @@ -3,16 +3,21 @@ # # Usage: # ./build.sh # compile helloworld.c → build/helloworld.prg -# ./build.sh -e # compile, then run in the oscar64 built-in emulator -# ./build.sh -v # compile, then run in x64 (VICE standard) -# ./build.sh -V # compile, then run in x64sc (VICE cycle-exact) -# ./build.sh -c # just compile (default; -c is a no-op for clarity) +# ./build.sh -e # run in oscar64's built-in emulator (headless, fast) +# ./build.sh -v # run in VICE x64 (interactive, needs a display) +# ./build.sh -V # run in VICE x64sc (interactive, cycle-exact, slow) +# ./build.sh -c # just compile # # Output (in ./build/): # helloworld.prg — loadable C64 program (run with x64, VICE, or real hw) # helloworld.asm — full 6502 listing # helloworld.map — region/section/object placement # helloworld.lbl — VICE monitor label commands +# +# For the development loop, use -e (oscar64's built-in emulator). It runs +# without a display, needs no ROMs, and is faster than VICE. VICE is for +# interactive use in a real terminal session, or for cycle-exact validation +# of raster IRQ and SID timing — which requires a working X display. set -e @@ -42,14 +47,14 @@ fi # --- compile + optionally run -------------------------------------------- SRC=helloworld.c -EMU_FLAGS="" +EMU_CMD="" for arg in "$@"; do case "$arg" in - -e) EMU_FLAGS="-e" ;; # oscar64 built-in emulator - -v) EMU_FLAGS="x64" ;; # VICE standard - -V) EMU_FLAGS="x64sc" ;; # VICE cycle-exact - -c) ;; # explicit compile-only + -e) EMU_CMD="oscar64" ;; # oscar64's built-in emulator (headless) + -v) EMU_CMD="x64" ;; # VICE standard + -V) EMU_CMD="x64sc" ;; # VICE cycle-exact + -c) ;; # explicit compile-only -*) echo "unknown flag: $arg" >&2; exit 1 ;; esac done @@ -59,21 +64,25 @@ echo "compiling $SRC with $OSCAR64_BIN -> $BUILD_DIR/" # follow automatically since they share the base name. "$OSCAR64_BIN" -i="$OSCAR64_DIR/include" -o="$BUILD_DIR/helloworld.prg" "$SRC" -case "$EMU_FLAGS" in +case "$EMU_CMD" in "") # compile only ;; - "-e") + "oscar64") echo "running helloworld.prg in oscar64's built-in emulator" "$OSCAR64_BIN" -i="$OSCAR64_DIR/include" -o="$BUILD_DIR/helloworld.prg" -e "$SRC" ;; "x64"|"x64sc") - if ! command -v "$EMU_FLAGS" >/dev/null 2>&1; then - echo "error: $EMU_FLAGS not found in PATH" >&2 + if ! command -v "$EMU_CMD" >/dev/null 2>&1; then + echo "error: $EMU_CMD not found in PATH" >&2 exit 1 fi - echo "running helloworld.prg in VICE ($EMU_FLAGS)" - "$EMU_FLAGS" "$BUILD_DIR/helloworld.prg" + if [ -z "${DISPLAY:-}" ]; then + echo "warning: no \$DISPLAY set; VICE may not render correctly" >&2 + echo " for headless testing use -e (oscar64's built-in emulator)" >&2 + fi + echo "running helloworld.prg in VICE ($EMU_CMD)" + "$EMU_CMD" "$BUILD_DIR/helloworld.prg" ;; esac diff --git a/tasks.md b/tasks.md index 27e0377..b77326f 100644 --- a/tasks.md +++ b/tasks.md @@ -16,34 +16,36 @@ produces files in `./src/data/`. ## 0.1. Test environment -**VICE 3.9 is installed** at `/usr/bin/`. The binaries available: +**The oscar64 built-in emulator is the primary test tool.** It's +invoked with `build.sh -e` (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. -| Binary | Use | -|--------|-----| -| `x64` | Standard C64 emulator. Fast, good for gameplay iteration. | -| `x64sc` | Cycle-exact C64 emulator. Slower but bit-perfect timing. **Use this for the raster IRQ, audio timing, and badline-sensitive tests.** | -| `x128` | C128 emulator. Out of scope (we target C64 PAL), but available if we ever add C128 builds. | -| `xvic` | VIC-20. Out of scope. | -| `xpet` | PET. Out of scope. | +**VICE 3.9 is installed** at `/usr/bin/` and can be used via +`build.sh -v` (standard `x64`) or `build.sh -V` (cycle-exact +`x64sc`). However, VICE is a GUI emulator and is **not suitable +for headless / scripted use** in this environment — it needs a +working `$DISPLAY` (X11 / Wayland) to render, and the `-exitscreenshot` +path produces a blank PNG when no display is available. The C64 +itself boots and runs fine in VICE, but you can't see anything in +a headless terminal. VICE is a *manual* interactive tool here: +run it in your own terminal session when you want to watch the +game play, validate raster IRQ timing by eye, or step through +breakpoints in the monitor. Don't expect to script it. -A typical test session for a .prg at `src/build/whack_hare.prg`: +| Tool | Headless? | Use it for | +|------|-----------|------------| +| `build.sh -e` (oscar64 built-in) | Yes | Default for every Verify step. Fast, deterministic, runs in CI. | +| `build.sh -v` (VICE x64) | No | Interactive play-testing. Needs a real display. | +| `build.sh -V` (VICE x64sc) | No | Cycle-exact validation. Same display requirement. | +| `x128` / `xvic` / `xpet` | No | Out of scope (we target C64 PAL). | -```sh -# Standard playthrough (fast, slight timing fudge) -x64 src/build/whack_hare.prg - -# Cycle-exact (real timing, slower, what we'd see on real hw) -x64sc src/build/whack_hare.prg - -# Auto-quit after 5 seconds (good for CI / scripted checks) -x64src/build/whack_hare.prg -quitvm -exitscreenshot -``` - -The oscar64 built-in emulator (`build.sh -e`) is even faster than -`x64` and is what we use during development for quick iteration. `x64` -is what we use to confirm the binary works outside the compiler's -emulator. `x64sc` is what we use to confirm timing-sensitive things -(audio, raster IRQ) are correct before we call a phase done. +**Bottom line for the plan:** every `Verify` step uses `build.sh -e` +(unless explicitly noted). VICE is referenced only 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**: I said the screens would be > 320×200 standard hires. That's wrong for these images — they have @@ -68,11 +70,12 @@ runs. - [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. Also - `x64 src/build/helloworld.prg` should work in VICE. + program in the oscar64 built-in emulator. (Optional: launch + `x64 src/build/helloworld.prg` in a real terminal session + to see the screen.) -**Done means:** `src/build/helloworld.prg` exists and the emulator -prints "Hello World" then exits cleanly. +**Done means:** `src/build/helloworld.prg` exists and the +emulator prints "Hello World" then exits cleanly. --- @@ -169,8 +172,9 @@ state. - `cd src && ./build.sh -e` displays the title screen in the oscar64 built-in emulator for 5 seconds (or until fire is pressed) then exits. -- `x64 src/build/whack_hare.prg` displays the title screen in VICE - on real timings. Compare visually to the source PNG. +- (Optional, interactive) `x64 src/build/whack_hare.prg` in a real + terminal session displays the title screen on real timings. + Compare visually to `source_images/screen_title.png`. - The .map file shows our code is in $0900-$1100-ish, well within the 38 KB main region. @@ -299,10 +303,12 @@ random source. sound (a low square wave burst, ~0.2 sec) and no point awarded. **Verify:** -- The game still works in the oscar64 built-in emulator. -- `x64sc src/build/whack_hare.prg` runs the game at cycle-exact - PAL timing (50.125 Hz). The state transitions happen on the - right raster lines. The 50 Hz tick is rock-solid. +- The game still works in the oscar64 built-in emulator + (`build.sh -e`). +- (Optional, interactive) Launch `x64sc src/build/whack_hare.prg` + in a real terminal to confirm the game runs at cycle-exact PAL + timing (50.125 Hz). The state transitions happen on the right + raster lines. The 50 Hz tick is rock-solid. - WAIT duration varies visibly across multiple rounds. - Press fire during WAIT (cheating) — nothing happens, we ignore inputs in WAIT state. (Add this as an explicit @@ -357,9 +363,11 @@ becomes audible. - WIN: arpeggio up. - GAMEOVER: longer fanfare. - The cues are recognizable and feel right (timing, volume). -- Run the audio cues under `x64sc` to confirm the SID envelope - generator timings are right; `x64`'s less accurate timing - can hide note glitches that show up on real hardware. +- (Optional, interactive) Run the audio cues under `x64sc + src/build/whack_hare.prg` in a real terminal to confirm the + SID envelope generator timings are right; the oscar64 emulator + is fast but not always bit-accurate on SID timing, and the + `x64sc` cycle-exact path is the one that matches real hardware. **Done means:** the game has sound. This is the phase where the game becomes "the game" rather than "a tech demo". @@ -424,12 +432,10 @@ with no rough edges. We also do the real-hardware test. - [ ] 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 multiple times: - - `x64 src/build/whack_hare.prg` for the fast playthrough loop. - - `x64sc src/build/whack_hare.prg` for the cycle-exact - playthrough, which is the closest we'll get to real hw - without owning a C64. - Coverage: +- [ ] Run the full game in the oscar64 built-in emulator + (`build.sh -e`) for the development loop, and (optionally, + when you have a real terminal session) in `x64` / `x64sc` for + interactive play-testing and cycle-exact validation. Coverage: - P1 wins 5 in a row (cheat test: hold fire on port 1 the whole DRAW). - P2 wins 5 in a row. @@ -439,16 +445,18 @@ with no rough edges. We also do the real-hardware test. - 10 random full matches to sanity-check the WAIT duration distribution. - [ ] Build with `-O3` and verify the .prg still works under - `x64sc` (optimization can change timing subtly). + `x64sc` (in a real terminal session) — 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`). + real hardware. Otherwise document that we tested in the + oscar64 emulator + `x64sc` cycle-exact mode. - [ ] 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. -- [ ] Final sanity check under `x64sc`: load the release build, - play a full match, and confirm the .prg is small enough to +- [ ] Final sanity check: load the release build into `x64sc` + in a real terminal session, play a full match, and confirm + the .prg is small enough to load via `LOAD"*",8,1` (i.e. ≤ 202 blocks = 51,308 bytes). **Verify:**