redscript-mc 2.1.1 → 2.3.0

package/src/tuner/engine.ts

@@ -0,0 +1,272 @@
+/**
+ * Nelder-Mead simplex optimization engine for hyperparameter tuning.
+ * Suitable for continuous parameter spaces without gradient information.
+ * Supports mixed-integer parameters.
+ */
+
+import { TunerAdapter, SearchResult, ParamSpec } from './types';
+import { evaluate } from './metrics';
+
+export type ProgressCallback = (iteration: number, bestError: number) => void;
+
+interface SimplexPoint {
+  coords: number[];
+  score: number;
+}
+
+/**
+ * Apply integer constraints to parameters.
+ */
+function applyIntegerConstraints(
+  coords: number[],
+  specs: ParamSpec[]
+): number[] {
+  return coords.map((v, i) => {
+    const spec = specs[i];
+    // Clamp to range
+    const clamped = Math.max(spec.range[0], Math.min(spec.range[1], v));
+    return spec.integer ? Math.round(clamped) : clamped;
+  });
+}
+
+/**
+ * Convert coordinate array to params record.
+ */
+function coordsToParams(
+  coords: number[],
+  specs: ParamSpec[]
+): Record<string, number> {
+  const params: Record<string, number> = {};
+  for (let i = 0; i < specs.length; i++) {
+    params[specs[i].name] = coords[i];
+  }
+  return params;
+}
+
+/**
+ * Evaluate a point using the adapter.
+ */
+function scorePoint(
+  coords: number[],
+  specs: ParamSpec[],
+  adapter: TunerAdapter
+): number {
+  const constrained = applyIntegerConstraints(coords, specs);
+  const params = coordsToParams(constrained, specs);
+  const metrics = evaluate(adapter, params);
+  return metrics.maxError;
+}
+
+/**
+ * Run Nelder-Mead optimization.
+ */
+export function search(
+  adapter: TunerAdapter,
+  budget: number = 10000,
+  onProgress?: ProgressCallback
+): SearchResult {
+  const specs = adapter.params;
+  const n = specs.length;
+
+  if (n === 0) {
+    // No params to optimize
+    const params = coordsToParams([], specs);
+    const metrics = evaluate(adapter, params);
+    return {
+      params,
+      maxError: metrics.maxError,
+      mae: metrics.mae,
+      rmse: metrics.rmse,
+      budgetUsed: 0,
+    };
+  }
+
+  // Nelder-Mead parameters
+  const alpha = 1.0; // reflection
+  const gamma = 2.0; // expansion
+  const rho = 0.5; // contraction
+  const sigma = 0.5; // shrink
+
+  // Initialize simplex with n+1 points
+  const simplex: SimplexPoint[] = [];
+
+  // Start point: midpoint of each parameter range
+  const startCoords = specs.map(s => (s.range[0] + s.range[1]) / 2);
+  simplex.push({
+    coords: startCoords,
+    score: scorePoint(startCoords, specs, adapter),
+  });
+
+  // Generate remaining n points by perturbing each dimension
+  for (let i = 0; i < n; i++) {
+    const coords = [...startCoords];
+    const span = specs[i].range[1] - specs[i].range[0];
+    // Perturb by 20% of the range
+    coords[i] = startCoords[i] + span * 0.2;
+    simplex.push({
+      coords,
+      score: scorePoint(coords, specs, adapter),
+    });
+  }
+
+  let iteration = 0;
+
+  while (iteration < budget) {
+    // Sort simplex by score (ascending = better)
+    simplex.sort((a, b) => a.score - b.score);
+
+    const best = simplex[0];
+    const worst = simplex[n];
+    const secondWorst = simplex[n - 1];
+
+    if (onProgress && iteration % 100 === 0) {
+      onProgress(iteration, best.score);
+    }
+
+    // Check convergence: if all scores are the same, we're stuck
+    if (
+      simplex[n].score - simplex[0].score < 1e-15 &&
+      iteration > 100
+    ) {
+      break;
+    }
+
+    // Compute centroid of all but worst
+    const centroid = new Array(n).fill(0);
+    for (let i = 0; i < n; i++) {
+      for (let j = 0; j < n; j++) {
+        centroid[j] += simplex[i].coords[j] / n;
+      }
+    }
+
+    // Reflection
+    const reflected = centroid.map(
+      (c, j) => c + alpha * (c - worst.coords[j])
+    );
+    const reflectedScore = scorePoint(reflected, specs, adapter);
+    iteration++;
+
+    if (reflectedScore < best.score) {
+      // Expansion
+      const expanded = centroid.map(
+        (c, j) => c + gamma * (reflected[j] - c)
+      );
+      const expandedScore = scorePoint(expanded, specs, adapter);
+      iteration++;
+
+      if (expandedScore < reflectedScore) {
+        simplex[n] = { coords: expanded, score: expandedScore };
+      } else {
+        simplex[n] = { coords: reflected, score: reflectedScore };
+      }
+    } else if (reflectedScore < secondWorst.score) {
+      simplex[n] = { coords: reflected, score: reflectedScore };
+    } else {
+      // Contraction
+      const useReflected = reflectedScore < worst.score;
+      const contractionBase = useReflected ? reflected : worst.coords;
+      const contracted = centroid.map(
+        (c, j) => c + rho * (contractionBase[j] - c)
+      );
+      const contractedScore = scorePoint(contracted, specs, adapter);
+      iteration++;
+
+      if (contractedScore < (useReflected ? reflectedScore : worst.score)) {
+        simplex[n] = { coords: contracted, score: contractedScore };
+      } else {
+        // Shrink
+        for (let i = 1; i <= n; i++) {
+          simplex[i].coords = simplex[0].coords.map(
+            (c, j) => c + sigma * (simplex[i].coords[j] - c)
+          );
+          simplex[i].score = scorePoint(simplex[i].coords, specs, adapter);
+          iteration++;
+        }
+      }
+    }
+  }
+
+  // Sort final simplex
+  simplex.sort((a, b) => a.score - b.score);
+  const bestCoords = applyIntegerConstraints(simplex[0].coords, specs);
+  const bestParams = coordsToParams(bestCoords, specs);
+  const finalMetrics = evaluate(adapter, bestParams);
+
+  return {
+    params: bestParams,
+    maxError: finalMetrics.maxError,
+    mae: finalMetrics.mae,
+    rmse: finalMetrics.rmse,
+    budgetUsed: iteration,
+  };
+}
+
+/**
+ * Simulated Annealing search strategy.
+ * More robust than Nelder-Mead for integer parameters and multimodal objectives.
+ * Uses 3 independent restarts, taking the global best.
+ */
+export function searchSA(
+  adapter: TunerAdapter,
+  budget: number,
+  onProgress?: ProgressCallback,
+): SearchResult {
+  const RESTARTS = 3;
+  const budgetPerRun = Math.floor(budget / RESTARTS);
+  let globalBest: { params: Record<string, number>; error: number } | null = null;
+
+  for (let r = 0; r < RESTARTS; r++) {
+    // Random initialisation within param ranges
+    let current: Record<string, number> = {};
+    for (const p of adapter.params) {
+      current[p.name] = p.range[0] + Math.random() * (p.range[1] - p.range[0]);
+      if (p.integer) current[p.name] = Math.round(current[p.name]);
+    }
+
+    // T: 1.0 → 1e-4 over budgetPerRun iterations
+    let T = 1.0;
+    const cooling = Math.pow(1e-4, 1 / budgetPerRun);
+    let currentError = evaluate(adapter, current).maxError;
+    let bestLocal = { params: { ...current }, error: currentError };
+
+    for (let i = 0; i < budgetPerRun; i++) {
+      T *= cooling;
+      // Perturb one random param by ±10% of its range
+      const neighbor = { ...current };
+      const spec = adapter.params[Math.floor(Math.random() * adapter.params.length)];
+      const step = (spec.range[1] - spec.range[0]) * 0.1 * (Math.random() * 2 - 1);
+      neighbor[spec.name] = Math.max(
+        spec.range[0],
+        Math.min(spec.range[1], neighbor[spec.name] + step),
+      );
+      if (spec.integer) neighbor[spec.name] = Math.round(neighbor[spec.name]);
+
+      const neighborError = evaluate(adapter, neighbor).maxError;
+      const delta = neighborError - currentError;
+      if (delta < 0 || Math.random() < Math.exp(-delta / T)) {
+        current = neighbor;
+        currentError = neighborError;
+      }
+      if (currentError < bestLocal.error) {
+        bestLocal = { params: { ...current }, error: currentError };
+      }
+      const globalIter = r * budgetPerRun + i;
+      if (onProgress && globalIter % 100 === 0) {
+        onProgress(globalIter, globalBest?.error ?? bestLocal.error);
+      }
+    }
+
+    if (!globalBest || bestLocal.error < globalBest.error) {
+      globalBest = bestLocal;
+    }
+  }
+
+  const finalMetrics = evaluate(adapter, globalBest!.params);
+  return {
+    params: globalBest!.params,
+    maxError: finalMetrics.maxError,
+    mae: finalMetrics.mae,
+    rmse: finalMetrics.rmse,
+    budgetUsed: budget,
+  };
+}

