l3i

The Luau runtime for DreamWeave. A Rust binder for Luau 0.740 that owns its own Luau build, plans every VM before it exists, and lowers hot script calls to native code.

l3i is its author's second Luau binder. The first is C++: components/luau, which Dave Corley (S3kshun8) wrote for OpenMW on the feat/least-mergeable-branch branch of his fork. That branch is not in OpenMW's master and may never be: OpenMW's own scripting is components/lua, and OpenMW has no Luau binder. l3i is that binder done again in Rust, then given what a multi-crate engine needs on top. "The C++ binder" in the documentation is that one, and every components/luau/... file and testluau*.cpp test the sources cite is a file on that branch, at commit f69579c8. Where the fast paths came from links each optimisation to the C++ lines it started as. l3i is not affiliated with or endorsed by the OpenMW project.

Documentation: https://DreamWeave-MP.github.io/l3i/. This file is the short version.

• What it is
• Quick start
• What you get
• Features
• The rules
• Building
• Quality
• License

Nothing here is a catalogue: tags, atoms, type names and debug-name roots are host data.

[dependencies]
l3i = { version = "1", features = ["jit"] }   # jit, analysis, soft-render, bytes(-codecs, -digests, -text), intern, syntax, fs, process are optional

l3i builds only with clang, lld and cross-language thin LTO, and Cargo does not inherit a dependency's config, so copy the [env] and rustflags lines from this repository's .cargo/config.toml into your own. build.rs refuses anything else and names the missing piece; L3I_UNVERIFIED_TOOLCHAIN=1 turns that into a warning. Start here walks through it.

use l3i::Runtime;
use l3i::userdata::{Owned, Userdata, tagged};

struct Vec3 { x: f32, y: f32, z: f32 }

unsafe impl Userdata for Vec3 {
    const NAME: &'static str = "dreamweave.Vec3";
}

fn main() -> l3i::Result<()> {
    let runtime = Runtime::new()?;
    // The host picks the tag, per runtime, at registration.
    tagged::register::<Vec3>(&runtime, 10, |ty| {
        ty.property("x", |v: &Vec3| v.x)?;
        ty.method("length", |v: &Vec3| (v.x * v.x + v.y * v.y + v.z * v.z).sqrt())
    })?;
    let make = runtime.bind_function("dreamweave.vec3", |x: f32, y: f32, z: f32| Owned(Vec3 { x, y, z }))?;
    runtime.set_global("vec3", &make)?;
    runtime.exec("local v = vec3(3, 4, 0) assert(v.x == 3 and v:length() == 5)")?;
    Ok(())
}

That is the hand-assembled runtime. An engine composes one from extensions instead:

use l3i::Runtime;
use l3i::extension::{RuntimePlan, RuntimePolicy};
use l3i::quat::QuatExtension;
use l3i::raster::RasterExtension;

let plan = RuntimePlan::builder()
    .policy(RuntimePolicy::new().compat_global("@dream/quat", "quat"))
    .extension(QuatExtension)
    .extension(RasterExtension)
    .finalize()?;
let runtime = Runtime::from_plan(&plan)?;            // any number of these per plan
std::fs::write("dream.d.luau", plan.type_definitions())?;

Each row is a page of the guide.

The default feature set is empty. Networking is not a feature: dream-net is a dependency. Everything optional is pure Rust.

The short form of the safety model, which also records the Luau facts the ecosystem builds on and the deliberate divergences from the C++ binder.

• Luau is built with C++ exceptions. A Lua error inside a bound function unwinds through Rust frames to Luau's pcall; nothing puts catch_unwind on that path. A panic inside a native call aborts. Host-level raising calls run under lua_pcall.
• Stack is exclusive and never pops; temporaries live in a Frame; one open child frame per scope; views cannot escape the frame that owns their slot.
• Receivers are &T, never &mut T, because one userdata can appear in several argument slots of one call. Mutation goes through interior mutability.
• Bound callables are Fn, not FnMut: a binding can re-enter itself through Lua.
• Every unsafe block states the invariant it relies on. GC destructors never call the Lua API.
• Tags are 1..254; tag 0 is Luau's untagged default. Fast flags follow OpenMW's policy (plus LuauExperimentalIfLocalSyntax) and are frozen before the first VM or compile.
• Luau integers (42i) compare with == only and never equal a number, so identities (peers, events, handles, packed scalars) are integers and everything a script counts or thresholds is a plain number.

The value layout the binder reads is pinned by static_asserts in csrc/extra.cpp and proven against the API once per runtime, so a Luau bump that moves a byte fails at once. Every Luau API function in lua.h, lualib.h, luacode.h, luacodegen.h, luajitinliner.h and Require.h is declared in l3i::ffi, except the varargs lua_pushvfstring. TOOLCHAIN.md has the measurements behind the rule and Building the whole procedure.

cargo test, cargo test --all-features, cargo clippy --all-targets --all-features -- -W clippy::pedantic -D warnings and cargo fmt --check are clean on every commit. The integration tests link as one binary (cargo test <file>:: runs one file), since each binary pays a full link-time codegen under cross-language LTO. BENCHMARKS.md holds the Criterion numbers for the hot paths.

Wall time is noise past a few nanoseconds, so the binder's own cost is tracked in retired instructions per call from the CPU's counters (cargo bench --bench instructions), the loop subtracted, on the pinned Luau 0.740:

Every scenario reports fewer than 0.005 cache, TLB and branch misses per call. A bare VM's heap is 64 KiB after a full collection; the binder's own state is a 600-byte shared block plus 32 bytes per plan slot. Compatibility and performance has every table.

MIT OR Apache-2.0. Luau is Roblox's, under the MIT license; its notice ships in the package as luau/LICENSE.txt and luau/lua_LICENSE.txt.