c64-kb 0.17.0

package/templates/action-puzzle/src/render.c

@@ -0,0 +1,239 @@
+// render.c: character set, cave drawing, text and the glyph animation.
+#include "render.h"
+#include "cave.h"
+#include <c64/vic.h>
+
+// Screen colour per element code. Original palette choices.
+static const char tint[CODES] = {
+    VCOL_BLACK, VCOL_BROWN, VCOL_RED, VCOL_MED_GREY,            // space dirt brick steel
+    VCOL_LT_GREY, VCOL_LT_GREY, VCOL_CYAN, VCOL_CYAN,            // boulder, gem
+    VCOL_MED_GREY, VCOL_LT_GREEN, VCOL_YELLOW, VCOL_BLACK,       // exit shut/open, player, unused
+    VCOL_ORANGE, VCOL_ORANGE, VCOL_ORANGE, VCOL_ORANGE,          // spark, four headings
+    VCOL_PURPLE, VCOL_PURPLE, VCOL_PURPLE, VCOL_PURPLE,          // moth
+    VCOL_WHITE, VCOL_WHITE, VCOL_WHITE,                          // blast stages
+    VCOL_LT_BLUE, VCOL_LT_BLUE, VCOL_LT_BLUE                     // burst stages
+};
+
+// Original 8 x 8 glyphs, one per element code. Every glyph a check may
+// sample has ink at pixel (4, 4), the centre check.py reads for a cell.
+static const char glyphs[CODES][8] = {
+    { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 },  // space
+    { 0xa2, 0x08, 0x51, 0x04, 0x8a, 0x20, 0x45, 0x10 },  // dirt: speckle
+    { 0xfe, 0xfe, 0xfe, 0x00, 0xef, 0xef, 0xef, 0x00 },  // brick
+    { 0xff, 0x81, 0xbd, 0xbd, 0xbd, 0xbd, 0x81, 0xff },  // steel plate
+    { 0x3c, 0x7e, 0xdf, 0xff, 0xfb, 0xff, 0x7e, 0x3c },  // boulder
+    { 0x3c, 0x7e, 0xdf, 0xff, 0xfb, 0xff, 0x7e, 0x3c },  // boulder, falling
+    { 0x18, 0x3c, 0x7e, 0xff, 0x7e, 0x3c, 0x18, 0x00 },  // gem (animated)
+    { 0x18, 0x3c, 0x7e, 0xff, 0x7e, 0x3c, 0x18, 0x00 },  // gem, falling
+    { 0xff, 0x81, 0xbd, 0xbd, 0xbd, 0xbd, 0x81, 0xff },  // exit, shut: looks like steel
+    { 0xff, 0x81, 0x81, 0x89, 0x8d, 0x81, 0x81, 0xff },  // exit, open (animated)
+    { 0x18, 0x18, 0x3c, 0x5a, 0x18, 0x24, 0x24, 0x66 },  // player
+    { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 },  // unused
+    { 0x08, 0x08, 0x2a, 0x1c, 0x7f, 0x1c, 0x2a, 0x08 },  // spark (animated), x4
+    { 0x08, 0x08, 0x2a, 0x1c, 0x7f, 0x1c, 0x2a, 0x08 },
+    { 0x08, 0x08, 0x2a, 0x1c, 0x7f, 0x1c, 0x2a, 0x08 },
+    { 0x08, 0x08, 0x2a, 0x1c, 0x7f, 0x1c, 0x2a, 0x08 },
+    { 0x00, 0x66, 0xff, 0xff, 0x7e, 0x3c, 0x5a, 0x81 },  // moth (animated), x4
+    { 0x00, 0x66, 0xff, 0xff, 0x7e, 0x3c, 0x5a, 0x81 },
+    { 0x00, 0x66, 0xff, 0xff, 0x7e, 0x3c, 0x5a, 0x81 },
+    { 0x00, 0x66, 0xff, 0xff, 0x7e, 0x3c, 0x5a, 0x81 },
+    { 0x91, 0x52, 0x3c, 0xff, 0x3c, 0x52, 0x91, 0x10 },  // blast 1..3
+    { 0x00, 0x52, 0x24, 0x18, 0x18, 0x24, 0x52, 0x00 },
+    { 0x00, 0x00, 0x24, 0x18, 0x18, 0x24, 0x00, 0x00 },
+    { 0x91, 0x52, 0x3c, 0xff, 0x3c, 0x52, 0x91, 0x10 },  // burst 1..3
+    { 0x00, 0x52, 0x24, 0x18, 0x18, 0x24, 0x52, 0x00 },
+    { 0x00, 0x00, 0x24, 0x18, 0x18, 0x24, 0x00, 0x00 }
+};
+
+// Animation frames: four for the gem's sparkle, two each for the enemies
+// and the open exit. Pixel (4, 4) stays inked in every frame.
+static const char gem_anim[4][8] = {
+    { 0x18, 0x3c, 0x7e, 0xff, 0x7e, 0x3c, 0x18, 0x00 },
+    { 0x18, 0x24, 0x5a, 0xbd, 0x5a, 0x24, 0x18, 0x00 },
+    { 0x18, 0x3c, 0x7e, 0xdb, 0x7e, 0x3c, 0x18, 0x00 },
+    { 0x18, 0x3c, 0x76, 0xff, 0x6e, 0x3c, 0x18, 0x00 }
+};
+static const char spark_anim[2][8] = {
+    { 0x08, 0x08, 0x2a, 0x1c, 0x7f, 0x1c, 0x2a, 0x08 },
+    { 0x00, 0x41, 0x22, 0x14, 0x08, 0x14, 0x22, 0x41 }
+};
+static const char moth_anim[2][8] = {
+    { 0x00, 0x66, 0xff, 0xff, 0x7e, 0x3c, 0x5a, 0x81 },
+    { 0x00, 0x00, 0x24, 0x7e, 0xff, 0x3c, 0x24, 0x00 }
+};
+static const char exit_anim[2][8] = {
+    { 0xff, 0x81, 0x81, 0x89, 0x8d, 0x81, 0x81, 0xff },
+    { 0x00, 0x7e, 0x7e, 0x76, 0x7a, 0x7e, 0x7e, 0x00 }
+};
+
+void render_init(void)
+{
+    // Copy the ROM glyphs of screen codes 0-63 (letters, digits,
+    // punctuation) so text, the HUD and the harness meter read as usual.
+    // The character ROM is visible to the CPU at $D000 with $01 = $33; the
+    // KERNAL IRQ is off, so nothing can run while I/O is banked out.
+    char *rom = (char *)0xd000;
+    char port = *(volatile char *)0x01;
+    *(volatile char *)0x01 = 0x33;
+    for (unsigned i = 0; i < 512; i++)
+        CHARSET[i] = rom[i];
+    *(volatile char *)0x01 = port;
+    for (char c = 0; c < CODES; c++)
+        for (char k = 0; k < 8; k++)
+            CHARSET[(GLYPH_BASE + c) * 8 + k] = glyphs[c][k];
+    vic.memptr = 0x18;                          // screen $0400, characters $2000
+    vic.color_border = VCOL_BLACK;
+    vic.color_back = VCOL_BLACK;
+}
+
+void render_clear(void)
+{
+    for (unsigned i = 0; i < 1000; i++)
+    {
+        SCREEN[i] = 0x20;
+        COLOUR[i] = VCOL_WHITE;
+    }
+}
+
+void draw_cell(unsigned i)
+{
+    char t = cave[i] & 0x1f;
+    SCREEN[CW * CAVE_ROW0 + i] = GLYPH_BASE + t;
+    COLOUR[CW * CAVE_ROW0 + i] = tint[t];
+}
+
+// Rows waiting for a redraw after a dirty-list overflow.
+static bool pending[CH];
+char render_npending;
+
+// One cave row, with three row pointers and an 8-bit index.
+void draw_row(char y)
+{
+    const char *src = cave + CW * y;
+    char *scr = SCREEN + CW * (CAVE_ROW0 + y);
+    char *col = COLOUR + CW * (CAVE_ROW0 + y);
+    for (char x = 0; x < CW; x++)
+    {
+        char t = src[x] & 0x1f;
+        scr[x] = GLYPH_BASE + t;
+        col[x] = tint[t];
+    }
+}
+
+void draw_cave(void)
+{
+    for (char y = 0; y < CH; y++)
+        draw_row(y);
+    render_npending = 0;
+    for (char y = 0; y < CH; y++)
+        pending[y] = false;
+}
+
+// A slice's changes: the dirty list. On overflow the list is incomplete, so
+// every row the slice's moves and explosions can reach (one above to one
+// below) is queued instead, and draw_pending redraws them two a frame. That
+// bounds the frame: redrawing all seven rows at once in the first version
+// cost 55,305 cycles, almost three PAL frames (measured in review).
+void draw_dirty(char y0, char y1)
+{
+    if (cave_overflow)
+    {
+        if (y1 > CH - 1)
+            y1 = CH - 1;
+        for (char y = y0 - 1; y <= y1; y++)
+            if (!pending[y])
+            {
+                pending[y] = true;
+                render_npending++;
+            }
+    }
+    else
+        for (char n = 0; n < cave_ndirty; n++)
+            draw_cell(cave_dirty[n]);
+}
+
+void draw_pending(void)
+{
+    char budget = ROWS_PER_FRAME;
+    for (char y = 0; y < CH && budget && render_npending; y++)
+        if (pending[y])
+        {
+            draw_row(y);
+            pending[y] = false;
+            render_npending--;
+            budget--;
+        }
+}
+
+static void set_glyph(char code, const char *src)
+{
+    char *dst = CHARSET + (GLYPH_BASE + code) * 8;
+    for (char k = 0; k < 8; k++)
+        dst[k] = src[k];
+}
+
+void render_animate(char frame)
+{
+    if (frame & 3)
+        return;
+    char phase = (frame >> 2) & 3;
+    set_glyph(GEM, gem_anim[phase]);
+    set_glyph(GEM_F, gem_anim[phase]);
+    for (char h = 0; h < 4; h++)
+    {
+        set_glyph(SPARK + h, spark_anim[phase & 1]);
+        set_glyph(MOTH + h, moth_anim[phase & 1]);
+    }
+    set_glyph(EXIT_OPEN, exit_anim[phase >> 1]);
+}
+
+// Text in upper case, digits and punctuation, written as screen codes.
+void put_text(char row, char col, const char *s, char colour)
+{
+    char *p = SCREEN + 40 * row + col;
+    char *q = COLOUR + 40 * row + col;
+    while (*s)
+    {
+        char c = *s++;
+        if (c >= 'A' && c <= 'Z')
+            c = c - 'A' + 1;
+        *p++ = c;
+        *q++ = colour;
+    }
+}
+
+void put_codes(char row, char col, const char *codes, char n, char colour)
+{
+    char *p = SCREEN + 40 * row + col;
+    char *q = COLOUR + 40 * row + col;
+    for (char i = 0; i < n; i++)
+    {
+        p[i] = codes[i];
+        q[i] = colour;
+    }
+}
+
+// v as `digits` decimal digits (1 to 6), leading zeros shown.
+void put_num(char row, char col, unsigned long v, char digits, char colour)
+{
+    static const unsigned long pw[6] = { 100000, 10000, 1000, 100, 10, 1 };
+    char *p = SCREEN + 40 * row + col;
+    char *q = COLOUR + 40 * row + col;
+    for (char i = 6 - digits; i < 6; i++)
+    {
+        char d = 0x30;
+        while (v >= pw[i]) { v -= pw[i]; d++; }
+        *p++ = d;
+        *q++ = colour;
+    }
+}
+
+void fill_box(char row0, char col0, char row1, char col1, char colour)
+{
+    for (char r = row0; r <= row1; r++)
+        for (char c = col0; c <= col1; c++)
+        {
+            SCREEN[40 * r + c] = 0x20;
+            COLOUR[40 * r + c] = colour;
+        }
+}

