redscript-mc 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to RedScript will be documented in this file.
 
+## [2.4.0] - 2026-03-17
+
+### Added
+- Dynamic array index read: `arr[i]` where `i` is a variable (MC Function Macro, MC 1.20.2+)
+- Dynamic array index write: `arr[i] = val`, `arr[i] += val` compound assignment
+- `list_push(arr, val)` / `list_pop(arr)` / `list_len(arr)` builtins for NBT array manipulation
+
+### Known Limitations
+- Array parameters in function calls do not pass the array by reference yet; use `while` loops with dynamic index directly in the calling scope
+- `for` loops with dynamic array access may incorrectly inline when loop bounds are constants; use `while` loops instead
+
 ## [2.3.0] - 2026-03-17
 
 ### Added

package/dist/src/__tests__/array-dynamic.test.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Tests for dynamic array index read: arr[i] where i is a variable.
+ *
+ * Covers:
+ * - MIR: nbt_read_dynamic instruction is emitted instead of falling back to
+ *   copy(obj) (which returned the array length, not the value)
+ * - LIR/Emit: generates a macro helper function and calls it with
+ *   `function ns:__dyn_idx_... with storage rs:macro_args`
+ * - The generated .mcfunction contains 'with storage' (function macro call)
+ * - The helper function contains the $return macro line
+ */
+export {};

package/dist/src/__tests__/array-dynamic.test.js

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * Tests for dynamic array index read: arr[i] where i is a variable.
+ *
+ * Covers:
+ * - MIR: nbt_read_dynamic instruction is emitted instead of falling back to
+ *   copy(obj) (which returned the array length, not the value)
+ * - LIR/Emit: generates a macro helper function and calls it with
+ *   `function ns:__dyn_idx_... with storage rs:macro_args`
+ * - The generated .mcfunction contains 'with storage' (function macro call)
+ * - The helper function contains the $return macro line
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const compile_1 = require("../emit/compile");
+// Helper: find file in compiled output by path substring
+function getFile(files, pathSubstr) {
+    const f = files.find(f => f.path.includes(pathSubstr));
+    return f?.content;
+}
+// Helper: get the content of the function file for `fnName` in namespace
+function getFunctionBody(files, fnName, ns = 'test') {
+    const content = getFile(files, `${fnName}.mcfunction`);
+    if (!content) {
+        // list files for debug
+        const paths = files.map(f => f.path).join('\n');
+        throw new Error(`Function '${fnName}' not found in output. Files:\n${paths}`);
+    }
+    return content;
+}
+describe('Dynamic array index read: arr[i]', () => {
+    const src = `
+    fn test() {
+      let nums: int[] = [10, 20, 30, 40, 50];
+      let i: int = 2;
+      i = i + 1;
+      let v: int = nums[i];
+      scoreboard_set("#out", "test", v);
+    }
+  `;
+    let files;
+    beforeAll(() => {
+        const result = (0, compile_1.compile)(src, { namespace: 'test' });
+        files = result.files;
+    });
+    test('compiles without error', () => {
+        // beforeAll would have thrown if compilation failed
+        expect(files.length).toBeGreaterThan(0);
+    });
+    test('test function contains "with storage" (macro call)', () => {
+        const body = getFunctionBody(files, 'test');
+        expect(body).toContain('with storage');
+    });
+    test('test function does NOT contain fallback "scoreboard players set #out test 5"', () => {
+        // Old fallback would copy the array length (5 elements) as the result
+        const body = getFunctionBody(files, 'test');
+        expect(body).not.toContain('scoreboard players set #out test 5');
+    });
+    test('a macro helper function is generated for the array', () => {
+        // Should have a function file matching __dyn_idx_
+        const helperFile = files.find(f => f.path.includes('__dyn_idx_'));
+        expect(helperFile).toBeDefined();
+    });
+    test('macro helper function contains $return run data get', () => {
+        const helperFile = files.find(f => f.path.includes('__dyn_idx_'));
+        expect(helperFile).toBeDefined();
+        expect(helperFile.content).toContain('$return run data get');
+        expect(helperFile.content).toContain('$(arr_idx)');
+    });
+    test('macro helper function references the correct array path (nums)', () => {
+        const helperFile = files.find(f => f.path.includes('__dyn_idx_'));
+        expect(helperFile).toBeDefined();
+        expect(helperFile.content).toContain('nums[$(arr_idx)]');
+    });
+    test('test function stores index to rs:macro_args', () => {
+        const body = getFunctionBody(files, 'test');
+        // Should store the index value into rs:macro_args arr_idx
+        expect(body).toContain('rs:macro_args');
+    });
+});
+describe('Dynamic array index: constant index still uses direct nbt_read', () => {
+    const src = `
+    fn test_const() {
+      let nums: int[] = [10, 20, 30];
+      let v: int = nums[1];
+      scoreboard_set("#out", "test", v);
+    }
+  `;
+    let files;
+    beforeAll(() => {
+        const result = (0, compile_1.compile)(src, { namespace: 'test' });
+        files = result.files;
+    });
+    test('constant index does NOT generate macro call (uses direct data get)', () => {
+        const body = getFunctionBody(files, 'test_const');
+        // Direct nbt_read emits store_nbt_to_score → execute store result score ... run data get ...
+        // without 'with storage'
+        expect(body).not.toContain('with storage');
+        expect(body).toContain('data get storage');
+        expect(body).toContain('nums[1]');
+    });
+});
+describe('Dynamic array index: multiple arrays, separate helpers', () => {
+    const src = `
+    fn test_multi() {
+      let a: int[] = [1, 2, 3];
+      let b: int[] = [10, 20, 30];
+      let i: int = 1;
+      i = i + 0;
+      let va: int = a[i];
+      let vb: int = b[i];
+      scoreboard_set("#va", "test", va);
+      scoreboard_set("#vb", "test", vb);
+    }
+  `;
+    let files;
+    beforeAll(() => {
+        const result = (0, compile_1.compile)(src, { namespace: 'test' });
+        files = result.files;
+    });
+    test('two separate macro helpers are generated for arrays a and b', () => {
+        const helperFiles = files.filter(f => f.path.includes('__dyn_idx_'));
+        expect(helperFiles.length).toBe(2);
+    });
+    test('each helper references its respective array path', () => {
+        const helperFiles = files.filter(f => f.path.includes('__dyn_idx_'));
+        const contents = helperFiles.map(f => f.content).join('\n');
+        expect(contents).toContain('a[$(arr_idx)]');
+        expect(contents).toContain('b[$(arr_idx)]');
+    });
+});
+//# sourceMappingURL=array-dynamic.test.js.map

