redscript-mc 1.2.25 → 1.2.26

package/src/codegen/mcfunction/index.ts

@@ -16,7 +16,7 @@
  *   parameters:           "$p0", "$p1", ...
  */
 
-import type { IRBlock, IRFunction, IRModule, Operand, Terminator } from '../../ir/types'
+import type { IRBlock, IRFunction, IRInstr, IRModule, Operand, Terminator } from '../../ir/types'
 import { optimizeCommandFunctions, type OptimizationStats, createEmptyOptimizationStats, mergeOptimizationStats } from '../../optimizer/commands'
 import { EVENT_TYPES, isEventTypeName, type EventTypeName } from '../../events/types'
 import { VarAllocator } from '../var-allocator'
@@ -30,6 +30,7 @@ const OBJ = 'rs'  // scoreboard objective name
 function operandToScore(op: Operand, alloc: VarAllocator): string {
   if (op.kind === 'var')   return `${alloc.alloc(op.name)} ${OBJ}`
   if (op.kind === 'const') return `${alloc.constant(op.value)} ${OBJ}`
+  if (op.kind === 'param') return `${alloc.internal(`p${op.index}`)} ${OBJ}`
   throw new Error(`Cannot convert storage operand to score: ${op.path}`)
 }
 
@@ -74,6 +75,8 @@ function emitInstr(instr: ReturnType<typeof Object.assign> & { op: string }, ns:
         lines.push(`scoreboard players set ${dst} ${OBJ} ${src.value}`)
       } else if (src.kind === 'var') {
         lines.push(`scoreboard players operation ${dst} ${OBJ} = ${alloc.alloc(src.name)} ${OBJ}`)
+      } else if (src.kind === 'param') {
+        lines.push(`scoreboard players operation ${dst} ${OBJ} = ${alloc.internal(`p${src.index}`)} ${OBJ}`)
       } else {
         lines.push(`execute store result score ${dst} ${OBJ} run data get storage ${src.path}`)
       }
@@ -119,22 +122,41 @@ function emitInstr(instr: ReturnType<typeof Object.assign> & { op: string }, ns:
     }
 
     case 'call': {
-      // Push args as param fake players
+      // Push args into the internal parameter slots ($p0, $p1, ...).
+      // We emit the copy commands directly (not via emitInstr/alloc.alloc) to
+      // ensure the destination resolves to alloc.internal('p{i}') rather than
+      // alloc.alloc('p{i}') which would create a *different* user-var slot.
       for (let i = 0; i < instr.args.length; i++) {
-        const paramName = alloc.internal(`p${i}`)
-        lines.push(...emitInstr({ op: 'assign', dst: paramName, src: instr.args[i] }, ns, alloc))
+        const paramSlot = alloc.internal(`p${i}`)
+        const arg = instr.args[i] as Operand
+        if (arg.kind === 'const') {
+          lines.push(`scoreboard players set ${paramSlot} ${OBJ} ${arg.value}`)
+        } else if (arg.kind === 'var') {
+          lines.push(`scoreboard players operation ${paramSlot} ${OBJ} = ${alloc.alloc(arg.name)} ${OBJ}`)
+        } else if (arg.kind === 'param') {
+          lines.push(`scoreboard players operation ${paramSlot} ${OBJ} = ${alloc.internal(`p${arg.index}`)} ${OBJ}`)
+        }
+        // storage args are rare for call sites; fall through to no-op
       }
       lines.push(`function ${ns}:${instr.fn}`)
       if (instr.dst) {
-        const retName = alloc.internal('ret')
-        lines.push(`scoreboard players operation ${alloc.alloc(instr.dst)} ${OBJ} = ${retName} ${OBJ}`)
+        const retSlot = alloc.internal('ret')
+        lines.push(`scoreboard players operation ${alloc.alloc(instr.dst)} ${OBJ} = ${retSlot} ${OBJ}`)
       }
       break
     }
 
