redscript-mc 1.2.24 → 1.2.26

package/src/stdlib/advanced.mcrs

@@ -0,0 +1,249 @@
+// advanced.mcrs — Higher-order integer math and "fun" algorithms.
+//
+// Requires: math.mcrs (for lerp, smoothstep, mulfix, abs, isqrt, sqrt_fixed)
+//
+// Category 1: Number theory  — fib, is_prime, collatz_steps, digit_sum, reverse_int, mod_pow
+// Category 2: Hashing/noise  — hash_int, noise1d
+// Category 3: Curves         — bezier_quad, bezier_cubic
+// Category 4: Fractals 🤯    — mandelbrot_iter (fixed-point complex arithmetic)
+
+module library;
+
+// ─── Category 1: Number theory ───────────────────────────────────────────────
+
+// Fibonacci number F(n) using simple iteration.
+// Overflow: F(46) = 1836311903 ≈ INT_MAX; use n ≤ 46.
+// fib(0) == 0, fib(1) == 1, fib(10) == 55
+fn fib(n: int) -> int {
+    if (n <= 0) { return 0; }
+    if (n == 1) { return 1; }
+    let a: int = 0;
+    let b: int = 1;
+    let i: int = 2;
+    while (i <= n) {
+        let c: int = a + b;
+        a = b;
+        b = c;
+        i = i + 1;
+    }
+    return b;
+}
+
+// Primality test by trial division up to √n.
+// Returns 1 if n is prime, 0 otherwise.
+// is_prime(2) == 1, is_prime(4) == 0, is_prime(97) == 1
+fn is_prime(n: int) -> int {
+    if (n < 2) { return 0; }
+    if (n == 2) { return 1; }
+    if (n % 2 == 0) { return 0; }
+    let i: int = 3;
+    while (i * i <= n) {
+        if (n % i == 0) { return 0; }
+        i = i + 2;
+    }
+    return 1;
+}
+
+// Number of steps in the Collatz sequence starting at n until reaching 1.
+// collatz_steps(1)  == 0
+// collatz_steps(6)  == 8
+// collatz_steps(27) == 111   (world record among small numbers)
+fn collatz_steps(n: int) -> int {
+    if (n <= 1) { return 0; }
+    let x: int = n;
+    let steps: int = 0;
+    while (x != 1) {
+        if (x % 2 == 0) {
+            x = x / 2;
+        } else {
+            x = 3 * x + 1;
+        }
+        steps = steps + 1;
+    }
+    return steps;
+}
+
+// Sum of decimal digits.  Negative input uses absolute value.
+// digit_sum(123) == 6, digit_sum(0) == 0
+fn digit_sum(n: int) -> int {
+    let x: int = n;
+    if (x < 0) { x = 0 - x; }
+    if (x == 0) { return 0; }
+    let sum: int = 0;
+    while (x > 0) {
+        sum = sum + x % 10;
+        x = x / 10;
+    }
+    return sum;
+}
+
+// Count decimal digits.  0 has 1 digit.  Negative: counts absolute digits.
+// count_digits(0) == 1, count_digits(100) == 3
+fn count_digits(n: int) -> int {
+    let x: int = n;
+    if (x < 0) { x = 0 - x; }
+    if (x == 0) { return 1; }
+    let cnt: int = 0;
+    while (x > 0) {
+        cnt = cnt + 1;
+        x = x / 10;
+    }
+    return cnt;
+}
+
+// Reverse the decimal digits of an integer.  Sign is preserved.
+// reverse_int(12345) == 54321, reverse_int(-42) == -24
+fn reverse_int(n: int) -> int {
+    let x: int = n;
+    let neg: int = 0;
+    if (x < 0) { x = 0 - x; neg = 1; }
+    let result: int = 0;
+    while (x > 0) {
+        result = result * 10 + x % 10;
+        x = x / 10;
+    }
+    if (neg == 1) { return 0 - result; }
+    return result;
+}
+
+// Modular exponentiation: (base ^ exp) mod m  using fast O(log exp) squaring.
+// IMPORTANT: m must be ≤ 46340 to avoid b*b overflow (46340² < INT_MAX).
+// mod_pow(2, 10, 1000) == 24   (1024 mod 1000)
+fn mod_pow(base: int, exp: int, m: int) -> int {
+    if (m == 1) { return 0; }
+    let result: int = 1;
+    let b: int = base % m;
+    if (b < 0) { b = b + m; }
+    let e: int = exp;
+    while (e > 0) {
+        if (e % 2 == 1) {
+            result = result * b % m;
+        }
+        b = b * b % m;
+        e = e / 2;
+    }
+    return result;
+}
+
+// ─── Category 2: Hashing & noise ─────────────────────────────────────────────
+
+// Integer hash function.  Output is non-negative, range [0, ~2 × 10⁹).
+// Deterministic, no randomness — same input always produces the same output.
+// Suitable as a seeded pseudo-random value for procedural generation.
+// hash_int(0) != hash_int(1), repeatable across runs.
+fn hash_int(n: int) -> int {
+    let h: int = n;
+    if (h < 0) { h = 0 - h; }
+    h = h % 46340;               // Clamp so h² fits in int32
+    h = h * 46337 + 97;          // 46337 is prime; h*46337 ≤ 46340*46337 < INT_MAX
+    if (h < 0) { h = 0 - h; }
+    h = h % 46340;
+    h = h * 46337 + 211;
+    if (h < 0) { h = 0 - h; }
+    return h;
+}
+
+// 1D value noise.  Input x in fixed-point (scale = 1000).
+// Output in [0, 999] — smoothly interpolated between hashed lattice points.
+// noise1d(0) == noise1d(0), noise1d(500) is between noise1d(0) and noise1d(1000).
+fn noise1d(x: int) -> int {
+    let ix: int = x / 1000;
+    let frac: int = x % 1000;
+    // Handle negative x so frac is always in [0, 999]
+    if (frac < 0) {
+        ix = ix - 1;
+        frac = frac + 1000;
+    }
+    let h0: int = hash_int(ix) % 1000;
+    let h1: int = hash_int(ix + 1) % 1000;
+    if (h0 < 0) { h0 = 0 - h0; }
+    if (h1 < 0) { h1 = 0 - h1; }
+    // Smoothstep for C1 continuity
+    let t: int = smoothstep(0, 1000, frac);
+    return lerp(h0, h1, t);
+}
+
+// ─── Category 3: Curves ──────────────────────────────────────────────────────
+
+// Quadratic Bezier: B(t) = lerp(lerp(p0,p1,t), lerp(p1,p2,t), t)
+// De Casteljau's algorithm — numerically stable, safe for large coordinates.
+// t in [0, 1000] (fixed-point).
+//
+// bezier_quad(0, 500, 1000, 0)    == 0     (t=0: start)
+// bezier_quad(0, 500, 1000, 500)  == 500   (t=500: midpoint of curve)
+// bezier_quad(0, 500, 1000, 1000) == 1000  (t=1000: end)
+// bezier_quad(0, 1000, 0, 500)    == 500   (arch at midpoint)
+fn bezier_quad(p0: int, p1: int, p2: int, t: int) -> int {
+    let m0: int = lerp(p0, p1, t);
+    let m1: int = lerp(p1, p2, t);
+    return lerp(m0, m1, t);
+}
+
+// Cubic Bezier: 4-point curve using De Casteljau's algorithm.
+// t in [0, 1000].
+// bezier_cubic(0, 333, 667, 1000, 0)    == 0
+// bezier_cubic(0, 333, 667, 1000, 1000) == 1000
+fn bezier_cubic(p0: int, p1: int, p2: int, p3: int, t: int) -> int {
+    let m0: int = lerp(p0, p1, t);
+    let m1: int = lerp(p1, p2, t);
+    let m2: int = lerp(p2, p3, t);
+    let n0: int = lerp(m0, m1, t);
+    let n1: int = lerp(m1, m2, t);
+    return lerp(n0, n1, t);
+}
+
+// ─── Category 4: Fractals 🤯 ─────────────────────────────────────────────────
+
+// Mandelbrot set iteration count.
+//
+// cx, cy: fixed-point coordinates of the complex number c = cx/1000 + i*cy/1000
+//   cx = -2000..1000  (i.e. real part -2.0..1.0)
+//   cy = -1000..1000  (imaginary part -1.0..1.0)
+//
+// Returns the number of iterations before |z| > 2 (escape), or max_iter if
+// the point is in the Mandelbrot set.  Use the return value to colour blocks!
+//
+// Points in the set: mandelbrot_iter(-1000, 0, 100) == 100  (c = -1+0i)
+// Points outside:   mandelbrot_iter(1000, 0, 100)  == 0   (c = 1+0i, escapes immediately)
+// Boundary region:  mandelbrot_iter(-500, 500, 50) → varies
+//
+// Algorithm: z₀ = 0, z_{n+1} = z_n² + c
+//   z_n = (zr + zi·i),  z_n² = zr²−zi² + 2·zr·zi·i
+//   Escape when |z|² = (zr²+zi²)/10⁶ > 4  ↔  mulfix(zr,zr)+mulfix(zi,zi) > 4000
+fn mandelbrot_iter(cx: int, cy: int, max_iter: int) -> int {
+    let zr: int = 0;
+    let zi: int = 0;
+    let i: int = 0;
+    while (i < max_iter) {
+        let zr2: int = mulfix(zr, zr) - mulfix(zi, zi) + cx;
+        let zi2: int = 2 * mulfix(zr, zi) + cy;
+        zr = zr2;
+        zi = zi2;
+        if (mulfix(zr, zr) + mulfix(zi, zi) > 4000) {
+            return i;
+        }
+        i = i + 1;
+    }
+    return max_iter;
+}
+
+// Julia set iteration count (generalised Mandelbrot with fixed c and variable z₀).
+// z0r, z0i: starting point (fixed-point, scale=1000)
+// cr, ci:   constant c   (fixed-point, scale=1000)
+// Same escape condition as mandelbrot_iter.
+fn julia_iter(z0r: int, z0i: int, cr: int, ci: int, max_iter: int) -> int {
+    let zr: int = z0r;
+    let zi: int = z0i;
+    let i: int = 0;
+    while (i < max_iter) {
+        let zr2: int = mulfix(zr, zr) - mulfix(zi, zi) + cr;
+        let zi2: int = 2 * mulfix(zr, zi) + ci;
+        zr = zr2;
+        zi = zi2;
+        if (mulfix(zr, zr) + mulfix(zi, zi) > 4000) {
+            return i;
+        }
+        i = i + 1;
+    }
+    return max_iter;
+}

