c64-kb 0.17.0

package/templates/platformer/tools/tearcheck.py

@@ -0,0 +1,229 @@
+#!/usr/bin/env python3
+"""Shoot a run mid-scroll and prove every picture is whole.
+
+usage: tearcheck.py --x64sc X --harness DIR --src DIR --expect whole|torn PRG CYCLES...
+
+Renders the level from the program's own sources (src/level.c, src/art.c,
+src/game.h) into one picture 2,048 pixels wide, runs PRG headless in VICE
+once per cycle count on PAL and on NTSC, and matches each exit screenshot's
+playfield (character rows 0-19, the 38-column window) against that render:
+which camera positions give exactly these pixels, row by row.
+
+A whole picture is one camera for all 160 lines. VICE's exit screenshot is
+taken mid-frame, so a picture may also be two frames: lines above the beam
+from the frame being drawn, lines below from the one before. The two parts
+then differ by one frame of camera movement, at most CAM_SPEED (2) pixels,
+and the lower part must be exactly the camera the HUD shows (below).
+A torn picture has a part a whole column (8 pixels) off, or more than one
+seam. Sprite colours (white, light red, cyan) are masked; a coin cell may
+show the coin or the sky (it may have been taken).
+
+The phase test. The AUTOPILOT build prints on HUD row 23 ("CAM 0576") the
+camera of the picture the IRQ at line 251 has just set up. The lowest part
+of the playfield must be at that camera, give or take one frame's
+movement: a page and an XSCROLL that disagree put the whole picture 8
+pixels off, which the seam test alone cannot see.
+
+--expect whole: exit 0 when every shot is whole or a two-frame composite.
+--expect torn:  exit 0 when at least one shot is torn (the TEAR_DEMO build:
+                the check can see a tear). Exit 1 otherwise, 2 on a setup
+                error.
+"""
+import argparse
+import importlib.util
+import os
+import re
+import subprocess
+import sys
+import tempfile
+
+import numpy as np
+from PIL import Image
+
+CAM_SPEED = 2
+SPRITE_COLOURS = {1, 10, 3}             # player, walker, hopper (src/game.h COL_*)
+VCOL = ["BLACK", "WHITE", "RED", "CYAN", "PURPLE", "GREEN", "BLUE", "YELLOW",
+        "ORANGE", "BROWN", "LT_RED", "DARK_GREY", "MED_GREY", "LT_GREEN", "LT_BLUE", "LT_GREY"]
+
+
+def unescape(s):
+    return s.encode().decode("unicode_escape")
+
+
+def block(text, name):
+    m = re.search(rf"// {name}-BEGIN\n(.*?)// {name}-END", text, re.S)
+    if not m:
+        raise SystemExit(f"tearcheck: no {name}-BEGIN/END block")
+    return m.group(1)
+
+
+def load_model(src):
+    game = open(os.path.join(src, "game.h")).read()
+    level = open(os.path.join(src, "level.c")).read()
+    art = open(os.path.join(src, "art.c")).read()
+    ch = {k: int(v) for k, v in re.findall(r"#define (CH_\w+)\s+(\d+)", game)}
+    col = {k: VCOL.index(v) for k, v in re.findall(r"#define (COL_\w+)\s+VCOL_(\w+)", game)}
+    rows = [unescape(s) for s in re.findall(r'"((?:[^"\\]|\\.)*)"', block(level, "LEVEL"))]
+    tiles = block(level, "TILES")
+    key = unescape(re.search(r'tile_key\[\] = "((?:[^"\\]|\\.)*)"', tiles).group(1))
+    quads = [[ch[n] for n in q] for q in re.findall(r"\{\s*(CH_\w+),\s*(CH_\w+),\s*(CH_\w+),\s*(CH_\w+)\s*\}", tiles)]
+    hbody = re.search(r"heights\[64\] = \{(.*?)\};", level, re.S).group(1)
+    heights = [int(v) for v in re.findall(r"^\s*([\d, ]+),?\s*//", hbody, re.M) for v in v.split(",") if v.strip()]
+    ga = block(art, "GLYPH-ART")
+    codes = [ch[n] for n in re.findall(r"CH_\w+", re.search(r"glyph_code\[\] = \{(.*?)\};", ga, re.S).group(1))]
+    strs = re.findall(r'"([.byg]{4})"', re.search(r"glyph_art\[\]\[8\]\[5\] = \{(.*?)\};", ga, re.S).group(1))
+    if len(rows) != 10 or len(heights) != 64 or len(strs) != 8 * len(codes) or len(quads) != len(key):
+        raise SystemExit(f"tearcheck: could not read the model (rows {len(rows)}, heights {len(heights)}, "
+                         f"art {len(strs)}/{8 * len(codes)}, tiles {len(quads)}/{len(key)})")
+    # glyph -> 8 rows of 4 multicolour pixel values
+    glyph = {ch["CH_SKY"]: [[0] * 4 for _ in range(8)]}
+    val = {".": 0, "b": 1, "y": 2, "g": 3}
+    for i, code in enumerate(codes):
+        glyph[code] = [[val[c] for c in strs[i * 8 + r]] for r in range(8)]
+    for t in range(1, 7):                   # art.c slope_glyph: the higher of each pixel's two columns
+        h = heights[t * 8:t * 8 + 8]
+        g = []
+        for r in range(8):
+            row = []
+            for k in range(4):
+                s = min(h[2 * k], h[2 * k + 1])
+                row.append(0 if r < s else 3 if r == s else 1)
+            g.append(row)
+        glyph[ch["CH_SLOPE1"] - 1 + t] = g
+    palette = [col["COL_SKY"], col["COL_EARTH"], col["COL_GOLD"], col["COL_GRASS"]]
+    coin = key.index("o")
+
+    def render(with_coins):
+        img = np.zeros((160, len(rows[0]) * 16), dtype=np.uint8)
+        for ty, line in enumerate(rows):
+            for tx, k in enumerate(line):
+                t = key.index(k) if k in key else 0
+                if t == coin and not with_coins:
+                    t = 0
+                for q, code in enumerate(quads[t]):
+                    g = glyph[code]
+                    y0, x0 = ty * 16 + (q >> 1) * 8, tx * 16 + (q & 1) * 8
+                    for r in range(8):
+                        for k4 in range(4):
+                            img[y0 + r, x0 + 2 * k4:x0 + 2 * k4 + 2] = palette[g[r][k4]]
+        return img
+
+    return render(True), render(False)
+
+
+def load_check(harness):
+    spec = importlib.util.spec_from_file_location("check", os.path.join(harness, "check.py"))
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def shot_indices(path, model, chk):
+    im = Image.open(path).convert("RGB")
+    g = chk.GEOMETRY[model]
+    pal = {tuple(c): i for i, c in enumerate(chk.PALETTE[model])}
+    y0 = 51 - g["line_offset"]
+    a = np.array(im)[y0:y0 + 160, 31 + 8:335 + 8]      # VIC X 31-334, lines 51-210
+    out = np.full(a.shape[:2], 255, dtype=np.uint8)
+    for rgb, i in pal.items():
+        out[np.all(a == rgb, axis=2)] = i
+    return out
+
+
+def row_candidates(row, w1, w0):
+    """Camera positions at which this 304-pixel row matches the render."""
+    mask = np.isin(row, list(SPRITE_COLOURS)) | (row == 255)
+    ok = (w1 == row) | (w0 == row) | mask
+    return np.nonzero(ok.all(axis=1))[0]
+
+
+def segments(img, world1, world0):
+    from numpy.lib.stride_tricks import sliding_window_view
+    segs, cur, start = [], None, 0
+    for y in range(160):
+        w1 = sliding_window_view(world1[y], 304)
+        w0 = sliding_window_view(world0[y], 304)
+        c = set(row_candidates(img[y], w1, w0).tolist())
+        nxt = c if cur is None else cur & c
+        if not nxt:
+            segs.append((start, y - 1, cur))
+            start, nxt = y, c
+        cur = nxt
+    segs.append((start, 159, cur))
+    return segs
+
+
+def hud_camera(png, model, chk):
+    text = chk.read_text(chk.Shot(png, model), chk.load_glyphs(), 23, 30, 8)
+    return int(text[4:]) if text.startswith("CAM ") and text[4:].isdigit() else None
+
+
+def judge(segs, cam):
+    if any(not s[2] for s in segs):
+        return "no camera matches a part: not the level", None
+    if len(segs) > 2:
+        return f"TORN: {len(segs)} parts, seams at lines {[51 + s[0] for s in segs[1:]]}", None
+    what = "whole"
+    if len(segs) == 2:
+        a, b = segs[0][2], segs[1][2]
+        d = min(abs(x - y) for x in a for y in b)
+        if d > CAM_SPEED:
+            return f"TORN at line {51 + segs[1][0]}: parts {d} pixels apart", None
+        what = f"two frames, seam at line {51 + segs[1][0]}, cameras {min(a)} / {min(b)}"
+    low = segs[-1][2]
+    # In a real two-frame shot the lower part is the older frame, the one the
+    # HUD row (drawn after the playfield) belongs to: exactly its camera. A
+    # mid-picture XSCROLL write also makes two parts 1-2 pixels apart, but
+    # then the lower part is not the HUD camera (review mutation, line 150).
+    if len(segs) == 2 and cam is not None and cam not in low:
+        return f"SEAM NOT A FRAME BOUNDARY: lower part {sorted(low)[:3]} is not the HUD camera {cam}", None
+    if cam is None:
+        return what + "; HUD camera unreadable (the beam was on it)", low
+    off = min(abs(c - cam) for c in low)
+    if off > CAM_SPEED:
+        return f"OFF PHASE: the picture is {off} pixels from the HUD camera {cam}", None
+    return what + f", HUD camera {cam}", low
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--x64sc", required=True)
+    ap.add_argument("--harness", required=True)
+    ap.add_argument("--src", required=True)
+    ap.add_argument("--expect", choices=["whole", "torn"], required=True)
+    ap.add_argument("--timeout", default="180")
+    ap.add_argument("prg")
+    ap.add_argument("cycles", nargs="+")
+    a = ap.parse_args()
+    chk = load_check(a.harness)
+    world1, world0 = load_model(a.src)
+    torn = bad = 0
+    with tempfile.TemporaryDirectory() as tmp:
+        for model in ("pal", "ntsc"):
+            for cyc in a.cycles:
+                png = os.path.join(tmp, f"{model}-{cyc}.png")
+                cmd = ["timeout", a.timeout, a.x64sc, "-default", "-warp", "+sound", "+autostart-delay-random",
+                       "-autostartprgmode", "1", "-limitcycles", cyc]
+                if model == "ntsc":
+                    cmd += ["-model", "ntsc"]
+                subprocess.run(cmd + ["-exitscreenshot", png, "-autostart", a.prg],
+                               stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+                if not os.path.exists(png):
+                    print(f"tearcheck: no screenshot for {model} {cyc}", file=sys.stderr)
+                    sys.exit(2)
+                cam = hud_camera(png, model, chk)
+                verdict, cams = judge(segments(shot_indices(png, model, chk), world1, world0), cam)
+                if cams is None:
+                    torn += 1
+                    bad += 1
+                print(f"{'TORN' if cams is None else 'ok  '} {model.upper():4s} {int(cyc):>10,} cycles: {verdict}")
+    n = 2 * len(a.cycles)
+    if a.expect == "whole":
+        print(f"tearcheck: {n - bad} of {n} shots whole or two-frame composites")
+        sys.exit(0 if bad == 0 else 1)
+    print(f"tearcheck: {torn} of {n} shots torn; the check {'sees' if torn else 'does NOT see'} the tear")
+    sys.exit(0 if torn else 1)
+
+
+if __name__ == "__main__":
+    main()

package/templates/shmup-vertical/.claude/settings.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|MultiEdit|Write|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "h=\"$CLAUDE_PROJECT_DIR/harness/hooks/plan-gate.py\"; [ -f \"$h\" ] || h=\"$CLAUDE_PROJECT_DIR/../_harness/hooks/plan-gate.py\"; exec python3 \"$h\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/shmup-vertical/.mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "c64-kb": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["../../dist/cli.js", "serve"],
+      "env": {}
+    }
+  }
+}

