redscript-mc 2.2.1 → 2.3.0

package/src/stdlib/color.mcrs

@@ -0,0 +1,160 @@
+// color.mcrs — Color utilities for RedScript datapacks.
+//
+// All RGB values: 0-255
+// All HSL values: H 0-360, S 0-100, L 0-100
+// Packed int format: 0xRRGGBB (R in bits 16-23, G in bits 8-15, B in bits 0-7)
+//   packed = R*65536 + G*256 + B
+//
+// Note: No native bitwise ops in MC scoreboard — packing/unpacking uses multiply/divide.
+
+module library;
+
+// ─── Pack / Unpack ────────────────────────────────────────────────────────────
+
+// rgb_pack(r, g, b): pack RGB into a single int (0xRRGGBB)
+fn rgb_pack(r: int, g: int, b: int): int {
+    return r * 65536 + g * 256 + b;
+}
+
+// rgb_r(packed): extract red component
+fn rgb_r(packed: int): int {
+    return packed / 65536 % 256;
+}
+
+// rgb_g(packed): extract green component
+fn rgb_g(packed: int): int {
+    return packed / 256 % 256;
+}
+
+// rgb_b(packed): extract blue component
+fn rgb_b(packed: int): int {
+    return packed % 256;
+}
+
+// ─── Blending ─────────────────────────────────────────────────────────────────
+
+// rgb_lerp(a, b, t): linear blend between two packed colors, t ∈ [0, 1000]
+// t=0 → a, t=1000 → b
+fn rgb_lerp(a: int, b: int, t: int): int {
+    let ra: int = a / 65536 % 256;
+    let ga: int = a / 256 % 256;
+    let ba_: int = a % 256;
+    let rb: int = b / 65536 % 256;
+    let gb: int = b / 256 % 256;
+    let bb_: int = b % 256;
+    let r: int = ra + (rb - ra) * t / 1000;
+    let g: int = ga + (gb - ga) * t / 1000;
+    let bv: int = ba_ + (bb_ - ba_) * t / 1000;
+    return r * 65536 + g * 256 + bv;
+}
+
+// ─── HSL ↔ RGB ────────────────────────────────────────────────────────────────
+
+// hsl_to_rgb_r/g/b: convert HSL to individual RGB components
+// H: 0-360, S: 0-100, L: 0-100, returns 0-255
+fn _hsl_chroma_x(h: int, c: int): int {
+    // X = C * (1 - |H/60 mod 2 - 1|)
+    let sector: int = h / 60;
+    let rem: int = h % 120;
+    if (rem > 60) { rem = 120 - rem; }
+    return c * rem / 60;
+}
+
+fn hsl_to_r(h: int, s: int, l: int): int {
+    let c: int = s * (1000 - (2 * l * 10 - 1000)) / 1000;
+    if (c < 0) { c = 0 - c; }
+    c = c / 10;
+    let x: int = _hsl_chroma_x(h, c);
+    let m: int = l * 255 / 100 - c / 2;
+    let sector: int = h / 60;
+    if (sector == 0) { return (c + m); }
+    if (sector == 1) { return (x + m); }
+    if (sector == 2) { return m; }
+    if (sector == 3) { return m; }
+    if (sector == 4) { return (x + m); }
+    return (c + m);
+}
+
+fn hsl_to_g(h: int, s: int, l: int): int {
+    let c: int = s * (1000 - (2 * l * 10 - 1000)) / 1000;
+    if (c < 0) { c = 0 - c; }
+    c = c / 10;
+    let x: int = _hsl_chroma_x(h, c);
+    let m: int = l * 255 / 100 - c / 2;
+    let sector: int = h / 60;
+    if (sector == 0) { return (x + m); }
+    if (sector == 1) { return (c + m); }
+    if (sector == 2) { return (c + m); }
+    if (sector == 3) { return (x + m); }
+    if (sector == 4) { return m; }
+    return m;
+}
+
+fn hsl_to_b(h: int, s: int, l: int): int {
+    let c: int = s * (1000 - (2 * l * 10 - 1000)) / 1000;
+    if (c < 0) { c = 0 - c; }
+    c = c / 10;
+    let x: int = _hsl_chroma_x(h, c);
+    let m: int = l * 255 / 100 - c / 2;
+    let sector: int = h / 60;
+    if (sector == 0) { return m; }
+    if (sector == 1) { return m; }
+    if (sector == 2) { return (x + m); }
+    if (sector == 3) { return (c + m); }
+    if (sector == 4) { return (c + m); }
+    return (x + m);
+}
+
+// hsl_to_packed(h, s, l): HSL → packed RGB int
+fn hsl_to_packed(h: int, s: int, l: int): int {
+    return rgb_pack(hsl_to_r(h, s, l), hsl_to_g(h, s, l), hsl_to_b(h, s, l));
+}
+
+// ─── RGB → HSL ────────────────────────────────────────────────────────────────
+
+// rgb_to_l(r, g, b): lightness 0-100
+fn rgb_to_l(r: int, g: int, b: int): int {
+    let mx: int = r;
+    if (g > mx) { mx = g; }
+    if (b > mx) { mx = b; }
+    let mn: int = r;
+    if (g < mn) { mn = g; }
+    if (b < mn) { mn = b; }
+    return (mx + mn) * 100 / 510;
+}
+
+// rgb_to_s(r, g, b): saturation 0-100
+fn rgb_to_s(r: int, g: int, b: int): int {
+    let mx: int = r;
+    if (g > mx) { mx = g; }
+    if (b > mx) { mx = b; }
+    let mn: int = r;
+    if (g < mn) { mn = g; }
+    if (b < mn) { mn = b; }
+    let c: int = mx - mn;
+    if (c == 0) { return 0; }
+    let l: int = (mx + mn) * 100 / 510;
+    if (l <= 50) { return c * 100 / (mx + mn); }
+    return c * 100 / (510 - mx - mn);
+}
+
+// rgb_to_h(r, g, b): hue 0-360
+fn rgb_to_h(r: int, g: int, b: int): int {
+    let mx: int = r;
+    if (g > mx) { mx = g; }
+    if (b > mx) { mx = b; }
+    let mn: int = r;
+    if (g < mn) { mn = g; }
+    if (b < mn) { mn = b; }
+    let c: int = mx - mn;
+    if (c == 0) { return 0; }
+    if (mx == r) {
+        let h: int = 60 * (g - b) / c;
+        if (h < 0) { h = h + 360; }
+        return h;
+    }
+    if (mx == g) {
+        return 60 * (b - r) / c + 120;
+    }
+    return 60 * (r - g) / c + 240;
+}

