redscript-mc 2.2.1 → 2.4.0

package/src/stdlib/random.mcrs

@@ -0,0 +1,67 @@
+// random.mcrs — Pseudo-random number generators for RedScript datapacks.
+//
+// LCG (Linear Congruential Generator):
+//   Simple, fast, sufficient for most game use-cases.
+//   Parameters: a=1664525, c=1013904223 (Numerical Recipes)
+//   Modulus: 2^32 via int32 overflow (free in MC scoreboard arithmetic).
+//
+// Usage:
+//   let seed: int = 12345;  // any non-zero starting value
+//   seed = next_lcg(seed);  // advance state
+//   let roll: int = random_range(seed, 0, 100);
+
+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.
+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.
+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.
+fn random_bool(seed: int): int {
+    let r: int = seed;
+    if (r < 0) { r = 0 - r; }
+    return r % 2;
+}
+
+// ─── PCG (Permuted Congruential Generator) ───────────────────────────────────
+// Better statistical quality than LCG — passes more randomness tests.
+// Requires stdlib/bits for bit_xor, bit_shr.
+//
+// PCG-XSH-RR (32-bit output from 64-bit state is approximated here with two
+// int32 words; this is a simplified PCG32 variant that fits MC scoreboard).
+//
+// Reference: https://www.pcg-random.org/
+//
+// 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.
+fn pcg_next_lo(state_lo: int): int {
+    return state_lo * 747796405 + 2891336453;
+}
+
+// pcg_next_hi(state_lo, state_hi): advance PCG state (high word).
+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).
+fn pcg_output(state_lo: int): int {
+    let xsh: int = state_lo;
+    // xsh = ((state >> 18) ^ state) >> 27   (simplified: use single xor-shift)
+    let shifted: int = xsh / 262144;  // >> 18
+    let xored: int = xsh / 32 + shifted;  // approximation of XSH
+    if (xored < 0) { xored = 0 - xored; }
+    return xored;
+}

package/src/stdlib/signal.mcrs

