redscript-mc 2.6.2 → 3.0.0

package/src/stdlib/list.mcrs

@@ -21,9 +21,26 @@ module library;
 
 // ─── Static min/max/avg ──────────────────────────────────────────────────────
 
+/// Return the smaller of two integers.
+/// @since 1.0.0
+/// @param a First value
+/// @param b Second value
+/// @returns a if a ≤ b, otherwise b
 fn sort2_min(a: int, b: int): int { if (a <= b) { return a; } return b; }
+
+/// Return the larger of two integers.
+/// @since 1.0.0
+/// @param a First value
+/// @param b Second value
+/// @returns a if a ≥ b, otherwise b
 fn sort2_max(a: int, b: int): int { if (a >= b) { return a; } return b; }
 
+/// Minimum of three integers.
+/// @since 1.0.0
+/// @param a First value
+/// @param b Second value
+/// @param c Third value
+/// @returns The smallest of a, b, c
 fn list_min3(a: int, b: int, c: int): int {
     let m: int = a;
     if (b < m) { m = b; }
@@ -31,6 +48,12 @@ fn list_min3(a: int, b: int, c: int): int {
     return m;
 }
 
+/// Maximum of three integers.
+/// @since 1.0.0
+/// @param a First value
+/// @param b Second value
+/// @param c Third value
+/// @returns The largest of a, b, c
 fn list_max3(a: int, b: int, c: int): int {
     let m: int = a;
     if (b > m) { m = b; }
@@ -38,6 +61,14 @@ fn list_max3(a: int, b: int, c: int): int {
     return m;
 }
 
+/// Minimum of five integers.
+/// @since 1.0.0
+/// @param a Value 1
+/// @param b Value 2
+/// @param c Value 3
+/// @param d Value 4
+/// @param e Value 5
+/// @returns The smallest of the five inputs
 fn list_min5(a: int, b: int, c: int, d: int, e: int): int {
     let m: int = a;
     if (b < m) { m = b; }
@@ -47,6 +78,14 @@ fn list_min5(a: int, b: int, c: int, d: int, e: int): int {
     return m;
 }
 
+/// Maximum of five integers.
+/// @since 1.0.0
+/// @param a Value 1
+/// @param b Value 2
+/// @param c Value 3
+/// @param d Value 4
+/// @param e Value 5
+/// @returns The largest of the five inputs
 fn list_max5(a: int, b: int, c: int, d: int, e: int): int {
     let m: int = a;
     if (b > m) { m = b; }
@@ -56,15 +95,60 @@ fn list_max5(a: int, b: int, c: int, d: int, e: int): int {
     return m;
 }
 
+/// Sum of five integers.
+/// @since 1.0.0
+/// @param a Value 1
+/// @param b Value 2
+/// @param c Value 3
+/// @param d Value 4
+/// @param e Value 5
+/// @returns a + b + c + d + e
 fn list_sum5(a: int, b: int, c: int, d: int, e: int): int { return a + b + c + d + e; }
+
+/// Sum of four integers.
+/// @since 1.0.0
+/// @param a Value 1
+/// @param b Value 2
+/// @param c Value 3
+/// @param d Value 4
+/// @returns a + b + c + d
 fn list_sum4(a: int, b: int, c: int, d: int): int { return a + b + c + d; }
+
+/// Sum of three integers.
+/// @since 1.0.0
+/// @param a Value 1
+/// @param b Value 2
+/// @param c Value 3
+/// @returns a + b + c
 fn list_sum3(a: int, b: int, c: int): int { return a + b + c; }
+
+/// Integer average of three values (truncates toward zero).
+/// @since 1.0.0
+/// @param a Value 1
+/// @param b Value 2
+/// @param c Value 3
+/// @returns (a + b + c) / 3
 fn avg3(a: int, b: int, c: int): int { return (a + b + c) / 3; }
+
+/// Integer average of five values (truncates toward zero).
+/// @since 1.0.0
+/// @param a Value 1
+/// @param b Value 2
+/// @param c Value 3
+/// @param d Value 4
+/// @param e Value 5
+/// @returns (a + b + c + d + e) / 5
 fn avg5(a: int, b: int, c: int, d: int, e: int): int { return (a + b + c + d + e) / 5; }
 
 // ─── Static sort (sorting network) ───────────────────────────────────────────
 
-// sort3(a, b, c, pos): return sorted value at position pos (0=min, 1=mid, 2=max)
+/// Sort three values and return the one at position `pos` (0 = min, 1 = mid, 2 = max).
+/// @since 1.0.0
+/// @param a Value 1
+/// @param b Value 2
+/// @param c Value 3
+/// @param pos Desired position in sorted order (0, 1, or 2)
+/// @returns The value at the requested sorted position
 fn sort3(a: int, b: int, c: int, pos: int): int {
     let x: int = a; let y: int = b; let z: int = c;
     if (x > y) { let t: int = x; x = y; y = t; }
@@ -77,6 +161,12 @@ fn sort3(a: int, b: int, c: int, pos: int): int {
 
 // ─── Weighted random choice ───────────────────────────────────────────────────
 
+/// Weighted random choice between two options (0 or 1) using an LCG seed.
+/// @since 1.0.0
+/// @param seed LCG seed (any integer)
+/// @param w0 Weight for option 0 (must be > 0)
+/// @param w1 Weight for option 1 (must be > 0)
+/// @returns 0 with probability w0/(w0+w1), 1 otherwise
 fn weighted2(seed: int, w0: int, w1: int): int {
     let total: int = w0 + w1;
     let r: int = seed * 1664525 + 1013904223;
@@ -85,6 +175,13 @@ fn weighted2(seed: int, w0: int, w1: int): int {
     return 1;
 }
 
+/// Weighted random choice among three options (0, 1, or 2) using an LCG seed.
+/// @since 1.0.0
+/// @param seed LCG seed (any integer)
+/// @param w0 Weight for option 0
+/// @param w1 Weight for option 1
+/// @param w2 Weight for option 2
+/// @returns 0, 1, or 2 proportional to the respective weights
 fn weighted3(seed: int, w0: int, w1: int, w2: int): int {
     let total: int = w0 + w1 + w2;
     let r: int = seed * 1664525 + 1013904223;
@@ -97,8 +194,14 @@ fn weighted3(seed: int, w0: int, w1: int, w2: int): int {
 
 // ─── 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
+/// Sort four values using an optimal 5-comparison sorting network, returning the value at `pos`.
+/// @since 1.0.0
+/// @param a Value 1
+/// @param b Value 2
+/// @param c Value 3
+/// @param d Value 4
+/// @param pos Desired position in sorted order (0 = min, 3 = max)
+/// @returns The value at the requested sorted position
 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
@@ -113,8 +216,15 @@ fn sort4(a: int, b: int, c: int, d: int, pos: int): int {
     return z;
 }
 
-// sort5(a,b,c,d,e, pos): sort 5 values, return value at position pos
-// Uses 9-comparison sorting network
+/// Sort five values using a 9-comparison Batcher odd-even merge sort network, returning the value at `pos`.
+/// @since 1.0.0
+/// @param a Value 1
+/// @param b Value 2
+/// @param c Value 3
+/// @param d Value 4
+/// @param e Value 5
+/// @param pos Desired position in sorted order (0 = min, 4 = max)
+/// @returns The value at the requested sorted position
 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)
@@ -136,8 +246,11 @@ fn sort5(a: int, b: int, c: int, d: int, e: int, pos: int): int {
 
 // ─── 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)
+/// In-place ascending bubble sort for an array of any length.
+/// Requires RedScript ≥ 2.4.0 (array parameter passed by reference).
+/// @since 1.0.0
+/// @param arr Array to sort (modified in-place)
+/// @param len Number of elements to sort
 fn list_sort_asc(arr: int[], len: int) {
     let i: int = 0;
     while (i < len - 1) {
@@ -154,7 +267,11 @@ fn list_sort_asc(arr: int[], len: int) {
     }
 }
 
-// list_sort_desc(arr, len): in-place descending bubble sort
+/// In-place descending bubble sort for an array of any length.
+/// Requires RedScript ≥ 2.4.0 (array parameter passed by reference).
+/// @since 1.0.0
+/// @param arr Array to sort (modified in-place)
+/// @param len Number of elements to sort
 fn list_sort_desc(arr: int[], len: int) {
     let i: int = 0;
     while (i < len - 1) {
@@ -173,7 +290,11 @@ fn list_sort_desc(arr: int[], len: int) {
 
 // ─── Dynamic array aggregates ─────────────────────────────────────────────────
 
-// list_sum(arr, len): sum of all elements
+/// Sum all elements of an array.
+/// @since 1.0.0
+/// @param arr Input array
+/// @param len Number of elements
+/// @returns Sum of arr[0..len)
 fn list_sum(arr: int[], len: int): int {
     let s: int = 0;
     let i: int = 0;
@@ -184,15 +305,22 @@ fn list_sum(arr: int[], len: int): int {
     return s;
 }
 
-// list_avg(arr, len): arithmetic mean ×10000 (fixed-point)
-// Returns (sum * 10000) / len; returns 0 for empty array
+/// Arithmetic mean of an array as fixed-point × 10000.
+/// @since 1.0.0
+/// @param arr Input array
+/// @param len Number of elements (must be > 0)
+/// @returns (sum × 10000) / len; returns 0 for empty array
 fn list_avg(arr: int[], len: int): int {
     if (len <= 0) { return 0; }
     let s: int = list_sum(arr, len);
     return s * 10000 / len;
 }
 
-// list_min(arr, len): minimum element in array
+/// Minimum element in an array.
+/// @since 1.0.0
+/// @param arr Input array (must have at least one element)
+/// @param len Number of elements
+/// @returns Smallest value in arr[0..len)
 fn list_min(arr: int[], len: int): int {
     let m: int = arr[0];
     let i: int = 1;
@@ -203,7 +331,11 @@ fn list_min(arr: int[], len: int): int {
     return m;
 }
 
-// list_max(arr, len): maximum element in array
+/// Maximum element in an array.
+/// @since 1.0.0
+/// @param arr Input array (must have at least one element)
+/// @param len Number of elements
+/// @returns Largest value in arr[0..len)
 fn list_max(arr: int[], len: int): int {
     let m: int = arr[0];
     let i: int = 1;
@@ -214,7 +346,12 @@ fn list_max(arr: int[], len: int): int {
     return m;
 }
 
-// list_contains(arr, len, val): 1 if val is in arr, 0 otherwise
+/// Test whether a value exists in an array.
+/// @since 1.0.0
+/// @param arr Input array
+/// @param len Number of elements
+/// @param val Value to search for
+/// @returns 1 if val is found, 0 otherwise
 fn list_contains(arr: int[], len: int, val: int): int {
     let i: int = 0;
     while (i < len) {
@@ -224,7 +361,12 @@ fn list_contains(arr: int[], len: int, val: int): int {
     return 0;
 }
 
-// list_index_of(arr, len, val): first index of val in arr, or -1 if not found
+/// Find the first index of a value in an array.
+/// @since 1.0.0
+/// @param arr Input array
+/// @param len Number of elements
+/// @param val Value to search for
+/// @returns First index of val, or -1 if not found
 fn list_index_of(arr: int[], len: int, val: int): int {
     let i: int = 0;
     while (i < len) {
@@ -234,8 +376,12 @@ fn list_index_of(arr: int[], len: int, val: int): int {
     return -1;
 }
 
-// list_shuffle(arr, len, seed): Fisher-Yates shuffle in-place using next_lcg RNG
-// For each i from len-1 down to 1: pick j in [0, i] using next_lcg, swap arr[i] and arr[j]
+/// Fisher-Yates in-place shuffle using a linear congruential generator.
+/// @since 1.0.0
+/// @param arr Array to shuffle (modified in-place)
+/// @param len Number of elements
+/// @param seed Initial LCG seed (any integer)
+/// @returns The shuffled array (same reference as arr)
 fn list_shuffle(arr: int[], len: int, seed: int): int[] {
     let i: int = len - 1;
     let s: int = seed;
@@ -252,7 +398,11 @@ fn list_shuffle(arr: int[], len: int, seed: int): int[] {
     return arr;
 }
 
-// list_dedup_count(arr, len): count of unique values (O(n²) — fine for small arrays)
+/// Count the number of unique values in an array (O(n²); suitable for small arrays).
+/// @since 1.0.0
+/// @param arr Input array
+/// @param len Number of elements
+/// @returns Count of distinct values in arr[0..len)
 fn list_dedup_count(arr: int[], len: int): int {
     let count: int = 0;
     let i: int = 0;

package/src/stdlib/map.mcrs

@@ -0,0 +1,112 @@
+// map.mcrs — NBT compound-backed map helpers for RedScript datapacks.
+//
+// Maps are stored in `storage rs:maps` using a compound per map:
+//
+//   rs:maps { Stats: { kills: 12, deaths: 3 } }
+//
+// `map_name` selects the top-level compound field. `key` selects the child
+// field within that compound. Both values are interpolated directly into the
+// NBT path, so callers should use path-safe identifiers (for example
+// `Stats`, `kills`, `player_01`) rather than arbitrary user text.
+
+module library;
+
+fn __map_set_apply() {
+    raw("$execute store result storage rs:maps $(map_name).$(key) int 1 run data get storage rs:macro_args value");
+}
+
+fn __map_get_apply() {
+    raw("$execute store result score $ret __OBJ__ run data get storage rs:maps $(map_name).$(key)");
+}
+
+fn __map_has_apply() {
+    raw("$execute store success score $ret __OBJ__ if data storage rs:maps $(map_name).$(key)");
+}
+
+fn __map_delete_apply() {
+    raw("$data remove storage rs:maps $(map_name).$(key)");
+}
+
+fn __map_clear_apply() {
+    raw("$data remove storage rs:maps $(map_name)");
+}
+
+/// Stores an integer value in `storage rs:maps.{map_name}.{key}`.
+///
+/// This creates the parent compound on demand if it does not already exist.
+/// Both `map_name` and `key` are inserted directly into the NBT path, so they
+/// must be valid path segments.
+///
+/// @since 3.0.0
+/// @param map_name  Top-level map name under `storage rs:maps`
+/// @param key       Key name inside the selected map compound
+/// @param value     Integer value to write
+/// @example
+/// map_set("Stats", "kills", 7)
+fn map_set(map_name: string, key: string, value: int) {
+    raw("data modify storage rs:macro_args map_name set from storage rs:strings __sp0");
+    raw("data modify storage rs:macro_args key set from storage rs:strings __sp1");
+    raw("execute store result storage rs:macro_args value int 1 run scoreboard players get $p0 __OBJ__");
+    raw("function __NS__:__map_set_apply with storage rs:macro_args");
+}
+
+/// Reads an integer value from `storage rs:maps.{map_name}.{key}`.
+///
+/// If the path does not exist, this function returns `0`.
+///
+/// @since 3.0.0
+/// @param map_name  Top-level map name under `storage rs:maps`
+/// @param key       Key name inside the selected map compound
+/// @returns         Stored integer value, or `0` if the key is missing
+/// @example
+/// let kills: int = map_get("Stats", "kills")
+fn map_get(map_name: string, key: string): int {
+    raw("scoreboard players set $ret __OBJ__ 0");
+    raw("data modify storage rs:macro_args map_name set from storage rs:strings __sp0");
+    raw("data modify storage rs:macro_args key set from storage rs:strings __sp1");
+    raw("function __NS__:__map_get_apply with storage rs:macro_args");
+    raw("return 1");
+    return 0;
+}
+
+/// Checks whether `storage rs:maps.{map_name}.{key}` exists.
+///
+/// @since 3.0.0
+/// @param map_name  Top-level map name under `storage rs:maps`
+/// @param key       Key name inside the selected map compound
+/// @returns         `1` if the key exists, otherwise `0`
+/// @example
+/// if (map_has("Stats", "kills") == 1) { }
+fn map_has(map_name: string, key: string): int {
+    raw("data modify storage rs:macro_args map_name set from storage rs:strings __sp0");
+    raw("data modify storage rs:macro_args key set from storage rs:strings __sp1");
+    raw("function __NS__:__map_has_apply with storage rs:macro_args");
+    raw("return 1");
+    return 0;
+}
+
+/// Removes a key from the selected map compound.
+///
+/// Removing a missing key is a no-op in Minecraft.
+///
+/// @since 3.0.0
+/// @param map_name  Top-level map name under `storage rs:maps`
+/// @param key       Key name inside the selected map compound
+/// @example
+/// map_delete("Stats", "kills")
+fn map_delete(map_name: string, key: string) {
+    raw("data modify storage rs:macro_args map_name set from storage rs:strings __sp0");
+    raw("data modify storage rs:macro_args key set from storage rs:strings __sp1");
+    raw("function __NS__:__map_delete_apply with storage rs:macro_args");
+}
+
+/// Removes the entire map compound from `storage rs:maps`.
+///
+/// @since 3.0.0
+/// @param map_name  Top-level map name under `storage rs:maps`
+/// @example
+/// map_clear("Stats")
+fn map_clear(map_name: string) {
+    raw("data modify storage rs:macro_args map_name set from storage rs:strings __sp0");
+    raw("function __NS__:__map_clear_apply with storage rs:macro_args");
+}

package/src/stdlib/math.mcrs

@@ -17,6 +17,13 @@ module library;
 
 // ─── Phase 1: Basic integer helpers ──────────────────────────────────────────
 
+/// Return the absolute value of x.
+/// @since 1.0.0
+/// @param x  The input value (any numeric type T)
+/// @returns  x if x >= 0, else -x
+/// @example
+/// let a = abs(-5)   // result: 5
+/// let b = abs(3)    // result: 3
 fn abs<T>(x: T) -> T {
     if (x < 0) {
         return 0 - x;
@@ -24,6 +31,12 @@ fn abs<T>(x: T) -> T {
     return x;
 }
 
+/// Return the sign of x: 1, 0, or -1.
+/// @since 1.0.0
+/// @param x  Input integer
+/// @returns  1 if x > 0, -1 if x < 0, 0 if x == 0
+/// @example
+/// let s = sign(-42)  // result: -1
 fn sign(x: int) -> int {
     if (x > 0) {
         return 1;
@@ -34,6 +47,13 @@ fn sign(x: int) -> int {
     return 0;
 }
 
+/// Return the smaller of two values.
+/// @since 1.0.0
+/// @param a  First value
+/// @param b  Second value
+/// @returns  a if a < b, else b
+/// @example
+/// let m = min(3, 7)  // result: 3
 fn min<T>(a: T, b: T) -> T {
     if (a < b) {
         return a;
@@ -41,6 +61,13 @@ fn min<T>(a: T, b: T) -> T {
     return b;
 }
 
+/// Return the larger of two values.
+/// @since 1.0.0
+/// @param a  First value
+/// @param b  Second value
+/// @returns  a if a > b, else b
+/// @example
+/// let m = max(3, 7)  // result: 7
 fn max<T>(a: T, b: T) -> T {
     if (a > b) {
         return a;
@@ -48,6 +75,15 @@ fn max<T>(a: T, b: T) -> T {
     return b;
 }
 
+/// Clamp x to the range [lo, hi].
+/// @since 1.0.0
+/// @param x   Input value
+/// @param lo  Lower bound (inclusive)
+/// @param hi  Upper bound (inclusive)
+/// @returns   lo if x < lo; hi if x > hi; otherwise x
+/// @example
+/// let c = clamp(150, 0, 100)  // result: 100
+/// let d = clamp(50, 0, 100)   // result: 50
 fn clamp<T>(x: T, lo: T, hi: T) -> T {
     if (x < lo) {
         return lo;
@@ -58,9 +94,15 @@ fn clamp<T>(x: T, lo: T, hi: T) -> T {
     return x;
 }
 
-// Linear interpolation (fixed-point t, t in [0, 1000])
-// lerp(0, 1000, 500) == 500
-// lerp(100, 200, 750) == 175
+/// Linear interpolation between a and b using fixed-point t in [0, 1000].
+/// @since 1.0.0
+/// @param a  Start value
+/// @param b  End value
+/// @param t  Interpolation factor ×1000 (0 = a, 1000 = b)
+/// @returns  a + (b - a) * t / 1000
+/// @example
+/// let v = lerp(0, 1000, 500)    // result: 500
+/// let w = lerp(100, 200, 750)   // result: 175
 fn lerp(a: int, b: int, t: int) -> int {
     return a + (b - a) * t / 1000;
 }
@@ -100,9 +142,13 @@ fn isqrt(n: int) -> int {
     return x;
 }
 
-// Fixed-point sqrt (scale = 1000)
-// sqrt_fixed(2000) ≈ 1414  (√2 × 1000)
-// sqrt_fixed(1000) == 1000 (√1 × 1000)
+/// Fixed-point square root (scale = 1000).
+/// @since 1.0.0
+/// @param x  Input value ×1000 (i.e. 2.0 → 2000)
+/// @returns  sqrt(x/1000) × 1000
+/// @example
+/// let s = sqrt_fixed(2000)  // result: ~1414  (√2 × 1000)
+/// let t = sqrt_fixed(1000)  // result: 1000   (√1 × 1000)
 fn sqrt_fixed(x: int) -> int {
     return isqrt(x * 1000);
 }
@@ -162,14 +208,14 @@ fn _math_init() {
     );
 }
 
-// sin_fixed(deg) → sin(deg°) × 1000   (integer degrees, any value)
-// sin_fixed(30)  == 500
-// sin_fixed(90)  == 1000
-// sin_fixed(180) == 0
-// sin_fixed(270) == -1000
-//
-// @require_on_load(_math_init): the sin lookup table is written to NBT storage at
-// world load automatically when this function is included in a project.
+/// Sine of an angle in integer degrees, returned as ×1000 fixed-point.
+/// Uses a 91-entry lookup table stored in NBT (math:tables.sin).
+/// @since 2.0.0
+/// @param deg  Angle in degrees (any integer; normalised mod 360)
+/// @returns    sin(deg°) × 1000  (range: -1000 to 1000)
+/// @example
+/// let s = sin_fixed(30)   // result: 500
+/// let t = sin_fixed(270)  // result: -1000
 @require_on_load(_math_init)
 fn sin_fixed(deg: int) -> int {
     // Normalise to [0, 359]
@@ -192,10 +238,14 @@ fn sin_fixed(deg: int) -> int {
     return 0 - storage_get_int("math:tables", "sin", idx);
 }
 
-// cos_fixed(deg) → cos(deg°) × 1000   (integer degrees, any value)
-// cos_fixed(0)   == 1000
-// cos_fixed(90)  == 0
-// cos_fixed(180) == -1000
+/// Cosine of an angle in integer degrees, returned as ×1000 fixed-point.
+/// Implemented as sin_fixed(deg + 90).
+/// @since 2.0.0
+/// @param deg  Angle in degrees (any integer; normalised mod 360)
+/// @returns    cos(deg°) × 1000  (range: -1000 to 1000)
+/// @example
+/// let c = cos_fixed(0)    // result: 1000
+/// let d = cos_fixed(180)  // result: -1000
 @require_on_load(_math_init)
 fn cos_fixed(deg: int) -> int {
     return sin_fixed(deg + 90);