Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Format:LuaJIT bytecode

From ReverseEngineering.wiki
Format
Developer Mike Pall
Versions dump version 1 (LuaJIT 2.0), 2 (LuaJIT 2.1); 0x80 or higher for private modifications
Magic 1B 4C 4A + version byte (2 in 2.1) + flags (ULEB128)
Extensions .ljbc, .luac, .raw (luajit -b output name is chosen by the user)
Endianness instructions and constants in the dump follow flag bit 0 (BE)
License MIT (reference implementation)
On this wiki Facts · Code · Notes · Topics

Precompiled chunk format of LuaJIT (luajit -b, string.dump): the header 1B 4C 4A (ESC 'L' 'J'), a dump version byte (1 for LuaJIT 2.0, 2 for 2.1), a ULEB128 flags value and an optional chunk name, then length-prefixed function prototypes with 32-bit instructions in an 8-bit-opcode ABC/AD encoding and ULEB128-packed constants. It is unrelated to the PUC-Rio layout of Format:Lua bytecode.

Overview

Library:LuaJIT has its own bytecode, with a different instruction set from PUC-Rio Library:Lua 5.1 even though the language is the same: luajit -b script.lua out.raw, string.dump(f [, strip]) and lj_bcwrite produce it, lj_bcread loads it (the loader accepts a chunk whose first byte is 0x1B). A tool for Format:Lua bytecode cannot read it. The format has no checksum.

Header

Grammar from the comment in src/lj_bcdump.h:

dump   = header proto+ 0U
header = ESC 'L' 'J' versionB flagsU [namelenU nameB*]
proto  = lengthU pdata
pdata  = phead bcinsW* uvdataH* kgc* knum* [debugB*]
phead  = flagsB numparamsB framesizeB numuvB numkgcU numknU numbcU [debuglenU [firstlineU numlineU]]
(B = 8 bit, H = 16 bit, W = 32 bit, U = ULEB128; the last proto is followed by a 0 length)

Bytes: 1B 4C 4A, the dump version (BCDUMP_VERSION = 2 in the 2.1 source; a private modification of the format must use 0x80 or higher, so a first-byte-after-LJ of 0x80+ means a vendor fork), the flags (ULEB128; one byte for the known bits) and, unless the dump is stripped, the ULEB128 length and bytes of the chunk name (for example @script.lua). A stripped dump has no name and no debug sections.

Flags: 0x01 big-endian, 0x02 stripped, 0x04 uses FFI, 0x08 FR2 (64-bit stack frames, GC64 builds), 0x10 uses bit ops; 0x80000000 asks the writer for deterministic table order. The reader rejects a dump whose version differs, that has unknown flag bits, or whose FR2 flag does not match the loading VM's frame size: a GC64 LuaJIT cannot load non-GC64 dumps and vice versa. Typical headers: 1B 4C 4A 02 00 (2.1, full), 1B 4C 4A 02 02 (2.1 stripped), 1B 4C 4A 02 0A (2.1 stripped, GC64 build), 1B 4C 4A 01 .. (2.0).

Instructions

Instructions are 32-bit words with an 8-bit opcode in the low byte: format ABC = op | A<<8 | C<<16 | B<<24, format AD = op | A<<8 | D<<16 (D 16 bit; jumps use D - 0x8000). Constants are split in GC constants (child prototype type 0, table 1, signed int64 2, uint64 3, complex 4, strings as 5 + length) and numeric constants (ULEB128 of value+1 for ints that fit 32 bit, else two words). Table constants carry nil/false/true/int/num/str entries (types 0 to 5). Slot numbering in the dump is the in-memory numbering, so a decompiler must know the exact VM version (the opcode list in src/lj_bc.h changes between 2.0 and 2.1 and in the rolling branch).

Decompilers

See Technique:Choosing a decompiler (the LuaJIT decompiler row is marked Unverified there).

Code & repositories

  • https://github.com/LuaJIT/LuaJIT @ 2a8e017ef1ece6a95b983ffca073d30609dce7c4 · license: MIT (declared by the contributor; GitHub's detector did not recognize a license file)
    The LuaJIT source (MIT): src/lj_bcdump.h documents the dump format, lj_bc.h the instruction set, lj_bcwrite.c and lj_bcread.c the writer and loader; the v2.1 branch is the rolling release.
    Tested on: source read, not run: source read at the pinned commit; nothing built or run · checked 2026-10-18; last activity 2026-10-14

Pitfalls

  • Many Lua games ship LuaJIT bytecode with the .lua or .luac extension; check the third byte (4A = LuaJIT, 75 = PUC-Rio).
  • LuaJIT 2.0 (branch v2.0 at commit 2410b57fd466298e6a64a68986a6b696c23656ac) defines BCDUMP_VERSION 1 and only the flags BE 0x01, STRIP 0x02 and FFI 0x04 (known mask 0x07), in src/lj_bcdump.h lines 39-46; 2.1 (branch v2.1, commit dd3b24369ddfaa83c78cd6fdd91d157c8968ec8d) defines version 2 and adds FR2 0x08, BITOP 0x10 and DETERMINISTIC 0x80000000 (lines 39-50). Read from the source; no 2.0 binary was checked.
  • Obfuscated or modified dumps (renumbered opcodes, XOR-ed bytes) are common; the 0x80+ version rule is a convention, not enforced.

Evidence & references

  • LuaJIT/LuaJIT commit 2a8e017ef1ece6a95b983ffca073d30609dce7c4: src/lj_bcdump.h (grammar, BCDUMP_* constants), src/lj_bcwrite.c (bcwrite_header, lines 388-410), src/lj_bcread.c (header validation, lines 398-413), src/lj_bc.h (instruction formats). Read only, nothing built.