redscript-mc 2.1.1 → 2.3.0

package/dist/src/tuner/engine.js

@@ -0,0 +1,215 @@
+"use strict";
+/**
+ * Nelder-Mead simplex optimization engine for hyperparameter tuning.
+ * Suitable for continuous parameter spaces without gradient information.
+ * Supports mixed-integer parameters.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.search = search;
+exports.searchSA = searchSA;
+const metrics_1 = require("./metrics");
+/**
+ * Apply integer constraints to parameters.
+ */
+function applyIntegerConstraints(coords, specs) {
+    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, specs) {
+    const params = {};
+    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, specs, adapter) {
+    const constrained = applyIntegerConstraints(coords, specs);
+    const params = coordsToParams(constrained, specs);
+    const metrics = (0, metrics_1.evaluate)(adapter, params);
+    return metrics.maxError;
+}
+/**
+ * Run Nelder-Mead optimization.
+ */
+function search(adapter, budget = 10000, onProgress) {
+    const specs = adapter.params;
+    const n = specs.length;
+    if (n === 0) {
+        // No params to optimize
+        const params = coordsToParams([], specs);
+        const metrics = (0, metrics_1.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 = [];
+    // 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 = (0, metrics_1.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.
+ */
+function searchSA(adapter, budget, onProgress) {
+    const RESTARTS = 3;
+    const budgetPerRun = Math.floor(budget / RESTARTS);
+    let globalBest = null;
+    for (let r = 0; r < RESTARTS; r++) {
+        // Random initialisation within param ranges
+        let current = {};
+        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 = (0, metrics_1.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 = (0, metrics_1.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 = (0, metrics_1.evaluate)(adapter, globalBest.params);
+    return {
+        params: globalBest.params,
+        maxError: finalMetrics.maxError,
+        mae: finalMetrics.mae,
+        rmse: finalMetrics.rmse,
+        budgetUsed: budget,
+    };
+}
+//# sourceMappingURL=engine.js.map

package/dist/src/tuner/metrics.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 declare function evaluate(adapter: TunerAdapter, params: Record<string, number>): EvaluationResult;

package/dist/src/tuner/metrics.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Error metrics for tuner adapters.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluate = evaluate;
+/**
+ * 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.
+ */
+function evaluate(adapter, params) {
+    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),
+    };
+}
+//# sourceMappingURL=metrics.js.map

package/dist/src/tuner/simulator.d.ts

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

package/dist/src/tuner/simulator.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * MC int32 arithmetic simulation.
+ * Minecraft scoreboards use 32-bit signed integers (Java int).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INT32_MIN = exports.INT32_MAX = void 0;
+exports.i32 = i32;
+exports.isOverflow = isOverflow;
+exports.fixedMul = fixedMul;
+exports.safeAdd = safeAdd;
+exports.safeSub = safeSub;
+exports.safeMul = safeMul;
+exports.safeDiv = safeDiv;
+exports.INT32_MAX = 2147483647;
+exports.INT32_MIN = -2147483648;
+/**
+ * Truncate to int32 using JavaScript bitwise (same as Java int cast).
+ */
+function i32(x) {
+    return x | 0;
+}
+/**
+ * Check if a value is within int32 range (before truncation).
+ */
+function isOverflow(x) {
+    return x > exports.INT32_MAX || x < exports.INT32_MIN || !isFinite(x) || isNaN(x);
+}
+/**
+ * Fixed-point multiply: compute i32(i32(a * b) / scale).
+ * Returns Infinity if overflow is detected before truncation.
+ */
+function fixedMul(a, b, scale) {
+    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.
+ */
+function safeAdd(a, b) {
+    const result = a + b;
+    if (isOverflow(result))
+        return Infinity;
+    return i32(result);
+}
+/**
+ * Safe i32 subtraction - returns Infinity on overflow.
+ */
+function safeSub(a, b) {
+    const result = a - b;
+    if (isOverflow(result))
+        return Infinity;
+    return i32(result);
+}
+/**
+ * Safe i32 multiply - returns Infinity on overflow.
+ */
+function safeMul(a, b) {
+    const result = a * b;
+    if (isOverflow(result))
+        return Infinity;
+    return i32(result);
+}
+/**
+ * Safe i32 division - returns Infinity on division by zero.
+ */
+function safeDiv(a, b) {
+    if (b === 0)
+        return Infinity;
+    return i32(a / b);
+}
+//# sourceMappingURL=simulator.js.map

package/dist/src/tuner/types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared types for the redscript tuner system.
+ */
+export interface ParamSpec {
+    name: string;
+    range: [number, number];
+    integer: boolean;
+}
+export interface ResultMeta {
+    maxError: number;
+    mae: number;
+    rmse: number;
+    estimatedCmds: number;
+    tuneDate: string;
+    budgetUsed: number;
+}
+export interface TunerAdapter {
+    name: string;
+    description: string;
+    params: ParamSpec[];
+    simulate(input: number, params: Record<string, number>): number;
+    reference(input: number): number;
+    sampleInputs(): number[];
+    generateCode(params: Record<string, number>, meta: ResultMeta): string;
+}
+export interface SearchResult {
+    params: Record<string, number>;
+    maxError: number;
+    mae: number;
+    rmse: number;
+    budgetUsed: number;
+}

package/dist/src/tuner/types.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Shared types for the redscript tuner system.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/src/typechecker/index.d.ts

@@ -18,6 +18,8 @@ export declare class TypeChecker {
     private currentReturnType;
     private scope;
     private selfTypeStack;
+    private loopDepth;
+    private condDepth;
     private readonly richTextBuiltins;
     constructor(source?: string, filePath?: string);
     private getNodeLocation;

package/dist/src/typechecker/index.js

@@ -123,6 +123,9 @@ class TypeChecker {
         this.scope = new Map();
         // Stack for tracking @s type in different contexts
         this.selfTypeStack = ['entity'];
+        // Depth of loop/conditional nesting (for static-allocation enforcement)
+        this.loopDepth = 0;
+        this.condDepth = 0;
         this.richTextBuiltins = new Map([
             ['say', { messageIndex: 0 }],
             ['announce', { messageIndex: 0 }],
@@ -296,18 +299,24 @@ 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);
@@ -320,7 +329,9 @@ 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 {
@@ -331,7 +342,9 @@ 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':
@@ -612,6 +625,14 @@ 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;
         }
@@ -759,6 +780,14 @@ class TypeChecker {
         }
     }
     checkStaticCallExpr(expr) {
+        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);

package/docs/ROADMAP.md

@@ -393,3 +393,38 @@ if let Some(player) = p {
 ---
 
 *此文档由奇尔沙治生成 · 2026-03-16*
+
+---
+
+## 遗留 Known Issues（未来修复）
+
+### Timer stdlib 重构
+**问题：** Timer 用硬编码 player 名存状态，只能有一个实例
+**解法：** 全局自增 ID + macro 函数（`$scoreboard players set $(player) ...`），让每个实例有唯一的 player 名
+**依赖：** lambda codegen（见下）
+**工作量：** 2-3天
+
+### lambda / closure codegen
+**问题：** `setTimeout(20, () => { ... })` 的 lambda 在 MIR 层被丢弃（`const 0` 占位符），没有真正编译
+**解法：** lambda body → 独立命名函数（`__timeout_callback_N`），在 HIR/MIR 层 lift
+**工作量：** 3-5天
+
+### Array literal 初始化
+**已修复：** `nums[0]` 的读取修好了（NBT storage codegen）
+**待完善：** `let nums = [10, 20, 30]` 的初始化写入目前走 fixture workaround
+**工作量：** 1-2天
+
+### mc-integration flaky tests
+- `entity query: armor_stands survive peaceful mode` — 依赖服务器 peaceful mode 设置
+- `E2E I: nested if/else boundary` — 偶发，服务器状态依赖
+
+### 设计决策：Timer 实例化策略
+
+**选定方案：编译期静态分配 + 禁止动态创建**
+
+- `Timer::new()` 只能在函数顶层/模块级别调用，不能在循环/条件分支里调用
+- 编译器给每个 `Timer::new()` 静态分配一个唯一 ID（`__timer_0`、`__timer_1`...）
+- 在循环体内调用 `Timer::new()` → 编译错误，提示使用预分配的 Timer 变量
+- 同理适用于 `setTimeout` / `setInterval`
+
+好处：零运行时开销，行为完全可预测，符合 MC 的数据包执行模型。