redscript-mc 2.5.0 → 2.6.2

package/src/stdlib/bigint.mcrs

@@ -194,3 +194,254 @@ fn bigint_leading_zeros(arr: int[], len: int): int {
     }
     return count;
 }
+
+// ─── Division: bigint ÷ small integer ────────────────────────────────────────
+// Divides n-chunk bigint by a small integer (1 ≤ divisor ≤ 9999)
+// Algorithm: long division chunk by chunk (most-significant first)
+// 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.
+fn bigint_div_small(a: int[], divisor: int, result: int[], len: int): int {
+    let rem: int = 0;
+    let i: int = 0;
+    while (i < len) {
+        let cur: int = rem * 10000 + a[i];
+        result[i] = cur / divisor;
+        rem = cur % divisor;
+        i = i + 1;
+    }
+    return rem;
+}
+
+// bigint_mod_small(a, divisor, len): return a % divisor (0..divisor-1)
+fn bigint_mod_small(a: int[], divisor: int, len: int): int {
+    let rem: int = 0;
+    let i: int = 0;
+    while (i < len) {
+        rem = (rem * 10000 + a[i]) % divisor;
+        i = i + 1;
+    }
+    return rem;
+}
+
+// bigint_print_chunks(a, len): get the value of chunk at index i
+// Helper to read specific chunk for display purposes
+fn bigint_chunk(a: int[], i: int): int {
+    return a[i];
+}
+
+// ─── Full bigint × bigint multiplication ─────────────────────────────────────
+//
+// bigint_mul(a, b, result, la, lb):
+//   Multiply two bigints: result = a * b
+//   a has la chunks, b has lb chunks, result must have la+lb chunks (pre-zeroed)
+//   Uses schoolbook O(n²) algorithm.
+//   Maximum safe chunk product: 9999 * 9999 = 99,980,001 < INT32_MAX ✓
+//   After accumulation each chunk can exceed 10000 — carry_pass normalizes.
+//
+// Usage:
+//   import "stdlib/bigint"
+//   let a: int[] = [0, 0, 1234, 5678];   // 4-chunk
+//   let b: int[] = [0, 0, 9999];          // 3-chunk
+//   let result: int[] = [0, 0, 0, 0, 0, 0, 0]; // la+lb = 7 chunks, pre-zeroed
+//   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]
+    // result has la+lb chunks; result[la+lb-1] is the LSB chunk
+    let i: int = 0;
+    while (i < la) {
+        let j: int = 0;
+        while (j < lb) {
+            // Position in result: MSB-aligned
+            // a[i] * b[j] contributes to result[i + j + 1] (1-indexed from MSB, 0 = overflow slot)
+            let pos: int = i + j + 1;
+            result[pos] = result[pos] + a[i] * b[j];
+            j = j + 1;
+        }
+        i = i + 1;
+    }
+
+    // Phase 2: carry propagation from LSB to MSB
+    let total: int = la + lb;
+    let k: int = total - 1;
+    while (k > 0) {
+        let carry: int = result[k] / 10000;
+        result[k] = result[k] % 10000;
+        result[k - 1] = result[k - 1] + carry;
+        k = k - 1;
+    }
+}
+
+// bigint_mul_result_len(la, lb): required result array length for bigint_mul
+fn bigint_mul_result_len(la: int, lb: int): int {
+    return la + lb;
+}
+
+// bigint_sq(a, result, len):
+//   Square a bigint: result = a * a
+//   result must have len*2 chunks (pre-zeroed).
+//   Optimized: only compute upper triangle and double (avoids redundant multiplications).
+//
+fn bigint_sq(a: int[], result: int[], len: int) {
+    // Diagonal terms (i == j)
+    let i: int = 0;
+    while (i < len) {
+        let pos: int = i + i + 1;
+        result[pos] = result[pos] + a[i] * a[i];
+        i = i + 1;
+    }
+
+    // Off-diagonal terms (i < j), doubled
+    i = 0;
+    while (i < len) {
+        let j: int = i + 1;
+        while (j < len) {
+            let pos: int = i + j + 1;
+            // a[i]*a[j] * 2 — safe: 9999*9999*2 = 199,960,002 < INT32_MAX
+            result[pos] = result[pos] + a[i] * a[j] * 2;
+            j = j + 1;
+        }
+        i = i + 1;
+    }
+
+    // Carry propagation
+    let total: int = len * 2;
+    let k: int = total - 1;
+    while (k > 0) {
+        let carry: int = result[k] / 10000;
+        result[k] = result[k] % 10000;
+        result[k - 1] = result[k - 1] + carry;
+        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.
+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/calculus.mcrs

@@ -0,0 +1,150 @@
+// calculus.mcrs — Numerical calculus for RedScript datapacks.
+//
+// All values fixed-point ×10000 unless noted.
+//
+// Methods:
+//   - Numerical differentiation (finite difference)
+//   - Numerical integration (trapezoid, Simpson's rule over fixed arrays)
+//   - Riemann sum helpers
+//   - Curve length approximation
+
+module library;
+
+// ─── Differentiation ─────────────────────────────────────────────────────────
+
+// deriv_forward(f1, f0, h_fx): forward difference derivative
+// f1 = f(x+h), f0 = f(x), h_fx = step size ×10000
+// Returns df/dx ×10000
+fn deriv_forward(f1: int, f0: int, h_fx: int): int {
+    if (h_fx == 0) { return 0; }
+    return (f1 - f0) * 10000 / h_fx;
+}
+
+// deriv_central(f_plus, f_minus, h_fx): central difference (more accurate)
+// f_plus = f(x+h), f_minus = f(x-h)
+// Returns df/dx ×10000
+fn deriv_central(f_plus: int, f_minus: int, h_fx: int): int {
+    if (h_fx == 0) { return 0; }
+    return (f_plus - f_minus) * 10000 / (2 * h_fx);
+}
+
+// second_deriv(f_plus, f0, f_minus, h_fx): second derivative
+// Returns d²f/dx² ×10000
+fn second_deriv(f_plus: int, f0: int, f_minus: int, h_fx: int): int {
+    if (h_fx == 0) { return 0; }
+    return (f_plus - 2 * f0 + f_minus) * 100000000 / h_fx / h_fx;
+}
+
+// ─── Integration over arrays ──────────────────────────────────────────────────
+//
+// For integration, the user provides an array of function values at equally
+// spaced points, and the step size.
+
+// integrate_trapezoid(vals, n, h_fx): trapezoidal rule integration
+// vals: array of n function values ×10000, equally spaced by h_fx
+// h_fx: step width ×10000
+// Returns integral ×10000 (area under curve)
+fn integrate_trapezoid(vals: int[], n: int, h_fx: int): int {
+    if (n < 2) { return 0; }
+    // Sum = (vals[0] + vals[n-1]) / 2 + vals[1] + vals[2] + ... + vals[n-2]
+    let sum: int = vals[0] / 2 + vals[n - 1] / 2;
+    let i: int = 1;
+    while (i < n - 1) {
+        sum = sum + vals[i];
+        i = i + 1;
+    }
+    return sum * h_fx / 10000;
+}
+
+// integrate_simpson(vals, n, h_fx): Simpson's 1/3 rule (n must be odd, n ≥ 3)
+// More accurate than trapezoid for smooth functions
+fn integrate_simpson(vals: int[], n: int, h_fx: int): int {
+    if (n < 3) { return integrate_trapezoid(vals, n, h_fx); }
+    // Ensure n is odd by using n-1 if even
+    let m: int = n;
+    if (m % 2 == 0) { m = m - 1; }
+    // Coefficients: 1, 4, 2, 4, 2, ..., 4, 1 (times h/3)
+    let sum: int = vals[0] + vals[m - 1];
+    let i: int = 1;
+    while (i < m - 1) {
+        if (i % 2 == 1) {
+            sum = sum + 4 * vals[i];
+        }
+        if (i % 2 == 0) {
+            sum = sum + 2 * vals[i];
+        }
+        i = i + 1;
+    }
+    return sum * h_fx / 30000;  // × h/3 = h_fx / (3 × 10000)
+}
+
+// ─── Riemann sums ─────────────────────────────────────────────────────────────
+
+// riemann_left(vals, n, h_fx): left Riemann sum
+fn riemann_left(vals: int[], n: int, h_fx: int): int {
+    let sum: int = 0;
+    let i: int = 0;
+    while (i < n - 1) { sum = sum + vals[i]; i = i + 1; }
+    return sum * h_fx / 10000;
+}
+
+// riemann_right(vals, n, h_fx): right Riemann sum
+fn riemann_right(vals: int[], n: int, h_fx: int): int {
+    let sum: int = 0;
+    let i: int = 1;
+    while (i < n) { sum = sum + vals[i]; i = i + 1; }
+    return sum * h_fx / 10000;
+}
+
+// riemann_mid(vals, n, h_fx): midpoint Riemann sum
+// vals: midpoint values (n-1 midpoints for n-1 intervals)
+fn riemann_mid(vals: int[], n: int, h_fx: int): int {
+    let sum: int = 0;
+    let i: int = 0;
+    while (i < n) { sum = sum + vals[i]; i = i + 1; }
+    return sum * h_fx / 10000;
+}
+
+// ─── Curve length ────────────────────────────────────────────────────────────
+
+// curve_length_2d(xs, ys, n): approximate arc length of a 2D polyline
+// xs, ys: x and y coordinates ×10000 of n points
+fn curve_length_2d(xs: int[], ys: int[], n: int): int {
+    let total: int = 0;
+    let i: int = 0;
+    while (i < n - 1) {
+        let dx: int = xs[i + 1] - xs[i];
+        let dy: int = ys[i + 1] - ys[i];
+        let seg_sq: int = dx * dx / 10000 + dy * dy / 10000;
+        total = total + isqrt(seg_sq * 100) * 100;
+        i = i + 1;
+    }
+    return total;
+}
+
+// ─── Running statistics ───────────────────────────────────────────────────────
+
+// running_mean(prev_mean, new_val, n): Welford's online mean update
+// prev_mean ×10000, new_val ×10000, n: count after adding new_val (n ≥ 1)
+fn running_mean(prev_mean: int, new_val: int, n: int): int {
+    if (n <= 1) { return new_val; }
+    return prev_mean + (new_val - prev_mean) * 10000 / (n * 10000);
+}
+
+// running_m2(prev_m2, prev_mean, new_mean, new_val): Welford's M2 update
+// Used to compute variance: variance = m2 / (n-1)
+fn running_m2(prev_m2: int, prev_mean: int, new_mean: int, new_val: int): int {
+    return prev_m2 + (new_val - prev_mean) * (new_val - new_mean) / 10000;
+}
+
+// variance_from_m2(m2, n): get variance from Welford's M2, n = number of samples
+fn variance_from_m2(m2: int, n: int): int {
+    if (n <= 1) { return 0; }
+    return m2 / (n - 1);
+}
+
+// std_dev_approx(variance_fx): approximate std dev = √variance
+fn std_dev_approx(variance_fx: int): int {
+    if (variance_fx <= 0) { return 0; }
+    return isqrt(variance_fx * 100) * 100 / 10000;
+}

package/src/stdlib/color.mcrs

@@ -1,9 +1,7 @@
 // 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
+// Pack/unpack: RGB values 0-255, packed int 0xRRGGBB = R*65536 + G*256 + B
+// HSL ×10000 scale: R,G,B ∈ [0,2550000], H ∈ [0,3600000], S,L ∈ [0,10000]
 //
 // Note: No native bitwise ops in MC scoreboard — packing/unpacking uses multiply/divide.
 
@@ -48,71 +46,14 @@ fn rgb_lerp(a: int, b: int, t: int): int {
     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 → HSL (×10000 scale) ─────────────────────────────────────────────────
+//
+// All values ×10000 scale:
+//   R, G, B ∈ [0, 2550000]  (255 × 10000)
+//   H ∈ [0, 3600000]        (360° × 10000)
+//   S, L ∈ [0, 10000]       (1.0 × 10000)
 
-// rgb_to_l(r, g, b): lightness 0-100
+// rgb_to_l(r, g, b): lightness ×10000, range [0, 10000]
 fn rgb_to_l(r: int, g: int, b: int): int {
     let mx: int = r;
     if (g > mx) { mx = g; }
@@ -120,10 +61,10 @@ fn rgb_to_l(r: int, g: int, b: int): int {
     let mn: int = r;
     if (g < mn) { mn = g; }
     if (b < mn) { mn = b; }
-    return (mx + mn) * 100 / 510;
+    return (mx + mn) / 510;
 }
 
-// rgb_to_s(r, g, b): saturation 0-100
+// rgb_to_s(r, g, b): saturation ×10000, range [0, 10000]
 fn rgb_to_s(r: int, g: int, b: int): int {
     let mx: int = r;
     if (g > mx) { mx = g; }
@@ -131,14 +72,16 @@ fn rgb_to_s(r: int, g: int, b: int): int {
     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);
+    let d: int = mx - mn;
+    if (d == 0) { return 0; }
+    let l: int = (mx + mn) / 510;
+    let denom: int = 2 * l;
+    if (20000 - 2 * l < denom) { denom = 20000 - 2 * l; }
+    if (denom == 0) { return 0; }
+    return d * 10000 / (255 * denom);
 }
 
-// rgb_to_h(r, g, b): hue 0-360
+// rgb_to_h(r, g, b): hue ×10000, range [0, 3600000]
 fn rgb_to_h(r: int, g: int, b: int): int {
     let mx: int = r;
     if (g > mx) { mx = g; }
@@ -146,15 +89,92 @@ fn rgb_to_h(r: int, g: int, b: int): int {
     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 d: int = mx - mn;
+    if (d == 0) { return 0; }
     if (mx == r) {
-        let h: int = 60 * (g - b) / c;
-        if (h < 0) { h = h + 360; }
+        let h: int = 600000 * (g - b) / d;
+        if (h < 0) { h = h + 3600000; }
         return h;
     }
     if (mx == g) {
-        return 60 * (b - r) / c + 120;
+        return 1200000 + 600000 * (b - r) / d;
     }
-    return 60 * (r - g) / c + 240;
+    return 2400000 + 600000 * (r - g) / d;
+}
+
+// ─── HSL → RGB (×10000 scale) ─────────────────────────────────────────────────
+
+// _hsl10k_chroma_x: helper — X component for HSL→RGB conversion (×10000 scale)
+// c: chroma ×10000, h: hue ×10000 [0, 3600000]
+fn _hsl10k_chroma_x(h: int, c: int): int {
+    // X = C * (1 - |H/600000 mod 2 - 1|)
+    let rem: int = h % 1200000;
+    if (rem > 600000) { rem = 1200000 - rem; }
+    return c * rem / 600000;
+}
+
+// _hsl10k_chroma: chroma C = (1 - |2L-1|) * S, all ×10000
+fn _hsl10k_chroma(s: int, l: int): int {
+    let abs2l1: int = 2 * l - 10000;
+    if (abs2l1 < 0) { abs2l1 = 0 - abs2l1; }
+    return (10000 - abs2l1) * s / 10000;
+}
+
+// hsl_to_r(h, s, l): H×10000, S×10000, L×10000 → R ∈ [0, 2550000]
+fn hsl_to_r(h: int, s: int, l: int): int {
+    let c: int = _hsl10k_chroma(s, l);
+    let x: int = _hsl10k_chroma_x(h, c);
+    let m: int = l - c / 2;
+    let sector: int = h / 600000;
+    let r1: int = 0;
+    if (sector == 0) { r1 = c; }
+    if (sector == 1) { r1 = x; }
+    if (sector == 4) { r1 = x; }
+    if (sector == 5) { r1 = c; }
+    return (r1 + m) * 255;
+}
+
+// hsl_to_g(h, s, l): H×10000, S×10000, L×10000 → G ∈ [0, 2550000]
+fn hsl_to_g(h: int, s: int, l: int): int {
+    let c: int = _hsl10k_chroma(s, l);
+    let x: int = _hsl10k_chroma_x(h, c);
+    let m: int = l - c / 2;
+    let sector: int = h / 600000;
+    let g1: int = 0;
+    if (sector == 0) { g1 = x; }
+    if (sector == 1) { g1 = c; }
+    if (sector == 2) { g1 = c; }
+    if (sector == 3) { g1 = x; }
+    return (g1 + m) * 255;
+}
+
+// hsl_to_b(h, s, l): H×10000, S×10000, L×10000 → B ∈ [0, 2550000]
+fn hsl_to_b(h: int, s: int, l: int): int {
+    let c: int = _hsl10k_chroma(s, l);
+    let x: int = _hsl10k_chroma_x(h, c);
+    let m: int = l - c / 2;
+    let sector: int = h / 600000;
+    let b1: int = 0;
+    if (sector == 2) { b1 = x; }
+    if (sector == 3) { b1 = c; }
+    if (sector == 4) { b1 = c; }
+    if (sector == 5) { b1 = x; }
+    return (b1 + m) * 255;
+}
+
+// hsl_to_packed(h, s, l): HSL (×10000 scale) → packed RGB int (0xRRGGBB)
+fn hsl_to_packed(h: int, s: int, l: int): int {
+    let r: int = hsl_to_r(h, s, l) / 10000;
+    let g: int = hsl_to_g(h, s, l) / 10000;
+    let b: int = hsl_to_b(h, s, l) / 10000;
+    return rgb_pack(r, g, b);
+}
+
+// ─── rgb_to_hex ───────────────────────────────────────────────────────────────
+
+// rgb_to_hex(r, g, b): pack RGB into 0xRRGGBB integer
+// Equivalent to rgb_pack; provided as an explicit named alias.
+// r, g, b ∈ [0, 255]; no fixed-point — simple integer arithmetic.
+fn rgb_to_hex(r: int, g: int, b: int): int {
+    return r * 65536 + g * 256 + b;
 }

package/src/stdlib/combat.mcrs

@@ -1,20 +1,26 @@
+// module library
 // Combat helpers for simple RPG-style datapacks.
 
-fn weapon_damage(base: int, bonus: int) -> int {
-    return base + bonus;
+// Returns base + bonus damage.
+fn weapon_damage(base: int, bonus: int): int {
+    return base + bonus
 }
 
-fn enemy_health(name: string) -> int {
-    return scoreboard_get(name, #health);
+// Applies damage to a health value, clamping to 0.
+// Usage: let new_hp: int = take_damage(current_hp, amount)
+// Then: scoreboard_set(player, objective, new_hp)
+fn take_damage(health: int, amount: int): int {
+    let next: int = health - amount
+    if (next < 0) {
+        next = 0
+    }
+    return next
 }
 
-fn apply_damage(name: string, amount: int) {
-    let health: int = enemy_health(name);
-    let next: int = health - amount;
-
-    if (next < 0) {
-        scoreboard_set(name, #health, 0);
-    } else {
-        scoreboard_set(name, #health, next);
+// Returns 1 if health <= 0 (dead), else 0.
+fn is_dead(health: int): int {
+    if (health <= 0) {
+        return 1
     }
+    return 0
 }