package/src/tuner/metrics.ts

@@ -0,0 +1,66 @@
+/**
+ * Error metrics for tuner adapters.
+ */
+
+import { TunerAdapter } from './types';
+
+export interface EvaluationResult {
+  maxError: number;
+  mae: number;
+  rmse: number;
+}
+
+/**
+ * Evaluate an adapter with given params across all sample inputs.
+ * Returns max_error, mae, and rmse relative to the reference function.
+ * Penalizes overflow by returning Infinity for all metrics.
+ */
+export function evaluate(
+  adapter: TunerAdapter,
+  params: Record<string, number>
+): EvaluationResult {
+  const inputs = adapter.sampleInputs();
+  let maxError = 0;
+  let sumAbsError = 0;
+  let sumSqError = 0;
+  let count = 0;
+
+  for (const input of inputs) {
+    const simResult = adapter.simulate(input, params);
+    const refResult = adapter.reference(input);
+
+    // Penalize overflow or NaN
+    if (!isFinite(simResult) || isNaN(simResult)) {
+      return { maxError: Infinity, mae: Infinity, rmse: Infinity };
+    }
+
+    if (!isFinite(refResult) || isNaN(refResult)) {
+      continue; // skip degenerate reference points
+    }
+
+    // Both are in fixed-point; normalize to compare in floating-point units
+    const SCALE = 10000;
+    const simFloat = simResult / SCALE;
+    const refFloat = refResult / SCALE;
+
+    const absError = Math.abs(simFloat - refFloat);
+    if (absError === Infinity) {
+      return { maxError: Infinity, mae: Infinity, rmse: Infinity };
+    }
+
+    if (absError > maxError) maxError = absError;
+    sumAbsError += absError;
+    sumSqError += absError * absError;
+    count++;
+  }
+
+  if (count === 0) {
+    return { maxError: Infinity, mae: Infinity, rmse: Infinity };
+  }
+
+  return {
+    maxError,
+    mae: sumAbsError / count,
+    rmse: Math.sqrt(sumSqError / count),
+  };
+}

