@8bitscript/pet 0.1.0

package/src/input.8bs

@@ -0,0 +1,135 @@
+// @8bitscript/pet/input — the PET behind @8bitscript/input.
+//
+// Named by "8bitscript".exports["./input"] in this package's package.json,
+// and by "8bitscript".entry.pet in @8bitscript/input's, so a portable
+// program writes
+//
+//     import { input } from "@8bitscript/input";
+//
+// and gets this file on a PET. The matrix itself is ./keyboard.8bs with
+// ./keys.8bs, which stay available to a program that wants a key this file
+// does not map.
+//
+// ---- a keyboard and nothing else -----------------------------------------
+//
+// The PET is the machine with the least to offer this surface, and saying
+// so plainly is the job. There are **no control ports** — no joystick, no
+// paddles, no mouse, nothing to plug in — because the machine predates the
+// idea. `pointer()` is a constant false, and so every `if
+// (input.pointer())` in a component folds away to nothing here.
+//
+// What there is is a keyboard, and it has the two cursor keys the
+// Commodore machines all have rather than four: `CURSOR_RIGHT` and
+// `CURSOR_DOWN`, each reversed by SHIFT. So left is SHIFT plus the right
+// key. That is what the machine has, and this file reports it rather than
+// pretending otherwise.
+//
+//   - **left / right / up / down** — the two cursor keys, with SHIFT.
+//   - **confirm** — RETURN.
+//   - **cancel** — RUN/STOP.
+//
+// ---- edges, not levels ---------------------------------------------------
+//
+// Every answer is **edge-triggered**: true on the one frame the press
+// begins, false while it is held. `poll()` must be called exactly once a
+// frame, right after waitFrame().
+//
+// One thing worth knowing about this keyboard specifically: the PET's
+// matrix is read a row at a time and has the same ghosting every
+// undiodedmatrix does — three keys down can read as four. Two keys are
+// always safe, and SHIFT plus a cursor key is two.
+import { keyboard } from "./keyboard.8bs";
+import { Key } from "./keys.8bs";
+
+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;
+
+export namespace input {
+
+    // Nothing to set up: there is no pointer to give a ceiling to and the
+    // matrix needs no configuration. Here so a program written for nine
+    // machines calls the same thing on all of them.
+    function begin(): void {
+    }
+
+    // Snapshot the matrix and work out what began this frame. Once a
+    // frame, right after waitFrame().
+    function poll(): void {
+        keyboard.scan();
+
+        before = held;
+        held = 0;
+
+        let shifted: bool = keyboard.pressed(Key.SHIFT_LEFT) || keyboard.pressed(Key.SHIFT_RIGHT);
+        if (keyboard.pressed(Key.CURSOR_RIGHT)) {
+            if (shifted) {
+                held = held | Edge.LEFT;
+            } else {
+                held = held | Edge.RIGHT;
+            }
+        }
+        if (keyboard.pressed(Key.CURSOR_DOWN)) {
+            if (shifted) {
+                held = held | Edge.UP;
+            } else {
+                held = held | Edge.DOWN;
+            }
+        }
+        if (keyboard.pressed(Key.RETURN)) {
+            held = held | Edge.CONFIRM;
+        }
+        if (keyboard.pressed(Key.STOP)) {
+            held = held | Edge.CANCEL;
+        }
+
+        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;
+    }
+
+    // No control ports on this machine, so no pointer — a constant, not a
+    // measurement.
+    function pointer(): bool {
+        return false;
+    }
+
+    function pointerCell(): usmallint {
+        return 0;
+    }
+
+    function pointerButton(): bool {
+        return false;
+    }
+}

package/src/keyboard.8bs

