@8bitscript/c64 0.1.0

package/src/mouse.8bs

@@ -0,0 +1,265 @@
+// @8bitscript/c64/mouse — a 1351 mouse in a control port: is one there,
+// where has it moved, which button is down.
+//
+// Named by "8bitscript".exports["./mouse"] in this package's package.json:
+//
+//     import { mouse } from "@8bitscript/c64/mouse";
+//
+//     mouse.select(Mouse.PORT_1);      // once, at start-up
+//     ...
+//     waitFrame();
+//     mouse.poll();                    // once a frame
+//     if (mouse.present()) { ... mouse.x() ... }
+//
+// A run-time hardware probe *and* the driver that uses it, because for a
+// mouse the two cannot be separated: a 1351 says nothing about itself
+// except through the same two lines its movement arrives on. A build
+// fitted with one (`--hardware port1=mouse1351`) has `Input.MOUSE` true
+// from @8bitscript/system, meaning this build may use a mouse; this is
+// how it finds out whether one is really plugged in. A program that never
+// imports this file carries none of it.
+//
+// **How a 1351 talks.** It is not a switch like a joystick. Each axis is
+// a counter the mouse advances as it moves, presented on the port's
+// analogue line, which the SID converts and hands back at `$D419` (X) and
+// `$D41A` (Y) — the same registers a paddle uses. VICE's `mouse_1351.c`
+// returns `(counter & 0x7f) + 0x40`, so the value lives in 64..191 and
+// wraps; movement is the *difference* between two readings, not the
+// reading. Sampled once a frame, a difference above half the range is the
+// counter having wrapped the other way, which is what makes it a signed
+// step rather than a jump.
+//
+// **A 1-count is fuzz until it happens twice the same way.** VICE's
+// 1351 is a 7-bit counter — `(x & 0x7f) + 0x40` in `mouse_1351.c` — so a
+// host pixel is often a 1-count step, and at rest the pots flicker 64/65.
+// Applying every 1-count walked the pointer with no host motion. Masking
+// to bits 1–6 and ignoring `|delta| < 3` (the previous driver) threw slow
+// motion away: `last` still advanced, so a slow move never accumulated
+// and the pointer hung until the host jumped several counts in one frame
+// (Studio, 2026-09-07). Holding the first 1-count and applying on the
+// second keeps rest still and lets a slow move through.
+//
+// **How presence is answered, and how honestly.** Measured under VICE
+// with `-controlport1device` at each of its four settings, at rest, both
+// lines read: nothing 255, a joystick 255, paddles 255, a 1351 **64** —
+// exactly the zero of the formula above. So a reading inside the 1351's
+// range is what says a mouse is there, and 255 says one is not. Two
+// things to be honest about: a real paddle sits wherever it was last
+// turned, so a paddle at mid-travel reads in this range too and only
+// movement tells them apart; and a mouse is only *found* once the program
+// has waited a frame after `select()` for the SID's converter to settle.
+// `present()` therefore means "consistent with a 1351", and a program
+// that must be certain should watch for movement before believing it.
+//
+// **The buttons** are not analogue at all: they ride the port's ordinary
+// joystick lines, left on FIRE and right on UP (`mouse_1351.c`), so they
+// are read exactly as a joystick's switches are — which also means a
+// joystick pushed up looks like a right button, and this file will not
+// pretend otherwise.
+//
+// **The port select** is CIA1 port A's top two bits: `%01` reads port 1's
+// analogue lines, `%10` port 2's (confirmed here — `$DC00 = $40` is what
+// made the 1351 readable in port 1). Those same bits are keyboard column
+// outputs, so `select()` leaves the other six high, driving no column;
+// `@8bitscript/c64/keyboard`'s scan writes all eight itself and must be
+// followed by another `select()` before the next `poll()` if both are
+// used. The converter needs about half a millisecond after a select, so
+// the order that works is: `select()` at start-up, then one `poll()` a
+// frame.
+import { paddleX, paddleY, cia1PortA, cia1PortB } from "./index.8bs";
+
+export namespace Mouse {
+    const PORT_1: utinyint = 0x7F;   // %01 in the top bits, no keyboard column driven
+    const PORT_2: utinyint = 0xBF;   // %10
+}
+
+namespace Pot {
+    const COUNTER: utinyint = 0x7F;  // VICE's 1351 is 7 bits; bit 0 is also fuzz
+    const LOWEST: utinyint = 64;     // a 1351 at its zero point
+    const HIGHEST: utinyint = 191;   // and at the other end of its wrap
+    const HALF: utinyint = 64;       // half the 7-bit wrap space: a bigger step is a wrap
+}
+
+// Per-axis filter for 1-count steps. Rest's 64/65 flicker is +1 then -1
+// and never leaves WAIT; a slow host move is +1, +1 and then tracks at
+// one pixel a count instead of jumping two and stalling on the next.
+namespace Axis {
+    const IDLE: utinyint = 0;
+    const WAIT_POS: utinyint = 1;
+    const RUN_POS: utinyint = 2;
+    const WAIT_NEG: utinyint = 3;
+    const RUN_NEG: utinyint = 4;
+}
+
+// The last counter reading on each axis, and where the pointer has got to.
+let lastX: utinyint = 0;
+let lastY: utinyint = 0;
+let atX: usmallint = 0;
+let atY: usmallint = 0;
+let started: bool = false;
+let hold: array<utinyint, 2>;
+
+// Whether the reading the last poll() took was consistent with a 1351.
+// **Kept, rather than asked again**, and that is not an optimisation: the
+// SID's converter runs continuously, so two reads of `$D419` are two
+// different moments, and a program that asks twice in one frame can get
+// two different answers. Measured under x64sc with a 1351 fitted in port
+// 1: `@8bitscript/c64/input`'s poll() concluded *no pointer* while a read
+// taken a few instructions later in the same frame said there was one, so
+// an arrow drawn from one answer and hit-tested from the other flickered
+// out of existence. One reading a frame, and everyone shares it.
+let there: bool = false;
+
+// How far the pointer may travel on each axis. A 1351's counters run on
+// for as long as the mouse is pushed, so without a ceiling a pointer
+// shoved off the right of the screen has to be dragged all the way back
+// before it reappears — the accumulator, not the display, is what has to
+// stop. Wide open until a program calls `setLimits()`.
+let limitX: usmallint = 65535;
+let limitY: usmallint = 65535;
+
+export namespace mouse {
+    // Point the SID's analogue lines at one control port: Mouse.PORT_1 or
+    // Mouse.PORT_2. Once, at start-up — the converter needs a frame to
+    // settle before the first poll() means anything.
+    function select(port: utinyint): void {
+        cia1PortA = port;
+    }
+
+    // The ceiling each axis stops at, in mouse counts — `setLimits(319,
+    // 199)` for a C64's pixels, `setLimits(39, 24)` for its cells if the
+    // program scales before it gets here. Both axes stop at 0 either way.
+    // Set it once at start-up; a program that never calls this gets an
+    // accumulator that runs as far as the mouse is pushed.
+    function setLimits(x: usmallint, y: usmallint): void {
+        limitX = x;
+        limitY = y;
+    }
+
+    // One axis' movement since the last reading, added to `at` and held
+    // between 0 and `limit`. The difference is taken in all seven bits,
+    // and a difference past half the 7-bit wrap space is the counter
+    // having gone the other way.
+    //
+    // **A 1-count is fuzz until it happens twice the same way, then it
+    // tracks.** VICE's rest reading flickers 64/65; applying every
+    // 1-count walked the pointer with no host motion. Masking to bits 1–6
+    // and ignoring `|delta| < 3` *and* updating `last` (the previous
+    // driver) ate slow host motion: a trackpad step is often 1–2 counts a
+    // frame, so the pointer hung until the host jumped (Studio,
+    // 2026-09-07). Confirming the first 1-count, then applying each
+    // further 1-count, keeps rest still and lets a slow move through one
+    // pixel at a time. A still frame after a *run* drops back to idle so
+    // rest cannot walk; a still frame while *waiting* is kept, because a
+    // slow host move is often one count then several frames of zero —
+    // idling there ate the second count (Studio, 2026-09-07).
+    function step(at: usmallint, last: utinyint, now: utinyint, limit: usmallint, axis: utinyint): usmallint {
+        let delta: utinyint = (now - last) & Pot.COUNTER;
+        let state: utinyint = hold[axis];
+        if (delta == 0) {
+            if (state == Axis.RUN_POS || state == Axis.RUN_NEG) {
+                hold[axis] = Axis.IDLE;
+            }
+            return at;
+        }
+        if (delta < Pot.HALF) {
+            if (delta == 1) {
+                if (state == Axis.WAIT_POS || state == Axis.RUN_POS) {
+                    hold[axis] = Axis.RUN_POS;
+                } else {
+                    hold[axis] = Axis.WAIT_POS;
+                    return at;
+                }
+            } else {
+                hold[axis] = Axis.RUN_POS;
+            }
+            if (limit - at < delta) {
+                return limit;
+            }
+            return at + delta;
+        }
+        let back: utinyint = 128 - delta;
+        if (back == 1) {
+            if (state == Axis.WAIT_NEG || state == Axis.RUN_NEG) {
+                hold[axis] = Axis.RUN_NEG;
+            } else {
+                hold[axis] = Axis.WAIT_NEG;
+                return at;
+            }
+        } else {
+            hold[axis] = Axis.RUN_NEG;
+        }
+        if (back > at) {
+            return 0;
+        }
+        return at - back;
+    }
+
+    // Read both axes. Once a frame, after waitFrame().
+    //
+    // **One reading of each line, answering both questions.** Whether a
+    // mouse is there and how far it moved come out of the same two bytes,
+    // because they are two readings of one moment: the range check says a
+    // 1351 and the difference from last frame says how far. Reading the
+    // registers a second time later in the frame — which is what
+    // `present()` used to do — samples a converter that has moved on.
+    function poll(): void {
+        let rawX: utinyint = paddleX;
+        let rawY: utinyint = paddleY;
+        there = rawX >= Pot.LOWEST && rawX <= Pot.HIGHEST && rawY >= Pot.LOWEST && rawY <= Pot.HIGHEST;
+        if (started) {
+            atX = mouse.step(atX, lastX, rawX, limitX, 0);
+            // Y runs opposite the screen. Verified under x64sc (Studio,
+            // 2026-09-07): the same sign as X moved the arrow up when the
+            // mouse moved down. last and now are swapped so the *delta*
+            // flips and the rest position stays 0 (top-left). Reporting
+            // `limitY - atY` would park the arrow at the bottom instead.
+            atY = mouse.step(atY, rawY, lastY, limitY, 1);
+        }
+        lastX = rawX;
+        lastY = rawY;
+        started = true;
+    }
+
+    // Is a 1351 in the selected port? True when both lines read inside
+    // the 1351's range: nothing, a joystick and paddles at rest all read
+    // 255. A paddle turned to the middle of its travel also reads here,
+    // so this means "consistent with a mouse" — movement is what proves
+    // one.
+    //
+    // **This is what the last `poll()` saw, not a fresh reading**, so it
+    // is false until the first poll and it gives every caller in a frame
+    // the same answer. See `there` above for the measurement that made
+    // that necessary.
+    function present(): bool {
+        return there;
+    }
+
+    // Where the pointer has moved to since the program started, in mouse
+    // counts. A program scales these to its own screen.
+    function x(): usmallint {
+        return atX;
+    }
+
+    function y(): usmallint {
+        return atY;
+    }
+
+    // The buttons, on the port's joystick lines: left is FIRE, right is
+    // UP. Port 1 is CIA1 port B; port 2 is port A, which is also the
+    // register select() writes, so a port-2 mouse's buttons are read from
+    // what the port reads back, not from what was written.
+    function left(port: utinyint): bool {
+        if (port == Mouse.PORT_1) {
+            return (cia1PortB & 16) == 0;
+        }
+        return (cia1PortA & 16) == 0;
+    }
+
+    function right(port: utinyint): bool {
+        if (port == Mouse.PORT_1) {
+            return (cia1PortB & 1) == 0;
+        }
+        return (cia1PortA & 1) == 0;
+    }
+}

