redscript-mc 2.4.1 → 2.6.0

package/docs/stdlib/advanced.md

@@ -0,0 +1,276 @@
+# `advanced` — Higher-order integer math and algorithmic functions
+
+Import: `import advanced;`
+
+Provides number theory (Fibonacci, primality, Collatz, digit operations, modular exponentiation), integer hashing, 1D noise, Bézier curves (quadratic through N-order), fractal iteration (Mandelbrot, Julia), 2D geometry helpers, and digital root / Ulam spiral utilities. Requires `math` for `lerp`, `smoothstep`, `mulfix`, `abs`, `isqrt`, `sqrt_fixed`.
+
+## Functions
+
+### `fib(n: int): int`
+
+Fibonacci number F(n) using simple iteration. F(0)=0, F(1)=1. Safe up to n=46 (F(46)≈INT_MAX); overflows for larger inputs.
+
+**Example:**
+```rs
+import advanced;
+let f: int = fib(10);  // 55
+```
+
+---
+
+### `is_prime(n: int): int`
+
+Primality test by trial division up to √n. Returns 1 if `n` is prime, 0 otherwise.
+
+**Example:**
+```rs
+import advanced;
+let p: int = is_prime(97);  // 1
+```
+
+---
+
+### `collatz_steps(n: int): int`
+
+Number of steps in the Collatz sequence starting at `n` until reaching 1.
+
+**Example:**
+```rs
+import advanced;
+let s: int = collatz_steps(27);  // 111
+```
+
+---
+
+### `digit_sum(n: int): int`
+
+Sum of decimal digits. Negative input uses absolute value.
+
+**Example:**
+```rs
+import advanced;
+let d: int = digit_sum(123);  // 6
+```
+
+---
+
+### `count_digits(n: int): int`
+
+Count decimal digits. Zero has 1 digit. Negative input counts absolute digits.
+
+**Example:**
+```rs
+import advanced;
+let d: int = count_digits(100);  // 3
+```
+
+---
+
+### `reverse_int(n: int): int`
+
+Reverse the decimal digits of an integer. Sign is preserved.
+
+**Example:**
+```rs
+import advanced;
+let r: int = reverse_int(12345);  // 54321
+```
+
+---
+
+### `mod_pow(base: int, exp: int, m: int): int`
+
+Modular exponentiation: `(base ^ exp) mod m` using fast O(log exp) squaring. `m` must be ≤ 46340 to avoid overflow.
+
+> **Cost:** O(log exp) multiply-divide steps
+
+**Example:**
+```rs
+import advanced;
+let r: int = mod_pow(2, 10, 1000);  // 24  (1024 mod 1000)
+```
+
+---
+
+### `hash_int(n: int): int`
+
+Integer hash function. Output is non-negative in range `[0, ~2×10⁹)`. Deterministic — same input always produces the same output. Suitable as a seeded pseudo-random value for procedural generation.
+
+**Example:**
+```rs
+import advanced;
+let h: int = hash_int(42);
+```
+
+---
+
+### `noise1d(x: int): int`
+
+1D value noise. Input `x` in fixed-point (scale=1000). Output in `[0, 999]` — smoothly interpolated between hashed lattice points using smoothstep for C1 continuity.
+
+**Example:**
+```rs
+import advanced;
+let n: int = noise1d(500);  // between noise1d(0) and noise1d(1000)
+```
+
+---
+
+### `bezier_quad(p0: int, p1: int, p2: int, t: int): int`
+
+Quadratic Bézier curve using De Casteljau's algorithm. `t` in `[0, 1000]` (fixed-point). Numerically stable, safe for large coordinates.
+
+**Example:**
+```rs
+import advanced;
+let mid: int = bezier_quad(0, 500, 1000, 500);  // 500
+```
+
+---
+
+### `bezier_cubic(p0: int, p1: int, p2: int, p3: int, t: int): int`
+
+Cubic Bézier curve (4 control points) using De Casteljau's algorithm. `t` in `[0, 1000]`.
+
+**Example:**
+```rs
+import advanced;
+let pos: int = bezier_cubic(0, 333, 667, 1000, 500);
+```
+
+---
+
+### `bezier_quartic(p0: int, p1: int, p2: int, p3: int, p4: int, t: int): int`
+
+Quartic Bézier curve (5 control points) using De Casteljau's algorithm. `t` in `[0, 1000]`.
+
+**Example:**
+```rs
+import advanced;
+let pos: int = bezier_quartic(0, 250, 500, 750, 1000, 500);  // 500
+```
+
+---
+
+### `bezier_n(pts: int[], n: int, t: int): int`
+
+N-order Bézier curve via De Casteljau's algorithm. `t` in `[0, 1000]`. **Modifies `pts` in-place.** Use `bezier_n_safe` if you need to preserve the control points array.
+
+**Example:**
+```rs
+import advanced;
+let pts: int[] = [0, 333, 667, 1000];
+let pos: int = bezier_n(pts, 4, 500);
+```
+
+---
+
+### `bezier_n_safe(pts: int[], work: int[], n: int, t: int): int`
+
+N-order Bézier, non-destructive. Copies `pts` into `work` (length ≥ n) then runs `bezier_n` on `work`. `pts` is not modified.
+
+**Example:**
+```rs
+import advanced;
+let pts: int[] = [0, 333, 667, 1000];
+let work: int[] = [0, 0, 0, 0];
+let pos: int = bezier_n_safe(pts, work, 4, 750);
+```
+
+---
+
+### `mandelbrot_iter(cx: int, cy: int, max_iter: int): int`
+
+Mandelbrot set iteration count. `cx`, `cy`: fixed-point coordinates of `c` (scale=1000). Returns iterations before escape (`|z| > 2`), or `max_iter` if inside the set. Use the return value to colour blocks.
+
+**Example:**
+```rs
+import advanced;
+let iters: int = mandelbrot_iter(-1000, 0, 100);  // 100 (point in set)
+```
+
+---
+
+### `julia_iter(z0r: int, z0i: int, cr: int, ci: int, max_iter: int): int`
+
+Julia set iteration count — generalised Mandelbrot with fixed `c` and variable starting point `z0`. Same escape condition and scale as `mandelbrot_iter`.
+
+**Example:**
+```rs
+import advanced;
+let iters: int = julia_iter(0, 0, -7000, 2600, 50);
+```
+
+---
+
+### `angle_between(x1: int, y1: int, x2: int, y2: int): int`
+
+Angle between two 2D vectors in degrees (unsigned, 0–180). Normalises both vectors before computing. Returns 0 if either vector is zero.
+
+> **Note:** Keep vector components ≤ ~2000 to avoid overflow in the normalisation step.
+
+**Example:**
+```rs
+import advanced;
+let deg: int = angle_between(1000, 0, 0, 1000);  // 90
+```
+
+---
+
+### `clamp_circle_x(x: int, y: int, r: int): int`
+
+X component of a 2D point clamped to lie within a circle of radius `r` centred at the origin.
+
+**Example:**
+```rs
+import advanced;
+let cx: int = clamp_circle_x(600, 0, 500);  // 500
+```
+
+---
+
+### `clamp_circle_y(x: int, y: int, r: int): int`
+
+Y component of a 2D point clamped to lie within a circle of radius `r` centred at the origin.
+
+**Example:**
+```rs
+import advanced;
+let cy: int = clamp_circle_y(0, 600, 500);  // 500
+```
+
+---
+
+### `newton_sqrt(n: int): int`
+
+Newton's method integer square root (alternative to `isqrt`). Converges quadratically.
+
+**Example:**
+```rs
+import advanced;
+let r: int = newton_sqrt(25);  // 5
+```
+
+---
+
+### `digital_root(n: int): int`
+
+Repeatedly sum digits until a single digit remains (digital root). `digital_root(493)` → 7 (4+9+3=16 → 1+6=7).
+
+**Example:**
+```rs
+import advanced;
+let d: int = digital_root(493);  // 7
+```
+
+---
+
+### `spiral_ring(n: int): int`
+
+Ulam spiral ring number: which concentric square ring integer `n` falls on. Ring 0: n=1; Ring 1: n=2–9; Ring 2: n=10–25.
+
+**Example:**
+```rs
+import advanced;
+let ring: int = spiral_ring(9);  // 1
+```

