@8bitscript/c64 0.1.0

package/src/input.8bs

@@ -0,0 +1,269 @@
+// @8bitscript/c64/input — the C64 behind @8bitscript/input.
+//
+// Named by "8bitscript".exports["./input"] in this package's package.json,
+// and by "8bitscript".entry.c64 in @8bitscript/input's, so a portable
+// program writes
+//
+//     import { input } from "@8bitscript/input";
+//
+// and gets this file on a C64. Nothing here is C64-specific to a program:
+// it is the same ten calls on all nine machines, answered from whatever
+// this one has. The machine-level layers underneath — ./keyboard.8bs,
+// ./keys.8bs, ./joystick.8bs, ./mouse.8bs — stay available to a program
+// that wants the matrix itself.
+//
+// ---- what a direction means here ------------------------------------------
+//
+// A menu asks "did the user just press right", not "is right held down",
+// so every direction and button here is **edge-triggered**: true on the
+// one frame the press begins, false while it is held. That is what makes
+// a highlight step one item per press instead of racing across the bar,
+// and it is why `poll()` has to be called exactly once a frame — twice a
+// frame and every press is seen once and then swallowed.
+//
+// Three things can move the highlight on this machine, and all three are
+// or'd together, because a program should not care which the user reached
+// for:
+//
+//   - **The cursor keys.** The C64 has two, not four: `CURSOR_RIGHT` and
+//     `CURSOR_DOWN`, with SHIFT reversing each. So left is SHIFT plus the
+//     right key, which is what the machine actually has and what this file
+//     reports rather than pretending there are four keys.
+//   - **A joystick in port 2**, which is where every C64 game asked for
+//     one. Port 1 shares wires with the keyboard's rows, so a stick there
+//     types; port 2 is the one that does not fight the matrix.
+//   - **A 1351 mouse in port 1**, if this build was fitted with one — see
+//     below.
+//
+// RETURN or the joystick's fire button confirms; RUN/STOP cancels.
+//
+// ---- the mouse is a compile-time decision and a run-time answer -----------
+//
+// `#fact(input.mouse)` is false on a stock C64 and true for a build made
+// with `--hardware port1=mouse1351`. It is a `run` fact, so what it means
+// is "this build may use a mouse" — and that is exactly the two-stage
+// shape this machine needs:
+//
+//   - **Compiling.** `HAS_MOUSE` is a const, so `if (HAS_MOUSE)` is
+//     `if (false)` on a stock build and the pointer code below is never
+//     reached, never referenced, and never linked. A program that did not
+//     ask for a mouse pays nothing for one — not a byte of code, not a
+//     byte of the accumulator.
+//   - **Running.** A 1351 says nothing about itself except through the
+//     lines its movement arrives on, so even a build that asked for one
+//     has to find out whether one is plugged in. `pointer()` answers that,
+//     from ./mouse.8bs's probe, every frame.
+//
+// **The port assignment is this file's choice, not a fact.**
+// `input.mouse` is one flag and does not say which port the mouse is in.
+// This file reads the mouse in **port 1** and the joystick in **port 2**,
+// which is the arrangement C64 software settled on — a stick in the port
+// that does not fight the keyboard, a pointer in the one that does. A
+// program that needs it the other way round wants ./mouse.8bs directly.
+//
+// **The pointer is reported in cells, not pixels**, because that is the
+// unit @8bitscript/text works in and the unit a component hit-tests
+// against: `pointerCell()` is a flat cell index, the same number
+// `text.print()` takes. A 1351 count is about a pixel, so the accumulator
+// is limited to the screen in pixels and shifted down by the cell size.
+//
+// **Y is inverted in ./mouse.8bs**, not here. A 1351's Y counter runs
+// opposite the screen; `poll()` there swaps last and now on that axis so
+// `mouse.y()` is already in screen rows (0 at the top). This file only
+// shifts that number to a cell. Verified under x64sc (Studio, 2026-09-07):
+// applying Y with the same sign as X moved the arrow up when the mouse
+// moved down; inverting the delta, not `LIMIT_Y - y`, kept the rest
+// position in the top-left corner.
+import { Video } from "./geometry.8bs";
+import { keyboard } from "./keyboard.8bs";
+import { Key } from "./keys.8bs";
+import { joystick, Joystick } from "./joystick.8bs";
+import { mouse, Mouse } from "./mouse.8bs";
+
+// Was this build fitted with a mouse? Folded while compiling, so the whole
+// pointer half of this file is either present or absent, never tested.
+const HAS_MOUSE: bool = #fact(input.mouse);
+
+// The pointer's travel, in mouse counts — a count is about a pixel, and a
+// cell is 8 of them on this machine. The shift is written as a shift
+// rather than a divide by CELL_PIXELS because a 6502 has neither, and the
+// one the compiler can do without a helper routine is this one.
+const CELL_SHIFT: utinyint = 3; // 8 pixels a cell
+const LIMIT_X: usmallint = 319; // Video.COLUMNS * 8 - 1
+const LIMIT_Y: usmallint = 199; // Video.ROWS * 8 - 1
+
+// One bit per thing a program can ask about, so a frame's input is one
+// byte and an edge is one AND.
+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;
+    const BUTTON: utinyint = 64;
+}
+
+// What is held now, what was held at the last poll, and what began this
+// frame — `now & ~last`, written with the XOR the language has.
+let held: utinyint = 0;
+let before: utinyint = 0;
+let began: utinyint = 0;
+
+// Where the pointer is, in cells, and whether one is really there.
+let atCell: usmallint = 0;
+let havePointer: bool = false;
+
+export namespace input {
+
+    // Once, at start-up, before the first poll() — the input equivalent of
+    // screen.blank(). On this machine it gives the pointer its ceiling and
+    // points the SID at the mouse's port so the first poll() has something
+    // settled to read. On a build with no mouse it compiles to nothing at
+    // all, and on a machine with no pointer it is an empty function that
+    // costs a program one call it can write once and forget.
+    function begin(): void {
+        if (HAS_MOUSE) {
+            mouse.setLimits(LIMIT_X, LIMIT_Y);
+            mouse.select(Mouse.PORT_1);
+        }
+    }
+
+    // Everything this machine offers, gathered once. Call it once a frame,
+    // right after waitFrame(), and never twice.
+    //
+    // The order is forced by the hardware and is the whole reason this
+    // function exists rather than three calls in a program:
+    //
+    //   1. **Read the pots first.** They answer for the port `select()`
+    //      pointed the SID at during the *previous* poll — the converter
+    //      needs about half a millisecond to settle, and a frame is thirty
+    //      times that, so last frame's select is exactly what makes this
+    //      frame's reading mean something.
+    //   2. **Then the keyboard**, which drives all eight column lines and
+    //      leaves port A at $FF.
+    //   3. **Then the joysticks**, which need port A at $FF to read as
+    //      joysticks — which is the state the keyboard scan just left.
+    //   4. **Then point the SID back at the mouse's port**, for the read
+    //      at the top of the next frame.
+    function poll(): void {
+        if (HAS_MOUSE) {
+            mouse.poll();
+        }
+        keyboard.scan();
+        joystick.scan();
+
+        before = held;
+        held = 0;
+
+        // The two cursor keys and SHIFT, which is what "four directions"
+        // is on this keyboard.
+        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;
+        }
+
+        // The stick in port 2, or'd on top: same directions, same confirm.
+        let stick: utinyint = joystick.bits(Joystick.PORT_2);
+        if ((stick & Joystick.LEFT) != 0) {
+            held = held | Edge.LEFT;
+        }
+        if ((stick & Joystick.RIGHT) != 0) {
+            held = held | Edge.RIGHT;
+        }
+        if ((stick & Joystick.UP) != 0) {
+            held = held | Edge.UP;
+        }
+        if ((stick & Joystick.DOWN) != 0) {
+            held = held | Edge.DOWN;
+        }
+        if ((stick & Joystick.FIRE) != 0) {
+            held = held | Edge.CONFIRM;
+        }
+
+        if (HAS_MOUSE) {
+            havePointer = mouse.present();
+            if (havePointer) {
+                // Counts to cells. Y is already screen-space: ./mouse.8bs
+                // inverts the 1351's counter so 0 is the top row.
+                let column: usmallint = mouse.x() >> CELL_SHIFT;
+                let row: usmallint = mouse.y() >> CELL_SHIFT;
+                atCell = row * Video.COLUMNS + column;
+            }
+            // The mouse's buttons ride the port's ordinary joystick lines,
+            // so they are already in the snapshot taken above — read from
+            // there rather than from the live port, which by now has a
+            // keyboard column driven on it.
+            if ((joystick.bits(Joystick.PORT_1) & Joystick.FIRE) != 0) {
+                held = held | Edge.BUTTON;
+            }
+            // Point the SID at the mouse's port for the next frame's read.
+            // Last, because joystick.scan() puts port A back to $FF.
+            mouse.select(Mouse.PORT_1);
+        }
+
+        began = held & (before ^ 0xFF);
+    }
+
+    // The four directions, each true only on the frame its press began.
+    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;
+    }
+
+    // RETURN, or the stick's fire button.
+    function confirm(): bool {
+        return (began & Edge.CONFIRM) != 0;
+    }
+
+    // RUN/STOP.
+    function cancel(): bool {
+        return (began & Edge.CANCEL) != 0;
+    }
+
+    // Is a pointer really there? False on every stock build, where the
+    // question folds away entirely; on a build fitted with a mouse, this
+    // is ./mouse.8bs's probe answering every frame.
+    function pointer(): bool {
+        return havePointer;
+    }
+
+    // Where it is, as a flat cell index — the same unit text.print() takes.
+    // Meaningless unless pointer() is true.
+    function pointerCell(): usmallint {
+        return atCell;
+    }
+
+    // The pointer's main button, on the frame its press began.
+    function pointerButton(): bool {
+        return (began & Edge.BUTTON) != 0;
+    }
+}

