redscript-mc 2.2.1 → 2.3.0

package/dist/src/tuner/cli.js

@@ -0,0 +1,168 @@
+"use strict";
+/**
+ * CLI entry point for `redscript tune`.
+ * Usage: redscript tune --adapter <name> [--budget N] [--out path]
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const engine_1 = require("./engine");
+const ln_polynomial_1 = require("./adapters/ln-polynomial");
+const sqrt_newton_1 = require("./adapters/sqrt-newton");
+const ADAPTERS = {
+    'ln-polynomial': ln_polynomial_1.lnPolynomialAdapter,
+    'sqrt-newton': sqrt_newton_1.sqrtNewtonAdapter,
+};
+function printUsage() {
+    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) {
+    const result = { budget: 10000, strategy: 'nm' };
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--adapter' && args[i + 1]) {
+            result.adapter = args[++i];
+        }
+        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];
+        }
+        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, width = 30) {
+    const filled = Math.round(fraction * width);
+    const bar = '█'.repeat(filled) + '░'.repeat(width - filled);
+    return `[${bar}]`;
+}
+async function main() {
+    // 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' ? engine_1.searchSA : engine_1.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 = {
+        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);
+});
+//# sourceMappingURL=cli.js.map

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

@@ -0,0 +1,17 @@
+/**
+ * Nelder-Mead simplex optimization engine for hyperparameter tuning.
+ * Suitable for continuous parameter spaces without gradient information.
+ * Supports mixed-integer parameters.
+ */
+import { TunerAdapter, SearchResult } from './types';
+export type ProgressCallback = (iteration: number, bestError: number) => void;
+/**
+ * Run Nelder-Mead optimization.
+ */
+export declare function search(adapter: TunerAdapter, budget?: number, onProgress?: ProgressCallback): SearchResult;
+/**
+ * Simulated Annealing search strategy.
+ * More robust than Nelder-Mead for integer parameters and multimodal objectives.
+ * Uses 3 independent restarts, taking the global best.
+ */
+export declare function searchSA(adapter: TunerAdapter, budget: number, onProgress?: ProgressCallback): SearchResult;

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