redscript-mc 2.4.0 → 2.5.0

package/src/stdlib/bigint.mcrs

@@ -1,124 +1,65 @@
 // bigint.mcrs — Multi-precision integer arithmetic for RedScript.
 //
-// Representation: "万进制" (base-10000) int array stored in NBT storage.
-//   [1, 2345, 6789] represents 1_0002345_6789 = 100,023,456,789
-//   Each element is 0-9999 (4 decimal digits).
-//   First element is the most significant (big-endian).
-//   Leading zeros in non-first elements must be preserved conceptually.
+// Representation: base-10000 (万进制) int array stored in NBT storage.
+//   arr[0] = most significant chunk (big-endian)
+//   Each element: 0-9999 (4 decimal digits)
+//   Example: [1, 2345, 6789] = 1_0002345_6789 = 100,023,456,789
 //
-// NBT path: storage rs:bigint <varname>
+// Functions for 96-bit (3-chunk) operations:
+//   bigint3_add, bigint3_sub, bigint3_mul1, bigint3_cmp, bigint3_div_by_small
 //
-// Operations use raw() to emit NBT commands. All operations are on stored values.
-// This module provides:
-//   1. Helper functions for single-chunk arithmetic (within int32)
-//   2. raw()-based macros for NBT-backed multi-chunk operations
-//   3. Conversion utilities
-//
-// NOTE: Full arbitrary-precision ops (like kaer's library) require
-// complex NBT recursion not yet expressible in RedScript.
-// This module provides a 96-bit (3 × 4-digit) max precision layer,
-// which covers values up to ~10^12 (1 trillion).
+// Functions for arbitrary-length arrays (requires array by-ref, RedScript ≥ 2.4.0):
+//   bigint_add(a, b, result, len) — add two n-chunk bigints
+//   bigint_cmp(a, b, len)        — compare two n-chunk bigints
+//   bigint_mul_small(a, n, result, len) — multiply n-chunk bigint by small int
+//   bigint_zero(arr, len)        — set array to zero
+//   bigint_copy(src, dst, len)   — copy bigint
 
 module library;
 
 // ─── Constants ───────────────────────────────────────────────────────────────
 
-// BIGINT_BASE: base for 万进制 representation
 fn bigint_base(): int { return 10000; }
 
-// ─── Single-precision helpers ────────────────────────────────────────────────
-// These work on individual 4-digit chunks.
-
-// chunk_hi(n): upper 4 digits of an 8-digit product (n must fit in int32)
-// chunk_hi(12345678) = 1234
-fn chunk_hi(n: int): int {
-    return n / 10000;
-}
-
-// chunk_lo(n): lower 4 digits
-// chunk_lo(12345678) = 5678
-fn chunk_lo(n: int): int {
-    return n % 10000;
-}
-
-// ─── 96-bit (3-chunk) addition ────────────────────────────────────────────────
-// Represents number as (hi, mid, lo) where value = hi*10^8 + mid*10^4 + lo
-
-// bigint3_add_lo(alo, blo): low chunk sum (carry handled by mid)
-fn bigint3_add_lo(alo: int, blo: int): int {
-    return (alo + blo) % 10000;
-}
+// ─── Single-chunk helpers ────────────────────────────────────────────────────
 
-// bigint3_carry_lo(alo, blo): carry from low to mid chunk (0 or 1)
-fn bigint3_carry_lo(alo: int, blo: int): int {
-    return (alo + blo) / 10000;
-}
+fn chunk_hi(n: int): int { return n / 10000; }
+fn chunk_lo(n: int): int { return n % 10000; }
 
-// bigint3_add_mid(amid, bmid, carry): mid chunk sum
-fn bigint3_add_mid(amid: int, bmid: int, carry: int): int {
-    return (amid + bmid + carry) % 10000;
-}
+// ─── 3-chunk (96-bit) arithmetic ─────────────────────────────────────────────
 
