redscript-mc 2.4.1 → 2.6.0

package/src/stdlib/math_hp.mcrs

@@ -63,3 +63,455 @@ fn cos_hp(angle: int): int {
     raw("tp @e[tag=rs_trig,limit=1] 0 0 0");
     return scoreboard_get("$cos_hp_out", "__rs_math_hp");
 }
+
+// ─── Display Entity SVD: High-precision arithmetic ────────────────────────────
+//
+// MC Display Entities use SVD (Singular Value Decomposition) internally.
+// By setting a diagonal matrix [a,0,0,0, 0,b,0,0, 0,0,c,0, 0,0,0,d],
+// MC computes scale = [a/d, b/d, c/d] in Java double precision (~15 sig figs).
+//
+// This allows:
+//   - div_hp(a, b)        → a/b with double precision
+//   - div3_hp(a,b,c, d)  → [a/d, b/d, c/d] — three divisions in one call
+//   - sqrt_hp(x)          → √x via distance trick
+//   - norm3_hp(x, y, z)  → √(x²+y²+z²) via vector magnitude
+//
+// ⚠ SETUP: Also call init_trig() in your @load (reuses rs_trig entity).
+//   Uses a SEPARATE entity tagged "rs_div" for SVD operations.
+//   init_trig() does NOT create rs_div — call init_div() separately.
+
+// init_div(): create the Display Entity for SVD operations.
+// Call once from your @load function.
+@require_on_load(init_div)
+fn init_div() {
+    raw("execute unless entity @e[tag=rs_div,limit=1] run summon minecraft:block_display ~ 0 ~ {Tags:[\"rs_div\"]}");
+}
+
+// div_hp(a, b): high-precision division a/b, returns (a/b) × 10000
+// a, b: integers (×10000 scale). Result: (a/b) × 10000
+// Example: div_hp(10000, 3000) ≈ 33333 (10000/3000 = 3.3333...)
+@require_on_load(init_div)
+fn div_hp(a: int, b: int): int {
+    // Set transformation matrix: [a,0,0,0, 0,1,0,0, 0,0,1,0, 0,0,0,b]
+    // MC SVD gives scale.x = a/b
+    scoreboard_set("$div_a", "__rs_math_hp", a);
+    scoreboard_set("$div_b", "__rs_math_hp", b);
+    raw("execute store result storage rs:math_hp div_a float 0.0001 run scoreboard players get $div_a __rs_math_hp");
+    raw("execute store result storage rs:math_hp div_b float 0.0001 run scoreboard players get $div_b __rs_math_hp");
+    raw("data modify entity @e[tag=rs_div,limit=1] transformation set value {left_rotation:[0f,0f,0f,1f],scale:[1f,1f,1f],right_rotation:[0f,0f,0f,1f],translation:[0f,0f,0f]}");
+    raw("execute store result storage rs:math_hp div_mat[0] float 1 run data get storage rs:math_hp div_a");
+    raw("execute store result storage rs:math_hp div_mat[15] float 1 run data get storage rs:math_hp div_b");
+    raw("data modify entity @e[tag=rs_div,limit=1] transformation set from storage rs:math_hp div_mat");
+    raw("execute store result score $div_result __rs_math_hp run data get entity @e[tag=rs_div,limit=1] transformation.scale[0] 10000.0");
+    return scoreboard_get("$div_result", "__rs_math_hp");
+}
+
+// div3_hp(a, b, c, d): divide three values by d simultaneously
+// Returns a/d, result in scoreboard $div3_x/y/z __rs_math_hp (×10000)
+// Use scoreboard_get to read each result.
+@require_on_load(init_div)
+fn div3_hp(a: int, b: int, c: int, d: int): int {
+    scoreboard_set("$div3_a", "__rs_math_hp", a);
+    scoreboard_set("$div3_b", "__rs_math_hp", b);
+    scoreboard_set("$div3_c", "__rs_math_hp", c);
+    scoreboard_set("$div3_d", "__rs_math_hp", d);
+    raw("execute store result storage rs:math_hp d3a float 0.0001 run scoreboard players get $div3_a __rs_math_hp");
+    raw("execute store result storage rs:math_hp d3b float 0.0001 run scoreboard players get $div3_b __rs_math_hp");
+    raw("execute store result storage rs:math_hp d3c float 0.0001 run scoreboard players get $div3_c __rs_math_hp");
+    raw("execute store result storage rs:math_hp d3d float 0.0001 run scoreboard players get $div3_d __rs_math_hp");
+    // Build diagonal matrix [a,0,0,0, 0,b,0,0, 0,0,c,0, 0,0,0,d]
+    raw("data modify storage rs:math_hp div3_mat set value [0f,0f,0f,0f,0f,0f,0f,0f,0f,0f,0f,0f,0f,0f,0f,0f]");
+    raw("execute store result storage rs:math_hp div3_mat[0] float 1 run data get storage rs:math_hp d3a");
+    raw("execute store result storage rs:math_hp div3_mat[5] float 1 run data get storage rs:math_hp d3b");
+    raw("execute store result storage rs:math_hp div3_mat[10] float 1 run data get storage rs:math_hp d3c");
+    raw("execute store result storage rs:math_hp div3_mat[15] float 1 run data get storage rs:math_hp d3d");
+    raw("data modify entity @e[tag=rs_div,limit=1] transformation set from storage rs:math_hp div3_mat");
+    // Read all three scale components
+    raw("execute store result score $div3_x __rs_math_hp run data get entity @e[tag=rs_div,limit=1] transformation.scale[0] 10000.0");
+    raw("execute store result score $div3_y __rs_math_hp run data get entity @e[tag=rs_div,limit=1] transformation.scale[1] 10000.0");
+    raw("execute store result score $div3_z __rs_math_hp run data get entity @e[tag=rs_div,limit=1] transformation.scale[2] 10000.0");
+    return scoreboard_get("$div3_x", "__rs_math_hp");
+}
+
+// sqrt_hp(x): high-precision square root via vector magnitude trick
+// x: integer ×10000. Returns √(x/10000) × 10000
+// Uses: send vector (√x, 0, 0) unit → magnitude = √x
+@require_on_load(init_div)
+fn sqrt_hp(x: int): int {
+    // Use trig entity: tp it to (sqrt(x), 0, 0) direction
+    // Trick: set pos to (x_float, 0, 0), then use unit_vector to get 1.0 in x
+    // Actually simpler: use div3 with a=x, b=0, c=0, d=1 and read scale[0]
+    scoreboard_set("$sqrt_x", "__rs_math_hp", x);
+    raw("execute store result storage rs:math_hp sq_x float 0.0001 run scoreboard players get $sqrt_x __rs_math_hp");
+    // Diagonal matrix [x,0,0, 0,1,0, 0,0,1, 0,0,0,1] → scale[0] = sqrt(x) via SVD? No...
+    // Actually: use distance trick via entity positioned at (√x, 0, 0) after tp ^√x
+    // Simpler approach: Newton iteration with div_hp for refinement
+    // g = isqrt(x), then refine: g = (g + div_hp(x, g)) / 2
+    let g: int = isqrt(x * 100) * 100;  // initial from integer sqrt, ×10000 scale
+    if (g <= 0) { g = 1; }
+    // Two Newton refinement steps using div_hp
+    let d: int = div_hp(x, g);
+    g = (g + d) / 2;
+    d = div_hp(x, g);
+    g = (g + d) / 2;
+    return g;
+}
+
+// norm3_hp(x, y, z): high-precision 3D vector norm √(x²+y²+z²)
+// All inputs ×10000. Returns magnitude ×10000.
+// Uses trig entity position trick.
+@require_on_load(init_trig)
+fn norm3_hp(x: int, y: int, z: int): int {
+    // Store x,y,z as float in storage
+    scoreboard_set("$norm_x", "__rs_math_hp", x);
+    scoreboard_set("$norm_y", "__rs_math_hp", y);
+    scoreboard_set("$norm_z", "__rs_math_hp", z);
+    raw("execute store result storage rs:math_hp nrm_x float 0.0001 run scoreboard players get $norm_x __rs_math_hp");
+    raw("execute store result storage rs:math_hp nrm_y float 0.0001 run scoreboard players get $norm_y __rs_math_hp");
+    raw("execute store result storage rs:math_hp nrm_z float 0.0001 run scoreboard players get $norm_z __rs_math_hp");
+    // TP marker to (x,y,z), then read distance from origin
+    raw("execute as @e[tag=rs_trig,limit=1] run tp @s 0.0 0.0 0.0");
+    raw("data modify entity @e[tag=rs_trig,limit=1] Pos set from storage rs:math_hp nrm_x");
+    // Actually distance from world origin: read distance using entity selector
+    // Simpler: use Pythagorean theorem via sqrt_hp
+    let x2: int = x / 100 * x / 100;  // x² / 10000
+    let y2: int = y / 100 * y / 100;
+    let z2: int = z / 100 * z / 100;
+    return sqrt_hp(x2 + y2 + z2);
+}
+
+// ─── Double-precision arithmetic helpers ──────────────────────────────────────
+//
+// double_mul_fixed(d, f): double × fixed-point, true double precision.
+// Computes d × (f / 10000) entirely in IEEE 754 double arithmetic.
+// d: double (NBT-backed IEEE 754)
+// f: int in ×10000 fixed-point representation (e.g. 15000 = 1.5)
+// Returns: double result = d × (f / 10000)
+//
+// Algorithm (function-macro trick):
+//   1. Compute scale = f × 0.0001 and store as a double in rs:math_hp __dmul_args.scale
+//   2. Call __dmul_apply_scale via 'with storage' macro so $(scale) is substituted
+//   3. Helper does: $execute store result storage rs:d __dp0 double $(scale) run data get storage rs:d __dp0 1
+//      = __dp0 ← __dp0 × scale   (pure double arithmetic, no integer intermediate)
+//   4. Return __dp0 (now contains d × (f/10000)) as fixed for the caller
+//
+// No integer overflow risk; no truncation of d before multiplication.
+//
+
+// Internal macro helper — DO NOT CALL DIRECTLY.
+// Called via: function __NS__:__dmul_apply_scale with storage rs:math_hp __dmul_args
+// Reads $(scale) from rs:math_hp __dmul_args.scale, multiplies __dp0 by it in-place.
+fn __dmul_apply_scale() {
+    raw("$execute store result storage rs:d __dp0 double $(scale) run data get storage rs:d __dp0 1");
+}
+
+fn double_mul_fixed(d: double, f: int): double {
+    // Step 1: store f into math_hp scoreboard, then compute scale = f × 0.0001
+    scoreboard_set("$dmul_f", "__rs_math_hp", f);
+    // Store scale as double into the macro-args compound (path must use dot notation)
+    raw("execute store result storage rs:math_hp __dmul_args.scale double 0.0001 run scoreboard players get $dmul_f __rs_math_hp");
+    // Step 2: d is already in __dp0 (first double param convention)
+    // Step 3: call macro helper — overwrites __dp0 with d × (f/10000) in IEEE 754 double
+    raw("function __NS__:__dmul_apply_scale with storage rs:math_hp __dmul_args");
+    // Step 4: __dp0 now holds d × (f/10000). Return it (read as ×10000 fixed for caller).
+    return d;
+}
+
+// ─── Double-precision addition: entity position trick ─────────────────────────
+//
+// double_add(a, b): a + b in full IEEE 754 double precision.
+//
+// Algorithm: Minecraft internally stores entity Pos as Java double[].
+// By TPing a marker to x=a then doing a relative TP of +b, the game computes
+// a+b in native Java double arithmetic (no int intermediate).
+//
+// Entity: area_effect_cloud, UUID b54f1a4f-d7ac-4002-915e-3c2a3bf6f8a4
+// Tag: rs_math_hp_marker
+// Summoned once at load via init_double_add().
+//
+// ⚠ Precision: full double (~15 sig figs). No overflow within double range.
+//
+
+// init_double_add(): summon the AEC marker entity for double_add/sub.
+// Called automatically via @require_on_load.
+@require_on_load(init_double_add)
+fn init_double_add() {
+    raw("execute unless entity b54f1a4f-d7ac-4002-915e-3c2a3bf6f8a4 run summon minecraft:area_effect_cloud ~ ~ ~ {UUID:[I;-1238834609,-698744574,-1879932794,1006600372],NoGravity:1b,Duration:2147483647,Tags:[\"rs_math_hp_marker\"]}");
+}
+
+// __dadd_tp_to: macro helper — teleport marker to absolute x=$(x).
+// DO NOT CALL DIRECTLY. Called via: function __NS__:__dadd_tp_to with storage rs:d __dadd_args
+fn __dadd_tp_to() {
+    raw("$tp b54f1a4f-d7ac-4002-915e-3c2a3bf6f8a4 $(x) 0.0 0.0");
+}
+
+// __dadd_tp_rel: macro helper — relative TP marker by +$(dx) on X axis.
+// DO NOT CALL DIRECTLY. Called via: function __NS__:__dadd_tp_rel with storage rs:d __dadd_args
+fn __dadd_tp_rel() {
+    raw("$execute at b54f1a4f-d7ac-4002-915e-3c2a3bf6f8a4 run tp b54f1a4f-d7ac-4002-915e-3c2a3bf6f8a4 ~$(dx) 0.0 0.0");
+}
+
+// double_add(a, b): a + b in true double precision.
+// a, b: double (NBT-backed). Returns: a + b as double in __dp0.
+@require_on_load(init_double_add)
+fn double_add(a: double, b: double): double {
+    // __dp0 = a, __dp1 = b (set by caller)
+    // Copy a into __dadd_args.x, b into __dadd_args.dx for macro substitution
+    raw("data modify storage rs:d __dadd_args.x set from storage rs:d __dp0");
+    raw("function __NS__:__dadd_tp_to with storage rs:d __dadd_args");
+    raw("data modify storage rs:d __dadd_args.dx set from storage rs:d __dp1");
+    raw("function __NS__:__dadd_tp_rel with storage rs:d __dadd_args");
+    // Read Pos[0] back into __dp0 — this is a+b in double precision
+    raw("data modify storage rs:d __dp0 set from entity b54f1a4f-d7ac-4002-915e-3c2a3bf6f8a4 Pos[0]");
+    // Reset marker to origin
+    raw("tp b54f1a4f-d7ac-4002-915e-3c2a3bf6f8a4 0.0 0.0 0.0");
+    return a;
+}
+
+// ─── double_sub: subtraction via negation + add ────────────────────────────────
+//
+// double_sub(a, b): a - b.
+//
+// Negates b by re-reading it through execute store with scale -1 (double ×(-1)).
+// ⚠ Precision note: the negation step uses:
+//     execute store result storage rs:d __dp1 double -0.0001 run data get storage rs:d __dp1 10000
+//   This round-trips through a Java long (int64), which truncates the value to
+//   ~15 decimal digits (same as double precision). Exact for |b| ≤ 2^53.
+//   Catastrophic cancellation warning applies when a ≈ b (same as all FP subtraction).
+//
+
+// double_sub(a, b): a - b in double precision.
+// a, b: double. Returns: a - b as double in __dp0.
+@require_on_load(init_double_add)
+fn double_sub(a: double, b: double): double {
+    // Negate __dp1 (b): read as ×10000 long, store back as double × -0.0001
+    raw("execute store result storage rs:d __dp1 double -0.0001 run data get storage rs:d __dp1 10000");
+    // Now compute a + (-b)
+    raw("data modify storage rs:d __dadd_args.x set from storage rs:d __dp0");
+    raw("function __NS__:__dadd_tp_to with storage rs:d __dadd_args");
+    raw("data modify storage rs:d __dadd_args.dx set from storage rs:d __dp1");
+    raw("function __NS__:__dadd_tp_rel with storage rs:d __dadd_args");
+    raw("data modify storage rs:d __dp0 set from entity b54f1a4f-d7ac-4002-915e-3c2a3bf6f8a4 Pos[0]");
+    raw("tp b54f1a4f-d7ac-4002-915e-3c2a3bf6f8a4 0.0 0.0 0.0");
+    return a;
+}
+
+// ─── double_mul: scoreboard 4-decimal approximation ───────────────────────────
+//
+// double_mul(a, b): a × b — scoreboard integer approximation.
+//
+// Algorithm:
+//   score_a = floor(a × 10000)  [stored as int32 via data get × 10000]
+//   score_b = floor(b × 10000)
+//   result_score = (score_a × score_b) / 10000   [integer division]
+//   result = result_score as double × 0.0001
+//
+// ⚠ Limitations:
+//   - Overflow: score_a and score_b are Java int (32-bit signed).
+//     |a| × 10000 must fit in int32: safe for |a|, |b| ≤ ~214748.
+//     Products score_a × score_b overflow int32 for |a|×|b| > ~21474.
+//     For larger values use double_mul_fixed on log/exp decomposition.
+//   - Precision: ~4 decimal digits (10000× scale). Not full double precision.
+//   - Negative values: correctly handled by signed scoreboard arithmetic.
+//
+// For true double-precision multiplication, use the ln/exp approach once
+// double-precision ln/exp are available.
+//
+
+fn double_mul(a: double, b: double): double {
+    // Convert a and b to ×10000 integer scores
+    raw("execute store result score $dmul_a __rs_math_hp run data get storage rs:d __dp0 10000");
+    raw("execute store result score $dmul_b __rs_math_hp run data get storage rs:d __dp1 10000");
+    // Multiply: result = score_a * score_b / 10000
+    raw("scoreboard players operation $dmul_a __rs_math_hp *= $dmul_b __rs_math_hp");
+    raw("scoreboard players set $dmul_div __rs_math_hp 10000");
+    raw("scoreboard players operation $dmul_a __rs_math_hp /= $dmul_div __rs_math_hp");
+    // Store result back as double × 0.0001
+    raw("execute store result storage rs:d __dp0 double 0.0001 run scoreboard players get $dmul_a __rs_math_hp");
+    return a;
+}
+
+// ─── double_div: display entity SVD trick ─────────────────────────────────────
+//
+// double_div(a, b): a / b in full IEEE 754 double precision.
+//
+// Algorithm: MC display entities decompose their transformation matrix via SVD.
+// Setting matrix element [0] = a and [15] = b in a 4×4 diagonal matrix causes
+// MC to compute scale[0] = a/b in native Java double arithmetic.
+//
+// Uses the rs_div entity (block_display, tag="rs_div") from init_div() above.
+// init_div() must be called — it is via @require_on_load(init_div).
+//
+// ⚠ Precision: full double (~15 sig figs). Division by zero produces Infinity/NaN
+//   (Java double semantics) which will corrupt NBT if read back.
+//
+
+// __ddiv_set_mat: macro helper — set div entity transformation matrix elements.
+// $(da) → a as float, $(db) → b as float (already in NBT as doubles).
+// DO NOT CALL DIRECTLY.
+fn __ddiv_set_mat() {
+    raw("$data modify entity @e[tag=rs_div,limit=1] transformation set value [$(da)f,0f,0f,0f,0f,1f,0f,0f,0f,0f,1f,0f,0f,0f,0f,$(db)f]");
+}
+
+// double_div(a, b): a / b in true double precision.
+// a, b: double. Returns: a / b as double in __dp0.
+// ⚠ b must not be zero (produces Java Infinity, corrupts NBT).
+@require_on_load(init_div)
+fn double_div(a: double, b: double): double {
+    // Store a and b as float in macro args compound for __ddiv_set_mat
+    // We piggyback on rs:math_hp storage for the args
+    raw("execute store result storage rs:math_hp __ddiv_args.da float 1 run data get storage rs:d __dp0 1");
+    raw("execute store result storage rs:math_hp __ddiv_args.db float 1 run data get storage rs:d __dp1 1");
+    raw("function __NS__:__ddiv_set_mat with storage rs:math_hp __ddiv_args");
+    // Read scale[0] = a/b back as double into __dp0
+    raw("data modify storage rs:d __dp0 set from entity @e[tag=rs_div,limit=1] transformation.scale[0]");
+    return a;
+}
+
+// ─── High-precision natural logarithm (Newton-refined) ───────────────────────
+//
+// ln_hp(x): high-precision natural log via Newton refinement of ln_5term.
+// Input/Output: ×10000 fixed-point (e.g. 10000 = 1.0, 27183 ≈ e)
+// Valid range: x ∈ [100, 1000000]
+//
+// Algorithm:
+//   1. y = ln_5term(x)                   — ~6-digit atanh series estimate
+//   2. e_y = exp_fx(y)                   — compute e^y in ×10000 fixed-point
+//   3. correction = (x - e_y) * 10000 / e_y   — Newton step: ln(x/e^y) ≈ x/e^y - 1
+//   4. return y + correction
+//
+// Precision: one Newton step squares the error, improving from ~6 digits to ~11 digits.
+// Since exp_fx itself has ~6-digit precision, the effective output is ~8–9 digits.
+//
+fn ln_hp(x: int): int {
+    // Step 1: initial estimate via 5-term atanh series
+    let y: int = ln_5term(x);
+
+    // Step 2: compute e^y — exp_fx takes ×10000 input, returns ×10000 output
+    let e_y: int = exp_fx(y);
+
+    // Step 3: Newton correction — (x/e^y - 1) in ×10000 fixed-point
+    // correction = (x - e_y) × 10000 / e_y
+    if (e_y <= 0) { return y; }
+    let correction: int = (x - e_y) * 10000 / e_y;
+
+    // Step 4: refined result
+    return y + correction;
+}
+
+// ─── Extended-precision natural logarithm (5-term atanh series) ───────────────
+//
+// ln_5term(x): natural log using 5-term atanh series (more precise than 3-term ln())
+// Input/Output: same as ln() — ×10000 fixed-point
+// Valid range: x ∈ [100, 1000000]
+//
+// max_error ≈ 0.000002 (2× better than 3-term ln())
+// Cost: ~5 more scoreboard operations than ln()
+//
+fn ln_5term(x: int): int {
+    let scale: int = 10000;
+    let ln2: int = 6931;
+
+    // Range reduction: bring x into [scale, 2*scale)
+    let xr: int = x;
+    let k: int = 0;
+    while (xr < scale) {
+        xr = xr * 2;
+        k = k - 1;
+    }
+    while (xr >= scale * 2) {
+        xr = xr / 2;
+        k = k + 1;
+    }
+
+    // s = (xr - scale) * scale / (xr + scale) ∈ [0, 3333]
+    let s: int = (xr - scale) * scale / (xr + scale);
+
+    // 5-term atanh series: ln(xr/scale) = 2*(A1*s + A3*s³ + A5*s⁵ + A7*s⁷ + A9*s⁹)
+    // Theoretical coefficients ×10000: A1=20000, A3=6667, A5=4000, A7=2857, A9=2222
+    let s2: int = s * s / scale;
+    let s3: int = s * s2 / scale;
+    let s5: int = s3 * s2 / scale;
+    let s7: int = s5 * s2 / scale;
+    let s9: int = s7 * s2 / scale;
+    let lnxr: int = 20000 * s / scale + 6667 * s3 / scale + 4000 * s5 / scale + 2857 * s7 / scale + 2222 * s9 / scale;
+
+    return k * ln2 + lnxr;
+}
+
+// ─── double_sqrt: square root of a double-precision value ─────────────────────
+//
+// double_sqrt(x): √x, returned as double.
+// Strategy: x_fixed = x * 10000 (via "as fixed"), then sqrt_fx gives
+//   sqrt_fx(x_fixed) = floor(√x_fixed) = floor(√(x*10000)) = floor(√x * 100)
+// So r = sqrt_fx(x_fixed) satisfies r ≈ √x * 100.
+// Scale r by 100 more to get √x in ×10000 units: r_scaled = r * 100.
+// Then convert to double with scale 0.0001.
+//
+fn double_sqrt(x: double): double {
+    // Convert double → ×10000 int
+    let x_fixed: int = x as int;
+    raw("execute store result score $dsqrt_xfx __rs_math_hp run data get storage rs:d __dp0 10000");
+    let xfx: int = scoreboard_get("$dsqrt_xfx", "__rs_math_hp");
+    // r = floor(√(x * 10000)) ≈ √x * 100
+    let r: int = isqrt(xfx);
+    // r_scaled = r * 100 → represents √x in ×10000 units
+    let r_scaled: int = r * 100;
+    scoreboard_set("$dsqrt_rsc", "__rs_math_hp", r_scaled);
+    // Convert ×10000 int back to double with scale 0.0001
+    raw("execute store result storage rs:d __dp0 double 0.0001 run scoreboard players get $dsqrt_rsc __rs_math_hp");
+    return x;
+}
+
+// ─── pow_real: real-valued power base^exp_val ─────────────────────────────────
+//
+// pow_real(base, exp_val): base^exp_val for double inputs, double result.
+// Uses: a^b = e^(b * ln(a)) via fixed-point helpers.
+// Steps:
+//   1. base_fixed = base (×10000 int) via scoreboard read
+//   2. ln_base = ln_hp(base_fixed)          — ×10000 fixed, ≈ ln(base)
+//   3. exp_fixed = exp_val (×10000 int)     — ≈ exp_val
+//   4. exponent = ln_base * exp_fixed / 10000  — ×10000, ≈ ln(base) * exp_val
+//   5. result_fixed = exp_fx(exponent)         — ×10000, ≈ e^(ln(base)*exp_val)
+//   6. Convert result_fixed to double via scoreboard
+//
+@require_on_load(init_trig)
+fn pow_real(base: double, exp_val: double): double {
+    // Read base ×10000 from __dp0 (first double param)
+    raw("execute store result score $preal_base __rs_math_hp run data get storage rs:d __dp0 10000");
+    let base_fixed: int = scoreboard_get("$preal_base", "__rs_math_hp");
+    // Read exp_val ×10000 from __dp1 (second double param)
+    raw("execute store result score $preal_exp __rs_math_hp run data get storage rs:d __dp1 10000");
+    let exp_fixed: int = scoreboard_get("$preal_exp", "__rs_math_hp");
+    // Compute ln(base) via high-precision log
+    let ln_base: int = ln_hp(base_fixed);
+    // exponent = ln(base) * exp_val, both ×10000 → divide by 10000 to stay in scale
+    let exponent: int = ln_base * exp_fixed / 10000;
+    // result = e^exponent in ×10000
+    let result_fixed: int = exp_fx(exponent);
+    scoreboard_set("$preal_res", "__rs_math_hp", result_fixed);
+    // Convert result to double
+    raw("execute store result storage rs:d __dp0 double 0.0001 run scoreboard players get $preal_res __rs_math_hp");
+    return base;
+}
+
+// ─── pow_fast: integer-exponent double power via recursive squaring ────────────
+//
+// pow_fast(base, exp_val): base^exp_val for double base, int exponent.
+// Uses binary exponentiation. Handles negative exponents via double_div.
+// Recursion supported in RedScript.
+//
+fn pow_fast(base: double, exp_val: int): double {
+    if (exp_val == 0) { return 1.0d; }
+    if (exp_val < 0) {
+        // 1.0 / base^(-exp_val)
+        let pos_result: double = pow_fast(base, 0 - exp_val);
+        return double_div(1.0d, pos_result);
+    }
+    if (exp_val % 2 == 0) {
+        let half: double = pow_fast(base, exp_val / 2);
+        return double_mul(half, half);
+    }
+    let rest: double = pow_fast(base, exp_val - 1);
+    return double_mul(base, rest);
+}

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