redscript-mc 1.2.24 → 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))
@@ -384,15 +499,29 @@ export function generateDatapackWithStats(
         ? `data/${ns}/function/${fn.name}.mcfunction`
         : `data/${ns}/function/${fn.name}/${block.label}.mcfunction`
 
+      // Skip empty continuation blocks (only contain the block comment, no real commands)
+      // Entry block (i === 0) is always emitted so the function file exists
+      const hasRealContent = lines.some(l => !l.startsWith('#') && l.trim() !== '')
+      if (i !== 0 && !hasRealContent) continue
+
       files.push({ path: filePath, content: lines.join('\n') })
     }
   }
 
-  // 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)
@@ -63,9 +92,13 @@ export class VarAllocator {
    */
   toSourceMap(): Record<string, string> {
     const map: Record<string, string> = {}
-    for (const [orig, alloc] of this.varCache)    map[alloc] = orig
-    for (const [val,  alloc] of this.constCache)  map[alloc] = `const(${val})`
-    for (const [suf,  alloc] of this.internalCache) map[alloc] = `__${suf}`
+    for (const [orig, alloc] of this.varCache) {
+      // Skip compiler-generated temporaries (start with _ followed by digits)
+      if (/^_\d+$/.test(orig)) continue
+      map[alloc] = orig
+    }
+    for (const [val,  alloc] of this.constCache)    map[alloc] = `const:${val}`
+    for (const [suf,  alloc] of this.internalCache) map[alloc] = `internal:${suf}`
     return map
   }
 }

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',