redscript-mc 1.2.26 → 1.2.27

package/src/__tests__/stdlib-bigint.test.ts

@@ -0,0 +1,427 @@
+/**
+ * stdlib/bigint.mcrs — runtime behavioural tests
+ *
+ * Tests basic BigInt operations (base 10000, 8 limbs = 32 decimal digits).
+ * All arithmetic validated against known values.
+ */
+
+import * as fs from 'fs'
+import * as path from 'path'
+import { compile } from '../compile'
+import { MCRuntime } from '../runtime'
+
+const MATH_SRC   = fs.readFileSync(path.join(__dirname, '../../src/stdlib/math.mcrs'), 'utf-8')
+const BIGINT_SRC = fs.readFileSync(path.join(__dirname, '../../src/stdlib/bigint.mcrs'), 'utf-8')
+
+function run(driver: string): MCRuntime {
+  const result = compile(driver, {
+    namespace: 'bitest',
+    librarySources: [MATH_SRC, BIGINT_SRC],
+  })
+  if (!result.success) throw new Error(result.error?.message ?? 'compile failed')
+  const rt = new MCRuntime('bitest')
+  for (const file of result.files ?? []) {
+    if (!file.path.endsWith('.mcfunction')) continue
+    const match = file.path.match(/data\/([^/]+)\/function\/(.+)\.mcfunction$/)
+    if (!match) continue
+    rt.loadFunction(`${match[1]}:${match[2]}`, file.content.split('\n'))
+  }
+  rt.load()
+  return rt
+}
+
+function sc(rt: MCRuntime, key: string): number {
+  return rt.getScore('out', `bitest.${key}`) ?? 0
+}
+
+// ── storage_set_int roundtrip ─────────────────────────────────────────────────
+
+describe('storage_set_int roundtrip', () => {
+  it('static index: write 99 to arr[2], read back', () => {
+    const rt = run(`fn test() {
+      storage_set_array("rs:t", "arr", "[10,20,30,40]");
+      storage_set_int("rs:t", "arr", 2, 99);
+      scoreboard_set("out", "r", storage_get_int("rs:t", "arr", 2));
+    }`)
+    rt.execFunction('test')
+    expect(sc(rt, 'r')).toBe(99)
+  })
+
+  it('runtime index: write 777 to arr[idx], read back', () => {
+    const rt = run(`fn test() {
+      storage_set_array("rs:t", "arr", "[1,2,3,4,5]");
+      let idx: int = 3;
+      storage_set_int("rs:t", "arr", idx, 777);
+      scoreboard_set("out", "r", storage_get_int("rs:t", "arr", idx));
+    }`)
+    rt.execFunction('test')
+    expect(sc(rt, 'r')).toBe(777)
+  })
+
+  it('loop write: fill arr[0..3] with 10,20,30,40', () => {
+    const rt = run(`fn test() {
+      storage_set_array("rs:t", "arr", "[0,0,0,0]");
+      let i: int = 0;
+      while (i < 4) {
+        storage_set_int("rs:t", "arr", i, (i + 1) * 10);
+        i = i + 1;
+      }
+      scoreboard_set("out", "a", storage_get_int("rs:t", "arr", 0));
+      scoreboard_set("out", "b", storage_get_int("rs:t", "arr", 1));
+      scoreboard_set("out", "c", storage_get_int("rs:t", "arr", 2));
+      scoreboard_set("out", "d", storage_get_int("rs:t", "arr", 3));
+    }`)
+    rt.execFunction('test')
+    expect(sc(rt, 'a')).toBe(10)
+    expect(sc(rt, 'b')).toBe(20)
+    expect(sc(rt, 'c')).toBe(30)
+    expect(sc(rt, 'd')).toBe(40)
+  })
+})
+
+// ── bigint_init + from_int ────────────────────────────────────────────────────
+
+describe('bigint init and load', () => {
+  it('bigint_init zeros registers', () => {
+    const rt = run(`fn test() {
+      bigint_init();
+      scoreboard_set("out", "r", bigint_get_a(0));
+    }`)
+    rt.execFunction('test')
+    expect(sc(rt, 'r')).toBe(0)
+  })
+
+  it('bigint_from_int_a(12345678): limb0=5678, limb1=1234', () => {
+    const rt = run(`fn test() {
+      bigint_init();
+      bigint_from_int_a(12345678);
+      scoreboard_set("out", "l0", bigint_get_a(0));
+      scoreboard_set("out", "l1", bigint_get_a(1));
+      scoreboard_set("out", "l2", bigint_get_a(2));
+    }`)
+    rt.execFunction('test')
+    expect(sc(rt, 'l0')).toBe(5678)
+    expect(sc(rt, 'l1')).toBe(1234)
+    expect(sc(rt, 'l2')).toBe(0)
+  })
+
+  it('bigint_from_int_a(2000000000): limb0=0, limb1=0, limb2=20', () => {
+    // 2000000000 = 20 × 10000^2 (not 2000: 20 × 10^8 = 2×10^9 ✓)
+    const rt = run(`fn test() {
+      bigint_init();
+      bigint_from_int_a(2000000000);
+      scoreboard_set("out", "l0", bigint_get_a(0));
+      scoreboard_set("out", "l1", bigint_get_a(1));
+      scoreboard_set("out", "l2", bigint_get_a(2));
+    }`)
+    rt.execFunction('test')
+    expect(sc(rt, 'l0')).toBe(0)
+    expect(sc(rt, 'l1')).toBe(0)
+    expect(sc(rt, 'l2')).toBe(20)
+  })
+})
+
+// ── bigint_add ────────────────────────────────────────────────────────────────
+
+describe('bigint_add', () => {
+  it('1 + 1 = 2 (simple)', () => {
+    const rt = run(`fn test() {
+      bigint_init();
+      bigint_from_int_a(1);
+      bigint_from_int_b(1);
+      bigint_add();
+      scoreboard_set("out", "r", bigint_get_c(0));
+    }`)
+    rt.execFunction('test')
+    expect(sc(rt, 'r')).toBe(2)
+  })
+
+  it('9999 + 1 = 10000: carry across limb boundary', () => {
+    // a=[9999,0,...] + b=[1,0,...] = c=[0,1,0,...] (carry to limb1)
+    const rt = run(`fn test() {
+      bigint_init();
+      bigint_from_int_a(9999);
+      bigint_from_int_b(1);
+      bigint_add();
+      scoreboard_set("out", "l0", bigint_get_c(0));
+      scoreboard_set("out", "l1", bigint_get_c(1));
+    }`)
+    rt.execFunction('test')
+    expect(sc(rt, 'l0')).toBe(0)
+    expect(sc(rt, 'l1')).toBe(1)
+  })
+
+  it('99990000 + 10000 = 100000000: multi-limb carry', () => {
+    // a=[0,9999,...] + b=[0,1,...] = c=[0,0,1,...] (carry to limb2)
+    const rt = run(`fn test() {
+      bigint_init();
+      bigint_from_int_a(99990000);
+      bigint_from_int_b(10000);
+      bigint_add();
+      scoreboard_set("out", "l0", bigint_get_c(0));
+      scoreboard_set("out", "l1", bigint_get_c(1));
+      scoreboard_set("out", "l2", bigint_get_c(2));
+    }`)
+    rt.execFunction('test')
+    expect(sc(rt, 'l0')).toBe(0)
+    expect(sc(rt, 'l1')).toBe(0)
+    expect(sc(rt, 'l2')).toBe(1)
+  })
+
+  it('large add: 999999999 + 999999999', () => {
+    // 999999999 = [9999, 9999, 9, 0, ...]
+    // + same = [9998, 9999, 18, 0, ...] after carry
+    // = 1999999998: l0=9998, l1=9999, l2=19 (carry: 9+9=18, no carry from l2)
+    // Wait: l0=9999+9999=19998, carry=1, l0=9998
+    //       l1=9999+9999+1=19999, carry=1, l1=9999
+    //       l2=9+9+1=19, carry=0, l2=19
+    const rt = run(`fn test() {
+      bigint_init();
+      bigint_from_int_a(999999999);
+      bigint_from_int_b(999999999);
+      bigint_add();
+      scoreboard_set("out", "l0", bigint_get_c(0));
+      scoreboard_set("out", "l1", bigint_get_c(1));
+      scoreboard_set("out", "l2", bigint_get_c(2));
+    }`)
+    rt.execFunction('test')
+    expect(sc(rt, 'l0')).toBe(9998)  // 1999999998 % 10000 = 9998
+    expect(sc(rt, 'l1')).toBe(9999)  // floor(1999999998 / 10000) % 10000 = 9999
+    expect(sc(rt, 'l2')).toBe(19)    // floor(1999999998 / 100000000) = 19
+  })
+})
+
+// ── bigint_sub ────────────────────────────────────────────────────────────────
+
+describe('bigint_sub', () => {
+  it('10 - 3 = 7', () => {
+    const rt = run(`fn test() {
+      bigint_init();
+      bigint_from_int_a(10);
+      bigint_from_int_b(3);
+      bigint_sub();
+      scoreboard_set("out", "r", bigint_get_c(0));
+    }`)
+    rt.execFunction('test')
+    expect(sc(rt, 'r')).toBe(7)
+  })
+
+  it('10000 - 1 = 9999: borrow across limb boundary', () => {
+    // a=[0,1,...] - b=[1,0,...] = c=[9999,0,...] (borrow from limb1)
+    const rt = run(`fn test() {
+      bigint_init();
+      bigint_from_int_a(10000);
+      bigint_from_int_b(1);
+      bigint_sub();
+      scoreboard_set("out", "l0", bigint_get_c(0));
+      scoreboard_set("out", "l1", bigint_get_c(1));
+    }`)
+    rt.execFunction('test')
+    expect(sc(rt, 'l0')).toBe(9999)
+    expect(sc(rt, 'l1')).toBe(0)
+  })
+})
+
+// ── bigint_compare ────────────────────────────────────────────────────────────
+
+describe('bigint_compare', () => {
+  it('1 == 1 → 0', () => {
+    const rt = run(`fn test() {
+      bigint_init();
+      bigint_from_int_a(1);
+      bigint_from_int_b(1);
+      scoreboard_set("out", "r", bigint_compare());
+    }`)
+    rt.execFunction('test')
+    expect(sc(rt, 'r')).toBe(0)
+  })
+
+  it('2 > 1 → 1', () => {
+    const rt = run(`fn test() {
+      bigint_init();
+      bigint_from_int_a(2);
+      bigint_from_int_b(1);
+      scoreboard_set("out", "r", bigint_compare());
+    }`)
+    rt.execFunction('test')
+    expect(sc(rt, 'r')).toBe(1)
+  })
+
+  it('1 < 2 → -1', () => {
+    const rt = run(`fn test() {
+      bigint_init();
+      bigint_from_int_a(1);
+      bigint_from_int_b(2);
+      scoreboard_set("out", "r", bigint_compare());
+    }`)
+    rt.execFunction('test')
+    expect(sc(rt, 'r')).toBe(-1)
+  })
+})
+
+// ── bigint_mul_small ──────────────────────────────────────────────────────────
+
+describe('bigint_mul_small', () => {
+  it('12345 * 2 = 24690', () => {
+    const rt = run(`fn test() {
+      bigint_init();
+      bigint_from_int_a(12345);
+      bigint_mul_small(2);
+      scoreboard_set("out", "l0", bigint_get_c(0));
+      scoreboard_set("out", "l1", bigint_get_c(1));
+    }`)
+    rt.execFunction('test')
+    expect(sc(rt, 'l0')).toBe(4690)
+    expect(sc(rt, 'l1')).toBe(2)
+  })
+
+  it('9999 * 9999 = 99980001: carry', () => {
+    // c[0] = 99980001 % 10000 = 1
+    // c[1] = floor(99980001 / 10000) = 9998
+    const rt = run(`fn test() {
+      bigint_init();
+      bigint_from_int_a(9999);
+      bigint_mul_small(9999);
+      scoreboard_set("out", "l0", bigint_get_c(0));
+      scoreboard_set("out", "l1", bigint_get_c(1));
+    }`)
+    rt.execFunction('test')
+    expect(sc(rt, 'l0')).toBe(1)      // 99980001 % 10000 = 1  (actually 0001)
+    expect(sc(rt, 'l1')).toBe(9998)   // 9998
+  })
+})
+
+// ── bigint_mul ────────────────────────────────────────────────────────────────
+
+describe('bigint_mul', () => {
+  it('3 * 4 = 12', () => {
+    const rt = run(`fn test() {
+      bigint_init();
+      bigint_from_int_a(3);
+      bigint_from_int_b(4);
+      bigint_mul();
+      scoreboard_set("out", "r", bigint_get_c(0));
+    }`)
+    rt.execFunction('test')
+    expect(sc(rt, 'r')).toBe(12)
+  })
+
+  it('9999 * 9999 = 99980001', () => {
+    const rt = run(`fn test() {
+      bigint_init();
+      bigint_from_int_a(9999);
+      bigint_from_int_b(9999);
+      bigint_mul();
+      scoreboard_set("out", "l0", bigint_get_c(0));
+      scoreboard_set("out", "l1", bigint_get_c(1));
+    }`)
+    rt.execFunction('test')
+    expect(sc(rt, 'l0')).toBe(1)
+    expect(sc(rt, 'l1')).toBe(9998)
+  })
+
+  it('100000 * 100000 = 10^10: spans 3 limbs', () => {
+    // 10^10 = [0, 0, 0, 1, 0, ...] in base 10000 (1 * 10000^3 = 10^12? no)
+    // 10^10 / 10000^0 % 10000 = 0
+    // 10^10 / 10000^1 % 10000 = 0
+    // 10^10 / 10000^2 % 10000 = 10000 → wait: 10^10 / 10^8 = 100, 100 % 10000 = 100
+    // Actually: 10^10 = 100 * 10^8 = 100 * (10^4)^2
+    //   l0 = 10^10 % 10^4 = 0
+    //   l1 = floor(10^10 / 10^4) % 10^4 = floor(10^6) % 10000 = 0
+    //   l2 = floor(10^10 / 10^8) % 10^4 = 100 % 10000 = 100
+    const rt = run(`fn test() {
+      bigint_init();
+      bigint_from_int_a(100000);
+      bigint_from_int_b(100000);
+      bigint_mul();
+      scoreboard_set("out", "l0", bigint_get_c(0));
+      scoreboard_set("out", "l1", bigint_get_c(1));
+      scoreboard_set("out", "l2", bigint_get_c(2));
+    }`)
+    rt.execFunction('test')
+    expect(sc(rt, 'l0')).toBe(0)
+    expect(sc(rt, 'l1')).toBe(0)
+    expect(sc(rt, 'l2')).toBe(100)
+  })
+})
+
+// ── bigint_fib ────────────────────────────────────────────────────────────────
+
+describe('bigint_fib', () => {
+  it('F(0) = 0', () => {
+    const rt = run(`fn test() {
+      bigint_fib(0);
+      scoreboard_set("out", "r", bigint_get_a(0));
+    }`)
+    rt.execFunction('test')
+    expect(sc(rt, 'r')).toBe(0)
+  })
+
+  it('F(1) = 1', () => {
+    const rt = run(`fn test() {
+      bigint_fib(1);
+      scoreboard_set("out", "r", bigint_get_a(0));
+    }`)
+    rt.execFunction('test')
+    expect(sc(rt, 'r')).toBe(1)
+  })
+
+  it('F(10) = 55', () => {
+    const rt = run(`fn test() {
+      bigint_fib(10);
+      scoreboard_set("out", "r", bigint_get_a(0));
+    }`)
+    rt.execFunction('test')
+    expect(sc(rt, 'r')).toBe(55)
+  })
+
+  it('F(20) = 6765', () => {
+    const rt = run(`fn test() {
+      bigint_fib(20);
+      scoreboard_set("out", "r", bigint_get_a(0));
+    }`)
+    rt.execFunction('test')
+    expect(sc(rt, 'r')).toBe(6765)
+  })
+
+  it('F(50) = 12586269025: limb0=9025, limb1=8626, limb2=125', () => {
+    // F(50) = 12,586,269,025
+    // 12586269025 % 10000 = 9025
+    // floor(12586269025 / 10000) % 10000 = 1258626 % 10000 = 8626
+    // floor(12586269025 / 10^8) = 125
+    const rt = run(`fn test() {
+      bigint_fib(50);
+      scoreboard_set("out", "l0", bigint_get_a(0));
+      scoreboard_set("out", "l1", bigint_get_a(1));
+      scoreboard_set("out", "l2", bigint_get_a(2));
+    }`)
+    rt.execFunction('test')
+    expect(sc(rt, 'l0')).toBe(9025)
+    expect(sc(rt, 'l1')).toBe(8626)
+    expect(sc(rt, 'l2')).toBe(125)
+  })
+
+  it('F(100) low limbs check', () => {
+    // F(100) = 354224848179261915075
+    // % 10000 = 5075
+    // floor / 10000 % 10000 = floor(35422484817926191.5075) % 10000 = ...
+    // Let's compute:
+    // 354224848179261915075 % 10000 = 5075
+    // floor(354224848179261915075 / 10000) = 35422484817926191507 (JS BigInt)
+    // 35422484817926191507 % 10000 = 1507
+    // floor(35422484817926191507 / 10000) = 3542248481792619 (roughly)
+    // % 10000 = 2619
+    const rt = run(`fn test() {
+      bigint_fib(100);
+      scoreboard_set("out", "l0", bigint_get_a(0));
+      scoreboard_set("out", "l1", bigint_get_a(1));
+      scoreboard_set("out", "l2", bigint_get_a(2));
+    }`)
+    rt.execFunction('test')
+    const f100 = BigInt('354224848179261915075')
+    const b = BigInt(10000)
+    expect(sc(rt, 'l0')).toBe(Number(f100 % b))
+    expect(sc(rt, 'l1')).toBe(Number((f100 / b) % b))
+    expect(sc(rt, 'l2')).toBe(Number((f100 / b / b) % b))
+  })
+})

