@8bitscript/c64 0.1.0

package/src/sid.8bs

@@ -0,0 +1,211 @@
+// @8bitscript/c64/sid — the SID, voice by voice.
+//
+// Named by "8bitscript".exports["./sid"] in this package's package.json:
+//
+//     import { sid, Waveform, Note } from "@8bitscript/c64/sid";
+//
+//     sid.setVolume(15);
+//     sid.setEnvelope(0, 0, 9, 8, 6);
+//     sid.setWaveform(0, Waveform.PULSE);
+//     sid.setPulseWidth(0, 2048);
+//     sid.play(0, Note.A4);       // gate on, at 440 Hz on a PAL machine
+//     ...
+//     sid.release(0);             // gate off: the release phase begins
+//
+// Hardware-level, C64-only surface — the layer a portable, note-level
+// sound capability (packages/studio/AGENTS.md) will sit on. It is the
+// 6581/8580's three voices as they are: an oscillator with four waveforms
+// (triangle, sawtooth, pulse with a 12-bit width, noise), an ADSR envelope
+// per voice, ring modulation and hard sync between neighbours, one filter
+// shared by all three, and a master volume. Nothing here is a tracker, a
+// sequencer or a driver; it is the registers with their units named.
+//
+// The SID's registers are write-only, so this file keeps a copy of each
+// voice's control byte: `setWaveform` changes the waveform bits and keeps
+// the gate, `play`/`release` change the gate and keep the waveform.
+//
+// ---- pitch --------------------------------------------------------------
+//
+// A voice's 16-bit frequency register is `Fn`, and the pitch it plays is
+// `Fn * clock / 16777216` Hz (the 6581 datasheet: 2^24), where `clock` is
+// the CPU clock — 985248 Hz on a PAL machine, 1022727 on NTSC. `Note`
+// names the equal-tempered notes C0 to B6 (A4 = 440 Hz), and `NOTE_PAL`
+// and `NOTE_NTSC` hold each one's `Fn` for the two clocks, computed from
+// that formula and checked by packages/compiler/test/c64-package.test.mjs.
+// One build runs on both regions (there is no region at build time), so
+// which table `play` reads is a run-time choice: `sid.setRegion(Region.X)`
+// from a program that knows, or `sid.detectRegion()`, which watches one
+// frame of the raster (detectRegion in @8bitscript/c64: two frames, once)
+// and chooses. Until either is called the PAL table is in use, and on an
+// NTSC machine that plays every note about 3.8 percent sharp: two thirds
+// of a semitone, in tune with itself. Both tables stop at the last
+// complete octave: B7's `Fn` would overflow the register on PAL (the
+// ceiling is about 3848 Hz), though C7 to A#7 would fit, and NTSC's
+// higher ceiling is not a reason for the tables to differ; `setFrequency`
+// takes any `Fn` directly.
+import { sidRegisters, detectRegion, Region } from "./index.8bs";
+
+// Control-register waveform bits; one of the four, or the ring/sync
+// modifiers OR-ed in. Ring modulation replaces a voice's triangle output
+// with the ring product against the previous voice (voice 0's partner is
+// voice 2); sync resets the oscillator on the previous voice's cycle.
+export namespace Waveform {
+    const TRIANGLE: utinyint = 0x10;
+    const SAWTOOTH: utinyint = 0x20;
+    const PULSE: utinyint = 0x40;
+    const NOISE: utinyint = 0x80;
+    const RING: utinyint = 0x04;
+    const SYNC: utinyint = 0x02;
+}
+
+// Filter modes for `setFilter`: OR them together for more than one.
+export namespace Filter {
+    const OFF: utinyint = 0x00;
+    const LOW_PASS: utinyint = 0x10;
+    const BAND_PASS: utinyint = 0x20;
+    const HIGH_PASS: utinyint = 0x40;
+}
+
+// Note indexes into NOTE_PAL: octave * 12 + semitone, C0 = 0, A4 = 57.
+// CS is C sharp, and so on.
+export namespace Note {
+    const C0: utinyint = 0; const CS0: utinyint = 1; const D0: utinyint = 2; const DS0: utinyint = 3; const E0: utinyint = 4; const F0: utinyint = 5; const FS0: utinyint = 6; const G0: utinyint = 7; const GS0: utinyint = 8; const A0: utinyint = 9; const AS0: utinyint = 10; const B0: utinyint = 11;
+    const C1: utinyint = 12; const CS1: utinyint = 13; const D1: utinyint = 14; const DS1: utinyint = 15; const E1: utinyint = 16; const F1: utinyint = 17; const FS1: utinyint = 18; const G1: utinyint = 19; const GS1: utinyint = 20; const A1: utinyint = 21; const AS1: utinyint = 22; const B1: utinyint = 23;
+    const C2: utinyint = 24; const CS2: utinyint = 25; const D2: utinyint = 26; const DS2: utinyint = 27; const E2: utinyint = 28; const F2: utinyint = 29; const FS2: utinyint = 30; const G2: utinyint = 31; const GS2: utinyint = 32; const A2: utinyint = 33; const AS2: utinyint = 34; const B2: utinyint = 35;
+    const C3: utinyint = 36; const CS3: utinyint = 37; const D3: utinyint = 38; const DS3: utinyint = 39; const E3: utinyint = 40; const F3: utinyint = 41; const FS3: utinyint = 42; const G3: utinyint = 43; const GS3: utinyint = 44; const A3: utinyint = 45; const AS3: utinyint = 46; const B3: utinyint = 47;
+    const C4: utinyint = 48; const CS4: utinyint = 49; const D4: utinyint = 50; const DS4: utinyint = 51; const E4: utinyint = 52; const F4: utinyint = 53; const FS4: utinyint = 54; const G4: utinyint = 55; const GS4: utinyint = 56; const A4: utinyint = 57; const AS4: utinyint = 58; const B4: utinyint = 59;
+    const C5: utinyint = 60; const CS5: utinyint = 61; const D5: utinyint = 62; const DS5: utinyint = 63; const E5: utinyint = 64; const F5: utinyint = 65; const FS5: utinyint = 66; const G5: utinyint = 67; const GS5: utinyint = 68; const A5: utinyint = 69; const AS5: utinyint = 70; const B5: utinyint = 71;
+    const C6: utinyint = 72; const CS6: utinyint = 73; const D6: utinyint = 74; const DS6: utinyint = 75; const E6: utinyint = 76; const F6: utinyint = 77; const FS6: utinyint = 78; const G6: utinyint = 79; const GS6: utinyint = 80; const A6: utinyint = 81; const AS6: utinyint = 82; const B6: utinyint = 83;
+}
+
+// Fn per note for a 985248 Hz clock: round(f * 2^24 / 985248).
+const NOTE_PAL: array<usmallint, 84> = [
+    278, 295, 313, 331, 351, 372, 394, 417, 442, 468, 496, 526, // octave 0
+    557, 590, 625, 662, 702, 743, 788, 834, 884, 937, 992, 1051, // octave 1
+    1114, 1180, 1250, 1325, 1403, 1487, 1575, 1669, 1768, 1873, 1985, 2103, // octave 2
+    2228, 2360, 2500, 2649, 2807, 2973, 3150, 3338, 3536, 3746, 3969, 4205, // octave 3
+    4455, 4720, 5001, 5298, 5613, 5947, 6300, 6675, 7072, 7493, 7938, 8410, // octave 4
+    8910, 9440, 10001, 10596, 11226, 11894, 12601, 13350, 14144, 14985, 15876, 16820, // octave 5
+    17820, 18880, 20003, 21192, 22452, 23787, 25202, 26700, 28288, 29970, 31752, 33640, // octave 6
+];
+
+// Fn per note for a 1022727 Hz clock: round(f * 2^24 / 1022727).
+const NOTE_NTSC: array<usmallint, 84> = [
+    268, 284, 301, 319, 338, 358, 379, 402, 426, 451, 478, 506, // octave 0
+    536, 568, 602, 638, 676, 716, 759, 804, 852, 902, 956, 1013, // octave 1
+    1073, 1137, 1204, 1276, 1352, 1432, 1517, 1608, 1703, 1804, 1912, 2025, // octave 2
+    2146, 2274, 2409, 2552, 2704, 2864, 3035, 3215, 3406, 3609, 3824, 4051, // octave 3
+    4292, 4547, 4817, 5104, 5407, 5729, 6070, 6430, 6813, 7218, 7647, 8102, // octave 4
+    8584, 9094, 9635, 10208, 10815, 11458, 12139, 12861, 13626, 14436, 15294, 16204, // octave 5
+    17167, 18188, 19270, 20415, 21629, 22916, 24278, 25722, 27251, 28872, 30589, 32407, // octave 6
+];
+
+// Which table `play` reads: Region.PAL until told otherwise.
+let region: utinyint = 0;
+
+// Each voice's register base: 7 * voice, without a multiply.
+const VOICE_BASE: array<utinyint, 3> = [0, 7, 14];
+
+// The control byte last written per voice (write-only register).
+let control: array<utinyint, 3>;
+// $D417 and $D418, likewise: filter routing/resonance and mode/volume.
+let filterControl: utinyint = 0;
+let modeVolume: utinyint = 0;
+
+export namespace sid {
+    const VOICE_COUNT: utinyint = 3;
+
+    // Master volume, 0-15. Filter mode bits are kept.
+    function setVolume(volume: utinyint): void {
+        modeVolume = (modeVolume & 0xF0) | (volume & 15);
+        sidRegisters[24] = modeVolume;
+    }
+
+    // The raw 16-bit frequency register; see the pitch formula above.
+    function setFrequency(voice: utinyint, frequency: usmallint): void {
+        sidRegisters[VOICE_BASE[voice]] = frequency & 0xFF;
+        sidRegisters[VOICE_BASE[voice] + 1] = frequency >> 8;
+    }
+
+    // Pulse width for Waveform.PULSE, 0-4095; 2048 is a square wave.
+    function setPulseWidth(voice: utinyint, width: usmallint): void {
+        sidRegisters[VOICE_BASE[voice] + 2] = width & 0xFF;
+        sidRegisters[VOICE_BASE[voice] + 3] = (width >> 8) & 0x0F;
+    }
+
+    // Attack and decay rates 0-15 (2 ms to 8 s), sustain level 0-15,
+    // release rate 0-15 (6 ms to 24 s) — the datasheet's tables.
+    function setEnvelope(voice: utinyint, attack: utinyint, decay: utinyint, sustain: utinyint, release: utinyint): void {
+        sidRegisters[VOICE_BASE[voice] + 5] = (attack << 4) | (decay & 15);
+        sidRegisters[VOICE_BASE[voice] + 6] = (sustain << 4) | (release & 15);
+    }
+
+    // The waveform (and ring/sync) bits; the gate is left as it is.
+    function setWaveform(voice: utinyint, waveform: utinyint): void {
+        control[voice] = (control[voice] & 0x01) | (waveform & 0xF6);
+        sidRegisters[VOICE_BASE[voice] + 4] = control[voice];
+    }
+
+    // Gate on: the envelope starts its attack, at whatever pitch is set.
+    function gateOn(voice: utinyint): void {
+        control[voice] = control[voice] | 0x01;
+        sidRegisters[VOICE_BASE[voice] + 4] = control[voice];
+    }
+
+    // Gate off: the envelope enters its release phase.
+    function release(voice: utinyint): void {
+        control[voice] = control[voice] & 0xFE;
+        sidRegisters[VOICE_BASE[voice] + 4] = control[voice];
+    }
+
+    // The `Fn` for `note` at the current region's clock.
+    function frequencyOf(note: utinyint): usmallint {
+        if (region == Region.NTSC) {
+            return NOTE_NTSC[note];
+        }
+        return NOTE_PAL[note];
+    }
+
+    // Set the pitch to `note` (a `Note.*` index) and gate on.
+    function play(voice: utinyint, note: utinyint): void {
+        sid.setFrequency(voice, sid.frequencyOf(note));
+        sid.gateOn(voice);
+    }
+
+    // Which clock the notes are computed for: Region.PAL or Region.NTSC.
+    function setRegion(which: utinyint): void {
+        region = which;
+    }
+
+    // Find the region from the raster (two frames) and use it. Returns it.
+    function detectRegion(): utinyint {
+        region = detectRegion();
+        return region;
+    }
+
+    // The filter: an 11-bit cutoff, resonance 0-15, which voices go
+    // through it (bits 0-2, one per voice), and the mode. Mode bits share
+    // $D418 with the volume; both copies are kept here.
+    function setFilter(cutoff: usmallint, resonance: utinyint, voices: utinyint, mode: utinyint): void {
+        sidRegisters[21] = cutoff & 0x07;
+        sidRegisters[22] = (cutoff >> 3) & 0xFF;
+        filterControl = (resonance << 4) | (voices & 0x07);
+        sidRegisters[23] = filterControl;
+        modeVolume = (modeVolume & 0x0F) | (mode & 0x70);
+        sidRegisters[24] = modeVolume;
+    }
+
+    // Every voice gated off with its waveform cleared, the filter off,
+    // volume 0: the state a program should leave the chip in, and a good
+    // one to start from.
+    function reset(): void {
+        for (let voice: utinyint = 0; voice < 3; voice++) {
+            control[voice] = 0;
+            sidRegisters[VOICE_BASE[voice] + 4] = 0;
+        }
+        filterControl = 0;
+        sidRegisters[23] = 0;
+        modeVolume = 0;
+        sidRegisters[24] = 0;
+    }
+}