-    case 'raw':
-      lines.push(instr.cmd as string)
+    case 'raw': {
+      // resolveRaw rewrites $var tokens that are registered in the allocator
+      // so that mangle=true mode produces correct mangled names instead of
+      // the raw IR names embedded by the lowering phase.
+      // \x01 is a sentinel for the MC macro line-start '$' (used by
+      // storage_get_int sub-functions). Replace it last, after resolveRaw,
+      // so '$execute' is never treated as a variable reference.
+      const rawResolved = alloc.resolveRaw(instr.cmd as string).replace(/^\x01/, '$')
+      lines.push(rawResolved)
       break
+    }
   }
 
   return lines
@@ -159,15 +181,27 @@ function emitTerm(term: Terminator, ns: string, fnName: string, alloc: VarAlloca
       lines.push(`execute if score ${alloc.alloc(term.cond)} ${OBJ} matches 1.. run function ${ns}:${fnName}/${term.else_}`)
       break
     case 'return': {
-      const retName = alloc.internal('ret')
+      // Emit the copy to the shared return slot directly — do NOT go through
+      // emitInstr/alloc.alloc(retSlot) which would allocate a *user* var slot
+      // (different from the internal slot) and break mangle mode.
+      const retSlot = alloc.internal('ret')
       if (term.value) {
-        lines.push(...emitInstr({ op: 'assign', dst: retName, src: term.value }, ns, alloc))
+        if (term.value.kind === 'const') {
+          lines.push(`scoreboard players set ${retSlot} ${OBJ} ${term.value.value}`)
+        } else if (term.value.kind === 'var') {
+          lines.push(`scoreboard players operation ${retSlot} ${OBJ} = ${alloc.alloc(term.value.name)} ${OBJ}`)
+        } else if (term.value.kind === 'param') {
+          lines.push(`scoreboard players operation ${retSlot} ${OBJ} = ${alloc.internal(`p${term.value.index}`)} ${OBJ}`)
+        }
       }
-      // In MC 1.20+, use `return` command
+      // MC 1.20+: use `return` to propagate the value back to the caller's
+      // `execute store result … run function …` without an extra scoreboard read.
       if (term.value?.kind === 'const') {
         lines.push(`return ${term.value.value}`)
       } else if (term.value?.kind === 'var') {
         lines.push(`return run scoreboard players get ${alloc.alloc(term.value.name)} ${OBJ}`)
+      } else if (term.value?.kind === 'param') {
+        lines.push(`return run scoreboard players get ${alloc.internal(`p${term.value.index}`)} ${OBJ}`)
       }
       break
     }
@@ -266,6 +300,56 @@ export function countMcfunctionCommands(files: DatapackFile[]): number {
   }, 0)
 }
 
+// ---------------------------------------------------------------------------
+// Pre-allocation helpers for the two-pass mangle strategy
+// ---------------------------------------------------------------------------
+
+/** Register every variable referenced in an instruction with the allocator. */
+function preAllocInstr(instr: IRInstr, alloc: VarAllocator): void {
+  switch (instr.op) {
+    case 'assign':
+      alloc.alloc(instr.dst)
+      if (instr.src.kind === 'var') alloc.alloc(instr.src.name)
+      break
+    case 'binop':
+      alloc.alloc(instr.dst)
+      if (instr.lhs.kind === 'var') alloc.alloc(instr.lhs.name)
+      if (instr.rhs.kind === 'var') alloc.alloc(instr.rhs.name)
+      break
+    case 'cmp':
+      alloc.alloc(instr.dst)
+      if (instr.lhs.kind === 'var') alloc.alloc(instr.lhs.name)
+      if (instr.rhs.kind === 'var') alloc.alloc(instr.rhs.name)
+      break
+    case 'call':
+      for (const arg of instr.args) {
+        if (arg.kind === 'var') alloc.alloc(arg.name)
+      }
+      if (instr.dst) alloc.alloc(instr.dst)
+      break
+    case 'raw':
+      // Scan for $varname tokens and pre-register each one
+      ;(instr.cmd as string).replace(/\$[A-Za-z_][A-Za-z0-9_]*/g, (tok) => {
+        alloc.alloc(tok)
+        return tok
+      })
+      break
+  }
+}
+
+/** Register every variable referenced in a terminator with the allocator. */
+function preAllocTerm(term: Terminator, alloc: VarAllocator): void {
+  switch (term.op) {
+    case 'jump_if':
+    case 'jump_unless':
+      alloc.alloc(term.cond)
+      break
+    case 'return':
+      if (term.value?.kind === 'var') alloc.alloc(term.value.name)
+      break
+  }
+}
+
 export function generateDatapackWithStats(
   module: IRModule,
   options: DatapackGenerationOptions = {},
@@ -359,6 +443,40 @@ export function generateDatapackWithStats(
     ))
   }
 