@@ -0,0 +1,72 @@
+// @8bitscript/pet/keyboard — the PET's keyboard matrix, one snapshot a frame.
+//
+// Named by "8bitscript".exports["./keyboard"] in this package's package.json:
+//
+//     import { keyboard } from "@8bitscript/pet/keyboard";
+//     import { Key } from "@8bitscript/pet/keys";
+//
+// This is hardware-level, PET-only surface — the layer the portable input
+// capability is built on: `@8bitscript/pet/input` reads this file and
+// @8bitscript/input resolves to that, the way ./text.8bs is the layer
+// under @8bitscript/text. Importing it makes a program PET-specific.
+//
+// ---- how the matrix works -----------------------------------------------
+//
+// Ten rows by eight columns, no diodes. Writing a row number 0-9 to PIA1
+// port A ($E810) selects that row; PIA1 port B ($E812) then reads its eight
+// keys, a 0 bit where a key is down. A program that calls waitFrame()
+// anywhere — one scanning once a frame does — runs with interrupts off from
+// start-up (FRAME_SYNC.pet's `sei`, in the frame prologue the backend
+// emits for it), so the KERNAL's own scan is not running against this one.
+// A program with no waitFrame() at all still has the KERNAL IRQ alive and
+// selecting rows of its own sixty times a second; scan() there would read
+// a row it did not select. This package keeps no key buffer and decodes no
+// PETSCII; it answers "is this key down now", which is what a game loop asks.
+//
+// Reading $E812 has a side effect: it clears the retrace flag the frame
+// runtime waits on (see `pia1PortB` in ./index.8bs). So the matrix is read
+// exactly once a frame, all ten rows into `state`, by `keyboard.scan()`
+// — called right after waitFrame() returns, when the edge was just
+// consumed and the next is a whole frame away — and every question after
+// that reads the snapshot, never the port. Ten writes and ten reads, about
+// 200 cycles of a 20000-cycle frame.
+//
+// Ghosting: three keys down can read as four (any three corners of a
+// rectangle in the matrix light the fourth). Two keys are always safe.
+import { pia1PortA, pia1PortB } from "./index.8bs";
+
+// The last scan, one byte per row, a 1 bit where a key is down (the port's
+// active-low columns inverted once, here, so nothing else has to think
+// about it). All zero until the first scan.
+let state: array<utinyint, 10>;
+
+// Column 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 COLUMN_BIT: array<utinyint, 8> = [1, 2, 4, 8, 16, 32, 64, 128];
+
+export namespace keyboard {
+    const ROWS: utinyint = 10;
+    const COLUMNS: utinyint = 8;
+
+    // Read all ten rows into the snapshot. Once a frame, right after
+    // waitFrame().
+    function scan(): void {
+        for (let row: utinyint = 0; row < 10; row++) {
+            pia1PortA = row;
+            state[row] = pia1PortB ^ 0xFF;
+        }
+    }
+
+    // Is this key down in the last scan? `key` is a `Key.*` value from
+    // @8bitscript/pet/keys — `row * 8 + column` in the profile's matrix.
+    function pressed(key: utinyint): bool {
+        return (state[key >> 3] & COLUMN_BIT[key & 7]) != 0;
+    }
+
+    // The last scan's eight columns of one row, a 1 bit per key down:
+    // for code that wants a whole row at once (a matrix ghosting check,
+    // an "any key" test over all ten).
+    function row(index: utinyint): utinyint {
+        return state[index];
+    }
+}

package/src/keys.8bs

