Optimize Luau

Route all output there: --stats-file=$LUAU_TMP\stats.json, write benchmark files to $LUAU_TMP\bench.luau, run profiling/coverage tools with $LUAU_TMP as working directory. The OS handles cleanup -- no manual deletion needed.

CLI setup: After creating the temp directory, check if luau-compile is on PATH. If missing, download the latest release from https://github.com/luau-lang/luau and extract to $LUAU_TMP, then prepend to PATH for the session:

# Windows (PowerShell)
if (-not (Get-Command luau-compile -ErrorAction SilentlyContinue)) {
    $tag = (Invoke-RestMethod "https://api.github.com/repos/luau-lang/luau/releases/latest").tag_name
    Invoke-WebRequest -Uri "https://github.com/luau-lang/luau/releases/download/$tag/luau-windows.zip" -OutFile "$LUAU_TMP\luau.zip"
    Expand-Archive -Path "$LUAU_TMP\luau.zip" -DestinationPath $LUAU_TMP
    $env:PATH = "$LUAU_TMP;$env:PATH"
}

# macOS (bash/zsh)
if ! command -v luau-compile &> /dev/null; then
    tag=$(curl -s "https://api.github.com/repos/luau-lang/luau/releases/latest" | grep -o '"tag_name": "[^"]*"' | cut -d'"' -f4)
    curl -L "https://github.com/luau-lang/luau/releases/download/$tag/luau-macos.zip" -o "$LUAU_TMP/luau.zip"
    unzip "$LUAU_TMP/luau.zip" -d "$LUAU_TMP" && chmod +x "$LUAU_TMP"/luau*
    export PATH="$LUAU_TMP:$PATH"
fi

# Linux (bash)
if ! command -v luau-compile &> /dev/null; then
    tag=$(curl -s "https://api.github.com/repos/luau-lang/luau/releases/latest" | grep -o '"tag_name": "[^"]*"' | cut -d'"' -f4)
    curl -L "https://github.com/luau-lang/luau/releases/download/$tag/luau-ubuntu.zip" -o "$LUAU_TMP/luau.zip"
    unzip "$LUAU_TMP/luau.zip" -d "$LUAU_TMP" && chmod +x "$LUAU_TMP"/luau*
    export PATH="$LUAU_TMP:$PATH"
fi

Phase 0 -- Scope Resolution and Configuration

Resolve target

• If user specifies a file: optimize that file.
• If user specifies a directory: discover all .luau/.lua files, enter Phase 6 (multi-file mode).
• If no argument: optimize the currently open file.

Infer script context

Check in this order:

1. Filename suffix (highest priority):
   • *.server.luau / *.server.lua -> server (native codegen budget is server-side; benefit depends on code content)
   • *.client.luau / *.client.lua -> client (native codegen less effective due to device architecture diversity)
   • *.legacy.luau / *.legacy.lua -> ambiguous (could be cloned/moved at runtime). Ask the user.
   • *.luau / *.lua (no suffix) -> ModuleScript, fall through to path check.
2. Path-based inference (for ModuleScripts and ambiguous cases):
   • ServerScriptService/ServerStorage in path -> server-side module
   • StarterPlayer/StarterGui/StarterCharacterScripts/ReplicatedFirst in path -> client-side module
   • ReplicatedStorage/shared in path -> shared module
   • Ambiguous or outside Roblox project -> ask the user

Quiz the user

Use the AskQuestion tool with these three questions:

Question 1: "Compilation optimization intensity"

• minimal -- Headers (--!strict/--!optimize 2), type annotations on all function signatures, deprecated pattern replacements, native codegen analysis
• moderate -- + function restructuring for inlining, import hoisting, compound operators, fastcall enablement, allocation reduction
• insane -- + every micro-optimization from the pattern catalog, full bytecode analysis, register pressure optimization, closure caching analysis

Question 2: "Algorithm optimization"