package/templates/shmup-vertical/CLAUDE.md

@@ -0,0 +1,137 @@
+# Rules for an agent working on this C64 program
+
+This program runs on a stock Commodore 64, PAL and NTSC. It is built on the
+c64-kb harness (`./harness`, vendored from c64-kb's `templates/_harness`).
+c64-kb is the reference: its pages give the registers, timings, techniques,
+pitfalls and recipes this program is built from. A wrong number becomes a torn
+screen or a crash, so every claim here is measured or says it is not.
+
+A new program starts in c64-kb with `npm run new-project -- <starter> <dir>`.
+That copies the starter and the harness, points `.mcp.json` and `local.mk`
+at the c64-kb checkout, proves the copy with `make shot check`, and leaves a
+blank `PLAN.md`.
+
+## This starter: shmup-vertical
+
+A vertically scrolling shoot-em-up: a river scrolls down over a fixed
+score panel, the ship and the enemies fire character bullets, waves of
+enemies keyed to the scroll go through a sprite multiplexer, effects play
+inside the tune,
+and the high score is saved to drive 8. `README.md` has the file map and
+the first three things to extend. Start a program from it with
+`npm run new-project -- shmup-vertical <dir>` in c64-kb. `PLAN.md` here is
+a plan filled from real tool output; new-project keeps it as
+`PLAN-shmup-vertical-example.md` and gives the new program a blank one.
+
+What will bite you here:
+
+- `src/kernel.asm` owns the raster IRQ (`$FFFE`, KERNAL banked out). Add a
+  split as a new body in its chain; do not install a second handler.
+- No sprite may reach raster line 214 (sprites stop at Y 187, last line
+  208): a sprite there delays the panel split's writes (measured: 16 of
+  16 PAL shots broken with eight sprites on it; lines 209-213 were clean).
+  `make check` runs `make phases`, which compares the panel at all eight
+  YSCROLL phases; keep it passing after touching the split.
+- NTSC has little time to spare. `make stage` meters a staged heavy
+  stretch (worst 15,237 of 17,095 cycles on NTSC), but play reaches
+  heavier frames: `make joytest` and `make longplay` play the game with
+  fire held and a sweep and fail on any lost frame (`LOST_FRAMES`, `$02FD`).
+  In play's heaviest frames the work ended 7 lines before the frame IRQ
+  (`-dWORKEND=1`). Re-run all three after adding work to a frame. Work that
+  runs for every enemy or bullet every frame lives in `glyph.asm`,
+  `hit.asm` and `step.asm` for that reason.
+- Enemy dots are drawn before the beam reaches them only because enemies
+  fire from sprite Y 72-140 (`bullets.c`); `-dDRAWEND=1` measures the
+  margin. Keep new shots inside a window like it.
+- The two playfield screens are drawn from the map; write game text to
+  `level_screen()` and give its cells colour RAM below 8 (hires).
+- Oscar64's zero page reached `$56` here; the kernel uses none. Pass values
+  to the blob through its own bytes (`ASM_<LABEL>` in `build/asm.h`).
+- Disk calls go through `src/hiscore.c`, which stops the chain and turns
+  sprites off around them (sprite DMA on badlines hangs the KERNAL's serial
+  transfers). `make joytest` proves the save and the reboot.
+- `-dPROFILE=1` times each step of `play_frame` into `$0340` (CIA1 timer B,
+  IRQs held off per step); `-dWORKEND=1` records how late a frame's work
+  ended, at `$0370`; `-dLOOP_TEST=1` plays to GAME OVER and back to the
+  title; `-dEVENTLOG=1` logs each kill, hit and lost frame with its frame;
+  `-dGOD=1` keeps the ship; `make joy` with `tools/drive.py` drives the
+  normal game.
+
+## Before any code
+
+1. Brief: `npx tsx src/cli.ts game-briefing "<concept>" --archetype <name>`
+   (or `demo-briefing`), in the c64-kb checkout. Read what it proposes.
+2. For each technique you keep: `technique-lookup <name>` and
+   `pitfalls-for <name>`. Start from the recipe it names (`recipe-lookup`).
+3. Fill `PLAN.md`: paste the whole output of `check-compatibility` and of
+   `plan-budget` (same techniques) into their sections, list every technique
+   in its table, and replace every `FILL:` line.
+
+Until `PLAN.md` passes, a hook blocks Edit and Write under `src/`, and every
+make target that builds stops (`make plan-gate` says what is missing). With
+C64KB set, `make` re-runs `check-compatibility` and wants the pasted Verdict.
+The gate cannot see writes made through a shell command, or outputs edited
+into shape by hand: do neither. `make PLAN_GATE=off` overrides it; say why in
+`PLAN.md` if you do.
+
+## The loop
+
+```bash
+make                  # build build/<name>.prg
+make shot check       # autopilot build, headless PAL and NTSC, graded by expect.json
+make selftest         # the FORCE_FAULT build must fail the same checks
+make disk             # build/<name>.d64
+make claims           # every store the program makes, against what it declares
+make run              # windowed VICE, for a human
+```
+
+## Rules
+
+- Build before claiming. Code that has not built is not done.
+- Measure screenshots with `check.py` through `expect.json`, never by eye.
+  Every visible claim gets a check. Add one before you trust a change.
+- PAL and NTSC: both shots pass, or it is not done.
+- Name the rung for every number: measured here (`make shot`, the meter, the
+  VICE monitor), taken from a c64-kb page (say which), arithmetic, or not
+  measured. Never call something verified that was not run.
+- Frame cost comes from the meter: CIA2 timer A, printed as
+  `F<frames> W<worst> T<typical>` at row 24, columns 20 to 39, in AUTOPILOT
+  builds. It records the first `hold` frames: make that the autopilot
+  script's play frames. Typical is the median of those frames, the KB's
+  `cycles_per_frame_typical`. Keep grading, logging and printing outside the
+  bracket; work split between the main loop and IRQs is summed with
+  `METER_PAUSE` / `METER_START`.
+- Do not invent a register, routine or address. Look it up:
+  `lookup-register`, `lookup-kernal`, `memory-map`.
+- Lint every source you change: `npx tsx src/cli.ts lint <file>`.
+- Commit named paths only. Never `git add -A` or `git add .`. `build/`,
+  `shots/` and `local.mk` are never committed.
+
+## Harness facts you will need
+
+- `AUTOPILOT=1` builds read a scripted joystick byte instead of `$DC00` and
+  grade themselves: `$02FF` = `$01` and a green border on pass, `$02` and red
+  on fail. `FORCE_FAULT=1` must turn the verdict red and move something a
+  screenshot check can see.
+- Screenshot geometry (c64-kb `docs/runtime/vice-reference.md`): PAL 384 x 272,
+  row = raster line - 16; NTSC 384 x 247, row = line - 28; x = VIC X + 8. A
+  sprite at Y register y is drawn from line y + 1.
+- `check.py` reads text in the ROM character set unless a check names a
+  `charset` file; the meter's cells need 0-9, F, W and T in the set on screen.
+- A KickAssembler part called from C is a raw blob at its own `* =` address,
+  `$0880` or above; `build/asm.h` gives C its labels as `ASM_<LABEL>`
+  (`ASM_<SCOPE>_<LABEL>` inside a scope). Pass arguments through bytes in the
+  blob, not Oscar64's zero page (`$02` up; the top depends on the program:
+  `make zp` lists what the build's code touches).
+- The meter takes CIA2 timer A. Do not open RS-232 (device 2) while it runs.
+- The KERNAL serial routines end in `CLI` (ROM bytes `58 60` / `58 18` at
+  `$EDAB`, `$EDB5`, `$EDDB`, `$EE82`). After any disk call, `SEI` again if
+  the program runs with the KERNAL IRQ off: otherwise that IRQ lands inside
+  the meter's brackets and rewrites `$DC00`.
+
+## Calling c64-kb
+
+- CLI, from the c64-kb checkout (`C64KB` in `local.mk`):
+  `npx tsx src/cli.ts <command>`; `npx tsx src/cli.ts --help` lists them.
+- MCP: `.mcp.json` starts `node <c64-kb>/dist/cli.js serve` (run
+  `npm run build` in c64-kb first).