package/src/sprites.8bs

@@ -0,0 +1,197 @@
+// @8bitscript/c64/sprites — the VIC-II's eight hardware sprites.
+//
+// Named by "8bitscript".exports["./sprites"] in this package's package.json:
+//
+//     import { sprites } from "@8bitscript/c64/sprites";
+//     import { spriteShapes } from "@8bitscript/c64/video";
+//
+// This is hardware-level, C64-only surface — the layer a portable sprite
+// capability (the `sprites.place(...)` intent API the root AGENTS.md
+// describes) will sit on, the way ./text.8bs is the layer under
+// @8bitscript/text. Importing it makes a program C64-specific, and it
+// promises what the VIC-II has: eight movable objects, no more, each 24x21
+// pixels of one colour over a transparent background (or 12x21 double-
+// width pixels of three colours in multicolour), each drawn in front of
+// or behind the background by its own bit, and in a fixed order among
+// themselves — sprite 0 is always in front of sprite 1.
+//
+// ---- shapes -----------------------------------------------------------------
+//
+// A sprite's picture is 63 bytes — 21 rows of 3 bytes, one bit per pixel
+// left to right — in a 64-byte block inside the VIC's bank, and the
+// sprite's pointer (screen + $3F8 + n, `spritePointers[n]`) names the block
+// as its address / 64. The blocks this package owns are $E400-$FFBF,
+// blocks 144-254 in bank 3 (./geometry.8bs says why the picture is there),
+// reachable as one array: `spriteShapes[64 * (block - FIRST_BLOCK) + i]`.
+// Shape data is a program's own `const` table, and a const array is data
+// wherever the linker put it — which the VIC cannot see — so a program
+// copies each shape into a block once, at start-up:
+//
+//     const SHIP: array<u8, 63> = [ ... ];
+//     const SHIP_BLOCK: u8 = sprites.FIRST_BLOCK;
+//     for (let i: u8 = 0; i < 63; i++) {
+//         spriteShapes[sprites.blockOffset(SHIP_BLOCK) + i] = SHIP[i];
+//     }
+//     sprites.setShape(0, SHIP_BLOCK);
+//
+// and from then on `setShape` is one byte, which is how animation works:
+// several blocks, one pointer write a frame.
+//
+// ---- positions --------------------------------------------------------------
+//
+// Coordinates are the VIC's: X is 9 bits (0-511) and Y 8 bits, in a space
+// where the visible 320x200 window starts at (24, 50) with 25 rows and 40
+// columns on — so a sprite at X = 24, Y = 50 has its top-left pixel in the
+// top-left corner of the screen, X < 24 or Y < 50 slides it under the
+// border, and the last fully visible position is (320, 229). `place` takes
+// the 9-bit X as one number and splits it across $D000 and $D010 itself.
+//
+// ---- collisions -------------------------------------------------------------
+//
+// The VIC records which sprites overlapped another sprite ($D01E) or a
+// foreground pixel of the background ($D01F) as it drew the last frame,
+// and CLEARS EACH REGISTER WHEN IT IS READ. So `collisions()` and
+// `backgroundCollisions()` are read once, right after waitFrame(), and the
+// byte is kept: a second read in the same frame is zero. A bit says a
+// sprite touched something, not what; two set bits in $D01E were a pair.
+import {
+    spritePositions, spriteXHigh, spriteEnable, spriteExpandX, spriteExpandY,
+    spritePriority, spriteMulticolor, spriteCollision, spriteBackgroundCollision,
+    spriteSharedColor0, spriteSharedColor1, spriteColors, setupVideo,
+    videoMode, VideoMode, writeUnderIo,
+} from "./index.8bs";
+import { Video, Bitmap, spritePointers, spriteShapes } from "./geometry.8bs";
+
+
+// Bit masks, indexed rather than shifted: `1 << n` with a variable n is a
+// loop on the 6502, a table lookup is one indexed load.
+const BIT: array<utinyint, 8> = [1, 2, 4, 8, 16, 32, 64, 128];
+const NOT_BIT: array<utinyint, 8> = [254, 253, 251, 247, 239, 223, 191, 127];
+
+export namespace sprites {
+    const COUNT: utinyint = 8;
+    const WIDTH: utinyint = 24; // pixels, before X expansion
+    const HEIGHT: utinyint = 21; // pixels, before Y expansion
+    const BYTES: utinyint = 63; // one shape: 21 rows of 3 bytes
+    const FIRST_BLOCK: utinyint = Video.SHAPE_BLOCK_FIRST; // 144: the first block this package owns
+    const BLOCK_COUNT: utinyint = Video.SHAPE_COUNT; // 111 blocks, 144-254
+    const LEFT: usmallint = 24; // X of the screen's left edge
+    const TOP: utinyint = 50; // Y of the screen's top edge
+    const VISIBLE_WIDTH: usmallint = 320;
+    const VISIBLE_HEIGHT: utinyint = 200;
+
+    // Where block `block`'s 63 bytes start in `spriteShapes`.
+    function blockOffset(block: utinyint): usmallint {
+        return (block - Video.SHAPE_BLOCK_FIRST) * 64;
+    }
+
+    // Put sprite `index` at (x, y) — X 0-511, Y 0-255, the VIC's space.
+    function place(index: utinyint, x: usmallint, y: utinyint): void {
+        spritePositions[index * 2] = x;
+        spritePositions[index * 2 + 1] = y;
+        if (x >= 256) {
+            spriteXHigh = spriteXHigh | BIT[index];
+        } else {
+            spriteXHigh = spriteXHigh & NOT_BIT[index];
+        }
+    }
+
+    // Draw sprite `index` from shape block `block` (FIRST_BLOCK and up; in
+    // bitmap mode, Bitmap.SHAPE_BLOCK_FIRST and up). The pointer is at
+    // screen + $3F8 wherever the screen matrix is: $E3F8 in text mode,
+    // $DFF8 under the I/O area in bitmap mode.
+    function setShape(index: utinyint, block: utinyint): void {
+        if (videoMode == VideoMode.BITMAP) {
+            writeUnderIo(Bitmap.SPRITE_POINTERS + index, block);
+        } else {
+            spritePointers[index] = block;
+        }
+    }
+
+    // Byte `i` (0-62) of shape block `block`, wherever the block is:
+    // blocks 144-254 are `spriteShapes` in plain RAM, blocks 96-111 are
+    // under the I/O area (for sprites over a bitmap) and each byte is its
+    // own window there. A shape copy loop can use this for either. Any
+    // other block is refused: below 64 is the program's own RAM, 64-95
+    // the upper-case character set, 112-143 the text screen (or the
+    // bitmap's colour matrix), 255 the CPU's vectors.
+    function setShapeByte(block: utinyint, i: utinyint, value: utinyint): void {
+        if (block >= Video.SHAPE_BLOCK_FIRST && block < Video.SHAPE_BLOCK_FIRST + Video.SHAPE_COUNT) {
+            spriteShapes[sprites.blockOffset(block) + i] = value;
+        } else if (block >= Bitmap.SHAPE_BLOCK_FIRST && block < Bitmap.SHAPE_BLOCK_FIRST + Bitmap.SHAPE_COUNT) {
+            writeUnderIo(Video.BANK + block * 64 + i, value);
+        }
+    }
+
+    function setColor(index: utinyint, color: utinyint): void {
+        spriteColors[index] = color & 15;
+    }
+
+    // The sprite is drawn from the next frame on. Sets the picture up
+    // (bank 3, the character set) if nothing has yet.
+    function show(index: utinyint): void {
+        setupVideo();
+        spriteEnable = spriteEnable | BIT[index];
+    }
+
+    function hide(index: utinyint): void {
+        spriteEnable = spriteEnable & NOT_BIT[index];
+    }
+
+    function hideAll(): void {
+        spriteEnable = 0;
+    }
+
+    // Twice as wide and/or twice as tall, from the same 24x21 shape.
+    function expand(index: utinyint, wide: bool, tall: bool): void {
+        if (wide) {
+            spriteExpandX = spriteExpandX | BIT[index];
+        } else {
+            spriteExpandX = spriteExpandX & NOT_BIT[index];
+        }
+        if (tall) {
+            spriteExpandY = spriteExpandY | BIT[index];
+        } else {
+            spriteExpandY = spriteExpandY & NOT_BIT[index];
+        }
+    }
+
+    // Behind the background's foreground pixels (text, a bitmap's set
+    // bits) rather than in front of them. Background colour always shows
+    // through a sprite's transparent pixels either way.
+    function setBehindBackground(index: utinyint, behind: bool): void {
+        if (behind) {
+            spritePriority = spritePriority | BIT[index];
+        } else {
+            spritePriority = spritePriority & NOT_BIT[index];
+        }
+    }
+
+    // Multicolour: pixel pairs, %01 shared colour 0, %10 the sprite's own
+    // colour, %11 shared colour 1, %00 transparent. Half the horizontal
+    // resolution for two more colours; the shared pair is one for all.
+    function setMulticolor(index: utinyint, on: bool): void {
+        if (on) {
+            spriteMulticolor = spriteMulticolor | BIT[index];
+        } else {
+            spriteMulticolor = spriteMulticolor & NOT_BIT[index];
+        }
+    }
+
+    function setSharedColors(color0: utinyint, color1: utinyint): void {
+        spriteSharedColor0 = color0 & 15;
+        spriteSharedColor1 = color1 & 15;
+    }
+
+    // Sprites that overlapped another sprite while the last frame was
+    // drawn, one bit each. Clears when read: once a frame, keep the byte.
+    function collisions(): utinyint {
+        return spriteCollision;
+    }
+
+    // Sprites that overlapped a foreground pixel of the background while
+    // the last frame was drawn. Clears when read, the same way.
+    function backgroundCollisions(): utinyint {
+        return spriteBackgroundCollision;
+    }
+}

