c64-kb 0.17.0

package/templates/platformer/src/verdict.h

@@ -0,0 +1,206 @@
+// verdict.h: the AUTOPILOT build grades itself once the script is over,
+// from the game's own state, and freezes. Included by main.c only when
+// AUTOPILOT is set. $02FF = $01 and a green border on a pass, $02 and red
+// on a fail (c64-kb headless-verify); row 21 says which checks failed.
+//
+// DEBUG_AT=n (a build define) freezes at frame n instead and prints the
+// state on row 21: frame, player x and y, camera, events, state, respawn
+// x; row 23 the live enemies' x. That is how the script was timed.
+#ifndef DEBUG_AT
+#define DEBUG_AT 0
+#endif
+#define VERDICT_FRAME 860           // the script ends at 823; the player stands at the wall
+
+// What the script does, by design (autopilot.h): five coins (three by the
+// hill, two on the ledge), one stomp, one hit from the hopper, one respawn.
+#define EXPECT_COINS  5
+#define EXPECT_STOMPS 1
+#define EXPECT_HURTS  1
+#define EV_ALL        0x1fff
+// The brick at tile 45 has its left edge at x 720; the wall probe stops the
+// foot column BODY_HALF + 1 short of it, and the camera settles with the
+// player CAM_RIGHT (140) pixels in: arithmetic, not a pinned run.
+#define EXPECT_PX     (720 - BODY_HALF - 1)
+#define EXPECT_CAMX   (EXPECT_PX - 140)
+
+static void put_num(char row, char col, unsigned v, char width)
+{
+    char *p = HUDPAGE + row * 40 + col + width;
+    for (char i = 0; i < width; i++)
+    {
+        unsigned q = v / 10;
+        *--p = '0' + (char)(v - q * 10);
+        v = q;
+    }
+}
+
+static void put_hex(char row, char col, unsigned v)
+{
+    char *p = HUDPAGE + row * 40 + col;
+    for (char i = 0; i < 4; i++)
+    {
+        char d = (v >> (12 - 4 * i)) & 15;
+        p[i] = d < 10 ? '0' + d : d - 9;    // screen codes: A is 1
+    }
+}
+
+static void debug_print(void)
+{
+    put_num(21, 0, frame, 4);
+    put_num(21, 5, px, 4);
+    put_num(21, 10, py >> 8, 3);
+    put_num(21, 14, camx, 4);
+    put_num(21, 19, events, 5);
+    put_num(21, 25, state, 1);
+    put_num(21, 27, safe_x, 4);
+    for (char s = 0; s < NSLOT; s++)
+        put_num(23, 10 + s * 5, slot_lvl[s] == NO_SLOT ? 0 : slot_x[s], 4);
+}
+
+// Every ready page against the level at its column: the scroll's own check.
+// Row 20, the blank row above the HUD, must be sky on every page (it is
+// shown from whichever page is on display).
+static bool pages_match(void)
+{
+    for (char p = 0; p < NPAGES; p++)
+    {
+        const char *q = p == 0 ? PAGE0 : p == 1 ? PAGE1 : PAGE2;
+        for (char c = 0; c < 40; c++)
+            if (q[PF_ROWS * 40 + c] != CH_SKY)
+                return false;
+        if (page_rows[p] < PF_ROWS || page_col[p] < 0 || page_col[p] > LEVEL_CW - 40)
+            continue;
+        for (char r = 0; r < PF_ROWS; r++)
+            for (char c = 0; c < 40; c++)
+                if (q[r * 40 + c] != cell_char(page_col[p] + c, r))
+                    return false;
+    }
+    return true;
+}
+
+// The activation window's promises: a live entry is in exactly one slot;
+// a dormant, living entry is never inside the view; every live actor is
+// inside the drop window.
+static bool window_holds(void)
+{
+    char cc = camx >> 3;
+    for (char i = 0; i < lvl_count; i++)
+    {
+        char n = 0;
+        for (char s = 0; s < NSLOT; s++)
+            if (slot_lvl[s] == i)
+                n++;
+        if ((lvl_flags[i] & LF_LIVE) ? n != 1 : n != 0)
+            return false;
+        if (!(lvl_flags[i] & (LF_LIVE | LF_DEAD)) && lvl_col[i] >= cc && lvl_col[i] < cc + 40)
+            return false;
+    }
+    for (char s = 0; s < NSLOT; s++)
+    {
+        char c = slot_x[s] >> 3;
+        if (slot_lvl[s] != NO_SLOT && (c + 6 < cc || c > cc + 46))
+            return false;
+    }
+    return true;
+}
+
+// The sprite registers the VIC was given last blank against the model.
+static bool sprites_match(void)
+{
+    unsigned sx = px - 8 - camx + 31;
+    return vic.spr_pos[0].x == (char)sx && (vic.spr_msbx & 1) == (sx >> 8) &&
+           vic.spr_pos[0].y == (char)((py >> 8) - 21 + 50) && (vic.spr_enable & 1) &&
+           (vic.spr_color[0] & 15) == COL_PLAYER;
+}
+
+// Invariants checked after every play frame's work (outside the meter's
+// bracket), each with its own bit in the verdict, so a fault that heals
+// before the end of the script is still caught.
+static unsigned frame_faults;
+#define FF_POPIN   0x0800           // a dormant, living enemy inside the view: woken too late
+#define FF_DROP    0x1000           // a live enemy outside the drop window it was judged against
+#define FF_GROUND  0x2000           // a grounded player not exactly on its cell's surface
+#define FF_CAMERA  0x4000           // the page to show is not the camera's column, or not whole
+
+static void check_frame(void)
+{
+    char cc = camx >> 3;
+    for (char i = 0; i < lvl_count; i++)
+        if (!(lvl_flags[i] & (LF_LIVE | LF_DEAD)) && lvl_col[i] >= cc && lvl_col[i] < cc + 40)
+            frame_faults |= FF_POPIN;
+    for (char s = 0; s < NSLOT; s++)
+    {
+        char c = slot_x[s] >> 3;
+        if (slot_lvl[s] != NO_SLOT && !slot_squashed[s] && (c < drop_lo || c > drop_top))
+            frame_faults |= FF_DROP;
+    }
+    if (pground)
+    {
+        char fy = py >> 8, row = fy >> 3;
+        char a = cell_attr(px >> 3, row);
+        if (!(a & A_GROUND) || surface_at(px, row, a) != fy || (py & 0xff))
+            frame_faults |= FF_GROUND;
+    }
+    if (shown_col != cc || page_col[shown_page] != (int)cc || page_rows[shown_page] != PF_ROWS)
+        frame_faults |= FF_CAMERA;
+}
+
+static void grade(void)
+{
+    unsigned value = 0;
+    for (char i = 0; i < 6; i++)
+        value = value * 10 + score[i];
+    unsigned fails = 0;
+    if (events != EV_ALL)                                   fails |= 0x0001;
+    if (value != coins * 10u + stomps * 100u)               fails |= 0x0002;
+    if (coins != EXPECT_COINS || stomps != EXPECT_STOMPS)   fails |= 0x0004;
+    if (hurts != EXPECT_HURTS || lives != START_LIVES - EXPECT_HURTS) fails |= 0x0008;
+    if (px != EXPECT_PX || (py >> 8) != 128 || !pground)    fails |= 0x0010;
+    if (camx != EXPECT_CAMX)                                fails |= 0x0020;
+    if (!pages_match())                                     fails |= 0x0040;
+    if (!window_holds())                                    fails |= 0x0080;
+    if (!(lvl_flags[1] & LF_DEAD) || (lvl_flags[0] & (LF_LIVE | LF_DEAD)))
+        fails |= 0x0100;                                    // stomped stays dead; the walker left behind sleeps
+    if (!sprites_match())                                   fails |= 0x0200;
+    if (late)                                               fails |= 0x0400;
+    fails |= frame_faults;
+
+#if STAGE_CROWD
+    fails &= 0x0400;                // the crowded level plays nothing like the script: only late frames count
+#endif
+    bool ok = fails == 0;
+    RESULT = ok ? 0x01 : 0x02;
+    vic.color_border = ok ? VCOL_GREEN : VCOL_RED;
+    put_text(21, 0, ok ? "result 01 pass" : "result 02 fail");
+    if (!ok)
+        put_hex(21, 15, fails);
+}
+
+// Right after the IRQ at line 251 has set the new picture up, its camera
+// goes on row 23 ("CAM 0576"), so tools/tearcheck.py can compare the
+// picture with the camera the program meant: a page and an XSCROLL that
+// disagree put the picture 8 pixels off.
+static void autopilot_blank(void)
+{
+    put_text(23, 30, "cam");
+    put_num(23, 34, pub_camx, 4);
+}
+
+static void autopilot_frame(void)
+{
+    if (state == ST_GRADED)
+        return;
+    if (metering && state == ST_PLAY)
+        check_frame();              // a whole play frame ran (not the one that started the game)
+    if (DEBUG_AT && frame == DEBUG_AT)
+    {
+        debug_print();
+        state = ST_GRADED;
+    }
+    else if (frame == VERDICT_FRAME)
+    {
+        grade();
+        meter_print();
+        state = ST_GRADED;
+    }
+}