package/src/joystick.8bs

@@ -0,0 +1,78 @@
+// @8bitscript/c64/joystick — the two control ports, one snapshot a frame.
+//
+// Named by "8bitscript".exports["./joystick"] in this package's package.json:
+//
+//     import { joystick, Joystick } from "@8bitscript/c64/joystick";
+//
+//     joystick.scan();
+//     if (joystick.left(Joystick.PORT_2)) { ... }
+//
+// Hardware-level, C64-only surface, like ./keyboard.8bs: the layer a
+// portable input capability will sit on. A digital joystick is five
+// switches to ground — up, down, left, right, fire — on CIA1: port 2 on
+// port A ($DC00) bits 0-4, port 1 on port B ($DC01) bits 0-4, a 0 bit
+// where a switch is closed. `scan()` reads both once a frame into a
+// snapshot with the bits inverted (1 = pushed) and everything else answers
+// from it.
+//
+// Port A has to be $FF for the read to mean the joystick: its bits are
+// the keyboard's column selects, and a selected column's keys would show
+// up in port B as joystick 1. `keyboard.scan()` leaves it so; `scan()`
+// writes it again anyway, so a program with no keyboard is right too. The
+// order once a frame is: waitFrame(), keyboard.scan(), joystick.scan().
+//
+// Port 2 is where a game reads its player, and where every C64 game asked
+// for the stick: port 1 shares wires with the keyboard's rows, so a stick
+// there "types" (the KERNAL's scan sees it — irrelevant here, interrupts
+// are off) and, the other way round, keys held down read as joystick 1
+// pushes. Port 2 shares the column lines, which a scan only drives for the
+// length of `keyboard.scan()`. Paddles and the 1351 mouse are the SID's
+// two A/D lines (`paddleX`/`paddleY` in ./index.8bs), not this file.
+import { cia1PortA, cia1PortB } from "./index.8bs";
+
+// The last scan: index 0 port 1, index 1 port 2; bits as in `Joystick`.
+let state: array<utinyint, 2>;
+
+export namespace Joystick {
+    const PORT_1: utinyint = 0;
+    const PORT_2: utinyint = 1;
+    const UP: utinyint = 1;
+    const DOWN: utinyint = 2;
+    const LEFT: utinyint = 4;
+    const RIGHT: utinyint = 8;
+    const FIRE: utinyint = 16;
+}
+
+export namespace joystick {
+    // Read both ports into the snapshot. Once a frame, after keyboard.scan().
+    function scan(): void {
+        cia1PortA = 0xFF;
+        state[0] = (cia1PortB ^ 0xFF) & 0x1F;
+        state[1] = (cia1PortA ^ 0xFF) & 0x1F;
+    }
+
+    // The five switches of one port as `Joystick.*` bits, 1 = pushed.
+    function bits(port: utinyint): utinyint {
+        return state[port];
+    }
+
+    function up(port: utinyint): bool {
+        return (state[port] & Joystick.UP) != 0;
+    }
+
+    function down(port: utinyint): bool {
+        return (state[port] & Joystick.DOWN) != 0;
+    }
+
+    function left(port: utinyint): bool {
+        return (state[port] & Joystick.LEFT) != 0;
+    }
+
+    function right(port: utinyint): bool {
+        return (state[port] & Joystick.RIGHT) != 0;
+    }
+
+    function fire(port: utinyint): bool {
+        return (state[port] & Joystick.FIRE) != 0;
+    }
+}