package/docs/stdlib/bigint.md

@@ -0,0 +1,285 @@
+# `bigint` — Multi-precision integer arithmetic
+
+Import: `import bigint;`
+
+Arbitrary-precision integers represented as base-10000 (万進制) `int` arrays in NBT storage. Arrays are big-endian (index 0 = most significant chunk). Provides 3-chunk (96-bit) helpers and arbitrary-length operations for addition, subtraction, multiplication, division, comparison, and utility functions. Full bigint×bigint multiplication and squaring included.
+
+## Functions
+
+### `bigint_base(): int`
+
+Returns the chunk base constant: 10000.
+
+---
+
+### `bigint_zero(arr: int[], len: int)`
+
+Set all `len` chunks of `arr` to zero.
+
+**Example:**
+```rs
+import bigint;
+let a: int[] = [1, 2, 3];
+bigint_zero(a, 3);  // a = [0, 0, 0]
+```
+
+---
+
+### `bigint_copy(src: int[], dst: int[], len: int)`
+
+Copy `len` chunks from `src` into `dst`.
+
+**Example:**
+```rs
+import bigint;
+let src: int[] = [0, 1234, 5678];
+let dst: int[] = [0, 0, 0];
+bigint_copy(src, dst, 3);
+```
+
+---
+
+### `bigint_cmp(a: int[], b: int[], len: int): int`
+
+Compare two `len`-chunk bigints (big-endian). Returns 1 if `a > b`, -1 if `a < b`, 0 if equal.
+
+**Example:**
+```rs
+import bigint;
+let a: int[] = [0, 0, 5000];
+let b: int[] = [0, 0, 3000];
+let r: int = bigint_cmp(a, b, 3);  // 1
+```
+
+---
+
+### `bigint_add(a: int[], b: int[], result: int[], len: int): int`
+
+Add two `len`-chunk bigints into `result`. Returns carry-out (0 or 1). Caller should handle overflow.
+
+**Example:**
+```rs
+import bigint;
+let a: int[] = [0, 9999, 9999];
+let b: int[] = [0, 0, 1];
+let r: int[] = [0, 0, 0];
+let carry: int = bigint_add(a, b, r, 3);
+```
+
+---
+
+### `bigint_sub(a: int[], b: int[], result: int[], len: int)`
+
+Subtract: `result = a - b`. Assumes `a >= b` (no negative result handling).
+
+**Example:**
+```rs
+import bigint;
+let a: int[] = [0, 1, 0];
+let b: int[] = [0, 0, 5000];
+let r: int[] = [0, 0, 0];
+bigint_sub(a, b, r, 3);
+```
+
+---
+
+### `bigint_mul_small(a: int[], n: int, result: int[], len: int)`
+
+Multiply `len`-chunk bigint `a` by small integer `n` (must be ≤ 9999) into `result`.
+
+**Example:**
+```rs
+import bigint;
+let a: int[] = [0, 0, 1234];
+let r: int[] = [0, 0, 0];
+bigint_mul_small(a, 7, r, 3);  // r = [0, 0, 8638]
+```
+
+---
+
+### `bigint_shift_left(arr: int[], len: int)`
+
+Multiply bigint by 10000 (shift left one chunk). Loses the most significant chunk if non-zero.
+
+---
+
+### `bigint_is_zero(arr: int[], len: int): int`
+
+Returns 1 if all `len` chunks are zero.
+
+---
+
+### `bigint_leading_zeros(arr: int[], len: int): int`
+
+Count leading zero chunks from the most significant end.
+
+---
+
+### `bigint_div_small(a: int[], divisor: int, result: int[], len: int): int`
+
+Divide `len`-chunk bigint by a small integer (`1 ≤ divisor ≤ 9999`). Uses long division chunk by chunk. Returns the remainder.
+
+**Example:**
+```rs
+import bigint;
+let a: int[] = [0, 0, 10000];
+let r: int[] = [0, 0, 0];
+let rem: int = bigint_div_small(a, 3, r, 3);
+```
+
+---
+
+### `bigint_mod_small(a: int[], divisor: int, len: int): int`
+
+Returns `a mod divisor` (0..divisor-1) without storing the quotient.
+
+---
+
+### `bigint_chunk(a: int[], i: int): int`
+
+Read chunk at index `i`. Helper for display/inspection purposes.
+
+---
+
+### `bigint_mul(a: int[], b: int[], result: int[], la: int, lb: int)`
+
+Multiply two bigints: `result = a × b`. `a` has `la` chunks, `b` has `lb` chunks; `result` must be pre-zeroed with `la + lb` chunks. Uses schoolbook O(n²) algorithm.
+
+> **Cost:** O(la × lb) multiply operations
+
+**Example:**
+```rs
+import bigint;
+let a: int[] = [0, 0, 1234, 5678];
+let b: int[] = [0, 0, 9999];
+let result: int[] = [0, 0, 0, 0, 0, 0, 0];
+bigint_mul(a, b, result, 4, 3);
+```
+
+---
+
+### `bigint_mul_result_len(la: int, lb: int): int`
+
+Returns the required result array length for `bigint_mul`: `la + lb`.
+
+---
+
+### `bigint_sq(a: int[], result: int[], len: int)`
+
+Square a bigint: `result = a × a`. `result` must be pre-zeroed with `len * 2` chunks. Optimised: only computes upper triangle and doubles, avoiding redundant multiplications.
+
+> **Cost:** O(n²/2) multiply operations — roughly half of `bigint_mul`
+
+---
+
+### `bigint3_add_lo(alo: int, blo: int): int`
+
+Low chunk of a 3-chunk (96-bit) addition.
+
+---
+
+### `bigint3_carry_lo(alo: int, blo: int): int`
+
+Carry out from the low chunk addition.
+
+---
+
+### `bigint3_add_mid(amid: int, bmid: int, carry: int): int`
+
+Middle chunk of 3-chunk addition with incoming carry.
+
+---
+
+### `bigint3_carry_mid(amid: int, bmid: int, carry: int): int`
+
+Carry out from middle chunk addition.
+
+---
+
+### `bigint3_add_hi(ahi: int, bhi: int, carry: int): int`
+
+High chunk of 3-chunk addition with incoming carry.
+
+---
+
+### `bigint3_sub_lo(alo: int, blo: int): int`
+
+Low chunk of 3-chunk subtraction.
+
+---
+
+### `bigint3_borrow_lo(alo: int, blo: int): int`
+
+Borrow out from low chunk subtraction.
+
+---
+
+### `bigint3_sub_mid(amid: int, bmid: int, borrow: int): int`
+
+Middle chunk of 3-chunk subtraction with incoming borrow.
+
+---
+
+### `bigint3_borrow_mid(amid: int, bmid: int, borrow: int): int`
+
+Borrow out from middle chunk subtraction.
+
+---
+
+### `bigint3_sub_hi(ahi: int, bhi: int, borrow: int): int`
+
+High chunk of 3-chunk subtraction.
+
+---
+
+### `bigint3_mul1_lo(a: int, b: int): int`
+
+Low chunk of single-chunk multiply (used in 3-chunk multiply-by-small).
+
+---
+
+### `bigint3_mul1_hi(a: int, b: int): int`
+
+High chunk of single-chunk multiply.
+
+---
+
+### `bigint3_cmp(ahi: int, amid: int, alo: int, bhi: int, bmid: int, blo: int): int`
+
+Compare two explicit 3-chunk bigints. Returns 1 if a>b, -1 if a<b, 0 if equal.
+
+---
+
+### `int32_to_bigint3_lo(n: int): int`
+
+Low chunk of int32 split into 3 chunks.
+
+---
+
+### `int32_to_bigint3_mid(n: int): int`
+
+Middle chunk of int32 split into 3 chunks.
+
+---
+
+### `int32_to_bigint3_hi(n: int): int`
+
+High chunk of int32 split into 3 chunks.
+
+---
+
+### `bigint3_to_int32(hi: int, mid: int, lo: int): int`
+
+Reconstruct int32 from 3 chunks.
+
+---
+
+### `bigint3_div_chunk(chunk: int, rem: int, divisor: int): int`
+
+Long division quotient for one chunk: `(rem * 10000 + chunk) / divisor`.
+
+---
+
+### `bigint3_rem_chunk(chunk: int, rem: int, divisor: int): int`
+
+Long division remainder for one chunk: `(rem * 10000 + chunk) % divisor`.