package/src/stdlib/geometry.mcrs

@@ -0,0 +1,124 @@
+// geometry.mcrs — 3D geometry helpers for Minecraft datapacks.
+//
+// Fixed-point convention: coordinates × 100 (so 1.0 block = 100 units)
+// Angles in degrees × 10000
+//
+// Requires: import "stdlib/math" (for sqrt_fx, sin_fixed, cos_fixed, abs)
+
+module library;
+
+// ─── Midpoint ─────────────────────────────────────────────────────────────────
+
+// midpoint_x/y/z(a, b): integer midpoint of two coordinates
+fn midpoint(a: int, b: int): int {
+    return (a + b) / 2;
+}
+
+// ─── Bounding box ─────────────────────────────────────────────────────────────
+
+// aabb_contains(px, py, pz, minx, miny, minz, maxx, maxy, maxz):
+// Returns 1 if point (px,py,pz) is inside axis-aligned bounding box, 0 otherwise.
+fn aabb_contains(px: int, py: int, pz: int,
+                 minx: int, miny: int, minz: int,
+                 maxx: int, maxy: int, maxz: int): int {
+    if (px < minx) { return 0; }
+    if (px > maxx) { return 0; }
+    if (py < miny) { return 0; }
+    if (py > maxy) { return 0; }
+    if (pz < minz) { return 0; }
+    if (pz > maxz) { return 0; }
+    return 1;
+}
+
+// sphere_contains(px, py, pz, cx, cy, cz, r):
+// Returns 1 if point is inside sphere (all coords in same unit, r is radius).
+// Avoids sqrt by comparing squared distances.
+fn sphere_contains(px: int, py: int, pz: int,
+                   cx: int, cy: int, cz: int,
+                   r: int): int {
+    let dx: int = px - cx;
+    let dy: int = py - cy;
+    let dz: int = pz - cz;
+    let dist_sq: int = dx * dx + dy * dy + dz * dz;
+    if (dist_sq <= r * r) { return 1; }
+    return 0;
+}
+
+// cylinder_contains(px, pz, cx, cz, r):
+// Returns 1 if point is inside vertical cylinder (ignores Y). 2D circle check.
+fn cylinder_contains(px: int, pz: int, cx: int, cz: int, r: int): int {
+    let dx: int = px - cx;
+    let dz: int = pz - cz;
+    if (dx * dx + dz * dz <= r * r) { return 1; }
+    return 0;
+}
+
+// ─── Parabola (projectile) ───────────────────────────────────────────────────
+//
+// MC projectile physics: velocity in blocks/tick, gravity ≈ 0.05 blocks/tick²
+// For a simplified fixed-point model:
+//   pos(t) = init_pos + init_vel * t - gravity_half * t²
+//
+// All values × 100 (1 block = 100 units), time in ticks.
+
+// parabola_y(y0, vy0, t): Y position at tick t.
+// y0: initial Y × 100, vy0: initial Y velocity × 100 (blocks/tick × 100)
+// gravity: 5 units/tick² (= 0.05 blocks/tick² × 100)
+fn parabola_y(y0: int, vy0: int, t: int): int {
+    return y0 + vy0 * t - 5 * t * t / 2;
+}
+
+// parabola_x(x0, vx0, t): horizontal X position at tick t (no drag, constant).
+fn parabola_x(x0: int, vx0: int, t: int): int {
+    return x0 + vx0 * t;
+}
+
+// parabola_land_t(vy0): approximate tick when projectile returns to Y=0.
+// t_land ≈ 2 * vy0 / gravity = 2 * vy0 / 5 (in fixed-point units)
+fn parabola_land_t(vy0: int): int {
+    return 2 * vy0 / 5;
+}
+
+// ─── Grid / tile math ────────────────────────────────────────────────────────
+
+// tile_of(coord): which tile a coordinate belongs to (floor division).
+// tile_of(250, 100) = 2 (block 2 when tile size = 100)
+fn tile_of(coord: int, tile_size: int): int {
+    if (coord >= 0) {
+        return coord / tile_size;
+    }
+    return (coord - tile_size + 1) / tile_size;
+}
+
+// tile_center(tile, tile_size): center coordinate of a tile
+fn tile_center(tile: int, tile_size: int): int {
+    return tile * tile_size + tile_size / 2;
+}
+
+// ─── Angle helpers ────────────────────────────────────────────────────────────
+
+// angle_normalize(deg): normalize angle to [0, 3600000) (degrees × 10000)
+fn angle_normalize(deg: int): int {
+    let a: int = deg;
+    while (a < 0) { a = a + 3600000; }
+    while (a >= 3600000) { a = a - 3600000; }
+    return a;
+}
+
+// angle_diff(a, b): signed shortest angular difference (degrees × 10000)
+// Result in (-1800000, 1800000]
+fn angle_diff(a: int, b: int): int {
+    let d: int = angle_normalize(b - a);
+    if (d > 1800000) { d = d - 3600000; }
+    return d;
+}
+
+// ─── Sun angle helper ────────────────────────────────────────────────────────
+
+// mc_day_angle(daytime): MC sun angle × 10000 from /time query daytime
+// Daytime 0 = dawn (sun at east = 90°), 6000 = noon (sun at south = 180°)
+fn mc_day_angle(daytime: int): int {
+    // MC daytime: 0-24000 ticks per day
+    // Sun angle = (daytime * 360 / 24000 + 90) mod 360
+    return ((daytime * 360 / 24000 + 90) % 360) * 10000;
+}

