c64-kb 0.17.0

package/templates/action-puzzle/README.md

@@ -0,0 +1,240 @@
+# action-puzzle: CAVE RUN
+
+A Boulder Dash-style cave game for a stock C64, PAL and NTSC, in Oscar64 C.
+Copy it to start a game of this kind:
+
+```bash
+npm run new-project -- action-puzzle ~/c64/mygame     # in c64-kb
+```
+
+The player digs through earth. Boulders and gems fall and roll. Sparks keep
+a wall on their left, moths a wall on their right; either explodes when the
+player is next to it, and a moth crushed by a boulder bursts into gems.
+Boulders can be pushed sideways into space. Collecting the cave's quota of
+gems opens the exit. A time counter, a score, three lives. At game over a
+new high score is entered with the joystick and the five-row table is saved
+to drive 8; it is loaded again at start-up. An original two-voice tune plays
+throughout, with sound effects on the third voice. Graphics, caves and tune
+are original.
+
+Joystick in port 2. Fire starts; up and down pick a letter, fire sets it.
+
+## Files
+
+| File | What it holds |
+|---|---|
+| `src/main.c` | States (title, next cave, play, name entry, table), the frame loop, input, the autopilot and its verdict |
+| `src/cave.c`, `cave.h` | The rules: the cave scan, split into row slices (technique `cave_scan_engine`) |
+| `src/level.c`, `level.h` | The RLE cave decoder, timed on CIA1 timer B (`tile_map_render`, decode half) |
+| `src/render.c`, `render.h` | RAM character set at `$2000`, cell drawing, the dirty list, text, glyph animation (`charset_animation`) |
+| `src/sound.c`, `sound.h` | The tune on voices 1 and 2, effects on voice 3 (`sid_play_routine_pattern`, `sfx_engine_beside_music`) |
+| `src/hiscore.c`, `hiscore.h` | The table, the insert, the file on drive 8 (`high_score_table_insert`, `kernal_file_read_seq`, `kernal_file_write_seq`, `error_channel_check`) |
+| `tools/gen.py` | The caves, the autopilot script, a Python model of the rules, the note table. Writes `src/gen_*.h` |
+| `tools/model_check.py` | Every visible cave cell of both shots against the model (`make modelcheck`) |
+| `tools/disk_check.py` | Grades `make disktest` |
+| `tools/drive.py` | Plays the `make joy` build headless over VICE's binary monitor |
+| `expect.json`, `PLAN.md` | The screenshot checks; the plan with the c64-kb tool output it was made from |
+
+Memory: code and data `$0880`-`$1FFF` and `$2800` up; the character set
+`$2000`-`$27FF` (`$D018` = `$18`); screen `$0400`. Screen row 0 is the HUD,
+rows 1 to 22 the cave (one character a cell), row 23 messages, row 24 the
+cave name and, in AUTOPILOT builds, the frame meter.
+
+## How it runs
+
+One cave frame is one scan of the 38 x 20 interior. It is split into four
+slices of five rows, one slice a display frame, so the cave moves once every
+four frames on both models (12.5 cave frames a second on PAL, 15 on NTSC).
+The player's direction is latched at the first slice. Each slice redraws
+only the cells it changed. After the fourth slice the exit opens if the
+quota is met and the time counter ticks (once every 12 cave frames).
+
+The dirty list holds 16 cells: 8 moves, since a move marks two cells (an
+explosion marks nine). When a slice changes more, the list overflows and
+the slice's rows (one above to one below) are queued instead;
+`draw_pending` redraws at most two queued rows a frame, 34 cycles a cell
+from the generated code, about 2,800 cycles for two rows. The first version
+redrew all seven rows in the frame of the overflow, 55,305 cycles for 280
+cells (measured in comparison), almost three PAL frames.
+
+**How many objects a slice can move.** Each moving or landing object costs
+about 440 cycles on top of the slice's usual work: 16 boulders falling in
+one slice made a 13,643-cycle PAL frame and a 13,861-cycle NTSC one, against
+a typical frame of about 6,500 to 6,800 (the meter; arithmetic for the per-object
+figure). So about 20 moving objects a slice fit an NTSC frame, and about 25
+fit a PAL one. A cave that moves more in one slice drops frames. The
+autopilot's verdict counts dropped frames (below), so a cave designed past
+that limit fails its own check. The cave-scan recipe's 380-boulder fill is
+far past it; this starter's caves keep falls short and spread out.
+
+The KERNAL IRQ is off during play; the loop polls raster line 250. Disk
+calls happen on a static screen with the sound muted, and `SEI` follows
+each one, because the KERNAL serial routines end in `CLI`.
+
+## Checks
+
+| Command | What it proves |
+|---|---|
+| `make shot check` | The autopilot game on PAL and NTSC, each on a fresh D64 (`SHOT_DISK := 1`): 41 checks (verdict, HUD, the table row it inserted, the save read back, cave cells, PAL = NTSC, the meter) |
+| `make modelcheck` | 516 visible cave cells per shot match the model's cave at game over |
+| `make selftest` | The FORCE_FAULT build flips one byte of the save as it is read back: red border, letter V, and `READ BACK BAD` in the table |
+| `make selftest-scan` | The build with `SCAN_FLAG=0` (no scanned bit, the cave-scan recipe's double-move bug) fails, and its verdict names E |
+| `make disktest` | The save, a second save over it, and the load on a true-drive 1541 (below) |
+| `make claims` | Every store the autopilot run makes is one the Makefile declares |
+
+The autopilot plays a whole game of three lives. Its script is keyed to
+the game's own counter of cave starts: start 1 digs right along row 2,
+collects four gems, pushes a boulder twice, digs down for two more and walks
+into the open exit. Starts 2, 3 and 4 are cave 2 after each lost life: out
+from under a boulder, then under another, then the first again, and each
+time the boulder falls on him. So the restart path (the cave decoded again,
+a life taken, the score banked) runs twice. It enters the name ABE; 158
+goes in row 4, and the table is saved and read back from the shot's fresh
+disk. In cave 1 a boulder on the end of a brick rolls right, and a row of
+16 boulders falls and lands in one slice, which overflows the dirty list.
+
+`tools/gen.py` plays the same script through its model and writes what the
+game must end with. The verdict prints one letter for each test that
+failed, after the fold on row 23:
+
+| Letter | Test |
+|---|---|
+| F | the fold, chained over every cave the game left (0x75FA), against the model's |
+| S, G, C, P, K | score, gems, cave, play frames, cave starts |
+| T | the table row: rank, name and score |
+| L | every cave decode matched its fold |
+| E | the scan met the living player exactly once in every cave frame |
+| M | at every cave end, after the row queue is drained, every screen cell shows its cave cell |
+| D | no play frame's work ran past line 250 (the `$D019` raster latch, below) |
+| V | the save read back byte for byte (`memcmp`) |
+
+A watchdog ends the game once play runs past the model's frame count, so a
+broken rule still reaches the verdict. Each gate was checked with a
+mutation (2026-09-23): no right roll (F), no `dead_frames` reset on restart
+(F P K D), the row queue disabled (M), the save one byte short (V), the
+`memcmp` replaced by true (selftest then passes the fault build and fails),
+a busy loop in one play frame (D), and the E test removed (selftest-scan
+then finds no E).
+
+**Dropped frames.** The VIC sets bit 0 of `$D019` on every raster compare
+match even with the interrupt disabled. `wait_frame` acknowledges it at line
+250, so a set bit on entry means the frame's work overran. The KERNAL leaves
+the compare at line 311 (bit 8 set in `$D011`), so `main` clears that bit
+first: without it the latch never set (0 of 200 frames against 199 of 200,
+a test program in VICE x64sc 3.10).
+
+**The shot pin.** Both models are shot at 24,000,000 cycles. At
+18,000,000 the save is still running on both models; at 20,000,000,
+24,000,000 and 30,000,000 the picture is byte-identical, PAL and NTSC
+(VICE x64sc 3.10, windowless).
+
+**The disk test.** `make disktest` (`DISK_MODEL=ntsc` for NTSC) copies the
+release D64. It runs the autopilot build against the copy with
+`-drive8truedrive`, so the emulated 1541 runs its own DOS ROM. The build
+finds no file (62), plays, saves (scratch, then write) and shows
+`SAVED TO DISK (00)`. It then runs a second time on the same image. It
+loads that file, its 158 ties row 4 and goes in row 5, and the save must
+replace the file. Without the scratch the drive answers 63 (FILE EXISTS)
+and nothing is written: a build with the scratch removed fails this test.
+The second run's own verdict is red by design, because it did not start
+from the default table. c1541 reads the 38-byte `HISCORE` file back after
+each save, and the directory must hold one entry. Last, a cold VICE
+autostarts the D64: the drive loads the release PRG, which reads the file
+and shows the title with rows 4 and 5 `ABE 000158` and `SCORES FROM DISK
+(00)`. Three pictures, two files and the directory are graded. Run on
+2026-09-23: PASS on PAL and NTSC.
+
+## Driving it headless
+
+`make joy` builds the normal game (three lives, title, no autopilot) with
+`-dJOY_SOURCE=0x02fe`: the port byte comes from `$02FE` instead of `$DC00`.
+`tools/drive.py` plays that build over VICE's binary monitor. It writes the
+byte, lets the machine run, and reads screen RAM as text:
+
+```bash
+make joy
+python3 tools/drive.py build/action-puzzle-joy.prg "until:FIRE TO START" tap:fire \
+    until:LIVES hold:right "until:ENTER YOUR NAME" hold:none tap:up tap:fire tap:fire \
+    tap:fire "until:GAME OVER" print tap:fire "until:FIRE TO START" print
+```
+
+That run (2026-09-23) held right through three time-outs (cave 1 each
+time), entered BAA, and showed `4. BAA 000120` in the table, `NOT SAVED
+(74)` with no disk attached, and then the title. Two findings
+behind this design:
+
+- The windowless VICE's joyport commands do not reach `$DC00`. The binary
+  monitor's joyport set was accepted, but `$DC00` never changed, with or
+  without `-joydev2` (found in review).
+- Monitor screenshots from the windowless build came back stale while the
+  game ran, so `drive.py` reads screen RAM. Entering the text monitor during
+  the start-up disk read left that read hung twice here; the binary monitor
+  under warp did not.
+
+## The measured frame
+
+The harness meter (CIA2 timer A), over the autopilot's 240 play frames,
+VICE x64sc 3.10:
+
+| Model | Worst | Typical (median) | Frame |
+|---|---|---|---|
+| PAL | 13,643 | 6,518 | 19,656 |
+| NTSC | 13,861 | 6,776 | 17,095 |
+
+The worst frame is play frame 7, the slice where the 16 boulders fall and
+overflow the dirty list (a debug build that kept the worst frame's index
+found it). The cave decode between caves is not a play frame: 40,041 cycles
+on PAL and 40,519 on NTSC for cave 2, screen on, CIA1 timer B, printed after
+the verdict.
+
+The same checks pass with the released Oscar64 v1.32.273 (make shot check,
+modelcheck, selftest, selftest-scan and disktest on PAL, run 2026-09-23).
+Its meter reads 13,412 / 6,392 cycles on PAL and 13,669 / 6,607 on NTSC
+(measured on 3048ac1 by the other #39 session's comparator).
+
+Against `plan-budget` (the PLAN.md output): it summed the recipe's whole
+scan, 18,559 cycles, into every PAL play frame (range 19,599 to 19,807 plus
+1,075 for badlines, "undetermined") and left it out of the NTSC frame as
+multi-frame (1,040 to 1,248 plus 1,075). Neither is this program's frame:
+the scan here runs a quarter at a time. The scan loop takes 17 cycles a
+cell of dirt (counted from the generated code). The recipe's loop measured 18.7 (14,206 cycles
+for 760 cells, with badlines in). So a slice of 190 cells costs about 3,230
+cycles, plus the objects in it (arithmetic). The tool's
+music figure is the recipe's stub tune; this tune and its effects are
+measured only inside the whole frame.
+
+## Extending it
+
+1. **Scroll a bigger cave.** Draw cells as 2 x 2 characters and scroll a
+   window over a cave larger than the screen: `tile_map_render` and the
+   recipe `oscar64/tile-map-render` (metatiles), then a scroll technique
+   from `technique-lookup` (`techniques-for --category scroll`).
+2. **Add amoeba, a magic wall or more enemies.** Add codes in `cave.h`
+   (at most 32: glyphs sit at `$40` + code), a branch in `cell()`, a glyph
+   and a tint in `render.c`, the same colour in `tools/model_check.py`'s
+   `TINT`, and the same rule in `tools/gen.py`'s `Cave.cell`. Extend the
+   script and run `make gen shot check modelcheck`. The rules and the
+   scanned bit are `cave_scan_engine` (recipe `oscar64/cave-scan`).
+3. **Faster scans.** The scan loop is C; the recipe `oscar64/level-rle-decoder`
+   shows a hand-written decoder a little under twice as fast as the C one,
+   and the same move applies to `cave_scan_rows`. Measure before and after
+   with the meter.
+
+More caves: add them to `CAVES` in `tools/gen.py` and run `make gen`.
+
+## Left out on purpose
+
+- Scrolling, 2 x 2 cells, multicolour graphics, sprites: one cell is one
+  hires character, so the whole 40 x 22 cave is on screen.
+- Amoeba, magic wall, slime, collecting falling gems, the fire-to-grab move.
+- A raster IRQ: the loop polls line 250. Music keeps time only while the
+  loop does; it stops during disk calls.
+- Equal speed on both models: NTSC plays 20 % faster in real time,
+  tune included (pitfall `pal_ntsc_tempo_mismatch`). The note pitches are
+  right on both (a PAL and an NTSC table).
+- Anyone listening to the sound: the tune and effects were checked by the
+  registers claims-watch saw written, not by ear.
+- A real joystick on `$DC00`: the normal game was driven headless through
+  `$02FE` (above), which differs from the release build in one line of
+  `port_read`.
+- Real hardware.

package/templates/action-puzzle/expect.json

@@ -0,0 +1,25 @@
+{
+  "checks": [
+    { "name": "own verdict (border)", "type": "verdict" },
+    { "name": "verdict line and the model's chained fold (0x75FA)", "type": "text", "row": 23, "col": 0, "text": "RESULT 01 PASS  FOLD 30202" },
+    { "name": "HUD: cave 2's quota and time, the banked score 158, no lives left", "type": "text", "row": 0, "col": 0, "text": "GEMS 00/08 TIME 120 SCORE 000158 LIVES 0" },
+    { "name": "game-over box", "type": "text", "row": 7, "col": 16, "text": "GAME OVER" },
+    { "name": "table row 4: the scripted name and score, inserted", "type": "text", "row": 14, "col": 13, "text": "4. ABE 000158" },
+    { "name": "table row 5: the old row 4, shifted down", "type": "text", "row": 15, "col": 13, "text": "5. MUD 000100" },
+    { "name": "table row 3 kept", "type": "text", "row": 13, "col": 13, "text": "3. GEM 000200" },
+    { "name": "the save, read back byte for byte from the shot's fresh disk", "type": "text", "row": 17, "col": 9, "text": "SAVED TO DISK     (00)" },
+    { "name": "steel border, cave (0, 0)", "type": "pixel", "row": 1, "col": 0, "colour": 12 },
+    { "name": "boulder the model leaves at cave (22, 1)", "type": "pixel", "row": 2, "col": 22, "colour": 15 },
+    { "name": "boulder at cave (11, 2)", "type": "pixel", "row": 3, "col": 11, "colour": 15 },
+    { "name": "gem at cave (14, 3)", "type": "pixel", "row": 4, "col": 14, "colour": 3 },
+    { "name": "spark the model moved to cave (23, 4)", "type": "pixel", "row": 5, "col": 23, "colour": 8 },
+    { "name": "gem that fell into the spark's corridor, cave (24, 4)", "type": "pixel", "row": 5, "col": 24, "colour": 3 },
+    { "name": "exit still shut (looks like steel), cave (29, 4)", "type": "pixel", "row": 5, "col": 29, "colour": 12 },
+    { "name": "the explosion that killed the player left space, cave (5, 3)", "type": "pixel", "row": 4, "col": 5, "colour": 0 },
+    { "name": "where the killing boulder fell from is space, cave (5, 1)", "type": "pixel", "row": 2, "col": 5, "colour": 0 },
+    { "name": "dirt beside the blast, cave (1, 3)", "type": "pixel", "row": 4, "col": 1, "colour": 9 },
+    { "name": "gem at cave (4, 18), below the box", "type": "pixel", "row": 19, "col": 4, "colour": 3 },
+    { "name": "HUD, cave, box and verdict line the same on both models", "type": "same", "cells": [0, 0, 23, 39] },
+    { "name": "frame meter, the script's 240 play frames over four lives", "type": "meter", "row": 24, "col": 20, "frames": 240 }
+  ]
+}

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

@@ -0,0 +1,280 @@
+// cave.c: the rules. Built from c64-kb's oscar64/cave-scan recipe, with
+// pushing, a second enemy, explosions, gems collected for points, the exit
+// and the time counter added. Every rule here is written again in Python in
+// tools/gen.py (class Cave); change both together.
+#include "cave.h"
+
+char cave[CW * CH];
+char cave_move;
+char cave_got, cave_need, cave_time, cave_tick;
+unsigned cave_points;
+unsigned cave_player, cave_exit_at;
+bool cave_dead, cave_exited, cave_exit_open;
+char cave_events;
+char cave_seen;
+
+unsigned cave_dirty[DIRTY_MAX];
+char cave_ndirty;
+bool cave_overflow;
+
+// Headings in clockwise order: left, up, right, down. Turning left is
+// heading + 3, turning right heading + 1, both modulo 4.
+static const signed char step[4] = { -1, -CW, 1, CW };
+
+static void mark(char *q)
+{
+    if (cave_ndirty < DIRTY_MAX)
+        cave_dirty[cave_ndirty++] = q - cave;
+    else
+        cave_overflow = true;
+}
+
+// The one place an object moves. A move to a later cell in scan order sets
+// the scanned bit, so the scan skips the object when it gets there.
+static void put(char *dst, char v, char *src)
+{
+#if SCAN_FLAG
+    if (dst > src)
+        v |= SCANNED;
+#endif
+    *dst = v;
+    *src = SPACE;
+    if (v == PLAYER || v == (PLAYER | SCANNED))
+        cave_player = dst - cave;
+    mark(dst);
+    mark(src);
+}
+
+// A 3 x 3 explosion. Steel and the exit survive. Cells after `at` in scan
+// order get the scanned bit, so the explosion starts on the next cave frame
+// everywhere. `at` = 0xffff (from cave_end_frame) marks none.
+static void explode(unsigned centre, char kind, unsigned at)
+{
+    for (signed char dy = -CW; dy <= CW; dy += CW)
+        for (signed char dx = -1; dx <= 1; dx++)
+        {
+            unsigned n = centre + dy + dx;
+            char t = cave[n] & 0x7f;
+            if (t == STEEL || t == EXIT_SHUT || t == EXIT_OPEN)
+                continue;
+            if (t == PLAYER)
+                cave_dead = true;
+            cave[n] = n > at ? kind | SCANNED : kind;
+            mark(cave + n);
+        }
+    cave_events |= EV_BOOM;
+}
+
+static bool is_round(char t)
+{
+    return t == BOULDER || t == GEM || t == BRICK;
+}
+
+// Roll off a round object: left first, then right. Needs the side cell and
+// the cell below it empty. The object leaves falling.
+static bool roll(char *p, char fall)
+{
+    if (p[-1] == SPACE && p[CW - 1] == SPACE) { put(p - 1, fall, p); return true; }
+    if (p[1] == SPACE && p[CW + 1] == SPACE)  { put(p + 1, fall, p); return true; }
+    return false;
+}
+
+static void fall_rules(char *p, char v)
+{
+    char b = p[CW];
+    char bt = b & 0x7f;
+    if (b == SPACE)
+        put(p + CW, v, p);                            // keep falling
+    else if (bt == PLAYER || (bt >= SPARK && bt < MOTH))
+        explode(p + CW - cave, BLAST, p - cave);
+    else if (bt >= MOTH && bt < BLAST)
+        explode(p + CW - cave, BURST, p - cave);      // a moth dies into gems
+    else if (bt == BOULDER_F || bt == GEM_F)
+        ;                                             // wait for it to move
+    else if (!(is_round(bt) && roll(p, v)))
+    {
+        *p = v - 1;                                   // land
+        mark(p);
+        cave_events |= EV_LAND;
+    }
+}
+
+static void player_rules(char *p)
+{
+    if (cave_move >= 4)
+        return;
+    signed char s = step[cave_move];
+    char *t = p + s;
+    char tv = *t;
+    if (tv == SPACE || tv == DIRT)
+    {
+        if (tv == DIRT)
+            cave_events |= EV_DIG;
+        put(t, PLAYER, p);
+    }
+    else if (tv == GEM)
+    {
+        cave_got++;
+        cave_points += GEM_POINTS;
+        cave_events |= EV_GEM;
+        put(t, PLAYER, p);
+    }
+    else if (tv == EXIT_OPEN)
+    {
+        *p = SPACE;
+        mark(p);
+        cave_exited = true;
+    }
+    else if (tv == BOULDER && (cave_move == 0 || cave_move == 2) && t[s] == SPACE)
+    {
+        put(t + s, BOULDER, t);                       // push: the boulder first
+        put(t, PLAYER, p);
+        cave_events |= EV_PUSH;
+    }
+}
+
+// Sparks turn left when they can, moths turn right; either goes on when it
+// cannot turn, and turns the other way on the spot when both are blocked.
+// Either explodes when the player is next to it.
+static void enemy_rules(char *p, char v)
+{
+    char base = v < MOTH ? SPARK : MOTH;
+    char kind = v < MOTH ? BLAST : BURST;
+    for (char k = 0; k < 4; k++)
+        if ((p[step[k]] & 0x7f) == PLAYER)
+        {
+            explode(p - cave, kind, p - cave);
+            return;
+        }
+    char d = v & 3;
+    char first = base == SPARK ? (d + 3) & 3 : (d + 1) & 3;
+    char spin  = base == SPARK ? (d + 1) & 3 : (d + 3) & 3;
+    if (p[step[first]] == SPACE)
+        put(p + step[first], base + first, p);
+    else if (p[step[d]] == SPACE)
+        put(p + step[d], base + d, p);
+    else
+    {
+        *p = base + spin;
+        mark(p);
+    }
+}
+
+// One object's turn. Called only for codes BOULDER and up. It takes the row
+// and the column, not a cell pointer: with a pointer argument Oscar64 -O2
+// computed row + x for every cell before the test, and the loop took 42
+// cycles a cell instead of 17 (counted from the generated code). The frame meter read a typical play
+// frame of 11,812 cycles before and 7,004 after, on the build whose HUD still
+// rewrote every field each cave frame (6,340 with today's update_hud).
+static __noinline void cell(char *row, char x)
+{
+    char *p = row + x;
+    char v = *p;
+    if (v & SCANNED)
+    {
+        *p = v & 0x7f;                                // moved here this scan
+        return;
+    }
+    if (v == BOULDER || v == GEM)
+    {
+        char b = p[CW];
+        if (b == SPACE)
+            put(p + CW, v + 1, p);                    // start falling
+        else if (is_round(b & 0x7f))
+            roll(p, v + 1);
+    }
+    else if (v == BOULDER_F || v == GEM_F)
+        fall_rules(p, v);
+    else if (v == PLAYER)
+    {
+        cave_seen++;                                  // once a cave frame, or the scanned bit failed
+        player_rules(p);
+    }
+    else if (v >= BLAST)
+    {
+        if (v == BLAST + 2)
+            *p = SPACE;
+        else if (v == BURST + 2)
+            *p = GEM;
+        else
+            *p = v + 1;
+        mark(p);
+    }
+    else if (v >= SPARK)
+        enemy_rules(p, v);
+}
+
+// Interior rows y0 .. y1 - 1. The loop only reads and compares: LDA (row),Y,
+// CMP, BCC, INY, CPY, BCC: 5 + 2 + 3 + 2 + 2 + 3 = 17 cycles a cell of space,
+// dirt, brick or steel (from the generated code, both branches taken, no page
+// crossed). The dirty list starts
+// empty for each slice.
+__noinline void cave_scan_rows(char y0, char y1)
+{
+    cave_ndirty = 0;
+    cave_overflow = false;
+    char *row = cave + CW * y0;
+    for (char y = y0; y < y1; y++, row += CW)
+        for (char x = 1; x < CW - 1; x++)
+        {
+            char v = row[x];
+            if (v >= BOULDER)
+            {
+                if (v & SCANNED)
+                    row[x] = v & 0x7f;                // moved here this scan: no call
+                else
+                    cell(row, x);
+            }
+        }
+}
+
+void cave_start(char need, char time)
+{
+    cave_need = need;
+    cave_time = time;
+    cave_got = 0;
+    cave_tick = 0;
+    cave_points = 0;
+    cave_dead = cave_exited = cave_exit_open = false;
+    cave_move = NO_MOVE;
+    for (unsigned i = 0; i < CW * CH; i++)
+    {
+        if (cave[i] == PLAYER)
+            cave_player = i;
+        else if (cave[i] == EXIT_SHUT)
+            cave_exit_at = i;
+    }
+}
+
+// After the last slice of a cave frame: open the exit when the quota is met,
+// then run the clock. Time out explodes the player.
+void cave_end_frame(void)
+{
+    if (!cave_exit_open && cave_got >= cave_need)
+    {
+        cave[cave_exit_at] = EXIT_OPEN;
+        mark(cave + cave_exit_at);
+        cave_exit_open = true;
+        cave_events |= EV_OPEN;
+    }
+    if (cave_exited || cave_dead)
+        return;
+    if (++cave_tick == TICK_CAVE_FRAMES)
+    {
+        cave_tick = 0;
+        if (cave_time)
+            cave_time--;
+        if (cave_time == 0)
+            explode(cave_player, BLAST, 0xffff);
+    }
+}
+
+unsigned cave_fold(unsigned chk)
+{
+    for (unsigned i = 0; i < CW * CH; i++)
+    {
+        unsigned t = chk ^ (cave[i] & 0x7f);
+        chk = (t << 2) + t + 1;                       // (chk ^ v) * 5 + 1
+    }
+    return chk;
+}

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

@@ -0,0 +1,80 @@
+// cave.h: the cave and its rules (c64-kb technique cave_scan_engine).
+//
+// A 40 x 22 cave of one-byte cells, steel border included. One cave frame is
+// one top-to-bottom, left-to-right scan of the 38 x 20 interior. The game
+// splits it into slices of rows, one slice a display frame
+// (cave_scan_rows), then calls cave_end_frame. An object that moves down or
+// right gets bit 7 (SCANNED), so the scan skips it when it reaches the cell
+// it moved into. tools/gen.py holds a model of the same rules; the AUTOPILOT
+// build checks the cave against it.
+#ifndef CAVE_H
+#define CAVE_H
+
+#define CW 40                   // cave width in cells
+#define CH 22                   // cave height in cells
+
+// Element codes (tools/gen.py uses the same numbers). A code below BOULDER
+// never moves, and the scan loop does nothing more than compare it.
+#define SPACE      0
+#define DIRT       1
+#define BRICK      2            // round: things roll off it
+#define STEEL      3            // not round, not destroyed by explosions
+#define BOULDER    4
+#define BOULDER_F  5            // falling: the resting code + 1
+#define GEM        6
+#define GEM_F      7
+#define EXIT_SHUT  8            // drawn as steel until the quota is met
+#define EXIT_OPEN  9
+#define PLAYER     10
+#define SPARK      12           // 12..15: heading in the low two bits; keeps a wall on its left
+#define MOTH       16           // 16..19: keeps a wall on its right; dies into gems
+#define BLAST      20           // 20..22: explosion stages, then space
+#define BURST      23           // 23..25: explosion stages, then a gem
+#define CODES      26           // at most 32: render.c draws code & 0x1f at glyph $40 + code
+#define SCANNED    0x80
+
+#define NO_MOVE    0xff         // cave_move: headings 0..3 are left, up, right, down
+
+#define GEM_POINTS       10
+#define TICK_CAVE_FRAMES 12     // cave frames per unit of the time counter
+
+// Sound events a scan raised, for the effects engine (bits of cave_events).
+#define EV_DIG   0x01
+#define EV_PUSH  0x02
+#define EV_LAND  0x04
+#define EV_GEM   0x08
+#define EV_OPEN  0x10
+#define EV_BOOM  0x20
+
+extern char cave[CW * CH];
+extern char cave_move;          // the player's heading this cave frame, or NO_MOVE
+extern char cave_got, cave_need, cave_time, cave_tick;
+extern unsigned cave_points;    // points scored in this cave
+extern unsigned cave_player;    // cell index of the player
+extern unsigned cave_exit_at;
+extern bool cave_dead, cave_exited, cave_exit_open;
+extern char cave_events;
+extern char cave_seen;          // times the scan ran the player's rules; main.c resets it each cave frame
+
+// Cells a slice changed, for the renderer. A move marks two cells, an
+// explosion nine, so a slice holds up to 8 moves before the list overflows;
+// then render.c queues the slice's rows and redraws them two a frame.
+#define DIRTY_MAX 16
+extern unsigned cave_dirty[DIRTY_MAX];
+extern char cave_ndirty;
+extern bool cave_overflow;
+
+void cave_start(char need, char time);  // after the decode: find the player and exit
+void cave_scan_rows(char y0, char y1);  // scan interior rows y0 .. y1 - 1
+void cave_end_frame(void);              // after the last slice: exit, clock
+unsigned cave_fold(unsigned chk);       // chk = (chk ^ v) * 5 + 1 over all 880 cells
+
+// SCAN_FLAG=0 builds the rules without the scanned bit: the double-move bug
+// of the cave-scan recipe, which make selftest-scan must see fail.
+#ifndef SCAN_FLAG
+#define SCAN_FLAG 1
+#endif
+
+#pragma compile("cave.c")
+
+#endif

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

@@ -0,0 +1,20 @@
+// gen_autopilot.h: written by tools/gen.py. Do not edit; edit tools/gen.py.
+// The autopilot: one move per cave frame (L U R D, '-' still), per cave;
+// past the end of a cave's string the player stands still.
+static const char script0[] = "RRRRRRRRRRRRRRRRRRDDDR";
+static const char script1[] = "RRUD";
+static const char script2[] = "RRRRRRRRD";
+static const char script3[] = "RRUD";
+static const char * const script_for[4] = { script0, script1, script2, script3 };
+static const char script_len[4] = { 22, 4, 9, 4 };
+#define SCRIPT_STARTS 4
+#define LIVES_AUTOPILOT 3
+#define NAME_AUTOPILOT "ABE"
+// What the rules model says the program must hold at game over.
+#define EXPECT_FOLD 0x75fa
+#define EXPECT_SCORE 158UL
+#define EXPECT_GEMS 6
+#define EXPECT_CAVE 1
+#define EXPECT_PLAY_FRAMES 240
+#define EXPECT_STARTS 4
+#define EXPECT_RANK 3