package/docs/stdlib/bits.md

@@ -0,0 +1,159 @@
+# `bits` — Bitwise operations
+
+Import: `import bits;`
+
+Bitwise operations simulated with integer arithmetic (multiply/divide/modulo), since MC scoreboard has no native bitwise ops. Performance is O(32) per operation — fast enough for most game logic. For hot paths (>1000 calls/tick), consider lookup tables or restructuring the algorithm.
+
+## Functions
+
+### `bit_get(x: int, n: int): int`
+
+> **Cost:** O(n) — n up to 30 iterations
+
+Return 1 if bit `n` is set in `x`, 0 otherwise. `n ∈ [0, 30]`.
+
+**Example:**
+```rs
+import bits;
+let flag: int = bit_get(0b1010, 1);  // 1
+```
+
+---
+
+### `bit_set(x: int, n: int): int`
+
+> **Cost:** O(n)
+
+Set bit `n` to 1. `n ∈ [0, 30]`. Returns updated value.
+
+**Example:**
+```rs
+import bits;
+let v: int = bit_set(0, 3);  // 8
+```
+
+---
+
+### `bit_clear(x: int, n: int): int`
+
+> **Cost:** O(n)
+
+Clear bit `n` to 0. `n ∈ [0, 30]`. Returns updated value.
+
+**Example:**
+```rs
+import bits;
+let v: int = bit_clear(15, 0);  // 14
+```
+
+---
+
+### `bit_toggle(x: int, n: int): int`
+
+> **Cost:** O(n)
+
+Toggle bit `n`. `n ∈ [0, 30]`. Returns updated value.
+
+**Example:**
+```rs
+import bits;
+let v: int = bit_toggle(5, 1);  // 7  (101 → 111)
+```
+
+---
+
+### `bit_shl(x: int, n: int): int`
+
+> **Cost:** O(n)
+
+Left shift `x` by `n` bits (`x << n`). `n ∈ [0, 30]`.
+
+**Example:**
+```rs
+import bits;
+let v: int = bit_shl(1, 4);  // 16
+```
+
+---
+
+### `bit_shr(x: int, n: int): int`
+
+> **Cost:** O(n)
+
+Logical right shift `x` by `n` bits (`x >> n`). Divides by 2^n, truncating toward zero. `n ∈ [0, 30]`.
+
+**Example:**
+```rs
+import bits;
+let v: int = bit_shr(16, 2);  // 4
+```
+
+---
+
+### `bit_and(a: int, b: int): int`
+
+> **Cost:** O(31) — iterates over 31 bits
+
+Bitwise AND of `a` and `b`. Operates on bits 0–30 (sign bit excluded).
+
+**Example:**
+```rs
+import bits;
+let v: int = bit_and(12, 10);  // 8  (1100 & 1010 = 1000)
+```
+
+---
+
+### `bit_or(a: int, b: int): int`
+
+> **Cost:** O(31)
+
+Bitwise OR of `a` and `b`. Operates on bits 0–30.
+
+**Example:**
+```rs
+import bits;
+let v: int = bit_or(12, 10);  // 14  (1100 | 1010 = 1110)
+```
+
+---
+
+### `bit_xor(a: int, b: int): int`
+
+> **Cost:** O(31)
+
+Bitwise XOR of `a` and `b`. Operates on bits 0–30.
+
+**Example:**
+```rs
+import bits;
+let v: int = bit_xor(12, 10);  // 6  (1100 ^ 1010 = 0110)
+```
+
+---
+
+### `bit_not(x: int): int`
+
+> **Cost:** O(31)
+
+Bitwise NOT of `x`. Inverts all 31 bits (sign bit excluded).
+
+**Example:**
+```rs
+import bits;
+let v: int = bit_not(0);  // 2147483647  (all 31 bits set)
+```
+
+---
+
+### `popcount(x: int): int`
+
+> **Cost:** O(31)
+
+Count the number of set bits in `x`. Returns a value in `[0, 31]`.
+
+**Example:**
+```rs
+import bits;
+let count: int = popcount(255);  // 8
+```