@@ -0,0 +1,120 @@
+// @8bitscript/pet/keys — the keyboard matrix, key by key: graphics keyboard.
+//
+// Named by "8bitscript".exports["./keys"] in this package's package.json, for
+//
+//     import { keyboard } from "@8bitscript/pet/keyboard";
+//     import { Key } from "@8bitscript/pet/keys";
+//
+//     if (keyboard.pressed(Key.SPACE)) { ... }
+//
+// Each value is `row * 8 + column` in PIA1's matrix (see ./keyboard.8bs),
+// so a build for a profile reads that profile's table: this file is the
+// **graphics** keyboard of the 2001, 3xxx and 4xxx (calculator-style
+// keypad digits, the symbol row `! " # $ % & ' ( ) ←` above the letters,
+// every character unshifted), and `keys.pet.8032.8bs` beside it is the
+// **business** keyboard the 8032 has (typewriter layout: digits on the
+// top row, a numeric keypad, TAB, ESC, RPT). The two matrices wire the
+// same letters to different rows, which is exactly why the table is the
+// profile's and a program names keys, never numbers.
+//
+// A key that exists on both keyboards has the same name in both files —
+// letters, `DIGIT_n`, SPACE, RETURN, STOP, HOME, DELETE, the cursor keys,
+// both shifts, REVERSE, the arrows and the shared punctuation — so a
+// program that sticks to those builds for every PET. Names that exist
+// only here (the symbol row: EXCLAMATION, HASH, ... EQUALS) or only on
+// the business keyboard (KEYPAD_n, TAB, ESCAPE, REPEAT) are that
+// keyboard's alone, and an 8032 build of a program using one stops at
+// the import with "no member" — which is the right time to find out.
+//
+// Source: the matrix every PET reference gives for the graphics keyboard,
+// checked here key for key against VICE's own positional map for it,
+// /opt/homebrew/share/vice/PET/gtk3_grus_pos.vkm (each line there is
+// `keysym row column shiftflag`); packages/compiler/test/pet-keys.test.mjs
+// repeats that check when the file is present. Row 0 is `$E810 = 0`,
+// column 0 is PB0. A row's missing columns (1,5 and so on) have no key.
+
+export namespace Key {
+    // row 0
+    const EXCLAMATION: utinyint = 0;
+    const HASH: utinyint = 1;
+    const PERCENT: utinyint = 2;
+    const AMPERSAND: utinyint = 3;
+    const PAREN_LEFT: utinyint = 4;
+    const LEFT_ARROW: utinyint = 5; // the back-arrow key, top row right
+    const HOME: utinyint = 6; // CLR/HOME
+    const CURSOR_RIGHT: utinyint = 7; // shifted: cursor left
+    // row 1
+    const QUOTE: utinyint = 8;
+    const DOLLAR: utinyint = 9;
+    const APOSTROPHE: utinyint = 10;
+    const PAREN_RIGHT: utinyint = 11;
+    const BACKSLASH: utinyint = 12;
+    const CURSOR_DOWN: utinyint = 14; // shifted: cursor up
+    const DELETE: utinyint = 15; // INST/DEL
+    // row 2
+    const Q: utinyint = 16;
+    const E: utinyint = 17;
+    const T: utinyint = 18;
+    const U: utinyint = 19;
+    const O: utinyint = 20;
+    const UP_ARROW: utinyint = 21;
+    const DIGIT_7: utinyint = 22; // keypad
+    const DIGIT_9: utinyint = 23;
+    // row 3
+    const W: utinyint = 24;
+    const R: utinyint = 25;
+    const Y: utinyint = 26;
+    const I: utinyint = 27;
+    const P: utinyint = 28;
+    const DIGIT_8: utinyint = 30;
+    const SLASH: utinyint = 31;
+    // row 4
+    const A: utinyint = 32;
+    const D: utinyint = 33;
+    const G: utinyint = 34;
+    const J: utinyint = 35;
+    const L: utinyint = 36;
+    const DIGIT_4: utinyint = 38;
+    const DIGIT_6: utinyint = 39;
+    // row 5
+    const S: utinyint = 40;
+    const F: utinyint = 41;
+    const H: utinyint = 42;
+    const K: utinyint = 43;
+    const COLON: utinyint = 44;
+    const DIGIT_5: utinyint = 46;
+    const ASTERISK: utinyint = 47;
+    // row 6
+    const Z: utinyint = 48;
+    const C: utinyint = 49;
+    const B: utinyint = 50;
+    const M: utinyint = 51;
+    const SEMICOLON: utinyint = 52;
+    const RETURN: utinyint = 53;
+    const DIGIT_1: utinyint = 54;
+    const DIGIT_3: utinyint = 55;
+    // row 7
+    const X: utinyint = 56;
+    const V: utinyint = 57;
+    const N: utinyint = 58;
+    const COMMA: utinyint = 59;
+    const QUESTION: utinyint = 60;
+    const DIGIT_2: utinyint = 62;
+    const PLUS: utinyint = 63;
+    // row 8
+    const SHIFT_LEFT: utinyint = 64;
+    const AT: utinyint = 65;
+    const BRACKET_RIGHT: utinyint = 66;
+    const GREATER: utinyint = 68;
+    const SHIFT_RIGHT: utinyint = 69;
+    const DIGIT_0: utinyint = 70;
+    const MINUS: utinyint = 71;
+    // row 9
+    const REVERSE: utinyint = 72; // RVS
+    const BRACKET_LEFT: utinyint = 73;
+    const SPACE: utinyint = 74;
+    const LESS: utinyint = 75;
+    const STOP: utinyint = 76; // RUN/STOP
+    const PERIOD: utinyint = 78;
+    const EQUALS: utinyint = 79;
+}