@@ -0,0 +1,112 @@
+// signal.mcrs — Statistical distributions and probability helpers.
+//
+// All functions use integer arithmetic with ×10000 scale where noted.
+// For game logic: loot tables, mob spawn weights, particle density, etc.
+//
+// Requires: import "stdlib/random" for seed-based RNG
+
+module library;
+
+// ─── Uniform distribution ────────────────────────────────────────────────────
+
+// uniform_int(seed, lo, hi): integer in [lo, hi] inclusive
+// Returns new seed for chaining: use the result as next seed input.
+fn uniform_int(seed: int, lo: int, hi: int): int {
+    let r: int = seed * 1664525 + 1013904223;
+    if (r < 0) { r = 0 - r; }
+    return lo + r % (hi - lo + 1);
+}
+
+// uniform_frac(seed): uniform fraction in [0, 10000] (×10000 scale)
+fn uniform_frac(seed: int): int {
+    let r: int = seed * 1664525 + 1013904223;
+    if (r < 0) { r = 0 - r; }
+    return r % 10001;
+}
+
+// ─── Normal (Gaussian) approximation ─────────────────────────────────────────
+//
+// Method: Sum of 12 uniform [0,1] random values → subtract 6 → scale.
+// Result approximates N(0,1). Good enough for game use.
+// (Box-Muller requires sqrt/ln; this is cheaper and sufficient.)
+//
+// normal_approx12(seed): approximate N(0, 1) × 10000, range ≈ [-60000, 60000]
+// Each call consumes the seed 12 times (chains internally).
+fn normal_approx12(seed: int): int {
+    let s: int = seed;
+    let sum: int = 0;
+    // 12 uniform samples [0, 10000]
+    let r: int = 0;
+    s = s * 1664525 + 1013904223; r = s; if (r < 0) { r = 0 - r; } sum = sum + r % 10001;
+    s = s * 1664525 + 1013904223; r = s; if (r < 0) { r = 0 - r; } sum = sum + r % 10001;
+    s = s * 1664525 + 1013904223; r = s; if (r < 0) { r = 0 - r; } sum = sum + r % 10001;
+    s = s * 1664525 + 1013904223; r = s; if (r < 0) { r = 0 - r; } sum = sum + r % 10001;
+    s = s * 1664525 + 1013904223; r = s; if (r < 0) { r = 0 - r; } sum = sum + r % 10001;
+    s = s * 1664525 + 1013904223; r = s; if (r < 0) { r = 0 - r; } sum = sum + r % 10001;
+    s = s * 1664525 + 1013904223; r = s; if (r < 0) { r = 0 - r; } sum = sum + r % 10001;
+    s = s * 1664525 + 1013904223; r = s; if (r < 0) { r = 0 - r; } sum = sum + r % 10001;
+    s = s * 1664525 + 1013904223; r = s; if (r < 0) { r = 0 - r; } sum = sum + r % 10001;
+    s = s * 1664525 + 1013904223; r = s; if (r < 0) { r = 0 - r; } sum = sum + r % 10001;
+    s = s * 1664525 + 1013904223; r = s; if (r < 0) { r = 0 - r; } sum = sum + r % 10001;
+    s = s * 1664525 + 1013904223; r = s; if (r < 0) { r = 0 - r; } sum = sum + r % 10001;
+    // sum in [0, 120000], mean = 60000, σ ≈ 10000
+    return sum - 60000;
+}
+
+// ─── Exponential distribution ─────────────────────────────────────────────────
+//
+// Method: -ln(U) / λ where U is uniform [0,1].
+// Approximation: use ln from stdlib/math.
+//
+// exp_dist_approx(seed, lambda_fx): exponential variate × 10000
+// lambda_fx: rate parameter × 10000 (e.g. 10000 = rate 1.0)
+// Returns value in [0, ∞) × 10000, but caps at 100000 (10.0) for MC sanity.
+// Note: requires import "stdlib/math" for ln function.
+fn exp_dist_approx(seed: int, lambda_fx: int): int {
+    let r: int = seed * 1664525 + 1013904223;
+    if (r < 0) { r = 0 - r; }
+    let u: int = 100 + r % 9901;  // uniform in [100, 10000] (avoid ln(0))
+    // -ln(u/10000) × 10000 / lambda_fx
+    // ln(u) where u is ×10000 → use existing ln(u) which returns ×10000
+    // -ln(u/10000) = -(ln(u) - ln(10000)) = ln(10000) - ln(u)
+    // ln(10000) × 10000 ≈ 92103
+    let ln_u: int = ln(u);    // requires stdlib/math
+    let neg_ln: int = 92103 - ln_u;
+    if (neg_ln < 0) { neg_ln = 0; }
+    let result: int = neg_ln * 10000 / lambda_fx;
+    if (result > 100000) { result = 100000; }
+    return result;
+}
+
+// ─── Bernoulli trial ──────────────────────────────────────────────────────────
+
+// bernoulli(seed, p_fx): 1 with probability p/10000, else 0.
+// p_fx: probability × 10000 (e.g. 5000 = 50%, 1000 = 10%)
+fn bernoulli(seed: int, p_fx: int): int {
+    let r: int = seed * 1664525 + 1013904223;
+    if (r < 0) { r = 0 - r; }
+    if (r % 10000 < p_fx) { return 1; }
+    return 0;
+}
+
+// ─── Weighted choice ──────────────────────────────────────────────────────────
+
+// weighted2(seed, w0, w1): choose 0 or 1 with weights w0, w1
+fn weighted2(seed: int, w0: int, w1: int): int {
+    let total: int = w0 + w1;
+    let r: int = seed * 1664525 + 1013904223;
+    if (r < 0) { r = 0 - r; }
+    if (r % total < w0) { return 0; }
+    return 1;
+}
+
+// weighted3(seed, w0, w1, w2): choose 0, 1, or 2 with given weights
+fn weighted3(seed: int, w0: int, w1: int, w2: int): int {
+    let total: int = w0 + w1 + w2;
+    let r: int = seed * 1664525 + 1013904223;
+    if (r < 0) { r = 0 - r; }
+    let v: int = r % total;
+    if (v < w0) { return 0; }
+    if (v < w0 + w1) { return 1; }
+    return 2;
+}

package/src/stdlib/timer.mcrs

@@ -75,3 +75,35 @@ impl Timer {
         }
     }
 }