package/src/keyboard.8bs

@@ -0,0 +1,84 @@
+// @8bitscript/c64/keyboard — the C64's keyboard matrix, one snapshot a frame.
+//
+// Named by "8bitscript".exports["./keyboard"] in this package's package.json:
+//
+//     import { keyboard } from "@8bitscript/c64/keyboard";
+//     import { Key } from "@8bitscript/c64/keys";
+//
+// This is hardware-level, C64-only surface — the layer the portable input
+// capability is built on: `@8bitscript/c64/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 C64-specific.
+// It keeps no key buffer and decodes no PETSCII; it answers "is this key
+// down now", which is what a game loop asks.
+//
+// ---- how the matrix works -----------------------------------------------
+//
+// Eight columns by eight rows on CIA1, no diodes. Writing a byte with one
+// 0 bit to port A ($DC00) selects that column; port B ($DC01) then reads
+// the column's eight keys, a 0 bit where a key is down. The KERNAL's own
+// scan (SCNKEY, from its 60 Hz timer IRQ) drives the same two ports, and
+// would land its column select between this scan's write and read — which
+// is one reason the frame runtime starts a C64 program with `sei`
+// (FRAME_SYNC.c64 in packages/backend-6502): from the first waitFrame()
+// on, only this program touches CIA1. `scan()` writes the two direction
+// registers itself (A out, B in — the KERNAL's setting, made sure of), so
+// it does not depend on what ran before.
+//
+// `scan()` reads all eight columns into `state`, once a frame, right after
+// waitFrame() returns; every question after that reads the snapshot.
+// Sixteen port accesses, well under 200 cycles of a 17000-cycle NTSC frame.
+// It leaves port A at $FF — no column selected — which is the state
+// @8bitscript/c64/joystick needs to read the ports as joysticks; call
+// `keyboard.scan()` first and `joystick.scan()` second, both once a frame.
+//
+// The joystick lines are wired in parallel with the matrix: a stick in
+// port 1 pulls rows (a pushed direction reads as a key in every column),
+// a stick in port 2 pulls columns (an extra column selected, its keys
+// showing up under another's). A program that uses the keyboard and a
+// joystick at once lives with that, as every C64 game did — port 2 for
+// the stick, and keys that a stick cannot fake (a game that pauses on
+// RUN/STOP should expect it while the port-1 stick is pushed up: row 7).
+// 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 { cia1PortA, cia1PortB, cia1DirectionA, cia1DirectionB } from "./index.8bs";
+
+// The last scan, one byte per column, a 1 bit where a key is down (the
+// port's active-low rows inverted once, here, so nothing else has to
+// think about it). All zero until the first scan.
+let state: array<utinyint, 8>;
+
+// The column-select byte for each column, and the row masks — indexed
+// rather than shifted, as `1 << n` with a variable n is a loop on the 6502.
+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];
+
+export namespace keyboard {
+    const COLUMNS: utinyint = 8;
+    const ROWS: utinyint = 8;
+
+    // Read all eight columns into the snapshot. Once a frame, right after
+    // waitFrame(), before joystick.scan().
+    function scan(): void {
+        cia1DirectionA = 0xFF;
+        cia1DirectionB = 0x00;
+        for (let column: utinyint = 0; column < 8; column++) {
+            cia1PortA = COLUMN_SELECT[column];
+            state[column] = cia1PortB ^ 0xFF;
+        }
+        cia1PortA = 0xFF;
+    }
+
+    // Is this key down in the last scan? `key` is a `Key.*` value from
+    // @8bitscript/c64/keys — `column * 8 + row` in the matrix.
+    function pressed(key: utinyint): bool {
+        return (state[key >> 3] & ROW_BIT[key & 7]) != 0;
+    }
+
+    // The last scan's eight rows of one column, a 1 bit per key down:
+    // for code that wants a whole column at once (an "any key" test over
+    // all eight, a ghosting check).
+    function column(index: utinyint): utinyint {
+        return state[index];
+    }
+}