package/src/keys.pet.8032.8bs

@@ -0,0 +1,100 @@
+// @8bitscript/pet/keys — the keyboard matrix, key by key: business keyboard.
+//
+// The 8032 profile's version of keys.8bs (see that file for how the two
+// tables relate and which names both share). This is the **business**
+// keyboard of the 8032 (and the 4032B/3032B, which are not profiles):
+// typewriter layout with the digits on the top row, a numeric keypad of
+// its own, TAB, ESC and RPT, and the symbols `! " # ...` reached with
+// SHIFT rather than as keys of their own — so this table has KEYPAD_n
+// and no EXCLAMATION. Same encoding, `row * 8 + column` in PIA1's matrix.
+//
+// Source: the business matrix the PET references give, checked key for
+// key against VICE's positional map for the 8032, /opt/homebrew/share/
+// vice/PET/gtk3_buuk_pos.vkm — the UK business layout, which is the one
+// xpet's 8032 model loads. The US business keyboard is wired to the same
+// matrix in every reference consulted, but has not been checked here.
+
+export namespace Key {
+    // row 0
+    const DIGIT_2: utinyint = 0;
+    const DIGIT_5: utinyint = 1;
+    const DIGIT_8: utinyint = 2;
+    const MINUS: utinyint = 3; // shifted: =
+    const KEYPAD_8: utinyint = 4;
+    const CURSOR_RIGHT: utinyint = 5; // shifted: cursor left
+    // row 1
+    const DIGIT_1: utinyint = 8;
+    const DIGIT_4: utinyint = 9;
+    const DIGIT_7: utinyint = 10;
+    const DIGIT_0: utinyint = 11;
+    const KEYPAD_7: utinyint = 12;
+    const UP_ARROW: utinyint = 13;
+    const KEYPAD_9: utinyint = 15;
+    // row 2
+    const ESCAPE: utinyint = 16;
+    const S: utinyint = 17;
+    const F: utinyint = 18;
+    const H: utinyint = 19;
+    const BRACKET_RIGHT: utinyint = 20;
+    const K: utinyint = 21;
+    const SEMICOLON: utinyint = 22; // shifted: +
+    const KEYPAD_5: utinyint = 23;
+    // row 3
+    const A: utinyint = 24;
+    const D: utinyint = 25;
+    const G: utinyint = 26;
+    const J: utinyint = 27;
+    const RETURN: utinyint = 28;
+    const L: utinyint = 29;
+    const AT: utinyint = 30;
+    const KEYPAD_6: utinyint = 31;
+    // row 4
+    const TAB: utinyint = 32;
+    const W: utinyint = 33;
+    const R: utinyint = 34;
+    const Y: utinyint = 35;
+    const BACKSLASH: utinyint = 36;
+    const I: utinyint = 37;
+    const P: utinyint = 38;
+    const DELETE: utinyint = 39; // INST/DEL
+    // row 5
+    const Q: utinyint = 40;
+    const E: utinyint = 41;
+    const T: utinyint = 42;
+    const U: utinyint = 43;
+    const CURSOR_DOWN: utinyint = 44; // shifted: cursor up
+    const O: utinyint = 45;
+    const BRACKET_LEFT: utinyint = 46;
+    const KEYPAD_4: utinyint = 47;
+    // row 6
+    const SHIFT_LEFT: utinyint = 48;
+    const C: utinyint = 49;
+    const B: utinyint = 50;
+    const PERIOD: utinyint = 51;
+    const KEYPAD_PERIOD: utinyint = 52;
+    const SHIFT_RIGHT: utinyint = 54;
+    const KEYPAD_3: utinyint = 55;
+    // row 7
+    const Z: utinyint = 56;
+    const V: utinyint = 57;
+    const N: utinyint = 58;
+    const COMMA: utinyint = 59;
+    const KEYPAD_0: utinyint = 60;
+    const REPEAT: utinyint = 62; // RPT
+    const KEYPAD_2: utinyint = 63;
+    // row 8
+    const REVERSE: utinyint = 64; // RVS
+    const X: utinyint = 65;
+    const SPACE: utinyint = 66;
+    const M: utinyint = 67;
+    const HOME: utinyint = 68; // CLR/HOME
+    const SLASH: utinyint = 70; // shifted: ?
+    const KEYPAD_1: utinyint = 71;
+    // row 9
+    const LEFT_ARROW: utinyint = 72; // the back-arrow key, top row left
+    const DIGIT_3: utinyint = 73;
+    const DIGIT_6: utinyint = 74;
+    const DIGIT_9: utinyint = 75;
+    const STOP: utinyint = 76; // RUN/STOP
+    const COLON: utinyint = 77; // shifted: *
+}