+
+// ─── Tick-based stopwatch ─────────────────────────────────────────────────────
+
+// tick_to_seconds(ticks): convert MC ticks to seconds (20 ticks = 1 second)
+fn tick_to_seconds(ticks: int): int {
+    return ticks / 20;
+}
+
+// tick_to_ms(ticks): convert ticks to milliseconds
+fn tick_to_ms(ticks: int): int {
+    return ticks * 50;
+}
+
+// seconds_to_ticks(s): convert seconds to ticks
+fn seconds_to_ticks(s: int): int {
+    return s * 20;
+}
+
+// format_time_s(ticks): ticks → seconds component (mod 60)
+fn format_time_s(ticks: int): int {
+    return (ticks / 20) % 60;
+}
+
+// format_time_m(ticks): ticks → minutes component
+fn format_time_m(ticks: int): int {
+    return (ticks / 1200) % 60;
+}
+
+// format_time_h(ticks): ticks → hours component
+fn format_time_h(ticks: int): int {
+    return ticks / 72000;
+}

package/src/stdlib/vec.mcrs

@@ -244,3 +244,30 @@ fn chebyshev3d(x1: int, y1: int, z1: int, x2: int, y2: int, z2: int) -> int {
     if (dz > m) { m = dz; }
     return m;
 }
+
+// ─── 2D vector arithmetic ─────────────────────────────────────────────────────
+
+// add2d / sub2d / scale2d: component-wise ops. Return x or y component.
+fn add2d_x(ax: int, bx: int): int { return ax + bx; }
+fn add2d_y(ay: int, by: int): int { return ay + by; }
+fn sub2d_x(ax: int, bx: int): int { return ax - bx; }
+fn sub2d_y(ay: int, by: int): int { return ay - by; }
+fn scale2d_x(x: int, s: int): int { return x * s / 1000; }
+fn scale2d_y(y: int, s: int): int { return y * s / 1000; }
+fn neg2d_x(x: int): int { return 0 - x; }
+fn neg2d_y(y: int): int { return 0 - y; }
+
+// ─── 3D vector arithmetic ─────────────────────────────────────────────────────
+
+fn add3d_x(ax: int, bx: int): int { return ax + bx; }
+fn add3d_y(ay: int, by: int): int { return ay + by; }
+fn add3d_z(az: int, bz: int): int { return az + bz; }
+fn sub3d_x(ax: int, bx: int): int { return ax - bx; }
+fn sub3d_y(ay: int, by: int): int { return ay - by; }
+fn sub3d_z(az: int, bz: int): int { return az - bz; }
+fn scale3d_x(x: int, s: int): int { return x * s / 1000; }
+fn scale3d_y(y: int, s: int): int { return y * s / 1000; }
+fn scale3d_z(z: int, s: int): int { return z * s / 1000; }
+fn neg3d_x(x: int): int { return 0 - x; }
+fn neg3d_y(y: int): int { return 0 - y; }
+fn neg3d_z(z: int): int { return 0 - z; }

package/src/tuner/adapters/ln-polynomial.ts