+  // ─────────────────────────────────────────────────────────────────────────
+  // Pre-allocation pass (mangle mode only)
+  //
+  // When mangle=true, the codegen assigns sequential names ($a, $b, …) the
+  // FIRST time alloc.alloc() is called for a given variable.  Raw IR commands
+  // embed variable names (e.g. "$_0") as plain strings; resolveRaw() can only
+  // substitute them if the name was already registered in the allocator.
+  //
+  // Problem: a freshTemp ($\_0) used in a `raw` instruction and then in the
+  // immediately following `assign` gets registered by the `assign` AFTER the
+  // `raw` has already been emitted — so resolveRaw sees an unknown name and
+  // passes it through verbatim ($\_0), while the assign emits a different
+  // mangled slot ($e).  The two slots never meet and the value is lost.
+  //
+  // Fix: walk every instruction (and terminator) of every function in order
+  // and call alloc.alloc() for each variable reference.  This registers all
+  // names — with the same sequential order the main emit pass will encounter
+  // them — so that resolveRaw() can always find the correct mangled name.
+  // ─────────────────────────────────────────────────────────────────────────
+  if (mangle) {
+    for (const fn of module.functions) {
+      // Register internals used by the calling convention
+      for (let i = 0; i < fn.params.length; i++) alloc.internal(`p${i}`)
+      alloc.internal('ret')
+
+      for (const block of fn.blocks) {
+        for (const instr of block.instrs) {
+          preAllocInstr(instr as IRInstr, alloc)
+        }
+        preAllocTerm(block.term, alloc)
+      }
+    }
+  }
+
   // Generate each function
   for (const fn of module.functions) {
 
@@ -368,12 +486,9 @@ export function generateDatapackWithStats(
       const block = fn.blocks[i]
       const lines: string[] = [`# block: ${block.label}`]
 
-      // Param setup in entry block
-      if (i === 0) {
-        for (let j = 0; j < fn.params.length; j++) {
-          lines.push(`scoreboard players operation ${alloc.alloc(fn.params[j])} ${OBJ} = ${alloc.internal(`p${j}`)} ${OBJ}`)
-        }
-      }
+      // Param setup is now handled by the lowering IR itself via { kind: 'param' }
+      // operands, so we no longer need a separate codegen param-copy loop here.
+      // (Removing it prevents the double-assignment that caused mangle-mode collisions.)
 
       for (const instr of block.instrs) {
         lines.push(...emitInstr(instr as any, ns, alloc))
@@ -393,11 +508,20 @@ export function generateDatapackWithStats(
     }
   }
 
-  // Call @load functions from __load
+  // Call @load functions and @requires-referenced load helpers from __load.
+  // We collect them in a set to deduplicate (multiple fns might @requires the same dep).
+  const loadCalls = new Set<string>()
   for (const fn of module.functions) {
     if (fn.isLoadInit) {
-      loadLines.push(`function ${ns}:${fn.name}`)
+      loadCalls.add(fn.name)
     }
+    // @requires: if this fn is compiled in, its required load-helpers must also run
+    for (const dep of fn.requiredLoads ?? []) {
+      loadCalls.add(dep)
+    }
+  }
+  for (const name of loadCalls) {
+    loadLines.push(`function ${ns}:${name}`)
   }
 
   // Write __load.mcfunction

package/src/codegen/var-allocator.ts

@@ -35,6 +35,35 @@ export class VarAllocator {
     return name
   }
 
+  /**
+   * Look up the allocated name for a raw scoreboard fake-player name such as
+   * "$_2", "$x", "$p0", or "$ret".  Returns the mangled name when mangle=true,
+   * or the original name when mangle=false or the name is not yet known.
+   *
+   * Unlike alloc/internal/constant this does NOT create a new slot — it only
+   * resolves names that were already registered.  Used by the codegen to
+   * rewrite variable references inside `raw` IR instructions.
+   */
+  resolve(rawName: string): string {
+    const clean = rawName.startsWith('$') ? rawName.slice(1) : rawName
+    // Check every cache in priority order: vars, internals, consts
+    return (
+      this.varCache.get(clean) ??
+      this.internalCache.get(clean) ??
+      rawName  // not registered → return as-is (literal fake player, not a var)
+    )
+  }
+
+  /**
+   * Rewrite all $varname tokens in a raw mcfunction command string so that
+   * IR variable names are replaced by their allocated (possibly mangled) names.
+   * Tokens that are not registered in the allocator are left untouched (they
+   * are literal scoreboard fake-player names like "out" or "#rs").
+   */
+  resolveRaw(cmd: string): string {
+    return cmd.replace(/\$[A-Za-z_][A-Za-z0-9_]*/g, (tok) => this.resolve(tok))
+  }
+
   /** Allocate a name for a compiler internal (e.g. "ret", "p0"). */
   internal(suffix: string): string {
     const cached = this.internalCache.get(suffix)

package/src/compile.ts

@@ -26,6 +26,13 @@ export interface CompileOptions {
   filePath?: string
   optimize?: boolean
   dce?: boolean
+  mangle?: boolean
+  /** Additional source files that should be treated as *library* code.
+   *  Functions in these files are DCE-eligible: they are only compiled into
+   *  the datapack when actually called from user code.  Each string is parsed
+   *  independently (as if it had `module library;` at the top), so library
+   *  mode never bleeds into the main `source`. */
+  librarySources?: string[]
 }
 
 // ---------------------------------------------------------------------------
@@ -50,6 +57,10 @@ export interface SourceRange {
 export interface PreprocessedSource {
   source: string
   ranges: SourceRange[]
+  /** Imported files that declared `module library;` — parsed separately
+   *  in library mode so their functions are DCE-eligible.  Never concatenated
+   *  into `source`. */
+  libraryImports?: Array<{ source: string; filePath: string }>
 }
 
 /**
@@ -72,6 +83,17 @@ export function resolveSourceLine(
 
 const IMPORT_RE = /^\s*import\s+"([^"]+)"\s*;?\s*$/
 
+/** Returns true if the source file declares `module library;` at its top
+ *  (before any non-comment/non-blank lines). */
+function isLibrarySource(source: string): boolean {
+  for (const line of source.split('\n')) {
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith('//')) continue
+    return /^module\s+library\s*;/.test(trimmed)
+  }
+  return false
+}
+
 interface PreprocessOptions {
   filePath?: string
   seen?: Set<string>
@@ -99,6 +121,8 @@ export function preprocessSourceWithMetadata(source: string, options: Preprocess
 
   const lines = source.split('\n')
   const imports: PreprocessedSource[] = []
+  /** Library imports: `module library;` files routed here instead of concatenated. */
+  const libraryImports: Array<{ source: string; filePath: string }> = []
   const bodyLines: string[] = []
   let parsingHeader = true
 
@@ -133,7 +157,16 @@ export function preprocessSourceWithMetadata(source: string, options: Preprocess
           )
         }
 
-        imports.push(preprocessSourceWithMetadata(importedSource, { filePath: importPath, seen }))
+        if (isLibrarySource(importedSource)) {
+          // Library file: parse separately so its functions are DCE-eligible.
+          // Also collect any transitive library imports inside it.
+          const nested = preprocessSourceWithMetadata(importedSource, { filePath: importPath, seen })
+          libraryImports.push({ source: importedSource, filePath: importPath })
+          // Propagate transitive library imports (e.g. math.mcrs imports vec.mcrs)
+          if (nested.libraryImports) libraryImports.push(...nested.libraryImports)
+        } else {
+          imports.push(preprocessSourceWithMetadata(importedSource, { filePath: importPath, seen }))
+        }
       }
       continue
     }
@@ -167,7 +200,11 @@ export function preprocessSourceWithMetadata(source: string, options: Preprocess
     })
   }
 