-fn bigint3_carry_mid(amid: int, bmid: int, carry: int): int {
-    return (amid + bmid + carry) / 10000;
-}
-
-fn bigint3_add_hi(ahi: int, bhi: int, carry: int): int {
-    return (ahi + bhi + carry) % 10000;
-}
-
-// ─── 96-bit subtraction (a >= b assumed) ─────────────────────────────────────
+fn bigint3_add_lo(alo: int, blo: int): int { return (alo + blo) % 10000; }
+fn bigint3_carry_lo(alo: int, blo: int): int { return (alo + blo) / 10000; }
+fn bigint3_add_mid(amid: int, bmid: int, carry: int): int { return (amid + bmid + carry) % 10000; }
+fn bigint3_carry_mid(amid: int, bmid: int, carry: int): int { return (amid + bmid + carry) / 10000; }
+fn bigint3_add_hi(ahi: int, bhi: int, carry: int): int { return (ahi + bhi + carry) % 10000; }
 
 fn bigint3_sub_lo(alo: int, blo: int): int {
     if (alo >= blo) { return alo - blo; }
     return alo + 10000 - blo;
 }
-
 fn bigint3_borrow_lo(alo: int, blo: int): int {
     if (alo >= blo) { return 0; }
     return 1;
 }
-
 fn bigint3_sub_mid(amid: int, bmid: int, borrow: int): int {
     let v: int = amid - bmid - borrow;
     if (v < 0) { v = v + 10000; }
     return v;
 }
-
 fn bigint3_borrow_mid(amid: int, bmid: int, borrow: int): int {
     if (amid - borrow >= bmid) { return 0; }
     return 1;
 }
-
 fn bigint3_sub_hi(ahi: int, bhi: int, borrow: int): int {
     return ahi - bhi - borrow;
 }
 
-// ─── Multiplication (int × int → 96-bit) ─────────────────────────────────────
-
-// bigint3_mul_lo(a, b): low chunk of a × b (a, b each up to 10^12 / 10^8)
-// For a, b ≤ 9999 (one chunk each):
-fn bigint3_mul1_lo(a: int, b: int): int {
-    return (a * b) % 10000;
-}
-
-fn bigint3_mul1_hi(a: int, b: int): int {
-    return (a * b) / 10000;
-}
-
-// int32 × int32 → 96-bit: a*b where both ≤ 9999
-// Result fits in 8 decimal digits (max 9999*9999 = 99,980,001)
-fn bigint3_mul1_mid(a: int, b: int): int {
-    // No mid chunk needed for 1×1; return 0
-    return 0;
-}
-
-// ─── Comparison ──────────────────────────────────────────────────────────────
+fn bigint3_mul1_lo(a: int, b: int): int { return (a * b) % 10000; }
+fn bigint3_mul1_hi(a: int, b: int): int { return (a * b) / 10000; }
 