@@ -0,0 +1,147 @@
+/**
+ * ln(x) polynomial approximation adapter — atanh series form.
+ *
+ * Algorithm:
+ *   Input x: fixed-point integer (×10000), e.g. 10000 = 1.0
+ *   1. Range reduction: find k s.t. xr ∈ [10000, 20000)
+ *   2. s = (xr - 10000) * 10000 / (xr + 10000)   →  s ∈ [0, 3333]
+ *   3. ln(xr/10000) ≈ A1*s/SCALE + A3*s³/SCALE² + A5*s⁵/SCALE³
+ *      (coefficients absorb the factor of 2; theoretical: A1=20000, A3=6667, A5=4000)
+ *   4. ln(x/10000) = k * LN2 + ln(xr/10000)
+ *
+ * Intermediate overflow analysis (s ≤ 3333, SCALE = 10000):
+ *   s²    = s*s    ≤ 11M   — fits int32 (max ~2.1B)
+ *   s2    = s²/SCALE ≤ 1111
+ *   s3    = s*s2   ≤ 3.7M  — fits int32
+ *   s5    = s3*s2  ≤ 4.1M  — fits int32
+ *   A1*s  ≤ 22000*3333 ≤ 73M — fits int32
+ *   A3*s3 ≤ 7000*3703  ≤ 26M — fits int32
+ *   A5*s5 ≤ 5000*4115  ≤ 21M — fits int32
+ */
+
+import { TunerAdapter, ParamSpec, ResultMeta } from '../types';
+import { i32 } from '../simulator';
+
+const SCALE = 10000;
+const LN2_SCALED = 6931; // ln(2) * 10000
+
+export const defaultParams: Record<string, number> = {
+  A1: 20000,
+  A3: 6667,
+  A5: 4000,
+};
+
+export const lnPolynomialAdapter: TunerAdapter = {
+  name: 'ln-polynomial',
+  description: 'ln(x) atanh series approximation using fixed-point int32 arithmetic',
+
+  params: [
+    { name: 'A1', range: [18000, 22000], integer: true } as ParamSpec,
+    { name: 'A3', range: [5000, 9000],   integer: true } as ParamSpec,
+    { name: 'A5', range: [2000, 6000],   integer: true } as ParamSpec,
+  ],
+
+  simulate(input: number, params: Record<string, number>): number {
+    const A1 = i32(params['A1']);
+    const A3 = i32(params['A3']);
+    const A5 = i32(params['A5']);
+
+    let x = i32(input);
+    if (x <= 0) return -2147483648;
+
+    // Step 1: range reduction to [10000, 20000)
+    let k = 0;
+    while (x < 10000)  { x = i32(x * 2); k--; }
+    while (x >= 20000) { x = i32(x / 2); k++; }
+
+    // Step 2: s = (xr - SCALE) * SCALE / (xr + SCALE)
+    const num = i32(i32(x - SCALE) * SCALE);
+    const den = i32(x + SCALE);
+    if (den === 0) return Infinity as unknown as number;
+    const s = i32(num / den);  // s ∈ [0, 3333]
+
+    // Step 3: atanh series  (overflow-safe, each power divided by SCALE)
+    const s2 = i32(i32(s * s)  / SCALE);          // s²/SCALE    ∈ [0, 1111]
+    const s3 = i32(i32(s * s2) / SCALE);          // s³/SCALE²   ∈ [0, 370]
+    const s5 = i32(i32(s3 * s2) / SCALE);         // s⁵/SCALE⁴   ∈ [0, 41]
+
+    const lnxr = i32(
+      i32(A1 * s  / SCALE) +
+      i32(A3 * s3 / SCALE) +
+      i32(A5 * s5 / SCALE)
+    );
+
+    // Step 4: ln(x) = k*ln(2) + ln(xr)
+    return i32(i32(k * LN2_SCALED) + lnxr);
+  },
+
+  reference(input: number): number {
+    if (input <= 0) return -Infinity;
+    return Math.log(input / SCALE) * SCALE;
+  },
+
+  sampleInputs(): number[] {
+    const inputs: number[] = [];
+    // logarithmic sampling from 0.01 to 100 (×10000: 100 to 1_000_000)
+    const logMin = Math.log10(100);
+    const logMax = Math.log10(1_000_000);
+    const steps = 200;
+    for (let i = 0; i <= steps; i++) {
+      const v = logMin + (i / steps) * (logMax - logMin);
+      inputs.push(Math.round(Math.pow(10, v)));
+    }
+    return inputs;
+  },
+
+  generateCode(params: Record<string, number>, meta: ResultMeta): string {
+    const A1 = Math.round(params['A1']);
+    const A3 = Math.round(params['A3']);
+    const A5 = Math.round(params['A5']);
+    return `// AUTO-GENERATED by redscript tune — DO NOT EDIT
+// Adapter: ln-polynomial | Date: ${meta.tuneDate}
+// max_error: ${meta.maxError.toFixed(6)} | mae: ${meta.mae.toFixed(6)} | estimated_cmds: ${meta.estimatedCmds}
+// Run \`redscript tune --adapter ln-polynomial\` to regenerate
+//
+// atanh series coefficients (×10000 scale):
+//   A1 = ${A1}  (theoretical 2×10000 = 20000)
+//   A3 = ${A3}  (theoretical 2/3×10000 = 6667)
+//   A5 = ${A5}  (theoretical 2/5×10000 = 4000)
+
+fn ln(x: int): int {
+    // Input x: fixed-point ×10000; returns ln(x/10000)×10000
+    // Valid range: x ∈ [100, 1000000]  (0.01 ~ 100.0)
+    // max_error: ${meta.maxError.toFixed(6)} (in ×10000 units, i.e. ${(meta.maxError / SCALE).toFixed(8)} in real units)
+
+    let scale: int = ${SCALE};
+    let ln2: int = ${LN2_SCALED};
+    let A1: int = ${A1};
+    let A3: int = ${A3};
+    let A5: int = ${A5};
+
+    // Step 1: range reduction — bring x into [scale, 2*scale)
+    let xr: int = x;
+    let k: int = 0;
+    while (xr < scale) {
+        xr = xr * 2;
+        k = k - 1;
+    }
+    while (xr >= scale * 2) {
+        xr = xr / 2;
+        k = k + 1;
+    }
+
+    // Step 2: s = (xr - scale) * scale / (xr + scale)
+    let s: int = (xr - scale) * scale / (xr + scale);
+
+    // Step 3: atanh series ln(xr/scale) ≈ A1*s + A3*s³ + A5*s⁵ (all /scale)
+    let s2: int = s * s / scale;
+    let s3: int = s * s2;
+    let s5: int = s3 * s2;
+    let lnxr: int = A1 * s / scale + A3 * s3 / scale + A5 * s5 / scale;
+
+    // Step 4: ln(x) = k*ln(2) + ln(xr/scale)
+    return k * ln2 + lnxr;
+}
+`;
+  },
+};