package/src/pointer.8bs

@@ -0,0 +1,39 @@
+// @8bitscript/pet/pointer — the PET behind @8bitscript/pointer, and the
+// one machine of the nine where "no cursor" is the final answer rather
+// than a gap.
+//
+// Every call here does nothing and `DRAWS` is false, because **the PET has
+// no control ports at all** — no mouse, no joystick, no paddles, nothing to
+// point with — which is why @8bitscript/pet/input answers `pointer()`
+// false too. There is nothing to draw an arrow for, and a machine with
+// nothing to point cannot be given a pointer by writing more code.
+//
+// It still has to exist: Studio and every other portable program links
+// @8bitscript/pointer, so a missing entry is not a program without a
+// cursor, it is a program that does not build for the PET.
+//
+// It costs the PET nothing. `DRAWS` is a const and every function is
+// empty, so a program's `if (pointer.DRAWS)` folds away and LLVM deletes
+// the calls — the same zero the X16's input layer measures at (see
+// packages/input/AGENTS.md).
+//
+// Were a pointer ever wanted here it would need hardware the machine does
+// not have and this repository has no driver for: the light pen on the
+// 8296's user port, or a KoalaPad. Both would be a new hardware option in
+// packages/pet's catalog first, and neither would be a mouse.
+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,94 @@
+// @8bitscript/pet/screen — the PET'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 PET: @8bitscript/screen's entry is
+// keyed by machine and delegates here. 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.
+//
+// The PET is a monochrome machine — green or white phosphor, whatever the
+// monitor is, with no colour hardware at all. `screen.setColors()` still
+// exists and still links, because the point of the portable surface (see
+// @8bitscript/vic20 and @8bitscript/c64's screen.8bs) is that a single
+// portable program builds for every target without per-target branches in
+// user code — but here it is deliberately inert: there is no register to
+// write, so setColors() does nothing observable. A program that only ever
+// sets colours through the portable surface still builds and runs correctly
+// everywhere; it simply never shows a border or background tint on a PET,
+// because a PET cannot show one.
+//
+// `blank()` is the one thing here that touches the screen, and how much
+// screen there is depends on the model: 1000 cells on the 40-column PETs,
+// 2000 on the 80-column 8032. That number comes from ./geometry.8bs, whose
+// 8032 version is chosen by the build's profile — see that file.
+import { Video } from "./geometry.8bs";
+
+export namespace screen {
+    function setColors(border: u8, background: u8): void {
+        // Deliberately empty — see the file comment above.
+    }
+
+    // `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 < Video.CELL_COUNT; cell++) {
+            memory.write(0x8000 + cell, 32); // 32: the space screen code
+        }
+    }
+
+    function setBackground(background: u8): void {
+        // Deliberately empty — see the file comment above.
+    }
+
+    function setBorder(border: u8): void {
+        // Deliberately empty — see the file comment above.
+    }
+}
+
+// ---- colour names ----------------------------------------------------------
+//
+// The same eight names every machine's screen.8bs exports, so a program that
+// says `screen.setColors(BorderColor.BLUE, BackgroundColor.BLACK)` through
+// @8bitscript/screen still links here. The values are the C64's numbering,
+// for want of any of the PET's own — nothing reads them.
+
+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;
+    // 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;
+    // Not a colour: `blank(KEEP, ...)` leaves this one as it is. 255 is
+    // a value no register here takes.
+    const KEEP: utinyint = 255;
+}