package/src/text.8bs

@@ -0,0 +1,174 @@
+// @8bitscript/c64/text — the C64's implementation of @8bitscript/text.
+//
+// Named by "8bitscript".exports["./text"] in this package's package.json,
+// and what
+//
+//     import { text } from "@8bitscript/text";
+//
+// resolves to when the build is for the C64. Built on the registers
+// @8bitscript/c64 exports. Every machine's text.8bs exports this same
+// namespace — the same names, the same shapes, ASCII codes, and a cell 0
+// at the top-left corner inside the border — so a program that imports it
+// from @8bitscript/text draws the same thing on every target.
+import { memoryPointer, setupVideo, videoMode, VideoMode } from "./index.8bs";
+import { Video, screenRam, colorRam } from "./geometry.8bs";
+
+// The screen is addressed by flat cell index — a position is
+// `y * text.COLUMNS + x` — and these are the plainest things a text API
+// can be built from: poke one cell's character code, poke one cell's
+// colour, and how many cells the whole screen has. Whether a caller uses
+// these to clear the screen, lay out a label, or nothing at all is entirely
+// up to the caller — this package draws nothing on its own. Where the
+// 40x25 screen is (VIC bank 3, $E000 — ./geometry.8bs says why it is not
+// the KERNAL's $0400) reaches this file as `Video`; colour RAM is the
+// fixed 1K of nybbles at $D800 wherever the screen is.
+//
+// ---- character codes: ASCII in, screen codes out ----------------------------
+//
+// `text.putChar` takes ASCII on every machine — space (32), '0'-'9'
+// (48-57), 'A'-'Z' (65-90) and the punctuation `! , - . : ?` — upper case
+// only: that is the portable set, the characters every target's character
+// set has (the NES ships its own font, and that is what it has). The
+// hardware wants screen codes: in every Commodore character ROM, codes
+// 32-63 are those same ASCII values (space, digits, that punctuation), and
+// 'A'-'Z' are 1-26, so asciiToScreenCode() moves 64-95 down by 64 and
+// leaves 32-63 alone. Whether 1-26 then LOOK like 'A'-'Z' or 'a'-'z' is
+// the character set's choice — the ROM's boot state, whatever a program
+// ran before, or a user's SHIFT+C= — so this package owns the choice
+// rather than inheriting one: prepare() selects the upper-case set, every
+// run in text mode (in bitmap mode $D018 is the bitmap's, and left alone),
+// through the VIC-II's memory pointer (see @8bitscript/c64's
+// `memoryPointer`): one register write, of the value that also names this
+// screen's position in the bank, and "TICK" reads as TICK here the way it
+// does on the NES, the Atari, and the X16, none of which have a lower-case
+// set to fall into. (LLVM-MOS's libc used to flip every Commodore machine
+// to lower-case before main() with a hidden CHR$(14); packages/backend-6502
+// keeps that out of the link — see its commodoreCharsetGuard().)
+
+function asciiToScreenCode(code: utinyint): utinyint {
+    if (code >= 64 && code < 96) {
+        return code - 64;
+    }
+    return code;
+}
+
+// ---- print: strings and number fields ------------------------------------
+//
+// `text.print(cell, s)` writes a string's characters into consecutive
+// cells from `cell`, and `text.printNumber(cell, value, width)` writes
+// `value` as exactly `width` decimal digits, zero-padded and right-aligned,
+// so a field on a HUD never shifts columns. Both draw in the current colour —
+// white until `text.setColor(TextColor.CYAN)` changes it, and that one
+// call then colours everything printed after it, on the machines that have
+// per-cell colour. They are also the two
+// functions the compiler's template layout targets: `text.print(0,
+// \`TICK ${ticks:1}\`)` is laid out at compile time into these same calls
+// (see packages/compiler/src/ir).
+//
+// Under them: `place()` puts one character at one cell in the current
+// colour, and is all a run of text costs per character, with `prepare()`
+// making sure the picture is set up and selecting the upper-case set once
+// for the run. `text.putChar` and `text.putColor` stay the one-cell pokes
+// a caller can build anything from.
+let currentColor: utinyint = 1; // white, until text.setColor() says otherwise
+let currentReverse: bool = false; // until text.setReverse() says otherwise
+
+// Reverse video is bit 7 of the screen code: 128-255 are the ROM's
+// inverted copies of 0-127. A reverse space is a solid block in the
+// cell's colour, which is how a selected menu item becomes a filled bar.
+function toScreen(code: utinyint): utinyint {
+    let screen: utinyint = asciiToScreenCode(code);
+    if (currentReverse) {
+        screen = screen + 128;
+    }
+    return screen;
+}
+
+// What a run of text needs once, before its first character.
+function prepare(): void {
+    setupVideo();
+    if (videoMode == VideoMode.TEXT) {
+        memoryPointer = Video.MEMORY_POINTER_UPPERCASE;
+    }
+}
+
+function place(cell: usmallint, code: utinyint): void {
+    screenRam[cell] = toScreen(code);
+    colorRam[cell] = currentColor; // colour RAM is four bits wide; the VIC-II ignores the rest
+}
+
+// ---- digits -------------------------------------------------------------
+//
+// A number is written one place at a time, high to low, by subtracting the
+// place value until it no longer fits: the 6502 has no divide instruction,
+// and `value / 10` would link a 250-byte routine to do it. Places above the
+// field are still taken off, so a field narrower than its number shows the
+// low digits; places the number does not reach print as zeros.
+const DIGIT_PLACES: array<usmallint, 5> = [10000, 1000, 100, 10, 1];
+
+export namespace text {
+    const CELL_COUNT: usmallint = Video.CELL_COUNT; // 40 columns x 25 rows
+    const COLUMNS: utinyint = Video.COLUMNS; // cells per row, so cell = y * text.COLUMNS + x
+
+    function putChar(cell: usmallint, code: utinyint): void {
+        prepare();
+        screenRam[cell] = toScreen(code);
+    }
+
+    function putColor(cell: usmallint, color: utinyint): void {
+        colorRam[cell] = color;
+    }
+
+    function setColor(color: utinyint): void {
+        currentColor = color;
+    }
+
+    // Invert glyphs printed after this: the character pixels take the
+    // background colour and the rest of the cell takes the text colour.
+    function setReverse(on: bool): void {
+        currentReverse = on;
+    }
+
+    function print(cell: usmallint, s: string): void {
+        prepare();
+        for (let i: utinyint = 0; i < s.length; i++) {
+            place(cell + i, s[i]);
+        }
+    }
+
+    function printNumber(cell: usmallint, value: usmallint, width: utinyint): void {
+        prepare();
+        let k: utinyint = width;
+        if (k < DIGIT_PLACES.length) {
+            k = DIGIT_PLACES.length;
+        }
+        while (k > 0) {
+            let digit: utinyint = 48; // '0'
+            if (k <= DIGIT_PLACES.length) {
+                while (value >= DIGIT_PLACES[DIGIT_PLACES.length - k]) {
+                    value = value - DIGIT_PLACES[DIGIT_PLACES.length - k];
+                    digit++;
+                }
+            }
+            if (k <= width) {
+                place(cell + width - k, digit);
+            }
+            k--;
+        }
+    }
+}
+
+// The colours `text.setColor()` takes: the eight names every machine
+// shares, with this machine's colour-RAM values. Colour RAM takes all
+// sixteen VIC-II colours; the other eight are numbers 8-15, the ones
+// `BorderColor`/`BackgroundColor` in ./screen.8bs name.
+export namespace TextColor {
+    const BLACK: utinyint = 0;
+    const WHITE: utinyint = 1;
+    const RED: utinyint = 2;
+    const CYAN: utinyint = 3;
+    const PURPLE: utinyint = 4;
+    const GREEN: utinyint = 5;
+    const BLUE: utinyint = 6;
+    const YELLOW: utinyint = 7;
+}