@eryx/luau/vm Module

Luau bytecode compiler, loader, and disassembler.

Wraps the native Luau VM to compile source code to bytecode, load source or pre-compiled bytecode as callable functions, and produce human-readable bytecode disassembly listings.

local vm = require("@eryx/luau/vm")

-- Compile once, run many times
local bytecode = vm.compile(source, { optimizationLevel = 2 })
local fn = vm.load(bytecode, "=cached")
fn()

-- Inspect compiled code
print(vm.disassemble(source, { showLocals = true }))

Summary

Functions

vm.compile(source: string, options: CompileOptions?) → string
vm.load(sourceOrBytecode: string, chunkname: string?, options: LoadOptions?) → ((...any) → ...any)
vm.disassemble(source: string, options: DisassembleOptions?) → string

API Reference

Functions

vm.compile

Compiles Luau source code to bytecode.

The returned bytecode blob can be passed to load or cached for later use. If the source has syntax errors the bytecode will contain an encoded error that load will surface.

local bytecode = vm.compile(source, { optimizationLevel = 2 })
local fn = vm.load(bytecode, "=cached")
fn()
vm.compile(source: string, options: CompileOptions?) → string

Parameters

source: string

The Luau source code to compile.

options: CompileOptions?

Compiler options (optimization, debug, coverage levels).

Returns

string

The compiled bytecode blob.

vm.load

Loads Luau source code or pre-compiled bytecode as a callable function.

Accepts either a source string (which will be compiled automatically) or a bytecode blob previously returned by compile. This is the equivalent of loadstring in standard Lua.

The optional options table may be passed as the second argument (omitting chunkname) or as the third argument after chunkname.

local fn = vm.load("return 1 + 2", "=example")
print(fn()) -- 3
vm.load(sourceOrBytecode: string, chunkname: string?, options: LoadOptions?) → ((...any) → ...any)

Parameters

sourceOrBytecode: string

Luau source code or compiled bytecode.

chunkname: string?

Optional name for the chunk (shown in errors/stack traces, defaults to "=load"). May be omitted when passing options.

options: LoadOptions?

Optional load options (e.g. fast-flag overrides).

Returns

((...any) → ...any)

The loaded function.

vm.disassemble

Returns a human-readable bytecode listing for the given source.

Compiles the source and returns a formatted disassembly string showing every function's bytecode instructions, optionally with source lines, local variable info, compiler remarks, and type annotations.

local listing = vm.disassemble(source, {
    showLocals  = true,
    showRemarks = true,
})
print(listing)
vm.disassemble(source: string, options: DisassembleOptions?) → string

Parameters

source: string

The Luau source code to disassemble.

options: DisassembleOptions?

Disassembly options controlling output detail.

Returns

string

The formatted bytecode listing.

Types

CompileOptions
type CompileOptions = { optimizationLevel: number?, debugLevel: number?, coverageLevel: number?, typeInfoLevel: number?, flags: { [string]: boolean | number | string }? }
optimizationLevel: number?

Optimization level (0-2). Higher levels enable more aggressive inlining and dead-code elimination. Default is 1.

debugLevel: number?

Debug info level (0-2). 0 = none, 1 = line numbers only (default), 2 = line numbers + local/upvalue names.

coverageLevel: number?

Coverage instrumentation level (0-2). 0 = none (default), 1 = statement coverage, 2 = expression coverage.

typeInfoLevel: number?

Type info annotation level (0-1). When 1, tags locals and upvalues with type info for native codegen. Default is 0.

flags: { [string]: boolean | number | string }?

Luau fast-flag overrides applied before compilation. Values may be booleans, numbers, or their string representations.

LoadOptions
type LoadOptions = { flags: { [string]: boolean | number | string }? }
flags: { [string]: boolean | number | string }?

Luau fast-flag overrides applied before loading/compiling. Values may be booleans, numbers, or their string representations.

DisassembleOptions
type DisassembleOptions = { optimizationLevel: number?, debugLevel: number?, showLocals: boolean?, showRemarks: boolean?, showTypes: boolean?, flags: { [string]: boolean | number | string }? }
optimizationLevel: number?

Optimization level used when compiling before disassembly (0-2). Default is 1.

debugLevel: number?

Debug info level used when compiling (0-2). Default is 1.

showLocals: boolean?

If true, include local variable liveness ranges in the listing.

showRemarks: boolean?

If true, include compiler remarks (e.g. inlining decisions) in the listing.

showTypes: boolean?

If true, include type annotation info for tagged locals in the listing.

flags: { [string]: boolean | number | string }?

Luau fast-flag overrides applied before compilation. Values may be booleans, numbers, or their string representations.