package/src/tuner/adapters/sqrt-newton.ts

@@ -0,0 +1,135 @@
+/**
+ * sqrt(x) Newton's method adapter — fixed-point ×10000 scale.
+ *
+ * Algorithm:
+ *   Input x: fixed-point integer (×10000), e.g. 10000 = 1.0
+ *   Target: return floor(sqrt(x/10000) * 10000)
+ *
+ *   1. If x <= 0, return 0
+ *   2. Initial guess: g = x >> INIT_SHIFT  (default: x/2)
+ *   3. Newton iteration: g = (g + x * 10000 / g) / 2, repeated N times
+ *      Overflow-safe: x * 10000 / g  →  (x * 100) / (g / 100)
+ *   4. Return g
+ *
+ * Valid range: x ∈ [1, 1_000_000]  (real range 0.0001 to 100.0)
+ *   Larger x needs more iterations; beyond 1M, convergence is not guaranteed
+ *   within N=12 iterations from an x/2 initial guess.
+ *
+ * Overflow analysis (x ≤ 1_000_000, SCALE = 10000):
+ *   x * 100 ≤ 100_000_000 — fits int32 (max ~2.1B) ✓
+ *   g / 100 is never 0 for g ≥ 100 (guard included) ✓
+ *
+ * Parameters:
+ *   N:          iteration count, range [4, 12], integer
+ *   INIT_SHIFT: initial guess right shift, range [0, 3], integer (1 → x/2)
+ */
+
+import { TunerAdapter, ParamSpec, ResultMeta } from '../types';
+import { i32 } from '../simulator';
+
+const SCALE = 10000;
+
+export const defaultParams: Record<string, number> = {
+  N: 8,
+  INIT_SHIFT: 1,
+};
+
+export const sqrtNewtonAdapter: TunerAdapter = {
+  name: 'sqrt-newton',
+  description: 'sqrt(x) Newton iteration using fixed-point int32 arithmetic (×10000 scale)',
+
+  params: [
+    { name: 'N',          range: [4, 12], integer: true } as ParamSpec,
+    { name: 'INIT_SHIFT', range: [0, 3],  integer: true } as ParamSpec,
+  ],
+
+  simulate(input: number, params: Record<string, number>): number {
+    const N          = Math.round(params['N']!);
+    const INIT_SHIFT = Math.round(params['INIT_SHIFT']!);
+
+    let x = i32(input);
+    if (x <= 0) return 0;
+
+    // Initial guess: x >> INIT_SHIFT
+    let g = i32(x >> INIT_SHIFT);
+    if (g <= 0) g = 1; // guard against zero/negative guess
+
+    // Newton iterations: g = (g + x * 10000 / g) / 2
+    // Overflow-safe for x ≤ 1_000_000: split x*10000/g as (x*100)/(g/100)
+    for (let iter = 0; iter < N; iter++) {
+      const gDiv = i32(g / 100);
+      if (gDiv <= 0) break; // guard: g is too small, stop
+      const xdivg = i32(i32(x * 100) / gDiv); // ≈ x * 10000 / g
+      g = i32(i32(g + xdivg) / 2);
+      if (g <= 0) { g = 1; break; }
+    }
+
+    return g;
+  },
+
+  reference(input: number): number {
+    if (input <= 0) return 0;
+    return Math.floor(Math.sqrt(input / SCALE) * SCALE);
+  },
+
+  sampleInputs(): number[] {
+    const inputs: number[] = [];
+
+    // Logarithmic sampling from 0.01 to 100.0 (×10000: 100 to 1_000_000)
+    // Lower bound 100 avoids g/100=0 in overflow-safe Newton step.
+    const logMin = Math.log10(100);
+    const logMax = Math.log10(1_000_000);
+    const steps = 200;
+    for (let i = 0; i <= steps; i++) {
+      const v = logMin + (i / steps) * (logMax - logMin);
+      const x = Math.round(Math.pow(10, v));
+      inputs.push(x);
+    }
+
+    // Exact perfect squares (k=1..10 → x up to 100 * 10000 = 1_000_000)
+    for (let k = 1; k <= 10; k++) {
+      inputs.push(k * k * SCALE); // sqrt should be exactly k * SCALE
+    }
+
+    return inputs;
+  },
+
+  generateCode(params: Record<string, number>, meta: ResultMeta): string {
+    const N          = Math.round(params['N']!);
+    const INIT_SHIFT = Math.round(params['INIT_SHIFT']!);
+
+    const iters = Array.from({ length: N }, (_, i) =>
+      `    g = (g + x * 100 / (g / 100)) / 2;  // iteration ${i + 1}`
+    ).join('\n');
+
+    return `// AUTO-GENERATED by redscript tune — DO NOT EDIT
+// Adapter: sqrt-newton | Date: ${meta.tuneDate}
+// max_error: ${meta.maxError.toFixed(6)} | mae: ${meta.mae.toFixed(6)} | estimated_cmds: ${meta.estimatedCmds}
+// Run \`redscript tune --adapter sqrt-newton\` to regenerate
+//
+// Parameters:
+//   N          = ${N}   (Newton iteration count)
+//   INIT_SHIFT = ${INIT_SHIFT}   (initial guess = x >> ${INIT_SHIFT}, i.e. x / ${1 << INIT_SHIFT})
+
+fn sqrt_fx(x: int): int {
+    // Input x: fixed-point ×10000, returns floor(sqrt(x/10000)*10000)
+    // Valid range: x ∈ [0, 1000000]  (real range 0.0 to 100.0)
+    // max_error: ${meta.maxError.toFixed(6)} (in ×10000 units)
+    //
+    // Overflow-safe: x*10000/g computed as (x*100)/(g/100), valid for x ≤ 1_000_000
+
+    if (x <= 0) { return 0; }
+
+    // Initial guess: x / ${1 << INIT_SHIFT}
+    let g: int = x / ${1 << INIT_SHIFT};
+    if (g <= 0) { g = 1; }
+
+    // Newton iterations: g = (g + x * 10000 / g) / 2
+    // Split to avoid overflow: (x * 100) / (g / 100) ≈ x * 10000 / g
+${iters}
+
+    return g;
+}
+`;
+  },
+};

