Reference Implementations

Classification of implementations studied during architecture design. Each was examined for its approach to compilation, VM design, memory management, and API surface.

Tier 1 — Primary References

PUC-Rio Lua 5.1.1 (C)

• Source: ./lua-5.1.1/ (vendored in repo; see AGENTS.md for setup)
• Role: The specification. All behavioral questions are answered here.
• Architecture: 17,654 lines. Single-pass recursive descent compiler emitting 38 register-based opcodes (u32 packed). CallInfo chain for call stack. Incremental tri-color mark-sweep GC with write barriers. Array+hash tables. Interned strings with cached hash. longjmp/setjmp error handling. Stack-based C API.
• What we take: Opcode semantics, GC behavioral contract, weak table semantics, finalizer protocol, collectgarbage() API, standard library behavior, error messages.
• What we change: Single-pass compilation (we use AST), longjmp (we use Result), C API (we use traits), raw pointers (we use arenas).

Luau (C++)

• GitHub: https://github.com/luau-lang/luau
• Role: Architecture reference. Lua 5.1-compatible scripting language.
• Architecture: Lexer -> Parser -> AST -> Compiler -> VM. 83 register-based opcodes (count evolves with development). Incremental tri-color GC. CallInfo chain. Array+hash tables. String interning. No longjmp (C++ exceptions).
• What we take: AST-based pipeline design, separation of compiler phases, Proto as non-GC value (owned by closures), CallInfo chain pattern, incremental GC debt model.
• What we change: Opcode count (we use PUC-Rio’s 38, not Luau’s 83), language extensions (we implement standard Lua 5.1.1 only), native codegen (out of scope).

Tier 2 — Selective References

tsuki (Rust, Lua 5.4)

• GitHub: https://github.com/nickmass/tsuki
• Role: Proves Result-based error handling works for a Lua VM.
• Architecture: c2rust translation of Lua 5.4. PUC-Rio file naming (llex.rs, lparser.rs, lcode.rs). 83 opcodes. Incremental GC via raw pointers. Heavy use of unsafe code. Memory-safe public API over unsafe internals.
• What we take: Result-based error propagation pattern, memory-safe public API design, packed u32 instruction format for serialization.
• What we avoid: c2rust code style, heavy unsafe, wrong Lua version (5.4 vs 5.1.1).

full-moon (Rust, parser only)

• GitHub: https://github.com/Kampfkarren/full-moon
• Role: Best Rust patterns for Lua parsing.
• Architecture: Hand-written recursive descent parser. Lossless AST preserving whitespace and comments. Error recovery with partial AST. Multi-dialect support (5.1-5.4, Luau) via feature flags. Sealed traits, visitor pattern, builder pattern.
• What we take: Recursive descent parsing patterns, AST node design idioms, error recovery approach, sealed trait pattern.
• What we avoid: Lossless parsing (unnecessary for a VM), multi-dialect support (we only target 5.1.1), external dependencies.

mlua (Rust, FFI wrapper)

• GitHub: https://github.com/mlua-rs/mlua
• Role: API design reference for embedding Lua in Rust.
• Architecture: FFI wrapper around C Lua. Memory-safe Rust API over unsafe C bindings. Trait-based type conversions (IntoLua, FromLua). Registry-based lifetime management. Scoped values. UserData trait.
• What we take: Trait-based API design (IntoLua/FromLua pattern), UserData trait approach, scope-based lifetime management, error type design.
• Not applicable: FFI wrapping (we implement from scratch), C Lua compilation, vendored builds.

lua-rs / CppCXY (Rust, Lua 5.5)