• none -- Don't touch logic or data flow
• low hanging fruit -- Obvious O(n^2)->dict, redundant iterations, missing caches
• moderate -- + data structure changes, caching strategies, event-driven refactors, loop fusion
• insane -- + full algorithmic redesign where beneficial, dynamic programming, architectural restructuring

Question 3: "Benchmarking"

• yes -- Benchmark all non-trivial changes with luau CLI (when function is standalone)
• no -- Trust bytecode/codegen metrics only
• +EV only -- Benchmark only when algorithmic changes or ambiguous bytecode results warrant it

Derived behavior

Restructuring scope scales with compilation intensity:

• minimal: No restructuring. Only additive changes (headers, annotations, pattern swaps).
• moderate: Break up monoliths, reorder locals for inlining, hoist imports. Preserve exports/API.
• insane: Aggressive restructuring permitted. May change internal function boundaries, rewrite data flow.

Phase 1 -- Deep Code Read and Algorithmic Analysis

This phase comes FIRST. Algorithmic improvements produce order-of-magnitude speedups that dwarf any bytecode optimization. This is also the largest code change, so it must happen before any bytecode-level work.

Read the entire source file thoroughly before touching any CLI tools.

Step 1 -- Structural decomposition

Monolithic functions hide their algorithmic structure behind interleaved concerns. Before analyzing complexity, understand what the code is actually doing:

• Identify responsibilities: A 200-line function usually contains 3-5 logical steps that should be separate functions.
• Trace data flow: What goes in, what comes out, what is mutated along the way.
• Separate concerns: Validation, transformation, I/O, state management, error handling are often tangled. Separating them reveals the core algorithm.
• Name the steps: If you can't name what a code block does in 3-5 words, it's doing too much.
• Look for hidden abstractions: Repeated "iterate, filter, transform, collect" patterns that could be a single helper.

When the quiz allows restructuring (moderate/insane):

• Physically decompose monoliths into focused local functions. Each does one thing.
• This decomposition often reveals optimization opportunities invisible in the monolith: step 2 recomputes what step 1 already knew, or an inner loop could be a lookup table built in the outer loop.
• Smaller functions are easier for the compiler to inline at -O2 -- clearer code AND better bytecode.
• Preserve the original function as a thin orchestrator calling the decomposed pieces.

Even at "minimal" intensity, still perform this mental decomposition to inform the analysis below.

Step 2 -- Algorithmic analysis

With the structure understood (or cleaned up), analyze:

Complexity analysis -- Identify time complexity of every significant function:

• O(n^2) or worse: nested loops, repeated linear searches, quadratic string building
• O(n) where O(1) is possible: linear search replaceable with dictionary/set lookup
• Repeated work: same computation done multiple times, cacheable/memoizable
• Unnecessary copies: cloning data that could be referenced or mutated in place
• Hidden quadratics: O(n) function that calls another O(n) function inside a loop

Data structure fitness -- Is the right data structure being used?

• Array for membership testing -> set (dictionary with true values)
• Linear scan for lookup by key -> dictionary
• Repeated sort of mostly-sorted data -> maintain sorted order on insert
• Flat list with frequent removal from middle -> swap-and-pop
• Large string built incrementally -> table.concat pattern or buffer
• Multiple parallel arrays -> single array of structs (table of tables)
• Unbounded growth without cleanup -> size limits, LRU eviction, periodic pruning

Caching and memoization:

• Pure functions called repeatedly with same args -> memoize
• Expensive property reads in loops -> cache in local before loop
• Computed values unchanged within a scope -> hoist out
• Derived state recomputed from scratch on every access -> maintain incrementally

Redundant work elimination:

• Multiple passes over same data -> fuse into one
• Recomputing derived state -> maintain incrementally
• Sort/filter that could be done once and reused
• Deep clone where shallow clone or reference suffices
• Intermediate result immediately discarded after extracting one field

Architectural patterns:

• Per-frame polling where event-driven would work (RunService events are expensive)
• Synchronous work that could be chunked across frames with task.wait()
• Undisconnected event connections (memory leak + wasted computation)
• Rebuilding entire state on small change -> incremental update
• God-object owning too much state -> split responsibilities

Hot path identification:

• Event handlers on RunService (PreAnimation, PreRender, PreSimulation, PostSimulation, Heartbeat)
• Functions called inside loops
• Recursive functions
• Functions called from other hot functions

Step 3 -- Present findings and quiz the user

Before applying any changes, present a summary of all findings organized by impact. For each finding:

• What: One-line description of the issue
• Where: Function name / line range
• Why: What makes it slow (e.g., "O(n^2) nested scan on every frame")
• Fix: Proposed change in plain language
• Impact: Estimated improvement (order-of-magnitude, constant-factor, or clarity-only)

Then quiz the user using the AskQuestion tool:

• For fewer than 5 findings: one question per finding with options apply / skip / modify
• For 5+ findings: group by category with options apply all / cherry-pick / skip all:
  • Structural decomposition
  • Data structure changes
  • Algorithm changes
  • Architectural changes

If the algorithm quiz from Phase 0 was "none", present findings as informational only (no apply options). The user still sees what was found.

If the user selects "modify", wait for their input before proceeding with that specific change.

Step 4 -- Apply approved changes

Apply only user-approved changes, in this order (dependencies flow downward):

1. Structural decomposition -- break monoliths into focused functions (foundation for everything else)
2. Data structure changes -- swap arrays for dicts, add indexes, etc.
3. Algorithm changes -- replace O(n^2) with O(n), add caching/memoization
4. Architectural changes -- event-driven refactors, incremental updates

Benchmark algorithmic changes if the benchmarking quiz warrants it (see Phase 4.5).

Phase 2 -- Baseline Capture

Run all diagnostic tools on the code (post-algorithmic changes if any were applied in Phase 1). These metrics are the baseline for bytecode optimization phases.

Tools to run

Detect OS: use --target=x64_ms on Windows, --target=x64 on Linux/Mac. Route stats output to temp directory.

luau-analyze --mode=strict <file>
luau-analyze --annotate <file>
luau-compile --remarks -O2 --vector-lib=Vector3 --vector-ctor=new --vector-type=Vector3 <file>
luau-compile --text -O2 --vector-lib=Vector3 --vector-ctor=new --vector-type=Vector3 <file>
luau-compile --codegen --target=x64_ms --record-stats=function --stats-file=$LUAU_TMP\stats.json -O2 --vector-lib=Vector3 --vector-ctor=new --vector-type=Vector3 <file>

Metrics to capture

• Total bytecode instruction count (from --text)
• Allocation count: NEWTABLE, NEWCLOSURE occurrences (from --remarks)
• Inlining success/failure count (from --remarks: "inlining succeeded"/"inlining failed")
• Type coverage: count of any types in --annotate output
• Register spills and skipped functions (from --record-stats JSON lowerStats)
• Lint warning count (from --mode=strict)

Phase 3 -- Compilation-Level Code Analysis

Using both the source (already read in Phase 1) and tool output from Phase 2, identify bytecode-level optimization opportunities:

• Missing types: any inferences hurting native codegen (especially Vector3, CFrame, buffer params). JIT uses annotations directly -- no runtime type analysis. Unannotated params assumed to be tables.
• Import patterns: math.max resolved at load time via GETIMPORT. Broken by getfenv/setfenv/loadstring (marks env "impure").
• Allocation in loops: NEWTABLE, NEWCLOSURE in hot loops. High allocation rate = more GC assist work.
• Closure caching: Repeated function expressions cached when: no upvalues, or all upvalues immutable and module-scope. Mutable captures prevent caching.
• Upvalue mutability: ~90% immutable in typical code. Immutable = no allocation, no closing, faster access. Mutable = extra object.
• Method call patterns: obj:Method() uses fast method call instruction. Avoid obj.Method(obj). __index should point at a table directly (not function or deep chain).
• Inline caching: Best when field name known at compile time, no metatables, uniform shapes.
• pcall in hot paths: Prevents native codegen optimization.
• String concatenation: .. in loops -> table.concat or string interpolation.
• Deoptimizing APIs: getfenv/setfenv (even read-only!), loadstring disable ALL import optimization and fastcalls.
• Builtin global writes: math = ... disables fastcall. Lint BuiltinGlobalWrite catches this.
• Metamethod cost: __eq always called on ==/~= even for rawequal values.
• GC pressure: Incremental GC with "GC assists" -- allocating code pays proportional GC work.