package/src/tuner/simulator.ts

@@ -0,0 +1,69 @@
+/**
+ * MC int32 arithmetic simulation.
+ * Minecraft scoreboards use 32-bit signed integers (Java int).
+ */
+
+export const INT32_MAX = 2147483647;
+export const INT32_MIN = -2147483648;
+
+/**
+ * Truncate to int32 using JavaScript bitwise (same as Java int cast).
+ */
+export function i32(x: number): number {
+  return x | 0;
+}
+
+/**
+ * Check if a value is within int32 range (before truncation).
+ */
+export function isOverflow(x: number): boolean {
+  return x > INT32_MAX || x < INT32_MIN || !isFinite(x) || isNaN(x);
+}
+
+/**
+ * Fixed-point multiply: compute i32(i32(a * b) / scale).
+ * Returns Infinity if overflow is detected before truncation.
+ */
+export function fixedMul(a: number, b: number, scale: number): number {
+  const product = a * b;
+  if (isOverflow(product)) return Infinity;
+  const truncated = i32(product);
+  const divided = truncated / scale;
+  if (isOverflow(divided)) return Infinity;
+  return i32(divided);
+}
+
+/**
+ * Safe i32 addition - returns Infinity on overflow.
+ */
+export function safeAdd(a: number, b: number): number {
+  const result = a + b;
+  if (isOverflow(result)) return Infinity;
+  return i32(result);
+}
+
+/**
+ * Safe i32 subtraction - returns Infinity on overflow.
+ */
+export function safeSub(a: number, b: number): number {
+  const result = a - b;
+  if (isOverflow(result)) return Infinity;
+  return i32(result);
+}
+
+/**
+ * Safe i32 multiply - returns Infinity on overflow.
+ */
+export function safeMul(a: number, b: number): number {
+  const result = a * b;
+  if (isOverflow(result)) return Infinity;
+  return i32(result);
+}
+
+/**
+ * Safe i32 division - returns Infinity on division by zero.
+ */
+export function safeDiv(a: number, b: number): number {
+  if (b === 0) return Infinity;
+  return i32(a / b);
+}