package/src/stdlib/list.mcrs

@@ -0,0 +1,125 @@
+// list.mcrs — Dynamic NBT-backed integer list operations.
+//
+// Lists are stored in NBT storage as int arrays.
+// The storage namespace is "rs:lists" and path is the variable name.
+//
+// IMPORTANT: These functions use raw() to emit NBT commands.
+// They operate on a NAMED list stored at a specific NBT path.
+// The caller must pass the list path as a namespace:path string.
+//
+// Example usage:
+//   // Create a list (declare as int[])
+//   let mylist: int[] = [1, 2, 3];
+//
+//   // Use list_* functions with raw() for dynamic operations.
+//   // Note: push/pop/len use raw() NBT commands directly.
+//
+// For fixed-size arrays, use int[] literals directly.
+// For dynamic lists, use the functions below.
+//
+// Storage convention: lists live at storage rs:lists <varname>
+
+module library;
+
+// list_len_of(ns, path): count elements in an NBT int list.
+// Returns the count stored in a scoreboard temp.
+// Use: raw("execute store result score $len __ns run data get storage ns:name path")
+// This is a convenience wrapper — in practice use raw() directly.
+
+// list_sum(a, b, c, d, e): sum of up to 5 int values (utility)
+fn list_sum5(a: int, b: int, c: int, d: int, e: int): int {
+    return a + b + c + d + e;
+}
+
+fn list_sum4(a: int, b: int, c: int, d: int): int {
+    return a + b + c + d;
+}
+
+fn list_sum3(a: int, b: int, c: int): int {
+    return a + b + c;
+}
+
+// list_min3 / list_max3: min/max over 3 values (useful for array-derived work)
+fn list_min3(a: int, b: int, c: int): int {
+    let m: int = a;
+    if (b < m) { m = b; }
+    if (c < m) { m = c; }
+    return m;
+}
+
+fn list_max3(a: int, b: int, c: int): int {
+    let m: int = a;
+    if (b > m) { m = b; }
+    if (c > m) { m = c; }
+    return m;
+}
+
+fn list_min5(a: int, b: int, c: int, d: int, e: int): int {
+    let m: int = a;
+    if (b < m) { m = b; }
+    if (c < m) { m = c; }
+    if (d < m) { m = d; }
+    if (e < m) { m = e; }
+    return m;
+}
+
+fn list_max5(a: int, b: int, c: int, d: int, e: int): int {
+    let m: int = a;
+    if (b > m) { m = b; }
+    if (c > m) { m = c; }
+    if (d > m) { m = d; }
+    if (e > m) { m = e; }
+    return m;
+}
+
+// ─── Sorting (in-register, fixed size) ───────────────────────────────────────
+
+// sort3_asc: sort 3 values ascending, returns packed as 3 separate ints via
+// side-effect scoreboard. Caller reads $sort3_a, $sort3_b, $sort3_c.
+// (This is a placeholder — proper NBT list sort requires runtime support.)
+
+// swap helper: sort2 returns the smaller value
+fn sort2_min(a: int, b: int): int {
+    if (a <= b) { return a; }
+    return b;
+}
+
+fn sort2_max(a: int, b: int): int {
+    if (a >= b) { return a; }
+    return b;
+}
+
+// bubble_sort3: returns sorted value at position pos (0=min, 1=mid, 2=max)
+fn sort3(a: int, b: int, c: int, pos: int): int {
+    // Sorting network for 3 elements
+    let x: int = a;
+    let y: int = b;
+    let z: int = c;
+    // Step 1: compare-swap (x, y)
+    if (x > y) { let tmp: int = x; x = y; y = tmp; }
+    // Step 2: compare-swap (y, z)
+    if (y > z) { let tmp: int = y; y = z; z = tmp; }
+    // Step 3: compare-swap (x, y)
+    if (x > y) { let tmp: int = x; x = y; y = tmp; }
+    if (pos == 0) { return x; }
+    if (pos == 1) { return y; }
+    return z;
+}
+
+// ─── Statistics ──────────────────────────────────────────────────────────────
+
+// avg3(a, b, c): integer average (truncated)
+fn avg3(a: int, b: int, c: int): int {
+    return (a + b + c) / 3;
+}
+
+fn avg5(a: int, b: int, c: int, d: int, e: int): int {
+    return (a + b + c + d + e) / 5;
+}
+
+// clamp_list3(a, b, c, lo, hi): clamp all 3 values
+fn clamp3(a: int, lo: int, hi: int): int {
+    if (a < lo) { return lo; }
+    if (a > hi) { return hi; }
+    return a;
+}