-  return { source: combined, ranges }
+  return {
+    source: combined,
+    ranges,
+    libraryImports: libraryImports.length > 0 ? libraryImports : undefined,
+  }
 }
 
 export function preprocessSource(source: string, options: PreprocessOptions = {}): string {
@@ -191,8 +228,37 @@ export function compile(source: string, options: CompileOptions = {}): CompileRe
     // Lexing
     const tokens = new Lexer(preprocessedSource, filePath).tokenize()
 
-    // Parsing
+    // Parsing — user source
     const parsedAst = new Parser(tokens, preprocessedSource, filePath).parse(namespace)
+
+    // Collect all library sources: explicit `librarySources` option +
+    // auto-detected imports (files with `module library;` pulled out by the
+    // preprocessor rather than concatenated).
+    const allLibrarySources: Array<{ src: string; fp?: string }> = []
+    for (const libSrc of options.librarySources ?? []) {
+      allLibrarySources.push({ src: libSrc })
+    }
+    for (const li of preprocessed.libraryImports ?? []) {
+      allLibrarySources.push({ src: li.source, fp: li.filePath })
+    }
+
+    // Parse library sources independently (fresh Parser per source) so that
+    // `inLibraryMode` never bleeds into user code.  All resulting functions get
+    // isLibraryFn=true (either via `module library;` in the source, or forced below).
+    for (const { src, fp } of allLibrarySources) {
+      const libPreprocessed = preprocessSourceWithMetadata(src, fp ? { filePath: fp } : {})
+      const libTokens = new Lexer(libPreprocessed.source, fp).tokenize()
+      const libAst = new Parser(libTokens, libPreprocessed.source, fp).parse(namespace)
+      // Force all functions to library mode (even if source lacks `module library;`)
+      for (const fn of libAst.declarations) fn.isLibraryFn = true
+      // Merge into main AST
+      parsedAst.declarations.push(...libAst.declarations)
+      parsedAst.structs.push(...libAst.structs)
+      parsedAst.implBlocks.push(...libAst.implBlocks)
+      parsedAst.enums.push(...libAst.enums)
+      parsedAst.consts.push(...libAst.consts)
+      parsedAst.globals.push(...libAst.globals)
+    }
     const dceResult = shouldRunDce ? eliminateDeadCode(parsedAst) : { program: parsedAst, warnings: [] }
     const ast = dceResult.program
 
@@ -204,8 +270,9 @@ export function compile(source: string, options: CompileOptions = {}): CompileRe
       ? { ...ir, functions: ir.functions.map(fn => optimize(fn)) }
       : ir
 
-    // Code generation
-    const generated = generateDatapackWithStats(optimized)
+    // Code generation — mangle=true by default to prevent cross-function
+    // scoreboard variable collisions in the global MC scoreboard namespace.
+    const generated = generateDatapackWithStats(optimized, { mangle: options.mangle ?? true })
 
     return {
       success: true,

package/src/index.ts

@@ -69,8 +69,28 @@ export function compile(source: string, options: CompileOptions = {}): CompileRe
   // Lexing
   const tokens = new Lexer(preprocessedSource, filePath).tokenize()
 
-  // Parsing
+  // Parsing — user source
   const parsedAst = new Parser(tokens, preprocessedSource, filePath).parse(namespace)
+
+  // Library imports: files that declared `module library;` are parsed independently
+  // (fresh Parser per file) so their functions are DCE-eligible but never bleed into user code.
+  const allLibrarySources: Array<{ src: string; fp?: string }> = []
+  for (const li of preprocessed.libraryImports ?? []) {
+    allLibrarySources.push({ src: li.source, fp: li.filePath })
+  }
+  for (const { src, fp } of allLibrarySources) {
+    const libPreprocessed = preprocessSourceWithMetadata(src, fp ? { filePath: fp } : {})
+    const libTokens = new Lexer(libPreprocessed.source, fp).tokenize()
+    const libAst = new Parser(libTokens, libPreprocessed.source, fp).parse(namespace)
+    for (const fn of libAst.declarations) fn.isLibraryFn = true
+    parsedAst.declarations.push(...libAst.declarations)
+    parsedAst.structs.push(...libAst.structs)
+    parsedAst.implBlocks.push(...libAst.implBlocks)
+    parsedAst.enums.push(...libAst.enums)
+    parsedAst.consts.push(...libAst.consts)
+    parsedAst.globals.push(...libAst.globals)
+  }
+
   const dceResult = shouldRunDce ? eliminateDeadCode(parsedAst, preprocessed.ranges) : { program: parsedAst, warnings: [] }
   const ast = dceResult.program
 

package/src/ir/types.ts

@@ -19,6 +19,7 @@ export type Operand =
   | { kind: 'var';     name: string }        // scoreboard fake player
   | { kind: 'const';   value: number }       // integer literal
   | { kind: 'storage'; path: string }        // NBT storage path (e.g. "redscript:heap data.x")
+  | { kind: 'param';   index: number }       // function parameter slot (alloc.internal('p{i}')), avoids mangle collision
 
 // ---------------------------------------------------------------------------
 // Binary operators (all map to `scoreboard players operation`)
@@ -101,6 +102,7 @@ export interface IRFunction {
   commands?: IRCommand[]   // structure target command stream
   isTickLoop?: boolean     // true → Repeat command block (runs every tick)
   isLoadInit?: boolean     // true → called from __load.mcfunction
+  requiredLoads?: string[] // @requires("fn") — these fns are also called from __load when this fn is compiled in
   isTriggerHandler?: boolean  // true → handles a trigger event
   triggerName?: string        // the trigger objective name
   eventTrigger?: {

package/src/lexer/index.ts

@@ -15,7 +15,7 @@ import { DiagnosticError } from '../diagnostics'
 export type TokenKind =
   // Keywords
   | 'fn' | 'let' | 'const' | 'if' | 'else' | 'while' | 'for' | 'foreach' | 'match'
-  | 'return' | 'break' | 'continue' | 'as' | 'at' | 'in' | 'is' | 'struct' | 'impl' | 'enum' | 'trigger' | 'namespace'
+  | 'return' | 'break' | 'continue' | 'as' | 'at' | 'in' | 'is' | 'struct' | 'impl' | 'enum' | 'trigger' | 'namespace' | 'module'
   | 'execute' | 'run' | 'unless' | 'declare'
   // Types
   | 'int' | 'bool' | 'float' | 'string' | 'void'
@@ -86,6 +86,7 @@ const KEYWORDS: Record<string, TokenKind> = {
   enum: 'enum',
   trigger: 'trigger',
   namespace: 'namespace',
+  module: 'module',
   execute: 'execute',
   run: 'run',
   unless: 'unless',

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 }
   }