redscript-mc 2.4.1 → 2.6.0

package/docs/stdlib/math.md

@@ -0,0 +1,334 @@
+# `math` — Basic math operations
+
+Import: `import math;`
+
+Integer and fixed-point math helpers for RedScript datapacks. Fixed-point convention: scale = 1000 (1.0 → 1000, 3.14 → 3140) unless noted. Includes basic helpers (abs, sign, min, max, clamp, lerp), iterative algorithms (isqrt, sqrt_fixed, pow_int, gcd, lcm), trigonometry via a lookup table, fixed-point arithmetic helpers, easing (smoothstep/smootherstep), logarithms, exponential, cubic root, combinatorics, linear equation solvers, numerical integration steps, and arc trig approximations.
+
+## Functions
+
+### `abs<T>(x: T): T`
+
+Absolute value. Works for any numeric type.
+
+**Example:**
+```rs
+import math;
+let v: int = abs(-5);  // 5
+```
+
+---
+
+### `sign(x: int): int`
+
+Sign of `x`: returns 1, 0, or -1.
+
+---
+
+### `min<T>(a: T, b: T): T`
+
+Minimum of two values.
+
+---
+
+### `max<T>(a: T, b: T): T`
+
+Maximum of two values.
+
+---
+
+### `clamp<T>(x: T, lo: T, hi: T): T`
+
+Clamp `x` to the range `[lo, hi]`.
+
+---
+
+### `lerp(a: int, b: int, t: int): int`
+
+Linear interpolation. `t ∈ [0, 1000]`. `lerp(100, 200, 750)` → 175.
+
+**Example:**
+```rs
+import math;
+let v: int = lerp(0, 1000, 500);  // 500
+```
+
+---
+
+### `isqrt(n: int): int`
+
+> **Cost:** ≤16 Newton-Raphson iterations
+
+Integer square root: `⌊√n⌋`. Uses Newton's method. Converges in ≤16 iterations for all int32.
+
+**Example:**
+```rs
+import math;
+let r: int = isqrt(25);  // 5
+```
+
+---
+
+### `sqrt_fixed(x: int): int`
+
+Fixed-point sqrt (scale=1000). Returns `√x × 1000`. `sqrt_fixed(2000)` ≈ 1414.
+
+---
+
+### `pow_int(base: int, exp: int): int`
+
+> **Cost:** O(log exp)
+
+Integer power `base^exp` (exp ≥ 0). Fast exponentiation by squaring.
+
+---
+
+### `gcd(a: int, b: int): int`
+
+Greatest common divisor (Euclidean algorithm). `gcd(12, 8)` → 4.
+
+---
+
+### `lcm(a: int, b: int): int`
+
+Least common multiple. `lcm(4, 6)` → 12.
+
+---
+
+### `map(x: int, in_lo: int, in_hi: int, out_lo: int, out_hi: int): int`
+
+Range map: scale `x` from `[in_lo, in_hi]` onto `[out_lo, out_hi]` using integer arithmetic.
+
+**Example:**
+```rs
+import math;
+let v: int = map(5, 0, 10, 0, 100);  // 50
+```
+
+---
+
+### `ceil_div(a: int, b: int): int`
+
+Ceiling division: `⌈a / b⌉`. Requires b > 0.
+
+---
+
+### `log2_int(n: int): int`
+
+Integer log base 2: `⌊log₂(n)⌋`. Returns -1 for n ≤ 0.
+
+---
+
+### `sin_fixed(deg: int): int`
+
+> **Precision:** ≤1 unit error (≤0.1% relative) for all integer degree inputs  
+> **Cost:** ~4 MC commands + 1 NBT read  
+> **Requires:** `math:tables` NBT storage must be pre-loaded (auto-loaded via `@require_on_load(_math_init)`)
+
+`sin(deg°) × 1000`. Handles any integer degrees; normalises internally. `sin_fixed(30)` → 500.
+
+**Example:**
+```rs
+import math;
+let s: int = sin_fixed(90);  // 1000
+```
+
+---
+
+### `cos_fixed(deg: int): int`
+
+> **Precision:** ≤1 unit error  
+> **Cost:** ~4 MC commands + 1 NBT read  
+> **Requires:** `math:tables` NBT storage must be pre-loaded
+
+`cos(deg°) × 1000`. Implemented as `sin_fixed(deg + 90)`.
+
+---
+
+### `mulfix(a: int, b: int): int`
+
+Fixed-point multiply: `(a × b) / 1000`. Use when both operands are fixed-point (scale=1000) to avoid overflow.
+
+**Example:**
+```rs
+import math;
+let v: int = mulfix(500, 707);  // 353  (≈ 0.5 × 0.707)
+```
+
+---
+
+### `divfix(a: int, b: int): int`
+
+Fixed-point divide: `(a × 1000) / b`. Returns 0 if b=0.
+
+---
+
+### `smoothstep(lo: int, hi: int, x: int): int`
+
+> **Cost:** ~5 operations
+
+Smooth Hermite interpolation `3t² - 2t³`. Returns value in `[0, 1000]`. Eases in AND out.
+
+**Example:**
+```rs
+import math;
+let v: int = smoothstep(0, 100, 50);  // 500
+```
+
+---
+
+### `smootherstep(lo: int, hi: int, x: int): int`
+
+Perlin's order-5 smootherstep `6t⁵ - 15t⁴ + 10t³`. Zero first and second derivatives at endpoints.
+
+---
+
+### `ln(x: int): int`
+
+> **Precision:** max_error ≈ 0.000504 (tuned 2026-03-17, ~8–9 significant digits)  
+> **Cost:** ~27 commands (auto-tuned atanh polynomial)
+
+Natural logarithm. Input/output ×10000 scale. Valid range: x ∈ [100, 1000000] (0.01–100.0). Uses 3-term atanh series with range reduction.
+
+**Example:**
+```rs
+import math;
+let l: int = ln(27183);  // ~10000  (ln(e) ≈ 1.0)
+```
+
+---
+
+### `sqrt_fx(x: int): int`
+
+Fixed-point sqrt, scale ×10000. Input x ×10000 (e.g. 40000=4.0), returns `√(x/10000) × 10000`. `sqrt_fx(20000)` ≈ 14142.
+
+---
+
+### `exp_fx(x: int): int`
+
+`e^(x/10000) × 10000`. Uses range reduction + 6-term Horner-form Taylor series. `exp_fx(10000)` ≈ 27183. Valid range: x ∈ [-100000, 100000].
+
+---
+
+### `cbrt_fx(x: int): int`
+
+Integer cube root: `⌊∛x⌋`. Newton's method, 20 iterations.
+
+---
+
+### `cbrt_newton(x: int): int`
+
+Cube root with additional Newton refinement steps beyond `cbrt_fx`. Better convergence for large values.
+
+---
+
+### `factorial(n: int): int`
+
+`n!` for n ∈ [0, 12]. (13! exceeds int32.)
+
+---
+
+### `combinations(n: int, k: int): int`
+
+`C(n, k)` for n ≤ 20, k ≤ n. Uses multiplicative formula to avoid overflow.
+
+---
+
+### `log10_fx(x: int): int`
+
+Log base 10, fixed-point ×10000. Uses `ln(x) / ln(10)`.
+
+---
+
+### `log2_fx(x: int): int`
+
+Log base 2, fixed-point ×10000. Uses `ln(x) / ln(2)`.
+
+---
+
+### `loga_fx(base_fx: int, x: int): int`
+
+Log base `base_fx` of `x`, both ×10000.
+
+---
+
+### `gamma_int(n: int): int`
+
+Gamma function for positive integers: `Γ(n) = (n-1)!`.
+
+---
+
+### `solve2x2_x(a: int, b: int, e: int, c: int, d: int, f: int): int`
+
+Solve `ax + by = e, cx + dy = f` for x using Cramer's rule. Returns `x × 10000`. Returns 0 if determinant is 0.
+
+---
+
+### `solve2x2_y(a: int, b: int, e: int, c: int, d: int, f: int): int`
+
+Solve the same system for y. Returns `y × 10000`.
+
+---
+
+### `quadratic_disc(a: int, b: int, c: int): int`
+
+Discriminant `b² - 4ac`. Positive: two real roots; zero: one root; negative: no real roots.
+
+---
+
+### `quadratic_x1(a: int, b: int, c: int): int`
+
+Larger root of `ax² + bx + c = 0`, returned ×10000.
+
+---
+
+### `quadratic_x2(a: int, b: int, c: int): int`
+
+Smaller root ×10000.
+
+---
+
+### `approx_eq(a: int, b: int, eps: int): int`
+
+Returns 1 if `|a - b| ≤ eps`.
+
+---
+
+### `cubic_disc_fx(p_fx: int, q_fx: int): int`
+
+Discriminant of depressed cubic `t³ + p×t + q = 0`, ×10000 inputs.
+
+---
+
+### `cubic_newton(a_fx: int, b_fx: int, c_fx: int, d_fx: int, x0_fx: int): int`
+
+Newton iteration for general cubic `ax³ + bx² + cx + d = 0`. Up to 20 iterations. Returns approximate root ×10000.
+
+---
+
+### `trapezoid_step(fa: int, fb: int, h: int): int`
+
+One trapezoidal integration step: `(fa + fb) / 2 × h`. All ×10000.
+
+---
+
+### `simpson_step(fa: int, fm: int, fb: int, h: int): int`
+
+One Simpson's rule step over 2h width: `(fa + 4×fm + fb) × h/3`. All ×10000.
+
+---
+
+### `newton_step(x_fx: int, fx: int, dfx: int): int`
+
+One Newton-Raphson step: `x - f(x)/f'(x)`. Returns new x ×10000.
+
+---
+
+### `asin_approx(x_fx: int): int`
+
+Arcsin approximation for `x_fx ∈ [-10000, 10000]` (×10000). Returns degrees ×10000. Uses `arctan(x / √(1-x²))`.
+
+---
+
+### `acos_approx(x_fx: int): int`
+
+Arccos approximation. Returns degrees ×10000. Computed as `90° - asin(x)`.

