redscript-mc 1.2.25 → 1.2.26

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;
 }

package/src/stdlib/vec.mcrs

@@ -0,0 +1,246 @@
+// vec.mcrs — 2D and 3D vector math for RedScript datapacks.
+//
+// Fixed-point convention: scale = 1000  (same as math.mcrs)
+//   A unit vector has components in [-1000, 1000].
+//   A position / displacement in block coordinates uses raw integers.
+//
+// Dependency: import "math.mcrs" before this file (or compile with librarySources).
+//   Requires: abs, sqrt_fixed, sin_fixed, cos_fixed, lerp, mulfix, length2d_fixed
+//
+// Phase 1: 2D geometry (dot, cross, distance, length, normalize, lerp)
+// Phase 2: 2D direction (rotate, atan2)
+// Phase 3: 3D geometry (dot, cross, length, distance, manhattan, chebyshev)
+
+module library;
+
+// ─── Phase 1: 2D geometry ────────────────────────────────────────────────────
+
+// Dot product of two 2D integer vectors.
+// dot2d(3, 4, 3, 4) == 25
+fn dot2d(ax: int, ay: int, bx: int, by: int) -> int {
+    return ax * bx + ay * by;
+}
+
+// Z-component of the 3D cross product (ax*by − ay*bx).
+// Positive: b is counter-clockwise from a.
+// cross2d(1, 0, 0, 1) == 1
+fn cross2d(ax: int, ay: int, bx: int, by: int) -> int {
+    return ax * by - ay * bx;
+}
+
+// Euclidean length of a 2D integer vector, result in fixed-point (×1000).
+// length2d_fixed(3, 4) == 5000   (√25 × 1000)
+// Note: |x|, |y| ≤ ~1000 to avoid overflow; scale larger vectors down first.
+fn length2d_fixed(x: int, y: int) -> int {
+    return sqrt_fixed((x * x + y * y) * 1000);
+}
+
+// Euclidean distance between two integer-coordinate points, result ×1000.
+// distance2d_fixed(0, 0, 3, 4) == 5000
+fn distance2d_fixed(x1: int, y1: int, x2: int, y2: int) -> int {
+    let dx: int = x1 - x2;
+    let dy: int = y1 - y2;
+    return length2d_fixed(dx, dy);
+}
+
+// Manhattan distance (taxicab): |dx| + |dy|.
+// manhattan(0, 0, 3, 4) == 7
+fn manhattan(x1: int, y1: int, x2: int, y2: int) -> int {
+    let dx: int = x1 - x2;
+    let dy: int = y1 - y2;
+    if (dx < 0) { dx = 0 - dx; }
+    if (dy < 0) { dy = 0 - dy; }
+    return dx + dy;
+}
+
+// Chebyshev distance (chess-king): max(|dx|, |dy|).
+// chebyshev(0, 0, 3, 4) == 4
+fn chebyshev(x1: int, y1: int, x2: int, y2: int) -> int {
+    let dx: int = x1 - x2;
+    let dy: int = y1 - y2;
+    if (dx < 0) { dx = 0 - dx; }
+    if (dy < 0) { dy = 0 - dy; }
+    if (dx > dy) { return dx; }
+    return dy;
+}
+
+// X-component of the normalized unit vector (× 1000).
+// normalize2d_x(3, 4) == 600   (3/5 × 1000)
+// Returns 0 for the zero vector.
+fn normalize2d_x(x: int, y: int) -> int {
+    let len: int = length2d_fixed(x, y);
+    if (len == 0) { return 0; }
+    return x * 1000000 / len;
+}
+
+// Y-component of the normalized unit vector (× 1000).
+// normalize2d_y(3, 4) == 800   (4/5 × 1000)
+fn normalize2d_y(x: int, y: int) -> int {
+    let len: int = length2d_fixed(x, y);
+    if (len == 0) { return 0; }
+    return y * 1000000 / len;
+}
+
+// Linearly interpolate between vectors a=(ax,ay) and b=(bx,by), return x.
+// t in [0, 1000] (fixed-point).
+// lerp2d_x(0, 0, 100, 200, 500) == 50
+fn lerp2d_x(ax: int, ay: int, bx: int, by: int, t: int) -> int {
+    return ax + (bx - ax) * t / 1000;
+}
+
+// Linearly interpolate between vectors a and b, return y.
+// lerp2d_y(0, 0, 100, 200, 500) == 100
+fn lerp2d_y(ax: int, ay: int, bx: int, by: int, t: int) -> int {
+    return ay + (by - ay) * t / 1000;
+}
+
+// ─── Phase 2: 2D direction ────────────────────────────────────────────────────
+
+// tan lookup table for atan2_fixed binary search
+fn _atan_init() {
+    storage_set_array("math:tables", "tan",
+        "[0, 17, 35, 52, 70, 87, 105, 123, 141, 158, 176, 194, 213, 231, 249, 268, 287, 306, 325, 344, 364, 384, 404, 424, 445, 466, 488, 510, 532, 554, 577, 601, 625, 649, 675, 700, 727, 754, 781, 810, 839, 869, 900, 933, 966, 1000]"
+    );
+}
+
+// Angle of the vector (y, x) in integer degrees [0, 359].
+// Uses binary search on the tan table → O(log 46) per call.
+//
+// atan2_fixed(0,  1) ==   0   (east)
+// atan2_fixed(1,  0) ==  90
+// atan2_fixed(0, -1) == 180   (west)
+// atan2_fixed(-1, 0) == 270
+// atan2_fixed(1,  1) ==  45
+//
+// Inputs clamped to ≤ 46340 to avoid overflow.  For larger vectors:
+//   atan2_fixed(dy / 1000, dx / 1000)
+@require_on_load(_atan_init)
+fn atan2_fixed(y: int, x: int) -> int {
+    if (x == 0) {
+        if (y > 0) { return 90; }
+        if (y < 0) { return 270; }
+        return 0;
+    }
+    if (y == 0) {
+        if (x > 0) { return 0; }
+        return 180;
+    }
+
+    let ax: int = x;
+    if (ax < 0) { ax = 0 - ax; }
+    let ay: int = y;
+    if (ay < 0) { ay = 0 - ay; }
+
+    if (ax > 46340) { ax = 46340; }
+    if (ay > 46340) { ay = 46340; }
+
+    let swapped: int = 0;
+    if (ay > ax) {
+        let tmp: int = ax;
+        ax = ay;
+        ay = tmp;
+        swapped = 1;
+    }
+
+    let lo: int = 0;
+    let hi: int = 45;
+    while (lo < hi) {
+        let mid: int = (lo + hi + 1) / 2;
+        let t: int = storage_get_int("math:tables", "tan", mid);
+        if (t * ax > ay * 1000) {
+            hi = mid - 1;
+        } else {
+            lo = mid;
+        }
+    }
+    let theta: int = lo;
+    if (swapped == 1) { theta = 90 - theta; }
+
+    if (x > 0) {
+        if (y >= 0) { return theta; }
+        return 360 - theta;
+    }
+    if (y >= 0) { return 180 - theta; }
+    return 180 + theta;
+}
+
+// Rotate a 2D vector (x, y) by deg degrees, return the new X component.
+// Uses sin/cos table from math.mcrs — @require_on_load(_math_init) is
+// automatically pulled in because this function calls sin_fixed/cos_fixed.
+// rotate2d_x(1000, 0, 90) == 0      (unit vector east, rotated 90° = north)
+// rotate2d_x(1000, 0, 45) == 707    (cos 45° × 1000)
+fn rotate2d_x(x: int, y: int, deg: int) -> int {
+    // x' = x*cos(deg) - y*sin(deg)   (all in fixed-point, /1000 via mulfix)
+    return mulfix(x, cos_fixed(deg)) - mulfix(y, sin_fixed(deg));
+}
+
+// Rotate a 2D vector (x, y) by deg degrees, return the new Y component.
+// rotate2d_y(1000, 0, 90) == 1000   (unit vector east, rotated 90° = north)
+fn rotate2d_y(x: int, y: int, deg: int) -> int {
+    // y' = x*sin(deg) + y*cos(deg)
+    return mulfix(x, sin_fixed(deg)) + mulfix(y, cos_fixed(deg));
+}
+
+// ─── Phase 3: 3D geometry ────────────────────────────────────────────────────
+
+// Dot product of two 3D integer vectors.
+fn dot3d(ax: int, ay: int, az: int, bx: int, by: int, bz: int) -> int {
+    return ax * bx + ay * by + az * bz;
+}
+
+// Cross product X component: ay*bz − az*by
+fn cross3d_x(ax: int, ay: int, az: int, bx: int, by: int, bz: int) -> int {
+    return ay * bz - az * by;
+}
+
+// Cross product Y component: az*bx − ax*bz
+fn cross3d_y(ax: int, ay: int, az: int, bx: int, by: int, bz: int) -> int {
+    return az * bx - ax * bz;
+}
+
+// Cross product Z component: ax*by − ay*bx
+fn cross3d_z(ax: int, ay: int, az: int, bx: int, by: int, bz: int) -> int {
+    return ax * by - ay * bx;
+}
+
+// Euclidean length of a 3D integer vector, result in fixed-point (×1000).
+// length3d_fixed(1, 1, 1) == 1732   (√3 × 1000)
+// Note: |x|, |y|, |z| ≤ ~800 to keep x²+y²+z² ≤ ~2,000,000 (safe for *1000).
+fn length3d_fixed(x: int, y: int, z: int) -> int {
+    return sqrt_fixed((x * x + y * y + z * z) * 1000);
+}
+
+// Euclidean distance between two 3D integer points, result ×1000.
+fn distance3d_fixed(x1: int, y1: int, z1: int, x2: int, y2: int, z2: int) -> int {
+    let dx: int = x1 - x2;
+    let dy: int = y1 - y2;
+    let dz: int = z1 - z2;
+    return length3d_fixed(dx, dy, dz);
+}
+
+// Manhattan distance in 3D.
+// manhattan3d(0,0,0, 1,2,3) == 6
+fn manhattan3d(x1: int, y1: int, z1: int, x2: int, y2: int, z2: int) -> int {
+    let dx: int = x1 - x2;
+    let dy: int = y1 - y2;
+    let dz: int = z1 - z2;
+    if (dx < 0) { dx = 0 - dx; }
+    if (dy < 0) { dy = 0 - dy; }
+    if (dz < 0) { dz = 0 - dz; }
+    return dx + dy + dz;
+}
+
+// Chebyshev distance in 3D.
+// chebyshev3d(0,0,0, 3,1,2) == 3
+fn chebyshev3d(x1: int, y1: int, z1: int, x2: int, y2: int, z2: int) -> int {
+    let dx: int = x1 - x2;
+    let dy: int = y1 - y2;
+    let dz: int = z1 - z2;
+    if (dx < 0) { dx = 0 - dx; }
+    if (dy < 0) { dy = 0 - dy; }
+    if (dz < 0) { dz = 0 - dz; }
+    let m: int = dx;
+    if (dy > m) { m = dy; }
+    if (dz > m) { m = dz; }
+    return m;
+}