redscript-mc 2.0.0 → 2.1.0

package/dist/src/optimizer/interprocedural.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Interprocedural Constant Propagation — MIR module-level optimization pass.
+ *
+ * For each call site where all arguments are compile-time constants, creates
+ * a specialized clone of the callee with the parameters substituted as
+ * constants, then runs constant folding on the clone.
+ *
+ * Specialized function naming: `original__const_N1_N2_...` where N1, N2 are
+ * the constant argument values.
+ *
+ * This pass iterates to fixpoint to handle transitively specialized callees.
+ */
+import type { MIRModule } from '../mir/types';
+export declare function interproceduralConstProp(mod: MIRModule): MIRModule;

package/dist/src/optimizer/interprocedural.js

@@ -0,0 +1,186 @@
+"use strict";
+/**
+ * Interprocedural Constant Propagation — MIR module-level optimization pass.
+ *
+ * For each call site where all arguments are compile-time constants, creates
+ * a specialized clone of the callee with the parameters substituted as
+ * constants, then runs constant folding on the clone.
+ *
+ * Specialized function naming: `original__const_N1_N2_...` where N1, N2 are
+ * the constant argument values.
+ *
+ * This pass iterates to fixpoint to handle transitively specialized callees.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.interproceduralConstProp = interproceduralConstProp;
+const constant_fold_1 = require("./constant_fold");
+function interproceduralConstProp(mod) {
+    let current = mod;
+    // Iterate to fixpoint (new specializations may enable further specializations)
+    for (let i = 0; i < 10; i++) {
+        const next = runOnePass(current);
+        if (next.functions.length === current.functions.length &&
+            JSON.stringify(next.functions.map(f => f.name)) === JSON.stringify(current.functions.map(f => f.name))) {
+            // No new specializations
+            return next;
+        }
+        current = next;
+    }
+    return current;
+}
+function runOnePass(mod) {
+    const fnMap = new Map(mod.functions.map(f => [f.name, f]));
+    const newFunctions = [...mod.functions];
+    const added = new Set();
+    for (const fn of mod.functions) {
+        for (const block of fn.blocks) {
+            for (const instr of block.instrs) {
+                if (instr.kind !== 'call')
+                    continue;
+                if (instr.args.length === 0)
+                    continue;
+                if (!instr.args.every(a => a.kind === 'const'))
+                    continue;
+                const callee = fnMap.get(instr.fn);
+                if (!callee)
+                    continue;
+                if (callee.isMacro)
+                    continue;
+                if (callee.name === fn.name)
+                    continue; // no direct recursion at call site
+                if (callee.params.length !== instr.args.length)
+                    continue;
+                // Skip if the callee is self-recursive (would cause infinite specialization)
+                if (isSelfRecursive(callee))
+                    continue;
+                // Only specialize single-block (loop-free) functions — loop bodies mutate
+                // variables in ways that make constant-param substitution unsafe.
+                if (callee.blocks.length > 1)
+                    continue;
+                const constArgs = instr.args;
+                const mangledName = mangleName(instr.fn, constArgs.map(a => a.value));
+                if (fnMap.has(mangledName) || added.has(mangledName))
+                    continue;
+                // Create specialized clone
+                const specialized = specialize(callee, constArgs.map(a => a.value), mangledName);
+                newFunctions.push(specialized);
+                added.add(mangledName);
+                fnMap.set(mangledName, specialized);
+            }
+        }
+    }
+    if (added.size === 0)
+        return mod;
+    // Rewrite call sites to use specialized names
+    const updatedFunctions = newFunctions.map(fn => rewriteCallSites(fn, fnMap));
+    return { ...mod, functions: updatedFunctions };
+}
+/** Returns true if the function contains a call to itself (direct recursion). */
+function isSelfRecursive(fn) {
+    for (const block of fn.blocks) {
+        for (const instr of block.instrs) {
+            if (instr.kind === 'call' && instr.fn === fn.name)
+                return true;
+            if (instr.kind === 'call_macro' && instr.fn === fn.name)
+                return true;
+        }
+    }
+    return false;
+}
+function mangleName(name, args) {
+    return `${name}__const_${args.map(v => v < 0 ? `n${Math.abs(v)}` : String(v)).join('_')}`;
+}
+function specialize(fn, args, newName) {
+    // Build substitution map: param.name → const operand
+    const sub = new Map();
+    for (let i = 0; i < fn.params.length; i++) {
+        sub.set(fn.params[i].name, { kind: 'const', value: args[i] });
+    }
+    const newBlocks = fn.blocks.map(block => substituteBlock(block, sub));
+    const specialized = {
+        ...fn,
+        name: newName,
+        params: [], // no params — all specialized
+        blocks: newBlocks,
+        isMacro: false,
+    };
+    // Run constant folding on the specialized function
+    return (0, constant_fold_1.constantFold)(specialized);
+}
+function substituteBlock(block, sub) {
+    const instrs = block.instrs.map(instr => substituteInstr(instr, sub));
+    const term = substituteInstr(block.term, sub);
+    return { ...block, instrs, term };
+}
+function substituteOp(op, sub) {
+    if (op.kind === 'temp') {
+        const replacement = sub.get(op.name);
+        if (replacement !== undefined)
+            return replacement;
+    }
+    return op;
+}
+function substituteInstr(instr, sub) {
+    switch (instr.kind) {
+        case 'copy': return { ...instr, src: substituteOp(instr.src, sub) };
+        case 'neg':
+        case 'not': return { ...instr, src: substituteOp(instr.src, sub) };
+        case 'add':
+        case 'sub':
+        case 'mul':
+        case 'div':
+        case 'mod':
+        case 'and':
+        case 'or':
+            return { ...instr, a: substituteOp(instr.a, sub), b: substituteOp(instr.b, sub) };
+        case 'cmp':
+            return { ...instr, a: substituteOp(instr.a, sub), b: substituteOp(instr.b, sub) };
+        case 'nbt_write':
+            return { ...instr, src: substituteOp(instr.src, sub) };
+        case 'call':
+            return { ...instr, args: instr.args.map(a => substituteOp(a, sub)) };
+        case 'call_macro':
+            return { ...instr, args: instr.args.map(a => ({ ...a, value: substituteOp(a.value, sub) })) };
+        case 'branch':
+            return { ...instr, cond: substituteOp(instr.cond, sub) };
+        case 'return':
+            return { ...instr, value: instr.value ? substituteOp(instr.value, sub) : null };
+        default:
+            return instr;
+    }
+}
+function rewriteCallSites(fn, fnMap) {
+    return {
+        ...fn,
+        blocks: fn.blocks.map(block => ({
+            ...block,
+            instrs: block.instrs.map(instr => {
+                if (instr.kind !== 'call')
+                    return instr;
+                if (!instr.args.every(a => a.kind === 'const'))
+                    return instr;
+                const callee = fnMap.get(instr.fn);
+                if (!callee)
+                    return instr;
+                if (callee.isMacro)
+                    return instr;
+                if (callee.name === fn.name)
+                    return instr;
+                if (callee.params.length !== instr.args.length)
+                    return instr;
+                const constArgs = instr.args;
+                const mangledName = mangleName(instr.fn, constArgs.map(a => a.value));
+                if (!fnMap.has(mangledName))
+                    return instr;
+                return { ...instr, fn: mangledName, args: [] };
+            }),
+            term: (() => {
+                const term = block.term;
+                if (term.kind !== 'call')
+                    return term;
+                return term;
+            })(),
+        })),
+    };
+}
+//# sourceMappingURL=interprocedural.js.map

