Skip to content
l3i
guide

Documentation

How l3i puts a safe, scoped Rust layer over Luau 0.742: the stack tiers, userdata, modules and sandboxes, runtime options, direct access, the rest of the VM, the built-in extensions, the dialect, the safety model, and the complete Rust API.

l3i is a Rust binder for Luau 0.742. It began as a C++ Luau binder its author wrote for OpenMW; when these pages say “the C++ binder”, that is the one they mean, and Where the fast paths came from points at its lines. l3i owns its Luau build, declares the C API by hand, and puts a scoped layer over it: frame-bound stack views, registry-pinned owned values, a typed function binder that reads arguments straight from stack slots, tagged and untagged userdata, Luau’s direct userdata access, sandboxed script instances, and watchdog and profiler plumbing. The host owns the Runtime; component crates register bindings into it.

Tags, atoms, type names and debug-name roots are host data. The crate ships the mechanism and never a catalogue, so the same Rust type can be tag 8 in one runtime, tag 17 in another, and untagged in a third.

Learn it#

  • Start here: the crate, the toolchain it insists on, and a first program that exposes a Rust type to a script.
  • Stack and values: the three tiers, frames and views, owned values, and what the typed binder accepts and returns.
  • Userdata: tagged and untagged registration, the metatable builder, receivers, and the storage wrappers.

Use it#

  • Modules and sandboxes: frozen package tables, read-only views, per-script environments, templates, and require.
  • Runtime options: the builder, the watchdog, memory categories, call scopes, the collector, the profiler, and fast flags.
  • Direct access and atoms: atom catalogues, dispatch plans, cache validation, direct handlers, and direct fields.
  • Extensions: describing a crate’s whole Luau surface as a plan that instantiates any number of runtimes.
  • Primitives: bytes, strict options, exact integers, packed scalars, sequences and streams.
  • Built-in extensions: the network bridge, packed rotations and colours, bytes, the data plane, interning, locales, Luau’s parser, the filesystem, processes, TCP, DNS and TLS.
  • The l3i dialect: comprehensions, reducers, sinks, slices and record patterns, how they lower, what tooling sees, and what they cost.
  • Native code: Luau’s code generator with lowering hooks written in Rust.
  • Coroutines, debugging and the rest of the VM: threads, the debug API, memory controls, libraries, require, and the analysis feature.

Look it up#

  • Safety model: what the crate guarantees, the Luau facts it builds on, and where it diverges from the C++ binder on purpose.
  • Building: the submodule, what build.rs compiles, and the defines it owns.
  • Performance: instructions and cycles per call, and the benchmark suites.
  • Rust API: every public type, function and constant.