package/docs/stdlib/math_hp.md

@@ -0,0 +1,185 @@
+# `math_hp` — High-precision math
+
+Import: `import math_hp;`
+
+High-precision arithmetic exploiting Minecraft's internal IEEE 754 double storage. Provides double-precision sin/cos via a Marker entity rotation trick, high-precision division via Display Entity SVD, double arithmetic (add, sub, mul, div), high-precision ln (Newton-refined), double sqrt, and real-valued power. Setup required: call `init_trig()` (and optionally `init_div()`, `init_double_add()`) from your `@load` function.
+
+> **Setup required:** Call `init_trig()` in your `@load` function. These functions are auto-registered via `@require_on_load` but the entity must exist at runtime.
+
+## Functions
+
+### `init_trig()`
+
+Create the `rs_trig` Marker entity used by `sin_hp`/`cos_hp`/`norm3_hp`. Safe to call multiple times (only spawns if not already present). Called automatically via `@require_on_load`.
+
+---
+
+### `sin_hp(angle: int): int`
+
+> **Precision:** ~15 significant figures (Java `Math.sin` double precision)  
+> **Cost:** ~8 commands + entity NBT read/write  
+> **Requires:** `rs_trig` Marker entity must exist (call `init_trig()` in `@load`)
+
+High-precision sine. `angle` in degrees ×10000 (e.g. 450000 = 45°). Returns `sin(angle/10000°) × 10000`.
+
+**Example:**
+```rs
+import math_hp;
+
+@load fn setup() { init_trig(); }
+
+fn my_fn() {
+    let s: int = sin_hp(900000);  // 10000  (sin 90° = 1.0)
+}
+```
+
+---
+
+### `cos_hp(angle: int): int`
+
+> **Precision:** ~15 significant figures  
+> **Cost:** ~8 commands + entity NBT read/write  
+> **Requires:** `rs_trig` Marker entity
+
+High-precision cosine. `angle` in degrees ×10000. Returns `cos(angle/10000°) × 10000`.
+
+---
+
+### `init_div()`
+
+Create the `rs_div` block_display entity used by `div_hp`, `div3_hp`, `double_div`. Called automatically via `@require_on_load`.
+
+---
+
+### `div_hp(a: int, b: int): int`
+
+> **Precision:** ~15 significant figures (Display Entity SVD, Java double)  
+> **Cost:** ~10 commands + entity transformation write/read  
+> **Requires:** `rs_div` block_display entity (call `init_div()` in `@load`)
+
+High-precision integer division `a/b`, returns `(a/b) × 10000`. Example: `div_hp(10000, 3000)` ≈ 33333.
+
+**Example:**
+```rs
+import math_hp;
+let result: int = div_hp(10000, 3000);  // ~33333
+```
+
+---
+
+### `div3_hp(a: int, b: int, c: int, d: int): int`
+
+> **Precision:** ~15 significant figures  
+> **Requires:** `rs_div` entity
+
+Divide three values by `d` simultaneously via a diagonal matrix decomposition. Returns `a/d × 10000`. Results for `b/d` and `c/d` are in scoreboards `$div3_y` and `$div3_z __rs_math_hp`.
+
+---
+
+### `sqrt_hp(x: int): int`
+
+> **Precision:** ~8 significant figures (two Newton refinement steps using `div_hp`)  
+> **Requires:** `rs_div` entity
+
+High-precision square root. Input `x ×10000`. Returns `√(x/10000) × 10000`.
+
+---
+
+### `norm3_hp(x: int, y: int, z: int): int`
+
+> **Requires:** `rs_trig` entity
+
+High-precision 3D vector magnitude `√(x²+y²+z²)`. All inputs ×10000, returns ×10000.
+
+---
+
+### `double_mul_fixed(d: double, f: int): double`
+
+> **Precision:** Full IEEE 754 double (no integer intermediate for the multiplication)  
+> **Cost:** ~5 commands + macro function call
+
+Multiply a double value `d` by a fixed-point integer `f` (×10000 scale). Computes `d × (f / 10000)` entirely in IEEE 754 double arithmetic using a function macro trick.
+
+---
+
+### `init_double_add()`
+
+Summon the AEC marker entity for `double_add`/`double_sub`. Called automatically via `@require_on_load`.
+
+---
+
+### `double_add(a: double, b: double): double`
+
+> **Precision:** Full IEEE 754 double (~15 significant figures)  
+> **Cost:** ~6 commands + entity teleport
+
+`a + b` in true double precision via entity position trick (Marker teleported to `x=a` then relative TP by `+b`).
+
+---
+
+### `double_sub(a: double, b: double): double`
+
+> **Precision:** Full IEEE 754 double. Note: catastrophic cancellation applies when a ≈ b  
+> **Cost:** ~7 commands
+
+`a - b` in double precision. Negates `b` via execute-store with scale -1 then calls `double_add`.
+
+---
+
+### `double_mul(a: double, b: double): double`
+
+> **Precision:** ~4 decimal digits (10000× scale integer intermediary; NOT full double precision)  
+> **Cost:** ~5 commands  
+> **Note:** Overflow for |a|×|b| > ~21474; safe for small values only
+
+`a × b` via scoreboard integer approximation. For larger values use ln/exp decomposition.
+
+---
+
+### `double_div(a: double, b: double): double`
+
+> **Precision:** Full IEEE 754 double  
+> **Cost:** ~6 commands + entity transformation  
+> **Requires:** `rs_div` entity  
+> **Warning:** Division by zero produces Java Infinity/NaN which corrupts NBT
+
+`a / b` in true double precision via Display Entity SVD trick.
+
+---
+
+### `ln_hp(x: int): int`
+
+> **Precision:** ~8–9 significant digits (one Newton step on top of `ln_5term`)  
+> **Cost:** ~35 commands (ln_5term + exp_fx + correction)
+
+High-precision natural log. Input/output ×10000. Valid range: x ∈ [100, 1000000]. Algorithm: initial estimate via 5-term atanh series, then one Newton refinement step.
+
+---
+
+### `ln_5term(x: int): int`
+
+> **Precision:** max_error ≈ 0.000002 (2× better than 3-term `ln()`)  
+> **Cost:** ~30 commands
+
+Natural log using 5-term atanh series with range reduction. Input/output ×10000. Valid range: x ∈ [100, 1000000].
+
+---
+
+### `double_sqrt(x: double): double`
+
+Square root of a double value. Strategy: converts to ×10000 integer, applies `isqrt`, scales back to double.
+
+---
+
+### `pow_real(base: double, exp_val: double): double`
+
+> **Requires:** `rs_trig` entity  
+> **Precision:** ~6–8 significant digits (limited by exp_fx precision)
+
+`base^exp_val` for double inputs using `e^(exp_val × ln(base))` via fixed-point helpers.
+
+---
+
+### `pow_fast(base: double, exp_val: int): double`
+
+`base^exp_val` for double base, integer exponent. Uses binary exponentiation. Handles negative exponents via `double_div`. Recursive.