package/src/stdlib/math.mcrs

@@ -300,3 +300,93 @@ fn smootherstep(lo: int, hi: int, x: int) -> int {
     let inner: int = 10000 - 15 * t10 + 6 * t2 / 100;
     return t3 * inner / 100000;
 }
+
+// AUTO-GENERATED by redscript tune — DO NOT EDIT
+// Adapter: ln-polynomial | Date: 2026-03-17
+// max_error: 0.000557 | mae: 0.000186 | estimated_cmds: 27
+// Run `redscript tune --adapter ln-polynomial` to regenerate
+//
+// atanh series coefficients (×10000 scale):
+//   A1 = 20010  (theoretical 2×10000 = 20000)
+//   A3 = 6856  (theoretical 2/3×10000 = 6667)
+//   A5 = 2539  (theoretical 2/5×10000 = 4000)
+
+fn ln(x: int): int {
+    // Input x: fixed-point ×10000; returns ln(x/10000)×10000
+    // Valid range: x ∈ [100, 1000000]  (0.01 ~ 100.0)
+    // max_error: 0.000557 (in ×10000 units, i.e. 0.00000006 in real units)
+
+    let scale: int = 10000;
+    let ln2: int = 6931;
+    let A1: int = 20010;
+    let A3: int = 6856;
+    let A5: int = 2539;
+
+    // Step 1: range reduction — bring x into [scale, 2*scale)
+    let xr: int = x;
+    let k: int = 0;
+    while (xr < scale) {
+        xr = xr * 2;
+        k = k - 1;
+    }
+    while (xr >= scale * 2) {
+        xr = xr / 2;
+        k = k + 1;
+    }
+
+    // Step 2: s = (xr - scale) * scale / (xr + scale)
+    let s: int = (xr - scale) * scale / (xr + scale);
+
+    // Step 3: atanh series ln(xr/scale) ≈ A1*s + A3*s³ + A5*s⁵ (all /scale)
+    let s2: int = s * s / scale;
+    let s3: int = s * s2;
+    let s5: int = s3 * s2;
+    let lnxr: int = A1 * s / scale + A3 * s3 / scale + A5 * s5 / scale;
+
+    // Step 4: ln(x) = k*ln(2) + ln(xr/scale)
+    return k * ln2 + lnxr;
+}
+
+// sqrt_fx(x): fixed-point sqrt, scale ×10000
+// sqrt_fx(10000) == 10000  (√1.0 = 1.0)
+// sqrt_fx(20000) ≈ 14142   (√2.0 ≈ 1.4142)
+// sqrt_fx(40000) == 20000  (√4.0 = 2.0)
+fn sqrt_fx(x: int) -> int {
+    return isqrt(x * 100) * 100;
+}
+
+// exp_fx(x): e^(x/10000) × 10000, fixed-point ×10000
+// exp_fx(0)     == 10000  (e^0 = 1.0)
+// exp_fx(10000) ≈ 27183   (e^1 ≈ 2.7183)
+// exp_fx(6931)  ≈ 20000   (e^ln2 = 2.0)
+// exp_fx(-10000) ≈ 3679   (e^-1 ≈ 0.3679)
+// Valid range: x ∈ [-100000, 100000] (real: -10.0 to 10.0)
+fn exp_fx(x: int): int {
+    // Range reduction: x = k*ln2 + r, r in [0, 6931]
+    let ln2: int = 6931;
+    let k: int = x / ln2;
+    let r: int = x - k * ln2;
+    if (r < 0) { r = r + ln2; k = k - 1; }
+
+    // 6-term Horner-form Taylor: e^r ≈ 1 + r + r²/2! + r³/3! + ...
+    // Coefficients scaled ×10000, nested for numerical stability
+    let t: int = 14;
+    t = 83   + t * r / 10000;
+    t = 417  + t * r / 10000;
+    t = 1667 + t * r / 10000;
+    t = 5000 + t * r / 10000;
+    t = 10000 + t * r / 10000;
+    let er: int = 10000 + t * r / 10000;
+
+    // Scale by 2^k
+    if (k >= 0) {
+        let i: int = 0;
+        while (i < k) { er = er * 2; i = i + 1; }
+    }
+    if (k < 0) {
+        let i: int = 0;
+        let nk: int = 0 - k;
+        while (i < nk) { er = er / 2; i = i + 1; }
+    }
+    return er;
+}