Phase 4 -- Compilation Optimization

Apply changes in priority order. Re-run luau-compile --remarks -O2 --vector-lib=Vector3 --vector-ctor=new --vector-type=Vector3 <file> after structural changes to verify the compiler benefits.

Priority 1 -- Headers, type safety, and native codegen (always apply)

Add headers:

• --!strict / --!optimize 2. (--!optimize 2 is default in live but not Studio testing.)
• Do NOT blindly add --!native. Native codegen is analyzed separately (see "Native codegen strategy" below).

Remove deoptimizers:

• Replace getfenv/setfenv -- disables builtins, imports, and optimizations globally.
• Replace table.getn -> #t, table.foreach/table.foreachi -> for..in.

Type accuracy -- the first big battle:

Getting the file to pass --!strict cleanly is the single most impactful compilation change. Every any type is a function the native codegen cannot specialize. But the goal is accurate types, not silencing errors with casts:

• Run luau-analyze --annotate and identify every any inference. These are the targets.
• Add real type annotations to function signatures first (parameters and return types). This has the highest leverage -- it propagates type info to every caller and every local inside the function.
• Then annotate locals in hot paths where inference still falls to any.
• Annotate Vector3, CFrame, buffer params explicitly -- native codegen generates specialized vector code. Unannotated params are assumed to be generic tables with extra type checks.
• Do NOT paper over type errors with :: any casts. A cast to any is worse than no annotation -- it actively tells the compiler to give up. If a type error is hard to fix, use the narrowest cast possible (:: SpecificType), or restructure the code so the type flows naturally.
• Narrow any in dictionaries. {[string]: any} is common but hurts codegen. Ask: what values actually go in there? If it's a known set of types, use a union: {[string]: string | number | boolean}. If the dictionary has known keys, use a typed table: {name: string, score: number}. Only fall back to any when the value type is genuinely unbounded (e.g., serialized data from an external source).
• Use type refinements (type(), typeof(), :IsA(), assert()) to provide type info from runtime checks instead of casts.
• For OOP patterns: use typeof(setmetatable(...)) with explicit self: ClassName on methods (old typechecker compatible).
• For generic code: use proper generics (<T>) instead of any. If the function truly accepts anything, use unknown and narrow explicitly.
• Track type coverage: count any in --annotate output. The goal is zero (or as close as practical).

Native codegen strategy -- --!native vs @native vs neither:

Native codegen has two limits: a 1M instruction cap per module and a per-experience memory ceiling shared across all native scripts. Applying --!native indiscriminately wastes both budgets on functions that don't benefit, crowding out functions that would.