package/src/pointer.8bs

@@ -0,0 +1,183 @@
+// @8bitscript/c64/pointer — the C64 behind @8bitscript/pointer: an arrow,
+// drawn with one of the VIC-II's eight sprites.
+//
+// Named by "8bitscript".exports["./pointer"] in this package's package.json,
+// and by "8bitscript".entry.c64 in @8bitscript/pointer's, so a portable
+// program writes
+//
+//     import { pointer } from "@8bitscript/pointer";
+//
+// and gets this file on a C64. It is the *visible* half of the pointer
+// @8bitscript/input already reports: `input` says where the pointer is and
+// whether its button went down, and this says what the user sees while
+// they aim it. Two packages rather than one because reading and drawing
+// are separate everywhere else in this library — `text` draws, `input`
+// reads — and because a machine can perfectly well answer `pointerCell()`
+// and have nothing whatever to draw an arrow with. Eight of the nine are
+// in exactly that position today.
+//
+// ---- why a sprite, and which one ------------------------------------------
+//
+// A cursor has to move without disturbing what is under it, and on this
+// machine the only thing that does that is a movable object: a character
+// cell cursor would have to put back the cell it covered, and
+// @8bitscript/text can write a cell but not read one, so it could not.
+// A sprite also moves a pixel at a time where a cell cursor moves eight,
+// which is the difference between aiming at a menu item and guessing at
+// one.
+//
+// **This file owns sprite 0 and the last shape block, and says so.** The
+// VIC has eight sprites in a fixed front-to-back order and sprite 0 is
+// always in front, which is where a cursor belongs — it is over the
+// interface, not in it. The shape goes in the *last* block
+// @8bitscript/c64/sprites owns rather than the first, because a program
+// laying its own shapes out counts up from `sprites.FIRST_BLOCK` and would
+// otherwise land on the cursor's. A program that wants all eight sprites
+// and no cursor simply does not import this file, and pays nothing for it.
+//
+// ---- the position comes from the mouse's accumulator ----------------------
+//
+// `update()` reads ./mouse.8bs's x and y directly, in **pixels**, rather
+// than taking `input.pointerCell()` — a cell is 8 pixels and a cursor that
+// jumped 8 pixels at a time would be the cell cursor this file exists to
+// avoid. Reading the accumulator is free and safe: ./input.8bs's `poll()`
+// is what advances it, once a frame, and this only looks at where it got
+// to. That is the one ordering rule here, and it is the same one `input`
+// already has: **`poll()` then `update()`, once each a frame.** A program
+// that never calls `input.poll()` gets an arrow that never moves.
+//
+// The arrow's tip is its top-left pixel, so the sprite goes at the mouse's
+// pixel plus the screen's origin in the VIC's coordinate space
+// (`sprites.LEFT`, `sprites.TOP` — 24 and 50, documented in
+// ./sprites.8bs): the tip lands exactly on the pixel the mouse is at, and
+// `input.pointerCell()` is the cell that pixel is in, so what the user
+// aims at and what the program hit-tests are the same thing by
+// construction.
+//
+// ---- a build without a mouse pays nothing ---------------------------------
+//
+// `#fact(input.mouse)` is false on a stock C64, so `HAS_MOUSE` is a const,
+// `if (HAS_MOUSE)` is `if (false)`, and the arrow, its 63 bytes of shape
+// and every register write below are neither reached, referenced nor
+// linked. Fitting a mouse is what compiles them in — measured on Studio,
+// where the arrow costs **182 bytes of program and 1 of RAM** on top of
+// the input layer's mouse, and a mouse and its arrow together take that
+// program from 1523 bytes and 28 of RAM to 2208 and 47.
+import { sprites } from "./sprites.8bs";
+import { mouse } from "./mouse.8bs";
+
+// Was this build fitted with a mouse? Folded while compiling.
+const HAS_MOUSE: bool = #fact(input.mouse);
+
+// The colour the arrow starts in, in the VIC's sixteen. White reads against
+// every background @8bitscript/screen offers, and `setColor` changes it.
+const WHITE: utinyint = 1;
+
+// The arrow: 21 rows of 3 bytes, one bit a pixel, left to right — the
+// shape format ./sprites.8bs documents. Only the leftmost byte of each row
+// is set, so the arrow is 8 pixels wide inside a 24-pixel sprite; the tip
+// is the top-left pixel, which is what makes the sprite's position and the
+// pointer's position the same number.
+//
+//     X.......    XXXXXXXX
+//     XX......    XXXXXX..
+//     XXX.....    XXX.XX..
+//     XXXX....    XX...XX.
+//     XXXXX...    X....XX.
+//     XXXXXX..    ......XX
+//     XXXXXXX.    .......X
+//
+// A const array is data in the program image and never in RAM, so the
+// picture costs no memory the program could have used.
+const ARROW: array<utinyint, 63> = [
+    0x80, 0, 0,
+    0xC0, 0, 0,
+    0xE0, 0, 0,
+    0xF0, 0, 0,
+    0xF8, 0, 0,
+    0xFC, 0, 0,
+    0xFE, 0, 0,
+    0xFF, 0, 0,
+    0xFC, 0, 0,
+    0xEC, 0, 0,
+    0xC6, 0, 0,
+    0x86, 0, 0,
+    0x06, 0, 0,
+    0x03, 0, 0,
+    0, 0, 0,
+    0, 0, 0,
+    0, 0, 0,
+    0, 0, 0,
+    0, 0, 0,
+    0, 0, 0,
+    0, 0, 0,
+];
+
+export namespace pointer {
+
+    // Does this machine draw a pointer at all? A compile-time constant, so
+    // a program can lay itself out around the answer — and on the C64 it is
+    // "only if this build was fitted with a mouse", which is the same
+    // question `input.pointer()` answers at run time.
+    const DRAWS: bool = #fact(input.mouse);
+
+    // The sprite and the shape block this file claims. Named rather than
+    // hidden so a program using @8bitscript/c64/sprites alongside a cursor
+    // knows which two it may not have.
+    const SPRITE: utinyint = 0;
+    const BLOCK: utinyint = 254; // sprites.FIRST_BLOCK + sprites.BLOCK_COUNT - 1
+
+    // Once, at start-up, after input.begin(): copy the arrow into its block
+    // and point the sprite at it. The shape is copied rather than pointed
+    // at where it lies because the VIC reads its own bank and a const array
+    // is wherever the linker put it — the copy loop ./sprites.8bs's header
+    // describes. On a build with no mouse this compiles to nothing.
+    function begin(): void {
+        if (HAS_MOUSE) {
+            let i: utinyint = 0;
+            while (i < sprites.BYTES) {
+                sprites.setShapeByte(pointer.BLOCK, i, ARROW[i]);
+                i = i + 1;
+            }
+            sprites.setShape(pointer.SPRITE, pointer.BLOCK);
+            sprites.setColor(pointer.SPRITE, WHITE);
+        }
+    }
+
+    // The arrow's colour, in the VIC's sixteen — the same numbers
+    // @8bitscript/text's colours are.
+    function setColor(color: utinyint): void {
+        if (HAS_MOUSE) {
+            sprites.setColor(pointer.SPRITE, color);
+        }
+    }
+
+    // Once a frame, after input.poll(): put the arrow where the mouse got
+    // to, and show it only while a mouse is really answering. `present()`
+    // is ./mouse.8bs's probe — a build may be fitted for a mouse and not
+    // have one plugged in, and an arrow parked in a corner would be a lie
+    // about that.
+    function update(): void {
+        if (HAS_MOUSE) {
+            if (mouse.present()) {
+                // The VIC's Y is 8 bits and the screen's 200 rows of pixels
+                // start at 50, so the sum is at most 249 and cannot carry
+                // out of a byte — which is why this needs no clamp of its
+                // own beyond the ceiling input.begin() gave the mouse.
+                sprites.place(pointer.SPRITE, sprites.LEFT + mouse.x(), sprites.TOP + mouse.y());
+                sprites.show(pointer.SPRITE);
+            } else {
+                sprites.hide(pointer.SPRITE);
+            }
+        }
+    }
+
+    // Take the arrow off the screen and leave it off until the next
+    // update(). What a program does while it is doing something the user
+    // cannot point at.
+    function hide(): void {
+        if (HAS_MOUSE) {
+            sprites.hide(pointer.SPRITE);
+        }
+    }
+}

