@8bitscript/mega65 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 8BitScript contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@8bitscript/mega65",
+  "version": "0.1.0",
+  "description": "MEGA65 target support for 8BitScript: the hardware underneath the portable APIs.",
+  "license": "MIT",
+  "8bitscript": {
+    "entry": "./src/index.8bs",
+    "exports": {
+      "./screen": "./src/screen.8bs",
+      "./text": "./src/text.8bs",
+      "./input": "./src/input.8bs",
+      "./pointer": "./src/pointer.8bs"
+    },
+    "hardware": {
+      "facts": {
+        "video.columns": 80,
+        "video.rows": 25,
+        "video.cellWidth": 8,
+        "video.cellHeight": 8,
+        "video.palette": 256,
+        "video.cellColors": 2,
+        "video.colorPerCell": true,
+        "video.glyphs": 256,
+        "video.blockWidth": 2,
+        "video.blockHeight": 2,
+        "video.bitmap": true,
+        "video.layers": 1,
+        "video.scroll": true,
+        "video.sprites": 8,
+        "video.spritesPerLine": 8,
+        "video.spriteWidth": 64,
+        "video.spriteHeight": 255,
+        "video.spriteColors": 15,
+        "video.frameRate": 60,
+        "audio.voices": 16,
+        "audio.noise": true,
+        "audio.envelope": true,
+        "audio.filter": true,
+        "audio.pcm": true,
+        "audio.volume": true,
+        "audio.entropy": true,
+        "input.keyboard": true,
+        "input.joysticks": 2,
+        "input.pads": 0,
+        "input.mouse": false,
+        "input.paddles": false,
+        "storage.save": true,
+        "memory.ram": 45055,
+        "memory.banked": true,
+        "memory.bankedKib": 320,
+        "storage.kib": 783
+      },
+      "options": {},
+      "presets": {}
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.8bs

@@ -0,0 +1,79 @@
+// @8bitscript/mega65 — MEGA65 target support: the hardware underneath.
+//
+// The module entry point named by the "8bitscript".entry field in this
+// package's package.json, resolved and linked for:
+//
+//     import { borderColor, backgroundColor, memoryPointer } from "@8bitscript/mega65";
+//
+// The surface is the hardware, one register at a time. What a program
+// usually wants sits one layer up, in this package's own implementations of
+// the portable capability packages — `./src/screen.8bs` behind
+// @8bitscript/screen and `./src/text.8bs` behind @8bitscript/text, named by
+// the "8bitscript".exports map in package.json — which import these
+// registers and are built on nothing else.
+//
+// A program built with mos-mega65-clang loads at $2001 and runs in MEGA65
+// mode: the VIC-IV I/O personality is live, the CPU is at 40.5 MHz, the
+// ROM's screen is 80 columns wide at $0800, and the SDK's start-up leaves
+// interrupts off (`sei`, `$01 = $3E`, `$D030 = $44`) until exit — all
+// measured under xmega65, see AGENTS.md. The registers below are the
+// VIC-II-compatible ones the VIC-IV still answers to at the C64's
+// addresses, which is enough for a border, a background, and a character
+// set; the MEGA65's own registers (SCRNPTR, the palettes, the DMAgic, the
+// four SIDs) are not exported yet, and AGENTS.md is where their rules are.
+
+// $D020, the VIC-II(-compatible) border colour register.
+@address(0xD020)
+export let borderColor: volatile<u8>;
+
+// $D021, the VIC-II(-compatible) background colour register (background #0).
+@address(0xD021)
+export let backgroundColor: volatile<u8>;
+
+// $D018, the VIC-II-compatible memory pointer, laid out as the C64's: bits
+// 4-7 the screen base in 1K units, bits 1-3 the character set base in 2K
+// units. mega65.h names the default screen character matrix directly:
+// DEFAULT_SCREEN at $0800 — not the C64's $0400 — so the screen half is
+// $2x, and $24 selects the upper-case/graphics set at $1000 (the same 2K
+// the C64 has there) where $26 would be the lower-case set at $1800. The
+// MEGA65 re-derives its own wider VIC-IV pointers from a legacy $D018
+// write, so this is enough; verified on screen under xmega65, not inferred.
+@address(0xD018)
+export let memoryPointer: volatile<u8>;
+
+// $D030, the VIC-III control register A. The SDK's start-up sets it to $44
+// (PAL-RAM on, CROM9 on, no C65 ROM mapped, CRAM2K clear). Bit 0, CRAM2K,
+// maps the second kilobyte of colour RAM at $DC00-$DFFF in place of the
+// two CIAs — which the 80-column screen's cells 1024-1999 need, and which
+// text.8bs sets before every run of text (the frame runtime polls $D012,
+// not a CIA, so nothing here misses them). Writing anything but bit 0
+// re-maps ROM over the program: keep the other bits as the SDK left them.
+@address(0xD030)
+export let vicIIIControlA: volatile<u8>;
+
+export namespace VicIIIControl {
+    const SDK_STARTUP: utinyint = 0x44;          // what .init.010 stores
+    const COLOR_RAM_2K: utinyint = 0x45;         // the same, plus CRAM2K
+}
+
+// ---- CIA1 ($DC00): the keyboard matrix and the two control ports ------------
+//
+// A MEGA65 is a C64 here: the same chip at the same address, the same
+// eight columns by eight rows, the same key in the same place, and the
+// same two control ports on the same bits. So @8bitscript/c64/keys's codes
+// are the right codes on this machine, and `@8bitscript/mega65/input`
+// reads them exactly as the C64's layer does.
+//
+// What this machine adds and that layer does not yet read: the MEGA65's
+// own extended keyboard — the full-travel keys a C64 never had, including
+// **ALT**, CAPS LOCK and the four dedicated cursor keys — which the
+// hardware presents through its own registers rather than through this
+// matrix. That is the next thing to wire up here.
+@address(0xDC00)
+export let cia1PortA: volatile<u8>;
+@address(0xDC01)
+export let cia1PortB: volatile<u8>;
+@address(0xDC02)
+export let cia1DirectionA: volatile<u8>;
+@address(0xDC03)
+export let cia1DirectionB: volatile<u8>;

package/src/input.8bs

@@ -0,0 +1,168 @@
+// @8bitscript/mega65/input — the MEGA65 behind @8bitscript/input.
+//
+// Named by "8bitscript".exports["./input"] in this package's package.json,
+// and by "8bitscript".entry.mega65 in @8bitscript/input's, so a portable
+// program writes
+//
+//     import { input } from "@8bitscript/input";
+//
+// and gets this file on a MEGA65.
+//
+// ---- a C64's matrix on a machine that is not a C64 -----------------------
+//
+// For input, this machine is a C64: CIA1 at $DC00, eight columns by eight
+// rows, the same key in the same place, the two control ports on the same
+// bits. So the codes below are @8bitscript/c64/keys's codes, and the scan
+// is the C64's — write a byte with one 0 bit to port A to select a column,
+// read port B for that column's eight keys.
+//
+//   - **left / right / up / down** — the C64-shaped cursor keys, with
+//     SHIFT reversing each, or'd with a joystick in port 2.
+//   - **confirm** — RETURN, or fire. **cancel** — RUN/STOP.
+//
+// **What this leaves on the table is most of the keyboard.** A MEGA65 has
+// full-travel keys a C64 never had — four dedicated cursor keys, **ALT**,
+// CAPS LOCK, NO SCROLL, HELP — presented through the machine's own
+// registers rather than through this matrix. Reading them is the next
+// thing to do here, and it would make this the machine where a menu takes
+// ALT+letter. Until then a MEGA65 navigates exactly like a C64, which is
+// correct but is less than the hardware offers, and that is worth knowing
+// rather than discovering.
+//
+// **No mouse.** This package's hardware catalog has no options at all yet,
+// so `input.mouse` is false and there is nothing to detect. A 1351 on a
+// MEGA65 would be the C64's driver against these same registers.
+import { cia1PortA, cia1PortB, cia1DirectionA, cia1DirectionB } from "./index.8bs";
+
+// The C64 matrix's codes, for the keys this file maps.
+namespace Key {
+    const RETURN: utinyint = 1;
+    const CURSOR_RIGHT: utinyint = 2; // shifted: cursor left
+    const CURSOR_DOWN: utinyint = 7; // shifted: cursor up
+    const SHIFT_LEFT: utinyint = 15;
+    const SHIFT_RIGHT: utinyint = 52;
+    const STOP: utinyint = 63; // RUN/STOP
+}
+
+const COLUMN_SELECT: array<utinyint, 8> = [254, 253, 251, 247, 239, 223, 191, 127];
+const ROW_BIT: array<utinyint, 8> = [1, 2, 4, 8, 16, 32, 64, 128];
+
+let matrix: array<utinyint, 8>;
+
+namespace Edge {
+    const LEFT: utinyint = 1;
+    const RIGHT: utinyint = 2;
+    const UP: utinyint = 4;
+    const DOWN: utinyint = 8;
+    const CONFIRM: utinyint = 16;
+    const CANCEL: utinyint = 32;
+}
+
+let held: utinyint = 0;
+let before: utinyint = 0;
+let began: utinyint = 0;
+
+// Is this key down in the last scan?
+function keyDown(key: utinyint): bool {
+    return (matrix[key >> 3] & ROW_BIT[key & 7]) != 0;
+}
+
+export namespace input {
+
+    // Nothing to set up: no pointer to give a ceiling to.
+    function begin(): void {
+    }
+
+    function poll(): void {
+        cia1DirectionA = 0xFF;
+        cia1DirectionB = 0x00;
+        for (let column: utinyint = 0; column < 8; column++) {
+            cia1PortA = COLUMN_SELECT[column];
+            matrix[column] = cia1PortB ^ 0xFF;
+        }
+        cia1PortA = 0xFF;
+        // Port A back at $FF is what makes port B read as joystick 1 and
+        // port A as joystick 2, exactly as on a C64.
+        let stick: utinyint = (cia1PortA ^ 0xFF) & 0x1F;
+
+        before = held;
+        held = 0;
+
+        let shifted: bool = keyDown(Key.SHIFT_LEFT) || keyDown(Key.SHIFT_RIGHT);
+        if (keyDown(Key.CURSOR_RIGHT)) {
+            if (shifted) {
+                held = held | Edge.LEFT;
+            } else {
+                held = held | Edge.RIGHT;
+            }
+        }
+        if (keyDown(Key.CURSOR_DOWN)) {
+            if (shifted) {
+                held = held | Edge.UP;
+            } else {
+                held = held | Edge.DOWN;
+            }
+        }
+        if (keyDown(Key.RETURN)) {
+            held = held | Edge.CONFIRM;
+        }
+        if (keyDown(Key.STOP)) {
+            held = held | Edge.CANCEL;
+        }
+
+        // The stick in port 2: up 1, down 2, left 4, right 8, fire 16.
+        if ((stick & 4) != 0) {
+            held = held | Edge.LEFT;
+        }
+        if ((stick & 8) != 0) {
+            held = held | Edge.RIGHT;
+        }
+        if ((stick & 1) != 0) {
+            held = held | Edge.UP;
+        }
+        if ((stick & 2) != 0) {
+            held = held | Edge.DOWN;
+        }
+        if ((stick & 16) != 0) {
+            held = held | Edge.CONFIRM;
+        }
+
+        began = held & (before ^ 0xFF);
+    }
+
+    function left(): bool {
+        return (began & Edge.LEFT) != 0;
+    }
+
+    function right(): bool {
+        return (began & Edge.RIGHT) != 0;
+    }
+
+    function up(): bool {
+        return (began & Edge.UP) != 0;
+    }
+
+    function down(): bool {
+        return (began & Edge.DOWN) != 0;
+    }
+
+    function confirm(): bool {
+        return (began & Edge.CONFIRM) != 0;
+    }
+
+    function cancel(): bool {
+        return (began & Edge.CANCEL) != 0;
+    }
+
+    function pointer(): bool {
+        return false;
+    }
+
+    function pointerCell(): usmallint {
+        return 0;
+    }
+
+    function pointerButton(): bool {
+        return false;
+    }
+}

package/src/pointer.8bs

@@ -0,0 +1,40 @@
+// @8bitscript/mega65/pointer — the MEGA65 behind @8bitscript/pointer.
+//
+// Every call here does nothing and `DRAWS` is false, and as with the C128
+// this is a missing driver rather than a missing capability: the VIC-IV is
+// a superset of the VIC-II, so the eight sprites are there (and more
+// besides), and the machine has control ports a 1351 fits.
+//
+// Two things are missing, in this order. **The input half:**
+// @8bitscript/mega65/input reads the keyboard and the C64's joystick
+// arrangement and reports no pointer, because packages/mega65's catalog
+// has no control-port options at all yet — no value to set
+// `#fact(input.mouse)` true, so nothing to fit and no fact to compile a
+// pointer in from. **Then the drawing half:** this package has no sprites
+// layer, so there is nothing for a file like @8bitscript/c64/pointer to
+// sit on.
+//
+// Worth knowing before either is written: this machine starts up with
+// interrupts off and at 40.5 MHz (see packages/mega65/AGENTS.md), so it
+// has cycles to spare for a pointer — the constraint here is entirely that
+// nobody has written the two layers, not the hardware.
+//
+// It costs the MEGA65 nothing meanwhile: `DRAWS` is a const and every
+// function is empty, so a program's `if (pointer.DRAWS)` folds away and
+// LLVM deletes the calls.
+export namespace pointer {
+
+    const DRAWS: bool = false;
+
+    function begin(): void {
+    }
+
+    function setColor(color: utinyint): void {
+    }
+
+    function update(): void {
+    }
+
+    function hide(): void {
+    }
+}

package/src/screen.8bs

@@ -0,0 +1,106 @@
+// @8bitscript/mega65/screen — the MEGA65's implementation of @8bitscript/screen.
+//
+// Named by "8bitscript".exports["./screen"] in this package's package.json,
+// and what
+//
+//     import { screen, BorderColor, BackgroundColor } from "@8bitscript/screen";
+//
+// resolves to when the build is for the MEGA65: @8bitscript/screen's entry
+// is keyed by machine and delegates here. Built on the registers
+// @8bitscript/mega65 itself exports, one layer up from them. Every machine's
+// screen.8bs exports this same surface, which is what lets a program import
+// it from @8bitscript/screen and never name the hardware.
+import { borderColor, backgroundColor } from "./index.8bs";
+
+// ---- the screen: border and background --------------------------------------
+//
+// Border and background have their own registers at the C64's addresses;
+// the VIC-IV's are 8 bits wide (256 palette entries), and the shared eight
+// names stay on 0-15 so a program's colour means the same thing everywhere.
+// The screen a build runs on is 80x25 at $0800 (see text.8bs), so a blank
+// clears 2000 cells.
+export namespace screen {
+    function setColors(border: u8, background: u8): void {
+        borderColor = border & 15;
+        backgroundColor = background & 15;
+    }
+
+    // `blank(border, background)`: every cell blank and both colours set —
+    // black when left off, or `BorderColor.KEEP` / `BackgroundColor.KEEP`
+    // to leave one as it is. `setBorder` and `setBackground` are one
+    // colour each, `setColors` the pair; `text.setColor` owns what the
+    // next print looks like.
+    function blank(border: utinyint = BorderColor.BLACK, background: utinyint = BackgroundColor.BLACK): void {
+        if (border != BorderColor.KEEP) {
+            screen.setBorder(border);
+        }
+        if (background != BackgroundColor.KEEP) {
+            screen.setBackground(background);
+        }
+        for (let cell: usmallint = 0; cell < 2000; cell++) {
+            memory.write(0x0800 + cell, 32); // 32: the space screen code
+        }
+    }
+
+    function setBackground(background: u8): void {
+        backgroundColor = background & 15;
+    }
+
+    function setBorder(border: u8): void {
+        borderColor = border & 15;
+    }
+}
+
+// ---- colour names ----------------------------------------------------------
+//
+// The same eight names every machine's screen.8bs exports — Black, White,
+// Red, Cyan, Purple, Green, Blue, Yellow — so a program can write
+// `screen.setColors(BorderColor.BLUE, BackgroundColor.BLACK)` through
+// @8bitscript/screen and get blue on every target; the values are this
+// machine's own. In the VIC-II-compatible view both registers take the
+// C64's sixteen colours in the C64's numbering, so both namespaces carry
+// all sixteen.
+
+export namespace BorderColor {
+    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;
+    const ORANGE: utinyint = 8;
+    const BROWN: utinyint = 9;
+    const LIGHT_RED: utinyint = 10;
+    const DARK_GREY: utinyint = 11;
+    const GREY: utinyint = 12;
+    const LIGHT_GREEN: utinyint = 13;
+    const LIGHT_BLUE: utinyint = 14;
+    const LIGHT_GREY: utinyint = 15;
+    // Not a colour: `blank(KEEP, ...)` leaves this one as it is. 255 is
+    // a value no register here takes.
+    const KEEP: utinyint = 255;
+}
+
+export namespace BackgroundColor {
+    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;
+    const ORANGE: utinyint = 8;
+    const BROWN: utinyint = 9;
+    const LIGHT_RED: utinyint = 10;
+    const DARK_GREY: utinyint = 11;
+    const GREY: utinyint = 12;
+    const LIGHT_GREEN: utinyint = 13;
+    const LIGHT_BLUE: utinyint = 14;
+    const LIGHT_GREY: utinyint = 15;
+    // Not a colour: `blank(KEEP, ...)` leaves this one as it is. 255 is
+    // a value no register here takes.
+    const KEEP: utinyint = 255;
+}

package/src/text.8bs

@@ -0,0 +1,175 @@
+// @8bitscript/mega65/text — the MEGA65'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 MEGA65. Built on the registers
+// @8bitscript/mega65 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, vicIIIControlA, VicIIIControl } from "./index.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. mega65.h names the default screen
+// character matrix directly: DEFAULT_SCREEN at $0800 — not the C64's $0400
+// — and in the MEGA65 mode a build runs in, that screen is 80x25, 2000
+// cells (LINESTEP 80, CHRCOUNT 80, H640 set: measured under xmega65, see
+// AGENTS.md; an earlier version of this file drew for 40 columns and
+// wrapped every second row onto the right half of the one above). Colour
+// RAM is at $D800 for cells 0-1023, and for cells 1024-1999 at
+// $DC00-$DFCF only while $D030's CRAM2K bit is set — otherwise those
+// addresses are the two CIAs — so prepare() sets that bit before a run.
+//
+// ---- 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 ran before,
+// a user's SHIFT+C= — so this package owns the choice rather than
+// inheriting one (LLVM-MOS's libc used to flip the machine to lower-case
+// before main() with a hidden CHR$(14); packages/backend-6502's
+// commodoreCharsetGuard() keeps that out of the link). putChar() selects
+// the upper-case set, every
+// call, through the memory pointer (see @8bitscript/mega65's
+// `memoryPointer` for the $24 it takes here): one register write, 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.
+namespace CharacterSet {
+    const UPPERCASE_SCREEN_AT_0800: utinyint = 0x24;
+}
+
+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()` 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, as on the C64. Colour RAM's
+// upper nibble is also an attribute field (blink, reverse) — keep it
+// clear, and invert by the ROM copy instead.
+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 {
+    memoryPointer = CharacterSet.UPPERCASE_SCREEN_AT_0800;
+    vicIIIControlA = VicIIIControl.COLOR_RAM_2K;
+}
+
+function place(cell: usmallint, code: utinyint): void {
+    memory.write(0x0800 + cell, toScreen(code));
+    memory.write(0xD800 + cell, currentColor & 15); // the upper nibble is attributes (blink, reverse) — keep it clear
+}
+
+// ---- 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 = 2000; // 80 columns x 25 rows
+    const COLUMNS: utinyint = 80; // cells per row, so cell = y * text.COLUMNS + x
+
+    function putChar(cell: usmallint, code: utinyint): void {
+        prepare();
+        memory.write(0x0800 + cell, toScreen(code));
+    }
+
+    function putColor(cell: usmallint, color: utinyint): void {
+        vicIIIControlA = VicIIIControl.COLOR_RAM_2K; // cells past 1023 live behind CRAM2K
+        memory.write(0xD800 + cell, color & 15);
+    }
+
+    function setColor(color: utinyint): void {
+        currentColor = color;
+    }
+
+    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.
+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;
+}