package/dist/src/__tests__/array-write.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Tests for array index write: arr[i] = val (constant and dynamic index).
+ *
+ * Covers:
+ * - Parser: arr[i] = val parses as index_assign (no "Expected ';'" error)
+ * - MIR: constant index → nbt_write, dynamic index → nbt_write_dynamic
+ * - LIR/Emit: constant index uses store_score_to_nbt to path[N]
+ *             dynamic index generates a macro helper function for write
+ * - Compound assignments: arr[i] += 5 desugars to read + write
+ */
+export {};

package/dist/src/__tests__/array-write.test.js

@@ -0,0 +1,149 @@
+"use strict";
+/**
+ * Tests for array index write: arr[i] = val (constant and dynamic index).
+ *
+ * Covers:
+ * - Parser: arr[i] = val parses as index_assign (no "Expected ';'" error)
+ * - MIR: constant index → nbt_write, dynamic index → nbt_write_dynamic
+ * - LIR/Emit: constant index uses store_score_to_nbt to path[N]
+ *             dynamic index generates a macro helper function for write
+ * - Compound assignments: arr[i] += 5 desugars to read + write
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const compile_1 = require("../emit/compile");
+// Helper: find file in compiled output by path substring
+function getFile(files, pathSubstr) {
+    const f = files.find(f => f.path.includes(pathSubstr));
+    return f?.content;
+}
+// Helper: get the content of the function file for `fnName` in namespace
+function getFunctionBody(files, fnName, ns = 'test') {
+    const content = getFile(files, `${fnName}.mcfunction`);
+    if (!content) {
+        const paths = files.map(f => f.path).join('\n');
+        throw new Error(`Function '${fnName}' not found in output. Files:\n${paths}`);
+    }
+    return content;
+}
+// ---------------------------------------------------------------------------
+// Constant index write: arr[1] = 99
+// ---------------------------------------------------------------------------
+describe('Constant index write: arr[1] = 99', () => {
+    const src = `
+    fn test() {
+      let nums: int[] = [10, 20, 30];
+      nums[1] = 99;
+      scoreboard_set("#out", "test", nums[1]);
+    }
+  `;
+    let files;
+    beforeAll(() => {
+        const result = (0, compile_1.compile)(src, { namespace: 'test' });
+        files = result.files;
+    });
+    test('compiles without error', () => {
+        expect(files.length).toBeGreaterThan(0);
+    });
+    test('test function contains nbt store to array path [1] (constant write)', () => {
+        const body = getFunctionBody(files, 'test');
+        // Should write to path like "nums[1]" via execute store result storage
+        expect(body).toMatch(/nums\[1\]/);
+    });
+    test('test function reads back from nums[1] after writing', () => {
+        const body = getFunctionBody(files, 'test');
+        // Should also read nums[1] for scoreboard_set
+        expect(body).toMatch(/nums\[1\]/);
+    });
+});
+// ---------------------------------------------------------------------------
+// Dynamic index write: arr[i] = 99
+// ---------------------------------------------------------------------------
+describe('Dynamic index write: arr[i] = 99', () => {
+    const src = `
+    fn test() {
+      let nums: int[] = [10, 20, 30];
+      let i: int = 1;
+      nums[i] = 99;
+      scoreboard_set("#out", "test", nums[i]);
+    }
+  `;
+    let files;
+    beforeAll(() => {
+        const result = (0, compile_1.compile)(src, { namespace: 'test' });
+        files = result.files;
+    });
+    test('compiles without error', () => {
+        expect(files.length).toBeGreaterThan(0);
+    });
+    test('test function contains "with storage" (macro call for write)', () => {
+        const body = getFunctionBody(files, 'test');
+        expect(body).toContain('with storage');
+    });
+    test('a __dyn_wrt_ helper function is generated', () => {
+        const helperFile = files.find(f => f.path.includes('__dyn_wrt_'));
+        expect(helperFile).toBeDefined();
+    });
+    test('the write helper contains a macro line with arr_idx and arr_val', () => {
+        const helperFile = files.find(f => f.path.includes('__dyn_wrt_'));
+        expect(helperFile).toBeDefined();
+        expect(helperFile.content).toContain('$(arr_idx)');
+        expect(helperFile.content).toContain('$(arr_val)');
+    });
+    test('the write helper uses data modify set value', () => {
+        const helperFile = files.find(f => f.path.includes('__dyn_wrt_'));
+        expect(helperFile.content).toContain('data modify storage');
+        expect(helperFile.content).toContain('set value');
+    });
+});
+// ---------------------------------------------------------------------------
+// Compound assignment: arr[i] += 5
+// ---------------------------------------------------------------------------
+describe('Compound index assignment: arr[i] += 5', () => {
+    const src = `
+    fn test() {
+      let nums: int[] = [10, 20, 30];
+      let i: int = 0;
+      nums[i] += 5;
+      scoreboard_set("#out", "test", nums[i]);
+    }
+  `;
+    let files;
+    beforeAll(() => {
+        const result = (0, compile_1.compile)(src, { namespace: 'test' });
+        files = result.files;
+    });
+    test('compiles without error', () => {
+        expect(files.length).toBeGreaterThan(0);
+    });
+    test('compound assignment generates both read and write macro calls', () => {
+        const body = getFunctionBody(files, 'test');
+        // Should call with storage at least twice (read for += and write + scoreboard_set read)
+        const matches = (body.match(/with storage/g) || []).length;
+        expect(matches).toBeGreaterThanOrEqual(1);
+    });
+});
+// ---------------------------------------------------------------------------
+// Constant compound assignment: arr[0] += 5
+// ---------------------------------------------------------------------------
+describe('Constant compound index assignment: arr[0] += 5', () => {
+    const src = `
+    fn test() {
+      let nums: int[] = [10, 20, 30];
+      nums[0] += 5;
+      scoreboard_set("#out", "test", nums[0]);
+    }
+  `;
+    let files;
+    beforeAll(() => {
+        const result = (0, compile_1.compile)(src, { namespace: 'test' });
+        files = result.files;
+    });
+    test('compiles without error', () => {
+        expect(files.length).toBeGreaterThan(0);
+    });
+    test('test function contains array path [0] for read and write', () => {
+        const body = getFunctionBody(files, 'test');
+        expect(body).toMatch(/nums\[0\]/);
+    });
+});
+//# sourceMappingURL=array-write.test.js.map

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

@@ -228,6 +228,13 @@ export type Expr = {
     obj: Expr;
     index: Expr;
     span?: Span;
+} | {
+    kind: 'index_assign';
+    obj: Expr;
+    index: Expr;
+    op: AssignOp;
+    value: Expr;
+    span?: Span;
 } | {
     kind: 'array_lit';
     elements: Expr[];

package/dist/src/emit/modules.js

@@ -465,6 +465,11 @@ function rewriteExpr(expr, symbolMap) {
             rewriteExpr(expr.obj, symbolMap);
             rewriteExpr(expr.index, symbolMap);
             break;
+        case 'index_assign':
+            rewriteExpr(expr.obj, symbolMap);
+            rewriteExpr(expr.index, symbolMap);
+            rewriteExpr(expr.value, symbolMap);
+            break;
         case 'array_lit':
             for (const el of expr.elements)
                 rewriteExpr(el, symbolMap);

package/dist/src/hir/lower.js

@@ -360,6 +360,35 @@ function lowerExpr(expr) {
             return { kind: 'member', obj: lowerExpr(expr.obj), field: expr.field, span: expr.span };
         case 'index':
             return { kind: 'index', obj: lowerExpr(expr.obj), index: lowerExpr(expr.index), span: expr.span };
+        // --- Desugaring: compound index_assign → plain index_assign ---
+        case 'index_assign':
+            if (expr.op !== '=') {
+                const binOp = COMPOUND_TO_BINOP[expr.op];
+                const obj = lowerExpr(expr.obj);
+                const index = lowerExpr(expr.index);
+                return {
+                    kind: 'index_assign',
+                    obj,
+                    index,
+                    op: '=',
+                    value: {
+                        kind: 'binary',
+                        op: binOp,
+                        left: { kind: 'index', obj, index },
+                        right: lowerExpr(expr.value),
+                        span: expr.span,
+                    },
+                    span: expr.span,
+                };
+            }
+            return {
+                kind: 'index_assign',
+                obj: lowerExpr(expr.obj),
+                index: lowerExpr(expr.index),
+                op: expr.op,
+                value: lowerExpr(expr.value),
+                span: expr.span,
+            };
         case 'call':
             return { kind: 'call', fn: expr.fn, args: expr.args.map(lowerExpr), typeArgs: expr.typeArgs, span: expr.span };
         case 'invoke':

package/dist/src/hir/monomorphize.js

@@ -278,6 +278,8 @@ class Monomorphizer {
                 return { ...expr, value: this.rewriteExpr(expr.value, ctx) };
             case 'member_assign':
                 return { ...expr, obj: this.rewriteExpr(expr.obj, ctx), value: this.rewriteExpr(expr.value, ctx) };
+            case 'index_assign':
+                return { ...expr, obj: this.rewriteExpr(expr.obj, ctx), index: this.rewriteExpr(expr.index, ctx), value: this.rewriteExpr(expr.value, ctx) };
             case 'member':
                 return { ...expr, obj: this.rewriteExpr(expr.obj, ctx) };
             case 'index':

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

@@ -12,8 +12,8 @@
  * All types and names are preserved from the AST.
  */
 import type { Span, TypeNode, EntitySelector, CoordComponent, Decorator, RangeExpr, FStringPart, SelectorFilter, EntityTypeName, LambdaParam } from '../ast/types';