package/dist/src/optimizer/lir/const_imm.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Constant Immediate Folding — LIR optimization pass.
+ *
+ * Peephole: finds score_set($__const_C, C) immediately followed by
+ * score_add/score_sub(dst, $__const_C), where $__const_C has no other
+ * uses in the function, and replaces the pair with a single
+ * `scoreboard players add/remove` raw command.
+ *
+ * This saves one command per arithmetic-with-constant operation.
+ */
+import type { LIRFunction } from '../../lir/types';
+export declare function constImmFold(fn: LIRFunction): LIRFunction;

package/dist/src/optimizer/lir/const_imm.js

@@ -0,0 +1,139 @@
+"use strict";
+/**
+ * Constant Immediate Folding — LIR optimization pass.
+ *
+ * Peephole: finds score_set($__const_C, C) immediately followed by
+ * score_add/score_sub(dst, $__const_C), where $__const_C has no other
+ * uses in the function, and replaces the pair with a single
+ * `scoreboard players add/remove` raw command.
+ *
+ * This saves one command per arithmetic-with-constant operation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.constImmFold = constImmFold;
+function slotKey(s) {
+    return `${s.player}\0${s.obj}`;
+}
+/** Count how many times a slot is used as a source operand. */
+function countSlotUses(instrs, target) {
+    let count = 0;
+    for (const instr of instrs) {
+        for (const s of getReadSlots(instr)) {
+            if (slotKey(s) === target)
+                count++;
+        }
+    }
+    return count;
+}
+function extractSlotsFromRaw(cmd) {
+    const slots = [];
+    const re = /(\$[\w.]+)\s+(\S+)/g;
+    let m;
+    while ((m = re.exec(cmd)) !== null) {
+        slots.push({ player: m[1], obj: m[2] });
+    }
+    return slots;
+}
+function getReadSlots(instr) {
+    switch (instr.kind) {
+        case 'score_copy': return [instr.src];
+        case 'score_add':
+        case 'score_sub':
+        case 'score_mul':
+        case 'score_div':
+        case 'score_mod':
+        case 'score_min':
+        case 'score_max':
+            return [instr.src];
+        case 'score_swap': return [instr.a, instr.b];
+        case 'store_cmd_to_score': return getReadSlots(instr.cmd);
+        case 'store_score_to_nbt': return [instr.src];
+        case 'return_value': return [instr.slot];
+        case 'call_if_matches':
+        case 'call_unless_matches':
+            return [instr.slot];
+        case 'call_if_score':
+        case 'call_unless_score':
+            return [instr.a, instr.b];
+        case 'raw': return extractSlotsFromRaw(instr.cmd);
+        case 'macro_line': return extractSlotsFromRaw(instr.template);
+        default: return [];
+    }
+}
+function constImmFold(fn) {
+    const instrs = fn.instructions;
+    if (instrs.length < 2)
+        return fn;
+    // Pre-compute use counts for all const slots
+    const useCounts = new Map();
+    for (const instr of instrs) {
+        for (const s of getReadSlots(instr)) {
+            const key = slotKey(s);
+            useCounts.set(key, (useCounts.get(key) || 0) + 1);
+        }
+    }
+    const result = [];
+    let changed = false;
+    let i = 0;
+    while (i < instrs.length) {
+        const curr = instrs[i];
+        const next = instrs[i + 1];
+        // Pattern: score_set(constSlot, C) + score_add/sub(dst, constSlot)
+        if (next &&
+            curr.kind === 'score_set' &&
+            curr.dst.player.startsWith('$__const_') &&
+            (next.kind === 'score_add' || next.kind === 'score_sub') &&
+            slotKey(next.src) === slotKey(curr.dst) &&
+            (useCounts.get(slotKey(curr.dst)) || 0) === 1) {
+            const C = curr.value;
+            const dst = next.dst;
+            if (C === 0 && next.kind === 'score_add') {
+                // add 0 is a no-op — skip both
+                changed = true;
+                i += 2;
+                continue;
+            }
+            if (C === 0 && next.kind === 'score_sub') {
+                // sub 0 is a no-op — skip both
+                changed = true;
+                i += 2;
+                continue;
+            }
+            // Determine add vs remove
+            let op;
+            let val;
+            if (next.kind === 'score_add') {
+                if (C > 0) {
+                    op = 'add';
+                    val = C;
+                }
+                else {
+                    op = 'remove';
+                    val = -C;
+                }
+            }
+            else {
+                // score_sub
+                if (C > 0) {
+                    op = 'remove';
+                    val = C;
+                }
+                else {
+                    op = 'add';
+                    val = -C;
+                }
+            }
+            result.push({
+                kind: 'raw',
+                cmd: `scoreboard players ${op} ${dst.player} ${dst.obj} ${val}`,
+            });
+            changed = true;
+            i += 2;
+            continue;
+        }
+        result.push(curr);
+        i++;
+    }
+    return changed ? { ...fn, instructions: result } : fn;
+}
+//# sourceMappingURL=const_imm.js.map

