redscript-mc 2.3.0 → 2.4.0

package/src/hir/lower.ts

@@ -409,6 +409,36 @@ function lowerExpr(expr: Expr): HIRExpr {
     case 'index':
       return { kind: 'index', obj: lowerExpr(expr.obj), index: lowerExpr(expr.index), span: expr.span }
 
+    // --- Desugaring: compound index_assign → plain index_assign ---
+    case 'index_assign':
+      if (expr.op !== '=') {
+        const binOp = COMPOUND_TO_BINOP[expr.op]
+        const obj = lowerExpr(expr.obj)
+        const index = lowerExpr(expr.index)
+        return {
+          kind: 'index_assign',
+          obj,
+          index,
+          op: '=' as const,
+          value: {
+            kind: 'binary',
+            op: binOp as any,
+            left: { kind: 'index', obj, index },
+            right: lowerExpr(expr.value),
+            span: expr.span,
+          },
+          span: expr.span,
+        }
+      }
+      return {
+        kind: 'index_assign',
+        obj: lowerExpr(expr.obj),
+        index: lowerExpr(expr.index),
+        op: expr.op,
+        value: lowerExpr(expr.value),
+        span: expr.span,
+      }
+
     case 'call':
       return { kind: 'call', fn: expr.fn, args: expr.args.map(lowerExpr), typeArgs: expr.typeArgs, span: expr.span }
 

package/src/hir/monomorphize.ts

@@ -312,6 +312,8 @@ class Monomorphizer {
         return { ...expr, value: this.rewriteExpr(expr.value, ctx) }
       case 'member_assign':
         return { ...expr, obj: this.rewriteExpr(expr.obj, ctx), value: this.rewriteExpr(expr.value, ctx) }
+      case 'index_assign':
+        return { ...expr, obj: this.rewriteExpr(expr.obj, ctx), index: this.rewriteExpr(expr.index, ctx), value: this.rewriteExpr(expr.value, ctx) }
       case 'member':
         return { ...expr, obj: this.rewriteExpr(expr.obj, ctx) }
       case 'index':

package/src/hir/types.ts

@@ -24,7 +24,7 @@ import type {
   EntityTypeName,
   LambdaParam,
 } from '../ast/types'
-import type { BinOp, CmpOp } from '../ast/types'
+import type { BinOp, CmpOp, AssignOp } from '../ast/types'
 
 // Re-export types that HIR shares with AST unchanged
 export type {
@@ -40,6 +40,7 @@ export type {
   LambdaParam,
   BinOp,
   CmpOp,
+  AssignOp,
 }
 
 // ---------------------------------------------------------------------------
@@ -77,6 +78,7 @@ export type HIRExpr =
   // Assignment — only plain '=' (compound ops desugared)
   | { kind: 'assign'; target: string; value: HIRExpr; span?: Span }
   | { kind: 'member_assign'; obj: HIRExpr; field: string; value: HIRExpr; span?: Span }
+  | { kind: 'index_assign'; obj: HIRExpr; index: HIRExpr; op: AssignOp; value: HIRExpr; span?: Span }
   // Access
   | { kind: 'member'; obj: HIRExpr; field: string; span?: Span }
   | { kind: 'index'; obj: HIRExpr; index: HIRExpr; span?: Span }

package/src/lir/lower.ts

@@ -50,6 +50,10 @@ class LoweringContext {
   private currentMIRFn: MIRFunction | null = null
   /** Block map for quick lookup */
   private blockMap = new Map<BlockId, MIRBlock>()
+  /** Track generated dynamic array macro helper functions to avoid duplicates: key → fn name */
+  private dynIdxHelpers = new Map<string, string>()
+  /** Track generated dynamic array write helper functions: key → fn name */
+  private dynWrtHelpers = new Map<string, string>()
 
   constructor(namespace: string, objective: string) {
     this.namespace = namespace
@@ -77,6 +81,78 @@ class LoweringContext {
     this.functions.push(fn)
   }
 
+  /**
+   * Get or create a macro helper function for dynamic array index reads.
+   * The helper function is: $return run data get storage <ns> <pathPrefix>[$(arr_idx)] 1
+   * Returns the qualified MC function name (namespace:fnName).
+   */
+  getDynIdxHelper(ns: string, pathPrefix: string): string {
+    const key = `${ns}\0${pathPrefix}`
+    const existing = this.dynIdxHelpers.get(key)
+    if (existing) return existing
+
+    // Generate deterministic name from ns and pathPrefix
+    const sanitize = (s: string) => s.replace(/[^a-z0-9_]/gi, '_').toLowerCase()
+    // Extract just the storage name part from ns (e.g. "myns:arrays" → "myns_arrays")
+    const nsStr = sanitize(ns)
+    const prefixStr = sanitize(pathPrefix)
+    const helperName = `__dyn_idx_${nsStr}_${prefixStr}`
+
+    // The helper is placed in the current namespace
+    const qualifiedName = `${this.namespace}:${helperName}`
+
+    // Generate the macro function content:
+    // $return run data get storage <ns> <pathPrefix>[$(arr_idx)] 1
+    const macroLine: LIRInstr = {
+      kind: 'macro_line',
+      template: `return run data get storage ${ns} ${pathPrefix}[$(arr_idx)] 1`,
+    }
+
+    this.addFunction({
+      name: helperName,
+      instructions: [macroLine],
+      isMacro: true,
+      macroParams: ['arr_idx'],
+    })
+
+    this.dynIdxHelpers.set(key, qualifiedName)
+    return qualifiedName
+  }
+
+  /**
+   * Get or create a macro helper function for dynamic array index writes.
+   * The helper function: $data modify storage <ns> <pathPrefix>[$(arr_idx)] set value $(arr_val)
+   * Returns the qualified MC function name.
+   */
+  getDynWrtHelper(ns: string, pathPrefix: string): string {
+    const key = `${ns}\0${pathPrefix}`
+    const existing = this.dynWrtHelpers.get(key)
+    if (existing) return existing
+
+    const sanitize = (s: string) => s.replace(/[^a-z0-9_]/gi, '_').toLowerCase()
+    const nsStr = sanitize(ns)
+    const prefixStr = sanitize(pathPrefix)
+    const helperName = `__dyn_wrt_${nsStr}_${prefixStr}`
+
+    const qualifiedName = `${this.namespace}:${helperName}`
+
+    // Macro line: $data modify storage <ns> <pathPrefix>[$(arr_idx)] set value $(arr_val)
+    const macroLine: LIRInstr = {
+      kind: 'macro_line',
+      template: `data modify storage ${ns} ${pathPrefix}[$(arr_idx)] set value $(arr_val)`,
+    }
+
+    this.addFunction({
+      name: helperName,
+      instructions: [macroLine],
+      isMacro: true,
+      macroParams: ['arr_idx', 'arr_val'],
+    })
+
+    this.dynWrtHelpers.set(key, qualifiedName)
+    return qualifiedName
+  }
+
   /** Attach sourceLoc to newly added instructions (from the given start index onward) */
   tagSourceLoc(instrs: LIRInstr[], fromIndex: number, sourceLoc: SourceLoc | undefined): void {
     if (!sourceLoc) return
@@ -321,6 +397,46 @@ function lowerInstrInner(
       break
     }
 
+    case 'nbt_read_dynamic': {
+      // Strategy:
+      // 1. Store the index value into rs:macro_args __arr_idx (int)
+      // 2. Call the per-array macro helper function with 'with storage rs:macro_args'
+      // 3. Result comes back via $ret scoreboard slot (the macro uses $return)
+
+      const dst = ctx.slot(instr.dst)
+      const idxSlot = operandToSlot(instr.indexSrc, ctx, instrs)
+
+      // Step 1: store index score → rs:macro_args arr_idx (int, scale 1)
+      instrs.push({
+        kind: 'store_score_to_nbt',
+        ns: 'rs:macro_args',
+        path: 'arr_idx',
+        type: 'int',
+        scale: 1,
+        src: idxSlot,
+      })
+
+      // Step 2: get or create the macro helper function, then call it
+      const helperFn = ctx.getDynIdxHelper(instr.ns, instr.pathPrefix)
+      instrs.push({ kind: 'call_macro', fn: helperFn, storage: 'rs:macro_args' })
+
+      // Step 3: the macro uses $return which sets the MC return value.
+      // We need to capture that. In MC, $return run ... returns the result
+      // to the caller via the execute store mechanism.
+      // Use store_cmd_to_score to capture the return value of the macro call.
+      // Actually, the call_macro instruction above already ran the function.
+      // The $return run data get ... sets the scoreboard return value for the
+      // *calling* function context. We need to use execute store result score.
+      // Rewrite: use raw command instead:
+      instrs.pop() // remove the call_macro we just added
+      instrs.push({
+        kind: 'store_cmd_to_score',
+        dst,
+        cmd: { kind: 'call_macro', fn: helperFn, storage: 'rs:macro_args' },
+      })
+      break
+    }
+
     case 'nbt_write': {
       const srcSlot = operandToSlot(instr.src, ctx, instrs)
       instrs.push({
@@ -334,6 +450,41 @@ function lowerInstrInner(
       break
     }
 
+    case 'nbt_write_dynamic': {
+      // Strategy:
+      // 1. Store index score → rs:macro_args arr_idx (int)
+      // 2. Store value score → rs:macro_args arr_val (int)
+      // 3. Call macro helper: $data modify storage <ns> <pathPrefix>[$(arr_idx)] set value $(arr_val)
+
+      const idxSlot = operandToSlot(instr.indexSrc, ctx, instrs)
+      const valSlot = operandToSlot(instr.valueSrc, ctx, instrs)
+
+      // Store index
+      instrs.push({
+        kind: 'store_score_to_nbt',
+        ns: 'rs:macro_args',
+        path: 'arr_idx',
+        type: 'int',
+        scale: 1,
+        src: idxSlot,
+      })
+
+      // Store value
+      instrs.push({
+        kind: 'store_score_to_nbt',
+        ns: 'rs:macro_args',
+        path: 'arr_val',
+        type: 'int',
+        scale: 1,
+        src: valSlot,
+      })
+
+      // Call macro helper function
+      const helperFn = ctx.getDynWrtHelper(instr.ns, instr.pathPrefix)
+      instrs.push({ kind: 'call_macro', fn: helperFn, storage: 'rs:macro_args' })
+      break
+    }
+
     case 'score_read': {
       // execute store result score $dst __obj run scoreboard players get <player> <obj>
       const dst = ctx.slot(instr.dst)

package/src/mir/lower.ts

@@ -1075,12 +1075,19 @@ function lowerExpr(
     }
 
     case 'index': {
-      // Check if obj is a tracked array variable with a constant index
+      // Check if obj is a tracked array variable
       if (expr.obj.kind === 'ident') {
         const arrInfo = ctx.arrayVars.get(expr.obj.name)
-        if (arrInfo && expr.index.kind === 'int_lit') {
+        if (arrInfo) {
           const t = ctx.freshTemp()
-          ctx.emit({ kind: 'nbt_read', dst: t, ns: arrInfo.ns, path: `${arrInfo.pathPrefix}[${expr.index.value}]`, scale: 1 })
+          if (expr.index.kind === 'int_lit') {
+            // Constant index: direct NBT read
+            ctx.emit({ kind: 'nbt_read', dst: t, ns: arrInfo.ns, path: `${arrInfo.pathPrefix}[${expr.index.value}]`, scale: 1 })
+          } else {
+            // Dynamic index: emit nbt_read_dynamic
+            const idxOp = lowerExpr(expr.index, ctx, scope)
+            ctx.emit({ kind: 'nbt_read_dynamic', dst: t, ns: arrInfo.ns, pathPrefix: arrInfo.pathPrefix, indexSrc: idxOp })
+          }
           return { kind: 'temp', name: t }
         }
       }
@@ -1091,6 +1098,25 @@ function lowerExpr(
       return { kind: 'temp', name: t }
     }
 
+    case 'index_assign': {
+      const valOp = lowerExpr(expr.value, ctx, scope)
+      if (expr.obj.kind === 'ident') {
+        const arrInfo = ctx.arrayVars.get(expr.obj.name)
+        if (arrInfo) {
+          if (expr.index.kind === 'int_lit') {
+            // constant index → direct nbt_write
+            ctx.emit({ kind: 'nbt_write', ns: arrInfo.ns, path: `${arrInfo.pathPrefix}[${expr.index.value}]`, type: 'int', scale: 1, src: valOp })
+          } else {
+            // dynamic index → nbt_write_dynamic
+            const idxOp = lowerExpr(expr.index, ctx, scope)
+            ctx.emit({ kind: 'nbt_write_dynamic', ns: arrInfo.ns, pathPrefix: arrInfo.pathPrefix, indexSrc: idxOp, valueSrc: valOp })
+          }
+          return valOp
+        }
+      }
+      return valOp
+    }
+
     case 'call': {
       // Handle scoreboard_get / score — read from vanilla MC scoreboard
       if (expr.fn === 'scoreboard_get' || expr.fn === 'score') {
@@ -1112,6 +1138,52 @@ function lowerExpr(
         return { kind: 'temp', name: t }
       }
 
+      // Handle list_push(arr_name, val) — append an int to an NBT int array
+      // list_push("rs:lists", "mylist", val) or simpler: uses the array's storage path
+      if (expr.fn === 'list_push') {
+        // list_push(array_var, value)
+        // 1. Append a placeholder 0
+        // 2. Overwrite [-1] with the actual value
+        if (expr.args[0].kind === 'ident') {
+          const arrInfo = ctx.arrayVars.get((expr.args[0] as { kind: 'ident'; name: string }).name)
+          if (arrInfo) {
+            const valOp = lowerExpr(expr.args[1], ctx, scope)
+            // Step 1: append placeholder
+            ctx.emit({ kind: 'call', dst: null, fn: `__raw:data modify storage ${arrInfo.ns} ${arrInfo.pathPrefix} append value 0`, args: [] })
+            // Step 2: overwrite last element with actual value
+            ctx.emit({ kind: 'nbt_write', ns: arrInfo.ns, path: `${arrInfo.pathPrefix}[-1]`, type: 'int', scale: 1, src: valOp })
+            const t = ctx.freshTemp()
+            ctx.emit({ kind: 'const', dst: t, value: 0 })
+            return { kind: 'temp', name: t }
+          }
+        }
+      }
+
+      // Handle list_pop(arr_var) — remove last element from NBT int array
+      if (expr.fn === 'list_pop') {
+        if (expr.args[0].kind === 'ident') {
+          const arrInfo = ctx.arrayVars.get((expr.args[0] as { kind: 'ident'; name: string }).name)
+          if (arrInfo) {
+            ctx.emit({ kind: 'call', dst: null, fn: `__raw:data remove storage ${arrInfo.ns} ${arrInfo.pathPrefix}[-1]`, args: [] })
+            const t = ctx.freshTemp()
+            ctx.emit({ kind: 'const', dst: t, value: 0 })
+            return { kind: 'temp', name: t }
+          }
+        }
+      }
+
+      // Handle list_len(arr_var) — get length of NBT int array
+      if (expr.fn === 'list_len') {
+        if (expr.args[0].kind === 'ident') {
+          const arrInfo = ctx.arrayVars.get((expr.args[0] as { kind: 'ident'; name: string }).name)
+          if (arrInfo) {
+            const t = ctx.freshTemp()
+            ctx.emit({ kind: 'nbt_read', dst: t, ns: arrInfo.ns, path: `${arrInfo.pathPrefix}`, scale: 1 })
+            return { kind: 'temp', name: t }
+          }
+        }
+      }
+
       // Handle setTimeout/setInterval: lift lambda arg to a named helper function
       if ((expr.fn === 'setTimeout' || expr.fn === 'setInterval') && expr.args.length === 2) {
         const ticksArg = expr.args[0]

package/src/mir/macro.ts

@@ -140,6 +140,11 @@ function scanExpr(expr: HIRExpr, paramNames: Set<string>, macroParams: Set<strin
       scanExpr(expr.obj, paramNames, macroParams)
       scanExpr(expr.value, paramNames, macroParams)
       break
+    case 'index_assign':
+      scanExpr(expr.obj, paramNames, macroParams)
+      scanExpr(expr.index, paramNames, macroParams)
+      scanExpr(expr.value, paramNames, macroParams)
+      break
     case 'member':
       scanExpr(expr.obj, paramNames, macroParams)
       break

package/src/mir/types.ts

@@ -78,7 +78,9 @@ export type MIRInstr = MIRInstrBase & (
 
   // ── NBT storage ──────────────────────────────────────────────────────────
   | { kind: 'nbt_read'; dst: Temp; ns: string; path: string; scale: number }
+  | { kind: 'nbt_read_dynamic'; dst: Temp; ns: string; pathPrefix: string; indexSrc: Operand }
   | { kind: 'nbt_write'; ns: string; path: string; type: NBTType; scale: number; src: Operand }
+  | { kind: 'nbt_write_dynamic'; ns: string; pathPrefix: string; indexSrc: Operand; valueSrc: Operand }
 
   // ── Vanilla scoreboard interop ────────────────────────────────────────────
   | { kind: 'score_read'; dst: Temp; player: string; obj: string }

package/src/mir/verify.ts

@@ -164,6 +164,7 @@ function getDst(instr: MIRInstr): Temp | null {
     case 'cmp':
     case 'and': case 'or': case 'not':
     case 'nbt_read':
+    case 'nbt_read_dynamic':
       return instr.dst
     case 'call':
     case 'call_macro':
@@ -194,9 +195,15 @@ function getUsedTemps(instr: MIRInstr): Temp[] {
       break
     case 'nbt_read':
       break
+    case 'nbt_read_dynamic':
+      temps.push(...getOperandTemps(instr.indexSrc))
+      break
     case 'nbt_write':
       temps.push(...getOperandTemps(instr.src))
       break
+    case 'nbt_write_dynamic':
+      temps.push(...getOperandTemps(instr.indexSrc), ...getOperandTemps(instr.valueSrc))
+      break
     case 'call':
       for (const arg of instr.args) temps.push(...getOperandTemps(arg))
       break

package/src/optimizer/copy_prop.ts

@@ -77,6 +77,10 @@ function rewriteUses(instr: MIRInstr, copies: Map<Temp, Operand>): MIRInstr {
       return { ...instr, a: resolve(instr.a, copies), b: resolve(instr.b, copies) }
     case 'nbt_write':
       return { ...instr, src: resolve(instr.src, copies) }
+    case 'nbt_write_dynamic':
+      return { ...instr, indexSrc: resolve(instr.indexSrc, copies), valueSrc: resolve(instr.valueSrc, copies) }
+    case 'nbt_read_dynamic':
+      return { ...instr, indexSrc: resolve(instr.indexSrc, copies) }
     case 'call':
       return { ...instr, args: instr.args.map(a => resolve(a, copies)) }
     case 'call_macro':
@@ -99,6 +103,7 @@ function getDst(instr: MIRInstr): Temp | null {
     case 'neg': case 'cmp':
     case 'and': case 'or': case 'not':
     case 'nbt_read':
+    case 'nbt_read_dynamic':
       return instr.dst
     case 'call': case 'call_macro':
       return instr.dst

package/src/optimizer/coroutine.ts

@@ -946,8 +946,12 @@ function rewriteInstr(instr: MIRInstr, promoted: Map<Temp, Temp>): MIRInstr {
       return { ...instr, dst: rTemp(instr.dst), src: rOp(instr.src) }
     case 'nbt_read':
       return { ...instr, dst: rTemp(instr.dst) }
+    case 'nbt_read_dynamic':
+      return { ...instr, dst: rTemp(instr.dst), indexSrc: rOp(instr.indexSrc) }
     case 'nbt_write':
       return { ...instr, src: rOp(instr.src) }
+    case 'nbt_write_dynamic':
+      return { ...instr, indexSrc: rOp(instr.indexSrc), valueSrc: rOp(instr.valueSrc) }
     case 'call':
       return { ...instr, dst: instr.dst ? rTemp(instr.dst) : null, args: instr.args.map(rOp) }
     case 'call_macro':
@@ -999,6 +1003,7 @@ function getDst(instr: MIRInstr): Temp | null {
     case 'neg': case 'cmp':
     case 'and': case 'or': case 'not':
     case 'nbt_read':
+    case 'nbt_read_dynamic':
       return instr.dst
     case 'call': case 'call_macro':
       return instr.dst
@@ -1019,6 +1024,10 @@ function getUsedTemps(instr: MIRInstr): Temp[] {
       addOp(instr.a); addOp(instr.b); break
     case 'nbt_write':
       addOp(instr.src); break
+    case 'nbt_write_dynamic':
+      addOp(instr.indexSrc); addOp(instr.valueSrc); break
+    case 'nbt_read_dynamic':
+      addOp(instr.indexSrc); break
     case 'call':
       instr.args.forEach(addOp); break
     case 'call_macro':

package/src/optimizer/dce.ts

@@ -79,6 +79,7 @@ function recomputePreds(blocks: MIRBlock[]): MIRBlock[] {
 function hasSideEffects(instr: MIRInstr): boolean {
   if (instr.kind === 'call' || instr.kind === 'call_macro' ||
     instr.kind === 'call_context' || instr.kind === 'nbt_write' ||
+    instr.kind === 'nbt_write_dynamic' ||
     instr.kind === 'score_write') return true
   // Return field temps (__rf_) write to global return slots — not dead even if unused locally
   // Option slot temps (__opt_) write observable scoreboard state — preserve even if var unused
@@ -102,6 +103,7 @@ function getDst(instr: MIRInstr): Temp | null {
     case 'neg': case 'cmp':
     case 'and': case 'or': case 'not':
     case 'nbt_read':
+    case 'nbt_read_dynamic':
       return instr.dst
     case 'call': case 'call_macro':
       return instr.dst
@@ -124,6 +126,10 @@ function getUsedTemps(instr: MIRInstr): Temp[] {
       addOp(instr.a); addOp(instr.b); break
     case 'nbt_write':
       addOp(instr.src); break
+    case 'nbt_write_dynamic':
+      addOp(instr.indexSrc); addOp(instr.valueSrc); break
+    case 'nbt_read_dynamic':
+      addOp(instr.indexSrc); break
     case 'call':
       instr.args.forEach(addOp); break
     case 'call_macro':

package/src/optimizer/unroll.ts

@@ -334,6 +334,8 @@ function substituteInstr(instr: MIRInstr, sub: Map<Temp, Operand>): MIRInstr {
       return { ...instr, a: substituteOp(instr.a, sub), b: substituteOp(instr.b, sub) }
     case 'nbt_write':
       return { ...instr, src: substituteOp(instr.src, sub) }
+    case 'nbt_write_dynamic':
+      return { ...instr, indexSrc: substituteOp(instr.indexSrc, sub), valueSrc: substituteOp(instr.valueSrc, sub) }
     case 'call':
       return { ...instr, args: instr.args.map(a => substituteOp(a, sub)) }
     case 'call_macro':
@@ -357,6 +359,7 @@ function getInstrDst(instr: MIRInstr): Temp | null {
     case 'add': case 'sub': case 'mul': case 'div': case 'mod':
     case 'neg': case 'cmp': case 'and': case 'or': case 'not':
     case 'nbt_read':
+    case 'nbt_read_dynamic':
       return instr.dst
     case 'call': case 'call_macro':
       return instr.dst

package/src/parser/index.ts

@@ -1162,6 +1162,15 @@ export class Parser {
           this.getLocToken(left) ?? token
         )
       }
+
+      // Index assignment: arr[0] = val, arr[i] = val
+      if (left.kind === 'index') {
+        const value = this.parseAssignment()
+        return this.withLoc(
+          { kind: 'index_assign', obj: left.obj, index: left.index, op, value },
+          this.getLocToken(left) ?? token
+        )
+      }
     }
 
     return left

package/src/stdlib/list.mcrs

@@ -1,45 +1,29 @@
-// list.mcrs — Dynamic NBT-backed integer list operations.
+// list.mcrs — List and array utilities for RedScript datapacks.
 //
-// Lists are stored in NBT storage as int arrays.
-// The storage namespace is "rs:lists" and path is the variable name.
+// NOTE: Array parameters cannot be passed to functions by reference in
+// the current RedScript implementation. Functions that operate on arrays
+// must be inlined by the user, OR use fixed-size static helpers below.
 //
-// IMPORTANT: These functions use raw() to emit NBT commands.
-// They operate on a NAMED list stored at a specific NBT path.
-// The caller must pass the list path as a namespace:path string.
+// For dynamic array operations (sort, search, sum over variable-length arrays),
+// write the loop directly in your code:
 //
-// Example usage:
-//   // Create a list (declare as int[])
-//   let mylist: int[] = [1, 2, 3];
+//   let nums: int[] = [30, 10, 20];
+//   // Manual bubble sort (2 elements):
+//   if (nums[0] > nums[1]) {
+//       let tmp: int = nums[0];
+//       nums[0] = nums[1];
+//       nums[1] = tmp;
+//   }
 //
-//   // Use list_* functions with raw() for dynamic operations.
-//   // Note: push/pop/len use raw() NBT commands directly.
-//
-// For fixed-size arrays, use int[] literals directly.
-// For dynamic lists, use the functions below.
-//
-// Storage convention: lists live at storage rs:lists <varname>
+// The static helpers below work on up to 5 discrete values passed as arguments.
 
 module library;
 
-// list_len_of(ns, path): count elements in an NBT int list.
-// Returns the count stored in a scoreboard temp.
-// Use: raw("execute store result score $len __ns run data get storage ns:name path")
-// This is a convenience wrapper — in practice use raw() directly.
-
-// list_sum(a, b, c, d, e): sum of up to 5 int values (utility)
-fn list_sum5(a: int, b: int, c: int, d: int, e: int): int {
-    return a + b + c + d + e;
-}
+// ─── Static min/max/avg ──────────────────────────────────────────────────────
 
-fn list_sum4(a: int, b: int, c: int, d: int): int {
-    return a + b + c + d;
-}
-
-fn list_sum3(a: int, b: int, c: int): int {
-    return a + b + c;
-}
+fn sort2_min(a: int, b: int): int { if (a <= b) { return a; } return b; }
+fn sort2_max(a: int, b: int): int { if (a >= b) { return a; } return b; }
 
-// list_min3 / list_max3: min/max over 3 values (useful for array-derived work)
 fn list_min3(a: int, b: int, c: int): int {
     let m: int = a;
     if (b < m) { m = b; }
@@ -72,54 +56,41 @@ fn list_max5(a: int, b: int, c: int, d: int, e: int): int {
     return m;
 }
 
-// ─── Sorting (in-register, fixed size) ───────────────────────────────────────
+fn list_sum5(a: int, b: int, c: int, d: int, e: int): int { return a + b + c + d + e; }
+fn list_sum4(a: int, b: int, c: int, d: int): int { return a + b + c + d; }
+fn list_sum3(a: int, b: int, c: int): int { return a + b + c; }
+fn avg3(a: int, b: int, c: int): int { return (a + b + c) / 3; }
+fn avg5(a: int, b: int, c: int, d: int, e: int): int { return (a + b + c + d + e) / 5; }
 
-// sort3_asc: sort 3 values ascending, returns packed as 3 separate ints via
-// side-effect scoreboard. Caller reads $sort3_a, $sort3_b, $sort3_c.
-// (This is a placeholder — proper NBT list sort requires runtime support.)
+// ─── Static sort (sorting network) ───────────────────────────────────────────
 
-// swap helper: sort2 returns the smaller value
-fn sort2_min(a: int, b: int): int {
-    if (a <= b) { return a; }
-    return b;
-}
-
-fn sort2_max(a: int, b: int): int {
-    if (a >= b) { return a; }
-    return b;
-}
-
-// bubble_sort3: returns sorted value at position pos (0=min, 1=mid, 2=max)
+// sort3(a, b, c, pos): return sorted value at position pos (0=min, 1=mid, 2=max)
 fn sort3(a: int, b: int, c: int, pos: int): int {
-    // Sorting network for 3 elements
-    let x: int = a;
-    let y: int = b;
-    let z: int = c;
-    // Step 1: compare-swap (x, y)
-    if (x > y) { let tmp: int = x; x = y; y = tmp; }
-    // Step 2: compare-swap (y, z)
-    if (y > z) { let tmp: int = y; y = z; z = tmp; }
-    // Step 3: compare-swap (x, y)
-    if (x > y) { let tmp: int = x; x = y; y = tmp; }
+    let x: int = a; let y: int = b; let z: int = c;
+    if (x > y) { let t: int = x; x = y; y = t; }
+    if (y > z) { let t: int = y; y = z; z = t; }
+    if (x > y) { let t: int = x; x = y; y = t; }
     if (pos == 0) { return x; }
     if (pos == 1) { return y; }
     return z;
 }
 
-// ─── Statistics ──────────────────────────────────────────────────────────────
-
-// avg3(a, b, c): integer average (truncated)
-fn avg3(a: int, b: int, c: int): int {
-    return (a + b + c) / 3;
-}
+// ─── Weighted random choice ───────────────────────────────────────────────────
 
-fn avg5(a: int, b: int, c: int, d: int, e: int): int {
-    return (a + b + c + d + e) / 5;
+fn weighted2(seed: int, w0: int, w1: int): int {
+    let total: int = w0 + w1;
+    let r: int = seed * 1664525 + 1013904223;
+    if (r < 0) { r = 0 - r; }
+    if (r % total < w0) { return 0; }
+    return 1;
 }
 
-// clamp_list3(a, b, c, lo, hi): clamp all 3 values
-fn clamp3(a: int, lo: int, hi: int): int {
-    if (a < lo) { return lo; }
-    if (a > hi) { return hi; }
-    return a;
+fn weighted3(seed: int, w0: int, w1: int, w2: int): int {
+    let total: int = w0 + w1 + w2;
+    let r: int = seed * 1664525 + 1013904223;
+    if (r < 0) { r = 0 - r; }
+    let v: int = r % total;
+    if (v < w0) { return 0; }
+    if (v < w0 + w1) { return 1; }
+    return 2;
 }