package/templates/shmup-vertical/Makefile

@@ -0,0 +1,131 @@
+# shmup-vertical: a vertically scrolling shoot-em-up starter. Every target
+# but phases, stage and joy comes from the harness:
+#   make            build build/shmup-vertical.prg (after the PLAN.md gate)
+#   make run        windowed VICE, joystick in port 2
+#   make shot       headless PAL and NTSC exit screenshots of the autopilot build
+#   make check      make phases, then grade shots/pal.png and shots/ntsc.png against expect.json
+#   make phases     the panel split frozen on each of the eight YSCROLL phases, PAL and NTSC,
+#                   compared with the graded phase-3 shot (tools/phases.py)
+#   make selftest   prove check fails on the FORCE_FAULT=1 build
+#   make stage      the heaviest frame the game makes (-dSTAGE=1): the meter's readout, PAL and NTSC
+#   make joy        the normal game reading its port byte from $02FE, for tools/drive.py
+#   make joytest    the joy build played to GAME OVER and rebooted: the saved HI must show
+#   make disk       build/shmup-vertical.d64
+#   make claims     c64-kb's claims-watch over the autopilot build, when available
+#   make clean
+NAME     := shmup-vertical
+C_MAIN   := src/main.c
+KICK_SRC := src/kernel.asm
+
+# Pinned after the verdict. Its disk round trip ends with the $02FF store at
+# about 21,700,000 cycles (PAL) and 21,600,000 (NTSC), under the VICE monitor
+# on a fresh disk. After it nothing on screen changes: PAL at 30,000,000 and
+# 34,000,000 cycles and NTSC at 30,000,000 and 36,000,000 gave byte-identical
+# pictures.
+SHOT_CYCLES_PAL  := 30000000
+SHOT_CYCLES_NTSC := 30000000
+
+# Drive 8 is attached during make shot: the autopilot writes and reads
+# HISCORE on a fresh copy of build/shmup-vertical.d64 each run (the harness).
+# A save cut off leaves a splat file; the program scratches and rewrites one
+# (drive reply 60).
+SHOT_DISK := 1
+
+# What the program may write, for make claims, found by claims-watch on the
+# autopilot build (30,000,000 cycles, drive 8 attached). zero_page $02-$56:
+# Oscar64's registers ($02-$52) and main's callee-saved temporaries, which
+# reached $56 in this build ($55 before the review's fixes grew main); a
+# bigger main reaches further. The $DC0D stores
+# that mask CIA1 count against all its units. The KERNAL routines are the
+# disk calls of src/hiscore.c (kernalio.h) and the KERNAL IRQ that runs
+# during the first load. CIA2 timers A and B are the frame meter's. $02FD
+# is LOST_FRAMES (main.c), which make joytest reads.
+CLAIMS_ARGS = --cycles 30000000 --disk $(abspath $(D64)) \
+  --claim 'zero_page $$02-$$56, sprite_0-7, vic_raster_irq, irq_vector_fffe, nmi_vector_fffa, sid_voice_1-3, sid_filter_volume, cia1_port_a, cia1_timer_a, cia1_timer_b, cia1_tod, cia2_vic_bank' \
+  --range 'colour=$$D800-$$DBE7,result=$$02FF,lost_frames=$$02FD' \
+  --harness 'cia2_timer_a, cia2_timer_b, cia2_tod' \
+  --kernal 'SETNAM,SETLFS,OPEN,CLOSE,CHKIN,CHKOUT,CLRCHN,CHRIN,CHROUT,READST,IRQ'
+
+# The harness sits beside the starter in c64-kb (../_harness) or is vendored
+# into ./harness when the starter is copied out on its own.
+# Proof targets `npm run verify:templates -- --selftest` runs after selftest.
+VERIFY_TARGETS := stage joytest longplay
+
+HARNESS ?= $(firstword $(wildcard harness) ../_harness)
+$(if $(wildcard $(HARNESS)/harness.mk),,$(error No harness at '$(HARNESS)'. Copy c64-kb's templates/_harness to ./harness, or make the project with npm run new-project in c64-kb))
+include $(HARNESS)/harness.mk
+
+# claims runs the autopilot build with the disk attached.
+claims: $(D64)
+
+# ---- phases: the split at every YSCROLL phase ----------------------------------------
+# The graded shot freezes on YSCROLL 3 only, so a broken entry in the split's
+# delay table (kernel.asm delay_tbl) for any other phase passes make shot
+# check. Each build here freezes on one phase; tools/phases.py shoots all
+# eight on both models and wants panel lines 215-250 identical to phase 3.
+PHASES := 0 1 2 3 4 5 6 7
+PRG_PHASES := $(foreach k,$(PHASES),build/$(NAME)-ph$(k).prg)
+build/$(NAME)-ph%.prg: $(C_DEPS) $(ASM_OUT) $(METER_DEPS) | plan-gate
+	@mkdir -p build
+	$(OSCAR64_BUILD) -d$(AUTOPILOT_DEFINE)=1 -dFREEZE_Y=$* -o=$@ $(C_MAIN)
+
+.PHONY: phases
+phases: $(PRG_PHASES) $(D64)
+	$(PYTHON) tools/phases.py --x64sc $(X64SC) --d64 $(D64) --pal $(SHOT_CYCLES_PAL) --ntsc $(SHOT_CYCLES_NTSC) $(PRG_PHASES)
+
+check: phases
+
+# ---- stage: the heaviest frame ------------------------------------------------------
+# -dSTAGE=1 plays a script that puts 12 enemies, bolts, enemy dots and a kill
+# in the same frames and meters play frames 150-399. Its verdict grades no
+# overrun and every bullet cell restored; stage-expect.json adds the meter's
+# worst inside a frame on both models. STAGE_DEFS='-dSD=24 -dSX=16' moves
+# the script (the worst of a 4 x 4 sweep; see PLAN.md). Re-run it after
+# adding work to a frame.
+STAGE_DEFS ?= -dSD=24 -dSX=16
+PRG_STAGE := build/$(NAME)-stage.prg
+$(PRG_STAGE): $(C_DEPS) $(ASM_OUT) $(METER_DEPS) $(STARTER_MAKEFILE) | plan-gate
+	@mkdir -p build
+	$(OSCAR64_BUILD) -d$(AUTOPILOT_DEFINE)=1 -dSTAGE=1 $(STAGE_DEFS) -o=$@ $(C_MAIN)
+
+.PHONY: stage
+stage: $(PRG_STAGE) $(D64)
+	$(call vice_shot,$(PRG_STAGE),40000000,,shots/stage-pal.png)
+	$(call vice_shot,$(PRG_STAGE),40000000,-model ntsc,shots/stage-ntsc.png)
+	$(PYTHON) tools/meter.py $(HARNESS_DIR) shots/stage-pal.png pal shots/stage-ntsc.png ntsc
+	$(PYTHON) $(HARNESS_DIR)/check.py stage-expect.json shots/stage-pal.png shots/stage-ntsc.png
+
+# ---- joy: the normal game driven headless ------------------------------------------
+# The port byte comes from $02FE instead of $DC00, so a VICE monitor can
+# drive it (tools/drive.py).
+PRG_JOY := build/$(NAME)-joy.prg
+$(PRG_JOY): $(C_DEPS) $(ASM_OUT) $(METER_DEPS) | plan-gate
+	@mkdir -p build
+	$(OSCAR64_BUILD) -dJOY_SOURCE=0x02fe -o=$@ $(C_MAIN)
+
+.PHONY: joy
+joy: $(PRG_JOY)
+
+# joytest: the joy build played on PAL and NTSC, fire held and the ship
+# swept, to GAME OVER; its save, and a reboot on the same fresh disk showing
+# that score as HI; then JOYTEST_SOAK more games a model, each graded on
+# LOST_FRAMES (tools/joytest.py). Any lost frame fails.
+JOYTEST_SOAK ?= 15
+.PHONY: joytest
+joytest: $(PRG_JOY) $(D64)
+	X64SC=$(X64SC) $(PYTHON) tools/joytest.py $(PRG_JOY) $(D64) --soak $(JOYTEST_SOAK)
+
+# longplay: a joy build whose ship is never lost (-dGOD=1), so fire held and
+# a sweep run through the level's later loops, where the waves come closer
+# together: LONGPLAY_GAMES games a model at once, LONGPLAY_SECONDS of warp
+# each, and any lost frame fails.
+LONGPLAY_SECONDS ?= 40
+LONGPLAY_GAMES ?= 4
+PRG_GOD := build/$(NAME)-god.prg
+$(PRG_GOD): $(C_DEPS) $(ASM_OUT) $(METER_DEPS) | plan-gate
+	@mkdir -p build
+	$(OSCAR64_BUILD) -dJOY_SOURCE=0x02fe -dGOD=1 -o=$@ $(C_MAIN)
+
+.PHONY: longplay
+longplay: $(PRG_GOD) $(D64)
+	X64SC=$(X64SC) $(PYTHON) tools/joytest.py $(PRG_GOD) $(D64) --long $(LONGPLAY_SECONDS) --soak $$(( $(LONGPLAY_GAMES) - 1 )) --jobs $(LONGPLAY_GAMES)