package/src/keys.8bs

@@ -0,0 +1,103 @@
+// @8bitscript/c64/keys — the keyboard matrix, key by key.
+//
+// Named by "8bitscript".exports["./keys"] in this package's package.json, for
+//
+//     import { keyboard } from "@8bitscript/c64/keyboard";
+//     import { Key } from "@8bitscript/c64/keys";
+//
+//     if (keyboard.pressed(Key.SPACE)) { ... }
+//
+// Each value is `column * 8 + row` in CIA1's matrix (see ./keyboard.8bs):
+// the column is the bit of port A ($DC00) driven low to select it, the row
+// the bit of port B ($DC01) that reads low. Every C64 ever made has this
+// one matrix — the C64C, SX-64, and the rest moved keys on the case, not
+// on the wires — so unlike the PET there is one table and no profile twin.
+// Two keys are not in it: RESTORE is wired to the CPU's NMI line, and
+// SHIFT LOCK is the left SHIFT key's own wire, held down.
+//
+// A key that also exists on the PET has the same name here — letters,
+// `DIGIT_n`, SPACE, RETURN, STOP, HOME, DELETE, the cursor keys, both
+// shifts, the arrows and the shared punctuation — so a program that
+// sticks to those names reads the same on both machines' keyboard layers.
+//
+// Source: the matrix in the Programmer's Reference Guide and every C64
+// reference since, checked here key for key against VICE's own positional
+// keyboard map for the C64, /opt/homebrew/share/vice/C64/gtk3_pos.vkm
+// (each line there is `keysym column row shiftflag`, in the same
+// numbering as this file); packages/compiler/test/c64-keys.test.mjs repeats
+// that check when the file is present.
+
+export namespace Key {
+    // column 0
+    const DELETE: utinyint = 0; // INST/DEL
+    const RETURN: utinyint = 1;
+    const CURSOR_RIGHT: utinyint = 2; // shifted: cursor left
+    const F7: utinyint = 3; // shifted: F8
+    const F1: utinyint = 4; // shifted: F2
+    const F3: utinyint = 5; // shifted: F4
+    const F5: utinyint = 6; // shifted: F6
+    const CURSOR_DOWN: utinyint = 7; // shifted: cursor up
+    // column 1
+    const DIGIT_3: utinyint = 8;
+    const W: utinyint = 9;
+    const A: utinyint = 10;
+    const DIGIT_4: utinyint = 11;
+    const Z: utinyint = 12;
+    const S: utinyint = 13;
+    const E: utinyint = 14;
+    const SHIFT_LEFT: utinyint = 15; // also SHIFT LOCK
+    // column 2
+    const DIGIT_5: utinyint = 16;
+    const R: utinyint = 17;
+    const D: utinyint = 18;
+    const DIGIT_6: utinyint = 19;
+    const C: utinyint = 20;
+    const F: utinyint = 21;
+    const T: utinyint = 22;
+    const X: utinyint = 23;
+    // column 3
+    const DIGIT_7: utinyint = 24;
+    const Y: utinyint = 25;
+    const G: utinyint = 26;
+    const DIGIT_8: utinyint = 27;
+    const B: utinyint = 28;
+    const H: utinyint = 29;
+    const U: utinyint = 30;
+    const V: utinyint = 31;
+    // column 4
+    const DIGIT_9: utinyint = 32;
+    const I: utinyint = 33;
+    const J: utinyint = 34;
+    const DIGIT_0: utinyint = 35;
+    const M: utinyint = 36;
+    const K: utinyint = 37;
+    const O: utinyint = 38;
+    const N: utinyint = 39;
+    // column 5
+    const PLUS: utinyint = 40;
+    const P: utinyint = 41;
+    const L: utinyint = 42;
+    const MINUS: utinyint = 43;
+    const PERIOD: utinyint = 44;
+    const COLON: utinyint = 45;
+    const AT: utinyint = 46;
+    const COMMA: utinyint = 47;
+    // column 6
+    const POUND: utinyint = 48; // £
+    const ASTERISK: utinyint = 49;
+    const SEMICOLON: utinyint = 50;
+    const HOME: utinyint = 51; // CLR/HOME
+    const SHIFT_RIGHT: utinyint = 52;
+    const EQUALS: utinyint = 53;
+    const UP_ARROW: utinyint = 54;
+    const SLASH: utinyint = 55;
+    // column 7
+    const DIGIT_1: utinyint = 56;
+    const LEFT_ARROW: utinyint = 57;
+    const CONTROL: utinyint = 58;
+    const DIGIT_2: utinyint = 59;
+    const SPACE: utinyint = 60;
+    const COMMODORE: utinyint = 61; // the C= key
+    const Q: utinyint = 62;
+    const STOP: utinyint = 63; // RUN/STOP
+}