1. Classify every function in the file by its dominant work:

   • Native-worthy: Tight computational loops, math-heavy logic (Vector3/CFrame arithmetic, buffer ops, bit32 ops, numerical algorithms, physics calculations). These get genuine speedups from JIT compilation.
   • Not native-worthy: Roblox API calls (Instance:Clone(), :FindFirstChild(), :GetChildren(), event connections), table construction without computation (allocation-bound), heavy Luau library calls (string.format, pattern matching -- C implementations native codegen can't speed up), one-shot initialization, coroutine/task scheduling. The dominant cost is the API/library call or GC, not Luau instruction dispatch.

2. Decision matrix:

   • All/most functions are native-worthy (math utility modules, physics solvers, buffer serializers): Use --!native on the whole file.
   • Some functions are native-worthy (mixed scripts with hot computational loops alongside API-heavy code): Use @native on individual functions that benefit. This is the common case for real game scripts.
   • No functions are native-worthy (typical game scripts: event handlers, UI logic, Roblox API orchestration): Skip native codegen entirely. Don't waste the budget.

3. @native placement rules:

   • Place @native directly above the function declaration.
   • Inner/nested functions do NOT inherit @native -- annotate them individually if needed.
   • Top-level module code runs once at require() time; @native has no meaningful benefit there.
   • Prioritize functions identified as hot paths in Phase 1 (RunService handlers, loop bodies, recursive functions) -- but only if their work is computational, not API-bound.

4. Budget awareness: Check native codegen stats from --record-stats. If the module's native instruction count is high, be more selective with @native to leave budget for other scripts in the experience.

Priority 2 -- Low-hanging structural wins

• Hoist library functions: local floor = math.floor enables GETIMPORT fastcall. Fastcall builtins: assert, type, typeof, rawget/rawset/rawequal, getmetatable/setmetatable, tonumber/tostring, most math.* (not noise, random/randomseed), bit32.*, some string.*/table.*. Partial specializations: assert (unused return + truthy), bit32.extract (constant field/width), select(n, ...) O(1).
• Replace pairs(t)/ipairs(t) -> for k, v in t do. Generalized iteration skips the pairs() call. for i=1,#t is slightly slower.
• math.floor(a / b) -> a // b (dedicated VM opcode, //= compound form).
• Use compound assignment (+=, -=, *=, //=, ..=) -- LHS evaluated once.
• String concat in loops -> table.concat or backtick interpolation (lowers to optimized string.format).
• table.create(n) for known-size arrays. Sequential fill: local t = table.create(N); for i=1,N do t[i] = ... end.
• table.insert(t, v) for unknown-size append -- #t is O(1) cached, worst case O(log N).
• a + (b - a) * t -> math.lerp(a, b, t) (exact at endpoints, monotonic).
• Manual byte swap -> bit32.byteswap(n) (CPU bswap).
• Manual log2 -> bit32.countlz(n) (CPU instruction, ~8x faster).
• Manual linear search -> table.find(t, v).
• Manual pairs clone -> table.clone(t).
• Manual string.byte/string.char -> string.pack/string.unpack.
• rawlen(t) when metamethods not needed.
• Explicit .//..//@ prefixes in require().

Priority 3 -- Function structure for inlining

• Break monoliths into small local functions (compiler inlines at -O2).
• Inlining requirements: local, non-mutated, non-recursive, not OOP (: syntax), not metamethod. Disabled by getfenv/setfenv.
• Inlining + constant folding cascade: local function double(x) return x*2 end; local y = double(5) folds to y = 10.
• Create local function wrappers for frequently-called imported module methods.
• Move pcall out of hot loops.
• Use obj:Method() not obj.Method(obj) -- fast method call instruction.
• __index should point at a table directly for inline caching.
• Reduce mutable upvalue captures in loop closures. Immutable upvalues = no allocation, no closing.
• Set all table fields at once (compiler infers hash capacity from subsequent assignments).
• Loop unrolling: constant bounds only, simple body.
• Native codegen size limits: 64K instructions/block, 32K blocks/function, 1M instructions/module. Split if exceeded.

Priority 4 -- Micro-optimizations (hot paths only)

• Table shape consistency (same fields, same order) -- inline caching predicts hash slots.
• buffer for binary data (fixed-size, offset-based, efficient native lowering).
• buffer.readu32 + bit32 over buffer.readbits when schema known.
• Strength reduction: * 2^n -> bit32.lshift, / 2^n -> bit32.rshift.
• Minimize tostring/tonumber in tight loops.
• table.freeze for readonly config (avoids proxy __index overhead).
• Keep __eq cheap -- fires on every ==/~= and table.find.
• math.isfinite/math.isnan/math.isinf over x ~= x.
• Annotate Vector3 params for native specialization.
• if expr then A else B over cond and A or B (one branch, falsy-safe).

Phase 4.5 -- Benchmark with luau CLI

When a non-trivial optimization is applied to an isolated, pure-logic function (no Roblox API dependencies), write a small benchmark harness:

local function original(...)
    -- paste original implementation
end

local function optimized(...)
    -- paste optimized implementation
end

local ITERATIONS = 1_000_000
local clock = os.clock

for _ = 1, 1000 do original(...) end
for _ = 1, 1000 do optimized(...) end

local t0 = clock()
for _ = 1, ITERATIONS do original(...) end
local t1 = clock()
for _ = 1, ITERATIONS do optimized(...) end
local t2 = clock()

print(`Original:  {t1 - t0:.4f}s`)
print(`Optimized: {t2 - t1:.4f}s`)
print(`Speedup:   {(t1 - t0) / (t2 - t1):.2f}x`)

Run with both paths:

luau -O2 bench.luau
luau -O2 --codegen bench.luau

When to benchmark: Self-contained function, algorithmic/data structure change, ambiguous bytecode diff, tiebreak between approaches.

When NOT to benchmark: Roblox API dependencies (use Studio Script Profiler instead), purely additive changes, cold code.

Write the benchmark file to $LUAU_TMP\bench.luau, not the project directory. Run luau from $LUAU_TMP as working directory so profile.out and other residuals land there too.

Phase 5 -- Verification

Re-run all Phase 2 tools and present a before/after comparison:

• Bytecode instruction count delta
• Allocation count delta
• Inlining success rate delta
• Type coverage improvement (fewer any types)
• Register spill delta
• Lint warning delta
• Benchmark results (if Phase 4.5 was used)

If any metric regressed, investigate and explain why (or revert).

Phase 6 -- Multi-file Mode

When optimizing a directory:

1. Run Phase 1 (code read) on all files to identify algorithmic improvement potential.
2. Run Phase 2 (baseline) on all files to identify bytecode optimization potential.
3. Prioritize by: worst algorithmic complexity, most lint warnings, most any types, most allocations, most failed inlines.
4. Process files one at a time through Phases 1-5.
5. Present aggregate metrics at the end.

Key Principles

These principles govern every optimization decision:

• Same implementation, better performance -- behavioral equivalence is non-negotiable. Never change what the code does, only how fast it does it.
• Algorithms first, bytecode second -- an O(n) algorithm with unoptimized bytecode beats an O(n^2) algorithm with perfect bytecode every time.
• Low-hanging fruit first -- headers and types before restructuring, restructuring before micro-optimizations.
• Compiler feedback loop -- verify each structural change with luau-compile --remarks. If the compiler didn't benefit, the change wasn't worth it.
• Small functions over monoliths -- easier for the compiler to inline, easier for humans to maintain, easier to reason about algorithmically.
• Local functions for inlining -- even at the cost of duplicating imported behavior in high-traffic code.
• Quantify everything -- before/after metrics for every optimization pass. No "I think this is faster" -- prove it.
• Type annotations drive native codegen quality -- every any type is a missed specialization opportunity. The JIT uses annotations directly with no runtime analysis.
• Native codegen is a budget, not a checkbox -- --!native on every file wastes the per-experience native code memory limit on functions that don't benefit. Apply @native selectively to computational hot functions; reserve --!native for genuinely math-heavy modules.
• Event-driven over polling -- avoid per-frame calculations when events suffice.

Reference Material

Consult reference.md during execution for detailed lookup tables covering:

• Type System (Old Typechecker Only) -- available vs new-typechecker-only features
• Type Refinement Patterns
• Deprecated Patterns
• Lint Rules
• Bytecode Pattern Catalog
• Allocation Reduction
• Inlining Rules
• Native Codegen (detailed --!native vs @native breakdown)
• CLI Tools (luau-compile, luau-analyze, luau, luau-ast)
• VM Architecture
• Documentation paths to consult