-import type { BinOp, CmpOp } from '../ast/types';
-export type { Span, TypeNode, EntitySelector, CoordComponent, Decorator, RangeExpr, FStringPart, SelectorFilter, EntityTypeName, LambdaParam, BinOp, CmpOp, };
+import type { BinOp, CmpOp, AssignOp } from '../ast/types';
+export type { Span, TypeNode, EntitySelector, CoordComponent, Decorator, RangeExpr, FStringPart, SelectorFilter, EntityTypeName, LambdaParam, BinOp, CmpOp, AssignOp, };
 export type HIRExpr = {
     kind: 'int_lit';
     value: number;
@@ -124,6 +124,13 @@ export type HIRExpr = {
     field: string;
     value: HIRExpr;
     span?: Span;
+} | {
+    kind: 'index_assign';
+    obj: HIRExpr;
+    index: HIRExpr;
+    op: AssignOp;
+    value: HIRExpr;
+    span?: Span;
 } | {
     kind: 'member';
     obj: HIRExpr;

package/dist/src/lir/lower.js

@@ -41,6 +41,10 @@ class LoweringContext {
         this.currentMIRFn = null;
         /** Block map for quick lookup */
         this.blockMap = new Map();
+        /** Track generated dynamic array macro helper functions to avoid duplicates: key → fn name */
+        this.dynIdxHelpers = new Map();
+        /** Track generated dynamic array write helper functions: key → fn name */
+        this.dynWrtHelpers = new Map();
         this.namespace = namespace;
         this.objective = objective;
     }
@@ -62,6 +66,68 @@ class LoweringContext {
     addFunction(fn) {
         this.functions.push(fn);
     }
+    /**
+     * Get or create a macro helper function for dynamic array index reads.
+     * The helper function is: $return run data get storage <ns> <pathPrefix>[$(arr_idx)] 1
+     * Returns the qualified MC function name (namespace:fnName).
+     */
+    getDynIdxHelper(ns, pathPrefix) {
+        const key = `${ns}\0${pathPrefix}`;
+        const existing = this.dynIdxHelpers.get(key);
+        if (existing)
+            return existing;
+        // Generate deterministic name from ns and pathPrefix
+        const sanitize = (s) => s.replace(/[^a-z0-9_]/gi, '_').toLowerCase();
+        // Extract just the storage name part from ns (e.g. "myns:arrays" → "myns_arrays")
+        const nsStr = sanitize(ns);
+        const prefixStr = sanitize(pathPrefix);
+        const helperName = `__dyn_idx_${nsStr}_${prefixStr}`;
+        // The helper is placed in the current namespace
+        const qualifiedName = `${this.namespace}:${helperName}`;
+        // Generate the macro function content:
+        // $return run data get storage <ns> <pathPrefix>[$(arr_idx)] 1
+        const macroLine = {
+            kind: 'macro_line',
+            template: `return run data get storage ${ns} ${pathPrefix}[$(arr_idx)] 1`,
+        };
+        this.addFunction({
+            name: helperName,
+            instructions: [macroLine],
+            isMacro: true,
+            macroParams: ['arr_idx'],
+        });
+        this.dynIdxHelpers.set(key, qualifiedName);
+        return qualifiedName;
+    }
+    /**
+     * Get or create a macro helper function for dynamic array index writes.
+     * The helper function: $data modify storage <ns> <pathPrefix>[$(arr_idx)] set value $(arr_val)
+     * Returns the qualified MC function name.
+     */
+    getDynWrtHelper(ns, pathPrefix) {
+        const key = `${ns}\0${pathPrefix}`;
+        const existing = this.dynWrtHelpers.get(key);
+        if (existing)
+            return existing;
+        const sanitize = (s) => s.replace(/[^a-z0-9_]/gi, '_').toLowerCase();
+        const nsStr = sanitize(ns);
+        const prefixStr = sanitize(pathPrefix);
+        const helperName = `__dyn_wrt_${nsStr}_${prefixStr}`;
+        const qualifiedName = `${this.namespace}:${helperName}`;
+        // Macro line: $data modify storage <ns> <pathPrefix>[$(arr_idx)] set value $(arr_val)
+        const macroLine = {
+            kind: 'macro_line',
+            template: `data modify storage ${ns} ${pathPrefix}[$(arr_idx)] set value $(arr_val)`,
+        };
+        this.addFunction({
+            name: helperName,
+            instructions: [macroLine],
+            isMacro: true,
+            macroParams: ['arr_idx', 'arr_val'],
+        });
+        this.dynWrtHelpers.set(key, qualifiedName);
+        return qualifiedName;
+    }
     /** Attach sourceLoc to newly added instructions (from the given start index onward) */
     tagSourceLoc(instrs, fromIndex, sourceLoc) {
         if (!sourceLoc)
@@ -263,6 +329,41 @@ function lowerInstrInner(instr, fn, ctx, instrs) {
             });
             break;
         }
+        case 'nbt_read_dynamic': {
+            // Strategy:
+            // 1. Store the index value into rs:macro_args __arr_idx (int)
+            // 2. Call the per-array macro helper function with 'with storage rs:macro_args'
+            // 3. Result comes back via $ret scoreboard slot (the macro uses $return)
+            const dst = ctx.slot(instr.dst);
+            const idxSlot = operandToSlot(instr.indexSrc, ctx, instrs);
+            // Step 1: store index score → rs:macro_args arr_idx (int, scale 1)
+            instrs.push({
+                kind: 'store_score_to_nbt',
+                ns: 'rs:macro_args',
+                path: 'arr_idx',
+                type: 'int',
+                scale: 1,
+                src: idxSlot,
+            });
+            // Step 2: get or create the macro helper function, then call it
+            const helperFn = ctx.getDynIdxHelper(instr.ns, instr.pathPrefix);
+            instrs.push({ kind: 'call_macro', fn: helperFn, storage: 'rs:macro_args' });
+            // Step 3: the macro uses $return which sets the MC return value.
+            // We need to capture that. In MC, $return run ... returns the result
+            // to the caller via the execute store mechanism.
+            // Use store_cmd_to_score to capture the return value of the macro call.
+            // Actually, the call_macro instruction above already ran the function.
+            // The $return run data get ... sets the scoreboard return value for the
+            // *calling* function context. We need to use execute store result score.
+            // Rewrite: use raw command instead:
+            instrs.pop(); // remove the call_macro we just added
+            instrs.push({
+                kind: 'store_cmd_to_score',
+                dst,
+                cmd: { kind: 'call_macro', fn: helperFn, storage: 'rs:macro_args' },
+            });
+            break;
+        }
         case 'nbt_write': {
             const srcSlot = operandToSlot(instr.src, ctx, instrs);
             instrs.push({
@@ -275,6 +376,36 @@ function lowerInstrInner(instr, fn, ctx, instrs) {
             });
             break;
         }
+        case 'nbt_write_dynamic': {
+            // Strategy:
+            // 1. Store index score → rs:macro_args arr_idx (int)
+            // 2. Store value score → rs:macro_args arr_val (int)
+            // 3. Call macro helper: $data modify storage <ns> <pathPrefix>[$(arr_idx)] set value $(arr_val)
+            const idxSlot = operandToSlot(instr.indexSrc, ctx, instrs);
+            const valSlot = operandToSlot(instr.valueSrc, ctx, instrs);
+            // Store index
+            instrs.push({
+                kind: 'store_score_to_nbt',
+                ns: 'rs:macro_args',
+                path: 'arr_idx',
+                type: 'int',
+                scale: 1,
+                src: idxSlot,
+            });
+            // Store value
+            instrs.push({
+                kind: 'store_score_to_nbt',
+                ns: 'rs:macro_args',
+                path: 'arr_val',
+                type: 'int',
+                scale: 1,
+                src: valSlot,
+            });
+            // Call macro helper function
+            const helperFn = ctx.getDynWrtHelper(instr.ns, instr.pathPrefix);
+            instrs.push({ kind: 'call_macro', fn: helperFn, storage: 'rs:macro_args' });
+            break;
+        }
         case 'score_read': {
             // execute store result score $dst __obj run scoreboard players get <player> <obj>
             const dst = ctx.slot(instr.dst);