package/templates/action-puzzle/src/render.h

@@ -0,0 +1,31 @@
+// render.h: the screen. Text mode, one character per cave cell, a RAM
+// character set at $2000 whose codes $40 + element hold the cave's glyphs
+// (animated by rewriting glyph bytes: c64-kb technique charset_animation).
+#ifndef RENDER_H
+#define RENDER_H
+
+#define SCREEN      ((char *)0x0400)
+#define COLOUR      ((char *)0xd800)
+#define CHARSET     ((char *)0x2000)
+#define CAVE_ROW0   1           // screen row of cave row 0
+#define GLYPH_BASE  0x40        // screen code of element 0
+
+void render_init(void);                         // charset, $D018, colours
+void render_clear(void);                        // blank the whole screen
+void draw_cell(unsigned i);                     // cave cell i to the screen
+void draw_cave(void);                           // all 880 cells
+void draw_row(char y);                          // one cave row
+void draw_dirty(char y0, char y1);              // the cells the last slice changed, or queue its rows
+void draw_pending(void);                        // redraw up to ROWS_PER_FRAME queued rows
+extern char render_npending;                    // rows still queued
+
+#define ROWS_PER_FRAME 2                        // queued rows redrawn a frame after an overflow
+void render_animate(char frame);                // glyph animation, one phase in four frames
+void put_text(char row, char col, const char *s, char colour);
+void put_codes(char row, char col, const char *codes, char n, char colour);
+void put_num(char row, char col, unsigned long v, char digits, char colour);
+void fill_box(char row0, char col0, char row1, char col1, char colour);
+
+#pragma compile("render.c")
+
+#endif

