redscript-mc 2.6.2 → 3.0.0

package/src/stdlib/sort.mcrs

@@ -19,8 +19,15 @@ module library
 
 // ─── Insertion sort (ascending) ───────────────────────────────────────────────
 
-// insertion_sort(arr, len): sort arr[0..len-1] ascending in-place
-// Time: O(n²); excellent for small n (≤64) and nearly-sorted data
+/// Sort an integer array ascending in-place using insertion sort.
+/// @since 1.0.0
+/// @param arr  Integer array to sort (mutated in-place)
+/// @param len  Number of elements to sort (arr[0..len-1])
+/// @returns  void — arr is sorted ascending after this call
+/// @example
+/// let data: int[] = [30, 10, 50, 20]
+/// insertion_sort(data, 4)
+/// // data is now [10, 20, 30, 50]
 fn insertion_sort(arr: int[], len: int) {
     let i: int = 1
     while (i < len) {
@@ -46,7 +53,15 @@ fn insertion_sort(arr: int[], len: int) {
 
 // ─── Insertion sort (descending) ──────────────────────────────────────────────
 
-// insertion_sort_desc(arr, len): sort arr[0..len-1] descending in-place
+/// Sort an integer array descending in-place using insertion sort.
+/// @since 1.0.0
+/// @param arr  Integer array to sort (mutated in-place)
+/// @param len  Number of elements to sort (arr[0..len-1])
+/// @returns  void — arr is sorted descending after this call
+/// @example
+/// let scores: int[] = [30, 10, 50, 20]
+/// insertion_sort_desc(scores, 4)
+/// // scores is now [50, 30, 20, 10]
 fn insertion_sort_desc(arr: int[], len: int) {
     let i: int = 1
     while (i < len) {
@@ -72,9 +87,16 @@ fn insertion_sort_desc(arr: int[], len: int) {
 
 // ─── Merge two sorted arrays ──────────────────────────────────────────────────
 
-// sort_merge(a, la, b, lb): merge sorted a[0..la-1] and b[0..lb-1]
-// Returns a new sorted int[] of length la+lb
-// Useful as the merge step of merge sort when caller handles recursion manually
+/// Merge two sorted integer arrays into a new sorted array.
+/// @since 1.0.0
+/// @param a   First sorted array
+/// @param la  Number of elements in a (a[0..la-1])
+/// @param b   Second sorted array
+/// @param lb  Number of elements in b (b[0..lb-1])
+/// @returns  New sorted int[] of length la+lb containing all elements of a and b
+/// @example
+/// let merged: int[] = sort_merge([1, 3, 5], 3, [2, 4, 6], 3)
+/// // result: [1, 2, 3, 4, 5, 6]
 fn sort_merge(a: int[], la: int, b: int[], lb: int): int[] {
     let result: int[] = []
     let i: int = 0
@@ -111,22 +133,15 @@ fn sort_merge(a: int[], la: int, b: int[], lb: int): int[] {
 
 // ─── Coroutine merge sort (bottom-up, iterative) ──────────────────────────────
 
-// merge_sort_coro(arr, n): sort arr[0..n-1] ascending in-place using bottom-up
-// merge sort, spread across server ticks via @coroutine.
-//
-// Each coroutine tick completes one full merge pass (doubling the sorted width).
-// After log₂(n) ticks, arr is fully sorted.
-//
-// @coroutine(onDone=merge_sort_noop) — replace onDone with your handler if you
-// need a callback once sorting is complete.
-//
-// Complexity: O(n log n) time, O(n) scratch space (temp[] for each merge pass).
-//
-// Usage:
-//   let data: int[] = [30, 10, 50, 20, 40]
-//   merge_sort_coro(data, 5)
-//   // several ticks later, data is [10, 20, 30, 40, 50]
-
+/// Sort an array ascending using bottom-up merge sort, spread across server ticks.
+/// @since 1.0.0
+/// @param arr  Integer array to sort (mutated in-place)
+/// @param n    Number of elements in arr
+/// @returns  void — arr is sorted after ceil(log₂(n)) ticks; onDone fires when complete
+/// @example
+/// let data: int[] = [30, 10, 50, 20, 40]
+/// merge_sort_coro(data, 5)
+/// // several ticks later, data is [10, 20, 30, 40, 50]
 // @coroutine(batch=1) spreads the outer width-doubling loop: 1 pass per tick.
 // Each tick completes all merges for the current width, then doubles width.
 // After ceil(log₂(n)) ticks, onDone fires and arr is fully sorted.
@@ -148,6 +163,7 @@ fn merge_sort_coro(arr: int[], n: int) {
             // via a temporary scratch array
             if (mid < right) {
                 let tmp: int[] = []
+                let tlen: int = 0
                 let ia: int = left
                 let ib: int = mid
                 let merging: int = 1
@@ -156,18 +172,22 @@ fn merge_sort_coro(arr: int[], n: int) {
                         if (ib < right) {
                             if (arr[ia] <= arr[ib]) {
                                 tmp.push(arr[ia])
+                                tlen = tlen + 1
                                 ia = ia + 1
                             } else {
                                 tmp.push(arr[ib])
+                                tlen = tlen + 1
                                 ib = ib + 1
                             }
                         } else {
                             tmp.push(arr[ia])
+                            tlen = tlen + 1
                             ia = ia + 1
                         }
                     } else {
                         if (ib < right) {
                             tmp.push(arr[ib])
+                            tlen = tlen + 1
                             ib = ib + 1
                         } else {
                             merging = 0
@@ -176,7 +196,6 @@ fn merge_sort_coro(arr: int[], n: int) {
                 }
                 // Write merged tmp back into arr[left..right)
                 let ti: int = 0
-                let tlen: int = tmp.len()
                 while (ti < tlen) {
                     arr[left + ti] = tmp[ti]
                     ti = ti + 1
@@ -190,5 +209,6 @@ fn merge_sort_coro(arr: int[], n: int) {
     }
 }
 
-// merge_sort_noop: default onDone callback — replace with your own handler
+/// Default no-op callback for merge_sort_coro. Replace with your own handler to react when sorting completes.
+/// @since 1.0.0
 fn merge_sort_noop() {}

package/src/stdlib/spawn.mcrs

@@ -1,40 +1,63 @@
 // Spawn point and teleport helpers
 // Usage: import "stdlib/spawn.mcrs"
 
-/// Teleport player to coordinates
+/// Teleports the target selector to fixed world coordinates.
+/// @param target  Target selector to move
+/// @param x       Destination X coordinate
+/// @param y       Destination Y coordinate
+/// @param z       Destination Z coordinate
+/// @example
+/// teleport_to(@p, 0, 64, 0)
 fn teleport_to(target: selector, x: int, y: int, z: int) {
     tp(target, x, y, z);
 }
 
-/// Teleport player to another entity
+/// Teleports the target selector to another entity.
+/// @param target  Selector to teleport
+/// @param dest    Selector whose current position is used as the destination
 fn teleport_to_entity(target: selector, dest: selector) {
     tp(target, dest);
 }
 
-/// Spread players randomly in area
+/// Placeholder helper for spreading all players randomly in an area.
+/// The raw `spreadplayers` command is noted here but not emitted yet.
+/// Current behavior only broadcasts a status message.
+/// @param x       Center X coordinate
+/// @param z       Center Z coordinate
+/// @param radius  Maximum spread radius in blocks
 fn spread_players(x: int, z: int, radius: int) {
     // Use raw command for spreadplayers
     // spreadplayers(x, z, 0, radius, false, @a);
     say("Spreading players...");
 }
 
-/// Teleport all players to one location
+/// Teleports all players to one location.
+/// @param x  Destination X coordinate
+/// @param y  Destination Y coordinate
+/// @param z  Destination Z coordinate
 fn gather_all(x: int, y: int, z: int) {
     tp(@a, x, y, z);
 }
 
-/// Teleport player up (for launching)
+/// Teleports the target upward relative to its current position.
+/// Useful for launch pads or scripted knock-up effects.
+/// @param target  Selector to move
+/// @param height  Relative Y offset in blocks
 fn launch_up(target: selector, height: int) {
     tp(target, ~0, ~height, ~0);
 }
 
-/// Teleport to lobby (customize coordinates)
+/// Teleports the target to the hard-coded lobby position.
+/// This helper also shows a welcome title and should be customized per map.
+/// @param target  Selector to move to the lobby
 fn goto_lobby(target: selector) {
     tp(target, 0, 64, 0);
     title(target, "Welcome to Lobby!");
 }
 
-/// Teleport to arena (customize coordinates)
+/// Teleports the target to the hard-coded arena position.
+/// This helper also shows a fight title and should be customized per map.
+/// @param target  Selector to move to the arena
 fn goto_arena(target: selector) {
     tp(target, 100, 64, 100);
     title(target, "Fight!");

package/src/stdlib/state.mcrs

@@ -23,19 +23,39 @@
 module library
 
 /// Read the current state of an entity.
-/// Returns -1 if the entity has not been initialised (score is 0 = unset in MC,
-/// but we reserve -1 as the sentinel for "never set via init_state").
+///
+/// Returns `-1` if the entity has not been initialised (score is 0 = unset in
+/// Minecraft, but we reserve `-1` as the sentinel for "never set via
+/// `init_state`").
+///
+/// @since 1.0.0
+/// @param entity  Selector for the target entity
+/// @returns       Current state value stored in `rs.state`, or `-1` if unset
+/// @example
+/// let s: int = get_state(@s)
 fn get_state(entity: selector) -> int {
     return scoreboard_get(entity, "rs.state");
 }
 
 /// Write a state value to an entity.
+///
+/// @since 1.0.0
+/// @param entity  Selector for the target entity
+/// @param state   Integer state constant to write
+/// @example
+/// set_state(@s, 1)
 fn set_state(entity: selector, state: int) {
     scoreboard_set(entity, "rs.state", state);
 }
 
 /// Check whether an entity is currently in the given state.
-/// Returns 1 if yes, 0 if no.
+///
+/// @since 1.0.0
+/// @param entity  Selector for the target entity
+/// @param state   Integer state constant to compare against
+/// @returns       `1` if the entity is in `state`, `0` otherwise
+/// @example
+/// if (is_state(@s, STATE_COMBAT) == 1) { /* per-tick combat logic */ }
 fn is_state(entity: selector, state: int) -> int {
     let cur: int = get_state(entity);
     if (cur == state) {
@@ -45,7 +65,14 @@ fn is_state(entity: selector, state: int) -> int {
 }
 
 /// Initialise an entity's state only if it has not been set yet (score == -1).
-/// Call once on spawn / load to avoid overwriting an in-progress state.
+///
+/// Call once on spawn or load to avoid overwriting an in-progress state.
+///
+/// @since 1.0.0
+/// @param entity   Selector for the target entity
+/// @param initial  State constant to write when the entity is uninitialised
+/// @example
+/// init_state(@s, STATE_IDLE)
 fn init_state(entity: selector, initial: int) {
     let cur: int = get_state(entity);
     if (cur == -1) {
@@ -54,8 +81,16 @@ fn init_state(entity: selector, initial: int) {
 }
 
 /// Attempt a guarded transition from `from` to `to`.
+///
 /// Only performs the transition when the entity is currently in `from`.
-/// Returns 1 on success, 0 if the entity was not in `from`.
+///
+/// @since 1.0.0
+/// @param entity  Selector for the target entity
+/// @param from    Required current state
+/// @param to      State to transition into
+/// @returns       `1` on success, `0` if the entity was not in `from`
+/// @example
+/// let ok: int = transition(@s, STATE_IDLE, STATE_COMBAT)
 fn transition(entity: selector, from: int, to: int) -> int {
     if (is_state(entity, from) == 1) {
         set_state(entity, to);

package/src/stdlib/strings.mcrs

@@ -1,7 +1,135 @@
-// String helpers for RedScript datapacks.
-// Runtime string manipulation is still limited; `str_len` is compiler-assisted
-// and lowers to `data get storage rs:strings ...` for literal-backed strings.
+// strings.mcrs — String manipulation helpers for RedScript datapacks.
+//
+// ## MC 1.21.4 String Model
+//
+// Runtime string operations work via NBT storage (rs:strings).
+// Strings must be pre-written into rs:strings storage before calling
+// these functions. The storage layout convention is:
+//
+//   rs:strings { A: "...", B: "...", Result: "..." }
+//
+// The string parameters accepted by these functions represent the
+// NBT field name (key) within rs:strings, e.g. passing "A" means
+// the string is stored at `rs:strings.A`.
+//
+// ## Feasibility Summary (MC 1.21.4)
+//
+//   str_len      — PARTIAL: returns 1 for plain string NBT tags.
+//                  For true length, strings must be stored as char-lists.
+//   str_concat   — PARTIAL: produces an NBT list [A, B] usable in tellraw.
+//                  Single concatenated string requires a macro helper.
+//   str_contains — NOT FEASIBLE natively (no substring search command).
+//                  Always returns 0; workaround described in docs.
+//   str_slice    — FEASIBLE via `data modify ... set string` (MC 1.20.2+).
 
+module library;
+
+// ─── str_len ──────────────────────────────────────────────────────────────────
+
+/// Returns the length of the string stored at rs:strings.{s}.
+///
+/// LIMITATION (MC 1.21.4): `execute store result score ... run data get storage`
+/// returns 1 for any plain string NBT tag, not the character count. To get a
+/// true character count, the string must be stored as an NBT list of single-char
+/// strings (e.g. ["h","e","l","l","o"]), in which case data_get returns the list
+/// length correctly.
+///
+/// For literal strings whose length is known at compile time, prefer using
+/// the constant directly — the compiler will fold it.
+///
+/// @since 1.0.0
+/// @param s  NBT field name in rs:strings (e.g. "A")
+/// @returns  1 for plain string tags; list element count for char-list strings.
+/// @example
+/// str_len("A")  // result: 1 (plain string) or char count (char-list)
 fn str_len(s: string) -> int {
+    return data_get("storage", "rs:strings", s);
+}
+
+// ─── str_concat ───────────────────────────────────────────────────────────────
+
+/// Concatenates two strings from rs:strings and writes the result to
+/// rs:strings.Result as an NBT list [a_value, b_value].
+///
+/// The result list is suitable for use in tellraw JSON text components:
+///   tellraw @a {"nbt":"Result","storage":"rs:strings","interpret":false}
+///
+/// LIMITATION (MC 1.21.4): MC has no native string concatenation command.
+/// Single-string concatenation (e.g. "ab" from "a"+"b") requires a
+/// recursive macro helper function; this is out of scope for a pure stdlib.
+/// The NBT list representation works for display (tellraw) but cannot be
+/// passed back to further string operations without conversion.
+///
+/// ALTERNATIVE for display: use a tellraw JSON array directly:
+///   tellraw @a [{"storage":"rs:strings","nbt":"A"},{"storage":"rs:strings","nbt":"B"}]
+///
+/// @since 1.0.0
+/// @param a  NBT field name of the first string in rs:strings (e.g. "A")
+/// @param b  NBT field name of the second string in rs:strings (e.g. "B")
+/// @returns  rs:strings.Result is set to an NBT list [valueA, valueB]
+/// @example
+/// str_concat("A", "B")  // rs:strings.Result = ["hello", "world"]
+fn str_concat(a: string, b: string) {
+    // Initialise Result as an empty list
+    raw("data modify storage rs:strings Result set value []");
+    // Append both strings as list elements (order-preserving concat)
+    raw("data modify storage rs:strings Result append from storage rs:strings {a}");
+    raw("data modify storage rs:strings Result append from storage rs:strings {b}");
+}
+
+// ─── str_contains ─────────────────────────────────────────────────────────────
+
+/// Checks whether the string at rs:strings.{s} contains the substring at
+/// rs:strings.{sub}. Returns 1 if found, 0 if not found.
+///
+/// NOT FEASIBLE (MC 1.21.4): Minecraft datapacks do not provide a native
+/// substring search command. There is no `execute if data` form that tests
+/// whether one string is contained within another.
+///
+/// THIS FUNCTION ALWAYS RETURNS 0.
+///
+/// WORKAROUNDS for datapack authors:
+///   1. If sub is a compile-time constant and the check position is known,
+///      use str_slice to extract a window and compare via scoreboard.
+///   2. Pre-process strings server-side and store a presence flag in NBT.
+///   3. Use a macro function (MC 1.20.2+) that iterates over character
+///      positions with `$(var)` substitution and returns early on match.
+///
+/// @since 1.0.0
+/// @param s    NBT field name of the haystack string in rs:strings
+/// @param sub  NBT field name of the needle string in rs:strings
+/// @returns    0 (always — not implemented due to MC limitation)
+fn str_contains(s: string, sub: string) -> int {
+    // NOT FEASIBLE in MC 1.21.4: no native substring search.
+    // Returns 0 as a safe default. See workaround section in docs above.
     return 0;
 }
+
+// ─── str_slice ────────────────────────────────────────────────────────────────
+
+/// Extracts a substring from rs:strings.{s} and writes it to rs:strings.Result.
+/// Uses the MC 1.20.2+ `data modify ... set string ... start end` feature.
+///
+/// Indices follow Java/Python slicing semantics:
+///   - start is inclusive, 0-based.
+///   - end is exclusive (end = start + length).
+///   - Negative end counts from the end of the string (e.g. -1 = all but last char).
+///   - Omitting end (use a very large positive int like 999999) copies to end of string.
+///
+/// Examples:
+///   str_slice("A", 0, 5)  → first 5 characters of rs:strings.A
+///   str_slice("A", 2, -1) → all but first 2 and last 1 characters
+///
+/// @since 2.2.0
+/// @param s      NBT field name of the source string in rs:strings (e.g. "A")
+/// @param start  Start index (inclusive, 0-based)
+/// @param end    End index (exclusive); negative counts from string end
+/// @returns      rs:strings.Result contains the extracted substring
+/// @example
+/// str_slice("A", 0, 5)   // first 5 chars of rs:strings.A
+/// str_slice("A", 2, -1)  // drop first 2 and last 1 chars
+fn str_slice(s: string, start: int, end: int) {
+    // MC 1.20.2+ set-string command: copies a substring of the source string.
+    // {s}, {start}, {end} are interpolated by the RedScript compiler.
+    raw("data modify storage rs:strings Result set string storage rs:strings {s} {start} {end}");
+}

package/src/stdlib/tags.mcrs

@@ -1,5 +1,5 @@
-// Minecraft Java Edition tag constants generated from the Minecraft Fandom Tag page.
-// Covers Java Edition block, entity type, item, fluid, and damage type tags listed on the page.
+/// Minecraft Java Edition tag constants generated from the Minecraft Fandom tag page.
+/// Covers block, entity type, item, fluid, and damage type tags.
 
 // ===== BLOCK TAGS =====
 

package/src/stdlib/teams.mcrs

@@ -1,57 +1,68 @@
 // Team management helpers
 // Usage: import "stdlib/teams.mcrs"
 
-/// Create a team with color
+/// Creates a team and applies a display color.
+/// @param name   Team name used by the scoreboard team system
+/// @param color  Minecraft team color string such as `red` or `blue`
+/// @example
+/// create_team("spectator", "gray")
 fn create_team(name: string, color: string) {
     team_add(name);
     team_option(name, "color", color);
 }
 
-/// Create red team
+/// Creates the standard red team with friendly fire disabled.
+/// @example
+/// create_red_team()
 fn create_red_team() {
     team_add("red");
     team_option("red", "color", "red");
     team_option("red", "friendlyFire", "false");
 }
 
-/// Create blue team
+/// Creates the standard blue team with friendly fire disabled.
 fn create_blue_team() {
     team_add("blue");
     team_option("blue", "color", "blue");
     team_option("blue", "friendlyFire", "false");
 }
 
-/// Create green team
+/// Creates the standard green team with friendly fire disabled.
 fn create_green_team() {
     team_add("green");
     team_option("green", "color", "green");
     team_option("green", "friendlyFire", "false");
 }
 
-/// Create yellow team
+/// Creates the standard yellow team with friendly fire disabled.
 fn create_yellow_team() {
     team_add("yellow");
     team_option("yellow", "color", "yellow");
     team_option("yellow", "friendlyFire", "false");
 }
 
-/// Add player to team
+/// Adds an entity or player selector to a team.
+/// @param target     Target selector to join the team
+/// @param team_name  Existing team name
 fn add_to_team(target: selector, team_name: string) {
     team_join(target, team_name);
 }
 
-/// Remove player from all teams
+/// Removes an entity or player selector from all teams.
+/// @param target  Target selector to remove from teams
 fn remove_from_teams(target: selector) {
     team_leave(target);
 }
 
-/// Setup standard 2-team game
+/// Creates the default two-team setup used by many arena games.
+/// This creates `red` and `blue`.
 fn setup_two_teams() {
     create_red_team();
     create_blue_team();
 }
 
-/// Setup 4-team game
+/// Creates the default four-team setup.
+/// This creates `red`, `blue`, `green`, and `yellow`.
 fn setup_four_teams() {
     create_red_team();
     create_blue_team();
@@ -59,7 +70,8 @@ fn setup_four_teams() {
     create_yellow_team();
 }
 
-/// Cleanup all teams
+/// Removes the default team set created by this module.
+/// Safe to call during cleanup even if some teams were unused.
 fn cleanup_teams() {
     team_remove("red");
     team_remove("blue");

package/src/stdlib/timer.mcrs

@@ -78,32 +78,62 @@ impl Timer {
 
 // ─── Tick-based stopwatch ─────────────────────────────────────────────────────
 
-// tick_to_seconds(ticks): convert MC ticks to seconds (20 ticks = 1 second)
+/// Convert Minecraft ticks to whole seconds (20 ticks = 1 second).
+/// @since 1.0.0
+/// @param ticks  Elapsed ticks
+/// @returns      ticks / 20
+/// @example
+/// let s = tick_to_seconds(100)  // result: 5
 fn tick_to_seconds(ticks: int): int {
     return ticks / 20;
 }
 
-// tick_to_ms(ticks): convert ticks to milliseconds
+/// Convert Minecraft ticks to milliseconds (1 tick = 50 ms).
+/// @since 1.0.0
+/// @param ticks  Elapsed ticks
+/// @returns      ticks * 50
+/// @example
+/// let ms = tick_to_ms(20)  // result: 1000
 fn tick_to_ms(ticks: int): int {
     return ticks * 50;
 }
 
-// seconds_to_ticks(s): convert seconds to ticks
+/// Convert seconds to Minecraft ticks (1 second = 20 ticks).
+/// @since 1.0.0
+/// @param s  Seconds
+/// @returns  s * 20
+/// @example
+/// let t = seconds_to_ticks(5)  // result: 100
 fn seconds_to_ticks(s: int): int {
     return s * 20;
 }
 
-// format_time_s(ticks): ticks → seconds component (mod 60)
+/// Extract seconds component from a tick count (0-59).
+/// @since 1.0.0
+/// @param ticks  Elapsed ticks
+/// @returns      (ticks / 20) % 60
+/// @example
+/// let s = format_time_s(1500)  // result: 15  (75 seconds mod 60)
 fn format_time_s(ticks: int): int {
     return (ticks / 20) % 60;
 }
 
-// format_time_m(ticks): ticks → minutes component
+/// Extract minutes component from a tick count (0-59).
+/// @since 1.0.0
+/// @param ticks  Elapsed ticks
+/// @returns      (ticks / 1200) % 60
+/// @example
+/// let m = format_time_m(72000)  // result: 0  (1 hour)
 fn format_time_m(ticks: int): int {
     return (ticks / 1200) % 60;
 }
 
-// format_time_h(ticks): ticks → hours component
+/// Extract hours component from a tick count.
+/// @since 1.0.0
+/// @param ticks  Elapsed ticks
+/// @returns      ticks / 72000
+/// @example
+/// let h = format_time_h(144000)  // result: 2
 fn format_time_h(ticks: int): int {
     return ticks / 72000;
 }