redscript-mc 1.2.25 → 1.2.26

package/dist/lowering/index.js

@@ -128,6 +128,8 @@ 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)
 };
 function getSpan(node) {
     return node?.span;
@@ -196,6 +198,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]
@@ -564,13 +573,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 +590,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 +662,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 +802,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 +1078,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 +1237,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 +2245,50 @@ 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 };
+        }
         // data_merge(target, nbt) — merge NBT into entity/block/storage
         // data_merge(@s, { Invisible: 1b, Silent: 1b })
         if (name === 'data_merge') {
@@ -3006,7 +3079,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/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/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/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;

package/dist/runtime/index.js

@@ -235,6 +235,8 @@ class MCRuntime {
         this.entityIdCounter = 0;
         // Flag to stop function execution (for return)
         this.shouldReturn = false;
+        // Current MC macro context: key → value (set by 'function ... with storage')
+        this.currentMacroContext = null;
         this.namespace = namespace;
         // Initialize default objective
         this.scoreboard.set('rs', new Map());
@@ -321,6 +323,12 @@ class MCRuntime {
         cmd = cmd.trim();
         if (!cmd || cmd.startsWith('#'))
             return true;
+        // MC macro command: line starts with '$'.
+        // Expand $(key) placeholders from currentMacroContext, then execute.
+        if (cmd.startsWith('$')) {
+            const expanded = this.expandMacro(cmd.slice(1));
+            return this.execCommand(expanded, executor);
+        }
         // Parse command
         if (cmd.startsWith('scoreboard ')) {
             return this.execScoreboard(cmd);
@@ -502,7 +510,12 @@ class MCRuntime {
                     const value = storeTarget.type === 'result'
                         ? (this.returnValue ?? (result ? 1 : 0))
                         : (result ? 1 : 0);
-                    this.setScore(storeTarget.player, storeTarget.objective, value);
+                    if ('storagePath' in storeTarget) {
+                        this.setStorageField(storeTarget.storagePath, storeTarget.field, value);
+                    }
+                    else {
+                        this.setScore(storeTarget.player, storeTarget.objective, value);
+                    }
                 }
                 return result;
             }
@@ -577,15 +590,44 @@ class MCRuntime {
             // Handle 'unless score ...'
             if (rest.startsWith('unless score ')) {
                 rest = rest.slice(13);
-                const scoreParts = rest.match(/^(\S+)\s+(\S+)\s+matches\s+(\S+)(.*)$/);
-                if (scoreParts) {
-                    const [, player, obj, rangeStr, remaining] = scoreParts;
+                // unless score <player> <obj> matches <range>
+                const matchesParts = rest.match(/^(\S+)\s+(\S+)\s+matches\s+(\S+)(.*)$/);
+                if (matchesParts) {
+                    const [, player, obj, rangeStr, remaining] = matchesParts;
                     const range = parseRange(rangeStr);
                     const score = this.getScore(player, obj);
                     condition = condition && !matchesRange(score, range);
                     rest = remaining.trim();
                     continue;
                 }
+                // unless score <p1> <o1> <op> <p2> <o2>
+                const compareMatch = rest.match(/^(\S+)\s+(\S+)\s+([<>=]+)\s+(\S+)\s+(\S+)(.*)$/);
+                if (compareMatch) {
+                    const [, p1, o1, op, p2, o2, remaining] = compareMatch;
+                    const v1 = this.getScore(p1, o1);
+                    const v2 = this.getScore(p2, o2);
+                    let matches = false;
+                    switch (op) {
+                        case '=':
+                            matches = v1 === v2;
+                            break;
+                        case '<':
+                            matches = v1 < v2;
+                            break;
+                        case '<=':
+                            matches = v1 <= v2;
+                            break;
+                        case '>':
+                            matches = v1 > v2;
+                            break;
+                        case '>=':
+                            matches = v1 >= v2;
+                            break;
+                    }
+                    condition = condition && !matches; // unless = negate
+                    rest = remaining.trim();
+                    continue;
+                }
             }
             // Handle 'if entity <selector>'
             if (rest.startsWith('if entity ')) {
@@ -605,6 +647,18 @@ class MCRuntime {
                 condition = condition && entities.length === 0;
                 continue;
             }
+            // Handle 'store result storage <ns:path> <field> <type> <scale>'
+            if (rest.startsWith('store result storage ')) {
+                rest = rest.slice(21);
+                // format: <ns:path> <field> <type> <scale> <run-cmd>
+                const storageParts = rest.match(/^(\S+)\s+(\S+)\s+(\S+)\s+([\d.]+)\s+(.*)$/);
+                if (storageParts) {
+                    const [, storagePath, field, , , remaining] = storageParts;
+                    storeTarget = { storagePath, field, type: 'result' };
+                    rest = remaining.trim();
+                    continue;
+                }
+            }
             // Handle 'store result score <player> <obj>'
             if (rest.startsWith('store result score ')) {
                 rest = rest.slice(19);
@@ -637,7 +691,12 @@ class MCRuntime {
             const value = storeTarget.type === 'result'
                 ? (this.returnValue ?? (condition ? 1 : 0))
                 : (condition ? 1 : 0);
-            this.setScore(storeTarget.player, storeTarget.objective, value);
+            if ('storagePath' in storeTarget) {
+                this.setStorageField(storeTarget.storagePath, storeTarget.field, value);
+            }
+            else {
+                this.setScore(storeTarget.player, storeTarget.objective, value);
+            }
         }
         return condition;
     }
@@ -659,12 +718,35 @@ class MCRuntime {
     // Function Command
     // -------------------------------------------------------------------------
     execFunctionCmd(cmd, executor) {
-        const fnName = cmd.slice(9).trim(); // remove 'function '
+        let fnRef = cmd.slice(9).trim(); // remove 'function '
+        // Handle 'function ns:name with storage ns:path' — MC macro calling convention.
+        // The called function may have $( ) placeholders that need to be expanded
+        // using the provided storage compound. We execute the function after
+        // expanding its macro context.
+        const withStorageMatch = fnRef.match(/^(\S+)\s+with\s+storage\s+(\S+)$/);
+        if (withStorageMatch) {
+            const [, actualFnName, storagePath] = withStorageMatch;
+            const macroContext = this.getStorageCompound(storagePath) ?? {};
+            const outerShouldReturn = this.shouldReturn;
+            const outerMacroCtx = this.currentMacroContext;
+            this.currentMacroContext = macroContext;
+            this.execFunction(actualFnName, executor);
+            this.currentMacroContext = outerMacroCtx;
+            this.shouldReturn = outerShouldReturn;
+            return true;
+        }
         const outerShouldReturn = this.shouldReturn;
-        this.execFunction(fnName, executor);
+        this.execFunction(fnRef, executor);
         this.shouldReturn = outerShouldReturn;
         return true;
     }
+    /** Expand MC macro placeholders: $(key) → value from currentMacroContext */
+    expandMacro(cmd) {
+        return cmd.replace(/\$\(([^)]+)\)/g, (_, key) => {
+            const val = this.currentMacroContext?.[key];
+            return val !== undefined ? String(val) : `$(${key})`;
+        });
+    }
     // -------------------------------------------------------------------------
     // Data Commands
     // -------------------------------------------------------------------------
@@ -689,8 +771,18 @@ class MCRuntime {
             }
             return true;
         }
-        // data get storage <ns:path> <field>
-        const getMatch = cmd.match(/^data get storage (\S+) (\S+)$/);
+        // data get storage <ns:path> <field>[<index>] [scale]  (array element access)
+        const getArrMatch = cmd.match(/^data get storage (\S+) (\S+)\[(\d+)\](?:\s+[\d.]+)?$/);
+        if (getArrMatch) {
+            const [, storagePath, field, indexStr] = getArrMatch;
+            const arr = this.getStorageField(storagePath, field);
+            const idx = parseInt(indexStr, 10);
+            const value = Array.isArray(arr) ? arr[idx] : undefined;
+            this.returnValue = typeof value === 'number' ? value : 0;
+            return true;
+        }
+        // data get storage <ns:path> <field> [scale]
+        const getMatch = cmd.match(/^data get storage (\S+) (\S+)(?:\s+[\d.]+)?$/);
         if (getMatch) {
             const [, storagePath, field] = getMatch;
             const value = this.getStorageField(storagePath, field);
@@ -736,6 +828,14 @@ class MCRuntime {
             return str;
         }
     }
+    /** Return the whole storage compound at storagePath as a flat key→value map.
+     *  Used by 'function ... with storage' to provide macro context. */
+    getStorageCompound(storagePath) {
+        const data = this.storage.get(storagePath);
+        if (!data || typeof data !== 'object' || Array.isArray(data))
+            return null;
+        return data;
+    }
     getStorageField(storagePath, field) {
         const data = this.storage.get(storagePath) ?? {};
         const segments = this.parseStoragePath(field);

package/editors/vscode/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "redscript-vscode",
-  "version": "1.0.16",
+  "version": "1.0.28",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "redscript-vscode",
-      "version": "1.0.16",
+      "version": "1.0.28",
       "license": "MIT",
       "dependencies": {
         "redscript": "file:../../"
@@ -23,7 +23,7 @@
     },
     "../..": {
       "name": "redscript-mc",
-      "version": "1.2.25",
+      "version": "1.2.26",
       "license": "MIT",
       "bin": {
         "redscript": "dist/cli.js",

package/editors/vscode/package.json

@@ -2,7 +2,7 @@
   "name": "redscript-vscode",
   "displayName": "RedScript for Minecraft",
   "description": "Syntax highlighting, error diagnostics, and language support for RedScript — a compiler targeting Minecraft Java Edition",
-  "version": "1.0.16",
+  "version": "1.0.28",
   "publisher": "bkmashiro",
   "icon": "icon.png",
   "license": "MIT",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "redscript-mc",
-  "version": "1.2.25",
+  "version": "1.2.26",
   "description": "A high-level programming language that compiles to Minecraft datapacks",
   "main": "dist/index.js",
   "bin": {

package/src/__tests__/cli.test.ts

@@ -173,7 +173,7 @@ describe('CLI API', () => {
       const mainFn = result.files.find(file => file.path.endsWith('/main.mcfunction'))
       expect(doneFn?.content).toContain('scoreboard players get timer_ticks rs')
       expect(doneFn?.content).toContain('return run scoreboard players get')
-      expect(mainFn?.content).toContain('execute if score $finished rs matches 1..')
+      expect(mainFn?.content).toContain('execute if score $main_finished rs matches 1..')
     })
 
     it('Timer.tick increments', () => {