package/dist/src/optimizer/lir/dead_slot.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Dead Slot Elimination — LIR optimization pass.
+ *
+ * Removes score_set / score_copy instructions where the destination slot
+ * is never read anywhere in the function.
+ *
+ * Preserves writes to:
+ *  - $ret (return value)
+ *  - $p0, $p1, … (parameter passing slots)
+ *  - slots used in side-effectful instructions (calls, stores, nbt ops, raw)
+ */
+import type { LIRFunction, LIRModule } from '../../lir/types';
+export declare function deadSlotElim(fn: LIRFunction): LIRFunction;
+export declare function deadSlotElimModule(mod: LIRModule): LIRModule;

package/dist/src/optimizer/lir/dead_slot.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * Dead Slot Elimination — LIR optimization pass.
+ *
+ * Removes score_set / score_copy instructions where the destination slot
+ * is never read anywhere in the function.
+ *
+ * Preserves writes to:
+ *  - $ret (return value)
+ *  - $p0, $p1, … (parameter passing slots)
+ *  - slots used in side-effectful instructions (calls, stores, nbt ops, raw)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deadSlotElim = deadSlotElim;
+exports.deadSlotElimModule = deadSlotElimModule;
+/** Canonical key for a slot (player + obj). */
+function slotKey(s) {
+    return `${s.player}\0${s.obj}`;
+}
+/**
+ * Extract slot references from a raw MC command string.
+ * Matches patterns like `$player_name objective_name` used in scoreboard commands.
+ */
+function extractSlotsFromRaw(cmd) {
+    const slots = [];
+    // Match $<player> <obj> patterns (scoreboard slot references)
+    const re = /(\$[\w.]+)\s+(\S+)/g;
+    let m;
+    while ((m = re.exec(cmd)) !== null) {
+        slots.push({ player: m[1], obj: m[2] });
+    }
+    return slots;
+}
+/** Collect all slots that are *read* (used as source) by an instruction. */
+function getReadSlots(instr) {
+    switch (instr.kind) {
+        case 'score_copy': return [instr.src];
+        case 'score_add':
+        case 'score_sub':
+        case 'score_mul':
+        case 'score_div':
+        case 'score_mod':
+        case 'score_min':
+        case 'score_max':
+            return [instr.src];
+        case 'score_swap': return [instr.a, instr.b];
+        case 'store_cmd_to_score': return getReadSlots(instr.cmd);
+        case 'store_score_to_nbt': return [instr.src];
+        case 'store_nbt_to_score': return [];
+        case 'return_value': return [instr.slot];
+        case 'call_if_matches':
+        case 'call_unless_matches':
+            return [instr.slot];
+        case 'call_if_score':
+        case 'call_unless_score':
+            return [instr.a, instr.b];
+        case 'raw': return extractSlotsFromRaw(instr.cmd);
+        case 'macro_line': return extractSlotsFromRaw(instr.template);
+        default: return [];
+    }
+}
+/** Returns the destination slot if the instruction is a pure write (no side effects). */
+function getPureWriteDst(instr) {
+    switch (instr.kind) {
+        case 'score_set': return instr.dst;
+        case 'score_copy': return instr.dst;
+        default: return null;
+    }
+}
+/** True if a slot should never be eliminated (externally visible). */
+function isProtectedSlot(s) {
+    const p = s.player;
+    if (p === '$ret' || p.startsWith('$ret_') || /^\$p\d+$/.test(p))
+        return true;
+    // Option slots: __opt_ prefix ensures they're always written to scoreboard
+    // even when the variable appears unused locally
+    if (p.includes('__opt_'))
+        return true;
+    return false;
+}
+function deadSlotElim(fn) {
+    // 1. Collect all read slots across the function
+    const readSet = new Set();
+    for (const instr of fn.instructions) {
+        for (const s of getReadSlots(instr)) {
+            readSet.add(slotKey(s));
+        }
+    }
+    // 2. Filter out pure writes to slots that are never read
+    const filtered = fn.instructions.filter(instr => {
+        const dst = getPureWriteDst(instr);
+        if (dst === null)
+            return true; // not a pure write → keep
+        if (isProtectedSlot(dst))
+            return true;
+        return readSet.has(slotKey(dst));
+    });
+    if (filtered.length === fn.instructions.length)
+        return fn;
+    return { ...fn, instructions: filtered };
+}
+function deadSlotElimModule(mod) {
+    // Collect all slots read across ALL functions (cross-function visibility)
+    const globalReadSet = new Set();
+    for (const fn of mod.functions) {
+        for (const instr of fn.instructions) {
+            for (const s of getReadSlots(instr)) {
+                globalReadSet.add(slotKey(s));
+            }
+        }
+    }
+    let changed = false;
+    const functions = mod.functions.map(fn => {
+        const filtered = fn.instructions.filter(instr => {
+            const dst = getPureWriteDst(instr);
+            if (dst === null)
+                return true;
+            if (isProtectedSlot(dst))
+                return true;
+            return globalReadSet.has(slotKey(dst));
+        });
+        if (filtered.length !== fn.instructions.length)
+            changed = true;
+        if (filtered.length === fn.instructions.length)
+            return fn;
+        return { ...fn, instructions: filtered };
+    });
+    return changed ? { ...mod, functions } : mod;
+}
+//# sourceMappingURL=dead_slot.js.map

