@8bitscript/random 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/README.md

@@ -0,0 +1,69 @@
+# @8bitscript/random
+
+Deterministic pseudo-random generators, the same code on every target —
+VIC-20, C64, PET, C128, Atari 8-bit, NES, Commander X16, MEGA65, and web.
+Two, so far, at two import paths, with the same three calls:
+
+```bash
+pnpm add @8bitscript/random
+```
+
+```
+import { random } from "@8bitscript/random"; // the default: a 16-bit LCG
+// or
+import { table } from "@8bitscript/random/table"; // a precomputed lookup table
+
+random.seed(1234);
+let roll: utinyint = random.range(6) + 1; // 1..6
+```
+
+| Call | What it does |
+| --- | --- |
+| `seed(value)` | Replaces the generator's whole state |
+| `next()` | One step of the generator; a byte, 0-255 |
+| `range(bound)` | `next() % bound` — a value from 0 up to (not including) `bound` |
+
+`table` adds one more call, since it has no reason not to: `at(index)`
+reads the table directly with no state of its own, for a program that
+already keeps its own running counter (frames elapsed is the usual one).
+
+## Which one
+
+| | `@8bitscript/random` | `@8bitscript/random/table` |
+| --- | --- | --- |
+| How `next()` works | `state = state * 25173 + 13849`, return the high byte | `TABLE[index]`, then `index++` |
+| Cost per call | A 16-bit multiply and add | One indexed load |
+| Period | 65536 | 256 |
+| Distribution | Good, not exact | Exact over every 256 consecutive calls — the table is a permutation of 0-255 |
+
+Reach for the default generator first. Reach for `/table` where a 6502
+multiply is specifically the thing a piece of code cannot afford — several
+picks in one frame, in a routine already fighting for cycles — and a
+256-call period is not a problem for what it is picking. The two are
+interchangeable at the call site: switching is one import line.
+
+**Deterministic by default, explicitly seeded — never hardware entropy.**
+The root [`AGENTS.md`](../../AGENTS.md) rule is that a program's ordinary
+random numbers must come from a small, seeded, fixed-state generator, and
+hardware entropy (a POKEY register, SID's oscillator 3, timing jitter)
+belongs behind its own separate, explicitly optional import. Both
+generators here are that default. Neither reads a register on any target —
+a program that wants a less predictable seed reaches for a machine's own
+entropy source (`@8bitscript/atari8/random`'s POKEY counter,
+`@8bitscript/c64/random`'s SID voice 3) and hands the byte it reads to
+either one's `seed()`.
+
+**Not called until you call it.** A program that never calls `seed()` gets
+the same sequence every run. That is a feature for testing and for
+reproducing a bug from a screenshot, not an oversight — call `seed()` once,
+from whatever the program wants unpredictable (elapsed frames before the
+first key press is the usual shape on a machine with no hardware entropy at
+all), and every run after that differs.
+
+**Not cryptographic, on any target.** Public, fixed steps over small state
+are exactly as guessable as they sound, table included. This is for game
+boards, shuffles, and enemy behaviour — nothing a program needs to keep
+secret from the person playing it.
+
+See [`src/index.8bs`](src/index.8bs) and [`src/table.8bs`](src/table.8bs)
+for each generator and the reasoning behind it.

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@8bitscript/random",
+  "version": "0.1.0",
+  "description": "Deterministic pseudo-random generators, explicitly seeded, the same code on every target: a 16-bit LCG at the bare import, a precomputed lookup table at ./table. Hardware entropy stays behind its own machine-specific import (@8bitscript/atari8/random, @8bitscript/c64/random).",
+  "license": "MIT",
+  "8bitscript": {
+    "entry": "./src/index.8bs",
+    "exports": {
+      "./table": "./src/table.8bs"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/src/index.8bs

@@ -0,0 +1,71 @@
+// @8bitscript/random — a small, deterministic pseudo-random generator.
+//
+//     import { random } from "@8bitscript/random";
+//
+//     random.seed(1234);
+//     let roll: utinyint = random.range(6) + 1; // 1..6
+//
+// The root AGENTS.md rule is that "randomness must be deterministic by
+// default, explicitly seeded, with small fixed state" — hardware entropy
+// (a POKEY register, SID's oscillator 3, timing jitter) belongs behind its
+// own separate, explicitly optional import, never silently underneath a
+// program's ordinary random numbers. This package is the deterministic
+// default every target can use: sixteen bits of state, one multiply-and-add
+// step, nothing read from hardware. A program on the one target that does
+// have hardware entropy behind its own import today — POKEY's counter,
+// `@8bitscript/atari8/random` — reads a byte from it once and hands that to
+// `seed()`; this file never reaches for a register itself, on any target,
+// which is what lets it be the same sixteen lines on all nine.
+//
+// This is not the file to reach for if a program ever needs numbers a
+// player cannot predict by reading the source — nothing here is
+// cryptographic, on any target, any more than the hardware sources are.
+
+let state: usmallint = 1;
+
+export namespace random {
+    // Replaces the generator's whole state. A program that never calls this
+    // gets the same sequence on every run, starting from `state`'s own
+    // initialiser above — a deterministic default, not a random one nobody
+    // asked for. 0 is a valid seed: the additive constant below means the
+    // next `next()` still moves state away from it, unlike a generator
+    // built on multiplication or XOR alone, where an all-zero state is a
+    // fixed point.
+    function seed(value: usmallint): void {
+        state = value;
+    }
+
+    // One step of a 16-bit linear congruential generator: `state = state *
+    // A + C`, wrapping the way `usmallint` arithmetic always does, which is
+    // exactly the modulus a 16-bit LCG wants (mod 65536). A and C are the
+    // constants several 8-bit BASICs used for their own RND — coprime with
+    // 65536 and long enough for a game board or a shuffled deck.
+    //
+    // The result is the *high* byte of the new state, not the low one: the
+    // low byte of a LCG this size cycles with a much shorter period (16 for
+    // A - 1 divisible by 4, here a period of 4 in the very lowest bit) and
+    // fails an obvious pattern check almost immediately, while the high
+    // byte carries the full 65536-state period. `state >> 8` costs one
+    // instruction on the 6502 and is exact on the web target too — no
+    // divide, on either backend.
+    function next(): utinyint {
+        state = state * 25173 + 13849;
+        return state >> 8;
+    }
+
+    // A value from 0 up to (not including) bound — the shape a caller
+    // wants when picking among a fixed number of choices: a board cell, a
+    // shuffled index, a die face after adding 1. `bound` must be at least
+    // 1. The classic modulo-bias caveat applies here as much as it does on
+    // any machine: for a `bound` that is not a power of two, the results
+    // near 255 are very slightly less likely than the results near 0,
+    // because 256 is not an exact multiple of `bound`. That bias is under
+    // 1/256 of a percentage point for anything this package is likely to be
+    // asked for — a handful of board cells or die faces — and not worth a
+    // rejection-sampling loop's extra code on a machine measured in
+    // kilobytes; a program that needs an exactly uniform pick from a large
+    // bound should say so and this note is where to start.
+    function range(bound: utinyint): utinyint {
+        return random.next() % bound;
+    }
+}

package/src/table.8bs

@@ -0,0 +1,88 @@
+// @8bitscript/random/table — a precomputed lookup table, not an algorithm:
+// the "random" byte for any position is a read of program data, nothing
+// computed. This is the technique 8-bit code reached for before spending a
+// multiply on randomness was affordable, and it is still the cheapest random
+// byte 8BitScript can produce on any of the nine targets.
+//
+//     import { table } from "@8bitscript/random/table";
+//
+//     table.seed(37);                     // any utinyint start point
+//     let roll: utinyint = table.range(6) + 1; // 1..6
+//
+// Same shape as the default generator's (`@8bitscript/random`,
+// ../index.8bs): `seed()`, `next()`, `range(bound)`. A program can switch
+// between the two by changing one import line, which is the point of
+// keeping the surface identical rather than making this generator's
+// strengths (or its one real weakness) show up as a different set of calls.
+//
+// **The trade this makes, stated plainly**: `next()` repeats every 256
+// calls, always in the same order from wherever `index` is — a far shorter
+// period than the default generator's 65536 states, and a predictable one:
+// see `index` once and every value after it is known. What it buys back is
+// that `next()` is one indexed load — `TABLE[index]`, `index++` — never a
+// 16-bit multiply and add, on the 6502 or the web. A program that needs
+// more than 256 calls' worth of unpredictability, or that hands `index`'s
+// value to anything a player could see, wants `@8bitscript/random` instead;
+// one that calls this a handful of times per frame, in code where a 6502
+// multiply is the thing being budgeted against, is exactly what this file
+// is for.
+//
+// **The 256 bytes are a permutation, not an arbitrary sequence** — every
+// value 0-255 appears exactly once, shuffled once (a seeded Fisher-Yates,
+// off the source repository, not on any target) and baked in here as
+// `.rodata`. That is a real property this table has and a plain LCG does
+// not: any 256 consecutive calls to `next()`, from any starting `index`,
+// use every possible byte exactly once — perfectly even in the long run
+// by construction, not by chance, at the cost of the short period above.
+const TABLE: array<utinyint, 256> = [
+    184, 152, 234,  42, 232, 225, 236, 202, 129, 123, 183,  74, 187,  15, 249, 166,
+     47,  68, 218,  37, 134, 110, 147,  91, 219, 229, 148, 135,  13, 111, 222, 195,
+    113, 126,  19, 190,  49,  11, 142,  18,  10, 154, 206, 254,  77, 199,  99, 250,
+    231,  59, 233,  72, 107, 196,  26, 252, 235, 238, 100, 138, 139, 189, 178, 118,
+    212,  78,  98, 214, 167, 143,  71, 145,  87, 179, 165,  28,  16,  53,  30,  86,
+     60, 205, 247, 120, 128,  76, 185, 207,  97,  51, 204, 169,  39, 159, 217, 161,
+     43,  57,   4,  75, 141,   3, 251,  84, 155, 198,  23, 239,  61,  27,  90,  14,
+    177, 230, 245, 197,  64, 140,  65, 226, 151,   6,  56, 127, 181, 255,  88, 103,
+    223,  21,  29, 224,  62, 115,  46,  22, 173,   1, 156, 241,  17, 125, 208, 228,
+    122, 132,  54,  70,  69, 105, 149, 101, 200, 112, 243, 168,  80,  66, 182, 248,
+    203, 201,  31,  85, 176,  55,  63,  50, 211, 193,  52,  38,  45,  40, 209, 237,
+    119, 133, 216,  41, 244,  25, 246, 121, 215, 171,  12, 160, 144,  92, 106, 227,
+     35, 130,   8, 108, 158, 162,  36,  48, 174,  34, 117,  67, 153, 186, 194,  32,
+    157, 175,  95,  79, 221, 191,  81,  44, 163,   0, 253, 104, 136, 150, 240,  73,
+    210,  96,   7, 146, 188, 114,   5,  82, 213, 137,  93, 124,  94,  83,  89,  58,
+    116, 170, 180,   2, 242, 131, 192, 102,  20, 164, 109, 172, 220,  24,   9,  33,
+];
+
+let index: utinyint = 0;
+
+export namespace table {
+    // Replaces the running position, wherever a program wants to start —
+    // `index` is a `utinyint`, so any value is in range and wraps at 256
+    // for free (256 is exactly `TABLE.length`).
+    function seed(value: utinyint): void {
+        index = value;
+    }
+
+    // The byte at the current position, then step to the next one.
+    function next(): utinyint {
+        let value: utinyint = TABLE[index];
+        index++;
+        return value;
+    }
+
+    // A value from 0 up to (not including) bound. See ../index.8bs for the
+    // same modulo-bias note — it applies here too, and for the same reason.
+    function range(bound: utinyint): utinyint {
+        return table.next() % bound;
+    }
+
+    // The table with no state at all: a program that already keeps its own
+    // running counter — frames elapsed since start-up is the usual one —
+    // reads a "random" byte by indexing this table with it directly,
+    // rather than asking this file to keep a second counter next to it.
+    // `at(0)` and repeated `next()` calls from `seed(0)` agree, because
+    // this is exactly what `next()` reads before it steps `index`.
+    function at(i: utinyint): utinyint {
+        return TABLE[i];
+    }
+}