package/src/stdlib/math.mcrs

@@ -1,49 +1,289 @@
-// Integer math helpers for RedScript datapacks.
+// math.mcrs — Integer & fixed-point math helpers for RedScript datapacks.
+//
+// Fixed-point convention: scale = 1000
+//   1.0  → 1000
+//   3.14 → 3140
+//   Use `sqrt_fixed` / `lerp` for sub-integer precision.
+//
+// Phase 1: basic integer helpers (abs, sign, min, max, clamp, lerp)
+// Phase 2: iterative algorithms (isqrt, sqrt_fixed, pow_int, gcd)
+// Phase 3: trig (sin_fixed, cos_fixed) — lookup table in NBT storage
+
+// All functions in this file are library-mode: only compiled into the
+// datapack if actually called from user code.  Use via `librarySources`
+// compile option or concatenate with user code (module library; handles it).
+module library;
+// Phase 4: number theory & utilities (lcm, map, ceil_div, log2_int)
+
+// ─── Phase 1: Basic integer helpers ──────────────────────────────────────────
 
 fn abs(x: int) -> int {
     if (x < 0) {
-        return -x;
-    } else {
-        return x;
+        return 0 - x;
+    }
+    return x;
+}
+
+fn sign(x: int) -> int {
+    if (x > 0) {
+        return 1;
+    }
+    if (x < 0) {
+        return -1;
     }
+    return 0;
 }
 
 fn min(a: int, b: int) -> int {
     if (a < b) {
         return a;
-    } else {
-        return b;
     }
+    return b;
 }
 
 fn max(a: int, b: int) -> int {
     if (a > b) {
         return a;
-    } else {
-        return b;
     }
+    return b;
 }
 
 fn clamp(x: int, lo: int, hi: int) -> int {
     if (x < lo) {
         return lo;
-    } else {
-        if (x > hi) {
-            return hi;
-        } else {
+    }
+    if (x > hi) {
+        return hi;
+    }
+    return x;
+}
+
+// Linear interpolation (fixed-point t, t in [0, 1000])
+// lerp(0, 1000, 500) == 500
+// lerp(100, 200, 750) == 175
+fn lerp(a: int, b: int, t: int) -> int {
+    return a + (b - a) * t / 1000;
+}
+
+// ─── Phase 2: Iterative algorithms ───────────────────────────────────────────
+
+// Integer square root: floor(sqrt(n))
+// Uses Newton's method, converges in ≤16 iterations for all int32.
+// isqrt(9) == 3, isqrt(10) == 3, isqrt(0) == 0
+fn isqrt(n: int) -> int {
+    if (n <= 0) {
+        return 0;
+    }
+    let x: int = n;
+    let i: int = 0;
+    while (i < 16) {
+        let next: int = (x + n / x) / 2;
+        if (next >= x) {
             return x;
         }
+        x = next;
+        i = i + 1;
     }
+    return x;
 }
 
-fn sign(x: int) -> int {
-    if (x > 0) {
+// Fixed-point sqrt (scale = 1000)
+// sqrt_fixed(2000) ≈ 1414  (√2 × 1000)
+// sqrt_fixed(1000) == 1000 (√1 × 1000)
+fn sqrt_fixed(x: int) -> int {
+    return isqrt(x * 1000);
+}
+
+// Integer power: base^exp  (exp ≥ 0)
+// Fast exponentiation by squaring: O(log exp)
+// pow_int(2, 10) == 1024, pow_int(3, 0) == 1
+fn pow_int(base: int, exp: int) -> int {
+    if (exp <= 0) {
         return 1;
-    } else {
-        if (x < 0) {
-            return -1;
-        } else {
-            return 0;
+    }
+    let result: int = 1;
+    let b: int = base;
+    let e: int = exp;
+    while (e > 0) {
+        if (e % 2 == 1) {
+            result = result * b;
         }
+        b = b * b;
+        e = e / 2;
+    }
+    return result;
+}
+
+// Greatest common divisor (Euclidean algorithm)
+// gcd(12, 8) == 4, gcd(0, 5) == 5
+fn gcd(a: int, b: int) -> int {
+    // Inline abs to avoid cross-function scoreboard variable collision.
+    let x: int = a;
+    if (x < 0) { x = 0 - x; }
+    let y: int = b;
+    if (y < 0) { y = 0 - y; }
+    while (y > 0) {
+        let r: int = x % y;
+        x = y;
+        y = r;
+    }
+    return x;
+}
+
+// ─── Phase 3: Trigonometry ────────────────────────────────────────────────────
+//
+// sin/cos lookup table stored in NBT storage (math:tables).
+// 91 entries covering 0-90°; other quadrants derived by symmetry.
+// All values are sin(i°) × 1000, rounded to nearest integer.
+//
+// Accuracy: ≤ 1 unit error (≤0.1% relative) for all integer degrees.
+// Cost: ~4 MC commands per call + 1 NBT read per call (O(1)).
+
+// Initialize the sin lookup table.
+// This function has NO @load — it is called from __load only when sin_fixed
+// or cos_fixed are compiled into the project (via @requires).  If you only
+// use Phase 1/2/4 functions, this never runs and adds zero overhead.
+fn _math_init() {
+    storage_set_array("math:tables", "sin",
+        "[0, 17, 35, 52, 70, 87, 105, 122, 139, 156, 174, 191, 208, 225, 242, 259, 276, 292, 309, 326, 342, 358, 375, 391, 407, 423, 438, 454, 469, 485, 500, 515, 530, 545, 559, 574, 588, 602, 616, 629, 643, 656, 669, 682, 695, 707, 719, 731, 743, 755, 766, 777, 788, 799, 809, 819, 829, 839, 848, 857, 866, 875, 883, 891, 899, 906, 914, 921, 927, 934, 940, 946, 951, 956, 961, 966, 970, 974, 978, 982, 985, 988, 990, 993, 995, 996, 998, 999, 999, 1000, 1000]"
+    );
+}
+
+// sin_fixed(deg) → sin(deg°) × 1000   (integer degrees, any value)
+// sin_fixed(30)  == 500
+// sin_fixed(90)  == 1000
+// sin_fixed(180) == 0
+// sin_fixed(270) == -1000
+//
+// @require_on_load(_math_init): the sin lookup table is written to NBT storage at
+// world load automatically when this function is included in a project.
+@require_on_load(_math_init)
+fn sin_fixed(deg: int) -> int {
+    // Normalise to [0, 359]
+    let d: int = deg % 360;
+    if (d < 0) { d = d + 360; }
+
+    // Quadrant reduction to first quadrant index [0, 90]
+    if (d <= 90) {
+        return storage_get_int("math:tables", "sin", d);
+    }
+    if (d <= 180) {
+        return storage_get_int("math:tables", "sin", 180 - d);
+    }
+    if (d <= 270) {
+        let idx: int = d - 180;
+        return 0 - storage_get_int("math:tables", "sin", idx);
+    }
+    // d in (270, 360)
+    let idx: int = 360 - d;
+    return 0 - storage_get_int("math:tables", "sin", idx);
+}
+
+// cos_fixed(deg) → cos(deg°) × 1000   (integer degrees, any value)
+// cos_fixed(0)   == 1000
+// cos_fixed(90)  == 0
+// cos_fixed(180) == -1000
+@require_on_load(_math_init)
+fn cos_fixed(deg: int) -> int {
+    return sin_fixed(deg + 90);
+}
+
+// ─── Phase 4: Number theory & utilities ──────────────────────────────────────
+
+// Least common multiple
+// lcm(4, 6) == 12, lcm(0, 5) == 0
+fn lcm(a: int, b: int) -> int {
+    let g: int = gcd(a, b);
+    if (g == 0) { return 0; }
+    return a / g * b;
+}
+
+// Range map: scale x from [in_lo, in_hi] onto [out_lo, out_hi].
+// Uses integer arithmetic — multiply before dividing to preserve precision.
+// map(5, 0, 10, 0, 100) == 50
+// map(1, 0, 10, 100, 200) == 110
+fn map(x: int, in_lo: int, in_hi: int, out_lo: int, out_hi: int) -> int {
+    let in_range: int = in_hi - in_lo;
+    if (in_range == 0) { return out_lo; }
+    return out_lo + (x - in_lo) * (out_hi - out_lo) / in_range;
+}
+
+// Ceiling division: ⌈a / b⌉  (b > 0 required)
+// ceil_div(7, 3) == 3, ceil_div(6, 3) == 2
+fn ceil_div(a: int, b: int) -> int {
+    return (a + b - 1) / b;
+}
+
+// Integer log base 2: ⌊log₂(n)⌋
+// log2_int(1) == 0, log2_int(8) == 3, log2_int(7) == 2
+// Returns -1 for n ≤ 0 (error sentinel).
+fn log2_int(n: int) -> int {
+    if (n <= 0) { return -1; }
+    let result: int = 0;
+    let v: int = n;
+    while (v > 1) {
+        v = v / 2;
+        result = result + 1;
     }
+    return result;
+}
+
+// ─── Phase 5: Fixed-point arithmetic & easing ────────────────────────────────
+// Vector functions (dot2d, cross2d, length2d_fixed, manhattan, chebyshev,
+// atan2_fixed, rotate2d, normalize2d, etc.) have moved to vec.mcrs.
+
+// Fixed-point multiply: (a × b) / 1000
+// Use instead of a*b when both operands are fixed-point (scale=1000),
+// e.g. mulfix(sin_fixed(30), cos_fixed(45)) instead of sin*cos which overflows.
+// mulfix(500, 707) == 353   (≈ 0.5 × 0.707)
+fn mulfix(a: int, b: int) -> int {
+    return a * b / 1000;
+}
+
+// Fixed-point divide: (a × 1000) / b
+// Inverse of mulfix; produces a fixed-point result from two integers.
+// divfix(1, 3) == 333   (≈ 0.333)
+fn divfix(a: int, b: int) -> int {
+    if (b == 0) { return 0; }
+    return a * 1000 / b;
+}
+
+// Smooth Hermite interpolation (Ken Perlin's smoothstep).
+// Returns a value in [0, 1000] (fixed-point scale = 1000).
+// Eases in AND out — useful for animations and value transitions.
+//
+// smoothstep(0, 100, 0)   == 0
+// smoothstep(0, 100, 50)  == 500
+// smoothstep(0, 100, 100) == 1000
+// smoothstep(0, 100, 25)  == 156   (≈ 3×0.25² − 2×0.25³ = 0.15625)
+fn smoothstep(lo: int, hi: int, x: int) -> int {
+    let range: int = hi - lo;
+    if (range == 0) { return 0; }
+    // t in [0, 1000]
+    let t: int = (x - lo) * 1000 / range;
+    if (t < 0) { t = 0; }
+    if (t > 1000) { t = 1000; }
+    // f(t) = t² × (3 − 2t) / 1000   (all in scale=1000)
+    // Rewrite to avoid int32 overflow: use t/10 as intermediate
+    let t10: int = t / 10;   // [0, 100], avoids 1000² = 10⁶ overflow
+    return t10 * t10 * (3000 - 2 * t) / 10000;
+}
+
+// Smoother step (Perlin's order-5): 6t⁵ − 15t⁴ + 10t³
+// Higher-order derivative at edges → smoother acceleration curve.
+// smootherstep(0, 100, 25) ≈ 103
+fn smootherstep(lo: int, hi: int, x: int) -> int {
+    let range: int = hi - lo;
+    if (range == 0) { return 0; }
+    let t: int = (x - lo) * 1000 / range;
+    if (t < 0) { t = 0; }
+    if (t > 1000) { t = 1000; }
+    // f(t) = t³ × (10 − t × (15 − 6t) / 1000) / 1000000
+    // Compute in stages to stay within int32
+    let t10: int = t / 10;          // [0, 100]
+    let t2: int = t10 * t10;        // [0, 10000]
+    let t3: int = t2 * t10 / 100;  // [0, 10000]
+    // 10t³ − 15t⁴ + 6t⁵ = t³(10 − 15t + 6t²)  at scale=1000
+    let inner: int = 10000 - 15 * t10 + 6 * t2 / 100;
+    return t3 * inner / 100000;
 }