package/dist/src/optimizer/lir/peephole.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Execute-Store Peephole Pass — LIR optimization pass.
+ *
+ * Merges a `call_context` immediately followed by `score_set(dst, value)`
+ * into a single `store_cmd_to_score` instruction:
+ *
+ *   execute [subcommands] run function ns:fn      ← call_context
+ *   scoreboard players set $result __ns N         ← score_set
+ *
+ * becomes:
+ *
+ *   execute store result score $result __ns [subcommands] run function ns:fn
+ *
+ * This saves one command when the caller only needs to know whether the
+ * execute chain ran (success = 1) or to capture the function's return value.
+ *
+ * Safety: only merges when the two instructions are immediately adjacent
+ * (no instructions between them).
+ */
+import type { LIRFunction } from '../../lir/types';
+export declare function execStorePeephole(fn: LIRFunction): LIRFunction;

package/dist/src/optimizer/lir/peephole.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * Execute-Store Peephole Pass — LIR optimization pass.
+ *
+ * Merges a `call_context` immediately followed by `score_set(dst, value)`
+ * into a single `store_cmd_to_score` instruction:
+ *
+ *   execute [subcommands] run function ns:fn      ← call_context
+ *   scoreboard players set $result __ns N         ← score_set
+ *
+ * becomes:
+ *
+ *   execute store result score $result __ns [subcommands] run function ns:fn
+ *
+ * This saves one command when the caller only needs to know whether the
+ * execute chain ran (success = 1) or to capture the function's return value.
+ *
+ * Safety: only merges when the two instructions are immediately adjacent
+ * (no instructions between them).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.execStorePeephole = execStorePeephole;
+function execStorePeephole(fn) {
+    const instrs = fn.instructions;
+    if (instrs.length < 2)
+        return fn;
+    const result = [];
+    let changed = false;
+    let i = 0;
+    while (i < instrs.length) {
+        const curr = instrs[i];
+        const next = instrs[i + 1];
+        // Pattern: call_context immediately followed by score_set
+        if (next &&
+            curr.kind === 'call_context' &&
+            next.kind === 'score_set') {
+            // Merge: execute store result score <dst> [subcommands] run function <fn>
+            result.push({
+                kind: 'store_cmd_to_score',
+                dst: next.dst,
+                cmd: curr,
+            });
+            changed = true;
+            i += 2;
+            continue;
+        }
+        result.push(curr);
+        i++;
+    }
+    return changed ? { ...fn, instructions: result } : fn;
+}
+//# sourceMappingURL=peephole.js.map

