redscript-mc 2.6.2 → 3.0.1

package/src/mir/lower.ts

@@ -7,7 +7,7 @@
 
 import type {
   HIRModule, HIRFunction, HIRStmt, HIRBlock, HIRExpr,
-  HIRExecuteSubcommand, HIRParam,
+  HIRExecuteSubcommand, HIRParam, TypeNode, HIRFStringPart,
 } from '../hir/types'
 import type {
   MIRModule, MIRFunction, MIRBlock, MIRInstr, BlockId,
@@ -15,6 +15,35 @@ import type {
 } from './types'
 import { detectMacroFunctions, BUILTIN_SET, type MacroFunctionInfo } from './macro'
 
+function formatTypeNode(type: TypeNode): string {
+  switch (type.kind) {
+    case 'named':
+      return type.name
+    case 'array':
+      return `${formatTypeNode(type.elem)}[]`
+    case 'struct':
+    case 'enum':
+      return type.name
+    case 'function_type':
+      return `fn(${type.params.map(formatTypeNode).join(', ')}) -> ${formatTypeNode(type.return)}`
+    case 'entity':
+      return type.entityType
+    case 'selector':
+      return type.entityType ? `selector<${type.entityType}>` : 'selector'
+    case 'tuple':
+      return `(${type.elements.map(formatTypeNode).join(', ')})`
+    case 'option':
+      return `Option<${formatTypeNode(type.inner)}>`
+  }
+}
+
+function formatFunctionSignature(fn: HIRFunction): string {
+  const params = fn.params
+    .map(param => `${param.name}: ${formatTypeNode(param.type)}`)
+    .join(', ')
+  return `fn ${fn.name}(${params}) -> ${formatTypeNode(fn.returnType)}`
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -22,31 +51,59 @@ import { detectMacroFunctions, BUILTIN_SET, type MacroFunctionInfo } from './mac
 export function lowerToMIR(hir: HIRModule, sourceFile?: string): MIRModule {
   // Build struct definitions: name → field names
   const structDefs = new Map<string, string[]>()
+  // Track @singleton struct names for special expansion of GameState::set(gs) calls
+  const singletonStructs = new Set<string>()
   for (const s of hir.structs) {
     structDefs.set(s.name, s.fields.map(f => f.name))
+    if (s.isSingleton) singletonStructs.add(s.name)
   }
 
   // Build enum definitions: enumName → variantName → integer value
   const enumDefs = new Map<string, Map<string, number>>()
+  // Build enum payload info: enumName → variantName → field list
+  const enumPayloads = new Map<string, Map<string, { name: string; type: TypeNode }[]>>()
   for (const e of hir.enums) {
     const variants = new Map<string, number>()
+    const payloads = new Map<string, { name: string; type: TypeNode }[]>()
     for (const v of e.variants) {
       variants.set(v.name, v.value ?? 0)
+      if (v.fields && v.fields.length > 0) {
+        payloads.set(v.name, v.fields)
+      }
     }
     enumDefs.set(e.name, variants)
+    if (payloads.size > 0) {
+      enumPayloads.set(e.name, payloads)
+    }
   }
 
-  // Build impl method info: typeName → methodName → { hasSelf }
-  const implMethods = new Map<string, Map<string, { hasSelf: boolean }>>()
+  // Build impl method info: typeName → methodName → { hasSelf, returnStructName? }
+  const implMethods = new Map<string, Map<string, { hasSelf: boolean; returnStructName?: string }>>()
   for (const ib of hir.implBlocks) {
-    const methods = new Map<string, { hasSelf: boolean }>()
+    const methods = new Map<string, { hasSelf: boolean; returnStructName?: string }>()
     for (const m of ib.methods) {
       const hasSelf = m.params.length > 0 && m.params[0].name === 'self'
-      methods.set(m.name, { hasSelf })
+      const returnStructName = m.returnType.kind === 'struct' ? m.returnType.name : undefined
+      methods.set(m.name, { hasSelf, returnStructName })
     }
     implMethods.set(ib.typeName, methods)
   }
 
+  // Build Display impl registry: typeName → f-string parts from to_string body
+  // Used to inline Display::to_string() calls at call sites instead of generating a function.
+  const displayImpls = new Map<string, HIRFStringPart[]>()
+  for (const ib of hir.implBlocks) {
+    if (ib.traitName === 'Display') {
+      const toStringMethod = ib.methods.find(m => m.name === 'to_string')
+      if (toStringMethod && toStringMethod.body.length > 0) {
+        const firstStmt = toStringMethod.body[0]
+        if (firstStmt.kind === 'return' && firstStmt.value && firstStmt.value.kind === 'f_string') {
+          displayImpls.set(ib.typeName, firstStmt.value.parts)
+        }
+      }
+    }
+  }
+
   // Pre-scan for macro functions
   const macroInfo = detectMacroFunctions(hir)
 
@@ -71,16 +128,25 @@ export function lowerToMIR(hir: HIRModule, sourceFile?: string): MIRModule {
   // Shared registry: specializedName → [mirFn, ...helpers]
   const specializedFnsRegistry = new Map<string, MIRFunction[]>()
 
+  // Build module-level const map: name → integer value (for inlining at use sites)
+  const constValues = new Map<string, number>()
+  for (const c of hir.consts) {
+    if (c.value.kind === 'int_lit') constValues.set(c.name, c.value.value)
+    else if (c.value.kind === 'bool_lit') constValues.set(c.name, c.value.value ? 1 : 0)
+    else if (c.value.kind === 'float_lit') constValues.set(c.name, Math.round(c.value.value * 10000))
+  }
+
   const allFunctions: MIRFunction[] = []
   for (const f of hir.functions) {
-    const { fn, helpers } = lowerFunction(f, hir.namespace, structDefs, implMethods, macroInfo, fnParamInfo, enumDefs, sourceFile, timerCounter, undefined, hirFnMap, specializedFnsRegistry)
+    const { fn, helpers } = lowerFunction(f, hir.namespace, structDefs, implMethods, macroInfo, fnParamInfo, enumDefs, sourceFile, timerCounter, undefined, hirFnMap, specializedFnsRegistry, undefined, enumPayloads, constValues, singletonStructs, displayImpls)
     allFunctions.push(fn, ...helpers)
   }
 
-  // Lower impl block methods
+  // Lower impl block methods (skip Display::to_string — inlined at call sites instead)
   for (const ib of hir.implBlocks) {
+    if (ib.traitName === 'Display') continue  // Display impls are inlined, not emitted as functions
     for (const m of ib.methods) {
-      const { fn, helpers } = lowerImplMethod(m, ib.typeName, hir.namespace, structDefs, implMethods, macroInfo, fnParamInfo, enumDefs, sourceFile, timerCounter)
+      const { fn, helpers } = lowerImplMethod(m, ib.typeName, hir.namespace, structDefs, implMethods, macroInfo, fnParamInfo, enumDefs, sourceFile, timerCounter, enumPayloads, constValues)
       allFunctions.push(fn, ...helpers)
     }
   }
@@ -106,22 +172,26 @@ class FnContext {
   private blockCounter = 0
   readonly blocks: MIRBlock[] = []
   private currentBlock: MIRBlock
-  /** Stack of (loopHeader, loopExit, continueTo) for break/continue */
-  private loopStack: { header: BlockId; exit: BlockId; continueTo: BlockId }[] = []
+  /** Stack of (loopHeader, loopExit, continueTo, label?) for break/continue */
+  private loopStack: { header: BlockId; exit: BlockId; continueTo: BlockId; label?: string }[] = []
+  /** Pending label to attach to the next pushLoop call (set by labeled_loop lowering) */
+  private pendingLoopLabel: string | undefined = undefined
   /** Extracted helper functions for execute blocks */
   readonly helperFunctions: MIRFunction[] = []
   private readonly namespace: string
   private readonly fnName: string
   /** Struct definitions: struct name → field names */
   readonly structDefs: Map<string, string[]>
-  /** Impl method info: typeName → methodName → { hasSelf } */
-  readonly implMethods: Map<string, Map<string, { hasSelf: boolean }>>
+  /** Impl method info: typeName → methodName → { hasSelf, returnStructName? } */
+  readonly implMethods: Map<string, Map<string, { hasSelf: boolean; returnStructName?: string }>>
   /** Struct variable tracking: varName → { typeName, fields: fieldName → temp } */
   readonly structVars = new Map<string, { typeName: string; fields: Map<string, Temp> }>()
   /** Tuple variable tracking: varName → array of element temps (index = slot) */
   readonly tupleVars = new Map<string, Temp[]>()
   /** Array variable tracking: varName → { ns, pathPrefix } for NBT-backed int[] */
   readonly arrayVars = new Map<string, { ns: string; pathPrefix: string; knownLen?: number }>()
+  /** String variable tracking: varName → storage path within rs:strings */
+  readonly stringVars = new Map<string, string>()
   /** Macro function info for all functions in the module */
   readonly macroInfo: Map<string, MacroFunctionInfo>
   /** Function parameter info for call_macro generation */
@@ -130,6 +200,8 @@ class FnContext {
   readonly currentMacroParams: Set<string>
   /** Enum definitions: enumName → variantName → integer value */
   readonly enumDefs: Map<string, Map<string, number>>
+  /** Enum payload fields: enumName → variantName → field list */
+  readonly enumPayloads: Map<string, Map<string, { name: string; type: TypeNode }[]>>
   /** Current source location (set during statement lowering) */
   currentSourceLoc: SourceLoc | undefined = undefined
   /** Source file path for the module being compiled */
@@ -143,20 +215,28 @@ class FnContext {
   /** Tracks double variables: varName → NBT storage path (without "rs:d " prefix) */
   readonly doubleVars = new Map<string, string>()
   private doubleVarCount = 0
+  private stringVarCount = 0
   /** HIR function definitions for array-arg monomorphization */
   hirFunctions: Map<string, HIRFunction> = new Map()
   /** Shared registry of already-generated specialized (monomorphized) MIR functions */
   specializedFnsRegistry: Map<string, MIRFunction[]> = new Map()
+  /** Module-level const values: name → integer value (inlined at use sites) */
+  constValues: Map<string, number> = new Map()
+  /** @singleton struct names — static_call GameState::set(gs) expands struct fields */
+  singletonStructs: Set<string> = new Set()
+  /** Display trait impls: typeName → f-string parts from to_string body (inlined at call sites) */
+  displayImpls: Map<string, HIRFStringPart[]> = new Map()
 
   constructor(
     namespace: string,
     fnName: string,
     structDefs: Map<string, string[]> = new Map(),
-    implMethods: Map<string, Map<string, { hasSelf: boolean }>> = new Map(),
+    implMethods: Map<string, Map<string, { hasSelf: boolean; returnStructName?: string }>> = new Map(),
     macroInfo: Map<string, MacroFunctionInfo> = new Map(),
     fnParamInfo: Map<string, HIRParam[]> = new Map(),
     enumDefs: Map<string, Map<string, number>> = new Map(),
     timerCounter: { count: number; timerId: number } = { count: 0, timerId: 0 },
+    enumPayloads: Map<string, Map<string, { name: string; type: TypeNode }[]>> = new Map(),
   ) {
     this.namespace = namespace
     this.fnName = fnName
@@ -166,6 +246,7 @@ class FnContext {
     this.fnParamInfo = fnParamInfo
     this.currentMacroParams = macroInfo.get(fnName)?.macroParams ?? new Set()
     this.enumDefs = enumDefs
+    this.enumPayloads = enumPayloads
     this.timerCounter = timerCounter
     const entry = this.makeBlock('entry')
     this.currentBlock = entry
@@ -212,18 +293,32 @@ class FnContext {
     return this.currentBlock
   }
 
-  pushLoop(header: BlockId, exit: BlockId, continueTo?: BlockId): void {
-    this.loopStack.push({ header, exit, continueTo: continueTo ?? header })
+  setPendingLoopLabel(label: string): void {
+    this.pendingLoopLabel = label
+  }
+
+  pushLoop(header: BlockId, exit: BlockId, continueTo?: BlockId, label?: string): void {
+    const effectiveLabel = label ?? this.pendingLoopLabel
+    this.pendingLoopLabel = undefined
+    this.loopStack.push({ header, exit, continueTo: continueTo ?? header, label: effectiveLabel })
   }
 
   popLoop(): void {
     this.loopStack.pop()
   }
 
-  currentLoop(): { header: BlockId; exit: BlockId; continueTo: BlockId } | undefined {
+  currentLoop(): { header: BlockId; exit: BlockId; continueTo: BlockId; label?: string } | undefined {
     return this.loopStack[this.loopStack.length - 1]
   }
 
+  /** Find loop by label — searches from innermost to outermost */
+  findLoopByLabel(label: string): { header: BlockId; exit: BlockId; continueTo: BlockId } | undefined {
+    for (let i = this.loopStack.length - 1; i >= 0; i--) {
+      if (this.loopStack[i].label === label) return this.loopStack[i]
+    }
+    return undefined
+  }
+
   getNamespace(): string {
     return this.namespace
   }
@@ -238,6 +333,11 @@ class FnContext {
     this.doubleVars.set(varName, path)
     return path
   }
+
+  /** Allocate a unique NBT storage path for a string value */
+  freshStringVar(varName: string): string {
+    return `${this.namespace}_${this.fnName}_${varName}_${this.stringVarCount++}`
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -248,7 +348,7 @@ function lowerFunction(
   fn: HIRFunction,
   namespace: string,
   structDefs: Map<string, string[]> = new Map(),
-  implMethods: Map<string, Map<string, { hasSelf: boolean }>> = new Map(),
+  implMethods: Map<string, Map<string, { hasSelf: boolean; returnStructName?: string }>> = new Map(),
   macroInfo: Map<string, MacroFunctionInfo> = new Map(),
   fnParamInfo: Map<string, HIRParam[]> = new Map(),
   enumDefs: Map<string, Map<string, number>> = new Map(),
@@ -262,10 +362,17 @@ function lowerFunction(
   specializedFnsRegistry?: Map<string, MIRFunction[]>,
   /** Override the MIR function name (used when generating specialized versions) */
   overrideName?: string,
+  enumPayloads: Map<string, Map<string, { name: string; type: TypeNode }[]>> = new Map(),
+  constValues: Map<string, number> = new Map(),
+  singletonStructs: Set<string> = new Set(),
+  displayImpls: Map<string, HIRFStringPart[]> = new Map(),
 ): { fn: MIRFunction; helpers: MIRFunction[] } {
   const mirFnName = overrideName ?? fn.name
-  const ctx = new FnContext(namespace, mirFnName, structDefs, implMethods, macroInfo, fnParamInfo, enumDefs, timerCounter)
-  ctx.sourceFile = sourceFile
+  const ctx = new FnContext(namespace, mirFnName, structDefs, implMethods, macroInfo, fnParamInfo, enumDefs, timerCounter, enumPayloads)
+  ctx.sourceFile = fn.sourceFile ?? sourceFile
+  ctx.constValues = constValues
+  ctx.singletonStructs = singletonStructs
+  ctx.displayImpls = displayImpls
   if (hirFnMap) ctx.hirFunctions = hirFnMap
   if (specializedFnsRegistry) ctx.specializedFnsRegistry = specializedFnsRegistry
   const fnMacroInfo = macroInfo.get(fn.name)
@@ -282,6 +389,7 @@ function lowerFunction(
   const params: { name: Temp; isMacroParam: boolean }[] = []
   const scope = new Map<string, Temp>()
   let doubleParamSlot = 0
+  let stringParamSlot = 0
   fn.params.forEach((p) => {
     if (p.type.kind === 'array' && arrayArgBindings?.has(p.name)) {
       // Array param already bound via arrayVars; no scoreboard slot needed
@@ -294,6 +402,10 @@ function lowerFunction(
       // No scoreboard param slot; callee reads from rs:d __dp<i> via doubleVars
       return
     }
+    if (p.type.kind === 'named' && (p.type.name === 'string' || p.type.name === 'format_string')) {
+      ctx.stringVars.set(p.name, `__sp${stringParamSlot++}`)
+      return
+    }
     const t = ctx.freshTemp()
     params.push({ name: t, isMacroParam: fnMacroInfo?.macroParams.has(p.name) ?? false })
     scope.set(p.name, t)
@@ -320,6 +432,8 @@ function lowerFunction(
     blocks: liveBlocks,
     entry: 'entry',
     isMacro: fnMacroInfo != null,
+    sourceLoc: fn.span && (fn.sourceFile ?? sourceFile) ? { file: fn.sourceFile ?? sourceFile!, line: fn.span.line, col: fn.span.col } : undefined,
+    sourceSnippet: formatFunctionSignature(fn),
   }
 
   return { fn: result, helpers: ctx.helperFunctions }
@@ -330,16 +444,19 @@ function lowerImplMethod(
   typeName: string,
   namespace: string,
   structDefs: Map<string, string[]>,
-  implMethods: Map<string, Map<string, { hasSelf: boolean }>>,
+  implMethods: Map<string, Map<string, { hasSelf: boolean; returnStructName?: string }>>,
   macroInfo: Map<string, MacroFunctionInfo> = new Map(),
   fnParamInfo: Map<string, HIRParam[]> = new Map(),
   enumDefs: Map<string, Map<string, number>> = new Map(),
   sourceFile?: string,
   timerCounter: { count: number; timerId: number } = { count: 0, timerId: 0 },
+  enumPayloads: Map<string, Map<string, { name: string; type: TypeNode }[]>> = new Map(),
+  constValues: Map<string, number> = new Map(),
 ): { fn: MIRFunction; helpers: MIRFunction[] } {
   const fnName = `${typeName}::${method.name}`
-  const ctx = new FnContext(namespace, fnName, structDefs, implMethods, macroInfo, fnParamInfo, enumDefs, timerCounter)
-  ctx.sourceFile = sourceFile
+  const ctx = new FnContext(namespace, fnName, structDefs, implMethods, macroInfo, fnParamInfo, enumDefs, timerCounter, enumPayloads)
+  ctx.sourceFile = method.sourceFile ?? sourceFile
+  ctx.constValues = constValues
   const fields = structDefs.get(typeName) ?? []
   const hasSelf = method.params.length > 0 && method.params[0].name === 'self'
 
@@ -415,6 +532,8 @@ function lowerImplMethod(
     blocks: liveBlocks,
     entry: 'entry',
     isMacro: macroInfo.has(fnName),
+    sourceLoc: method.span && (method.sourceFile ?? sourceFile) ? { file: method.sourceFile ?? sourceFile!, line: method.span.line, col: method.span.col } : undefined,
+    sourceSnippet: formatFunctionSignature(method),
   }
 
   return { fn: result, helpers: ctx.helperFunctions }
@@ -492,7 +611,13 @@ function lowerStmt(
 
   switch (stmt.kind) {
     case 'let': {
-      if (stmt.init.kind === 'some_lit') {
+      if (stmt.type?.kind === 'named' && (stmt.type.name === 'string' || stmt.type.name === 'format_string')) {
+        const path = lowerStringExprToPath(stmt.init, ctx, scope, stmt.name) ?? ctx.freshStringVar(stmt.name)
+        ctx.stringVars.set(stmt.name, path)
+        const t = ctx.freshTemp()
+        ctx.emit({ kind: 'const', dst: t, value: 0 })
+        scope.set(stmt.name, t)
+      } else if (stmt.init.kind === 'some_lit') {
         // Some(expr) — create option struct vars: has=1, val=expr
         // Use __opt_ prefix so DCE treats these as side-effectful scoreboard writes
         const hasTemp: Temp = `__opt_${stmt.name}_has`
@@ -549,9 +674,18 @@ function lowerStmt(
         ctx.emit({ kind: 'copy', dst: valTemp, src: { kind: 'temp', name: '__rf_val' } })
         const fieldTemps = new Map<string, Temp>([['has', hasTemp], ['val', valTemp]])
         ctx.structVars.set(stmt.name, { typeName: '__option', fields: fieldTemps })
-      } else if (stmt.type?.kind === 'struct') {
+      } else if (
+        // Struct-typed let: explicit annotation OR inferred from @singleton::get() return
+        stmt.type?.kind === 'struct' ||
+        (stmt.init.kind === 'static_call' &&
+          ctx.singletonStructs.has((stmt.init as { kind: 'static_call'; type: string; method: string }).type) &&
+          (stmt.init as { kind: 'static_call'; method: string }).method === 'get')
+      ) {
         // Struct-typed let with non-literal init (e.g., call returning struct)
-        const fields = ctx.structDefs.get(stmt.type.name)
+        const inferredStructName = stmt.type?.kind === 'struct'
+          ? stmt.type.name
+          : (stmt.init as { kind: 'static_call'; type: string }).type
+        const fields = ctx.structDefs.get(inferredStructName)
         if (fields) {
           lowerExpr(stmt.init, ctx, scope)
           // Copy from return field slots into struct variable temps
@@ -567,7 +701,7 @@ function lowerStmt(
               ctx.constTemps.set(t, constVal)
             }
           }
-          ctx.structVars.set(stmt.name, { typeName: stmt.type.name, fields: fieldTemps })
+          ctx.structVars.set(stmt.name, { typeName: inferredStructName, fields: fieldTemps })
         } else {
           const valOp = lowerExpr(stmt.init, ctx, scope)
           const t = ctx.freshTemp()
@@ -701,6 +835,14 @@ function lowerStmt(
       break
     }
 
+    case 'const_decl': {
+      // Evaluate the literal at compile time and store in constValues for inlining at use sites
+      const op = lowerExpr(stmt.value, ctx, scope)
+      const numericValue = op.kind === 'const' ? op.value : 0
+      ctx.constValues.set(stmt.name, numericValue)
+      break
+    }
+
     case 'expr': {
       lowerExpr(stmt.expr, ctx, scope)
       break
@@ -773,6 +915,33 @@ function lowerStmt(
       break
     }
 
+    case 'break_label': {
+      const loop = ctx.findLoopByLabel(stmt.label)
+      if (!loop) throw new Error(`break: label '${stmt.label}' not found`)
+      ctx.terminate({ kind: 'jump', target: loop.exit })
+      const dead = ctx.newBlock('post_break_label')
+      ctx.switchTo(dead)
+      break
+    }
+
+    case 'continue_label': {
+      const loop = ctx.findLoopByLabel(stmt.label)
+      if (!loop) throw new Error(`continue: label '${stmt.label}' not found`)
+      ctx.terminate({ kind: 'jump', target: loop.continueTo })
+      const dead = ctx.newBlock('post_continue_label')
+      ctx.switchTo(dead)
+      break
+    }
+
+    case 'labeled_loop': {
+      // The body is a while/foreach stmt; we need to push the label into the loop stack.
+      // We do this by injecting the label into the next pushLoop call by temporarily
+      // storing the pending label in ctx, then letting the inner loop case handle it.
+      ctx.setPendingLoopLabel(stmt.label)
+      lowerStmt(stmt.body, ctx, scope)
+      break
+    }
+
     case 'if': {
       const condOp = lowerExpr(stmt.cond, ctx, scope)
       const thenBlock = ctx.newBlock('then')
@@ -876,6 +1045,8 @@ function lowerStmt(
         blocks: helperBlocks,
         entry: 'entry',
         isMacro: false,
+        sourceLoc: stmt.span && ctx.sourceFile ? { file: ctx.sourceFile, line: stmt.span.line, col: stmt.span.col } : undefined,
+        sourceSnippet: 'foreach helper',
       })
 
       ctx.emit({ kind: 'call_context', fn: helperName, subcommands })
@@ -903,6 +1074,8 @@ function lowerStmt(
         blocks: execBlocks,
         entry: 'entry',
         isMacro: false,
+        sourceLoc: stmt.span && ctx.sourceFile ? { file: ctx.sourceFile, line: stmt.span.line, col: stmt.span.col } : undefined,
+        sourceSnippet: 'execute helper',
       })
 
       ctx.emit({ kind: 'call_context', fn: helperName, subcommands })
@@ -910,6 +1083,53 @@ function lowerStmt(
     }
 
     case 'match': {
+      const hasStringPats = stmt.arms.some(a =>
+        a.pattern.kind === 'PatExpr' && a.pattern.expr.kind === 'str_lit'
+      )
+      if (hasStringPats) {
+        const matchPath = lowerStringExprToPath(stmt.expr, ctx, scope, 'match')
+        if (!matchPath) {
+          throw new Error('String match requires a string literal or tracked string variable')
+        }
+
+        const mergeBlock = ctx.newBlock('match_merge')
+        for (let i = 0; i < stmt.arms.length; i++) {
+          const arm = stmt.arms[i]
+          const pat = arm.pattern
+
+          if (pat.kind === 'PatWild') {
+            lowerBlock(arm.body, ctx, new Map(scope))
+            if (isPlaceholderTerm(ctx.current().term)) {
+              ctx.terminate({ kind: 'jump', target: mergeBlock.id })
+            }
+            continue
+          }
+
+          if (pat.kind === 'PatExpr' && pat.expr.kind === 'str_lit') {
+            const cmpTemp = ctx.freshTemp()
+            ctx.emit({ kind: 'string_match', dst: cmpTemp, ns: 'rs:strings', path: matchPath, value: pat.expr.value })
+            const armBody = ctx.newBlock('match_arm')
+            const nextArm = ctx.newBlock('match_next')
+            ctx.terminate({ kind: 'branch', cond: { kind: 'temp', name: cmpTemp }, then: armBody.id, else: nextArm.id })
+            ctx.switchTo(armBody)
+            lowerBlock(arm.body, ctx, new Map(scope))
+            if (isPlaceholderTerm(ctx.current().term)) {
+              ctx.terminate({ kind: 'jump', target: mergeBlock.id })
+            }
+            ctx.switchTo(nextArm)
+            continue
+          }
+
+          throw new Error(`Unsupported string match pattern: ${pat.kind}`)
+        }
+
+        if (isPlaceholderTerm(ctx.current().term)) {
+          ctx.terminate({ kind: 'jump', target: mergeBlock.id })
+        }
+        ctx.switchTo(mergeBlock)
+        break
+      }
+
       // Lower match as chained if/else
       const mergeBlock = ctx.newBlock('match_merge')
 
@@ -1005,6 +1225,37 @@ function lowerStmt(
             ctx.terminate({ kind: 'jump', target: mergeBlock.id })
           }
           ctx.switchTo(nextArm)
+        } else if (pat.kind === 'PatEnum') {
+          // Enum pattern: check tag value matches, then bind payload fields via NBT reads
+          const tagValue = ctx.enumDefs.get(pat.enumName)?.get(pat.variant) ?? 0
+          const cmpTemp = ctx.freshTemp()
+          ctx.emit({ kind: 'cmp', dst: cmpTemp, op: 'eq', a: matchVal, b: { kind: 'const', value: tagValue } })
+          const armBody = ctx.newBlock('match_arm')
+          const nextArm = ctx.newBlock('match_next')
+          ctx.terminate({ kind: 'branch', cond: { kind: 'temp', name: cmpTemp }, then: armBody.id, else: nextArm.id })
+          ctx.switchTo(armBody)
+          const armScope = new Map(scope)
+          // Bind each pattern variable by reading the corresponding NBT payload field
+          const payloadFields = ctx.enumPayloads.get(pat.enumName)?.get(pat.variant) ?? []
+          for (let bi = 0; bi < pat.bindings.length; bi++) {
+            const binding = pat.bindings[bi]
+            const fieldDef = payloadFields[bi]
+            const fieldName = fieldDef ? fieldDef.name : binding
+            const bindTemp = ctx.freshTemp()
+            ctx.emit({
+              kind: 'nbt_read',
+              dst: bindTemp,
+              ns: 'rs:enums',
+              path: `${pat.enumName}_${fieldName}`,
+              scale: 1,
+            })
+            armScope.set(binding, bindTemp)
+          }
+          lowerBlock(arm.body, ctx, armScope)
+          if (isPlaceholderTerm(ctx.current().term)) {
+            ctx.terminate({ kind: 'jump', target: mergeBlock.id })
+          }
+          ctx.switchTo(nextArm)
         } else if (pat.kind === 'PatExpr') {
           // Legacy: range_lit or other expression
           const expr = pat.expr
@@ -1126,6 +1377,58 @@ function lowerStmt(
       break
     }
 
+    case 'while_let_some': {
+      // while let Some(x) = init { body }
+      // Compiles to: loop { check opt.has; if 0 break; bind x = opt.val; body }
+      const headerBlock = ctx.newBlock('whl_header')
+      const bodyBlock = ctx.newBlock('whl_body')
+      const exitBlock = ctx.newBlock('whl_exit')
+
+      ctx.terminate({ kind: 'jump', target: headerBlock.id })
+
+      // Header: re-evaluate init and check has
+      ctx.switchTo(headerBlock)
+
+      let hasOp: Operand
+      let valTemp: Temp | undefined
+
+      const sv = (() => {
+        if (stmt.init.kind === 'ident') return ctx.structVars.get(stmt.init.name)
+        return undefined
+      })()
+
+      if (sv && sv.typeName === '__option') {
+        const hasT = sv.fields.get('has')!
+        const valT = sv.fields.get('val')!
+        hasOp = { kind: 'temp', name: hasT }
+        valTemp = valT
+      } else {
+        lowerExpr(stmt.init, ctx, scope)
+        const hasT = ctx.freshTemp()
+        const valT = ctx.freshTemp()
+        ctx.emit({ kind: 'copy', dst: hasT, src: { kind: 'temp', name: '__rf_has' } })
+        ctx.emit({ kind: 'copy', dst: valT, src: { kind: 'temp', name: '__rf_val' } })
+        hasOp = { kind: 'temp', name: hasT }
+        valTemp = valT
+      }
+
+      ctx.terminate({ kind: 'branch', cond: hasOp, then: bodyBlock.id, else: exitBlock.id })
+
+      // Body: bind x = val, run body
+      ctx.switchTo(bodyBlock)
+      const bodyScope = new Map(scope)
+      if (valTemp) bodyScope.set(stmt.binding, valTemp)
+      ctx.pushLoop(headerBlock.id, exitBlock.id, headerBlock.id)
+      lowerBlock(stmt.body, ctx, bodyScope)
+      ctx.popLoop()
+      if (isPlaceholderTerm(ctx.current().term)) {
+        ctx.terminate({ kind: 'jump', target: headerBlock.id })
+      }
+
+      ctx.switchTo(exitBlock)
+      break
+    }
+
     default: {
       const _exhaustive: never = stmt
       throw new Error(`Unknown HIR statement kind: ${(_exhaustive as any).kind}`)
@@ -1213,6 +1516,10 @@ function lowerExpr(
       }
       const temp = scope.get(expr.name)
       if (temp) return { kind: 'temp', name: temp }
+      // Module-level const: inline the literal value directly (no scoreboard slot)
+      if (ctx.constValues.has(expr.name)) {
+        return { kind: 'const', value: ctx.constValues.get(expr.name)! }
+      }
       // Unresolved ident — could be a global or external reference
       const t = ctx.freshTemp()
       ctx.emit({ kind: 'copy', dst: t, src: { kind: 'const', value: 0 } })
@@ -1346,6 +1653,36 @@ function lowerExpr(
       return { kind: 'const', value }
     }
 
+    case 'enum_construct': {
+      // Enum variant construction with payload:
+      //   Color::RGB(r: 10, g: 20, b: 30)
+      // → scoreboard set tag = variant int value
+      // → nbt_write rs:enums Color_r = 10, Color_g = 20, Color_b = 30
+      const variants = ctx.enumDefs.get(expr.enumName)
+      const tagValue = variants?.get(expr.variant) ?? 0
+      // Write tag to a temp (the result of the expression is the integer tag)
+      const tagTemp = ctx.freshTemp()
+      ctx.emit({ kind: 'const', dst: tagTemp, value: tagValue })
+      // Write payload fields to NBT storage rs:enums
+      const payloadFields = ctx.enumPayloads.get(expr.enumName)?.get(expr.variant) ?? []
+      for (const arg of expr.args) {
+        const fieldDef = payloadFields.find(f => f.name === arg.name)
+        const argOp = lowerExpr(arg.value, ctx, scope)
+        // Determine NBT type from field definition
+        const nbtType: NBTType = fieldDef && (fieldDef.type.kind === 'named') &&
+          (fieldDef.type.name === 'float' || fieldDef.type.name === 'fixed') ? 'float' : 'int'
+        ctx.emit({
+          kind: 'nbt_write',
+          ns: 'rs:enums',
+          path: `${expr.enumName}_${arg.name}`,
+          type: nbtType,
+          scale: 1,
+          src: argOp,
+        })
+      }
+      return { kind: 'temp', name: tagTemp }
+    }
+
     case 'member': {
       // Enum variant access via dot syntax: Phase.Idle → integer constant
       if (expr.obj.kind === 'ident') {
@@ -1695,9 +2032,57 @@ function lowerExpr(
         return { kind: 'temp', name: t }
       }
 
+      // Handle int_to_str / bool_to_str — identity functions for scoreboard int/bool → string
+      // In f-string context these are handled by precomputeFStringParts; outside that, just
+      // evaluate the argument and return it (integer stays as integer for scoreboard purposes).
+      if (expr.fn === 'int_to_str' || expr.fn === 'bool_to_str') {
+        if (expr.args.length === 1) {
+          return lowerExpr(expr.args[0], ctx, scope)
+        }
+        const t = ctx.freshTemp()
+        ctx.emit({ kind: 'const', dst: t, value: 0 })
+        return { kind: 'temp', name: t }
+      }
+
+      // Handle assert(cond[, message]) — test framework builtin
+      if (expr.fn === 'assert') {
+        const condArg = expr.args[0]
+        const msgArg = expr.args[1]
+        const condOp = condArg ? lowerExpr(condArg, ctx, scope) : { kind: 'const' as const, value: 0 }
+        // Evaluate condition to a temp
+        let condTemp: string
+        if (condOp.kind === 'temp') {
+          condTemp = condOp.name
+        } else {
+          condTemp = ctx.freshTemp()
+          ctx.emit({ kind: 'const', dst: condTemp, value: condOp.value })
+        }
+        // Get message string
+        let msgStr = 'assert failed'
+        if (msgArg && msgArg.kind === 'str_lit') {
+          msgStr = msgArg.value
+        }
+        const obj = `__${ctx.getNamespace()}`
+        // emit: execute unless score $condTemp <obj> matches 1 run tellraw @a "FAIL: <msg>"
+        const failMsg = JSON.stringify({ text: `FAIL: ${msgStr}`, color: 'red' })
+        ctx.emit({ kind: 'call', dst: null, fn: `__raw:execute unless score $${ctx.getFnName()}_${condTemp} ${obj} matches 1 run tellraw @a ${failMsg}`, args: [] })
+        ctx.emit({ kind: 'call', dst: null, fn: `__raw:execute unless score $${ctx.getFnName()}_${condTemp} ${obj} matches 1 run scoreboard players add rs.test_failed rs.meta 1`, args: [] })
+        const t = ctx.freshTemp()
+        ctx.emit({ kind: 'const', dst: t, value: 0 })
+        return { kind: 'temp', name: t }
+      }
+
       // Handle builtin calls → raw MC commands
       if (BUILTIN_SET.has(expr.fn)) {
-        const cmd = formatBuiltinCall(expr.fn, expr.args, ctx.currentMacroParams, ctx.getNamespace())
+        // For text builtins with f-string args, precompute complex expressions to temp vars
+        const TEXT_BUILTINS_SET = new Set(['tell', 'tellraw', 'title', 'subtitle', 'actionbar', 'announce'])
+        let resolvedArgs = expr.args
+        if (TEXT_BUILTINS_SET.has(expr.fn)) {
+          resolvedArgs = expr.args.map(arg =>
+            arg.kind === 'f_string' ? precomputeFStringParts(arg, ctx, scope) : arg
+          )
+        }
+        const cmd = formatBuiltinCall(expr.fn, resolvedArgs, ctx.currentMacroParams, ctx.getNamespace())
         ctx.emit({ kind: 'call', dst: null, fn: `__raw:${cmd}`, args: [] })
         const t = ctx.freshTemp()
         ctx.emit({ kind: 'const', dst: t, value: 0 })
@@ -1705,9 +2090,24 @@ function lowerExpr(
       }
 
       // Check for struct instance method call: parser desugars v.method() → call('method', [v, ...])
+      // Some method names are remapped by the parser (e.g. add→set_add for set builtins).
+      // We reverse-map them here to support impl methods with those names.
+      const PARSER_METHOD_REMAP: Record<string, string> = {
+        'set_add': 'add', 'set_contains': 'contains', 'set_remove': 'remove', 'set_clear': 'clear',
+        '__array_push': 'push', '__array_pop': 'pop',
+        '__entity_tag': 'tag', '__entity_untag': 'untag', '__entity_has_tag': 'has_tag',
+      }
       if (expr.args.length > 0 && expr.args[0].kind === 'ident') {
         const sv = ctx.structVars.get(expr.args[0].name)
         if (sv) {
+          // Intercept Display::to_string() calls — inlined at f-string call sites; return 0 otherwise
+          if (expr.fn === 'to_string' && ctx.displayImpls.has(sv.typeName)) {
+            // Display::to_string() is expanded inline in f-string context (precomputeFStringParts).
+            // Outside of that context, return a dummy 0 (the call is not valid standalone).
+            const t = ctx.freshTemp()
+            ctx.emit({ kind: 'const', dst: t, value: 0 })
+            return { kind: 'temp', name: t }
+          }
           // Intercept Timer method calls when _id is a known compile-time constant
           if (sv.typeName === 'Timer') {
             const idTemp = sv.fields.get('_id')
@@ -1716,7 +2116,10 @@ function lowerExpr(
               return lowerTimerMethod(expr.fn, timerId, sv, ctx, scope, expr.args.slice(1))
             }
           }
+          // Try direct name, then try reverse-mapped name (for parser-remapped builtins)
+          const originalMethodName = PARSER_METHOD_REMAP[expr.fn] ?? expr.fn
           const methodInfo = ctx.implMethods.get(sv.typeName)?.get(expr.fn)
+            ?? ctx.implMethods.get(sv.typeName)?.get(originalMethodName)
           if (methodInfo?.hasSelf) {
             // Build args: self fields first, then remaining explicit args
             const fields = ctx.structDefs.get(sv.typeName) ?? []
@@ -1745,7 +2148,7 @@ function lowerExpr(
             }
             const allArgs = [...selfArgs, ...explicitArgs]
             const t = ctx.freshTemp()
-            ctx.emit({ kind: 'call', dst: t, fn: `${sv.typeName}::${expr.fn}`, args: allArgs })
+            ctx.emit({ kind: 'call', dst: t, fn: `${sv.typeName}::${originalMethodName}`, args: allArgs })
             return { kind: 'temp', name: t }
           }
         }
@@ -1754,21 +2157,45 @@ function lowerExpr(
       // Check if calling a macro function → emit call_macro
       const targetMacro = ctx.macroInfo.get(expr.fn)
       if (targetMacro) {
-        const args = expr.args.map(a => lowerExpr(a, ctx, scope))
         const targetParams = ctx.fnParamInfo.get(expr.fn) ?? []
         const macroArgs: { name: string; value: Operand; type: NBTType; scale: number }[] = []
-        for (let i = 0; i < targetParams.length && i < args.length; i++) {
+        for (let i = 0; i < targetParams.length && i < expr.args.length; i++) {
           const paramName = targetParams[i].name
           if (targetMacro.macroParams.has(paramName)) {
             const paramTypeName = targetMacro.paramTypes.get(paramName) ?? 'int'
-            const isFloat = paramTypeName === 'float'
-            const isFixed = paramTypeName === 'fixed'
-            macroArgs.push({
-              name: paramName,
-              value: args[i],
-              type: (isFloat || isFixed) ? 'double' : 'int',
-              scale: isFloat ? 0.01 : isFixed ? 0.0001 : 1,
-            })
+            const isString = paramTypeName === 'string' || paramTypeName === 'format_string'
+            const isSelector = paramTypeName === 'selector'
+            if (isString) {
+              // String macro params: store directly to rs:macro_args as NBT string
+              const srcPath = lowerStringExprToPath(expr.args[i], ctx, scope, paramName)
+              if (srcPath) {
+                ctx.emit({
+                  kind: 'call',
+                  dst: null,
+                  fn: `__raw:data modify storage rs:macro_args ${paramName} set from storage rs:strings ${srcPath}`,
+                  args: [],
+                })
+              }
+            } else if (isSelector) {
+              // Selector macro params: store the selector string as an NBT string in rs:macro_args
+              const arg = expr.args[i]
+              const selStr = arg.kind === 'selector' ? arg.raw : '@s'
+              ctx.emit({
+                kind: 'call',
+                dst: null,
+                fn: `__raw:data modify storage rs:macro_args ${paramName} set value ${JSON.stringify(selStr)}`,
+                args: [],
+              })
+            } else {
+              const isFloat = paramTypeName === 'float'
+              const isFixed = paramTypeName === 'fixed'
+              macroArgs.push({
+                name: paramName,
+                value: lowerExpr(expr.args[i], ctx, scope),
+                type: (isFloat || isFixed) ? 'double' : 'int',
+                scale: isFloat ? 0.01 : isFixed ? 0.0001 : 1,
+              })
+            }
           }
         }
         const t = ctx.freshTemp()
@@ -1818,6 +2245,10 @@ function lowerExpr(
                 ctx.hirFunctions,
                 ctx.specializedFnsRegistry,
                 specializedName,
+                ctx.enumPayloads,
+                ctx.constValues,
+                ctx.singletonStructs,
+                ctx.displayImpls,
               )
               ctx.specializedFnsRegistry.set(specializedName, [specFn, ...specHelpers])
             }
@@ -1842,6 +2273,36 @@ function lowerExpr(
       {
         const targetParams = ctx.fnParamInfo.get(expr.fn)
         if (targetParams) {
+          const hasStringParam = targetParams.some(
+            p => p.type.kind === 'named' && (p.type.name === 'string' || p.type.name === 'format_string')
+          )
+          if (hasStringParam) {
+            const nonStringArgs: Operand[] = []
+            let stringSlot = 0
+            for (let i = 0; i < targetParams.length && i < expr.args.length; i++) {
+              const p = targetParams[i]
+              if (p.type.kind === 'named' && (p.type.name === 'string' || p.type.name === 'format_string')) {
+                const srcPath = lowerStringExprToPath(expr.args[i], ctx, scope, `arg${stringSlot}`)
+                if (srcPath) {
+                  ctx.emit({
+                    kind: 'call',
+                    dst: null,
+                    fn: `__raw:data modify storage rs:strings __sp${stringSlot} set from storage rs:strings ${srcPath}`,
+                    args: [],
+                  })
+                }
+                stringSlot++
+              } else {
+                nonStringArgs.push(lowerExpr(expr.args[i], ctx, scope))
+              }
+            }
+            for (let i = targetParams.length; i < expr.args.length; i++) {
+              nonStringArgs.push(lowerExpr(expr.args[i], ctx, scope))
+            }
+            const t = ctx.freshTemp()
+            ctx.emit({ kind: 'call', dst: t, fn: expr.fn, args: nonStringArgs })
+            return { kind: 'temp', name: t }
+          }
           const hasDoubleParam = targetParams.some(
             p => p.type.kind === 'named' && p.type.name === 'double'
           )
@@ -1914,6 +2375,12 @@ function lowerExpr(
       if (expr.callee.kind === 'member' && expr.callee.obj.kind === 'ident') {
         const sv = ctx.structVars.get(expr.callee.obj.name)
         if (sv) {
+          // Intercept Display::to_string() — inlined in f-string context; return 0 otherwise
+          if (expr.callee.field === 'to_string' && ctx.displayImpls.has(sv.typeName)) {
+            const t = ctx.freshTemp()
+            ctx.emit({ kind: 'const', dst: t, value: 0 })
+            return { kind: 'temp', name: t }
+          }
           // Intercept Timer method calls when _id is a known compile-time constant
           if (sv.typeName === 'Timer') {
             const idTemp = sv.fields.get('_id')
@@ -1938,6 +2405,35 @@ function lowerExpr(
           }
         }
       }
+      // Method chaining: callee obj is not a simple ident (e.g. v.scale(2).add(...))
+      // Determine if the callee obj expression returns a struct via __rf_ slots
+      if (expr.callee.kind === 'member' && expr.callee.obj.kind !== 'ident') {
+        const returnedStructType = inferInvokeReturnStructType(expr.callee.obj, ctx)
+        if (returnedStructType) {
+          // Lower the inner call — result goes into __rf_ slots
+          lowerExpr(expr.callee.obj, ctx, scope)
+          // Read __rf_ slots into temps for this chained call
+          const chainFields = ctx.structDefs.get(returnedStructType) ?? []
+          const chainFieldTemps = new Map<string, Temp>()
+          for (const fieldName of chainFields) {
+            const ft = ctx.freshTemp()
+            ctx.emit({ kind: 'copy', dst: ft, src: { kind: 'temp', name: `__rf_${fieldName}` } })
+            chainFieldTemps.set(fieldName, ft)
+          }
+          const methodInfo = ctx.implMethods.get(returnedStructType)?.get(expr.callee.field)
+          if (methodInfo?.hasSelf) {
+            const selfArgs: Operand[] = chainFields.map(f => {
+              const temp = chainFieldTemps.get(f)
+              return temp ? { kind: 'temp' as const, name: temp } : { kind: 'const' as const, value: 0 }
+            })
+            const explicitArgs = expr.args.map(a => lowerExpr(a, ctx, scope))
+            const allArgs = [...selfArgs, ...explicitArgs]
+            const ct = ctx.freshTemp()
+            ctx.emit({ kind: 'call', dst: ct, fn: `${returnedStructType}::${expr.callee.field}`, args: allArgs })
+            return { kind: 'temp', name: ct }
+          }
+        }
+      }
       // Fallback: generic invoke
       const calleeOp = lowerExpr(expr.callee, ctx, scope)
       const args = expr.args.map(a => lowerExpr(a, ctx, scope))
@@ -1965,6 +2461,28 @@ function lowerExpr(
         ctx.emit({ kind: 'const', dst: t, value: 0 })
         return { kind: 'temp', name: t }
       }
+      // @singleton struct static calls: expand struct arg field-by-field for ::set
+      if (ctx.singletonStructs.has(expr.type)) {
+        if (expr.method === 'get') {
+          // GameState::get() — no struct args, our synthetic LIR fn writes to $__rf_<field> slots
+          const t = ctx.freshTemp()
+          ctx.emit({ kind: 'call', dst: t, fn: `${expr.type}::${expr.method}`, args: [] })
+          return { kind: 'temp', name: t }
+        } else if (expr.method === 'set' && expr.args.length === 1 && expr.args[0].kind === 'ident') {
+          // GameState::set(gs) — flatten struct arg into individual field args ($p0, $p1, ...)
+          const sv = ctx.structVars.get(expr.args[0].name)
+          if (sv) {
+            const fields = ctx.structDefs.get(sv.typeName) ?? []
+            const fieldArgs: Operand[] = fields.map(f => {
+              const temp = sv.fields.get(f)
+              return temp ? { kind: 'temp' as const, name: temp } : { kind: 'const' as const, value: 0 }
+            })
+            const t = ctx.freshTemp()
+            ctx.emit({ kind: 'call', dst: t, fn: `${expr.type}::${expr.method}`, args: fieldArgs })
+            return { kind: 'temp', name: t }
+          }
+        }
+      }
       const args = expr.args.map(a => lowerExpr(a, ctx, scope))
       const t = ctx.freshTemp()
       ctx.emit({ kind: 'call', dst: t, fn: `${expr.type}::${expr.method}`, args })
@@ -2002,6 +2520,47 @@ function lowerExpr(
       return { kind: 'temp', name: t }
     }
 
+    case 'unwrap_or': {
+      // opt.unwrap_or(default) → evaluate opt, if has=1 return val else return default
+      const resultTemp = ctx.freshTemp()
+      const defaultOp = lowerExpr(expr.default_, ctx, scope)
+      ctx.emit({ kind: 'copy', dst: resultTemp, src: defaultOp })
+
+      const sv = (() => {
+        if (expr.opt.kind === 'ident') return ctx.structVars.get(expr.opt.name)
+        return undefined
+      })()
+
+      let hasOp: Operand
+      let valTemp: Temp | undefined
+
+      if (sv && sv.typeName === '__option') {
+        const hasT = sv.fields.get('has')!
+        const valT = sv.fields.get('val')!
+        hasOp = { kind: 'temp', name: hasT }
+        valTemp = valT
+      } else {
+        lowerExpr(expr.opt, ctx, scope)
+        const hasT = ctx.freshTemp()
+        const valT = ctx.freshTemp()
+        ctx.emit({ kind: 'copy', dst: hasT, src: { kind: 'temp', name: '__rf_has' } })
+        ctx.emit({ kind: 'copy', dst: valT, src: { kind: 'temp', name: '__rf_val' } })
+        hasOp = { kind: 'temp', name: hasT }
+        valTemp = valT
+      }
+
+      const someBlock = ctx.newBlock('unwrap_some')
+      const mergeBlock = ctx.newBlock('unwrap_merge')
+      ctx.terminate({ kind: 'branch', cond: hasOp, then: someBlock.id, else: mergeBlock.id })
+
+      ctx.switchTo(someBlock)
+      if (valTemp) ctx.emit({ kind: 'copy', dst: resultTemp, src: { kind: 'temp', name: valTemp } })
+      ctx.terminate({ kind: 'jump', target: mergeBlock.id })
+
+      ctx.switchTo(mergeBlock)
+      return { kind: 'temp', name: resultTemp }
+    }
+
     case 'type_cast': {
       const ns = ctx.getNamespace()
       const targetName = expr.targetType.kind === 'named' ? expr.targetType.name : null
@@ -2157,6 +2716,34 @@ function lowerShortCircuitOr(
 // Timer method inlining
 // ---------------------------------------------------------------------------
 
+/**
+ * Infer the struct type name returned by a chained invoke/call expression.
+ * Used to support method chaining: v.scale(2).add(...) where scale() returns Vec2.
+ * Returns the struct type name if determinable, otherwise undefined.
+ */
+function inferInvokeReturnStructType(
+  expr: HIRExpr,
+  ctx: FnContext,
+): string | undefined {
+  if (expr.kind === 'invoke' && expr.callee.kind === 'member') {
+    // Find the receiver type via structVars
+    let receiverTypeName: string | undefined
+    if (expr.callee.obj.kind === 'ident') {
+      receiverTypeName = ctx.structVars.get(expr.callee.obj.name)?.typeName
+    } else {
+      // Recursively infer the type for deeper chains
+      receiverTypeName = inferInvokeReturnStructType(expr.callee.obj, ctx)
+    }
+    if (receiverTypeName) {
+      const methodInfo = ctx.implMethods.get(receiverTypeName)?.get(expr.callee.field)
+      if (methodInfo?.returnStructName) {
+        return methodInfo.returnStructName
+      }
+    }
+  }
+  return undefined
+}
+
 /**
  * Inline a Timer instance method call using the statically-assigned timer ID.
  * Emits scoreboard operations directly, bypassing the Timer::* function calls.
@@ -2296,6 +2883,43 @@ function lowerExecuteSubcmd(sub: HIRExecuteSubcommand): ExecuteSubcmd {
   }
 }
 
+function lowerStringExprToPath(
+  expr: HIRExpr,
+  ctx: FnContext,
+  scope: Map<string, Temp>,
+  hint = 'str',
+): string | null {
+  switch (expr.kind) {
+    case 'str_lit': {
+      const path = ctx.freshStringVar(hint)
+      ctx.emit({
+        kind: 'call',
+        dst: null,
+        fn: `__raw:data modify storage rs:strings ${path} set value ${JSON.stringify(expr.value)}`,
+        args: [],
+      })
+      return path
+    }
+    case 'ident':
+      return ctx.stringVars.get(expr.name) ?? null
+    case 'assign': {
+      if (!ctx.stringVars.has(expr.target)) return null
+      const dstPath = ctx.stringVars.get(expr.target)!
+      const srcPath = lowerStringExprToPath(expr.value, ctx, scope, expr.target)
+      if (!srcPath || srcPath === dstPath) return dstPath
+      ctx.emit({
+        kind: 'call',
+        dst: null,
+        fn: `__raw:data modify storage rs:strings ${dstPath} set from storage rs:strings ${srcPath}`,
+        args: [],
+      })
+      return dstPath
+    }
+    default:
+      return null
+  }
+}
+
 function selectorToString(sel: { kind: string; filters?: any }): string {
   // EntitySelector has kind like '@a', '@e', '@s', etc.
   // Filters are key=value pairs that become [key=value,key=value]
@@ -2336,6 +2960,105 @@ const MACRO_SENTINEL = '\x01'
  * Convert an f_string HIRExpr to a Minecraft JSON text component string.
  * Each interpolated variable becomes a {"score":{"name":"$var","objective":"__ns"}} component.
  */
+/**
+ * Pre-evaluate complex f-string expression parts to MIR temp vars,
+ * returning a rewritten HIRExpr where each complex part is replaced by a simple ident.
+ */
+function precomputeFStringParts(
+  expr: HIRExpr,
+  ctx: FnContext,
+  scope: Map<string, Temp>,
+): HIRExpr {
+  if (expr.kind !== 'f_string') return expr
+
+  const newParts: HIRFStringPart[] = []
+
+  for (const part of expr.parts) {
+    if (part.kind === 'text') {
+      newParts.push(part)
+      continue
+    }
+
+    const inner: HIRExpr = part.expr
+    // Simple cases that fStringToJsonText already handles
+    if (inner.kind === 'ident' || inner.kind === 'int_lit' || inner.kind === 'bool_lit') {
+      newParts.push({ kind: 'expr', expr: inner })
+      continue
+    }
+
+    // Display::to_string() inline expansion in f-string context:
+    // v.to_string() (desugared as call{fn:'to_string', args:[v]}) → inline the Display impl's f-string
+    if (inner.kind === 'call' && inner.fn === 'to_string' && inner.args.length === 1 && inner.args[0].kind === 'ident') {
+      const argName = (inner.args[0] as { kind: 'ident'; name: string }).name
+      const sv = ctx.structVars.get(argName)
+      if (sv && ctx.displayImpls.has(sv.typeName)) {
+        const displayParts = ctx.displayImpls.get(sv.typeName)!
+        // Expand Display impl parts, substituting self.<field> with the actual struct field temps
+        for (const dp of displayParts) {
+          if (dp.kind === 'text') {
+            newParts.push(dp)
+          } else {
+            const dpExpr = dp.expr
+            // member(ident('self'), field) → lookup struct field temp
+            if (dpExpr.kind === 'member' && dpExpr.obj.kind === 'ident' && dpExpr.obj.name === 'self') {
+              const fieldTemp = sv.fields.get(dpExpr.field)
+              if (fieldTemp) {
+                newParts.push({ kind: 'expr', expr: { kind: 'ident', name: fieldTemp } })
+              } else {
+                newParts.push({ kind: 'expr', expr: { kind: 'int_lit', value: 0 } })
+              }
+            } else {
+              // Other expressions: lower them with self fields in scope
+              const selfScope = new Map(scope)
+              for (const [fieldName, fieldTemp] of sv.fields) {
+                selfScope.set(`self.${fieldName}`, fieldTemp)
+              }
+              const tempOp = lowerExpr(dpExpr, ctx, selfScope)
+              if (tempOp.kind === 'temp') {
+                newParts.push({ kind: 'expr', expr: { kind: 'ident', name: tempOp.name } })
+              } else if (tempOp.kind === 'const') {
+                newParts.push({ kind: 'expr', expr: { kind: 'int_lit', value: tempOp.value } })
+              }
+            }
+          }
+        }
+        continue
+      }
+    }
+
+    // int_to_str(x) / bool_to_str(x) in f-string: pass through the inner arg as a scoreboard score ref
+    if (inner.kind === 'call' && (inner.fn === 'int_to_str' || inner.fn === 'bool_to_str') && inner.args.length === 1) {
+      const arg: HIRExpr = inner.args[0]
+      if (arg.kind === 'ident') {
+        newParts.push({ kind: 'expr', expr: arg })
+        continue
+      }
+      // If arg is complex, lower it first
+      const argOp = lowerExpr(arg, ctx, scope)
+      if (argOp.kind === 'temp') {
+        newParts.push({ kind: 'expr', expr: { kind: 'ident', name: argOp.name } })
+      } else if (argOp.kind === 'const') {
+        newParts.push({ kind: 'expr', expr: { kind: 'int_lit', value: argOp.value } })
+      } else {
+        newParts.push(part)
+      }
+      continue
+    }
+
+    // Complex expression: lower to a temp var, then reference it as ident
+    const tempOp = lowerExpr(inner, ctx, scope)
+    if (tempOp.kind === 'temp') {
+      newParts.push({ kind: 'expr', expr: { kind: 'ident', name: tempOp.name } })
+    } else if (tempOp.kind === 'const') {
+      newParts.push({ kind: 'expr', expr: { kind: 'int_lit', value: tempOp.value } })
+    } else {
+      newParts.push(part)
+    }
+  }
+
+  return { kind: 'f_string', parts: newParts }
+}
+
 function fStringToJsonText(expr: HIRExpr, namespace: string): string {
   if (expr.kind !== 'f_string') return JSON.stringify(expr.kind === 'str_lit' ? { text: expr.value } : { text: '~' })
   const objective = `__${namespace}`
@@ -2344,12 +3067,14 @@ function fStringToJsonText(expr: HIRExpr, namespace: string): string {
     if (part.kind === 'text') {
       if (part.value) extra.push({ text: part.value })
     } else {
-      // expr part — must be a scoreboard variable (ident)
-      const inner = part.expr
+      // expr part — must be a scoreboard variable (ident) or literal
+      const inner = part.expr as HIRExpr
       if (inner.kind === 'ident') {
         extra.push({ score: { name: `$${inner.name}`, objective } })
       } else if (inner.kind === 'int_lit') {
         extra.push({ text: String(inner.value) })
+      } else if (inner.kind === 'bool_lit') {
+        extra.push({ text: inner.value ? 'true' : 'false' })
       } else {
         extra.push({ text: '?' })
       }
@@ -2473,6 +3198,26 @@ function formatBuiltinCall(
     case 'difficulty': cmd = `difficulty ${strs[0]}`; break
     case 'xp_add': cmd = `xp add ${strs[0]} ${strs[1]} ${strs[2] ?? 'points'}`; break
     case 'xp_set': cmd = `xp set ${strs[0]} ${strs[1]} ${strs[2] ?? 'points'}`; break
+    case 'scoreboard_add_objective': cmd = strs[2] ? `scoreboard objectives add ${strs[0]} ${strs[1]} ${strs[2]}` : `scoreboard objectives add ${strs[0]} ${strs[1]}`; break
+    case 'scoreboard_remove_objective': cmd = `scoreboard objectives remove ${strs[0]}`; break
+    case 'scoreboard_display': cmd = `scoreboard objectives setdisplay ${strs[0]} ${strs[1] ?? ''}`; break
+    case 'scoreboard_hide': cmd = `scoreboard objectives setdisplay ${strs[0]}`; break
+    case 'team_add': cmd = strs[1] ? `team add ${strs[0]} ${strs[1]}` : `team add ${strs[0]}`; break
+    case 'team_remove': cmd = `team remove ${strs[0]}`; break
+    case 'team_join': cmd = `team join ${strs[0]} ${strs[1]}`; break
+    case 'team_leave': cmd = `team leave ${strs[0]}`; break
+    case 'team_option': cmd = `team modify ${strs[0]} ${strs[1]} ${strs[2]}`; break
+    case 'bossbar_add': cmd = `bossbar add ${strs[0]} ${strs[1] ? JSON.stringify({ text: strs[1] }) : '""'}`; break
+    case 'bossbar_remove': cmd = `bossbar remove ${strs[0]}`; break
+    case 'bossbar_set_value': cmd = `bossbar set ${strs[0]} value ${strs[1]}`; break
+    case 'bossbar_get_value': cmd = `bossbar get ${strs[0]} value`; break
+    case 'bossbar_set_max': cmd = `bossbar set ${strs[0]} max ${strs[1]}`; break
+    case 'bossbar_set_color': cmd = `bossbar set ${strs[0]} color ${strs[1]}`; break
+    case 'bossbar_set_style': cmd = `bossbar set ${strs[0]} style ${strs[1]}`; break
+    case 'bossbar_set_visible': cmd = `bossbar set ${strs[0]} visible ${strs[1]}`; break
+    case 'bossbar_set_players': cmd = `bossbar set ${strs[0]} players ${strs[1]}`; break
+    case 'data_get': cmd = `data get ${strs[0]} ${strs[1]} ${strs[2] ?? ''}`.trimEnd(); break
+    case 'data_merge': cmd = `data merge ${strs[0]} ${strs[1]} ${strs[2]}`; break
     default: cmd = `${fn} ${strs.join(' ')}`
   }