package/src/lowering/index.ts

@@ -108,6 +108,7 @@ const BUILTINS: Record<string, (args: string[]) => string | null> = {
   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)
 }
 
 export interface Warning {
@@ -364,12 +365,24 @@ export class Lowering {
 
   private preScanExpr(expr: Expr, paramNames: Set<string>, macroParams: Set<string>): void {
     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: boolean = (() => {
+        try { return (handler as () => string | null)() === 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
@@ -2629,6 +2642,64 @@ export class Lowering {
       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') {

package/src/runtime/index.ts

@@ -697,17 +697,27 @@ export class MCRuntime {
         continue
       }
 
-      // Handle 'store result storage <ns:path> <field> <type> <scale>'
+      // Handle 'store result storage <ns:path> <field>[<idx>] <type> <scale>'  (array element)
       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+(.*)$/)
+        const sliced = rest.slice(21)
+        // Try array-index form first: <ns:path> <field>[<idx>] <type> <scale> <run-cmd>
+        // Use [^\[\s]+ for field (no brackets or spaces) so that \[ matches correctly.
+        const arrParts = sliced.match(/^(\S+)\s+([^\[\s]+)\[(\d+)\]\s+(\S+)\s+([\d.]+)\s+(.*)$/)
+        if (arrParts) {
+          const [, storagePath, field, indexStr, , , remaining] = arrParts
+          storeTarget = { storagePath, field: `${field}[${indexStr}]`, type: 'result' }
+          rest = remaining.trim()
+          continue
+        }
+        // Plain form: <ns:path> <field> <type> <scale> <run-cmd>
+        const storageParts = sliced.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
         }
+        rest = sliced
       }
 
       // Handle 'store result score <player> <obj>'
@@ -834,8 +844,20 @@ export class MCRuntime {
       return true
     }
 
+    // data modify storage <ns:path> <field>[<index>] set value <val>  (array element write)
+    const setArrMatch = cmd.match(/^data modify storage (\S+) ([^\[\s]+)\[(\d+)\] set value (.+)$/)
+    if (setArrMatch) {
+      const [, storagePath, field, indexStr, valueStr] = setArrMatch
+      const arr = this.getStorageField(storagePath, field)
+      const idx = parseInt(indexStr, 10)
+      if (Array.isArray(arr) && idx >= 0 && idx < arr.length) {
+        arr[idx] = this.parseDataValue(valueStr)
+      }
+      return true
+    }
+
     // data get storage <ns:path> <field>[<index>] [scale]  (array element access)
-    const getArrMatch = cmd.match(/^data get storage (\S+) (\S+)\[(\d+)\](?:\s+[\d.]+)?$/)
+    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)

package/src/stdlib/advanced.mcrs

@@ -247,3 +247,84 @@ fn julia_iter(z0r: int, z0i: int, cr: int, ci: int, max_iter: int) -> int {
     }
     return max_iter;
 }
+
+// ─── Category 5: Geometry experiments ────────────────────────────────────────
+
+// Angle between two 2D vectors in degrees (×1 = degrees, unsigned 0..180).
+// Strategy: normalize both vectors to unit (×1000 components), then
+//   angle = atan2(|cross|, dot)  where cross,dot are from the unit vectors.
+// Unit vector components are ≤ 1000, so cross/dot ≤ 10^6 (no overflow).
+// After dividing by 1000 to re-scale, pass to atan2_fixed.
+//
+// angle_between(1000, 0, 0, 1000) == 90
+// angle_between(1000, 0, 1000, 0) == 0
+// angle_between(1000, 0, -1000, 0) == 180
+fn angle_between(x1: int, y1: int, x2: int, y2: int) -> int {
+    let nx1: int = normalize2d_x(x1, y1);
+    let ny1: int = normalize2d_y(x1, y1);
+    let nx2: int = normalize2d_x(x2, y2);
+    let ny2: int = normalize2d_y(x2, y2);
+    if (nx1 == 0 && ny1 == 0) { return 0; }
+    if (nx2 == 0 && ny2 == 0) { return 0; }
+    // dot and cross of unit vectors (components ×1000 → result ×1000000)
+    let d: int = dot2d(nx1, ny1, nx2, ny2) / 1000;   // cos × 1000
+    let c: int = abs(cross2d(nx1, ny1, nx2, ny2)) / 1000; // |sin| × 1000
+    return atan2_fixed(c, d);
+}
+
+// Clamp a 2D point to lie within a circle of radius r centred at origin.
+// r is in the same units as x, y (raw block coords, NOT fixed-point).
+// Returns the clamped x component.
+// Note: keep x, y < ~2000 to avoid overflow in normalize2d_x (x * 10^6).
+//
+// clamp_circle_x(3, 4, 10) == 3   (point at dist 5, inside r=10)
+// clamp_circle_x(600, 0, 500) == 500
+fn clamp_circle_x(x: int, y: int, r: int) -> int {
+    // length2d_fixed returns dist × 1000; compare with r × 1000
+    let dist: int = length2d_fixed(x, y);
+    if (dist <= r * 1000) { return x; }
+    return normalize2d_x(x, y) * r / 1000;
+}
+
+// Y component of circle clamp.
+// clamp_circle_y(0, 600, 500) == 500
+fn clamp_circle_y(x: int, y: int, r: int) -> int {
+    let dist: int = length2d_fixed(x, y);
+    if (dist <= r * 1000) { return y; }
+    return normalize2d_y(x, y) * r / 1000;
+}
+
+// Newton's method integer square root (alternative to isqrt).
+// Converges quadratically; validates our while loop + division.
+// newton_sqrt(25) == 5, newton_sqrt(100) == 10, newton_sqrt(2) == 1
+fn newton_sqrt(n: int) -> int {
+    if (n <= 0) { return 0; }
+    if (n == 1) { return 1; }
+    let x: int = n / 2;
+    let prev: int = 0;
+    while (x != prev) {
+        prev = x;
+        x = (x + n / x) / 2;
+    }
+    return x;
+}
+
+// Digital root: repeatedly sum digits until single digit.
+// digital_root(493) == 7  (4+9+3=16 → 1+6=7)
+// digital_root(9) == 9
+// digital_root(0) == 0
+fn digital_root(n: int) -> int {
+    if (n == 0) { return 0; }
+    let r: int = n % 9;
+    if (r == 0) { return 9; }
+    return r;
+}
+
+// Ulam spiral ring number: which concentric square ring is n on?
+// Ring 0: n=1; Ring 1: n=2..9 (3×3 square); Ring 2: n=10..25 (5×5); etc.
+// Formula: floor((isqrt(n-1) + 1) / 2)
+// spiral_ring(1) == 0, spiral_ring(9) == 1, spiral_ring(25) == 2
+fn spiral_ring(n: int) -> int {
+    if (n <= 1) { return 0; }
+    return (isqrt(n - 1) + 1) / 2;
+}