package/docs/stdlib/matrix.md

@@ -0,0 +1,123 @@
+# `matrix` — Matrix math for Display Entities
+
+Import: `import matrix;`
+
+2D/3D transformation matrix helpers for MC Display Entities. Provides 2D rotation, scale, 3D Euler-angle rotation (Y-up), quaternion half-angle components, billboard rotation, and angle lerp. All values ×10000 unless noted; angles in degrees ×10000. Requires `math` for `sin_fixed`, `cos_fixed`, `abs`.
+
+## Functions
+
+### `rotate2d_x(x: int, y: int, angle_deg: int): int`
+
+X component after 2D rotation by `angle_deg ×10000`. Uses `cos_fixed`/`sin_fixed`.
+
+> **Requires:** `math:tables` NBT storage must be pre-loaded
+
+**Example:**
+```rs
+import matrix;
+let nx: int = rotate2d_x(1000, 0, 900000);  // 0  (rotated 90°)
+```
+
+---
+
+### `rotate2d_y(x: int, y: int, angle_deg: int): int`
+
+Y component after 2D rotation. Returns `x×sin + y×cos`.
+
+> **Requires:** `math:tables` NBT storage must be pre-loaded
+
+---
+
+### `scale_x(x: int, sx_fx: int): int`
+
+Scale x by `sx_fx ×10000` (e.g. 20000 = 2×).
+
+---
+
+### `scale_y(y: int, sy_fx: int): int`
+
+Scale y component.
+
+---
+
+### `scale_z(z: int, sz_fx: int): int`
+
+Scale z component.
+
+---
+
+### `uniform_scale(v: int, s_fx: int): int`
+
+Apply uniform scale to a component value.
+
+---
+
+### `rotate_y_x(x: int, z: int, angle_deg: int): int`
+
+X component after rotation around Y axis (Euler, Y-up). `angle_deg ×10000`.
+
+> **Requires:** `math:tables` NBT storage must be pre-loaded
+
+---
+
+### `rotate_y_z(x: int, z: int, angle_deg: int): int`
+
+Z component after rotation around Y axis.
+
+> **Requires:** `math:tables` NBT storage must be pre-loaded
+
+---
+
+### `rotate_x_y(y: int, z: int, angle_deg: int): int`
+
+Y component after rotation around X axis.
+
+> **Requires:** `math:tables` NBT storage must be pre-loaded
+
+---
+
+### `rotate_x_z(y: int, z: int, angle_deg: int): int`
+
+Z component after rotation around X axis.
+
+> **Requires:** `math:tables` NBT storage must be pre-loaded
+
+---
+
+### `quat_sin_half(angle_deg_fx: int): int`
+
+`sin(angle/2) ×1000` for quaternion construction. `angle_deg_fx` is degrees ×10000.
+
+> **Requires:** `math:tables` NBT storage must be pre-loaded
+
+---
+
+### `quat_cos_half(angle_deg_fx: int): int`
+
+`cos(angle/2) ×1000` for quaternion construction.
+
+> **Requires:** `math:tables` NBT storage must be pre-loaded
+
+---
+
+### `billboard_y(player_yaw_fx: int): int`
+
+Y rotation for a billboard facing the player. Input: player yaw ×10000. Returns the opposite direction mod 360°.
+
+**Example:**
+```rs
+import matrix;
+let rot: int = billboard_y(900000);  // 2700000 (facing opposite)
+```
+
+---
+
+### `lerp_angle(a_fx: int, b_fx: int, t: int): int`
+
+Lerp between two angles ×10000, taking the shortest angular path (normalises difference to [-1800000, 1800000]). `t ∈ [0, 10000]`.
+
+**Example:**
+```rs
+import matrix;
+let a: int = lerp_angle(0, 1800000, 5000);  // 900000
+```