redscript-mc 1.2.24 → 1.2.26

package/src/lowering/index.ts

@@ -106,6 +106,8 @@ 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)
 }
 
 export interface Warning {
@@ -215,6 +217,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
@@ -617,12 +627,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 +645,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 +661,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 +730,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 +891,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 +1227,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 +1416,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 +2574,61 @@ 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 }
+    }
+
     // data_merge(target, nbt) — merge NBT into entity/block/storage
     // data_merge(@s, { Invisible: 1b, Silent: 1b })
     if (name === 'data_merge') {
@@ -3447,7 +3533,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())

package/src/runtime/index.ts

@@ -266,6 +266,9 @@ export class MCRuntime {
   // Flag to stop function execution (for return)
   private shouldReturn: boolean = false
 
+  // Current MC macro context: key → value (set by 'function ... with storage')
+  private currentMacroContext: Record<string, any> | null = null
+
   constructor(namespace: string) {
     this.namespace = namespace
     // Initialize default objective
@@ -363,6 +366,13 @@ export 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)
@@ -542,7 +552,10 @@ export class MCRuntime {
     // Track execute state
     let currentExecutor = executor
     let condition: boolean = true
-    let storeTarget: { player: string; objective: string; type: 'result' | 'success' } | null = null
+    let storeTarget: 
+      | { player: string; objective: string; type: 'result' | 'success' }
+      | { storagePath: string; field: string; type: 'result' }
+      | null = null
 
     while (rest.length > 0) {
       rest = rest.trimStart()
@@ -557,7 +570,11 @@ export 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
@@ -630,15 +647,34 @@ export 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>'
@@ -661,6 +697,19 @@ export class MCRuntime {
         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)
@@ -695,7 +744,11 @@ export 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
@@ -721,13 +774,39 @@ export class MCRuntime {
   // -------------------------------------------------------------------------
 
   private execFunctionCmd(cmd: string, executor?: Entity): boolean {
-    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 */
+  private expandMacro(cmd: string): string {
+    return cmd.replace(/\$\(([^)]+)\)/g, (_, key) => {
+      const val = this.currentMacroContext?.[key]
+      return val !== undefined ? String(val) : `$(${key})`
+    })
+  }
+
   // -------------------------------------------------------------------------
   // Data Commands
   // -------------------------------------------------------------------------
@@ -755,8 +834,19 @@ export 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)
@@ -803,6 +893,14 @@ export class MCRuntime {
     }
   }
 
+  /** Return the whole storage compound at storagePath as a flat key→value map.
+   *  Used by 'function ... with storage' to provide macro context. */
+  private getStorageCompound(storagePath: string): Record<string, any> | null {
+    const data = this.storage.get(storagePath)
+    if (!data || typeof data !== 'object' || Array.isArray(data)) return null
+    return data as Record<string, any>
+  }
+
   private getStorageField(storagePath: string, field: string): any {
     const data = this.storage.get(storagePath) ?? {}
     const segments = this.parseStoragePath(field)