-// bigint3_cmp(ahi, amid, alo, bhi, bmid, blo):
-// Returns 1 if a > b, -1 if a < b, 0 if equal
-fn bigint3_cmp(ahi: int, amid: int, alo: int,
-               bhi: int, bmid: int, blo: int): int {
+// Compare: returns 1 if a>b, -1 if a<b, 0 if equal
+fn bigint3_cmp(ahi: int, amid: int, alo: int, bhi: int, bmid: int, blo: int): int {
     if (ahi > bhi) { return 1; }
     if (ahi < bhi) { return -1; }
     if (amid > bmid) { return 1; }
@@ -128,41 +69,128 @@ fn bigint3_cmp(ahi: int, amid: int, alo: int,
     return 0;
 }
 
-// ─── Conversion helpers ───────────────────────────────────────────────────────
-
-// int32_to_bigint3_lo(n): low chunk of n (4 digits)
+// int32 → 3 chunks
 fn int32_to_bigint3_lo(n: int): int {
     if (n < 0) { n = 0 - n; }
     return n % 10000;
 }
-
-// int32_to_bigint3_mid(n): mid chunk (digits 5-8)
 fn int32_to_bigint3_mid(n: int): int {
     if (n < 0) { n = 0 - n; }
     return (n / 10000) % 10000;
 }
-
-// int32_to_bigint3_hi(n): high chunk (digits 9+, usually 0 for int32)
 fn int32_to_bigint3_hi(n: int): int {
     if (n < 0) { n = 0 - n; }
     return n / 100000000;
 }
-
-// bigint3_to_int32(hi, mid, lo): convert back to int32 (truncates if > 2^31)
 fn bigint3_to_int32(hi: int, mid: int, lo: int): int {
     return hi * 100000000 + mid * 10000 + lo;
 }
 
-// ─── Division (96-bit / 16-bit) ──────────────────────────────────────────────
-// Divide 3-chunk bigint by a single small integer (≤ 9999).
-// Algorithm: long division, chunk by chunk.
-
-// bigint3_div_chunk(chunk, rem, divisor): quotient of (rem*10000 + chunk) / divisor
+// Division helpers (array ÷ small int ≤ 9999)
 fn bigint3_div_chunk(chunk: int, rem: int, divisor: int): int {
     return (rem * 10000 + chunk) / divisor;
 }
-
-// bigint3_rem_chunk(chunk, rem, divisor): new remainder after dividing (rem*10000+chunk)
 fn bigint3_rem_chunk(chunk: int, rem: int, divisor: int): int {
     return (rem * 10000 + chunk) % divisor;
 }
+
+// ─── Arbitrary-length operations (array by-ref, RedScript ≥ 2.4.0) ──────────
+
+// bigint_zero(arr, len): set all chunks to 0
+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
+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)
+fn bigint_cmp(a: int[], b: int[], len: int): int {
+    let i: int = 0;
+    while (i < len) {
+        if (a[i] > b[i]) { return 1; }
+        if (a[i] < b[i]) { return -1; }
+        i = i + 1;
+    }
+    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
+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)
+    while (i >= 0) {
+        let sum: int = a[i] + b[i] + carry;
+        result[i] = sum % 10000;
+        carry = sum / 10000;
+        i = i - 1;
+    }
+    return carry;
+}
+
+// bigint_sub(a, b, result, len): result = a - b (assumes a >= b)
+fn bigint_sub(a: int[], b: int[], result: int[], len: int) {
+    let borrow: int = 0;
+    let i: int = len - 1;
+    while (i >= 0) {
+        let diff: int = a[i] - b[i] - borrow;
+        if (diff < 0) {
+            diff = diff + 10000;
+            borrow = 1;
+        }
+        if (diff >= 0) { borrow = 0; }
+        result[i] = diff;
+        i = i - 1;
+    }
+}
+
+// bigint_mul_small(a, n, result, len): result = a × n, where n ≤ 9999
+fn bigint_mul_small(a: int[], n: int, result: int[], len: int) {
+    let carry: int = 0;
+    let i: int = len - 1;
+    while (i >= 0) {
+        let prod: int = a[i] * n + carry;
+        result[i] = prod % 10000;
+        carry = prod / 10000;
+        i = i - 1;
+    }
+}
+
+// bigint_shift_left(arr, len): multiply by 10000 (shift left one chunk)
+// Loses most significant chunk if non-zero
+fn bigint_shift_left(arr: int[], len: int) {
+    let i: int = 0;
+    while (i < len - 1) {
+        arr[i] = arr[i + 1];
+        i = i + 1;
+    }
+    arr[len - 1] = 0;
+}
+
+// bigint_is_zero(arr, len): returns 1 if all chunks are 0
+fn bigint_is_zero(arr: int[], len: int): int {
+    let i: int = 0;
+    while (i < len) {
+        if (arr[i] != 0) { return 0; }
+        i = i + 1;
+    }
+    return 1;
+}
+
+// bigint_leading_zeros(arr, len): count leading zero chunks
+fn bigint_leading_zeros(arr: int[], len: int): int {
+    let count: int = 0;
+    let i: int = 0;
+    while (i < len) {
+        if (arr[i] != 0) { return count; }
+        count = count + 1;
+        i = i + 1;
+    }
+    return count;
+}

package/src/stdlib/easing.mcrs