package/templates/platformer/src/view.c

@@ -0,0 +1,331 @@
+// view.c: the VIC-II side. Three playfield pages and a HUD page in bank 3;
+// the camera; the scroll. The frame's registers are computed into shadows
+// during the frame and written together in the vertical blank
+// (view_apply), so a picture is always one page at one XSCROLL.
+//
+// Scroll, after c64-kb soft_scroll_h and screen_double_buffer_d018:
+// XSCROLL = 7 - (camx & 7) moves the picture a pixel. A column crossing
+// is a $D018 flip to a page that already holds the next column. Of the
+// three pages one is on display (column c), one holds the column the
+// camera just came from (the page shown before the last crossing, so it
+// is ready for free), and the third is prepared for the next column in the
+// direction of travel: five rows a frame, copied one column over from the
+// page on display by slice_copy (engine.asm), plus the new column's five
+// cells from the level. The camera moves at most 2 pixels a frame, so the
+// next crossing that way is at least 4 frames off, and 4 slices finish it.
+// No page is written while it is on display: nothing tears, and no frame
+// carries a whole 20-row shift.
+#include "game.h"
+#include "asm.h"
+#include <string.h>
+
+#define CAM_LEFT   100              // the player's screen x the camera keeps between
+#define CAM_RIGHT  140
+#define CAM_SPEED  2                // pixels a frame, at most: 4 frames a column
+#define SLICE      5                // rows a prepare step (engine.asm's SLICE)
+#define NO_PAGE    0xff
+#define COL_MAX    (LEVEL_CW - 40)  // the last column a page can start at
+
+unsigned camx, shown_col;
+unsigned pub_camx;                  // the camera of the pair last published
+char shown_page;
+int page_col[NPAGES];
+char page_rows[NPAGES];
+static char prep_page;              // the page being prepared, or NO_PAGE
+
+static char *const page_addr[NPAGES] = { PAGE0, PAGE1, PAGE2 };
+static const char page_d018[NPAGES] = { D018_PAGE0, D018_PAGE1, D018_PAGE2 };
+
+static char sh_d016, sh_d018, sh_en, sh_msb, cia_ack;
+static char sh_x[8], sh_y[8], sh_ptr[8], sh_col[8];
+
+#define SLICE_SRC (*(volatile unsigned *)ASM_SLICE_SRC)
+#define PF_D016   (*(volatile char *)ASM_PF_D016)
+#define PF_D018   (*(volatile char *)ASM_PF_D018)
+#define SLICE_DST (*(volatile unsigned *)ASM_SLICE_DST)
+
+void view_init(void)
+{
+    vic.spr_enable = 0;
+    cia2.pra = cia2.pra & 0xfc;             // VIC bank 3: $C000-$FFFF
+    vic.ctrl1 = 0x1b;                       // display on, 25 rows, YSCROLL 3
+    vic.ctrl2 = D016_PLAY | 7;
+    vic.memptr = D018_PAGE0;
+    PF_D016 = D016_PLAY | 7;
+    PF_D018 = D018_PAGE0;
+    vic.color_border = COL_SKY;
+    vic.color_back = COL_SKY;
+    vic.color_back1 = COL_EARTH;
+    vic.color_back2 = COL_GOLD;
+    vic.spr_multi = 0;
+    vic.spr_expand_x = 0;
+    vic.spr_expand_y = 0;
+    vic.spr_priority = 0;                   // sprites in front of the playfield
+
+    // One memset per page. The obvious single loop storing to all four
+    // miscompiles at -O1 to -O3 (Oscar64 local build and upstream 9a902f6,
+    // issue #30 fault 7): the pointer high byte of the first page is set
+    // once per 256-byte block and reused for the others, so PAGE1 got one
+    // byte in 256 and row 20 showed garbage whenever page 1 was on screen.
+    memset(PAGE0, CH_SKY, 1024);
+    memset(PAGE1, CH_SKY, 1024);
+    memset(PAGE2, CH_SKY, 1024);
+    memset(HUDPAGE, CH_SKY, 1024);
+    for (unsigned i = 0; i < PF_ROWS * 40; i++)
+        COLOUR[i] = 0x08 | COL_GRASS;       // multicolour; 11 draws grass
+    for (unsigned i = PF_ROWS * 40; i < 1000; i++)
+        COLOUR[i] = VCOL_WHITE;             // row 20 is blank; the HUD is hires white
+
+    // The split IRQ. BASIC and KERNAL are out ($01 = $35), so the CPU takes
+    // its vectors from RAM: $FFFE to the split, $FFFA (RESTORE) to an RTI.
+    *(volatile unsigned *)0xfffe = ASM_IRQ_SPLIT;   // it then points $FFFE at irq_blank, and back
+    *(volatile unsigned *)0xfffa = ASM_NMI_RTI;
+    cia1.icr = 0x7f;                        // no CIA1 interrupts: the KERNAL's timer is not wanted
+    cia_ack = cia1.icr;                     // read: clears a pending CIA1 interrupt
+    vic.raster = SPLIT_LINE;                // $D011 bit 7 is 0: line 212
+    vic.intr_ctrl = 0x0f;                   // clear anything pending
+    vic.intr_enable = 0x01;                 // raster only
+    __asm { cli }
+}
+
+// Rows row0 to row0 + n - 1 of world column col, down a page column.
+static void level_cells(char *dst, unsigned col, char row0, char n)
+{
+    dst += row0 * 40;
+    for (char r = row0; r < row0 + n; r++, dst += 40)
+        *dst = cell_char(col, r);
+}
+
+static void page_draw(char p, int col)
+{
+    page_col[p] = col;
+    page_rows[p] = PF_ROWS;
+    if (col < 0 || col > COL_MAX)
+        return;                             // off the level: never shown
+    for (char c = 0; c < 40; c++)
+        level_column(page_addr[p] + c, col + c);
+}
+
+// Draw all three pages whole: the start of a game, not a scroll.
+void view_cut(void)
+{
+    shown_col = camx >> 3;
+    shown_page = 0;
+    page_draw(0, shown_col);
+    page_draw(1, (int)shown_col + 1);
+    page_draw(2, (int)shown_col - 1);
+    prep_page = NO_PAGE;
+    sh_d016 = D016_PLAY | (7 - (camx & 7));
+    sh_d018 = page_d018[0];
+}
+
+// A taken coin: every page that holds the cell, so a page shown later
+// cannot bring it back.
+void view_erase_tile(unsigned col, char row)
+{
+    char r = row & 0xfe;
+    for (char p = 0; p < NPAGES; p++)
+    {
+        char *base = page_addr[p] + r * 40;
+        int sc = (int)(col & ~1u) - page_col[p];
+        for (char k = 0; k < 2; k++, sc++)
+        {
+            if (sc >= 0 && sc < 40)
+            {
+                base[sc] = CH_SKY;
+                base[sc + 40] = CH_SKY;
+            }
+        }
+    }
+}
+
+// One slice of the page being prepared: five rows copied one column over
+// from the page on display, and those rows of the new column.
+static void prep_step(void)
+{
+    char p = prep_page;
+    char r = page_rows[p];
+    unsigned off = r * 40;
+    char *src = page_addr[shown_page] + off;
+    char *dst = page_addr[p] + off;
+    if (page_col[p] > (int)shown_col)
+    {
+        SLICE_SRC = (unsigned)src + 1;      // the picture moves left
+        SLICE_DST = (unsigned)dst;
+        __asm { jsr ASM_SLICE_COPY }
+        level_cells(page_addr[p] + 39, page_col[p] + 39, r, SLICE);
+    }
+    else
+    {
+        SLICE_SRC = (unsigned)src;          // the picture moves right
+        SLICE_DST = (unsigned)dst + 1;
+        __asm { jsr ASM_SLICE_COPY }
+        level_cells(page_addr[p], page_col[p], r, SLICE);
+    }
+    page_rows[p] = r + SLICE;
+    if (page_rows[p] >= PF_ROWS)
+        prep_page = NO_PAGE;
+}
+
+#if TEAR_DEMO
+// The old way, for tools/tearcheck.py to catch: shift the page on display
+// in place, in C, while the beam draws it (issue #18).
+static void shift_in_place(char *p, bool left)
+{
+    for (char r = 0; r < PF_ROWS; r++, p += 40)
+    {
+        if (left)
+            for (char c = 0; c < 39; c++)
+                p[c] = p[c + 1];
+        else
+            for (char c = 39; c > 0; c--)
+                p[c] = p[c - 1];
+    }
+}
+#endif
+
+// A crossing to column cc: flip to the page that holds it (finishing it
+// first if a slice is still owed, which the camera speed rules out in
+// play), keep the page just left as the neighbour behind, and start
+// preparing the third for the column after cc.
+static void cross(unsigned cc)
+{
+    bool right = cc > shown_col;
+#if TEAR_DEMO
+    char *p = page_addr[shown_page];
+    shift_in_place(p, right);
+    if (right)
+        level_column(p + 39, cc + 39);
+    else
+        level_column(p, cc);
+    page_col[shown_page] = cc;
+#else
+    char next = NO_PAGE;
+    for (char p = 0; p < NPAGES; p++)
+        if (p != shown_page && page_col[p] == (int)cc)
+            next = p;
+    if (next == NO_PAGE)
+    {
+        next = prep_page != NO_PAGE ? prep_page : (shown_page + 1) % NPAGES;
+        page_col[next] = cc;
+        page_rows[next] = 0;
+    }
+    while (page_rows[next] < PF_ROWS)
+    {
+        prep_page = next;
+        prep_step();                        // owed slices: not in play (see above)
+    }
+    char behind = shown_page;
+    shown_page = next;
+    char third = NPAGES - next - behind;    // pages are 0, 1, 2
+    int target = right ? (int)cc + 1 : (int)cc - 1;
+    page_col[third] = target;
+    page_rows[third] = 0;
+    prep_page = third;
+    if (target < 0 || target > COL_MAX)
+    {
+        page_rows[third] = PF_ROWS;         // off the level: nothing to prepare
+        prep_page = NO_PAGE;
+    }
+#endif
+    events |= right ? EV_SHIFT_L : EV_SHIFT_R;
+    shown_col = cc;
+}
+
+// The camera keeps the player between screen x 100 and 140, moving at most
+// CAM_SPEED a frame. The owed slice comes first, so a page due at this
+// frame's crossing is finished before the crossing is decided.
+void view_follow(void)
+{
+#if !TEAR_DEMO
+    if (prep_page != NO_PAGE)
+        prep_step();
+#endif
+    int sx = (int)px - (int)camx;
+    int t = camx;
+    if (sx > CAM_RIGHT)
+        t = (int)px - CAM_RIGHT;
+    else if (sx < CAM_LEFT)
+        t = (int)px - CAM_LEFT;
+    if (t < 0)
+        t = 0;
+    else if (t > CAM_MAX)
+        t = CAM_MAX;
+    if (t > (int)camx + CAM_SPEED)
+        t = camx + CAM_SPEED;
+    else if (t < (int)camx - CAM_SPEED)
+        t = camx - CAM_SPEED;
+    camx = t;
+
+    unsigned cc = camx >> 3;
+    if (cc != shown_col)
+        cross(cc);
+    sh_d016 = D016_PLAY | (7 - (camx & 7));
+    sh_d018 = page_d018[shown_page];
+}
+
+// One sprite's shadow. Art is 16 wide; x is the art's left edge in the
+// world; line is the Y register, one above the art's top row (the VIC
+// draws a sprite from line Y + 1, and world row y is on line 51 + y). A
+// sprite off the 38-column window is switched off: X wraps at 504 on PAL
+// and 520 on NTSC (c64-kb sprite_x_range_hidden_and_seam).
+static void put_sprite(char n, int x, int line, char shape, char colour, bool on)
+{
+    int sx = x - (int)camx + 31;            // world pixel camx sits at VIC X 31
+    char bit = 1 << n;
+    if (on && sx > 8 && sx < 335 && line > 20 && line < 190)   // bottom row above line 211: never over the HUD
+    {
+        sh_en |= bit;
+        sh_x[n] = sx & 0xff;
+        if (sx & 0x100)
+            sh_msb |= bit;
+        sh_y[n] = line;
+        sh_ptr[n] = SPR_BLOCK + shape;
+        sh_col[n] = colour;
+    }
+}
+
+void view_sprites(void)
+{
+    sh_en = 0;
+    sh_msb = 0;
+    char ps = panim.shape + (pleft && panim.shape < SH_MIRROR ? SH_MIRROR : 0);
+    put_sprite(0, px - 8, (int)(py >> 8) - 21 + 50, ps, COL_PLAYER, !(pinvuln & 4));
+    for (char s = 0; s < NSLOT; s++)
+    {
+        if (slot_lvl[s] != NO_SLOT)
+            put_sprite(s + 1, slot_x[s] - 8, (int)(slot_y[s] >> 8) - 16 + 50, slot_anim[s].shape,
+                       slot_type[s] == T_WALKER ? COL_WALKER : COL_HOPPER, true);
+    }
+}
+
+// The end of a frame's work: the page and XSCROLL for the next picture,
+// as one pair, for the IRQ at line 251 to write (engine.asm).
+void view_publish(void)
+{
+    __asm { sei }
+    PF_D016 = sh_d016;
+    PF_D018 = sh_d018;
+    pub_camx = camx;
+    __asm { cli }
+}
+
+// The vertical blank, from line 251: the sprites for the picture the IRQ
+// has just set up. The sprite pointers go to every page, because the VIC
+// reads them from whichever page it is showing.
+void view_apply(void)
+{
+    for (char n = 0; n < 8; n++)
+    {
+        vic.spr_pos[n].x = sh_x[n];
+        vic.spr_pos[n].y = sh_y[n];
+        vic.spr_color[n] = sh_col[n];
+        char p = sh_ptr[n];
+        PAGE0[0x3f8 + n] = p;
+        PAGE1[0x3f8 + n] = p;
+        PAGE2[0x3f8 + n] = p;
+        HUDPAGE[0x3f8 + n] = p;
+    }
+    vic.spr_msbx = sh_msb;
+    vic.spr_enable = sh_en;
+}