package/templates/action-puzzle/src/sound.c

@@ -0,0 +1,158 @@
+// sound.c: the tune and the effects. The tune is original: an arpeggiated
+// A minor, F, G, E loop, lead on voice 1 (pulse), bass on voice 2
+// (triangle). Note lengths are in frames, so on NTSC it plays 20 % faster
+// (c64-kb pitfall pal_ntsc_tempo_mismatch); the pitches come from the
+// model's own table, so they are right on both.
+#include "sound.h"
+#include <c64/sid.h>
+
+#include "gen_notes.h"
+
+#define REST 0xff
+
+// Note numbers are semitones above C1 (gen_notes.h): 45 is A4.
+static const char lead[32] = {
+    45, 48, 52, 48, 45, 52, 57, 52,             // A minor
+    41, 45, 48, 45, 53, 48, 45, 41,             // F
+    43, 47, 50, 47, 55, 50, 47, 43,             // G
+    40, 44, 47, 44, 52, 47, 44, REST            // E
+};
+static const char bass[16] = {
+    21, 21, 28, 21,  17, 17, 24, 17,  19, 19, 26, 19,  16, 16, 23, 16
+};
+#define LEAD_LEN 6                              // frames a lead note lasts
+#define BASS_LEN 12
+
+static const unsigned *notes;
+static char lead_pos, lead_timer, bass_pos, bass_timer;
+static char volume = 15;
+
+// ---- effects on voice 3 ---------------------------------------------------
+// One row per frame: frequency and control byte; the row with ctrl SFX_END
+// ends the effect and frees the voice. The first row of each effect is
+// TEST + GATE, the hard restart the sfx-engine recipe uses.
+#define SFX_END 0xff
+typedef struct { unsigned freq; char ctrl; } SfxRow;
+typedef struct { char prio; char attdec; char susrel; unsigned pw; const SfxRow *rows; } Sfx;
+
+static const SfxRow dig_rows[] = {
+    { 0x3000, SID_CTRL_TEST | SID_CTRL_GATE }, { 0x3000, SID_CTRL_NOISE | SID_CTRL_GATE },
+    { 0x2400, SID_CTRL_NOISE }, { 0, SFX_END } };
+static const SfxRow push_rows[] = {
+    { 0x0400, SID_CTRL_TEST | SID_CTRL_GATE }, { 0x0400, SID_CTRL_RECT | SID_CTRL_GATE },
+    { 0x0380, SID_CTRL_RECT | SID_CTRL_GATE }, { 0x0300, SID_CTRL_RECT }, { 0, SFX_END } };
+static const SfxRow land_rows[] = {
+    { 0x0800, SID_CTRL_TEST | SID_CTRL_GATE }, { 0x0800, SID_CTRL_NOISE | SID_CTRL_GATE },
+    { 0x0600, SID_CTRL_NOISE | SID_CTRL_GATE }, { 0x0400, SID_CTRL_NOISE }, { 0, SFX_END } };
+static const SfxRow gem_rows[] = {
+    { 0x2000, SID_CTRL_TEST | SID_CTRL_GATE }, { 0x2000, SID_CTRL_RECT | SID_CTRL_GATE },
+    { 0x2800, SID_CTRL_RECT | SID_CTRL_GATE }, { 0x3000, SID_CTRL_RECT | SID_CTRL_GATE },
+    { 0x4000, SID_CTRL_RECT | SID_CTRL_GATE }, { 0x4000, SID_CTRL_RECT }, { 0, SFX_END } };
+static const SfxRow open_rows[] = {
+    { 0x1000, SID_CTRL_TEST | SID_CTRL_GATE }, { 0x1000, SID_CTRL_TRI | SID_CTRL_GATE },
+    { 0x1400, SID_CTRL_TRI | SID_CTRL_GATE }, { 0x1800, SID_CTRL_TRI | SID_CTRL_GATE },
+    { 0x2000, SID_CTRL_TRI | SID_CTRL_GATE }, { 0x2800, SID_CTRL_TRI | SID_CTRL_GATE },
+    { 0x3000, SID_CTRL_TRI | SID_CTRL_GATE }, { 0x4000, SID_CTRL_TRI | SID_CTRL_GATE },
+    { 0x4000, SID_CTRL_TRI }, { 0, SFX_END } };
+static const SfxRow boom_rows[] = {
+    { 0x1800, SID_CTRL_TEST | SID_CTRL_GATE }, { 0x1800, SID_CTRL_NOISE | SID_CTRL_GATE },
+    { 0x1400, SID_CTRL_NOISE | SID_CTRL_GATE }, { 0x1000, SID_CTRL_NOISE | SID_CTRL_GATE },
+    { 0x0c00, SID_CTRL_NOISE | SID_CTRL_GATE }, { 0x0a00, SID_CTRL_NOISE | SID_CTRL_GATE },
+    { 0x0800, SID_CTRL_NOISE }, { 0x0600, SID_CTRL_NOISE }, { 0x0500, SID_CTRL_NOISE },
+    { 0x0400, SID_CTRL_NOISE }, { 0x0300, SID_CTRL_NOISE }, { 0, SFX_END } };
+
+static const Sfx effects[6] = {
+    { 0, SID_ATK_2 | SID_DKY_24,  0x00 | SID_DKY_48,  0x0800, dig_rows  },
+    { 1, SID_ATK_2 | SID_DKY_48,  0x40 | SID_DKY_114, 0x0400, push_rows },
+    { 1, SID_ATK_2 | SID_DKY_48,  0x40 | SID_DKY_114, 0x0800, land_rows },
+    { 2, SID_ATK_2 | SID_DKY_48,  0x80 | SID_DKY_168, 0x0800, gem_rows  },
+    { 3, SID_ATK_2 | SID_DKY_114, 0xa0 | SID_DKY_204, 0x0800, open_rows },
+    { 4, SID_ATK_2 | SID_DKY_114, 0xf0 | SID_DKY_750, 0x0800, boom_rows }
+};
+
+static const Sfx *sfx_cur;                      // the effect that owns voice 3, or 0
+static const SfxRow *sfx_row;
+
+void sound_init(bool ntsc)
+{
+    for (char r = 0; r < 25; r++)
+        ((volatile char *)0xd400)[r] = 0;       // silence first: no pops
+    notes = ntsc ? note_ntsc : note_pal;
+    sid.voices[0].pwm = 0x0600;
+    sid.voices[0].attdec = SID_ATK_2 | SID_DKY_114;
+    sid.voices[0].susrel = 0x60 | SID_DKY_168;
+    sid.voices[1].attdec = SID_ATK_2 | SID_DKY_168;
+    sid.voices[1].susrel = 0x80 | SID_DKY_114;
+    lead_pos = bass_pos = 0;
+    lead_timer = bass_timer = 0;
+    sfx_cur = nullptr;
+    sid.fmodevol = volume;
+}
+
+// One voice of the tune: a new note when the timer runs out, the gate
+// released on the note's last frame so the next one retriggers.
+static void voice_step(char v, char note, char *timer, char len, char wave)
+{
+    if (*timer == 0)
+    {
+        *timer = len;
+        if (note != REST)
+        {
+            sid.voices[v].freq = notes[note];
+            sid.voices[v].ctrl = wave | SID_CTRL_GATE;
+        }
+    }
+    if (--*timer == 0)
+        sid.voices[v].ctrl = wave;
+}
+
+void music_play(void)
+{
+    char was = lead_timer;
+    voice_step(0, lead[lead_pos], &lead_timer, LEAD_LEN, SID_CTRL_RECT);
+    if (was == 1)
+        lead_pos = (lead_pos + 1) & 31;
+    was = bass_timer;
+    voice_step(1, bass[bass_pos], &bass_timer, BASS_LEN, SID_CTRL_TRI);
+    if (was == 1)
+        bass_pos = (bass_pos + 1) & 15;
+    sid.fmodevol = volume;
+}
+
+void sfx_play(char fx)
+{
+    const Sfx *e = effects + fx;
+    if (sfx_cur && e->prio < sfx_cur->prio)
+        return;                                 // a more important effect keeps the voice
+    sfx_cur = e;
+    sfx_row = e->rows;
+    sid.voices[2].attdec = e->attdec;
+    sid.voices[2].susrel = e->susrel;
+    sid.voices[2].pwm = e->pw;
+}
+
+void sfx_update(void)
+{
+    if (!sfx_cur)
+        return;
+    if (sfx_row->ctrl == SFX_END)
+    {
+        sfx_cur = nullptr;
+        return;
+    }
+    sid.voices[2].freq = sfx_row->freq;
+    sid.voices[2].ctrl = sfx_row->ctrl;
+    sfx_row++;
+}
+
+void sound_mute(bool on)
+{
+    volume = on ? 0 : 15;
+    sid.fmodevol = volume;
+    if (on)
+    {
+        sid.voices[0].ctrl = 0;                 // gates off: nothing drones through a disk call
+        sid.voices[1].ctrl = 0;
+        sid.voices[2].ctrl = 0;
+    }
+}