@@ -0,0 +1,182 @@
+// easing.mcrs — Easing functions for animations and transitions.
+//
+// All functions take t ∈ [0, 10000] (fixed-point ×10000)
+// and return a value in [0, 10000] (or slightly outside for elastic/bounce).
+//
+// Common use: smooth particle movement, UI transitions, projectile arcs
+//
+// Requires: import "stdlib/math" (for abs, clamp, mul_fixed)
+
+module library;
+
+// ─── Linear ──────────────────────────────────────────────────────────────────
+
+fn ease_linear(t: int): int { return t; }
+
+// ─── Quadratic ───────────────────────────────────────────────────────────────
+
+// ease_in_quad: slow start, fast end
+fn ease_in_quad(t: int): int {
+    return t * t / 10000;
+}
+
+// ease_out_quad: fast start, slow end
+fn ease_out_quad(t: int): int {
+    let inv: int = 10000 - t;
+    return 10000 - inv * inv / 10000;
+}
+
+// ease_in_out_quad: slow start and end, fast middle
+fn ease_in_out_quad(t: int): int {
+    if (t < 5000) {
+        return 2 * t * t / 10000;
+    }
+    let inv: int = 10000 - t;
+    return 10000 - 2 * inv * inv / 10000;
+}
+
+// ─── Cubic ───────────────────────────────────────────────────────────────────
+
+fn ease_in_cubic(t: int): int {
+    return t * t / 10000 * t / 10000;
+}
+
+fn ease_out_cubic(t: int): int {
+    let inv: int = 10000 - t;
+    return 10000 - inv * inv / 10000 * inv / 10000;
+}
+
+fn ease_in_out_cubic(t: int): int {
+    if (t < 5000) {
+        return 4 * t * t / 10000 * t / 10000;
+    }
+    let inv: int = 10000 - t;
+    return 10000 - 4 * inv * inv / 10000 * inv / 10000;
+}
+
+// ─── Quartic ──────────────────────────────────────────────────────────────────
+
+fn ease_in_quart(t: int): int {
+    let t2: int = t * t / 10000;
+    return t2 * t2 / 10000;
+}
+
+fn ease_out_quart(t: int): int {
+    let inv: int = 10000 - t;
+    let inv2: int = inv * inv / 10000;
+    return 10000 - inv2 * inv2 / 10000;
+}
+
+// ─── Sine approximation ───────────────────────────────────────────────────────
+// Approximated using polynomial — no actual trig needed for easing
+
+// ease_in_sine: t ∈ [0,10000] → starts slow, accelerates
+fn ease_in_sine(t: int): int {
+    // ≈ 1 - cos(t*π/2) using polynomial: 1 - (1 - t²/2 + t⁴/24)
+    let t2: int = t * t / 10000;
+    let t4: int = t2 * t2 / 10000;
+    let cos_approx: int = 10000 - t2 * 4934 / 10000 + t4 * 405 / 10000;
+    return 10000 - cos_approx;
+}
+
+fn ease_out_sine(t: int): int {
+    return 10000 - ease_in_sine(10000 - t);
+}
+
+fn ease_in_out_sine(t: int): int {
+    if (t < 5000) {
+        return ease_in_sine(t * 2) / 2;
+    }
+    return 5000 + ease_out_sine((t - 5000) * 2) / 2;
+}
+
+// ─── Exponential ─────────────────────────────────────────────────────────────
+
+// ease_in_expo: very slow start, explosive end
+fn ease_in_expo(t: int): int {
+    if (t <= 0) { return 0; }
+    // Approximate 2^(10t-10) ≈ exp_fx((10*t-100000)*693/10000)
+    // Simplified: use cubic as proxy for games
+    let t3: int = t * t / 10000 * t / 10000;
+    return t3;
+}
+
+fn ease_out_expo(t: int): int {
+    if (t >= 10000) { return 10000; }
+    return 10000 - ease_in_expo(10000 - t);
+}
+
+// ─── Back (overshoot) ─────────────────────────────────────────────────────────
+
+// ease_in_back: slight pullback before moving forward
+// c1 = 1.70158 × 10000 = 17015
+fn ease_in_back(t: int): int {
+    let c1: int = 17015;   // 1.70158
+    let c3: int = c1 + 10000;  // c1 + 1
+    // t³ * c3 - t² * c1
+    let t2: int = t * t / 10000;
+    let t3: int = t2 * t / 10000;
+    return t3 * c3 / 10000 - t2 * c1 / 10000;
+}
+
+fn ease_out_back(t: int): int {
+    return 10000 - ease_in_back(10000 - t);
+}
+
+fn ease_in_out_back(t: int): int {
+    if (t < 5000) {
+        return ease_in_back(t * 2) / 2;
+    }
+    return 5000 + ease_out_back((t - 5000) * 2) / 2;
+}
+
+// ─── Bounce ───────────────────────────────────────────────────────────────────
+
+// ease_out_bounce: bounces at the end (ball dropping)
+fn ease_out_bounce(t: int): int {
+    let n1: int = 75625;  // 7.5625 × 10000
+    let d1: int = 27500;  // 2.75 × 10000
+    // Piecewise: 4 bounce segments
+    if (t < 3636) {  // t < 1/2.75
+        return n1 * t / 10000 * t / 10000;
+    }
+    if (t < 7272) {  // t < 2/2.75
+        let t2: int = t - 5454;  // t - 1.5/2.75
+        return n1 * t2 / 10000 * t2 / 10000 + 7500;
+    }
+    if (t < 9090) {  // t < 2.5/2.75
+        let t2: int = t - 8181;  // t - 2.25/2.75
+        return n1 * t2 / 10000 * t2 / 10000 + 9375;
+    }
+    let t2: int = t - 9545;  // t - 2.625/2.75
+    return n1 * t2 / 10000 * t2 / 10000 + 9844;
+}
+
+fn ease_in_bounce(t: int): int {
+    return 10000 - ease_out_bounce(10000 - t);
+}
+
+fn ease_in_out_bounce(t: int): int {
+    if (t < 5000) {
+        return ease_in_bounce(t * 2) / 2;
+    }
+    return 5000 + ease_out_bounce((t - 5000) * 2) / 2;
+}
+
+// ─── Smoothstep family ────────────────────────────────────────────────────────
+
+// smoothstep already in math.mcrs — re-exported here for convenience
+// smoothstep(t) = 3t² - 2t³
+fn ease_smooth(t: int): int {
+    return 3 * t * t / 10000 - 2 * t * t / 10000 * t / 10000;
+}
+
+// smootherstep: even smoother (Ken Perlin)
+// 6t⁵ - 15t⁴ + 10t³
+fn ease_smoother(t: int): int {
+    let t2: int = t * t / 10000;
+    let t3: int = t2 * t / 10000;
+    let t4: int = t3 * t / 10000;
+    let t5: int = t4 * t / 10000;
+    return 6 * t5 / 10000 - 15 * t4 / 10000 + 10 * t3 / 10000;
+}