package/src/random.8bs

@@ -0,0 +1,81 @@
+// @8bitscript/c64/random — SID voice 3's hardware entropy.
+//
+// Named by "8bitscript".exports["./random"] in this package's package.json:
+//
+//     import { random } from "@8bitscript/c64/random";
+//
+//     random.begin();
+//     let seed: utinyint = random.byte();
+//
+// Its own import, and not part of ./sid.8bs, on purpose — the same reason
+// @8bitscript/atari8/random stands apart from ./pokey.8bs there. Voice 3's
+// oscillator ($D41B) and envelope generator ($D41C) are readable *hardware*
+// state: with the oscillator set to the noise waveform, $D41B is the top
+// byte of a free-running 23-bit polynomial counter, sampled wherever it
+// happens to be when the CPU reads it, so two runs of the same program
+// never agree. That is exactly what a program wants for a seed and exactly
+// what it does not want anywhere else — a game that reads it inside its
+// logic cannot be replayed, cannot be tested against a recorded input, and
+// cannot be debugged from a screenshot. The root AGENTS.md rule is that
+// hardware entropy is never the deterministic PRNG's seed by default and
+// never arrives without being asked for; this file is the asking.
+//
+// The usual shape: read one byte at start-up, seed a deterministic
+// generator (`@8bitscript/random` or `@8bitscript/random/table`) with it,
+// and never touch this again.
+//
+// ---- this claims voice 3 whole ---------------------------------------------
+//
+// Reading real noise means voice 3 has to actually be making it: `begin()`
+// sets its frequency to the fastest the register allows (the noise LFSR is
+// clocked by the oscillator's own carries, so a low frequency barely
+// changes it between two reads a frame apart) and its waveform to noise,
+// then sets $D418's voice-3-off bit so none of that reaches the speaker.
+// The SID's registers below $D419 are write-only — the chip has no way to
+// report what is already there — so `begin()` writes $D418 as a whole
+// known byte (silent, no filter, volume 0) rather than trying to preserve
+// whatever a program had set before. **Call `begin()` first, before
+// `@8bitscript/c64/sid` touches the volume or the filter**, or its own
+// write will win and this file has no way to know that happened — the two
+// packages do not coordinate, the same way @8bitscript/atari8/random warns
+// about AUDCTL. A program that wants both real sound *and* this seed reads
+// the seed once, at start-up, before it plays a single note; using voice 3
+// for both music and entropy at the same time is not something this file
+// can make safe.
+//
+// ---- what the number actually is -------------------------------------------
+//
+// The noise waveform's LFSR is 23 bits, and $D41B is its top 8, so
+// consecutive reads a few cycles apart are consecutive shifts of one
+// register, not independent samples — the same caveat
+// @8bitscript/atari8/random's header gives POKEY's counter. `word()` is
+// here for a program that wants more than eight bits and knows that;
+// anything that needs many independent values wants a PRNG seeded once
+// from here. Nothing here is a source of cryptographic randomness, on this
+// chip or on POKEY's.
+import { sidRegisters, voice3Oscillator } from "./index.8bs";
+
+export namespace random {
+    // Claims voice 3: fastest-clocked noise, silenced. See the header for
+    // why this must run before anything else touches $D418.
+    function begin(): void {
+        sidRegisters[14] = 0xFF; // voice 3 frequency, low byte
+        sidRegisters[15] = 0xFF; // voice 3 frequency, high byte — fastest LFSR clock
+        sidRegisters[18] = 0x80; // voice 3 control: noise waveform, gate off
+        sidRegisters[24] = 0x80; // $D418: voice 3 off, filter off, volume 0 — a whole known byte, not a read-modify-write of a write-only register
+    }
+
+    // One byte from the oscillator, 0-255.
+    function byte(): utinyint {
+        return voice3Oscillator;
+    }
+
+    // Two bytes as one 16-bit value. See the header: the two reads are
+    // consecutive shifts of one register, close together in time, so this
+    // is wider than `byte()` but not twice as random.
+    function word(): usmallint {
+        let high: usmallint = voice3Oscillator;
+        let low: usmallint = voice3Oscillator;
+        return high * 256 + low;
+    }
+}