package/src/tuner/types.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared types for the redscript tuner system.
+ */
+
+export interface ParamSpec {
+  name: string;
+  range: [number, number]; // search range
+  integer: boolean; // whether to force integer rounding
+}
+
+export interface ResultMeta {
+  maxError: number;
+  mae: number;
+  rmse: number;
+  estimatedCmds: number; // estimated mcfunction command count
+  tuneDate: string;
+  budgetUsed: number;
+}
+
+export interface TunerAdapter {
+  name: string;
+  description: string;
+  params: ParamSpec[];
+
+  // Simulate function with int32 semantics, returns fixed-point integer result
+  simulate(input: number, params: Record<string, number>): number;
+
+  // Reference value (floating-point) for error computation
+  reference(input: number): number;
+
+  // Generate input sample points
+  sampleInputs(): number[];
+
+  // Generate full .mcrs code with the optimal params
+  generateCode(params: Record<string, number>, meta: ResultMeta): string;
+}
+
+export interface SearchResult {
+  params: Record<string, number>;
+  maxError: number;
+  mae: number;
+  rmse: number;
+  budgetUsed: number;
+}

package/src/typechecker/index.ts

@@ -138,6 +138,9 @@ export class TypeChecker {
   private scope: Map<string, ScopeSymbol> = new Map()
   // Stack for tracking @s type in different contexts
   private selfTypeStack: EntityTypeName[] = ['entity']
+  // Depth of loop/conditional nesting (for static-allocation enforcement)
+  private loopDepth = 0
+  private condDepth = 0
 
   private readonly richTextBuiltins = new Map<string, { messageIndex: number }>([
     ['say', { messageIndex: 0 }],
@@ -352,17 +355,23 @@ export class TypeChecker {
         break
       case 'if':
         this.checkExpr(stmt.cond)
+        this.condDepth++
         this.checkIfBranches(stmt)
+        this.condDepth--
         break
       case 'while':
         this.checkExpr(stmt.cond)
+        this.loopDepth++
         this.checkBlock(stmt.body)
+        this.loopDepth--
         break
       case 'for':
         if (stmt.init) this.checkStmt(stmt.init)
         this.checkExpr(stmt.cond)
         this.checkExpr(stmt.step)
+        this.loopDepth++
         this.checkBlock(stmt.body)
+        this.loopDepth--
         break
       case 'foreach':
         this.checkExpr(stmt.iterable)
@@ -375,7 +384,9 @@ export class TypeChecker {
           })
           // Push self type context for @s inside the loop
           this.pushSelfType(entityType)
+          this.loopDepth++
           this.checkBlock(stmt.body)
+          this.loopDepth--
           this.popSelfType()
         } else {
           const iterableType = this.inferType(stmt.iterable)
@@ -384,7 +395,9 @@ export class TypeChecker {
           } else {
             this.scope.set(stmt.binding, { type: { kind: 'named', name: 'void' }, mutable: true })
           }
+          this.loopDepth++
           this.checkBlock(stmt.body)
+          this.loopDepth--
         }
         break
       case 'match':
@@ -712,6 +725,19 @@ export class TypeChecker {
 
     const builtin = BUILTIN_SIGNATURES[expr.fn]
     if (builtin) {
+      if (expr.fn === 'setTimeout' || expr.fn === 'setInterval') {
+        if (this.loopDepth > 0) {
+          this.report(
+            `${expr.fn}() cannot be called inside a loop. Declare timers at the top level.`,
+            expr
+          )
+        } else if (this.condDepth > 0) {
+          this.report(
+            `${expr.fn}() cannot be called inside an if/else body. Declare timers at the top level.`,
+            expr
+          )
+        }
+      }
       this.checkFunctionCallArgs(expr.args, builtin.params, expr.fn, expr)
       return
     }
@@ -907,6 +933,19 @@ export class TypeChecker {
   }
 
   private checkStaticCallExpr(expr: Extract<Expr, { kind: 'static_call' }>): void {
+    if (expr.type === 'Timer' && expr.method === 'new') {
+      if (this.loopDepth > 0) {
+        this.report(
+          `Timer::new() cannot be called inside a loop. Declare timers at the top level.`,
+          expr
+        )
+      } else if (this.condDepth > 0) {
+        this.report(
+          `Timer::new() cannot be called inside an if/else body. Declare timers at the top level.`,
+          expr
+        )
+      }
+    }
     const method = this.implMethods.get(expr.type)?.get(expr.method)
     if (!method) {
       this.report(`Type '${expr.type}' has no static method '${expr.method}'`, expr)