package/src/stdlib/list.mcrs

@@ -94,3 +94,79 @@ fn weighted3(seed: int, w0: int, w1: int, w2: int): int {
     if (v < w0 + w1) { return 1; }
     return 2;
 }
+
+// ─── Sorting networks (fixed-size, optimal compare-swap count) ────────────────
+
+// sort4(a,b,c,d, pos): sort 4 values, return value at position pos (0=min)
+// Uses 5-comparison optimal sorting network
+fn sort4(a: int, b: int, c: int, d: int, pos: int): int {
+    let w: int = a; let x: int = b; let y: int = c; let z: int = d;
+    // Sorting network for 4 elements
+    if (w > x) { let t: int = w; w = x; x = t; }
+    if (y > z) { let t: int = y; y = z; z = t; }
+    if (w > y) { let t: int = w; w = y; y = t; }
+    if (x > z) { let t: int = x; x = z; z = t; }
+    if (x > y) { let t: int = x; x = y; y = t; }
+    if (pos == 0) { return w; }
+    if (pos == 1) { return x; }
+    if (pos == 2) { return y; }
+    return z;
+}
+
+// sort5(a,b,c,d,e, pos): sort 5 values, return value at position pos
+// Uses 9-comparison sorting network
+fn sort5(a: int, b: int, c: int, d: int, e: int, pos: int): int {
+    let v0: int = a; let v1: int = b; let v2: int = c; let v3: int = d; let v4: int = e;
+    // 9-comparison sorting network (Batcher odd-even merge sort)
+    if (v0 > v1) { let t: int = v0; v0 = v1; v1 = t; }
+    if (v2 > v3) { let t: int = v2; v2 = v3; v3 = t; }
+    if (v0 > v2) { let t: int = v0; v0 = v2; v2 = t; }
+    if (v1 > v4) { let t: int = v1; v1 = v4; v4 = t; }
+    if (v0 > v1) { let t: int = v0; v0 = v1; v1 = t; }
+    if (v2 > v3) { let t: int = v2; v2 = v3; v3 = t; }
+    if (v1 > v2) { let t: int = v1; v1 = v2; v2 = t; }
+    if (v3 > v4) { let t: int = v3; v3 = v4; v4 = t; }
+    if (v2 > v3) { let t: int = v2; v2 = v3; v3 = t; }
+    if (pos == 0) { return v0; }
+    if (pos == 1) { return v1; }
+    if (pos == 2) { return v2; }
+    if (pos == 3) { return v3; }
+    return v4;
+}
+
+// ─── Dynamic sort (arbitrary-length, uses array reference passing) ─────────────
+
+// list_sort_asc(arr, len): in-place ascending bubble sort
+// Requires RedScript ≥ 2.4.0 (array parameter by reference)
+fn list_sort_asc(arr: int[], len: int) {
+    let i: int = 0;
+    while (i < len - 1) {
+        let j: int = 0;
+        while (j < len - 1 - i) {
+            if (arr[j] > arr[j + 1]) {
+                let tmp: int = arr[j];
+                arr[j] = arr[j + 1];
+                arr[j + 1] = tmp;
+            }
+            j = j + 1;
+        }
+        i = i + 1;
+    }
+}
+
+// list_sort_desc(arr, len): in-place descending bubble sort
+fn list_sort_desc(arr: int[], len: int) {
+    let i: int = 0;
+    while (i < len - 1) {
+        let j: int = 0;
+        while (j < len - 1 - i) {
+            if (arr[j] < arr[j + 1]) {
+                let tmp: int = arr[j];
+                arr[j] = arr[j + 1];
+                arr[j + 1] = tmp;
+            }
+            j = j + 1;
+        }
+        i = i + 1;
+    }
+}

