redscript-mc 1.2.25 → 1.2.27

package/dist/isqrttest.map.json

@@ -0,0 +1,15 @@
+{
+  "$e": "n",
+  "$g": "p0",
+  "$j": "i",
+  "$k": "x",
+  "$p": "next",
+  "$s": "f",
+  "$u": "result",
+  "$a": "const:0",
+  "$b": "const:1",
+  "$c": "const:2",
+  "$d": "const:16",
+  "$f": "internal:p0",
+  "$i": "internal:ret"
+}

package/dist/lexer/index.d.ts

@@ -5,7 +5,7 @@
  * Handles special cases like entity selectors vs decorators,
  * range literals, and raw commands.
  */
-export type TokenKind = 'fn' | 'let' | 'const' | 'if' | 'else' | 'while' | 'for' | 'foreach' | 'match' | 'return' | 'break' | 'continue' | 'as' | 'at' | 'in' | 'is' | 'struct' | 'impl' | 'enum' | 'trigger' | 'namespace' | 'execute' | 'run' | 'unless' | 'declare' | 'int' | 'bool' | 'float' | 'string' | 'void' | 'BlockPos' | 'true' | 'false' | 'selector' | 'decorator' | 'int_lit' | 'float_lit' | 'byte_lit' | 'short_lit' | 'long_lit' | 'double_lit' | 'string_lit' | 'f_string' | 'range_lit' | 'rel_coord' | 'local_coord' | '+' | '-' | '*' | '/' | '%' | '~' | '^' | '==' | '!=' | '<' | '<=' | '>' | '>=' | '&&' | '||' | '!' | '=' | '+=' | '-=' | '*=' | '/=' | '%=' | '{' | '}' | '(' | ')' | '[' | ']' | ',' | ';' | ':' | '::' | '->' | '=>' | '.' | 'ident' | 'mc_name' | 'raw_cmd' | 'eof';
+export type TokenKind = 'fn' | 'let' | 'const' | 'if' | 'else' | 'while' | 'for' | 'foreach' | 'match' | 'return' | 'break' | 'continue' | 'as' | 'at' | 'in' | 'is' | 'struct' | 'impl' | 'enum' | 'trigger' | 'namespace' | 'module' | 'execute' | 'run' | 'unless' | 'declare' | 'int' | 'bool' | 'float' | 'string' | 'void' | 'BlockPos' | 'true' | 'false' | 'selector' | 'decorator' | 'int_lit' | 'float_lit' | 'byte_lit' | 'short_lit' | 'long_lit' | 'double_lit' | 'string_lit' | 'f_string' | 'range_lit' | 'rel_coord' | 'local_coord' | '+' | '-' | '*' | '/' | '%' | '~' | '^' | '==' | '!=' | '<' | '<=' | '>' | '>=' | '&&' | '||' | '!' | '=' | '+=' | '-=' | '*=' | '/=' | '%=' | '{' | '}' | '(' | ')' | '[' | ']' | ',' | ';' | ':' | '::' | '->' | '=>' | '.' | 'ident' | 'mc_name' | 'raw_cmd' | 'eof';
 export interface Token {
     kind: TokenKind;
     value: string;

package/dist/lexer/index.js

@@ -34,6 +34,7 @@ const KEYWORDS = {
     enum: 'enum',
     trigger: 'trigger',
     namespace: 'namespace',
+    module: 'module',
     execute: 'execute',
     run: 'run',
     unless: 'unless',

package/dist/lowering/index.d.ts

@@ -23,6 +23,11 @@ export declare class Lowering {
     private implMethods;
     private specializedFunctions;
     private currentFn;
+    /** Unique IR variable name for a local variable, scoped to the current function.
+     *  Prevents cross-function scoreboard slot collisions: $fn_x ≠ $gn_x.
+     *  Only applies to user-defined locals/params; internal slots ($p0, $ret) are
+     *  intentionally global (calling convention). */
+    private fnVar;
     private currentStdlibCallSite?;
     private foreachCounter;
     private lambdaCounter;

package/dist/lowering/index.js

@@ -128,6 +128,9 @@ const BUILTINS = {
     setTimeout: () => null, // Special handling
     setInterval: () => null, // Special handling
     clearInterval: () => null, // Special handling
+    storage_get_int: () => null, // Special handling (dynamic NBT array read via macro)
+    storage_set_array: () => null, // Special handling (write literal NBT array to storage)
+    storage_set_int: () => null, // Special handling (dynamic NBT array write via macro)
 };
 function getSpan(node) {
     return node?.span;
@@ -196,6 +199,13 @@ function emitBlockPos(pos) {
 // Lowering Class
 // ---------------------------------------------------------------------------
 class Lowering {
+    /** Unique IR variable name for a local variable, scoped to the current function.
+     *  Prevents cross-function scoreboard slot collisions: $fn_x ≠ $gn_x.
+     *  Only applies to user-defined locals/params; internal slots ($p0, $ret) are
+     *  intentionally global (calling convention). */
+    fnVar(name) {
+        return `$${this.currentFn}_${name}`;
+    }
     currentEntityContext() {
         return this.entityContextStack.length > 0
             ? this.entityContextStack[this.entityContextStack.length - 1]
@@ -330,12 +340,30 @@ class Lowering {
     }
     preScanExpr(expr, paramNames, macroParams) {
         if (expr.kind === 'call' && BUILTINS[expr.fn] !== undefined) {
-            // All ident args to macro-aware builtins that are params → macro params
-            for (const arg of expr.args) {
-                if (arg.kind === 'ident' && paramNames.has(arg.name)) {
-                    macroParams.add(arg.name);
+            // Only trigger macro param detection for builtins that actually emit
+            // MC commands with $(param) inline in the current function body.
+            // Special-handled builtins (storage_get_int / storage_set_int / etc.) are
+            // declared as `() => null` — they create their own sub-functions for macro
+            // indirection and do NOT require the surrounding function to be a macro.
+            const handler = BUILTINS[expr.fn];
+            const isSpecialHandled = (() => {
+                try {
+                    return handler() === null;
+                }
+                catch {
+                    return false;
+                }
+            })();
+            if (!isSpecialHandled) {
+                for (const arg of expr.args) {
+                    if (arg.kind === 'ident' && paramNames.has(arg.name)) {
+                        macroParams.add(arg.name);
+                    }
                 }
             }
+            // Always recurse into args for nested calls/expressions
+            for (const arg of expr.args)
+                this.preScanExpr(arg, paramNames, macroParams);
             return;
         }
         // Recurse into sub-expressions for other call types
@@ -564,13 +592,13 @@ class Lowering {
                     this.stringValues.set(param.name, '');
                     continue;
                 }
-                this.varMap.set(param.name, `$${param.name}`);
+                this.varMap.set(param.name, this.fnVar(param.name));
             }
         }
         else {
             for (const param of runtimeParams) {
                 const paramName = param.name;
-                this.varMap.set(paramName, `$${paramName}`);
+                this.varMap.set(paramName, this.fnVar(paramName));
                 this.varTypes.set(paramName, this.normalizeType(param.type));
             }
         }
@@ -581,18 +609,22 @@ class Lowering {
         }
         // Start entry block
         this.builder.startBlock('entry');
-        // Copy params from $p0, $p1, ... to named variables
+        // Copy params from the parameter-passing slots to named local variables.
+        // Use { kind: 'param', index: i } so the codegen resolves to
+        // alloc.internal('p{i}') consistently in both mangle and no-mangle modes,
+        // avoiding the slot-collision between the internal register and a user variable
+        // named 'p0'/'p1' that occurred with { kind: 'var', name: '$p0' }.
         for (let i = 0; i < runtimeParams.length; i++) {
             const paramName = runtimeParams[i].name;
-            const varName = `$${paramName}`;
-            this.builder.emitAssign(varName, { kind: 'var', name: `$p${i}` });
+            const varName = this.fnVar(paramName);
+            this.builder.emitAssign(varName, { kind: 'param', index: i });
         }
         if (staticEventDec) {
             for (let i = 0; i < fn.params.length; i++) {
                 const param = fn.params[i];
                 const expected = eventParamSpecs[i];
                 if (expected?.type.kind === 'named' && expected.type.name !== 'string') {
-                    this.builder.emitAssign(`$${param.name}`, { kind: 'const', value: 0 });
+                    this.builder.emitAssign(this.fnVar(param.name), { kind: 'const', value: 0 });
                 }
             }
         }
@@ -649,6 +681,22 @@ class Lowering {
         if (fn.decorators.some(d => d.name === 'load')) {
             irFn.isLoadInit = true;
         }
+        // @requires("dep_fn") — when this function is compiled in, dep_fn is also
+        // called from __load.  The dep_fn itself does NOT need @load; it can be a
+        // private (_) function that only runs at load time when this fn is used.
+        const requiredLoads = [];
+        for (const d of fn.decorators) {
+            if (d.name === 'require_on_load') {
+                for (const arg of d.rawArgs ?? []) {
+                    if (arg.kind === 'string') {
+                        requiredLoads.push(arg.value);
+                    }
+                }
+            }
+        }
+        if (requiredLoads.length > 0) {
+            irFn.requiredLoads = requiredLoads;
+        }
         // Handle tick rate counter if needed
         if (tickRate && tickRate > 1) {
             this.wrapWithTickRate(irFn, tickRate);
@@ -773,7 +821,7 @@ class Lowering {
         if (this.currentContext.binding === stmt.name) {
             throw new diagnostics_1.DiagnosticError('LoweringError', `Cannot redeclare foreach binding '${stmt.name}'`, stmt.span ?? { line: 0, col: 0 });
         }
-        const varName = `$${stmt.name}`;
+        const varName = this.fnVar(stmt.name);
         this.varMap.set(stmt.name, varName);
         // Track variable type
         const declaredType = stmt.type ? this.normalizeType(stmt.type) : this.inferExprType(stmt.init);
@@ -1049,7 +1097,7 @@ class Lowering {
         this.builder.startBlock(exitLabel);
     }
     lowerForRangeStmt(stmt) {
-        const loopVar = `$${stmt.varName}`;
+        const loopVar = this.fnVar(stmt.varName);
         const subFnName = `${this.currentFn}/__for_${this.foreachCounter++}`;
         // Initialize loop variable
         this.varMap.set(stmt.varName, loopVar);
@@ -1208,7 +1256,7 @@ class Lowering {
             return;
         }
         const arrayType = this.inferExprType(stmt.iterable);
-        const bindingVar = `$${stmt.binding}`;
+        const bindingVar = this.fnVar(stmt.binding);
         const indexVar = this.builder.freshTemp();
         const lengthVar = this.builder.freshTemp();
         const condVar = this.builder.freshTemp();
@@ -2216,6 +2264,98 @@ class Lowering {
             this.builder.emitRaw(`execute store result score ${dst} rs run data get ${targetType} ${target} ${path} ${scale}`);
             return { kind: 'var', name: dst };
         }
+        // storage_get_int(storage_ns, array_key, index) -> int
+        // Reads one element from an NBT int-array stored in data storage.
+        //   storage_ns : e.g. "math:tables"
+        //   array_key  : e.g. "sin"
+        //   index      : integer index (const or runtime)
+        //
+        // Const index: execute store result score $dst rs run data get storage math:tables sin[N] 1
+        // Runtime index: macro sub-function via rs:heap, mirrors readArrayElement.
+        if (name === 'storage_get_int') {
+            const storageNs = this.exprToString(args[0]); // "math:tables"
+            const arrayKey = this.exprToString(args[1]); // "sin"
+            const indexOperand = this.lowerExpr(args[2]);
+            const dst = this.builder.freshTemp();
+            if (indexOperand.kind === 'const') {
+                this.builder.emitRaw(`execute store result score ${dst} rs run data get storage ${storageNs} ${arrayKey}[${indexOperand.value}] 1`);
+            }
+            else {
+                // Runtime index: store the index into rs:heap under a unique key,
+                // then call a macro sub-function that uses $(key) to index the array.
+                const macroKey = `__sgi_${this.foreachCounter++}`;
+                const subFnName = `${this.currentFn}/__sgi_${this.foreachCounter++}`;
+                const indexVar = indexOperand.kind === 'var'
+                    ? indexOperand.name
+                    : this.operandToVar(indexOperand);
+                this.builder.emitRaw(`execute store result storage rs:heap ${macroKey} int 1 run scoreboard players get ${indexVar} rs`);
+                this.builder.emitRaw(`function ${this.namespace}:${subFnName} with storage rs:heap`);
+                // Prefix \x01 is a sentinel for the MC macro '$' line-start marker.
+                // We avoid using literal '$execute' here so the pre-alloc pass
+                // doesn't mistakenly register 'execute' as a scoreboard variable.
+                // Codegen replaces \x01 → '$' when emitting the mc function file.
+                this.emitRawSubFunction(subFnName, `\x01execute store result score ${dst} rs run data get storage ${storageNs} ${arrayKey}[$(${macroKey})] 1`);
+            }
+            return { kind: 'var', name: dst };
+        }
+        // storage_set_array(storage_ns, array_key, nbt_array_literal)
+        // Writes a literal NBT int array to data storage (used in @load for tables).
+        //   storage_set_array("math:tables", "sin", "[0, 17, 35, ...]")
+        if (name === 'storage_set_array') {
+            const storageNs = this.exprToString(args[0]);
+            const arrayKey = this.exprToString(args[1]);
+            const nbtLiteral = this.exprToString(args[2]);
+            this.builder.emitRaw(`data modify storage ${storageNs} ${arrayKey} set value ${nbtLiteral}`);
+            return { kind: 'const', value: 0 };
+        }
+        // storage_set_int(storage_ns, array_key, index, value) -> void
+        // Writes one integer element into an NBT int-array stored in data storage.
+        //   storage_ns : e.g. "rs:bigint"
+        //   array_key  : e.g. "a"
+        //   index      : element index (const or runtime)
+        //   value      : integer value to write (const or runtime)
+        //
+        // Const index + const value:
+        //   execute store result storage <ns> <key>[N] int 1 run scoreboard players set $const_V rs V
+        // Runtime index or value: macro sub-function via rs:heap
+        if (name === 'storage_set_int') {
+            const storageNs = this.exprToString(args[0]);
+            const arrayKey = this.exprToString(args[1]);
+            const indexOperand = this.lowerExpr(args[2]);
+            const valueOperand = this.lowerExpr(args[3]);
+            if (indexOperand.kind === 'const') {
+                // Static index — use execute store result to write to the fixed slot
+                const valVar = valueOperand.kind === 'var'
+                    ? valueOperand.name
+                    : this.operandToVar(valueOperand);
+                this.builder.emitRaw(`execute store result storage ${storageNs} ${arrayKey}[${indexOperand.value}] int 1 run scoreboard players get ${valVar} rs`);
+            }
+            else {
+                // Runtime index: we need a macro sub-function.
+                // Store index + value into rs:heap, call macro that does:
+                //   $data modify storage <ns> <key>[$(idx_key)] set value $(val_key)
+                const macroIdxKey = `__ssi_i_${this.foreachCounter++}`;
+                const macroValKey = `__ssi_v_${this.foreachCounter++}`; // kept to pin valVar in optimizer
+                const subFnName = `${this.currentFn}/__ssi_${this.foreachCounter++}`;
+                const indexVar = indexOperand.kind === 'var'
+                    ? indexOperand.name
+                    : this.operandToVar(indexOperand);
+                const valVar = valueOperand.kind === 'var'
+                    ? valueOperand.name
+                    : this.operandToVar(valueOperand);
+                this.builder.emitRaw(`execute store result storage rs:heap ${macroIdxKey} int 1 run scoreboard players get ${indexVar} rs`);
+                // Pin valVar in the optimizer's read-set so the assignment is not dead-code-eliminated.
+                // The value is stored to rs:heap but NOT used by the macro (the macro reads the scoreboard
+                // slot directly to avoid the MC 'data modify set value $(n)' macro substitution bug).
+                this.builder.emitRaw(`execute store result storage rs:heap ${macroValKey} int 1 run scoreboard players get ${valVar} rs`);
+                this.builder.emitRaw(`function ${this.namespace}:${subFnName} with storage rs:heap`);
+                // Use execute store result (not 'data modify set value $(val)') to avoid MC macro
+                // substitution bugs with numeric values. The scoreboard slot ${valVar} is hardcoded
+                // into the macro sub-function at compile time — only the array index is macro-substituted.
+                this.emitRawSubFunction(subFnName, `\x01execute store result storage ${storageNs} ${arrayKey}[$(${macroIdxKey})] int 1 run scoreboard players get ${valVar} rs`);
+            }
+            return { kind: 'const', value: 0 };
+        }
         // data_merge(target, nbt) — merge NBT into entity/block/storage
         // data_merge(@s, { Invisible: 1b, Silent: 1b })
         if (name === 'data_merge') {
@@ -3006,7 +3146,7 @@ class Lowering {
         const indexVar = index.kind === 'var' ? index.name : this.operandToVar(index);
         this.builder.emitRaw(`execute store result storage rs:heap ${macroKey} int 1 run scoreboard players get ${indexVar} rs`);
         this.builder.emitRaw(`function ${this.namespace}:${subFnName} with storage rs:heap`);
-        this.emitRawSubFunction(subFnName, `$execute store result score ${dst} rs run data get storage rs:heap ${arrayName}[$(${macroKey})]`);
+        this.emitRawSubFunction(subFnName, `\x01execute store result score ${dst} rs run data get storage rs:heap ${arrayName}[$(${macroKey})]`);
         return { kind: 'var', name: dst };
     }
     emitRawSubFunction(name, ...commands) {

package/dist/mathtest.map.json

@@ -0,0 +1,6 @@
+{
+  "$b": "x",
+  "$a": "const:0",
+  "$c": "internal:p0",
+  "$f": "internal:ret"
+}

package/dist/mypack.map.json

@@ -0,0 +1,27 @@
+{
+  "$o": "x",
+  "$r": "execute",
+  "$u": "y",
+  "$aa": "ax",
+  "$ad": "ay",
+  "$ai": "swapped",
+  "$ak": "tmp",
+  "$al": "lo",
+  "$am": "hi",
+  "$ar": "mid",
+  "$as": "t",
+  "$ax": "theta",
+  "$a": "const:0",
+  "$b": "const:1",
+  "$c": "const:2",
+  "$d": "const:45",
+  "$e": "const:90",
+  "$f": "const:180",
+  "$g": "const:270",
+  "$h": "const:360",
+  "$i": "const:1000",
+  "$j": "const:46340",
+  "$k": "internal:ret",
+  "$n": "internal:p0",
+  "$t": "internal:p1"
+}

package/dist/optimizer/dce.js

@@ -115,12 +115,17 @@ class DeadCodeEliminator {
     findEntryPoints(program) {
         const entries = new Set();
         for (const fn of program.declarations) {
-            // All top-level functions are entry points (callable via /function)
-            // Exception: functions starting with _ are considered private/internal
-            if (!fn.name.startsWith('_')) {
-                entries.add(fn.name);
+            // Library functions (from `module library;` or `librarySources`) are
+            // NOT MC entry points — they're only kept if reachable from user code.
+            // Exception: decorators like @tick / @load / @on / @keep always force inclusion.
+            if (!fn.isLibraryFn) {
+                // All top-level non-library functions are entry points (callable via /function)
+                // Exception: functions starting with _ are considered private/internal
+                if (!fn.name.startsWith('_')) {
+                    entries.add(fn.name);
+                }
             }
-            // Decorated functions are always entry points (even if prefixed with _)
+            // Decorated functions are always entry points regardless of library mode or _ prefix
             if (fn.decorators.some(decorator => [
                 'tick',
                 'load',
@@ -148,6 +153,17 @@ class DeadCodeEliminator {
         }
         this.reachableFunctions.add(fnName);
         this.collectFunctionRefs(fn);
+        // @requires("dep") — when fn is reachable, its required dependencies are
+        // also pulled into the reachable set so they survive DCE.
+        for (const decorator of fn.decorators) {
+            if (decorator.name === 'require_on_load') {
+                for (const arg of decorator.rawArgs ?? []) {
+                    if (arg.kind === 'string') {
+                        this.markReachable(arg.value);
+                    }
+                }
+            }
+        }
     }
     collectFunctionRefs(fn) {
         const scope = [fn.params.map(param => ({ id: `param:${fn.name}:${param.name}`, name: param.name }))];

package/dist/optimizer/passes.js

@@ -93,32 +93,44 @@ function copyPropagation(fn) {
                 return op;
             return copies.get(op.name) ?? op;
         }
+        /**
+         * Invalidate all copies that became stale because `written` was modified.
+         * When $y is overwritten, any mapping copies[$tmp] = $y is now stale:
+         * reading $tmp would return the OLD $y value via the copy, but $y now holds
+         * a different value.  Remove both the direct entry (copies[$y]) and every
+         * reverse entry that points at $y.
+         */
+        function invalidate(written) {
+            copies.delete(written);
+            for (const [k, v] of copies) {
+                if (v.kind === 'var' && v.name === written)
+                    copies.delete(k);
+            }
+        }
         const newInstrs = [];
         for (const instr of block.instrs) {
             switch (instr.op) {
                 case 'assign': {
                     const src = resolve(instr.src);
+                    invalidate(instr.dst);
                     // Only propagate scalars (var or const), not storage
                     if (src.kind === 'var' || src.kind === 'const') {
                         copies.set(instr.dst, src);
                     }
-                    else {
-                        copies.delete(instr.dst);
-                    }
                     newInstrs.push({ ...instr, src });
                     break;
                 }
                 case 'binop':
-                    copies.delete(instr.dst);
+                    invalidate(instr.dst);
                     newInstrs.push({ ...instr, lhs: resolve(instr.lhs), rhs: resolve(instr.rhs) });
                     break;
                 case 'cmp':
-                    copies.delete(instr.dst);
+                    invalidate(instr.dst);
                     newInstrs.push({ ...instr, lhs: resolve(instr.lhs), rhs: resolve(instr.rhs) });
                     break;
                 case 'call':
                     if (instr.dst)
-                        copies.delete(instr.dst);
+                        invalidate(instr.dst);
                     newInstrs.push({ ...instr, args: instr.args.map(resolve) });
                     break;
                 default:

package/dist/optimizer/structure.js

@@ -21,6 +21,8 @@ function operandToScore(op) {
         return `${varRef(op.name)} ${OBJ}`;
     if (op.kind === 'const')
         return `$const_${op.value} ${OBJ}`;
+    if (op.kind === 'param')
+        return `$p${op.index} ${OBJ}`;
     throw new Error(`Cannot convert storage operand to score: ${op.path}`);
 }
 function emitInstr(instr, namespace) {
@@ -35,6 +37,11 @@ function emitInstr(instr, namespace) {
                     cmd: `scoreboard players operation ${varRef(instr.dst)} ${OBJ} = ${varRef(instr.src.name)} ${OBJ}`,
                 });
             }
+            else if (instr.src.kind === 'param') {
+                commands.push({
+                    cmd: `scoreboard players operation ${varRef(instr.dst)} ${OBJ} = $p${instr.src.index} ${OBJ}`,
+                });
+            }
             else {
                 commands.push({
                     cmd: `execute store result score ${varRef(instr.dst)} ${OBJ} run data get storage ${instr.src.path}`,

package/dist/pack.mcmeta

@@ -0,0 +1,6 @@
+{
+  "pack": {
+    "pack_format": 26,
+    "description": "mypack datapack — compiled by redscript"
+  }
+}

package/dist/parser/index.d.ts

@@ -11,6 +11,11 @@ export declare class Parser {
     private pos;
     private sourceLines;
     private filePath?;
+    /** Set to true once `module library;` is seen — all subsequent fn declarations
+     *  will be marked isLibraryFn=true.  When library sources are parsed via the
+     *  `librarySources` compile option, each source is parsed by its own fresh
+     *  Parser instance, so this flag never bleeds into user code. */
+    private inLibraryMode;
     constructor(tokens: Token[], source?: string, filePath?: string);
     private peek;
     private advance;

package/dist/parser/index.js

@@ -64,6 +64,11 @@ function computeIsSingle(raw) {
 class Parser {
     constructor(tokens, source, filePath) {
         this.pos = 0;
+        /** Set to true once `module library;` is seen — all subsequent fn declarations
+         *  will be marked isLibraryFn=true.  When library sources are parsed via the
+         *  `librarySources` compile option, each source is parsed by its own fresh
+         *  Parser instance, so this flag never bleeds into user code. */
+        this.inLibraryMode = false;
         this.tokens = tokens;
         this.sourceLines = source?.split('\n') ?? [];
         this.filePath = filePath;
@@ -135,6 +140,7 @@ class Parser {
         const implBlocks = [];
         const enums = [];
         const consts = [];
+        let isLibrary = false;
         // Check for namespace declaration
         if (this.check('namespace')) {
             this.advance();
@@ -142,6 +148,19 @@ class Parser {
             namespace = name.value;
             this.expect(';');
         }
+        // Check for module declaration: `module library;`
+        // Library-mode: all functions parsed from this point are marked isLibraryFn=true.
+        // When using the `librarySources` compile option, each library source is parsed
+        // by its own fresh Parser — so this flag never bleeds into user code.
+        if (this.check('module')) {
+            this.advance();
+            const modKind = this.expect('ident');
+            if (modKind.value === 'library') {
+                isLibrary = true;
+                this.inLibraryMode = true;
+            }
+            this.expect(';');
+        }
         // Parse struct and function declarations
         while (!this.check('eof')) {
             if (this.check('let')) {
@@ -168,7 +187,7 @@ class Parser {
                 declarations.push(this.parseFnDecl());
             }
         }
-        return { namespace, globals, declarations, structs, implBlocks, enums, consts };
+        return { namespace, globals, declarations, structs, implBlocks, enums, consts, isLibrary };
     }
     // -------------------------------------------------------------------------
     // Struct Declaration
@@ -267,7 +286,8 @@ class Parser {
             returnType = this.parseType();
         }
         const body = this.parseBlock();
-        return this.withLoc({ name, params, returnType, decorators, body }, fnToken);
+        const fn = this.withLoc({ name, params, returnType, decorators, body, isLibraryFn: this.inLibraryMode || undefined }, fnToken);
+        return fn;
     }
     /** Parse a `declare fn name(params): returnType;` stub — no body, just discard. */
     parseDeclareStub() {
@@ -336,6 +356,27 @@ class Parser {
                 return { name, args };
             }
         }
+        // @require_on_load(fn_name) — when this fn is used, fn_name is called from __load.
+        // Accepts bare identifiers (with optional leading _) or quoted strings.
+        if (name === 'require_on_load') {
+            const rawArgs = [];
+            for (const part of argsStr.split(',')) {
+                const trimmed = part.trim();
+                // Bare identifier: @require_on_load(_math_init)
+                const identMatch = trimmed.match(/^([A-Za-z_][A-Za-z0-9_]*)$/);
+                if (identMatch) {
+                    rawArgs.push({ kind: 'string', value: identMatch[1] });
+                }
+                else {
+                    // Quoted string fallback: @require_on_load("_math_init")
+                    const strMatch = trimmed.match(/^"([^"]*)"$/);
+                    if (strMatch) {
+                        rawArgs.push({ kind: 'string', value: strMatch[1] });
+                    }
+                }
+            }
+            return { name, rawArgs };
+        }
         // Handle key=value format (e.g., rate=20)
         for (const part of argsStr.split(',')) {
             const [key, val] = part.split('=').map(s => s.trim());

package/dist/reqtest.map.json

@@ -0,0 +1,4 @@
+{
+  "$a": "const:42",
+  "$b": "internal:ret"
+}

package/dist/reqtest2.map.json

@@ -0,0 +1,4 @@
+{
+  "$a": "const:42",
+  "$b": "internal:ret"
+}

package/dist/runtime/index.d.ts

@@ -43,6 +43,7 @@ export declare class MCRuntime {
     private entityIdCounter;
     private returnValue;
     private shouldReturn;
+    private currentMacroContext;
     constructor(namespace: string);
     loadDatapack(dir: string): void;
     loadFunction(name: string, lines: string[]): void;
@@ -56,8 +57,13 @@ export declare class MCRuntime {
     private execExecute;
     private parseNextSelector;
     private execFunctionCmd;
+    /** Expand MC macro placeholders: $(key) → value from currentMacroContext */
+    private expandMacro;
     private execData;
     private parseDataValue;
+    /** Return the whole storage compound at storagePath as a flat key→value map.
+     *  Used by 'function ... with storage' to provide macro context. */
+    private getStorageCompound;
     private getStorageField;
     private setStorageField;
     private removeStorageField;