Moonquakes is a clean implementation of the Lua 5.4 virtual machine and runtime, written entirely in Zig.
Rather than binding to the existing C codebase, it reimagines the Lua execution model with modern clarity, explicit memory control, and a focus on readability over historical constraints.
The goal is not to create a direct port, but to reconstruct Lua’s core — values, bytecode, virtual machine, and eventually its standard library — in a way that is transparent, hackable, and faithful to the spirit of the language.
This document describes the internal architecture of Moonquakes: how the VM is structured, how instructions are encoded and executed, how values are represented, and how components such as prototypes, call frames, and runtime state interact.
It serves as a technical map for contributors and for future phases of development.
Moonquakes follows the same 32-bit instruction format used by the official Lua 5.4 virtual machine.
Every instruction is exactly one 32-bit word and is divided into several fields: OpCode, A, k, B, and C, or into larger composite fields depending on instruction mode.
The most common instruction encoding used by Lua 5.4 is the iABC format.
Each instruction is a 32-bit unsigned integer. Bit positions are described using little-endian bit numbering, where bit 0 is the least significant bit.
+-------------------------------------------------+
| 31 ... 24 | 23 ... 16 | 15 | 14 ... 7 | 6 ... 0 |
|-----------|-----------|----|----------|---------|
| C | B | k | A | OP |
+-------------------------------------------------+