package/src/stdlib/matrix.mcrs

@@ -0,0 +1,108 @@
+// matrix.mcrs — 2D/3D transformation matrices for Display Entities.
+//
+// MC Display Entities use a 4×4 transformation matrix (left_rotation × scale × right_rotation).
+// This module provides helpers for common transforms.
+//
+// Fixed-point: all values ×10000 unless noted.
+// Angle: degrees ×10000 (e.g. 450000 = 45°)
+//
+// Note: Actual matrix application to entities requires raw() commands.
+// These functions compute the values; use raw() to apply them.
+//
+// Requires: import "stdlib/math" (for sin_fixed, cos_fixed, abs)
+
+module library;
+
+// ─── 2D transform helpers ────────────────────────────────────────────────────
+
+// rotate2d_x: x component after 2D rotation by angle_deg×10000
+// rotate2d_x(x, y, 450000) ≈ x*cos45 - y*sin45
+fn rotate2d_x(x: int, y: int, angle_deg: int): int {
+    let c: int = cos_fixed(angle_deg / 10000);
+    let s: int = sin_fixed(angle_deg / 10000);
+    return x * c / 1000 - y * s / 1000;
+}
+
+fn rotate2d_y(x: int, y: int, angle_deg: int): int {
+    let c: int = cos_fixed(angle_deg / 10000);
+    let s: int = sin_fixed(angle_deg / 10000);
+    return x * s / 1000 + y * c / 1000;
+}
+
+// ─── Scale helpers ────────────────────────────────────────────────────────────
+
+// scale_x(x, sx_fx): scale x by sx_fx (sx_fx ×10000, e.g. 20000 = 2×)
+fn scale_x(x: int, sx_fx: int): int { return x * sx_fx / 10000; }
+fn scale_y(y: int, sy_fx: int): int { return y * sy_fx / 10000; }
+fn scale_z(z: int, sz_fx: int): int { return z * sz_fx / 10000; }
+
+// uniform_scale(v, s_fx): apply uniform scale
+fn uniform_scale(v: int, s_fx: int): int { return v * s_fx / 10000; }
+
+// ─── 3D rotation (Euler angles, Y-up) ────────────────────────────────────────
+
+// rotate_y_x: X component after rotation around Y axis
+fn rotate_y_x(x: int, z: int, angle_deg: int): int {
+    let c: int = cos_fixed(angle_deg / 10000);
+    let s: int = sin_fixed(angle_deg / 10000);
+    return x * c / 1000 + z * s / 1000;
+}
+
+fn rotate_y_z(x: int, z: int, angle_deg: int): int {
+    let c: int = cos_fixed(angle_deg / 10000);
+    let s: int = sin_fixed(angle_deg / 10000);
+    return 0 - x * s / 1000 + z * c / 1000;
+}
+
+// rotate_x_y: Y component after rotation around X axis
+fn rotate_x_y(y: int, z: int, angle_deg: int): int {
+    let c: int = cos_fixed(angle_deg / 10000);
+    let s: int = sin_fixed(angle_deg / 10000);
+    return y * c / 1000 - z * s / 1000;
+}
+
+fn rotate_x_z(y: int, z: int, angle_deg: int): int {
+    let c: int = cos_fixed(angle_deg / 10000);
+    let s: int = sin_fixed(angle_deg / 10000);
+    return y * s / 1000 + z * c / 1000;
+}
+
+// ─── Display Entity transformation ───────────────────────────────────────────
+// MC Display Entity transformation format:
+//   transformation: {left_rotation:[0f,0f,0f,1f], scale:[1f,1f,1f],
+//                    right_rotation:[0f,0f,0f,1f], translation:[0f,0f,0f]}
+//
+// Quaternion for Y-axis rotation by angle θ:
+//   [0, sin(θ/2), 0, cos(θ/2)]
+//
+// These helpers compute quaternion components (×10000)
+
+// quat_sin_half(angle_deg_fx): sin(angle/2) ×1000
+// angle_deg_fx: degrees ×10000
+fn quat_sin_half(angle_deg_fx: int): int {
+    return sin_fixed(angle_deg_fx / 20000);  // angle/2 in degrees, then /10000 for sin_fixed
+}
+
+fn quat_cos_half(angle_deg_fx: int): int {
+    return cos_fixed(angle_deg_fx / 20000);
+}
+
+// ─── Billboard helpers ────────────────────────────────────────────────────────
+
+// billboard_rotation_y(player_yaw_fx): get Y rotation for a billboard facing player
+// player_yaw_fx: player yaw ×10000 (from entity NBT Rotation[0])
+fn billboard_y(player_yaw_fx: int): int {
+    // Billboard should face opposite direction
+    return (player_yaw_fx + 1800000) % 3600000;
+}
+
+// ─── Interpolation for smooth animation ──────────────────────────────────────
+
+// lerp_angle(a_fx, b_fx, t): lerp between two angles ×10000, taking shortest path
+fn lerp_angle(a_fx: int, b_fx: int, t: int): int {
+    let diff: int = b_fx - a_fx;
+    // Normalize to [-1800000, 1800000]
+    while (diff > 1800000) { diff = diff - 3600000; }
+    while (diff < -1800000) { diff = diff + 3600000; }
+    return a_fx + diff * t / 10000;
+}