package/src/tuner/cli.ts

@@ -0,0 +1,158 @@
+/**
+ * CLI entry point for `redscript tune`.
+ * Usage: redscript tune --adapter <name> [--budget N] [--out path]
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { search, searchSA } from './engine';
+import { lnPolynomialAdapter } from './adapters/ln-polynomial';
+import { sqrtNewtonAdapter } from './adapters/sqrt-newton';
+import { TunerAdapter, ResultMeta } from './types';
+
+const ADAPTERS: Record<string, TunerAdapter> = {
+  'ln-polynomial': lnPolynomialAdapter,
+  'sqrt-newton':   sqrtNewtonAdapter,
+};
+
+function printUsage(): void {
+  console.log(`Usage: redscript tune --adapter <name> [--budget N] [--out path]
+
+Available adapters:
+${Object.entries(ADAPTERS)
+  .map(([name, a]) => `  ${name.padEnd(20)} ${a.description}`)
+  .join('\n')}
+
+Options:
+  --adapter <name>   Adapter to use (required)
+  --budget <N>       Max optimizer iterations (default: 10000)
+  --out <path>       Output .mcrs file path (optional)
+`);
+}
+
+function parseArgs(args: string[]): {
+  adapter?: string;
+  budget: number;
+  out?: string;
+  strategy: 'nm' | 'sa';
+} {
+  const result: { adapter?: string; budget: number; out?: string; strategy: 'nm' | 'sa' } = { budget: 10000, strategy: 'nm' };
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--adapter' && args[i + 1]) {
+      result.adapter = args[++i] as string;
+    } else if (args[i] === '--budget' && args[i + 1]) {
+      result.budget = parseInt(args[++i]!, 10);
+    } else if (args[i] === '--out' && args[i + 1]) {
+      result.out = args[++i] as string;
+    } else if (args[i] === '--strategy' && args[i + 1]) {
+      const s = args[++i];
+      if (s === 'nm' || s === 'sa') result.strategy = s;
+    }
+  }
+
+  return result;
+}
+
+function renderProgressBar(fraction: number, width = 30): string {
+  const filled = Math.round(fraction * width);
+  const bar = '█'.repeat(filled) + '░'.repeat(width - filled);
+  return `[${bar}]`;
+}
+
+async function main(): Promise<void> {
+  // Skip 'node', 'ts-node', 'cli.ts' etc from argv
+  const rawArgs = process.argv.slice(2);
+
+  // Support `redscript tune` prefix (first arg might be 'tune')
+  const args = rawArgs[0] === 'tune' ? rawArgs.slice(1) : rawArgs;
+
+  if (args.includes('--help') || args.includes('-h') || args.length === 0) {
+    printUsage();
+    process.exit(0);
+  }
+
+  const { adapter: adapterName, budget, out, strategy } = parseArgs(args);
+
+  if (!adapterName) {
+    console.error('Error: --adapter is required');
+    printUsage();
+    process.exit(1);
+  }
+
+  const adapter = ADAPTERS[adapterName];
+  if (!adapter) {
+    console.error(`Error: unknown adapter "${adapterName}"`);
+    console.error(`Available: ${Object.keys(ADAPTERS).join(', ')}`);
+    process.exit(1);
+  }
+
+  console.log(`\nredscript tune — ${adapter.name}`);
+  console.log(`Description: ${adapter.description}`);
+  console.log(`Strategy: ${strategy === 'sa' ? 'Simulated Annealing' : 'Nelder-Mead'}`);
+  console.log(`Budget: ${budget} iterations`);
+  console.log(`Parameters: ${adapter.params.map(p => p.name).join(', ')}\n`);
+
+  let lastProgress = 0;
+  const startTime = Date.now();
+
+  const searchFn = strategy === 'sa' ? searchSA : search;
+  const result = searchFn(adapter, budget, (iteration, bestError) => {
+    const fraction = iteration / budget;
+    const bar = renderProgressBar(fraction);
+    const errorStr = isFinite(bestError) ? bestError.toFixed(6) : 'Inf';
+    process.stdout.write(
+      `\r  ${bar} ${(fraction * 100).toFixed(1)}%  iter=${iteration}  best_max_error=${errorStr}   `
+    );
+    lastProgress = iteration;
+  });
+
+  const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+  process.stdout.write('\n');
+
+  console.log(`\n${'─'.repeat(60)}`);
+  console.log(`Optimization complete in ${elapsed}s`);
+  console.log(`Budget used: ${result.budgetUsed}/${budget} iterations`);
+  console.log(`\nResults:`);
+  console.log(`  max_error : ${result.maxError.toFixed(8)}`);
+  console.log(`  mae       : ${result.mae.toFixed(8)}`);
+  console.log(`  rmse      : ${result.rmse.toFixed(8)}`);
+  console.log(`\nBest parameters:`);
+  for (const [k, v] of Object.entries(result.params)) {
+    console.log(`  ${k.padEnd(12)} = ${v}`);
+  }
+
+  // Estimate command count (rough: ~4 cmds per param + 10 overhead)
+  const estimatedCmds = adapter.params.length * 4 + 15;
+
+  const meta: ResultMeta = {
+    maxError: result.maxError,
+    mae: result.mae,
+    rmse: result.rmse,
+    estimatedCmds,
+    tuneDate: new Date().toISOString().split('T')[0],
+    budgetUsed: result.budgetUsed,
+  };
+
+  const code = adapter.generateCode(result.params, meta);
+
+  if (out) {
+    const outPath = path.resolve(out);
+    const dir = path.dirname(outPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(outPath, code, 'utf8');
+    console.log(`\nWrote: ${outPath}`);
+  } else {
+    console.log(`\n${'─'.repeat(60)}`);
+    console.log('Generated code:');
+    console.log('─'.repeat(60));
+    console.log(code);
+  }
+}
+
+main().catch(err => {
+  console.error(err);
+  process.exit(1);
+});