redscript-mc 1.2.25 → 1.2.27

package/src/lowering/index.ts

@@ -106,6 +106,9 @@ const BUILTINS: Record<string, (args: string[]) => string | null> = {
   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)
 }
 
 export interface Warning {
@@ -215,6 +218,14 @@ export class Lowering {
   private implMethods: Map<string, Map<string, { fn: FnDecl; loweredName: string }>> = new Map()
   private specializedFunctions: Map<string, string> = new Map()
   private currentFn: string = ''
+
+  /** 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(name: string): string {
+    return `$${this.currentFn}_${name}`
+  }
   private currentStdlibCallSite?: StdlibCallSiteContext
   private foreachCounter: number = 0
   private lambdaCounter: number = 0
@@ -354,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
@@ -617,12 +640,12 @@ export class Lowering {
           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))
       }
     }
@@ -635,11 +658,15 @@ export 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) {
@@ -647,7 +674,7 @@ export class Lowering {
         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 })
         }
       }
     }
@@ -716,6 +743,23 @@ export class Lowering {
       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: string[] = []
+    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)
@@ -860,7 +904,7 @@ export class Lowering {
       )
     }
     
-    const varName = `$${stmt.name}`
+    const varName = this.fnVar(stmt.name)
     this.varMap.set(stmt.name, varName)
 
     // Track variable type
@@ -1196,7 +1240,7 @@ export class Lowering {
   }
 
   private lowerForRangeStmt(stmt: Extract<Stmt, { kind: 'for_range' }>): void {
-    const loopVar = `$${stmt.varName}`
+    const loopVar = this.fnVar(stmt.varName)
     const subFnName = `${this.currentFn}/__for_${this.foreachCounter++}`
 
     // Initialize loop variable
@@ -1385,7 +1429,7 @@ export class Lowering {
     }
 
     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()
@@ -2543,6 +2587,119 @@ export class Lowering {
       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') {
@@ -3447,7 +3604,7 @@ export class Lowering {
     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})]`
+      `\x01execute store result score ${dst} rs run data get storage rs:heap ${arrayName}[$(${macroKey})]`
     )
     return { kind: 'var', name: dst }
   }

package/src/optimizer/dce.ts

@@ -134,13 +134,18 @@ export class DeadCodeEliminator {
     const entries = new Set<string>()
 
     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',
@@ -172,6 +177,18 @@ export 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)
+          }
+        }
+      }
+    }
   }
 
   private collectFunctionRefs(fn: FnDecl): void {

package/src/optimizer/passes.ts

@@ -95,30 +95,43 @@ export function copyPropagation(fn: IRFunction): IRFunction {
       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: string): void {
+      copies.delete(written)
+      for (const [k, v] of copies) {
+        if (v.kind === 'var' && v.name === written) copies.delete(k)
+      }
+    }
+
     const newInstrs: IRInstr[] = []
     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)
+          if (instr.dst) invalidate(instr.dst)
           newInstrs.push({ ...instr, args: instr.args.map(resolve) })
           break
         default:

package/src/optimizer/structure.ts

@@ -24,7 +24,8 @@ function varRef(name: string): string {
 function operandToScore(op: Operand): string {
   if (op.kind === 'var') return `${varRef(op.name)} ${OBJ}`
   if (op.kind === 'const') return `$const_${op.value} ${OBJ}`
-  throw new Error(`Cannot convert storage operand to score: ${op.path}`)
+  if (op.kind === 'param') return `$p${op.index} ${OBJ}`
+  throw new Error(`Cannot convert storage operand to score: ${(op as any).path}`)
 }
 
 function emitInstr(instr: IRInstr, namespace: string): IRCommand[] {
@@ -38,6 +39,10 @@ function emitInstr(instr: IRInstr, namespace: string): IRCommand[] {
         commands.push({
           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/src/parser/index.ts

@@ -76,6 +76,11 @@ export class Parser {
   private pos: number = 0
   private sourceLines: string[]
   private filePath?: string
+  /** 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: boolean = false
 
   constructor(tokens: Token[], source?: string, filePath?: string) {
     this.tokens = tokens
@@ -169,6 +174,7 @@ export class Parser {
     const implBlocks: ImplBlock[] = []
     const enums: EnumDecl[] = []
     const consts: ConstDecl[] = []
+    let isLibrary = false
 
     // Check for namespace declaration
     if (this.check('namespace')) {
@@ -178,6 +184,20 @@ export class Parser {
       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')) {
@@ -199,7 +219,7 @@ export class Parser {
       }
     }
 
-    return { namespace, globals, declarations, structs, implBlocks, enums, consts }
+    return { namespace, globals, declarations, structs, implBlocks, enums, consts, isLibrary }
   }
 
   // -------------------------------------------------------------------------
@@ -322,7 +342,11 @@ export class Parser {
 
     const body = this.parseBlock()
 
-    return this.withLoc({ name, params, returnType, decorators, body }, fnToken)
+    const fn: import('../ast/types').FnDecl = 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. */
@@ -397,6 +421,27 @@ export class Parser {
       }
     }
 
+    // @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: NonNullable<Decorator['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())