@8bitscript/atari8 0.1.0

package/src/joystick.8bs

@@ -0,0 +1,147 @@
+// @8bitscript/atari8/joystick — the control ports, one snapshot a frame.
+//
+// Named by "8bitscript".exports["./joystick"] in this package's package.json:
+//
+//     import { joystick, Joystick } from "@8bitscript/atari8/joystick";
+//
+//     joystick.scan();
+//     if (joystick.left(Joystick.PORT_1)) { ... }
+//
+// Hardware-level, Atari-only surface, the layer a portable input capability
+// will sit on — the same shape as @8bitscript/c64/joystick, deliberately:
+// `scan()` once a frame into a snapshot, then `up`/`down`/`left`/`right`/
+// `fire` answering from it, and the same `Joystick.UP`/`DOWN`/`LEFT`/
+// `RIGHT`/`FIRE` bit values. That is not a coincidence to be tidied away
+// later: the Atari's own masks in the SDK's `atari.h` (`JOY_UP_MASK` $01,
+// `JOY_DOWN_MASK` $02, `JOY_LEFT_MASK` $04, `JOY_RIGHT_MASK` $08,
+// `JOY_BTN_1_MASK` $10) are bit for bit the C64's, so the two machines'
+// layers agree without either one pretending.
+//
+// ---- why this reads the OS shadows, not the hardware ----------------------
+//
+// A digital joystick is five switches to ground. The hardware is PIA's
+// PORTA ($D300) — four direction bits per port, 0 where a switch is
+// closed — and GTIA's TRIG0-3 ($D010-$D013), 0 while the button is down.
+// A program could read those directly, and one that has cleared NMIEN's
+// VBI bit and taken the machine over must. This layer does not, because on
+// an 8BitScript build it does not have to: an Atari program built by this
+// toolchain contains no `sei` and never disables the OS vertical blank
+// (checked in the linked ELF; see ../AGENTS.md), so the OS's own VBI
+// refreshes STICK0-3 ($0278-$027B) and STRIG0-3 ($0284-$0287) every single
+// frame, already debounced and already split per port. Reading the shadow
+// is one `lda abs,x` against PORTA's mask-and-shift, and it cannot race the
+// OS the way the C64's matrix scan races the KERNAL.
+//
+// The one thing it costs: the shadows are only as fresh as the last VBI, so
+// `scan()` belongs right after `waitFrame()`, which is where a frame's
+// input reads belong anyway.
+//
+// ---- a mouse in a port IS the joystick ------------------------------------
+//
+// An ST or Amiga mouse and a Trak-Ball are not separate devices to the
+// machine: they sit on a joystick port and signal movement as quadrature on
+// the very direction bits this file reads. So with `--hardware mouse=st` in
+// the port a program is scanning, `bits()` returns mouse motion and `up()`
+// and friends go true while the mouse moves — that is the hardware being
+// honest, not this layer being wrong. Seen here: test/layers-probe.8bs paints
+// its border green when every input reads idle, and under `mouse=st` it goes
+// red while `mouse=paddles` and `mouse=koala` stay green, because paddles and
+// a Koala Pad are on POKEY's POT lines instead and leave the stick bits
+// alone. A program that wants both puts them in different ports
+// (`--hardware mouseport=2`), or reads the pointer and does not scan that
+// port as a stick.
+//
+// ---- how many ports there are is a fact, not a guess -----------------------
+//
+// The 400 and 800 have four ports; every XL and XE has two, and on those
+// machines PORTB is not a joystick port at all but the memory-control
+// register (see ./banks.8bs). So the port count is a property of the
+// *model* the build was made for — `input.joysticks` on the fact sheet,
+// which the catalog's `model` option sets — and `scan()` reads exactly that
+// many. `#fact(input.joysticks)` is a compile-time constant, so on an
+// 800XL build the loop is two iterations and ports 3 and 4 cost nothing;
+// on an 800 build it is four. Asking for a port the machine does not have
+// answers "nothing pushed" rather than reading PORTB and calling the
+// memory-control bits a joystick.
+import { attract } from "./index.8bs";
+
+// The OS's per-port shadows, refreshed by its VBI: four directions at
+// STICK0 and one button at STRIG0, one byte each, consecutive.
+const STICK0: usmallint = 0x0278;
+const STRIG0: usmallint = 0x0284;
+
+// The last scan, one byte per port, `Joystick.*` bits, 1 = pushed — the
+// hardware's active-low sense inverted once, here, so nothing above has to
+// think about it. All zero until the first scan.
+let state: array<utinyint, 4>;
+
+export namespace Joystick {
+    const PORT_1: utinyint = 0;
+    const PORT_2: utinyint = 1;
+    // Only on a 400 or an 800; `Joystick.PORTS` says whether this build has
+    // them, and `scan()` leaves them at zero when it does not.
+    const PORT_3: utinyint = 2;
+    const PORT_4: utinyint = 3;
+
+    const UP: utinyint = 1;
+    const DOWN: utinyint = 2;
+    const LEFT: utinyint = 4;
+    const RIGHT: utinyint = 8;
+    const FIRE: utinyint = 16;
+
+    // What this build's model has: 4 on a 400 or 800, 2 on every XL/XE.
+    // The same number as `Input.JOYSTICKS` from @8bitscript/system — the
+    // fact sheet is the one source, this is it spelled without the import.
+    const PORTS: utinyint = #fact(input.joysticks);
+}
+
+export namespace joystick {
+    // Read every port this machine has into the snapshot. Once a frame,
+    // right after waitFrame().
+    //
+    // It also zeroes ATRACT ($4D), and that is not a side errand. The OS
+    // counts that byte up in its VBI and, after roughly nine minutes with
+    // no key pressed, starts cycling the playfield colours to save the
+    // phosphor — which a keyboard game never sees, because the OS clears
+    // ATRACT on a keypress, and a joystick-only game always does, because
+    // a joystick is not a key. Left alone it turns a working game's screen
+    // into slowly rolling colours partway through a long session. Three
+    // bytes here is the whole fix, and this is the one function a
+    // joystick-only game is certain to call every frame.
+    function scan(): void {
+        for (let port: utinyint = 0; port < Joystick.PORTS; port++) {
+            let pushed: utinyint = (memory.read(STICK0 + port) ^ 0x0F) & 0x0F;
+            // TRIG is 0 while the button is down.
+            if (memory.read(STRIG0 + port) == 0) {
+                pushed = pushed + Joystick.FIRE;
+            }
+            state[port] = pushed;
+        }
+        attract = 0;
+    }
+
+    // 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,157 @@
+// @8bitscript/atari8/keyboard — the keyboard, one snapshot a frame.
+//
+// Named by "8bitscript".exports["./keyboard"] in this package's package.json:
+//
+//     import { keyboard } from "@8bitscript/atari8/keyboard";
+//     import { Key } from "@8bitscript/atari8/keys";
+//
+//     keyboard.scan();
+//     if (keyboard.pressed(Key.SPACE)) { ... }
+//
+// Hardware-level, Atari-only surface, the same shape as
+// @8bitscript/c64/keyboard and @8bitscript/pet/keyboard — `scan()` once a
+// frame, then questions answered from the snapshot. What is behind it is
+// not the same shape at all, and the difference is the whole point of this
+// file, so read the next paragraph before writing a game around it.
+//
+// ---- this machine cannot tell you which keys are down ----------------------
+//
+// The C64 and PET have a matrix a program drives itself: select a column,
+// read eight rows, and after eight passes you know the state of every key at
+// once. The Atari has no matrix a program can reach. POKEY scans the
+// keyboard in hardware and reports *one* thing — the code of the last key
+// it saw, in KBCODE ($D209), with an IRQ to say it changed — plus one bit in
+// SKSTAT saying whether a key, that key, is still held. So:
+//
+//   - "is SPACE down" is answerable: the last key was SPACE and a key is
+//     still held. `pressed()` is exactly that, and it is honest.
+//   - "are UP and FIRE both down" is *not* answerable here. Two keys at once
+//     is what the joystick is for on this machine (./joystick.8bs), and it
+//     is why Atari games put movement on a stick and reserve the keyboard
+//     for one-at-a-time choices. A portable input capability must not
+//     promise chords on this target.
+//   - a key held down repeats: the OS's VBI auto-repeats it into CH after a
+//     delay, so `key()` fires again. `pressed()` does not care, but a menu
+//     that steps on every `key()` will step twice.
+//
+// ---- why this reads the OS shadow, not KBCODE ------------------------------
+//
+// The same reasoning as ./joystick.8bs. POKEY's keyboard IRQ is live under an
+// 8BitScript build (no `sei` is emitted; see ../AGENTS.md), and the OS's
+// handler is what debounces the key, applies SHIFT and CTRL, handles the
+// auto-repeat and the CAPS lock, and leaves the result in CH ($02FC), $FF
+// for "nothing new". Reading KBCODE instead means racing that handler for a
+// register it is already consuming, and re-implementing debounce. So
+// `scan()` takes CH and hands it back to the OS as $FF — the documented way
+// a program consumes a key — and only the "still held" bit comes from the
+// hardware, because the OS keeps no shadow of it.
+//
+// A program that has taken the machine over (NMIEN's VBI bit cleared) has no
+// CH being filled and must read KBCODE itself; `keyboard.raw()` is that
+// register, for exactly that case.
+import { chShadow, skstat, kbcode } from "./index.8bs";
+
+// The last code `scan()` took from CH, modifiers included, or `Key.NONE`.
+let last: utinyint = 0xFF;
+// Whether a key was still held at the last scan.
+let held: bool = false;
+// Whether SHIFT was down at the last scan, from SKSTAT rather than from the
+// code's bit 6 — so it is true while SHIFT is held on its own.
+let shifted: bool = false;
+
+// SKSTAT's keyboard bits are active low: the bit is 0 while the thing is
+// true. (Atari Hardware Manual; the SDK's _pokey.h names them
+// SKSTAT_LASTKEY_PRESSED and SKSTAT_SHIFTKEY_PRESSED without the polarity.
+// Checked here under atari800 with nothing pressed — both bits read 1 — by
+// test/layers-probe.8bs.)
+const SK_KEY_HELD: utinyint = 0x04;
+const SK_SHIFT_HELD: utinyint = 0x08;
+
+export namespace keyboard {
+    // Take whatever the OS has, once a frame, right after waitFrame().
+    //
+    // A key is consumed here: CH goes back to $FF so the next press is seen
+    // as new. That means exactly one `scan()` per frame — a second call in
+    // the same frame finds nothing and clears the answer.
+    function scan(): void {
+        let code: utinyint = chShadow;
+        if (code != 0xFF) {
+            last = code;
+            chShadow = 0xFF;
+        } else {
+            // No new key. Keep the old code only while it is still held, so
+            // `pressed()` follows the key down and up rather than latching
+            // the last key pressed forever.
+            let status: utinyint = skstat;
+            if ((status & SK_KEY_HELD) != 0) {
+                last = 0xFF;
+            }
+        }
+        let status2: utinyint = skstat;
+        held = (status2 & SK_KEY_HELD) == 0;
+        shifted = (status2 & SK_SHIFT_HELD) == 0;
+    }
+
+    // Is this key the one being pressed? `key` is a `Key.*` code; SHIFT and
+    // CTRL are masked off both sides, so `pressed(Key.A)` is true for a
+    // shifted A as well. To require a modifier, compare `code()` against
+    // `Key.A + Key.SHIFT` instead.
+    //
+    // The `Key.NONE` guard is not belt-and-braces: `Key.NONE` is $FF and the
+    // mask is $3F, so masking an idle keyboard gives $3F — which is exactly
+    // `Key.A`. Without this line an untouched machine reports A held down
+    // forever, and it looks perfectly correct in source. test/layers-probe.8bs
+    // checks this one case in its idle reading for that reason.
+    function pressed(key: utinyint): bool {
+        if (last == 0xFF) {
+            return false;
+        }
+        return (last & 0x3F) == (key & 0x3F);
+    }
+
+    // The last key's code with its modifiers masked off, or `Key.NONE`.
+    function key(): utinyint {
+        if (last == 0xFF) {
+            return 0xFF;
+        }
+        return last & 0x3F;
+    }
+
+    // The last key's code exactly as it arrived, `Key.SHIFT` and `Key.CTRL`
+    // still on it, or `Key.NONE`.
+    function code(): utinyint {
+        return last;
+    }
+
+    // Is a key — the one `key()` names — still being held down?
+    function down(): bool {
+        return held;
+    }
+
+    // Is SHIFT held, whether or not any other key is? This is SKSTAT's own
+    // bit, so it is true for SHIFT alone, which the key code cannot say.
+    function shift(): bool {
+        return shifted;
+    }
+
+    // Was CTRL held when the last key arrived? CTRL alone cannot be read on
+    // this machine at all — there is no bit for it — so this is the code's
+    // modifier and nothing more.
+    function control(): bool {
+        return (last & 0x80) != 0;
+    }
+
+    // Forget the last key, without waiting for a scan: a menu that has acted
+    // on a choice and does not want it acted on twice.
+    function clear(): void {
+        last = 0xFF;
+        chShadow = 0xFF;
+    }
+
+    // POKEY's own KBCODE, unfiltered and undebounced — for a program that
+    // has cleared NMIEN's VBI bit and so has no OS filling CH. Nothing else
+    // in this file reads it.
+    function raw(): utinyint {
+        return kbcode;
+    }
+}

package/src/keys.8bs

@@ -0,0 +1,116 @@
+// @8bitscript/atari8/keys — the keyboard's codes, key by key.
+//
+// Named by "8bitscript".exports["./keys"] in this package's package.json, for
+//
+//     import { keyboard } from "@8bitscript/atari8/keyboard";
+//     import { Key } from "@8bitscript/atari8/keys";
+//
+//     if (keyboard.pressed(Key.SPACE)) { ... }
+//
+// Each value is the code POKEY leaves in KBCODE ($D209) and the OS leaves in
+// CH ($02FC) — not a row and column the way the C64's and PET's tables are,
+// because on this machine a program never scans a matrix. POKEY scans it in
+// hardware and hands over one code (see ./keyboard.8bs for what that costs).
+//
+// The numbering looks arbitrary because it is: it is the order POKEY's own
+// scan counter reaches each key, so `L` is 0 and `A` is $3F with nothing in
+// between to reason about. Bits 6 and 7 are the SHIFT and CTRL modifiers
+// OR-ed onto the key's own six bits, which is why every code here is under
+// $40 and why `Key.SHIFT` and `Key.CTRL` are masks rather than keys.
+//
+// A key that also exists on the C64 and PET has the same name here —
+// letters, `DIGIT_n`, SPACE, RETURN, DELETE, ESC, the punctuation — so a
+// program that sticks to those names reads the same on all three machines'
+// keyboard layers.
+//
+// Source: `KEY_*` in the LLVM-MOS SDK's own
+// `mos-platform/atari8-common/include/atari.h`, which is also mirrored as
+// assembler equates in `asminc/atari.inc`; this file is generated from that
+// header, not transcribed, and packages/atari8/test/keys.test.mjs checks
+// every value against it whenever the SDK is present. (../AGENTS.md listed
+// this table as "to verify" before the header was found; it is now sourced.)
+
+export namespace Key {
+    // Nothing pressed: what CH holds when the OS has no key for the program,
+    // and what `keyboard.key()` answers.
+    const NONE: utinyint = 0xFF;
+
+    // Letters.
+    const A: utinyint = 0x3F;
+    const B: utinyint = 0x15;
+    const C: utinyint = 0x12;
+    const D: utinyint = 0x3A;
+    const E: utinyint = 0x2A;
+    const F: utinyint = 0x38;
+    const G: utinyint = 0x3D;
+    const H: utinyint = 0x39;
+    const I: utinyint = 0x0D;
+    const J: utinyint = 0x01;
+    const K: utinyint = 0x05;
+    const L: utinyint = 0x00;
+    const M: utinyint = 0x25;
+    const N: utinyint = 0x23;
+    const O: utinyint = 0x08;
+    const P: utinyint = 0x0A;
+    const Q: utinyint = 0x2F;
+    const R: utinyint = 0x28;
+    const S: utinyint = 0x3E;
+    const T: utinyint = 0x2D;
+    const U: utinyint = 0x0B;
+    const V: utinyint = 0x10;
+    const W: utinyint = 0x2E;
+    const X: utinyint = 0x16;
+    const Y: utinyint = 0x2B;
+    const Z: utinyint = 0x17;
+
+    // Digits, named DIGIT_n so a name never starts with a number.
+    const DIGIT_0: utinyint = 0x32;
+    const DIGIT_1: utinyint = 0x1F;
+    const DIGIT_2: utinyint = 0x1E;
+    const DIGIT_3: utinyint = 0x1A;
+    const DIGIT_4: utinyint = 0x18;
+    const DIGIT_5: utinyint = 0x1D;
+    const DIGIT_6: utinyint = 0x1B;
+    const DIGIT_7: utinyint = 0x33;
+    const DIGIT_8: utinyint = 0x35;
+    const DIGIT_9: utinyint = 0x30;
+
+    // Punctuation, unshifted. The shifted character on the same key is
+    // that key OR Key.SHIFT.
+    const COMMA: utinyint = 0x20;
+    const PERIOD: utinyint = 0x22;
+    const SLASH: utinyint = 0x26;
+    const SEMICOLON: utinyint = 0x02;
+    const PLUS: utinyint = 0x06; // '+', shifted '\\'
+    const ASTERISK: utinyint = 0x07; // '*'
+    const DASH: utinyint = 0x0E; // '-'
+    const EQUALS: utinyint = 0x0F; // '='
+    const LESSTHAN: utinyint = 0x36; // '<', on its own key
+    const GREATERTHAN: utinyint = 0x37; // '>', on its own key
+
+    // The keys that are not characters.
+    const ESC: utinyint = 0x1C;
+    const TAB: utinyint = 0x2C;
+    const SPACE: utinyint = 0x21;
+    const RETURN: utinyint = 0x0C;
+    const DELETE: utinyint = 0x34; // DELETE/BACK S
+    const CAPS: utinyint = 0x3C; // CAPS/LOWR
+    const INVERSE: utinyint = 0x27; // the Atari-logo key: inverse video
+    const HELP: utinyint = 0x11; // the 1200XL and later only
+
+    // Function keys: the 1200XL had four; no other model has any.
+    const F1: utinyint = 0x03;
+    const F2: utinyint = 0x04;
+    const F3: utinyint = 0x13;
+    const F4: utinyint = 0x14;
+
+    // Modifiers, as masks OR-ed onto a key code rather than keys of their
+    // own. Neither can be read alone through KBCODE: SHIFT on its own is
+    // SKSTAT's bit 3 (`keyboard.shift()`), and CTRL on its own cannot be
+    // read at all. There is no way to tell left SHIFT from right SHIFT.
+    const SHIFT: utinyint = 0x40;
+    const CTRL: utinyint = 0x80;
+    // The key itself, with both modifiers masked off — what
+    // `keyboard.key()` is compared against.
+    const CODE: utinyint = 0x3F;
+}

package/src/pointer.8bs

@@ -0,0 +1,39 @@
+// @8bitscript/atari8/pointer — the Atari 8-bit behind @8bitscript/pointer.
+//
+// Every call here does nothing and `DRAWS` is false, and both halves are
+// missing for the same reason: nobody has written the drivers.
+//
+// **The hardware could do it.** GTIA has four players and four missiles —
+// movable objects a cursor fits in, though a player is 8 pixels wide and
+// as tall as the display, so an arrow is a few bytes of a player's stripe
+// rather than a 24x21 block like the VIC's sprite. And the catalog already
+// offers a pointing device: `mouse` with `st`, `amiga` and `trak` values,
+// each of which atari800 emulates on `-mouseport`.
+//
+// **Neither end is built.** This package has no players/missiles layer for
+// the drawing, and @8bitscript/atari8/input reports no pointer because an
+// ST or Amiga mouse on this machine is quadrature on a joystick port's
+// direction bits, decoded in software at a high poll rate — a driver in
+// its own right, listed as a gap in packages/input/AGENTS.md. An arrow
+// wants the input half first: there is no point drawing a cursor with
+// nothing to move it.
+//
+// It costs the machine 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 {
+    }
+}