redscript-mc 2.6.0 → 3.0.0

package/src/stdlib/bigint.mcrs

@@ -19,6 +19,9 @@ module library;
 
 // ─── Constants ───────────────────────────────────────────────────────────────
 
+/// Return the bigint base (10000 = base-10000, each chunk holds 4 decimal digits).
+/// @since 1.0.0
+/// @returns  10000
 fn bigint_base(): int { return 10000; }
 
 // ─── Single-chunk helpers ────────────────────────────────────────────────────
@@ -96,20 +99,37 @@ fn bigint3_rem_chunk(chunk: int, rem: int, divisor: int): int {
 
 // ─── Arbitrary-length operations (array by-ref, RedScript ≥ 2.4.0) ──────────
 
-// bigint_zero(arr, len): set all chunks to 0
+/// Set all chunks of a bigint array to zero.
+/// @since 1.0.0
+/// @param arr  BigInt array (most-significant chunk at index 0)
+/// @param len  Number of chunks
+/// @returns  void — arr[0..len-1] set to 0
+/// @example
+/// bigint_zero(result, 4)  // zero out a 4-chunk bigint
 fn bigint_zero(arr: int[], len: int) {
     let i: int = 0;
     while (i < len) { arr[i] = 0; i = i + 1; }
 }
 
-// bigint_copy(src, dst, len): copy src into dst
+/// Copy a bigint from src into dst.
+/// @since 1.0.0
+/// @param src  Source bigint array
+/// @param dst  Destination bigint array (must have length >= len)
+/// @param len  Number of chunks to copy
+/// @returns  void — dst[0..len-1] = src[0..len-1]
 fn bigint_copy(src: int[], dst: int[], len: int) {
     let i: int = 0;
     while (i < len) { dst[i] = src[i]; i = i + 1; }
 }
 
-// bigint_cmp(a, b, len): compare a and b, returns 1 if a>b, -1 if a<b, 0 if equal
-// Most significant chunk is at index 0 (big-endian)
+/// Compare two bigints of equal length.
+/// @since 1.0.0
+/// @param a    First bigint (most-significant chunk at index 0)
+/// @param b    Second bigint
+/// @param len  Number of chunks (must be equal for both)
+/// @returns  1 if a > b, -1 if a < b, 0 if equal
+/// @example
+/// let cmp: int = bigint_cmp(a, b, 4)
 fn bigint_cmp(a: int[], b: int[], len: int): int {
     let i: int = 0;
     while (i < len) {
@@ -120,8 +140,15 @@ fn bigint_cmp(a: int[], b: int[], len: int): int {
     return 0;
 }
 
-// bigint_add(a, b, result, len): result = a + b (in-place into result array)
-// Returns carry out (0 or 1) — caller should handle overflow
+/// Add two bigints of equal length, writing result into a pre-allocated array.
+/// @since 1.0.0
+/// @param a       First bigint addend
+/// @param b       Second bigint addend
+/// @param result  Output bigint array (must have length >= len, may alias a or b)
+/// @param len     Number of chunks
+/// @returns  Carry out: 0 or 1 (overflow if non-zero)
+/// @example
+/// let carry: int = bigint_add(a, b, result, 4)
 fn bigint_add(a: int[], b: int[], result: int[], len: int): int {
     let carry: int = 0;
     let i: int = len - 1;  // start from least significant (rightmost)
@@ -134,7 +161,13 @@ fn bigint_add(a: int[], b: int[], result: int[], len: int): int {
     return carry;
 }
 
-// bigint_sub(a, b, result, len): result = a - b (assumes a >= b)
+/// Subtract bigint b from a, writing result (assumes a >= b, no underflow check).
+/// @since 1.0.0
+/// @param a       Minuend bigint
+/// @param b       Subtrahend bigint (must be <= a)
+/// @param result  Output bigint array
+/// @param len     Number of chunks
+/// @returns  void — result = a - b
 fn bigint_sub(a: int[], b: int[], result: int[], len: int) {
     let borrow: int = 0;
     let i: int = len - 1;
@@ -150,7 +183,15 @@ fn bigint_sub(a: int[], b: int[], result: int[], len: int) {
     }
 }
 
-// bigint_mul_small(a, n, result, len): result = a × n, where n ≤ 9999
+/// Multiply a bigint by a small integer (1 ≤ n ≤ 9999).
+/// @since 1.0.0
+/// @param a       Bigint multiplicand
+/// @param n       Small integer multiplier (must be in [1, 9999] to avoid overflow)
+/// @param result  Output bigint array (must have length >= len)
+/// @param len     Number of chunks
+/// @returns  void — result = a * n; high overflow is silently lost
+/// @example
+/// bigint_mul_small(a, 1000, result, 4)  // result = a × 1000
 fn bigint_mul_small(a: int[], n: int, result: int[], len: int) {
     let carry: int = 0;
     let i: int = len - 1;
@@ -201,8 +242,15 @@ fn bigint_leading_zeros(arr: int[], len: int): int {
 // result[i] = (rem*10000 + a[i]) / divisor
 // rem = (rem*10000 + a[i]) % divisor
 
-// bigint_div_small(a, divisor, result, len): result = a / divisor
-// Returns remainder.
+/// Divide a bigint by a small integer (1 ≤ divisor ≤ 9999), returning quotient and remainder.
+/// @since 1.0.0
+/// @param a        Dividend bigint
+/// @param divisor  Small integer divisor (range [1, 9999])
+/// @param result   Output quotient bigint array
+/// @param len      Number of chunks
+/// @returns  Remainder (0..divisor-1)
+/// @example
+/// let rem: int = bigint_div_small(a, 7, result, 4)
 fn bigint_div_small(a: int[], divisor: int, result: int[], len: int): int {
     let rem: int = 0;
     let i: int = 0;
@@ -215,7 +263,14 @@ fn bigint_div_small(a: int[], divisor: int, result: int[], len: int): int {
     return rem;
 }
 
-// bigint_mod_small(a, divisor, len): return a % divisor (0..divisor-1)
+/// Compute a bigint modulo a small integer without allocating a quotient array.
+/// @since 1.0.0
+/// @param a        Dividend bigint
+/// @param divisor  Small integer divisor (range [1, 9999])
+/// @param len      Number of chunks
+/// @returns  a % divisor, in [0, divisor-1]
+/// @example
+/// let mod: int = bigint_mod_small(a, 10, 4)  // last decimal digit of a
 fn bigint_mod_small(a: int[], divisor: int, len: int): int {
     let rem: int = 0;
     let i: int = 0;
@@ -248,6 +303,17 @@ fn bigint_chunk(a: int[], i: int): int {
 //   let result: int[] = [0, 0, 0, 0, 0, 0, 0]; // la+lb = 7 chunks, pre-zeroed
 //   bigint_mul(a, b, result, 4, 3);
 //
+/// Multiply two bigints using schoolbook O(n²) algorithm.
+/// @since 1.0.0
+/// @param a       First bigint (la chunks)
+/// @param b       Second bigint (lb chunks)
+/// @param result  Output bigint array (must have la+lb chunks, pre-zeroed)
+/// @param la      Number of chunks in a
+/// @param lb      Number of chunks in b
+/// @returns  void — result = a * b; result must not alias a or b
+/// @example
+/// let result: int[] = [0, 0, 0, 0, 0, 0, 0]
+/// bigint_mul(a, b, result, 4, 3)
 fn bigint_mul(a: int[], b: int[], result: int[], la: int, lb: int) {
     // Phase 1: accumulate partial products (big-endian, MSB at index 0)
     // a[i] is the (la-1-i)-th digit from LSB, similarly for b[j]
@@ -286,6 +352,15 @@ fn bigint_mul_result_len(la: int, lb: int): int {
 //   result must have len*2 chunks (pre-zeroed).
 //   Optimized: only compute upper triangle and double (avoids redundant multiplications).
 //
+/// Square a bigint (optimized: computes upper triangle only).
+/// @since 1.0.0
+/// @param a       Bigint to square (len chunks)
+/// @param result  Output bigint array (must have len*2 chunks, pre-zeroed)
+/// @param len     Number of chunks in a
+/// @returns  void — result = a * a
+/// @example
+/// let sq: int[] = [0, 0, 0, 0, 0, 0, 0, 0]
+/// bigint_sq(a, sq, 4)  // sq = a²
 fn bigint_sq(a: int[], result: int[], len: int) {
     // Diagonal terms (i == j)
     let i: int = 0;
@@ -318,3 +393,141 @@ fn bigint_sq(a: int[], result: int[], len: int) {
         k = k - 1;
     }
 }
+
+// ─── Full bigint ÷ bigint (Long Division) ────────────────────────────────────
+//
+// bigint_div(a, b, quotient, remainder, la, lb):
+//   Compute a / b → quotient, a % b → remainder
+//   a has la chunks, b has lb chunks (most-significant first, base 10000)
+//   quotient must have la chunks (pre-zeroed)
+//   remainder must have lb chunks (pre-zeroed)
+//
+//   Algorithm: Binary-search trial subtraction per digit position.
+//   For each position i in quotient (0..la-lb):
+//     trial_subtract(a_window, b, lb) to find max digit q such that q*b ≤ window.
+//
+// Prerequisite helpers: bigint_cmp, bigint_mul_small, bigint_sub (all in bigint.mcrs)
+
+// bigint_shl1(a, len): shift bigint left by 1 chunk (multiply by base 10000)
+// Modifies a in-place, drops most-significant chunk.
+fn bigint_shl1(a: int[], len: int): void {
+    let i: int = 0;
+    while (i < len - 1) {
+        a[i] = a[i + 1];
+        i = i + 1;
+    }
+    a[len - 1] = 0;
+}
+
+// bigint_cmp_window(a, aoff, b, len): compare a[aoff..aoff+len] with b[0..len]
+// Returns 1 if a_window > b, -1 if a_window < b, 0 if equal
+fn bigint_cmp_window(a: int[], aoff: int, b: int[], len: int): int {
+    let i: int = 0;
+    while (i < len) {
+        let ai: int = a[aoff + i];
+        let bi: int = b[i];
+        if (ai > bi) { return 1; }
+        if (ai < bi) { return -1; }
+        i = i + 1;
+    }
+    return 0;
+}
+
+// bigint_sub_window(a, aoff, b, len): a[aoff..aoff+len] -= b[0..len]  (in-place)
+fn bigint_sub_window(a: int[], aoff: int, b: int[], len: int): void {
+    let borrow: int = 0;
+    let i: int = len - 1;
+    while (i >= 0) {
+        let diff: int = a[aoff + i] - b[i] - borrow;
+        if (diff < 0) {
+            diff = diff + 10000;
+            borrow = 1;
+        } else {
+            borrow = 0;
+        }
+        a[aoff + i] = diff;
+        i = i - 1;
+    }
+}
+
+// bigint_mul_small_into(b, factor, out, len): out = b * factor (small int)
+fn bigint_mul_small_into(b: int[], factor: int, out: int[], len: int): void {
+    let carry: int = 0;
+    let i: int = len - 1;
+    while (i >= 0) {
+        let prod: int = b[i] * factor + carry;
+        out[i] = prod % 10000;
+        carry = prod / 10000;
+        i = i - 1;
+    }
+}
+
+// bigint_div(a, b, quotient, remainder, la, lb):
+// Full arbitrary-precision integer division.
+// quotient[0..la-1] is written, remainder[0..lb-1] is written.
+// a and b must not alias quotient or remainder.
+// NOTE: la >= lb required; both arrays most-significant first, base 10000.
+/// Full arbitrary-precision integer division: a / b → quotient and remainder.
+/// @since 1.0.0
+/// @param a          Dividend bigint (la chunks)
+/// @param b          Divisor bigint (lb chunks)
+/// @param quotient   Output quotient array (la chunks, pre-zeroed)
+/// @param remainder  Output remainder array (lb chunks, pre-zeroed)
+/// @param la         Number of chunks in a (must be >= lb)
+/// @param lb         Number of chunks in b
+/// @returns  void — quotient = a/b, remainder = a%b; a and b must not alias outputs
+/// @example
+/// bigint_div(a, b, quotient, remainder, 4, 2)
+fn bigint_div(a: int[], b: int[], quotient: int[], remainder: int[], la: int, lb: int): void {
+    // Work on a copy of a (dividend) to allow in-place subtraction
+    let work: int[] = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0];
+    let wi: int = 0;
+    while (wi < la) {
+        work[wi] = a[wi];
+        wi = wi + 1;
+    }
+
+    // Temp buffer for trial product: b * q_digit
+    let trial: int[] = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0];
+
+    // Zero quotient
+    let qi: int = 0;
+    while (qi < la) {
+        quotient[qi] = 0;
+        qi = qi + 1;
+    }
+
+    // Process each quotient digit position (la - lb + 1 digits)
+    let pos: int = 0;
+    while (pos <= la - lb) {
+        // Binary search for largest q in [0, 9999] s.t. b * q ≤ work[pos..pos+lb]
+        let lo: int = 0;
+        let hi: int = 9999;
+        let q: int = 0;
+        while (lo <= hi) {
+            let mid: int = (lo + hi) / 2;
+            bigint_mul_small_into(b, mid, trial, lb);
+            let cmp: int = bigint_cmp_window(work, pos, trial, lb);
+            if (cmp >= 0) {
+                q = mid;
+                lo = mid + 1;
+            } else {
+                hi = mid - 1;
+            }
+        }
+        quotient[pos] = q;
+        // Subtract b * q from work window
+        if (q > 0) {
+            bigint_mul_small_into(b, q, trial, lb);
+            bigint_sub_window(work, pos, trial, lb);
+        }
+        pos = pos + 1;
+    }
+
+    // Remainder is work[la-lb .. la-1]
+    let ri: int = 0;
+    while (ri < lb) {
+        remainder[ri] = work[la - lb + ri];
+        ri = ri + 1;
+    }
+}

package/src/stdlib/bits.mcrs

@@ -16,7 +16,13 @@ module library;
 
 // ─── Core: single-bit operations ─────────────────────────────────────────────
 
-// bit_get(x, n): return 1 if bit n is set, 0 otherwise. n ∈ [0, 30]
+/// Test whether bit n of x is set.
+/// @since 1.0.0
+/// @param x  Integer value to test
+/// @param n  Bit index (0 = least significant), range [0, 30]
+/// @returns  1 if bit n is set, 0 otherwise
+/// @example
+/// let b: int = bit_get(0b1010, 1)  // result: 1 (bit 1 of 10 is set)
 fn bit_get(x: int, n: int): int {
     let mask: int = 1;
     let i: int = 0;
@@ -24,7 +30,13 @@ fn bit_get(x: int, n: int): int {
     return (x / mask) % 2;
 }
 
-// bit_set(x, n): set bit n to 1. n ∈ [0, 30]
+/// Set bit n of x to 1 (idempotent if already set).
+/// @since 1.0.0
+/// @param x  Integer value to modify
+/// @param n  Bit index to set, range [0, 30]
+/// @returns  x with bit n set to 1
+/// @example
+/// let v: int = bit_set(0b0100, 0)  // result: 0b0101 = 5
 fn bit_set(x: int, n: int): int {
     let mask: int = 1;
     let i: int = 0;
@@ -33,7 +45,13 @@ fn bit_set(x: int, n: int): int {
     return x;
 }
 
-// bit_clear(x, n): clear bit n to 0. n ∈ [0, 30]
+/// Clear bit n of x to 0 (idempotent if already clear).
+/// @since 1.0.0
+/// @param x  Integer value to modify
+/// @param n  Bit index to clear, range [0, 30]
+/// @returns  x with bit n set to 0
+/// @example
+/// let v: int = bit_clear(0b0111, 1)  // result: 0b0101 = 5
 fn bit_clear(x: int, n: int): int {
     let mask: int = 1;
     let i: int = 0;
@@ -42,7 +60,13 @@ fn bit_clear(x: int, n: int): int {
     return x;
 }
 
-// bit_toggle(x, n): toggle bit n. n ∈ [0, 30]
+/// Toggle bit n of x (flip 0→1 or 1→0).
+/// @since 1.0.0
+/// @param x  Integer value to modify
+/// @param n  Bit index to toggle, range [0, 30]
+/// @returns  x with bit n flipped
+/// @example
+/// let v: int = bit_toggle(0b0101, 1)  // result: 0b0111 = 7
 fn bit_toggle(x: int, n: int): int {
     let mask: int = 1;
     let i: int = 0;
@@ -53,7 +77,13 @@ fn bit_toggle(x: int, n: int): int {
 
 // ─── Shift operations ────────────────────────────────────────────────────────
 
-// bit_shl(x, n): left shift x by n bits (x << n). n ∈ [0, 30]
+/// Left-shift x by n bits (equivalent to x * 2^n).
+/// @since 1.0.0
+/// @param x  Integer to shift
+/// @param n  Number of bit positions to shift left, range [0, 30]
+/// @returns  x << n
+/// @example
+/// let v: int = bit_shl(1, 4)  // result: 16 (1 << 4)
 fn bit_shl(x: int, n: int): int {
     let result: int = x;
     let i: int = 0;
@@ -61,8 +91,13 @@ fn bit_shl(x: int, n: int): int {
     return result;
 }
 
-// bit_shr(x, n): logical right shift x by n bits (x >> n). n ∈ [0, 30]
-// Note: divides by 2^n, truncating toward zero.
+/// Logical right-shift x by n bits (equivalent to x / 2^n, truncating toward zero).
+/// @since 1.0.0
+/// @param x  Integer to shift
+/// @param n  Number of bit positions to shift right, range [0, 30]
+/// @returns  x >> n (logical, not arithmetic for positive values)
+/// @example
+/// let v: int = bit_shr(256, 3)  // result: 32 (256 >> 3)
 fn bit_shr(x: int, n: int): int {
     let result: int = x;
     let i: int = 0;
@@ -73,7 +108,13 @@ fn bit_shr(x: int, n: int): int {
 // ─── Bitwise AND / OR / XOR ──────────────────────────────────────────────────
 // These iterate over 31 bits (signed int32, bit 31 is sign).
 
-// bit_and(a, b): bitwise AND
+/// Bitwise AND of two integers (all 31 non-sign bits).
+/// @since 1.0.0
+/// @param a  First operand
+/// @param b  Second operand
+/// @returns  a & b (bits set in both a and b)
+/// @example
+/// let v: int = bit_and(0b1100, 0b1010)  // result: 0b1000 = 8
 fn bit_and(a: int, b: int): int {
     let result: int = 0;
     let mask: int = 1;
@@ -90,7 +131,13 @@ fn bit_and(a: int, b: int): int {
     return result;
 }
 
-// bit_or(a, b): bitwise OR
+/// Bitwise OR of two integers (all 31 non-sign bits).
+/// @since 1.0.0
+/// @param a  First operand
+/// @param b  Second operand
+/// @returns  a | b (bits set in either a or b)
+/// @example
+/// let v: int = bit_or(0b1100, 0b1010)  // result: 0b1110 = 14
 fn bit_or(a: int, b: int): int {
     let result: int = 0;
     let mask: int = 1;
@@ -110,7 +157,13 @@ fn bit_or(a: int, b: int): int {
     return result;
 }
 
-// bit_xor(a, b): bitwise XOR
+/// Bitwise XOR of two integers (all 31 non-sign bits).
+/// @since 1.0.0
+/// @param a  First operand
+/// @param b  Second operand
+/// @returns  a ^ b (bits set in exactly one of a or b)
+/// @example
+/// let v: int = bit_xor(0b1100, 0b1010)  // result: 0b0110 = 6
 fn bit_xor(a: int, b: int): int {
     let result: int = 0;
     let mask: int = 1;
@@ -127,7 +180,12 @@ fn bit_xor(a: int, b: int): int {
     return result;
 }
 
-// bit_not(x): bitwise NOT (inverts all 31 bits, sign bit excluded)
+/// Bitwise NOT — inverts all 31 non-sign bits of x.
+/// @since 1.0.0
+/// @param x  Integer to invert
+/// @returns  ~x (all 31 lower bits flipped; sign bit excluded)
+/// @example
+/// let v: int = bit_not(0)  // result: 2147483647 (all 31 bits set)
 fn bit_not(x: int): int {
     let result: int = 0;
     let mask: int = 1;
@@ -144,7 +202,12 @@ fn bit_not(x: int): int {
 
 // ─── Popcount ────────────────────────────────────────────────────────────────
 
-// popcount(x): count number of set bits (0-31)
+/// Count the number of set bits in x (population count / Hamming weight).
+/// @since 1.0.0
+/// @param x  Integer value (uses 31 lower bits; sign bit excluded)
+/// @returns  Number of bits set to 1, in [0, 31]
+/// @example
+/// let n: int = popcount(255)  // result: 8 (0xFF has 8 bits set)
 fn popcount(x: int): int {
     let count: int = 0;
     let v: int = x;

package/src/stdlib/bossbar.mcrs

@@ -1,7 +1,14 @@
 // Bossbar helpers for progress bars and timers
 // Usage: import "stdlib/bossbar.mcrs"
 
-/// Create and show a timer bossbar
+/// Creates a visible timer bossbar for all players.
+/// The bossbar max and current value are initialized to `max_seconds * 20`
+/// so callers can update it directly in game ticks.
+/// @param id           Bossbar identifier, usually `<namespace>:<name>`
+/// @param name         Display name shown on the bossbar
+/// @param max_seconds  Duration in seconds; converted to ticks internally
+/// @example
+/// create_timer_bar("game:round", "Round Timer", 90)
 fn create_timer_bar(id: string, name: string, max_seconds: int) {
     bossbar_add(id, name);
     bossbar_set_max(id, max_seconds * 20);
@@ -12,7 +19,13 @@ fn create_timer_bar(id: string, name: string, max_seconds: int) {
     bossbar_set_visible(id, 1);
 }
 
-/// Create a health-style bossbar (red)
+/// Creates a visible red bossbar initialized at full value.
+/// Useful for boss HP or shared health objectives.
+/// @param id       Bossbar identifier, usually `<namespace>:<name>`
+/// @param name     Display name shown on the bossbar
+/// @param max_val  Maximum value and initial value of the bar
+/// @example
+/// create_health_bar("raid:boss_hp", "Warden", 500)
 fn create_health_bar(id: string, name: string, max_val: int) {
     bossbar_add(id, name);
     bossbar_set_max(id, max_val);
@@ -23,7 +36,13 @@ fn create_health_bar(id: string, name: string, max_val: int) {
     bossbar_set_visible(id, 1);
 }
 
-/// Create a progress bossbar (blue)
+/// Creates a visible blue progress bossbar starting at zero.
+/// Useful for charge bars, capture progress, or phase tracking.
+/// @param id       Bossbar identifier, usually `<namespace>:<name>`
+/// @param name     Display name shown on the bossbar
+/// @param max_val  Maximum progress value
+/// @example
+/// create_progress_bar("game:capture", "Capture", 100)
 fn create_progress_bar(id: string, name: string, max_val: int) {
     bossbar_add(id, name);
     bossbar_set_max(id, max_val);
@@ -34,27 +53,37 @@ fn create_progress_bar(id: string, name: string, max_val: int) {
     bossbar_set_visible(id, 1);
 }
 
-/// Update bossbar value
+/// Sets the current value of an existing bossbar.
+/// RedScript does not clamp the value; Minecraft handles display behavior.
+/// @param id     Bossbar identifier
+/// @param value  New current value
 fn update_bar(id: string, value: int) {
     bossbar_set_value(id, value);
 }
 
-/// Hide bossbar
+/// Hides an existing bossbar from all assigned players.
+/// @param id  Bossbar identifier
 fn hide_bar(id: string) {
     bossbar_set_visible(id, 0);
 }
 
-/// Show bossbar
+/// Shows an existing bossbar to all assigned players.
+/// @param id  Bossbar identifier
 fn show_bar(id: string) {
     bossbar_set_visible(id, 1);
 }
 
-/// Remove bossbar
+/// Removes an existing bossbar entirely.
+/// After removal, the same `id` must be recreated before reuse.
+/// @param id  Bossbar identifier
 fn remove_bar(id: string) {
     bossbar_remove(id);
 }
 
-/// Set bossbar color based on percentage
+/// Updates the bossbar color from a percentage threshold.
+/// Values above 66 use green, above 33 use yellow, otherwise red.
+/// @param id       Bossbar identifier
+/// @param percent  Percentage in the expected 0-100 range
 fn update_bar_color(id: string, percent: int) {
     if (percent > 66) {
         bossbar_set_color(id, "green");