package/templates/action-puzzle/src/sound.h

@@ -0,0 +1,22 @@
+// sound.h: an original two-voice tune (voices 1 and 2) and a table-driven
+// effects engine on voice 3 (c64-kb techniques sid_play_routine_pattern and
+// sfx_engine_beside_music). Call music_play() then sfx_update() once a frame.
+#ifndef SOUND_H
+#define SOUND_H
+
+#define SFX_DIG   0
+#define SFX_PUSH  1
+#define SFX_LAND  2
+#define SFX_GEM   3
+#define SFX_OPEN  4
+#define SFX_BOOM  5
+
+void sound_init(bool ntsc);     // silence the SID, pick the note table
+void music_play(void);          // one frame of the tune (the "play" call)
+void sfx_play(char fx);         // start an effect; a higher-priority one keeps the voice
+void sfx_update(void);          // one frame of the effect, after music_play
+void sound_mute(bool on);       // volume 0 during disk calls
+
+#pragma compile("sound.c")
+
+#endif

package/templates/action-puzzle/tools/disk_check.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""disk_check.py HARNESS_DIR BUILD_DIR [pal|ntsc]: grade `make disktest`.
+
+Reads from BUILD_DIR hiscore-1.seq and hiscore-2.seq (the file c1541 read
+back after each save run) and disktest-dir.txt (the directory at the end),
+and from shots/ the pictures disk-save.png, disk-save2.png and disk-load.png.
+
+  save 1  no file yet: the default table plus ABE 158 in row 4, SAVED (00)
+  save 2  the saved table loaded, ABE 158 again, a tie, so row 5: the file is
+          replaced (scratch, then write), SAVED (00), one HISCORE entry
+  load    the release PRG booted from the D64 shows the second table and
+          "SCORES FROM DISK (00)", which it prints only when its start-up
+          read of the file succeeded (hiscore.c, HI_LOADED)
+"""
+import os
+import struct
+import sys
+
+
+def rows_of(path, fails):
+    data = open(path, "rb").read()
+    if len(data) != 38 or data[:3] != bytes([0x43, 0x52, 1]):
+        fails.append(f"{path}: {len(data)} bytes, header {data[:3].hex()}, want 38 bytes, 435201")
+        return []
+    rows = []
+    for r in range(5):
+        name = "".join(chr(64 + c) for c in data[3 + 7 * r:6 + 7 * r])
+        rows.append((name, struct.unpack("<I", data[6 + 7 * r:10 + 7 * r])[0]))
+    print(f"disk_check: {os.path.basename(path)}: {rows}")
+    return rows
+
+
+def main():
+    harness, build = sys.argv[1:3]
+    model = sys.argv[3] if len(sys.argv) > 3 else "pal"
+    sys.path.insert(0, harness)
+    import check
+
+    fails = []
+    head = [("DIG", 400), ("ROX", 300), ("GEM", 200), ("ABE", 158)]
+    if rows_of(os.path.join(build, "hiscore-1.seq"), fails) != head + [("MUD", 100)]:
+        fails.append("save 1: the file is not the default table with ABE 158 in row 4")
+    if rows_of(os.path.join(build, "hiscore-2.seq"), fails) != head + [("ABE", 158)]:
+        fails.append("save 2: the file was not replaced by the table with ABE 158 in rows 4 and 5")
+    listing = open(os.path.join(build, "disktest-dir.txt")).read()
+    n = sum('"hiscore"' in line for line in listing.splitlines())
+    print(f"disk_check: {n} HISCORE entry in the directory")
+    if n != 1:
+        fails.append(f"the directory holds {n} HISCORE entries, want 1")
+
+    glyphs = check.load_glyphs()
+    want = {
+        "disk-save": [(None, 5), (23, 0, "RESULT 01 PASS"), (14, 13, "4. ABE 000158"),
+                      (17, 9, "SAVED TO DISK     (00)")],
+        "disk-save2": [(15, 13, "5. ABE 000158"), (17, 9, "SAVED TO DISK     (00)")],
+        "disk-load": [(2, 15, "CAVE RUN"), (12, 13, "4. ABE 000158"), (13, 13, "5. ABE 000158"),
+                      (16, 9, "SCORES FROM DISK  (00)")],
+    }
+    for pic, items in want.items():
+        shot = check.Shot(os.path.join("shots", pic + ".png"), model)
+        for item in items:
+            if item[0] is None:
+                ok = shot.index(*check.BORDER_SAMPLE) == item[1]
+                print(f"{'PASS' if ok else 'FAIL'} {pic} border green")
+            else:
+                row, col, text = item
+                got = check.read_text(shot, glyphs, row, col, len(text))
+                ok = got == text
+                print(f"{'PASS' if ok else 'FAIL'} {pic} row {row} col {col}: '{got}'")
+            if not ok:
+                fails.append(f"{pic}: {item}")
+    print("disk_check: PASS" if not fails else f"disk_check: {len(fails)} FAILED: {fails}")
+    sys.exit(1 if fails else 0)
+
+
+if __name__ == "__main__":
+    main()

package/templates/action-puzzle/tools/drive.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""drive.py PRG STEP...: play the `make joy` build headless over VICE's binary monitor.
+
+    python3 tools/drive.py build/action-puzzle-joy.prg "until:FIRE TO START" tap:fire \
+        until:LIVES hold:right "until:ENTER YOUR NAME" tap:up tap:fire tap:fire tap:fire \
+        "until:GAME OVER" print
+
+The joy build reads its port byte from $02FE (JOY_SOURCE) instead of $DC00,
+because the windowless VICE's joyport commands never reach $DC00 (see
+README). Steps:
+  hold:DIR     hold up, down, left, right or fire (DIR+DIR for two); hold:none releases
+  tap:DIR      press for 0.05 s of run time, then release for 0.1 s
+  run:SECONDS  let the machine run (warp) that long in real time
+  until:TEXT   run until TEXT is on screen (screen RAM read as text; 300 s limit)
+  print        print the screen's non-blank rows
+It reads screen RAM, not a picture: the windowless build's monitor
+screenshots came back stale while a game was running.
+"""
+import os
+import socket
+import struct
+import subprocess
+import sys
+import time
+
+X64SC = os.environ.get("X64SC", os.path.expanduser("~/Developer/c64/vice-headless/bin/x64sc"))
+PORT = int(os.environ.get("DRIVE_PORT", "6581"))
+BITS = {"none": 0, "up": 1, "down": 2, "left": 4, "right": 8, "fire": 16}
+
+
+class Vice:
+    def __init__(self, prg):
+        self.proc = subprocess.Popen(
+            [X64SC, "-default", "-warp", "+sound", "-autostartprgmode", "1", "-binarymonitor",
+             "-binarymonitoraddress", f"ip4://127.0.0.1:{PORT}", "-autostart", prg],
+            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+        for _ in range(100):
+            try:
+                self.sock = socket.create_connection(("127.0.0.1", PORT))
+                break
+            except OSError:
+                time.sleep(0.1)
+        else:
+            sys.exit("drive: no monitor")
+        self.rid = 0
+
+    def _read(self, n):
+        b = b""
+        while len(b) < n:
+            b += self.sock.recv(n - len(b)) or sys.exit("drive: monitor closed")
+        return b
+
+    def cmd(self, code, body=b""):
+        """One binary-monitor command (it stops the machine); returns the reply's body."""
+        self.rid += 1
+        self.sock.sendall(struct.pack("<BBIIB", 2, 2, len(body), self.rid, code) + body)
+        while True:
+            _, _, n, _, _, rid = struct.unpack("<BBIBBI", self._read(12))
+            data = self._read(n)
+            if rid == self.rid:
+                return data
+
+    def joy(self, bits):                                  # active low, as $DC00 reads
+        self.cmd(0x02, struct.pack("<BHHBH", 0, 0x02fe, 0x02fe, 0, 0) + bytes([0xff & ~bits]))
+
+    def run(self, seconds):
+        self.cmd(0xaa)                                    # exit the monitor: the machine runs
+        time.sleep(seconds)
+
+    def screen(self):
+        d = self.cmd(0x01, struct.pack("<BHHBH", 0, 0x0400, 0x07e7, 0, 0))[2:]
+        text = lambda c: chr(c + 64) if 1 <= c <= 26 else (chr(c) if 32 <= c < 64 else "~")
+        return ["".join(text(c & 0x7f) for c in d[r * 40:r * 40 + 40]) for r in range(25)]
+
+
+def main():
+    vice = Vice(sys.argv[1])
+    try:
+        vice.joy(0)
+        for step in sys.argv[2:]:
+            name, _, arg = step.partition(":")
+            if name in ("hold", "tap"):
+                vice.joy(sum(BITS[d] for d in arg.split("+")))
+                if name == "tap":
+                    vice.run(0.05)
+                    vice.joy(0)
+                    vice.run(0.1)
+            elif name == "run":
+                vice.run(float(arg))
+            elif name == "until":
+                t0 = time.time()
+                while not any(arg in row for row in vice.screen()):
+                    if time.time() - t0 > 300:
+                        sys.exit(f"drive: '{arg}' never appeared")
+                    vice.run(0.1)
+                print(f"drive: '{arg}' on screen")
+            elif name == "print":
+                for row in vice.screen():
+                    if row.strip():
+                        print("|" + row + "|")
+    finally:
+        vice.proc.kill()
+
+
+if __name__ == "__main__":
+    main()