package/src/stdlib/math_hp.mcrs

@@ -0,0 +1,65 @@
+// math_hp.mcrs — High-precision trig using MC entity rotation trick.
+//
+// MC internally uses Java Math.sin/cos (double precision).
+// By teleporting a Marker entity one block in its local forward direction,
+// Pos[0] = cos(θ) and Pos[2] = sin(θ) with ~15 significant figures.
+//
+// SCALE: angles in degrees × 10000 (e.g. 900000 = 90°)
+//        outputs × 10000 (e.g. 10000 = 1.0, -7071 ≈ sin 45°)
+//
+// ⚠ SETUP REQUIRED: Call init_trig() in your @load function:
+//     @load fn setup() { init_trig(); }
+//
+// Usage:
+//   import "stdlib/math_hp"
+//   @load fn setup() { init_trig(); }
+//   fn my_fn() {
+//       let s: int = sin_hp(450000);   // sin(45°) ≈ 7071
+//       let c: int = cos_hp(450000);   // cos(45°) ≈ 7071
+//   }
+
+module library;
+
+// Internal tag for the helper Marker entity.
+// Do NOT kill or modify entities with this tag.
+let _TRIG_TAG: string = "rs_trig";
+
+// init_trig(): create the Marker entity used by sin_hp/cos_hp.
+// Safe to call multiple times (uses execute unless entity).
+// Must be called from your @load function.
+@require_on_load(init_trig)
+fn init_trig() {
+    raw("execute unless entity @e[tag=rs_trig,limit=1] run summon minecraft:marker ~ 0 ~ {Tags:[\"rs_trig\"]}");
+}
+
+// sin_hp(angle): high-precision sine.
+// angle: degrees × 10000 (e.g. 450000 = 45°, 900000 = 90°)
+// returns: sin(angle/10000°) × 10000
+// Example: sin_hp(900000) == 10000, sin_hp(0) == 0, sin_hp(450000) ≈ 7071
+@require_on_load(init_trig)
+fn sin_hp(angle: int): int {
+    // Step 1: store angle into scoreboard, then use execute store to set Rotation[0]
+    scoreboard_set("$sin_hp_in", "__rs_math_hp", angle);
+    raw("execute store result entity @e[tag=rs_trig,limit=1] Rotation[0] float 0.0001 run scoreboard players get $sin_hp_in __rs_math_hp");
+    // Step 2: teleport Marker 1 block forward along its facing direction
+    raw("execute as @e[tag=rs_trig,limit=1] rotated as @s positioned 0.0 0.0 0.0 run tp @s ^ ^ ^1 ~ ~");
+    // Step 3: read Pos[2] (= sin θ), scale ×10000
+    raw("execute store result score $sin_hp_out __rs_math_hp run data get entity @e[tag=rs_trig,limit=1] Pos[2] 10000.0");
+    // Step 4: reset Marker position
+    raw("tp @e[tag=rs_trig,limit=1] 0 0 0");
+    return scoreboard_get("$sin_hp_out", "__rs_math_hp");
+}
+
+// cos_hp(angle): high-precision cosine.
+// angle: degrees × 10000 (e.g. 450000 = 45°)
+// returns: cos(angle/10000°) × 10000
+@require_on_load(init_trig)
+fn cos_hp(angle: int): int {
+    scoreboard_set("$cos_hp_in", "__rs_math_hp", angle);
+    raw("execute store result entity @e[tag=rs_trig,limit=1] Rotation[0] float 0.0001 run scoreboard players get $cos_hp_in __rs_math_hp");
+    raw("execute as @e[tag=rs_trig,limit=1] rotated as @s positioned 0.0 0.0 0.0 run tp @s ^ ^ ^1 ~ ~");
+    // Pos[0] = cos θ
+    raw("execute store result score $cos_hp_out __rs_math_hp run data get entity @e[tag=rs_trig,limit=1] Pos[0] 10000.0");
+    raw("tp @e[tag=rs_trig,limit=1] 0 0 0");
+    return scoreboard_get("$cos_hp_out", "__rs_math_hp");
+}

