GitHub - mmcdole/lunar: A Lua 5.1 runtime for Go.

A fast, memory-efficient Lua 5.1 runtime for Go.

Lunar is a complete implementation of Lua 5.1 (plus 5.2-style goto and labels) in pure Go. It passes the official Lua 5.1 test suite.

Quick start

package main

import (
	"fmt"

	"github.com/mmcdole/lunar"
)

func main() {
	state, err := lua.New(lua.Options{Libraries: lua.CoreLibraries()})
	if err != nil {
		panic(err)
	}
	defer state.Close()

	results, err := state.DoString("@demo.lua", `return ("lunar"):upper()`)
	if err != nil {
		panic(err)
	}

	text, _ := results[0].AsString()
	fmt.Println(text) // LUNAR
}

Libraries and file access are opt-in. lua.CoreLibraries() installs everything that can't touch the host, and lua.FullLibraries() adds IO, OS, and debug for scripts you trust. Loading scripts from disk is disabled until you configure a ScriptLoader.

Calling Go from Lua

NewNativeFunction wraps a Go function as a Lua value. Inside the callback, everything goes through the Frame: read arguments with its typed accessors, then return a result or throw a Lua error:

// Callable from Lua as greet(name).
greet, err := state.NewNativeFunction(func(frame lua.Frame) lua.Outcome {
	name, ok := frame.String(0) // first argument, must be a string
	if !ok {
		frame.ThrowArgTypeError(0, lua.StringKind)
	}
	return frame.ReturnString("hello, " + name)
})
if err != nil {
	panic(err)
}
if err := state.SetGlobal("greet", greet.Value()); err != nil {
	panic(err)
}

// results[0] is "hello, moon"
results, err := state.DoString("@hello.lua", `return greet("moon")`)

See Embedding Lunar for the full guide: calls, callbacks, tables, errors, cancellation, coroutines, and lifecycle.

Performance

Medians from 15 runs on an Apple M3 Pro with Go 1.25.1; each linked result set records its exact source revision. Lower is better.

The ratio depends on workload shape: Lunar wins on per-table overhead and on reusing repeated strings up to 64 bytes, while raw string bytes cost both runtimes the same, so the gap narrows toward 1× as string payload dominates. Loading the CBOR graph also allocates 7.3× less transient memory (107.5 MB versus 784.6 MB).

The full results include confidence intervals, allocation counts, and raw output; the benchmark protocol lists the commands, inputs, and runtime versions.

Compatibility

Scope

The compiler, VM, standard libraries, coroutines, binary chunks, weak tables, and finalizers are implemented. Current intentional limits:

• no C ABI, native C-module loading, or light userdata;
• no debug.sethook or debug.gethook;
• garbage collection runs synchronously rather than incrementally;
• no deterministic VM-instruction budget; and
• no table-iteration helpers beyond the Table.Next primitive.

A State serves one goroutine at a time; separate States can run concurrently.

The public embedding API is still stabilizing.

Documentation

• Embedding: setup, calls, callbacks, values, contexts, errors, and lifecycle
• Architecture: compiler, VM, runtime representation, and API boundaries
• Language compatibility: the goto extension and intentional Lua 5.1/5.2/LuaJIT choices
• Collection: Lua reachability, weak tables, and finalization
• Third-party notices: adapted algorithms, artwork, and benchmark sources

Lunar is available under the MIT License.