redscript-mc 2.5.0 → 2.6.2

package/src/stdlib/scheduler.mcrs

@@ -0,0 +1,271 @@
+// Scoreboard-based task scheduler.
+// Usage: import "stdlib/scheduler.mcrs"
+//
+// Supports 8 named timer slots (t0..t7) per entity and 8 global slots.
+// Scoreboards used: rs.t0 .. rs.t7  (per-player)
+//                   rs.g0 .. rs.g7  (global, stored on #rs fake-player)
+//
+// Typical usage:
+//   task_schedule(@s, 0, 40)   // schedule slot 0 to fire in 40 ticks
+//   // in @tick function:
+//   scheduler_tick()
+//   if (task_ready(@s, 0) == 1) { /* fire */ }
+
+module library
+
+// ─── Per-player tasks ─────────────────────────────────────────────────────────
+
+/// Schedule slot task_id (0..7) to fire after `delay` ticks for player p.
+fn task_schedule(p: selector, task_id: int, delay: int) {
+    if (task_id == 0) {
+        scoreboard_set(p, "rs.t0", delay);
+    } else {
+        if (task_id == 1) {
+            scoreboard_set(p, "rs.t1", delay);
+        } else {
+            if (task_id == 2) {
+                scoreboard_set(p, "rs.t2", delay);
+            } else {
+                if (task_id == 3) {
+                    scoreboard_set(p, "rs.t3", delay);
+                } else {
+                    if (task_id == 4) {
+                        scoreboard_set(p, "rs.t4", delay);
+                    } else {
+                        if (task_id == 5) {
+                            scoreboard_set(p, "rs.t5", delay);
+                        } else {
+                            if (task_id == 6) {
+                                scoreboard_set(p, "rs.t6", delay);
+                            } else {
+                                scoreboard_set(p, "rs.t7", delay);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+
+/// Cancel slot task_id for player p (zeroes the counter).
+fn task_cancel(p: selector, task_id: int) {
+    if (task_id == 0) {
+        scoreboard_set(p, "rs.t0", 0);
+    } else {
+        if (task_id == 1) {
+            scoreboard_set(p, "rs.t1", 0);
+        } else {
+            if (task_id == 2) {
+                scoreboard_set(p, "rs.t2", 0);
+            } else {
+                if (task_id == 3) {
+                    scoreboard_set(p, "rs.t3", 0);
+                } else {
+                    if (task_id == 4) {
+                        scoreboard_set(p, "rs.t4", 0);
+                    } else {
+                        if (task_id == 5) {
+                            scoreboard_set(p, "rs.t5", 0);
+                        } else {
+                            if (task_id == 6) {
+                                scoreboard_set(p, "rs.t6", 0);
+                            } else {
+                                scoreboard_set(p, "rs.t7", 0);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+
+/// Returns 1 if slot task_id is ready (counter reached 1 on last tick), 0 otherwise.
+/// Automatically clears the slot when ready.
+fn task_ready(p: selector, task_id: int) -> int {
+    let val: int = 0;
+    if (task_id == 0) {
+        val = scoreboard_get(p, "rs.t0");
+    } else {
+        if (task_id == 1) {
+            val = scoreboard_get(p, "rs.t1");
+        } else {
+            if (task_id == 2) {
+                val = scoreboard_get(p, "rs.t2");
+            } else {
+                if (task_id == 3) {
+                    val = scoreboard_get(p, "rs.t3");
+                } else {
+                    if (task_id == 4) {
+                        val = scoreboard_get(p, "rs.t4");
+                    } else {
+                        if (task_id == 5) {
+                            val = scoreboard_get(p, "rs.t5");
+                        } else {
+                            if (task_id == 6) {
+                                val = scoreboard_get(p, "rs.t6");
+                            } else {
+                                val = scoreboard_get(p, "rs.t7");
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    if (val == 1) {
+        task_cancel(p, task_id);
+        return 1;
+    }
+    return 0;
+}
+
+// ─── Global tasks (bound to #rs fake-player) ──────────────────────────────────
+
+/// Schedule global slot task_id (0..7) to fire after `delay` ticks.
+fn gtask_schedule(task_id: int, delay: int) {
+    if (task_id == 0) {
+        scoreboard_set("#rs", "rs.g0", delay);
+    } else {
+        if (task_id == 1) {
+            scoreboard_set("#rs", "rs.g1", delay);
+        } else {
+            if (task_id == 2) {
+                scoreboard_set("#rs", "rs.g2", delay);
+            } else {
+                if (task_id == 3) {
+                    scoreboard_set("#rs", "rs.g3", delay);
+                } else {
+                    if (task_id == 4) {
+                        scoreboard_set("#rs", "rs.g4", delay);
+                    } else {
+                        if (task_id == 5) {
+                            scoreboard_set("#rs", "rs.g5", delay);
+                        } else {
+                            if (task_id == 6) {
+                                scoreboard_set("#rs", "rs.g6", delay);
+                            } else {
+                                scoreboard_set("#rs", "rs.g7", delay);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+
+/// Cancel global slot task_id.
+fn gtask_cancel(task_id: int) {
+    if (task_id == 0) {
+        scoreboard_set("#rs", "rs.g0", 0);
+    } else {
+        if (task_id == 1) {
+            scoreboard_set("#rs", "rs.g1", 0);
+        } else {
+            if (task_id == 2) {
+                scoreboard_set("#rs", "rs.g2", 0);
+            } else {
+                if (task_id == 3) {
+                    scoreboard_set("#rs", "rs.g3", 0);
+                } else {
+                    if (task_id == 4) {
+                        scoreboard_set("#rs", "rs.g4", 0);
+                    } else {
+                        if (task_id == 5) {
+                            scoreboard_set("#rs", "rs.g5", 0);
+                        } else {
+                            if (task_id == 6) {
+                                scoreboard_set("#rs", "rs.g6", 0);
+                            } else {
+                                scoreboard_set("#rs", "rs.g7", 0);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+
+/// Returns 1 if global slot task_id is ready, 0 otherwise.
+/// Automatically clears the slot when ready.
+fn gtask_ready(task_id: int) -> int {
+    let val: int = 0;
+    if (task_id == 0) {
+        val = scoreboard_get("#rs", "rs.g0");
+    } else {
+        if (task_id == 1) {
+            val = scoreboard_get("#rs", "rs.g1");
+        } else {
+            if (task_id == 2) {
+                val = scoreboard_get("#rs", "rs.g2");
+            } else {
+                if (task_id == 3) {
+                    val = scoreboard_get("#rs", "rs.g3");
+                } else {
+                    if (task_id == 4) {
+                        val = scoreboard_get("#rs", "rs.g4");
+                    } else {
+                        if (task_id == 5) {
+                            val = scoreboard_get("#rs", "rs.g5");
+                        } else {
+                            if (task_id == 6) {
+                                val = scoreboard_get("#rs", "rs.g6");
+                            } else {
+                                val = scoreboard_get("#rs", "rs.g7");
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    if (val == 1) {
+        gtask_cancel(task_id);
+        return 1;
+    }
+    return 0;
+}
+
+// ─── Tick driver ──────────────────────────────────────────────────────────────
+
+/// Decrement all active per-player timers by 1.
+/// Call this inside your @tick function (executed as @a).
+fn scheduler_tick() {
+    // Per-player slots
+    raw("execute as @a run scoreboard players remove @s rs.t0 1");
+    raw("execute as @a[scores={rs.t0=..-1}] run scoreboard players set @s rs.t0 0");
+    raw("execute as @a run scoreboard players remove @s rs.t1 1");
+    raw("execute as @a[scores={rs.t1=..-1}] run scoreboard players set @s rs.t1 0");
+    raw("execute as @a run scoreboard players remove @s rs.t2 1");
+    raw("execute as @a[scores={rs.t2=..-1}] run scoreboard players set @s rs.t2 0");
+    raw("execute as @a run scoreboard players remove @s rs.t3 1");
+    raw("execute as @a[scores={rs.t3=..-1}] run scoreboard players set @s rs.t3 0");
+    raw("execute as @a run scoreboard players remove @s rs.t4 1");
+    raw("execute as @a[scores={rs.t4=..-1}] run scoreboard players set @s rs.t4 0");
+    raw("execute as @a run scoreboard players remove @s rs.t5 1");
+    raw("execute as @a[scores={rs.t5=..-1}] run scoreboard players set @s rs.t5 0");
+    raw("execute as @a run scoreboard players remove @s rs.t6 1");
+    raw("execute as @a[scores={rs.t6=..-1}] run scoreboard players set @s rs.t6 0");
+    raw("execute as @a run scoreboard players remove @s rs.t7 1");
+    raw("execute as @a[scores={rs.t7=..-1}] run scoreboard players set @s rs.t7 0");
+    // Global slots
+    raw("scoreboard players remove #rs rs.g0 1");
+    raw("execute if score #rs rs.g0 matches ..-1 run scoreboard players set #rs rs.g0 0");
+    raw("scoreboard players remove #rs rs.g1 1");
+    raw("execute if score #rs rs.g1 matches ..-1 run scoreboard players set #rs rs.g1 0");
+    raw("scoreboard players remove #rs rs.g2 1");
+    raw("execute if score #rs rs.g2 matches ..-1 run scoreboard players set #rs rs.g2 0");
+    raw("scoreboard players remove #rs rs.g3 1");
+    raw("execute if score #rs rs.g3 matches ..-1 run scoreboard players set #rs rs.g3 0");
+    raw("scoreboard players remove #rs rs.g4 1");
+    raw("execute if score #rs rs.g4 matches ..-1 run scoreboard players set #rs rs.g4 0");
+    raw("scoreboard players remove #rs rs.g5 1");
+    raw("execute if score #rs rs.g5 matches ..-1 run scoreboard players set #rs rs.g5 0");
+    raw("scoreboard players remove #rs rs.g6 1");
+    raw("execute if score #rs rs.g6 matches ..-1 run scoreboard players set #rs rs.g6 0");
+    raw("scoreboard players remove #rs rs.g7 1");
+    raw("execute if score #rs rs.g7 matches ..-1 run scoreboard players set #rs rs.g7 0");
+}

package/src/stdlib/signal.mcrs

@@ -110,3 +110,226 @@ fn weighted3(seed: int, w0: int, w1: int, w2: int): int {
     if (v < w0 + w1) { return 1; }
     return 2;
 }
+
+// ─── Gamma distribution ───────────────────────────────────────────────────────
+//
+// gamma_sample(shape_k, scale_theta, seed): Gamma(k, theta) × 10000
+// Method: sum of k independent Exponential(theta) samples.
+//   Exponential(theta) = -theta * ln(U)  where U ~ Uniform(0,1).
+// shape_k: integer shape parameter × 10000 (e.g. 10000 = k=1, 20000 = k=2)
+// scale_theta: scale parameter × 10000 (e.g. 10000 = theta=1.0)
+// seed: any integer seed
+// Returns: Gamma variate × 10000. Handles k = 1..5 via loop.
+// Requires: ln (stdlib/math), uniform_int (stdlib/signal)
+fn gamma_sample(shape_k: int, scale_theta: int, seed: int): int {
+    // Gamma(k, theta) = sum of k Exponential(theta) samples
+    // Exponential(theta) = -theta * ln(U), U ~ Uniform(0.1, 0.9999)
+    // ln expects ×10000 input; u in [1000,9999] = U in [0.1, 0.9999]
+    // Unrolled for k=1..5 (shape_k in ×10000: 10000..50000)
+    // Each term: e_i = scale_theta * (-ln(u_i)) / 10000
+    let u0: int = uniform_int(seed,     1000, 9999);
+    let e0: int = scale_theta * (0 - ln(u0)) / 10000;
+    if (shape_k <= 10000) { return e0; }
+    let u1: int = uniform_int(seed + 1, 1000, 9999);
+    let e1: int = scale_theta * (0 - ln(u1)) / 10000;
+    if (shape_k <= 20000) { return e0 + e1; }
+    let u2: int = uniform_int(seed + 2, 1000, 9999);
+    let e2: int = scale_theta * (0 - ln(u2)) / 10000;
+    if (shape_k <= 30000) { return e0 + e1 + e2; }
+    let u3: int = uniform_int(seed + 3, 1000, 9999);
+    let e3: int = scale_theta * (0 - ln(u3)) / 10000;
+    if (shape_k <= 40000) { return e0 + e1 + e2 + e3; }
+    let u4: int = uniform_int(seed + 4, 1000, 9999);
+    let e4: int = scale_theta * (0 - ln(u4)) / 10000;
+    return e0 + e1 + e2 + e3 + e4;
+}
+
+// ─── Poisson distribution ─────────────────────────────────────────────────────
+//
+// poisson_sample(lambda, seed): Poisson(lambda) count
+// Method: Knuth algorithm — count uniform products until product < e^(-lambda).
+// lambda: rate parameter × 10000 (e.g. 30000 = lambda=3.0)
+// seed: any integer seed
+// Returns: non-negative integer count (plain int, not ×10000).
+// Works well for lambda ≤ 20 (200000 in ×10000). Hard cap at 100 iterations.
+// Requires: exp_fx (stdlib/math), uniform_int (stdlib/signal)
+fn poisson_sample(lambda: int, seed: int): int {
+    let neg_lambda: int = 0 - lambda;
+    let L: int = exp_fx(neg_lambda);
+    let k: int = 0;
+    let p: int = 10000;
+    while (p >= L) {
+        let u: int = uniform_int(seed + k, 1, 10000);
+        p = p * u / 10000;
+        k = k + 1;
+        if (k >= 100) { p = 0; }
+    }
+    return k - 1;
+}
+
+// ─── Geometric distribution ───────────────────────────────────────────────────
+//
+// geometric_sample(p_success, seed): Geometric(p) — failures before first success
+// Method: floor(ln(U) / ln(1-p))
+// p_success: success probability × 10000 (e.g. 5000 = p=0.5)
+// seed: any integer seed
+// Returns: non-negative integer count of failures.
+// Requires: ln (stdlib/math), uniform_int (stdlib/signal)
+fn geometric_sample(p_success: int, seed: int): int {
+    let u: int = uniform_int(seed, 1, 9999);
+    let ln_u: int = ln(u);
+    let ln_1mp: int = ln(10000 - p_success);
+    // Both ln_u and ln_1mp are negative (u < 10000, 10000-p < 10000).
+    // ln_u / ln_1mp is positive and gives the geometric sample.
+    if (ln_1mp == 0) { return 0; }
+    return ln_u / ln_1mp;
+}
+
+// ─── Negative Binomial distribution ──────────────────────────────────────────
+//
+// negative_binomial_sample(r, p_success, seed): NegBin(r, p) — failures before r successes
+// Method: sum r independent Geometric(p) samples.
+// r: number of successes (plain integer, e.g. 1, 2, 3)
+// p_success: success probability × 10000 (e.g. 5000 = p=0.5)
+// seed: any integer seed
+// Returns: non-negative integer count of total failures.
+// Requires: geometric_sample
+fn negative_binomial_sample(r: int, p_success: int, seed: int): int {
+    let s: int = 0;
+    let i: int = 0;
+    while (i < r) {
+        s = s + geometric_sample(p_success, seed + i);
+        i = i + 1;
+    }
+    return s;
+}
+
+// ─── DFT helpers ──────────────────────────────────────────────────────────────
+//
+// _sin45(q): sin(q × 45°) × 10000, q = 0..7 (handles full circle in 45° steps)
+// Pure arithmetic — no NBT storage required. Works in MCRuntime for testing.
+fn _sin45(q: int): int {
+    let qi: int = q % 8;
+    if (qi < 0) { qi = qi + 8; }
+    if (qi == 0) { return 0; }
+    if (qi == 1) { return 7071; }
+    if (qi == 2) { return 10000; }
+    if (qi == 3) { return 7071; }
+    if (qi == 4) { return 0; }
+    if (qi == 5) { return -7071; }
+    if (qi == 6) { return -10000; }
+    return -7071;  // qi == 7
+}
+
+// _cos45(q): cos(q × 45°) × 10000
+fn _cos45(q: int): int {
+    return _sin45(q + 2);  // cos(x) = sin(x + 90°) = sin((q+2)×45°)
+}
+
+// ─── Discrete Fourier Transform (fixed-point, n ≤ 8) ─────────────────────────
+//
+// Computes DFT bin k of a real-valued signal with n samples.
+// All values use ×10000 scale.
+//
+// Angle convention: 360*k*j/n degrees — always a multiple of 45° for n ≤ 8.
+// Trig is handled by _sin45/_cos45 which take a 45°-step index.
+//
+// dft_real(s0..s7, n, k): real part of DFT bin k
+//   real[k] = (1/n) × Σ(j=0..n-1) samples[j] × cos(2π k j / n)
+//   Return value ×10000.
+//
+// To keep within int32: divide each term by 10000 before accumulating,
+// then divide the sum by n at the end.
+//
+// Note: passes samples as 8 explicit integers (s0..s7).
+//       Use s0..s(n-1); remaining args are ignored based on n.
+
+fn dft_real(s0: int, s1: int, s2: int, s3: int,
+            s4: int, s5: int, s6: int, s7: int,
+            n: int, k: int): int {
+    let acc: int = 0;
+    // j=0: angle = 0 → cos = 10000, term = s0 * 10000 / 10000 = s0
+    acc = acc + s0 * _cos45(0) / 10000;
+    if (n > 1) {
+        // j=1: angle_steps = 360*k*1/n / 45 = 8*k/n
+        let q1: int = 8 * k * 1 / n;
+        acc = acc + s1 * _cos45(q1) / 10000;
+    }
+    if (n > 2) {
+        let q2: int = 8 * k * 2 / n;
+        acc = acc + s2 * _cos45(q2) / 10000;
+    }
+    if (n > 3) {
+        let q3: int = 8 * k * 3 / n;
+        acc = acc + s3 * _cos45(q3) / 10000;
+    }
+    if (n > 4) {
+        let q4: int = 8 * k * 4 / n;
+        acc = acc + s4 * _cos45(q4) / 10000;
+    }
+    if (n > 5) {
+        let q5: int = 8 * k * 5 / n;
+        acc = acc + s5 * _cos45(q5) / 10000;
+    }
+    if (n > 6) {
+        let q6: int = 8 * k * 6 / n;
+        acc = acc + s6 * _cos45(q6) / 10000;
+    }
+    if (n > 7) {
+        let q7: int = 8 * k * 7 / n;
+        acc = acc + s7 * _cos45(q7) / 10000;
+    }
+    return acc / n;
+}
+
+// dft_imag(s0..s7, n, k): imaginary part of DFT bin k (negative sine convention)
+//   imag[k] = -(1/n) × Σ(j=0..n-1) samples[j] × sin(2π k j / n)
+fn dft_imag(s0: int, s1: int, s2: int, s3: int,
+            s4: int, s5: int, s6: int, s7: int,
+            n: int, k: int): int {
+    let acc: int = 0;
+    acc = acc + s0 * _sin45(0) / 10000;
+    if (n > 1) {
+        let q1: int = 8 * k * 1 / n;
+        acc = acc + s1 * _sin45(q1) / 10000;
+    }
+    if (n > 2) {
+        let q2: int = 8 * k * 2 / n;
+        acc = acc + s2 * _sin45(q2) / 10000;
+    }
+    if (n > 3) {
+        let q3: int = 8 * k * 3 / n;
+        acc = acc + s3 * _sin45(q3) / 10000;
+    }
+    if (n > 4) {
+        let q4: int = 8 * k * 4 / n;
+        acc = acc + s4 * _sin45(q4) / 10000;
+    }
+    if (n > 5) {
+        let q5: int = 8 * k * 5 / n;
+        acc = acc + s5 * _sin45(q5) / 10000;
+    }
+    if (n > 6) {
+        let q6: int = 8 * k * 6 / n;
+        acc = acc + s6 * _sin45(q6) / 10000;
+    }
+    if (n > 7) {
+        let q7: int = 8 * k * 7 / n;
+        acc = acc + s7 * _sin45(q7) / 10000;
+    }
+    // Negate (imaginary part uses -sin)
+    return 0 - (acc / n);
+}
+
+// dft_magnitude(s0..s7, n, k): magnitude of DFT bin k
+//   magnitude = sqrt_fx(real² + imag²)  where both real,imag are ×10000
+fn dft_magnitude(s0: int, s1: int, s2: int, s3: int,
+                 s4: int, s5: int, s6: int, s7: int,
+                 n: int, k: int): int {
+    let re: int = dft_real(s0, s1, s2, s3, s4, s5, s6, s7, n, k);
+    let im: int = dft_imag(s0, s1, s2, s3, s4, s5, s6, s7, n, k);
+    // re, im are ×10000; re²+im² in ×10000 units for sqrt_fx
+    let re2: int = re * re / 10000;
+    let im2: int = im * im / 10000;
+    return sqrt_fx(re2 + im2);
+}

package/src/stdlib/sort.mcrs

@@ -0,0 +1,194 @@
+// sort.mcrs — Sorting algorithms for RedScript datapacks.
+//
+// Algorithms:
+//   insertion_sort(arr, len)      — O(n²) ascending, best for n≤64
+//   insertion_sort_desc(arr, len) — O(n²) descending
+//   sort_merge(a, la, b, lb)      — merge two sorted int[] arrays into one
+//   merge_sort_coro(arr, n)       — O(n log n) bottom-up merge sort, tick-spread via @coroutine
+//
+// All functions operate on int[] via index writes (requires RedScript ≥ 2.4.0).
+//
+// Usage:
+//   let data: int[] = [30, 10, 50, 20, 40]
+//   insertion_sort(data, 5)    // data is now [10, 20, 30, 40, 50]
+//
+// Note: insertion_sort and insertion_sort_desc mutate in-place.
+// sort_merge creates and returns a new merged array.
+
+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
+fn insertion_sort(arr: int[], len: int) {
+    let i: int = 1
+    while (i < len) {
+        let key: int = arr[i]
+        let j: int = i - 1
+        let shifting: int = 1
+        while (shifting == 1) {
+            if (j >= 0) {
+                if (arr[j] > key) {
+                    arr[j + 1] = arr[j]
+                    j = j - 1
+                } else {
+                    shifting = 0
+                }
+            } else {
+                shifting = 0
+            }
+        }
+        arr[j + 1] = key
+        i = i + 1
+    }
+}
+
+// ─── Insertion sort (descending) ──────────────────────────────────────────────
+
+// insertion_sort_desc(arr, len): sort arr[0..len-1] descending in-place
+fn insertion_sort_desc(arr: int[], len: int) {
+    let i: int = 1
+    while (i < len) {
+        let key: int = arr[i]
+        let j: int = i - 1
+        let shifting: int = 1
+        while (shifting == 1) {
+            if (j >= 0) {
+                if (arr[j] < key) {
+                    arr[j + 1] = arr[j]
+                    j = j - 1
+                } else {
+                    shifting = 0
+                }
+            } else {
+                shifting = 0
+            }
+        }
+        arr[j + 1] = key
+        i = i + 1
+    }
+}
+
+// ─── 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
+fn sort_merge(a: int[], la: int, b: int[], lb: int): int[] {
+    let result: int[] = []
+    let i: int = 0
+    let j: int = 0
+    // merge loop
+    let merging: int = 1
+    while (merging == 1) {
+        if (i < la) {
+            if (j < lb) {
+                if (a[i] <= b[j]) {
+                    result.push(a[i])
+                    i = i + 1
+                } else {
+                    result.push(b[j])
+                    j = j + 1
+                }
+            } else {
+                // exhausted b, drain a
+                result.push(a[i])
+                i = i + 1
+            }
+        } else {
+            if (j < lb) {
+                // exhausted a, drain b
+                result.push(b[j])
+                j = j + 1
+            } else {
+                merging = 0
+            }
+        }
+    }
+    return result
+}
+
+// ─── 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]
+
+// @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.
+@coroutine(batch=1, onDone=merge_sort_noop)
+fn merge_sort_coro(arr: int[], n: int) {
+    let width: int = 1
+    // @coroutine(batch=1) yields here — one pass per tick
+    while (width < n) {
+        // One merge pass: process all adjacent run pairs of size `width`
+        let left: int = 0
+        while (left < n) {
+            // Clamp mid and right to n
+            let mid: int = left + width
+            if (mid > n) { mid = n }
+            let right: int = left + width * 2
+            if (right > n) { right = n }
+
+            // In-place merge of arr[left..mid) and arr[mid..right)
+            // via a temporary scratch array
+            if (mid < right) {
+                let tmp: int[] = []
+                let ia: int = left
+                let ib: int = mid
+                let merging: int = 1
+                while (merging == 1) {
+                    if (ia < mid) {
+                        if (ib < right) {
+                            if (arr[ia] <= arr[ib]) {
+                                tmp.push(arr[ia])
+                                ia = ia + 1
+                            } else {
+                                tmp.push(arr[ib])
+                                ib = ib + 1
+                            }
+                        } else {
+                            tmp.push(arr[ia])
+                            ia = ia + 1
+                        }
+                    } else {
+                        if (ib < right) {
+                            tmp.push(arr[ib])
+                            ib = ib + 1
+                        } else {
+                            merging = 0
+                        }
+                    }
+                }
+                // 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
+                }
+            }
+
+            left = left + width * 2
+        }
+        // Advance to next pass; @coroutine yields after this iteration
+        width = width * 2
+    }
+}
+
+// merge_sort_noop: default onDone callback — replace with your own handler
+fn merge_sort_noop() {}