package/templates/platformer/stage-expect.json

@@ -0,0 +1,6 @@
+{
+  "checks": [
+    { "name": "own verdict: no late frame with every slot full", "type": "verdict" },
+    { "name": "frame meter, every enemy slot live from the first play frame", "type": "meter", "row": 24, "col": 20, "frames": 255 }
+  ]
+}

package/templates/platformer/tools/drive.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""drive.py PRG STEP...: play the `make joy` build headless over VICE's binary monitor.
+
+    python3 tools/drive.py build/platformer-joy.prg "until:PRESS FIRE" tap:fire \
+        "until:LIVES 3" hold:right "until:GAME OVER" "until:PRESS FIRE" print
+
+Taken from templates/action-puzzle/tools/drive.py; only the screen it reads
+differs: this game's text is on the HUD page at $C800, rows 21-24. The joy
+build reads its port byte from $02FE (JOY_SOURCE) instead of $DC00, because
+the windowless VICE's joyport commands never reach $DC00. 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 play that long, at real speed (VICE runs without -warp)
+  until:TEXT   run until TEXT is on the HUD (300 s limit)
+  print        print the HUD's non-blank rows
+The monitor port is DRIVE_PORT, or a free one the script picks.
+"""
+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"))
+def free_port():
+    with socket.socket() as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+PORT = int(os.environ.get("DRIVE_PORT") or free_port())   # two drives at once do not collide
+HUD = 0xC800                                          # src/game.h HUDPAGE
+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", "+sound", "-autostartprgmode", "1", "-binarymonitor",   # real speed: run:1 is a second of play
+             "-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, HUD + 21 * 40, HUD + 1000 - 1, 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(4)]
+
+
+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()