c64-kb 0.17.0

package/templates/shmup-vertical/README.md

@@ -0,0 +1,189 @@
+# shmup-vertical
+
+A vertically scrolling shoot-em-up for the stock C64, PAL and NTSC, built
+to be copied and grown into a game. It plays: title, fire to start, three
+lives, game over, back to the title.
+
+- A river scrolls down one line a frame, through all eight YSCROLL phases,
+  above a fixed score panel.
+- The ship is a multicolour sprite on joystick port 2. Its bolts are
+  characters.
+- Enemies arrive in waves set off by how far the river has scrolled. Each
+  flies a small path program, which can fire: a dot, also a character,
+  falls towards where the ship was. With the ship, up to 13 sprites go
+  through a multiplexer onto the 8 hardware sprites.
+- Hits are tested with a box per sprite frame.
+- A three-voice tune plays; shot, explosion and ship-lost effects borrow
+  voice 3 and hand it back.
+- The high score is saved to drive 8 and loaded at start; a fresh disk's
+  title shows HI 000000. With no drive, the game runs without saving. A
+  save that was cut off (a splat file) is scratched and written again.
+
+Fire starts a game on the title only after it has been released: hold it
+through GAME OVER and the title waits.
+
+Make a project from it in c64-kb with
+`npm run new-project -- shmup-vertical <dir>`, then `make run`.
+
+## Files
+
+| File | What it holds |
+|---|---|
+| `src/main.c` | States (title, play, game over), the ship, the frame loop, the autopilot scripts and their verdict |
+| `src/level.c` | The river map and the downward scroll through two screens |
+| `src/waves.c` | The wave list, the path bytecode (MOVE, LOOP, FIRE, END), the pool of 12 enemies |
+| `src/bullets.c` | The ship's bolts and the enemies' dots: firing and the rules |
+| `src/hitbox.c` | The ship's box; the hits turned into events |
+| `src/display.c` | Character set, sprite art (as text), the score panel |
+| `src/hiscore.c` | The HISCORE file on drive 8 |
+| `src/game.h` | Memory map, the kernel's variables as C names, shared state |
+| `src/kernel.asm` | The raster IRQ chain, the panel split, the three-row copy (KickAssembler) |
+| `src/mux.asm` | The sprite multiplexer: sort, build, zone IRQs |
+| `src/sound.asm` | The music player with effects inside it, and the tune |
+| `src/glyph.asm` | The character bullets: the bolts' and the dots' moves and draws, the list, the erase, the restore check |
+| `src/hit.asm` | The dots against the ship; every enemy's box against the ship's and the bolts' |
+| `src/step.asm` | The path bytecode run for every enemy, explosions, one path step for every flying enemy |
+| `tools/phases.py` | `make phases`: the panel at every YSCROLL phase against the graded one |
+| `tools/meter.py` | `make stage`: reads the meter off the staged run's shots |
+| `tools/drive.py` | Plays the `make joy` build headless over VICE's binary monitor |
+| `tools/joytest.py` | `make joytest`: games played on PAL and NTSC to GAME OVER, graded on lost frames, and a reboot that must show the saved HI; `make longplay`: long games with a ship that is never lost |
+| `PLAN.md` | The plan, with the c64-kb tool output it was built from |
+| `expect.json`, `stage-expect.json` | What the graded and the staged screenshots must show |
+
+C does the game; KickAssembler does what needs exact cycles, no zero page,
+or runs for every enemy or bullet every frame. The harness assembles
+`kernel.asm` (which imports the other `.asm` files) to a blob at `$0880`
+and writes `build/asm.h`, so C calls it as `ASM_<LABEL>`.
+
+## How a frame runs
+
+The frame IRQ on line 252 sets the playfield's registers, shows the first
+eight sprites and tells C a frame began. C then restores the bullet cells,
+checks them against the map (AUTOPILOT builds), and moves and draws the
+bolts and dots before the beam reaches them. It tests hits, moves the ship,
+runs the waves, hands the actors to the multiplexer, draws three rows of
+the hidden screen and sets next frame's scroll. Zone IRQs reuse sprites down
+the screen. The split IRQ on line 212 switches to the panel on line 215 and
+plays the music.
+
+## Measured
+
+VICE x64sc 3.10, the harness meter. The graded script's 240 play frames:
+
+| Model | Worst frame | Typical (median) | Frame |
+|---|---|---|---|
+| PAL | 11,681 cycles | 8,374 | 19,656 |
+| NTSC | 11,875 cycles | 8,733 | 17,095 |
+
+`make stage` plays a script that puts 12 enemies, bolts, dots and a kill in
+the same frames, and meters play frames 150-399. The worst of a sweep of its
+timing over 16 variants is the variant it runs:
+
+| Model | `make stage` worst | Typical | Frame |
+|---|---|---|---|
+| PAL | 15,064 cycles | 9,280 | 19,656 |
+| NTSC | 15,237 cycles | 9,967 | 17,095 |
+
+The figures hold the C loop's frame and every IRQ, with badlines and sprite
+DMA. They leave out the loop's head (the wait, the scroll hand-over, the
+stick), the meter's own bookkeeping and about 45 cycles of entry and exit
+per IRQ outside the C loop's bracket. So a frame can be lost below 17,095:
+at 7974a7a the staged run lost one on NTSC with its worst at 16,122.
+
+The staged worst was not the heaviest frame play reaches. With fire held
+and the ship swept, NTSC play lost frames at 7974a7a: in the review's
+drive, 6 of 15 games, at play frame 465 in 5 of them; in a build of it
+with `-dWORKEND=1`, 4 of 4 games, at play frames 282-321 (the row-32 and
+row-40 swoops) and 454-477 (the row-48 saucers and the row-56 darts on the
+screen together), with bolts, dots and kills in the same frames. The staged
+run stops recording at play frame 399, before the second stretch.
+`-dWORKEND=1` reads the raster when a frame's work ends, in lines after the
+frame IRQ's line 252: the staged run's latest end on NTSC is now line 249
+of 263, and play's is 256, at play frames 464-472.
+
+Cuts to the work brought play back inside the NTSC frame; PLAN.md lists
+them with their figures. The largest: the bolts' loop, the paths and the
+dots' test against the ship moved to KickAssembler; the enemy box scan
+skips enemies whose lines miss every box and walks only the boxes that are
+on; the multiplexer's build loop keeps its write place in a register.
+`make joytest` now plays 16 games a model with fire held and a sweep, and
+fails on any lost frame: 16 of 16 NTSC games lost none. `make longplay`
+plays 4 games a model for 40 s of warp with a ship that is never lost
+(about 44,000 play frames each on NTSC, through the level's later loops):
+none lost a frame. The latest end over those runs was line 256 of 263 on
+NTSC (7 lines, about 450 cycles, to spare) and 243 of 312 on PAL.
+
+A frame far past the frame shows in the meter as about 65,524: CIA2 timer A
+counts down from 65,535 and wraps. A reading that high is a wrap, not the
+frame's size; count the lost frames instead (`OVERRUNS` in the verdict,
+`LOST_FRAMES` at `$02FD` in any build).
+
+The meter's readout is printed only after the freeze. Printed every frame,
+it cost up to 3,404 cycles outside the bracket and made the autopilot build
+drop frames that the game itself does not. The self-check of the bullet
+cells (about 250 cycles, and the map code each draw notes for it) runs in
+AUTOPILOT builds only and is inside the figures.
+
+The bullet draw must end before the beam reaches the cells it changes. The
+smallest margin measured (`-dDRAWEND=1`, NTSC) was 19 lines for a dot in
+the graded run and 25 in the staged run; for the bolts, read after all of
+them were drawn, 26 in both. On PAL the bolts were drawn before line 0 and
+the dots had 69 lines or more.
+
+`make phases` (part of `make check`) freezes the game on each of the eight
+YSCROLL phases and wants the panel identical to the graded one on both
+models: a bad entry in the split's delay table fails it. More in PLAN.md.
+
+## Next steps
+
+1. **A boss.** Several sprites at fixed offsets from one origin, moved as
+   one, entered as consecutive actors of the multiplexer. Technique
+   `multi_sprite_object`, recipe `oscar64-multi-sprite-object`.
+2. **Difficulty.** Replace the spacing shift in `spawner()` with level
+   tables read from data: speeds, counts, spacing and fire per loop, held
+   at the last row. Technique `difficulty_ramp_tables`, recipe
+   `oscar64-difficulty-tables`.
+3. **Power-ups.** A pickup is one more actor with its own box group against
+   the ship only: `hit.asm`'s `hit_scan` tests its boxes against enemies,
+   so give pickups their own loop beside `dot_scan` there. Technique
+   `per_frame_hitbox`, recipe `oscar64-per-frame-hitbox`.
+
+The level is the `bank` table in `level.c` (river widths every 4 map rows)
+and the `wave` table in `waves.c` (map row, path, type, count, spacing,
+formation). Paths are the byte arrays above them; `P_FIRE` fires a dot when
+the enemy is between sprite Y 72 and 140 (the window that keeps the draw
+ahead of the beam). Re-run `make stage` after changing either.
+
+## Left out on purpose
+
+- Colour per map cell: colour RAM cannot be double-buffered, so every
+  playfield cell shares one colour RAM value and the map is 4 colours.
+- Sprites below line 208: a sprite on line 214 breaks the panel split
+  (measured); 209-213 were clean, and MAX_SY keeps 5 lines of margin.
+- Enemy fire from above sprite Y 72 or below 140; power-ups, a boss, a
+  high-score table with names.
+- Keyboard and a second joystick; RESTORE does nothing.
+
+## Checks
+
+`make shot check` runs the autopilot on PAL and NTSC with a fresh copy of
+the disk on drive 8. The script shoots darts and saucers, is hit by a dart's
+dot, fires through a parade of ten enemies, then stops; the program freezes
+on YSCROLL 3, saves and reloads the high score and grades 18 facts,
+printing the number of the first that fails. `expect.json` then checks the
+verdict, the text, the meter, the ship and all ten parade sprites, the
+river's banks at 30 rows scrolled, the split and the panel. `make selftest`
+starts the ship 16 pixels to the right and must fail. `make stage`, `make
+joytest` and `make longplay` are this starter's proof targets
+(VERIFY_TARGETS), which `npm run verify:templates -- --selftest` runs too. `make claims` checks
+every store the program makes against what the Makefile declares. `make
+joy` builds the normal game reading its stick from `$02FE`, for
+`python3 tools/drive.py build/shmup-vertical-joy.prg "until:PUSH FIRE" tap:fire ...`
+(it takes a free monitor port unless DRIVE_PORT names one).
+
+Measuring switches, none in a release build: `-dPROFILE=1` (each step of the
+heaviest frame), `-dDRAWEND=1` (the bullet draw's margin to the beam),
+`-dWORKEND=1` (how late in the frame the work ended, at `$0370`; `=2` adds
+each step), `-dEVENTLOG=1` (each kill, hit and lost frame with its frame),
+`-dGOD=1` (the ship is never lost), `-dLOOP_TEST=1` (play to GAME OVER and
+back), `-dFREEZE_Y=0..7` (freeze on another phase).

package/templates/shmup-vertical/expect.json

@@ -0,0 +1,38 @@
+{
+  "checks": [
+    { "name": "own verdict (border)", "type": "verdict" },
+    { "name": "verdict line", "type": "text", "row": 9, "col": 1, "text": "RESULT 01 PASS" },
+    { "name": "score, kills, lives", "type": "text", "row": 10, "col": 1, "text": "SCORE 000450 KILLS 05 LIVES 2" },
+    { "name": "sprites shown, waves, ship, kills by type", "type": "text", "row": 11, "col": 1, "text": "SHOWN 11 WAVES 04 SHIP 060 176 K 1 4 0" },
+    { "name": "enemy dots fired, dots that hit the ship, frames that overran", "type": "text", "row": 12, "col": 1, "text": "FIRED 10 HIT 1 OVERRUNS 00" },
+    { "name": "frame meter, the script's 240 play frames", "type": "meter", "row": 13, "col": 10, "frames": 240 },
+
+    { "name": "ship where the script leaves it (X 120, Y 176): its light blue", "type": "sprite", "colour": 14, "vic_x": 124, "line": 180, "width": 16, "height": 12 },
+    { "name": "parade bug A1 (X 60, Y 72)", "type": "sprite", "colour": 4, "vic_x": 64, "line": 76, "width": 16, "height": 9 },
+    { "name": "parade bug A2 (X 108, Y 72)", "type": "sprite", "colour": 4, "vic_x": 112, "line": 76, "width": 16, "height": 9 },
+    { "name": "parade bug A3 (X 156, Y 72)", "type": "sprite", "colour": 4, "vic_x": 160, "line": 76, "width": 16, "height": 9 },
+    { "name": "parade bug A4 (X 204, Y 72)", "type": "sprite", "colour": 4, "vic_x": 208, "line": 76, "width": 16, "height": 9 },
+    { "name": "parade bug A5 (X 252, Y 72)", "type": "sprite", "colour": 4, "vic_x": 256, "line": 76, "width": 16, "height": 9 },
+    { "name": "parade bug B1 (X 60, Y 102)", "type": "sprite", "colour": 4, "vic_x": 64, "line": 106, "width": 16, "height": 9 },
+    { "name": "parade bug B2 (X 108, Y 102)", "type": "sprite", "colour": 4, "vic_x": 112, "line": 106, "width": 16, "height": 9 },
+    { "name": "parade bug B3 (X 156, Y 102)", "type": "sprite", "colour": 4, "vic_x": 160, "line": 106, "width": 16, "height": 9 },
+    { "name": "parade bug B4 (X 204, Y 102)", "type": "sprite", "colour": 4, "vic_x": 208, "line": 106, "width": 16, "height": 9 },
+    { "name": "parade bug B5 (X 252, Y 102)", "type": "sprite", "colour": 4, "vic_x": 256, "line": 106, "width": 16, "height": 9 },
+
+    { "name": "scrolled 30 rows: map row 36's right bank edge in screen row 14, column 25 (sand)", "type": "pixel", "vic_x": 226, "line": 163, "colour": 7 },
+    { "name": "... water left of that edge", "type": "pixel", "vic_x": 224, "line": 163, "colour": 6 },
+    { "name": "... earth right of it", "type": "pixel", "vic_x": 229, "line": 163, "colour": 9 },
+    { "name": "... map row 35 in screen row 15 is water in that column", "type": "pixel", "vic_x": 226, "line": 171, "colour": 6 },
+    { "name": "... map row 36's left bank edge in column 4 (sand)", "type": "pixel", "vic_x": 60, "line": 163, "colour": 7 },
+
+    { "name": "split: line 214 is still playfield (water in column 25)", "type": "pixel", "vic_x": 224, "line": 214, "colour": 6 },
+    { "name": "split: line 216 is the panel's grey", "type": "pixel", "vic_x": 224, "line": 216, "colour": 11 },
+    { "name": "panel rule, light grey, 40 columns (lines 218-219)", "type": "rect", "colour": 15, "vic_x": 24, "line": 218, "width": 320, "height": 2 },
+    { "name": "panel background, a blank row, 40 columns", "type": "rect", "colour": 11, "vic_x": 24, "line": 231, "width": 320, "height": 8 },
+    { "name": "two lives left: two cyan ships", "type": "rect", "colour": 3, "vic_x": 88, "line": 243, "width": 16, "height": 1 },
+    { "name": "no third life", "type": "rect", "colour": 11, "vic_x": 104, "line": 243, "width": 8, "height": 1 },
+    { "name": "no sprite under the panel: the panel's lines match on both models", "type": "same", "area": { "vic_x": 24, "line": 215, "width": 320, "height": 36 } },
+    { "name": "playfield rows 0-12 the same on both models", "type": "same", "cells": [0, 0, 12, 39] },
+    { "name": "playfield rows 14-20 the same on both models", "type": "same", "cells": [14, 0, 20, 39] }
+  ]
+}

package/templates/shmup-vertical/src/bullets.c

@@ -0,0 +1,158 @@
+// bullets.c: the ship's bolts and the enemies' bullets as characters, from
+// c64-kb's oscar64/char-bullets recipe (technique char_bullets). Each bullet
+// owns one reserved glyph. To draw it: save the screen code under it, copy
+// that code's glyph into the reserved glyph, OR the shot into it, write the
+// reserved code. Every bullet drawn in a frame goes on one list, bolts
+// first; restoring walks the list backwards, so bullets sharing a cell
+// unwind. The list, the moves and the draws are glyph.asm's (bb_run for the
+// bolts, eb_run for the dots, cb_draw, cb_erase, cb_check); this file fires
+// the bullets and holds the rules.
+//
+// Bolts: 1 pixel pair wide, rows 2-5 of their cell. A bolt moves up 7 lines
+// a frame while the playfield moves down 1, so it stays on rows 2-5 of
+// whatever cell it is in: b_line - 50 - YSCROLL = 8 * row every frame, the
+// carry frame included (YSCROLL 7 to 0, same row). b_line is the raster line
+// of the bolt's top row (row 2 of the cell, whose top is 48 + YSCROLL + 8 *
+// row). A bolt never straddles two cells.
+//
+// Enemy bullets: a 2 x 2 dot that falls 2 lines a frame and drifts one
+// pixel pair a frame towards where the ship was, snapped to an even glyph
+// row so it never crosses a cell edge. An enemy fires only between sprite Y 72 and
+// 140, so a bullet starts on line 84 or lower, in a cell that starts on line
+// 77 or lower. Bolts are drawn first; the draw must end before the beam
+// reaches the first cell it changes (the measured end is in PLAN.md).
+//
+// Colour: every playfield cell is multicolour with colour RAM $0F, so the
+// shots' pairs %11 draw in yellow and colour RAM is never touched.
+#include "bullets.h"
+#include "level.h"
+#include "display.h"
+#include "hitbox.h"
+
+#define EB_TOP    72            // enemies fire from sprite Y 72 ...
+#define EB_BOTTOM 140           // ... to 140
+#define eb_dx ((signed char *)ASM_EB_DX)
+
+unsigned eb_fired;
+
+#ifdef DRAWEND
+// Measuring only (-dDRAWEND=1): the smallest number of lines between the
+// raster just after a cell was written and the first line of that cell, at
+// the word it is given ($0364 bolts, $0366 dots; starts at $7FFF when main
+// sets it). Negative: the beam had reached the cell first. The raster is 0
+// while it is still in the lower border or has not reached line 0.
+char drawend_on;                                // main.c: 1 in a frame that starts on time
+
+static void drawend_margin(unsigned at, char top)
+{
+    if (!drawend_on)
+        return;
+    char l = vic.raster;
+    if ((vic.ctrl1 & 0x80) || l >= 250)
+        return;                                 // not yet past line 0: no risk
+    int m = (int)top - l;
+    volatile int *d = (volatile int *)at;
+    if (m < *d)
+        *d = m;
+}
+#endif
+
+void bullets_reset(void)
+{
+    for (char i = 0; i < NB; i++) {
+        b_live[i] = 0;
+        box_off(BOX_SHOT + i);
+    }
+    for (char j = 0; j < NEB; j++)
+        eb_live[j] = 0;
+    __asm { jsr ASM_CB_BEGIN }                  // an empty draw list
+    K_BYTE(ASM_CB_KEEP) = AUTOPILOT;            // bullets_restored needs the map's codes
+}
+
+// The bolt starts in the cell row above the ship's nose, placed as if drawn
+// this frame: the next frame's move keeps the invariant. Returns false when
+// every bolt is in flight or the ship is too high.
+bool bullet_fire(char hx, char ship_y)
+{
+    if (ship_y < 52 + 16 + cur_y)
+        return false;
+    char r = ((char)(ship_y - 52 - cur_y) >> 3) - 1;
+    for (char i = 0; i < NB; i++) {
+        if (!b_live[i]) {
+            b_live[i] = 1;
+            b_hx[i] = hx;
+            b_line[i] = 50 + cur_y + 8 * r;
+            return true;
+        }
+    }
+    return false;
+}
+
+// A dot from the middle of an enemy sprite at (hx, sy), drifting towards
+// target_hx. Outside the fire window, or with every slot in flight, nothing.
+void enemy_bullet_fire(char hx, char sy, char target_hx)
+{
+    if (sy < EB_TOP || sy > EB_BOTTOM)
+        return;
+    char x = hx + 6;
+    for (char j = 0; j < NEB; j++) {
+        if (!eb_live[j]) {
+            eb_live[j] = 1;
+            eb_hx[j] = x;
+            eb_line[j] = sy + 12;
+            eb_dx[j] = target_hx + 2 < x ? -1 : target_hx > x + 2 ? 1 : 0;
+            eb_fired++;
+            return;
+        }
+    }
+}
+
+void bullet_kill(char i)
+{
+    b_live[i] = 0;
+    box_off(BOX_SHOT + i);
+}
+
+void enemy_bullet_kill(char j)
+{
+    eb_live[j] = 0;
+}
+
+void bullets_erase(void)
+{
+    __asm { jsr ASM_CB_ERASE }
+}
+
+// Every cell the last draw changed holds the map's code again. Reads the
+// screen back, so an erase that skipped a cell, or ran in the wrong order,
+// leaves a reserved code there and fails.
+bool bullets_restored(void)
+{
+    __asm { jsr ASM_CB_CHECK }
+    return !K_BYTE(ASM_CB_FAULT);
+}
+
+void bullets_move_draw(void)
+{
+    K_BYTE(ASM_CB_FRONT) = cur_front;
+    K_BYTE(ASM_CB_TOP) = cur_row + 20;
+    K_BYTE(ASM_CB_Y) = cur_y;                   // the YSCROLL showing
+    __asm {
+        jsr ASM_CB_BEGIN
+        jsr ASM_BB_RUN                          // the bolts first
+    }
+#ifdef DRAWEND
+    // Read after all the bolts (then all the dots), so a margin here is
+    // smaller than the one just after its own cell was written: a lower
+    // bound.
+    for (char i = 0; i < NB; i++)
+        if (b_live[i])
+            drawend_margin(0x0364, b_line[i] - 2);  // the bolt's cell starts 2 lines up
+#endif
+    __asm { jsr ASM_EB_RUN }                    // then the enemies' dots
+#ifdef DRAWEND
+    for (char j = 0; j < NEB; j++)
+        if (eb_live[j])
+            drawend_margin(0x0366, eb_line[j] - ((char)(eb_line[j] - 48 - cur_y) & 7));
+#endif
+}

package/templates/shmup-vertical/src/bullets.h

@@ -0,0 +1,35 @@
+// bullets.h: the ship's bolts and the enemies' bullets, all drawn as
+// characters (char_bullets).
+#ifndef BULLETS_H
+#define BULLETS_H
+
+#include "game.h"
+
+// The ship's bolts, glyphs $F8-$FB. At most 3 fly at once: one shot per 7
+// frames (P_COOL 6), and a bolt from the lowest ship (Y 180) lives 16 frames
+// (arithmetic). The fourth is room for a faster gun.
+#define NB 4
+// The enemies' bullets, glyphs $F2-$F7.
+#define NEB 6
+
+// The bolts and the dots live in glyph.asm, which moves and draws them.
+#define b_live  ((char *)ASM_BB_LIVE)
+#define b_hx    ((char *)ASM_BB_HX)     // half X of the bolt's pixel pair
+#define b_line  ((char *)ASM_BB_LINE)   // raster line of the bolt's top row
+#define eb_live ((char *)ASM_EB_LIVE)
+#define eb_hx   ((char *)ASM_EB_HX)     // half X of the dot's pixel pair
+#define eb_line ((char *)ASM_EB_LINE)   // raster line of the dot's top row
+extern unsigned eb_fired;       // enemy bullets fired this game (play_enter clears it)
+
+void bullets_reset(void);
+bool bullet_fire(char hx, char ship_y);  // from a ship whose sprite Y is ship_y
+void enemy_bullet_fire(char hx, char sy, char target_hx);   // from an enemy sprite
+void bullets_erase(void);                // restore every drawn cell, reverse order
+void bullets_move_draw(void);            // move, draw into the showing screen
+void bullet_kill(char i);
+void enemy_bullet_kill(char j);
+bool bullets_restored(void);             // after bullets_erase: every cell is the map's
+
+#pragma compile("bullets.c")
+
+#endif

package/templates/shmup-vertical/src/display.c

@@ -0,0 +1,239 @@
+// display.c: the character set, sprite shapes, text and the score panel.
+// All art is original. Glyphs and sprites are written as strings of
+// multicolour pixel pairs, one digit per pair: 0 background, 1 $D022 or
+// $D025, 2 $D023 or the sprite's own colour, 3 colour RAM or $D026.
+#include "display.h"
+#include <c64/memmap.h>
+#include <string.h>
+
+// ---- playfield glyphs: 8 rows of 4 pairs each ------------------------------
+static const char * const glyph_art[7] = {
+    "11111121111111112111111111121111",    // G_LAND: earth, green specks
+    "22222212222222222122222222212222",    // G_GRASS
+    "23323322223223222322222122112112",    // G_TREE: canopy, trunk
+    "11111331331331311311111111111111",    // G_ROCK
+    "11301130111311131130113013001130",    // G_EDGE_L: land left, sand, water
+    "03110311311131110311031100310311",    // G_EDGE_R: water, sand, land right
+    "00000000000000000000000300300000",    // G_SPARKLE: light on the water
+};
+
+static const char life_glyph[8] = { 0x18, 0x3c, 0x3c, 0x7e, 0xff, 0xdb, 0x18, 0x00 };
+static const char rule_glyph[8] = { 0x00, 0x00, 0x00, 0xff, 0xff, 0x00, 0x00, 0x00 };
+
+// ---- sprites: 21 rows of 12 pairs -----------------------------------------
+static const char * const sprite_art[SPR_FRAMES][21] = {
+    {   // F_SHIP
+        "............", ".....33.....", ".....33.....", "....3223....",
+        "....2332....", "....2222....", "...122221...", "...122221...",
+        "..11222211..", ".1122332211.", "112223322211", "112222222211",
+        "11.222222.11", "1..122221..1", "...12..21...", "...3....3...",
+        "............", "............", "............", "............",
+        "............" },
+    {   // F_DART
+        "............", "..2......2..", "..22....22..", "..222..222..",
+        "...222222...", "...233332...", "....2332....", "....2112....",
+        ".....22.....", ".....22.....", ".....11.....", "............",
+        "............", "............", "............", "............",
+        "............", "............", "............", "............",
+        "............" },
+    {   // F_SAUCER
+        "............", "....3333....", "...322223...", "..22222222..",
+        ".2212121212.", "222222222222", ".1111111111.", "..1.1..1.1..",
+        "............", "............", "............", "............",
+        "............", "............", "............", "............",
+        "............", "............", "............", "............",
+        "............" },
+    {   // F_BUG
+        "............", "...1....1...", "....1..1....", "...222222...",
+        "..22322322..", "..22222222..", ".1222112221.", "1.22211222.1",
+        "..22222222..", ".1.222222.1.", "1...2222...1", ".....22.....",
+        "............", "............", "............", "............",
+        "............", "............", "............", "............",
+        "............" },
+    {   // F_BOOM1
+        "............", "............", ".....3......", "...3.2.3....",
+        "....222.....", "..32232223..", "....222.....", "...3.2.3....",
+        ".....3......", "............", "............", "............",
+        "............", "............", "............", "............",
+        "............", "............", "............", "............",
+        "............" },
+    {   // F_BOOM2
+        "............", "..3...3...3.", "...2..2..2..", "....1.1.1...",
+        ".3..22222..3", "..2.2.3.2.2.", "321.23332.12", "..2.2.3.2.2.",
+        ".3..22222..3", "....1.1.1...", "...2..2..2..", "..3...3...3.",
+        "............", "............", "............", "............",
+        "............", "............", "............", "............",
+        "............" },
+};
+
+// Four pair digits to one byte.
+static char pairs(const char *s)
+{
+    char b = 0;
+    for (char i = 0; i < 4; i++) {
+        char d = s[i];
+        b = (b << 2) | (d == '.' ? 0 : d - '0');
+    }
+    return b;
+}
+
+static void make_charset(void)
+{
+    __asm { sei }
+    mmap_set(MMAP_CHAR_ROM);
+    memcpy(CHARSET, (char *)0xd000, 64 * 8);        // letters, digits, punctuation
+    mmap_set(MMAP_NO_ROM);                          // I/O back; the kernel keeps $01 = $35
+    memset(CHARSET + 64 * 8, 0, 2048 - 64 * 8);
+    for (char g = 0; g < 7; g++) {
+        char *d = CHARSET + (G_LAND + g) * 8;
+        for (char r = 0; r < 8; r++)
+            d[r] = pairs(glyph_art[g] + 4 * r);
+    }
+    memcpy(CHARSET + G_LIFE * 8, life_glyph, 8);
+    memcpy(CHARSET + G_RULE * 8, rule_glyph, 8);
+    // Shots over open water need no merge (glyph.asm): a dot in each pixel
+    // pair on each even row pair, a bolt in each pair on rows 2-5, in %11.
+    for (char p = 0; p < 4; p++) {
+        char m = 0xc0 >> (2 * p);
+        for (char r = 0; r < 4; r++) {
+            char *d = CHARSET + (G_DOTS + 4 * p + r) * 8;
+            d[2 * r] = d[2 * r + 1] = m;
+        }
+        char *b = CHARSET + (G_BOLTS + p) * 8;
+        b[2] = b[3] = b[4] = b[5] = m;
+    }
+}
+
+static void make_sprites(void)
+{
+    for (char f = 0; f < SPR_FRAMES; f++) {
+        char *d = SPRITES + 64 * f;
+        for (char r = 0; r < 21; r++) {
+            const char *s = sprite_art[f][r];
+            d[0] = pairs(s);
+            d[1] = pairs(s + 4);
+            d[2] = pairs(s + 8);
+            d += 3;
+        }
+    }
+}
+
+void display_init(void)
+{
+    make_charset();
+    make_sprites();
+    cia2.pra = (cia2.pra & 0xfc) | 0x01;            // VIC bank 2: $8000-$BFFF
+    vic.color_border = VCOL_BLACK;
+    vic.color_back = PF_BG_COL;
+    vic.color_back1 = PF_MC1;
+    vic.color_back2 = PF_MC2;
+    vic.spr_multi = 0xff;
+    vic.spr_expand_x = 0;
+    vic.spr_expand_y = 0;
+    vic.spr_priority = 0;
+    vic.spr_mcolor0 = VCOL_DARK_GREY;
+    vic.spr_mcolor1 = VCOL_WHITE;
+    memset(PF0, G_WATER, 1000);
+    memset(PF1, G_WATER, 1000);
+    memset(COLOUR, PF_CRAM, 21 * 40);               // playfield rows 0-20
+    memset(COLOUR + 21 * 40, VCOL_WHITE, 4 * 40);   // panel rows 21-24
+    panel_draw();
+}
+
+// ASCII upper case, digits and punctuation to screen codes.
+void put_text(char *screen, char row, char col, const char *s)
+{
+    char *p = screen + 40 * row + col;
+    while (*s) {
+        char c = *s++;
+        *p++ = (c >= 'A' && c <= 'Z') ? c - 64 : c;
+    }
+}
+
+void text_colour(char row, char col, char n, char colour)
+{
+    memset(COLOUR + 40 * row + col, colour, n);
+}
+
+static const unsigned pow10[5] = { 1, 10, 100, 1000, 10000 };
+
+// Digits by repeated subtraction: no 16-bit division, a few hundred cycles.
+void put_dec(char *p, unsigned v, char digits)
+{
+    for (char i = digits; i > 0; i--) {
+        unsigned q = pow10[i - 1];
+        char d = '0';
+        while (v >= q) {
+            v -= q;
+            d++;
+        }
+        *p++ = d;
+    }
+}
+
+// ---- the panel: rows 20-24 of the screen at $8800 ------------------------------
+// Row 20 is a rule, drawn in colour RAM row 20's colour, which the playfield
+// shares (pitfall-free only because the playfield's value, $0F, reads as
+// light grey in hires). Rows 21-23 hold text; row 24 is cut by the border.
+#define SCORE_AT (PANEL + 21 * 40 + 8)          // five digits; the sixth is always 0
+#define HI_AT    (PANEL + 21 * 40 + 26)
+static char shown_lives = 0xff;
+// The score's digits change once a frame, in panel_update, however many
+// kills the frame had: the frames with most kills are the heaviest.
+static char score_due;
+
+void panel_draw(void)
+{
+    memset(PANEL, G_WATER, 1000);
+    memset(PANEL + 20 * 40, G_RULE, 40);
+    put_text(PANEL, 21, 2, "SCORE 000000         HI 000000");
+    put_text(PANEL, 23, 2, "LIVES");
+    put_dec(SCORE_AT, score, 5);
+    put_dec(HI_AT, hiscore, 5);
+    score_due = 0;
+    shown_lives = 0xff;
+    panel_update();
+}
+
+// Adds to the score's digits on the panel one digit at a time, so a kill
+// costs a few dozen cycles, not a 16-bit conversion. Call after score and
+// hiscore have been updated.
+static void add_digits(char tens)
+{
+    char *p = SCORE_AT + 4;
+    char c = tens;
+    for (;;) {
+        char d = *p - '0' + c;
+        c = 0;
+        while (d >= 10) {
+            d -= 10;
+            c++;
+        }
+        *p = '0' + d;
+        if (!c || p == SCORE_AT)
+            break;
+        p--;
+    }
+    if (score == hiscore)
+        memcpy(HI_AT, SCORE_AT, 5);
+}
+
+void panel_add(char tens)
+{
+    score_due += tens;
+}
+
+void panel_update(void)
+{
+    if (score_due) {
+        add_digits(score_due);
+        score_due = 0;
+    }
+    if (lives != shown_lives) {
+        for (char i = 0; i < 5; i++) {
+            PANEL[23 * 40 + 8 + i] = i < lives ? G_LIFE : G_WATER;
+            COLOUR[23 * 40 + 8 + i] = VCOL_CYAN;
+        }
+        shown_lives = lives;
+    }
+}