• GitHub: https://github.com/CppCXY/lua-rs
• Role: Architecture comparison. Full Lua 5.5 port to Rust with pointer-based VM design.
• Architecture: 64k lines across workspace (luars, luars-derive, luars_interpreter, luars_wasm). Faithful port of C Lua’s architecture: pointer-based VM dispatch, 86 Lua 5.5 opcodes, tri-color incremental + generational GC, 16-byte TValue (union + type tag), Brent’s collision tables, interned strings, pointer-based upvalues. 399 unsafe blocks. Multi-crate workspace with proc-macro derive crate. 28/30 official Lua 5.5 tests pass. External dependencies: ahash, rand, chrono, itoa, smol_str, syn/quote (macros).
• What we can study: Async/await coroutine bridging (novel feature), proc-macro derive for UserData, generational GC implementation, Lua 5.5 opcode set, lightweight 1-byte error enum with message stored in VM, platform abstraction layer design, WASM support approach.
• Key differences from rilua: Targets Lua 5.5 (not 5.1.1), uses raw pointers and union types (C-style, 399 unsafe blocks vs rilua’s arena-based zero-unsafe GC), has external dependencies (ahash, rand, chrono, smol_str vs rilua’s zero-dependency policy), pointer-based upvalues (vs rilua’s arena indices), larger scope (64k LOC vs rilua’s ~17k), proc-macro crate for ergonomic API.

Tier 3 — Limited Relevance

lua-in-rust (Rust, Lua 5.1.1)

• GitHub: https://github.com/cjneidhart/lua-in-rust
• Role: Previous base for rilua. Studied for lessons learned.
• Architecture: Single-pass compiler, stack-based VM (~40 custom opcodes), stop-the-world mark-sweep GC with raw pointers, string interning, HashMap-only tables. ~5,000 lines. ~40% complete.
• Lessons: Stack-based VM diverges too far from PUC-Rio’s register-based design. Single-pass compilation makes the compiler hard to test and extend. Raw pointer GC works but is fragile. String interning with pointer equality is the right approach.

lua-rs / lonng (Rust, compiler only)

• GitHub: https://github.com/lonng/lua-rs
• Role: Shows AST-to-bytecode compilation for Lua 5.1.
• Architecture: Multi-pass with explicit AST. Scanner -> Parser -> AST -> Compiler -> FunctionProto. No VM. Broken build. Zero unsafe.
• Useful for: AST node design, constant folding patterns, debug info tracking. Not useful for VM or runtime design.

lua-rs (Rust, full interpreter, CppCXY)

• Local path: ~/Repos/github.com/CppCXY/lua-rs
• GitHub: https://github.com/CppCXY/lua-rs
• Role: Performance comparison target. One-to-one C Lua 5.5 port.
• Architecture: Direct port of PUC-Rio’s C source to Rust. Same pipeline (Lexer -> Parser -> Code Generator -> Bytecode -> VM), 86 opcodes, tri-color incremental/generational GC, string interning. ~60K lines, ~400 unsafe blocks for GC pointer ops. 5 runtime deps (ahash, rand, chrono, itoa, smol_str). Requires nightly Rust.
• Useful for: Benchmarking (runs ~1.2x PUC-Rio on micro-benchmarks), comparing pure-Rust Lua implementation approaches and the safety-vs-performance trade-off.
• Differences: Targets Lua 5.5 (not 5.1.1), uses unsafe extensively, requires nightly. See docs/src/comparison.md.

coppermoon (Rust, mlua wrapper)

• GitHub: https://github.com/coppermoondev/coppermoon
• Role: None for VM/compiler work.
• Architecture: Node.js-like runtime wrapping mlua (C Lua 5.4 FFI). Not a from-scratch implementation. Provides batteries-included stdlib (HTTP, SQLite, WebSocket, etc.) over the C VM.
• Not applicable: Everything. This wraps C Lua, not implements it.

hematita (Rust, Lua 5.3)

• GitHub: https://github.com/danii/hematita
• Role: Reference for hardened Lua interpreter patterns in Rust.
• Architecture: From-scratch Lua interpreter in Rust targeting 5.3. Focuses on safety and correctness. Useful for comparing implementation approaches for parsing, value representation, and standard library.
• What we take: Comparison point for implementation patterns and edge case handling.
• Differences: Targets Lua 5.3 (not 5.1.1), different design goals.