redscript-mc 2.6.2 → 3.0.0

package/src/stdlib/queue.mcrs

@@ -0,0 +1,123 @@
+// queue.mcrs — NBT-backed FIFO queue for RedScript datapacks.
+//
+// The queue is stored in `storage rs:arrays Queue` as an int list.
+// A scoreboard objective `rs.q_head` tracks the logical head index so that
+// dequeue is O(1) (we never physically shift elements; the head pointer just
+// advances).  queue_clear resets both the list and the head pointer to 0.
+//
+// Storage layout:
+//   rs:arrays { Queue: [10, 20, 30] }   ← raw backing list
+//   scoreboard rs.q_head <global>        ← index of the next element to pop
+
+module library;
+
+// ─── Internal macro helpers ──────────────────────────────────────────────────
+
+fn __queue_append_apply() {
+    raw("$data modify storage rs:arrays Queue append value $(val)");
+}
+
+fn __queue_peek_apply() {
+    raw("$execute store result score $ret __OBJ__ run data get storage rs:arrays Queue[$(idx)]");
+}
+
+fn __queue_size_raw_apply() {
+    raw("$execute store result score $ret __OBJ__ run data get storage rs:arrays Queue");
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/// Enqueue a value into the queue.
+///
+/// The value is appended to the end of `storage rs:arrays Queue`.
+///
+/// @since 3.0.0
+/// @param val  Value to enqueue
+/// @example
+/// queue_push(42)
+fn queue_push(val: int) {
+    raw("execute store result storage rs:macro_args val int 1 run scoreboard players get $p0 __OBJ__");
+    raw("function __NS__:__queue_append_apply with storage rs:macro_args");
+}
+
+/// Dequeue and return the front value.
+///
+/// Advances the head pointer by one. If the queue is empty, returns `-1`.
+///
+/// @since 3.0.0
+/// @returns Front value, or -1 if empty
+/// @example
+/// let v: int = queue_pop()
+fn queue_pop(): int {
+    // Check empty
+    let empty: int = queue_empty();
+    if (empty == 1) { return -1; }
+
+    // Read front element
+    raw("scoreboard players set $ret __OBJ__ 0");
+    raw("execute store result storage rs:macro_args idx int 1 run scoreboard players get rs.q_head __RS__");
+    raw("function __NS__:__queue_peek_apply with storage rs:macro_args");
+    // Advance head pointer
+    raw("scoreboard players add rs.q_head __RS__ 1");
+    raw("return 1");
+    return 0;
+}
+
+/// Peek at the front value without removing it.
+///
+/// If the queue is empty, returns `-1`.
+///
+/// @since 3.0.0
+/// @returns Front value, or -1 if empty
+/// @example
+/// let front: int = queue_peek()
+fn queue_peek(): int {
+    let empty: int = queue_empty();
+    if (empty == 1) { return -1; }
+
+    raw("scoreboard players set $ret __OBJ__ 0");
+    raw("execute store result storage rs:macro_args idx int 1 run scoreboard players get rs.q_head __RS__");
+    raw("function __NS__:__queue_peek_apply with storage rs:macro_args");
+    raw("return 1");
+    return 0;
+}
+
+/// Get the number of elements in the queue.
+///
+/// This is the count of un-popped elements: `raw_size - head`.
+///
+/// @since 3.0.0
+/// @returns Queue size
+/// @example
+/// let n: int = queue_size()
+fn queue_size(): int {
+    raw("scoreboard players set $ret __OBJ__ 0");
+    raw("function __NS__:__queue_size_raw_apply with storage rs:macro_args");
+    raw("scoreboard players operation $ret __OBJ__ -= rs.q_head __RS__");
+    raw("return 1");
+    return 0;
+}
+
+/// Check if the queue is empty.
+///
+/// @since 3.0.0
+/// @returns 1 if empty, 0 otherwise
+/// @example
+/// if (queue_empty() == 1) { }
+fn queue_empty(): int {
+    let sz: int = queue_size();
+    if (sz <= 0) { return 1; }
+    return 0;
+}
+
+/// Clear all elements from the queue.
+///
+/// Resets `storage rs:arrays Queue` to an empty list and the head pointer to 0.
+///
+/// @since 3.0.0
+/// @example
+/// queue_clear()
+fn queue_clear() {
+    raw("data modify storage rs:arrays Queue set value []");
+    raw("scoreboard players set rs.q_head __RS__ 0");
+}

package/src/stdlib/random.mcrs

@@ -12,21 +12,41 @@
 
 module library;
 
-// next_lcg(seed): advance LCG state, return next pseudo-random int32.
-// The returned value is also the new seed for the next call.
+/// Advance the LCG state by one step, returning the next pseudo-random int32.
+/// The returned value is also the new seed for the next call.
+/// @since 1.0.0
+/// @param seed  Current LCG state (any non-zero integer to start)
+/// @returns  Next pseudo-random int32 (also serves as next seed)
+/// @example
+/// let seed: int = 12345
+/// seed = next_lcg(seed)
+/// seed = next_lcg(seed)  // advance two steps
 fn next_lcg(seed: int): int {
     return seed * 1664525 + 1013904223;
 }
 
-// random_range(seed, lo, hi): return integer in [lo, hi).
-// seed should already be the output of next_lcg.
+/// Generate a pseudo-random integer in the range [lo, hi).
+/// @since 1.0.0
+/// @param seed  LCG output value (result of next_lcg)
+/// @param lo    Inclusive lower bound
+/// @param hi    Exclusive upper bound (must be > lo)
+/// @returns  Integer in [lo, hi)
+/// @example
+/// seed = next_lcg(seed)
+/// let roll: int = random_range(seed, 1, 7)  // dice roll: 1-6
 fn random_range(seed: int, lo: int, hi: int): int {
     let r: int = seed;
     if (r < 0) { r = 0 - r; }
     return lo + r % (hi - lo);
 }
 
-// random_bool(seed): return 0 or 1 with equal probability.
+/// Generate a pseudo-random boolean (0 or 1) with equal probability.
+/// @since 1.0.0
+/// @param seed  LCG output value (result of next_lcg)
+/// @returns  0 or 1 with ~50% probability each
+/// @example
+/// seed = next_lcg(seed)
+/// let coin: int = random_bool(seed)  // 0 or 1
 fn random_bool(seed: int): int {
     let r: int = seed;
     if (r < 0) { r = 0 - r; }
@@ -44,19 +64,34 @@ fn random_bool(seed: int): int {
 //
 // Usage: maintain two state variables (hi, lo); update both each call.
 
-// pcg_next_lo(state_lo, state_hi): advance PCG state (low word).
-// Returns new low word. Use with pcg_next_hi.
+/// Advance the PCG low-word state by one step.
+/// Call together with pcg_next_hi; use pcg_output to extract the random value.
+/// @since 1.0.0
+/// @param state_lo  Current low word of PCG state
+/// @returns  New low word
+/// @example
+/// let lo: int = pcg_next_lo(state_lo)
 fn pcg_next_lo(state_lo: int): int {
     return state_lo * 747796405 + -1403630843;
 }
 
-// pcg_next_hi(state_lo, state_hi): advance PCG state (high word).
+/// Advance the PCG high-word state by one step.
+/// @since 1.0.0
+/// @param state_hi  Current high word of PCG state
+/// @param state_lo  Current low word of PCG state (previous, before pcg_next_lo)
+/// @returns  New high word
+/// @example
+/// let hi: int = pcg_next_hi(state_hi, state_lo)
 fn pcg_next_hi(state_hi: int, state_lo: int): int {
     return state_hi * 747796405 + state_lo;
 }
 
-// pcg_output(state_lo): extract output value from PCG low word.
-// Applies XSH-RR output permutation (simplified to XOR-shift).
+/// Extract an output value from the PCG low word using XSH-RR permutation.
+/// @since 1.0.0
+/// @param state_lo  Current low word of PCG state (after pcg_next_lo)
+/// @returns  Pseudo-random output value (unsigned, any int)
+/// @example
+/// let rng: int = pcg_output(state_lo)
 fn pcg_output(state_lo: int): int {
     let xsh: int = state_lo;
     // xsh = ((state >> 18) ^ state) >> 27   (simplified: use single xor-shift)
@@ -79,10 +114,14 @@ fn _binom_loop(n: int, p: int, seed: int, acc: int): int {
     return _binom_loop(n - 1, p, s2, acc + hit);
 }
 
-// binomial_sample(n, p_x10000, seed): count successes in n Bernoulli trials
-// p_x10000: probability ×10000 (e.g. 5000 = 0.5 = 50%)
-// seed: LCG seed (any non-zero int)
-// Returns: number of successes ∈ [0, n]
+/// Simulate n Bernoulli trials and count the number of successes (binomial distribution).
+/// @since 1.0.0
+/// @param n          Number of trials
+/// @param p_x10000   Success probability ×10000 (e.g. 5000 = 50%, 3000 = 30%)
+/// @param seed       LCG seed (any non-zero integer)
+/// @returns  Number of successes in [0, n]
+/// @example
+/// let hits: int = binomial_sample(10, 5000, 99999)  // ~5 successes on average
 fn binomial_sample(n: int, p_x10000: int, seed: int): int {
     return _binom_loop(n, p_x10000, seed, 0);
 }
@@ -103,10 +142,16 @@ fn _hyper_loop(rem_pop: int, rem_succ: int, draws: int, seed: int, acc: int): in
     return _hyper_loop(rem_pop - 1, rem_succ - success, draws - 1, s2, acc + success);
 }
 
-// hypergeometric_sample(pop_size, success_states, draws, seed):
-// Simulate drawing `draws` items without replacement from a population of `pop_size`
-// items of which `success_states` are successes.
-// seed: LCG seed. Returns: number of successes drawn ∈ [0, min(draws, success_states)].
+/// Draw `draws` items without replacement from a population and count successes (hypergeometric distribution).
+/// @since 1.0.0
+/// @param pop_size       Total population size
+/// @param success_states Number of "success" items in the population
+/// @param draws          Number of items to draw
+/// @param seed           LCG seed (any non-zero integer)
+/// @returns  Number of successes drawn, in [0, min(draws, success_states)]
+/// @example
+/// // 52-card deck, 4 aces, draw 5 cards
+/// let aces: int = hypergeometric_sample(52, 4, 5, 42)
 fn hypergeometric_sample(pop_size: int, success_states: int, draws: int, seed: int): int {
     return _hyper_loop(pop_size, success_states, draws, seed, 0);
 }

package/src/stdlib/result.mcrs

@@ -0,0 +1,111 @@
+// result.mcrs — Result<T> type for error handling in RedScript datapacks.
+//
+// Result<T> wraps either a successful value (Ok) or an error code (Err).
+// This is useful in Minecraft datapacks for operations that may fail,
+// such as division, inventory checks, or entity lookups.
+//
+// Usage:
+//   let r = divide(10, 2)
+//   match r {
+//     Result::Ok(value) => { /* use value */ }
+//     Result::Err(code) => { /* handle error code */ }
+//   }
+//
+// Error codes are integers; use negative values for errors by convention:
+//   -1 = generic error
+//   -2 = division by zero
+//   -3 = not found
+//   etc.
+
+module library;
+
+// ─── Result<T> enum ───────────────────────────────────────────────────────────
+
+enum Result {
+  Ok(value: int),
+  Err(code: int),
+}
+
+// ─── Constructor helpers ──────────────────────────────────────────────────────
+
+/// Construct a successful Result with the given value.
+/// @since 1.0.0
+/// @param value  The success value (any integer)
+/// @returns      Result::Ok(value)
+/// @example
+/// let r = result_ok(42)  // Ok result carrying 42
+fn result_ok(value: int): Result {
+  return Result::Ok(value: value);
+}
+
+/// Construct a failed Result with the given error code.
+/// @since 1.0.0
+/// @param code  Error code (use negative by convention: -1 generic, -2 div/zero)
+/// @returns     Result::Err(code)
+/// @example
+/// let r = result_err(-2)  // division-by-zero error
+fn result_err(code: int): Result {
+  return Result::Err(code: code);
+}
+
+// ─── Query helpers ────────────────────────────────────────────────────────────
+
+/// Returns 1 if the Result is Ok, 0 otherwise.
+/// @since 1.0.0
+/// @param r  The Result to test
+/// @returns  1 if Ok, 0 if Err
+/// @example
+/// let ok = result_is_ok(result_ok(5))  // result: 1
+fn result_is_ok(r: Result): int {
+  match r {
+    Result::Ok(value) => { return 1; }
+    Result::Err(code) => { return 0; }
+  }
+  return 0;
+}
+
+/// Returns 1 if the Result is Err, 0 otherwise.
+fn result_is_err(r: Result): int {
+  match r {
+    Result::Ok(value) => { return 0; }
+    Result::Err(code) => { return 1; }
+  }
+  return 0;
+}
+
+// ─── Extraction helpers ───────────────────────────────────────────────────────
+
+/// Extract the value from an Ok result.
+/// Returns 0 if the Result is Err (check result_is_ok first).
+/// @since 1.0.0
+/// @param r  The Result to unwrap
+/// @returns  The Ok value, or 0 if Err
+/// @example
+/// let v = result_value(result_ok(99))  // result: 99
+fn result_value(r: Result): int {
+  match r {
+    Result::Ok(value) => { return value; }
+    Result::Err(code) => { return 0; }
+  }
+  return 0;
+}
+
+/// Extract the error code from an Err result.
+/// Returns 0 if the Result is Ok (check result_is_err first).
+fn result_code(r: Result): int {
+  match r {
+    Result::Ok(value) => { return 0; }
+    Result::Err(code) => { return code; }
+  }
+  return 0;
+}
+
+// ─── Example: safe division ───────────────────────────────────────────────────
+
+/// Divide a by b; returns Err(-2) on division by zero.
+fn result_divide(a: int, b: int): Result {
+  if (b == 0) {
+    return Result::Err(code: -2);
+  }
+  return Result::Ok(value: a / b);
+}

package/src/stdlib/scheduler.mcrs

@@ -15,7 +15,14 @@ module library
 
 // ─── Per-player tasks ─────────────────────────────────────────────────────────
 
-/// Schedule slot task_id (0..7) to fire after `delay` ticks for player p.
+/// Schedule slot `task_id` (0–7) to fire after `delay` ticks for player `p`.
+///
+/// @since 1.0.0
+/// @param p        Recipient player or entity selector
+/// @param task_id  Slot index in range [0, 7]
+/// @param delay    Number of ticks to wait before firing
+/// @example
+/// task_schedule(@s, 0, 40)
 fn task_schedule(p: selector, task_id: int, delay: int) {
     if (task_id == 0) {
         scoreboard_set(p, "rs.t0", delay);
@@ -48,7 +55,13 @@ fn task_schedule(p: selector, task_id: int, delay: int) {
     }
 }
 
-/// Cancel slot task_id for player p (zeroes the counter).
+/// Cancel slot `task_id` for player `p` (zeroes the counter).
+///
+/// @since 1.0.0
+/// @param p        Recipient player or entity selector
+/// @param task_id  Slot index in range [0, 7]
+/// @example
+/// task_cancel(@s, 0)
 fn task_cancel(p: selector, task_id: int) {
     if (task_id == 0) {
         scoreboard_set(p, "rs.t0", 0);
@@ -81,8 +94,16 @@ fn task_cancel(p: selector, task_id: int) {
     }
 }
 
-/// Returns 1 if slot task_id is ready (counter reached 1 on last tick), 0 otherwise.
-/// Automatically clears the slot when ready.
+/// Returns `1` if slot `task_id` fired on this tick (counter reached 1), `0` otherwise.
+///
+/// Automatically clears the slot once it fires so subsequent calls return `0`.
+///
+/// @since 1.0.0
+/// @param p        Player or entity selector to check
+/// @param task_id  Slot index in range [0, 7]
+/// @returns        `1` when the task is ready, `0` otherwise
+/// @example
+/// if (task_ready(@s, 0) == 1) { /* handle event */ }
 fn task_ready(p: selector, task_id: int) -> int {
     let val: int = 0;
     if (task_id == 0) {
@@ -123,7 +144,16 @@ fn task_ready(p: selector, task_id: int) -> int {
 
 // ─── Global tasks (bound to #rs fake-player) ──────────────────────────────────
 
-/// Schedule global slot task_id (0..7) to fire after `delay` ticks.
+/// Schedule global slot `task_id` (0–7) to fire after `delay` ticks.
+///
+/// Global tasks are stored on the `#rs` fake-player and are not bound to any
+/// specific player entity.
+///
+/// @since 1.0.0
+/// @param task_id  Slot index in range [0, 7]
+/// @param delay    Number of ticks to wait before firing
+/// @example
+/// gtask_schedule(0, 200)
 fn gtask_schedule(task_id: int, delay: int) {
     if (task_id == 0) {
         scoreboard_set("#rs", "rs.g0", delay);
@@ -156,7 +186,12 @@ fn gtask_schedule(task_id: int, delay: int) {
     }
 }
 
-/// Cancel global slot task_id.
+/// Cancel global slot `task_id` by zeroing its counter.
+///
+/// @since 1.0.0
+/// @param task_id  Slot index in range [0, 7]
+/// @example
+/// gtask_cancel(0)
 fn gtask_cancel(task_id: int) {
     if (task_id == 0) {
         scoreboard_set("#rs", "rs.g0", 0);
@@ -189,8 +224,15 @@ fn gtask_cancel(task_id: int) {
     }
 }
 
-/// Returns 1 if global slot task_id is ready, 0 otherwise.
-/// Automatically clears the slot when ready.
+/// Returns `1` if global slot `task_id` fired this tick, `0` otherwise.
+///
+/// Automatically clears the slot once it fires.
+///
+/// @since 1.0.0
+/// @param task_id  Slot index in range [0, 7]
+/// @returns        `1` when the task is ready, `0` otherwise
+/// @example
+/// if (gtask_ready(0) == 1) { /* handle global event */ }
 fn gtask_ready(task_id: int) -> int {
     let val: int = 0;
     if (task_id == 0) {
@@ -231,8 +273,15 @@ fn gtask_ready(task_id: int) -> int {
 
 // ─── Tick driver ──────────────────────────────────────────────────────────────
 
-/// Decrement all active per-player timers by 1.
-/// Call this inside your @tick function (executed as @a).
+/// Decrement all active per-player and global timers by 1 each tick.
+///
+/// Call this inside your `@tick` function (executed as `@a`). Counters are
+/// clamped to 0 so they never go negative.
+///
+/// @since 1.0.0
+/// @example
+/// // In your @tick mcfunction:
+/// scheduler_tick()
 fn scheduler_tick() {
     // Per-player slots
     raw("execute as @a run scoreboard players remove @s rs.t0 1");