Format:Luau bytecode
| On this wiki | Facts · Code · Notes · Topics |
|---|
Serialized Luau function protos (Roblox and other Luau embedders): no \x1bLua signature; the first byte is the bytecode version (3 to 14 accepted by the loader at the cited commit, 0 means an error message follows), then for version 4+ a type-encoding version byte, a varint-counted string table and the protos with 32-bit-word instructions.
Overview
Library:Luau is a Lua 5.1 derivative; its compiler emits a binary string that luau_load (VM/src/lvmload.cpp) reads. Unlike Format:Lua bytecode there is no 1B 4C 75 61 signature, no size/endianness header and no test numbers: the very first byte is the bytecode version. A blob is therefore recognised by a plausible first byte (3 to 14 at the cited commit; the compiler default LBC_VERSION_TARGET is 9), a type version byte of 1 to 3 as second byte, and then a varint string count followed by length-prefixed strings.
Header
- byte 0: version. Value 0 means the rest of the buffer is a compile error message, not bytecode. The loader accepts
LBC_VERSION_MIN(3) toLBC_VERSION_MAX(14) and additionally the experimental value 100 (LBC_VERSION_CLASSES); otherwise it fails withbytecode version mismatch (expected [3..14], got N). - byte 1 (only if version >= 4): type-encoding version, accepted 1 to 3 (
LBC_TYPE_VERSION_*), elsebytecode type version mismatch. - varint: string count, then per string a varint length and the raw bytes (no NUL). Strings are later referenced by 1-based varint index; index 0 means NULL.
- if type version is 3: userdata type remapping table, entries of (byte index, string reference) ended by a 0 byte.
- varint: proto count, then the protos, then a varint index of the main proto.
Varints are 7 bits per byte, least significant group first, high bit set on all bytes except the last (readVarInt).
Proto
In order: (version >= 12 only: varint byte size of the proto), maxstacksize, numparams, nups, is_vararg (one byte each); for version >= 4 a flags byte (LPF_*: native module 1, native cold 2, native function 4, inlinable 8, uses export 16) and a varint-sized type info blob (type version 1 stores a 2+numparams function signature, versions 2 and 3 the raw bytes); varint instruction count and that many little-endian u32 words; varint constant count and tagged constants; varint child-proto count and varint proto ids; varint linedefined; a string reference for the debug name; a lineinfo flag byte (if set: log2 gap byte, one byte delta per instruction, one i32 delta per interval); a debuginfo flag byte (if set: local variables with name, startpc, endpc, register, then upvalue names); for version >= 11 a feedback vector description; for version >= 12 a cost varint if the proto is inlinable.
Constants
Tag byte, then: 0 nil, 1 boolean (byte), 2 number (double), 3 string (reference), 4 import (u32 packed global path), 5 table (varint key count, key constant ids), 6 closure (varint proto id), 7 vector (4 floats), 8 table with constants (version 7+), 9 integer (version 8+: sign byte and varint64 magnitude), 10 class shape (experimental), 11 vector of doubles (version 13+).
Instructions
Word code: opcode in the low byte; ABC = A bits 8-15, B bits 16-23, C bits 24-31; AD = A and a signed 16-bit D in bits 16-31; E = signed 24-bit in bits 8-31. Some opcodes are followed by a 32-bit AUX word, and the length is static per opcode (except NEWCLOSURE as the header says), so a disassembler needs the opcode table of Bytecode.h for the exact version. At the cited commit the LuauOpcode enum runs from LOP_NOP to LOP_FASTPCALL followed by LOP__COUNT. The loader may rewrite GETTABLEKS, SETTABLEKS and NAMECALL to userdata variants in memory; those never appear in a dump.
Version history (from the header comment of Bytecode.h)
v3 forward-group opcodes and JUMPXEQK; v4 proto flags, typeinfo, IDIV; v5 SUBRK/DIVRK and vector constants; v6 FASTCALL3; v7 table-with-constants; v8 integer constants; v9 userdata field atoms; v10-13 experimental (classes, feedback vectors, per-proto size, double vectors); v14 FASTPCALL.
Code & repositories
- https://github.com/luau-lang/luau @
9d7748a4f324213a18cb8283fa2a77c330225fa0· license: MIT
Luau source (MIT): VM/src/lvmload.cpp is the bytecode loader, Common/include/Luau/Bytecode.h the opcode and tag definitions with the version history.
Tested on: source read, not run · checked 2026-10-19; last activity 2026-10-16; Note: the latest release ships binaries; the wiki links only the source, never the binaries
Pitfalls
- Luau does not guarantee bytecode compatibility between releases; support for old versions is dropped, so a decompiler is tied to a version range.
- Unverified: Roblox's own client ships bytecode whose opcode bytes are obfuscated by a multiplier and signed with a hash; that is not in the open-source repository and was not checked.
- Unverified: no decompiler was evaluated for this page.