package/dist/src/optimizer/lir/pipeline.d.ts

@@ -0,0 +1,10 @@
+/**
+ * LIR Optimization Pipeline — runs all LIR passes on a module.
+ *
+ * Pass order: dead_slot → const_imm
+ * Dead slot runs first to remove unused writes, exposing more
+ * single-use const slots for const_imm to fold.
+ */
+import type { LIRFunction, LIRModule } from '../../lir/types';
+export type LIRPass = (fn: LIRFunction) => LIRFunction;
+export declare function lirOptimizeModule(mod: LIRModule): LIRModule;

package/dist/src/optimizer/lir/pipeline.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * LIR Optimization Pipeline — runs all LIR passes on a module.
+ *
+ * Pass order: dead_slot → const_imm
+ * Dead slot runs first to remove unused writes, exposing more
+ * single-use const slots for const_imm to fold.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lirOptimizeModule = lirOptimizeModule;
+const dead_slot_1 = require("./dead_slot");
+const const_imm_1 = require("./const_imm");
+const peephole_1 = require("./peephole");
+const perFunctionPasses = [
+    peephole_1.execStorePeephole,
+    const_imm_1.constImmFold,
+];
+function lirOptimizeModule(mod) {
+    // Module-level pass: dead slot elimination (cross-function analysis)
+    let result = (0, dead_slot_1.deadSlotElimModule)(mod);
+    // Per-function passes
+    let changed = false;
+    const functions = result.functions.map(fn => {
+        let current = fn;
+        for (const pass of perFunctionPasses) {
+            current = pass(current);
+        }
+        if (current !== fn)
+            changed = true;
+        return current;
+    });
+    return changed ? { ...result, functions } : result;
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/src/optimizer/nbt-batch.d.ts

@@ -0,0 +1,11 @@
+/**
+ * NBT Batch Read — MIR optimization pass.
+ *
+ * Eliminates redundant nbt_read instructions within a basic block:
+ * if the same (ns, path, scale) is read twice with no intervening nbt_write
+ * to that ns, the second read is replaced with a copy from the first read's dst.
+ *
+ * This reduces expensive `data get` commands in generated .mcfunction files.
+ */
+import type { MIRFunction } from '../mir/types';
+export declare function nbtBatchRead(fn: MIRFunction): MIRFunction;

package/dist/src/optimizer/nbt-batch.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * NBT Batch Read — MIR optimization pass.
+ *
+ * Eliminates redundant nbt_read instructions within a basic block:
+ * if the same (ns, path, scale) is read twice with no intervening nbt_write
+ * to that ns, the second read is replaced with a copy from the first read's dst.
+ *
+ * This reduces expensive `data get` commands in generated .mcfunction files.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nbtBatchRead = nbtBatchRead;
+function nbtBatchRead(fn) {
+    return {
+        ...fn,
+        blocks: fn.blocks.map(deduplicateBlock),
+    };
+}
+function deduplicateBlock(block) {
+    // Map from "ns\0path\0scale" → dst temp of the first read
+    const cache = new Map();
+    const instrs = [];
+    for (const instr of block.instrs) {
+        if (instr.kind === 'nbt_read') {
+            const key = `${instr.ns}\0${instr.path}\0${instr.scale}`;
+            const cached = cache.get(key);
+            if (cached !== undefined) {
+                // Replace with copy from cached temp
+                instrs.push({ kind: 'copy', dst: instr.dst, src: { kind: 'temp', name: cached } });
+            }
+            else {
+                cache.set(key, instr.dst);
+                instrs.push(instr);
+            }
+        }
+        else if (instr.kind === 'nbt_write') {
+            // Invalidate all cached reads for this ns
+            for (const key of [...cache.keys()]) {
+                if (key.startsWith(instr.ns + '\0')) {
+                    cache.delete(key);
+                }
+            }
+            instrs.push(instr);
+        }
+        else {
+            instrs.push(instr);
+        }
+    }
+    return { ...block, instrs };
+}
+//# sourceMappingURL=nbt-batch.js.map