package/src/stdlib/random.mcrs

@@ -0,0 +1,67 @@
+// random.mcrs — Pseudo-random number generators for RedScript datapacks.
+//
+// LCG (Linear Congruential Generator):
+//   Simple, fast, sufficient for most game use-cases.
+//   Parameters: a=1664525, c=1013904223 (Numerical Recipes)
+//   Modulus: 2^32 via int32 overflow (free in MC scoreboard arithmetic).
+//
+// Usage:
+//   let seed: int = 12345;  // any non-zero starting value
+//   seed = next_lcg(seed);  // advance state
+//   let roll: int = random_range(seed, 0, 100);
+
+module library;
+
+// next_lcg(seed): advance LCG state, return next pseudo-random int32.
+// The returned value is also the new seed for the next call.
+fn next_lcg(seed: int): int {
+    return seed * 1664525 + 1013904223;
+}
+
+// random_range(seed, lo, hi): return integer in [lo, hi).
+// seed should already be the output of next_lcg.
+fn random_range(seed: int, lo: int, hi: int): int {
+    let r: int = seed;
+    if (r < 0) { r = 0 - r; }
+    return lo + r % (hi - lo);
+}
+
+// random_bool(seed): return 0 or 1 with equal probability.
+fn random_bool(seed: int): int {
+    let r: int = seed;
+    if (r < 0) { r = 0 - r; }
+    return r % 2;
+}
+
+// ─── PCG (Permuted Congruential Generator) ───────────────────────────────────
+// Better statistical quality than LCG — passes more randomness tests.
+// Requires stdlib/bits for bit_xor, bit_shr.
+//
+// PCG-XSH-RR (32-bit output from 64-bit state is approximated here with two
+// int32 words; this is a simplified PCG32 variant that fits MC scoreboard).
+//
+// Reference: https://www.pcg-random.org/
+//
+// Usage: maintain two state variables (hi, lo); update both each call.
+
+// pcg_next_lo(state_lo, state_hi): advance PCG state (low word).
+// Returns new low word. Use with pcg_next_hi.
+fn pcg_next_lo(state_lo: int): int {
+    return state_lo * 747796405 + 2891336453;
+}
+
+// pcg_next_hi(state_lo, state_hi): advance PCG state (high word).
+fn pcg_next_hi(state_hi: int, state_lo: int): int {
+    return state_hi * 747796405 + state_lo;
+}
+
+// pcg_output(state_lo): extract output value from PCG low word.
+// Applies XSH-RR output permutation (simplified to XOR-shift).
+fn pcg_output(state_lo: int): int {
+    let xsh: int = state_lo;
+    // xsh = ((state >> 18) ^ state) >> 27   (simplified: use single xor-shift)
+    let shifted: int = xsh / 262144;  // >> 18
+    let xored: int = xsh / 32 + shifted;  // approximation of XSH
+    if (xored < 0) { xored = 0 - xored; }
+    return xored;
+}