Luau Runtime

Luau Runtime is a Minecraft mod library that lets other mods compile and run sandboxed Luau scripts. Native Luau libraries are bundled inside the mod JAR, so no native code is downloaded at runtime.

Features

• Strict type checking and compilation of in-memory Luau source files.
• Isolated, persistent ScriptInstances with explicit lifecycle management.
• Controlled source and host modules, including a sandboxed require.
• Safe conversion between Java values and Luau values.
• Limits for execution time, interrupt checks, VM memory, and host calls.
• Source breakpoints, stepping, pause, resume, and termination support.

Build

Initialize the Luau submodule, then build the project:

git submodule update --init --recursive
./gradlew build

A normal build compiles the JNI library for the current platform and embeds it in the produced JAR.

Quick start

Compile a root module, create an instance, initialize it once, and invoke an exported function:

import io.github.suterxom.luau.v1.api.LuauRuntime;
import io.github.suterxom.luau.v1.api.runtime.ExecutionResult;
import io.github.suterxom.luau.v1.api.value.LuauNumber;

import java.util.List;

var runtime = LuauRuntime.getInstance();
var compilation = runtime.compile("example/main", """
        local total = 0

        return {
            add = function(value: number): number
                total += value
                return total
            end,
        }
        """);

if (!compilation.successful()) {
    throw new IllegalStateException(compilation.diagnostics().toString());
}

try (var chunk = compilation.chunk().orElseThrow();
     var instance = chunk.createInstance()) {
    if (!(instance.initialize() instanceof ExecutionResult.Completed)) {
        throw new IllegalStateException("Script initialization failed");
    }

    var result = instance.invokeExport("add", List.of(new LuauNumber(2)));
    if (result instanceof ExecutionResult.Completed completed) {
        System.out.println(completed.values()); // [LuauNumber[value=2.0]]
    }
}

The root module must return an export table. initialize() runs its top-level code once, while invokeExport() calls a function from that table. Handle the other ExecutionResult variants when scripts may pause, exceed limits, or fail at runtime.

Third-party notices

This project embeds and distributes the Luau implementation. Luau is distributed under the MIT License and is based on the Lua 5.x implementation, which is also distributed under the MIT License.

Please refer to native/luau/LICENSE.txt and native/luau/lua_LICENSE.txt for the applicable license texts.