Binding and userdata

Modules l3i::bind, l3i::userdata (with tagged, untagged, metatable, iterator, dispatch), l3i::module, l3i::readonly, l3i::require and l3i::libraries. Userdata and Modules and sandboxes are the guides.

The binder#

Module l3i::bind. A Rust closure becomes a Lua function whose parameters are materialised one checked conversion each, positionally, with the C++ binder’s rules:

• &Call is injected and consumes no argument;
• ValueView borrows one argument slot without conversion;
• Option<T> maps absent and nil to None; a middle optional stays greedy and is skipped only when a following required parameter can consume the slot (nil disambiguates);
• VarArgs<T> and ArgView are terminators consuming every remaining argument, and must be last (a compile-time assertion);
• fixed arity rejects unused arguments, counts are validated before any conversion, and the first failing argument is reported with its position and expected type;
• Overload((f1, f2, ..)) tries candidates in order and the first probe match commits.

The closure is moved into a Lua-owned userdata (upvalue 1 of the C closure) and dropped by the collector, so captures must be 'static and must not touch the Lua API in Drop. Bound closures are Fn, not FnMut: a binding can re-enter itself through Lua, so state lives in Cell/RefCell captures. Up to eight parameters.

A Rust callable the binder can expose; Marker is inferred from the signature and never named. Implemented for every Fn(P1, .., Pn) -> R + 'static whose parameters are Param and whose result is Return, and for Overload.

An ordered overload set of one to five callables. Candidates are tried in declaration order and the first whose probe matches commits, so its conversion errors then propagate; no match is <name>: no matching overload. Nested overload sets never match, and an overload set cannot be bound as a method.

Binds callable as a Lua function named debug_name, validated against roots and retained for the VM’s life, and returns it pinned with the stack of scope left as it was. Runtime::bind_function is this over the runtime’s own roots.

Argument errors, word for word from bindfunction.cpp: <name>: bad argument #N (expected T): <cause>, <name>: bad argument #N (expected T): missing argument, <name>: bad argument count (expected at least N, got M), <name>: bad argument count (expected at most N, got M), <name>: bad argument count (unused arguments). A method called without a receiver (obj.method()) reports missing argument #1 to '<name>' (<type> expected).

use l3i::Runtime;
use l3i::bind::{Call, Overload, VarArgs};

fn main() -> l3i::Result<()> {
    let runtime = Runtime::new()?;
    let sum = runtime.bind_function("dreamweave.sum", |values: VarArgs<f64>| values.values.iter().sum::<f64>())?;
    runtime.set_global("sum", &sum)?;
    let greet = runtime.bind_function("dreamweave.greet", |name: &str, times: Option<i32>| {
        format!("{name}{}", "!".repeat(times.unwrap_or(1) as usize))
    })?;
    runtime.set_global("greet", &greet)?;
    let either = runtime.bind_function(
        "dreamweave.either",
        Overload((|n: f64| n * 2.0, |s: &str, _call: &Call| s.len() as f64)),
    )?;
    runtime.set_global("either", &either)?;
    runtime.exec("assert(sum(1, 2, 3) == 6) assert(greet('hi') == 'hi!') assert(greet('hi', 3) == 'hi!!!')")?;
    runtime.exec("assert(either(4) == 8 and either('abc') == 3)")?;
    Ok(())
}

Call#

The native call’s frame: the arguments at 1..=argument_count() and the stack above them, where results are pushed. Injected into a callable as &Call. Implements Scope.

Parameters#

A parameter type with the call lifetime erased; Item<'c> is what the callable receives for a call living 'c. This is what lets |view: ValueView, s: &str| be written without lifetimes.

One parameter of a call living 'c: KIND, EXPECTED, read_slot, read_arg, read_receiver, matches, probe and materialize. Hosts rarely implement it by hand: the impl_param_from_view! macro (exported at the crate root) implements Param and ParamItem for an owned type that already implements FromView for every lifetime.

How a parameter consumes Lua arguments: exactly one; none (&Call); zero or one; every remaining argument converted; every remaining argument borrowed. Clone, Copy, Debug, Eq.

Every remaining argument converted as T; must be the final parameter. start_slot is the physical stack slot of the first collected argument (it includes a method receiver; binder diagnostics number arguments separately). Debug.

A borrowed view over every remaining argument, heterogeneous and lazy, valid only for the call. Clone, Copy.

A tuple of Param markers with its compile-time descriptors (KINDS, REQUIRED, MAX, TERMINATOR, RECEIVER_NAME and the method-mode counterparts) and the ordered materialisation the binder runs. Implemented for tuples of zero to eight parameters.

Returns#

A callable’s result, pushed as zero or more Lua values.

NilThen::success(value) and NilThen::failure(value) construct it. Debug on all three; Variadic is also Default.

Debug, Default, Clone, Copy. Return borrowed text from a getter with call.push(&text)? and StackResults: a Return type cannot borrow from the arguments.

Userdata#

Module l3i::userdata. A type implements Userdata for identity and script name only; how it is exposed is decided per runtime at registration. tagged::register takes the tag the host assigns in that VM (payload inline, one destructor and one metatable per tag, O(1) checks; scarce, for hot types). untagged::register uses exact metatable identity and the Storage wrapper, consuming no tag. The same Rust type may be tag 8 in one runtime, 17 in another, and untagged in a third.

NAME is the script-visible __type and the root of the type’s debug names, such as dreamweave.util.Vector3; it must be a valid debug name under the runtime’s roots and unique within a VM. Implementors promise that Drop never calls into the Lua API, never panics, and does not depend on the VM being consistent: Luau runs it while sweeping. A payload whose alignment exceeds what Luau guarantees (8 bytes, or 16 from 16 bytes up) fails to compile.

A Luau runtime userdata tag. Valid registrations use 1..TAG_LIMIT; tag 0 is Luau’s untagged default.

8, or 16 once the payload is at least 16 bytes.

The payload when value is a T of either path (one tag-to-type compare, then one metatable identity compare), or None; or the Luau-style type error naming T::NAME.

A userdata result: returning Owned(value) from a bound function moves value into a new Lua-owned instance of whichever path this VM registered T on. Pushing an Owned<T> by reference (T: Clone) clones the payload; SequenceItem too.

The same as a free function.

A pointer to an engine-owned object that Luau may observe but never owns. The host guarantees the pointee and its address stay valid whenever Lua can reach the userdata, and that it is destroyed only after Lua execution has stopped; dropping the userdata never dereferences it. Prefer Arc<T> or handle payloads wherever the engine object’s lifetime is not already this strong. Clone, Copy, Debug.

A stable borrow as a userdata value, untagged types only (tagged payloads are always owned). Pushable and returnable; pushing one for a type that is tagged in this runtime is a logic error. Clone, Copy, Debug.

Untagged userdata storage: the payload is owned by Luau or a stable borrow. repr(C).

tagged#

Module l3i::userdata::tagged. Registration order is the contract: the metatable is built and frozen first, then the destructor and metatable are published for the tag last, because Luau’s setters cannot report failure. Instances are allocated with lua_newuserdatataggedwithmetatable and initialised at once.

Registers T under tag_value in this VM with a metatable configured by configure. Registering the same T twice under the same tag is a no-op. Errors (Error::Logic): a tag outside 1..TAG_LIMIT; another type on the tag; T already on another tag; T::NAME already naming a registry metatable or not under the debug roots; a failure inside configure, which unpublishes the half-built metatable.

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

struct Bar { value: Cell<i32> }

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

fn main() -> l3i::Result<()> {
    let runtime = Runtime::new()?;
    tagged::register::<Bar>(&runtime, 20, |ty| {
        ty.method("double", |bar: &Bar| bar.value.get() * 2)?;
        ty.property_rw("value", |bar: &Bar| bar.value.get(), |bar: &Bar, value: i32| bar.value.set(value))?;
        ty.property("readonly", |bar: &Bar| bar.value.get() + 100)?;
        ty.method("add", |bar: &Bar, other: &Bar| bar.value.get() + other.value.get())
    })?;
    let make = runtime.bind_function("dreamweave.tests.bar", |value: i32| Owned(Bar { value: Cell::new(value) }))?;
    runtime.set_global("bar", &make)?;
    runtime.exec("local b = bar(13) assert(b:double() == 26) b.value = 4 assert(b.readonly == 104 and b:add(bar(1)) == 5)")?;
    Ok(())
}

untagged#

Module l3i::userdata::untagged. Each type has exactly one metatable, published under its canonical name in the registry, in a private catalogue table, and in a per-type slot keyed by the Rust type, so duplicates fail in any of them. Checks compare exact metatable identity from a per-VM cache and require the metatable to be read-only.

Registers T’s metatable configured by configure. Transactional: a duplicate in any of the three places, a type already tagged in this runtime, an empty or invalid name, or a failing configure leaves every registry entry as it was. __metatable protection is restored even if configure removed it, and the table is frozen.

MetatableBuilder#

Module l3i::userdata::metatable. Member registration is a phase machine with explicit conflict rules: methods only give a plain methods table as __index (no dispatcher); the first property getter upgrades to a generated __index (methods, then getters) plus a generated __namecall keyed by Luau atoms; the first setter installs a generated __newindex, and misses are read-only errors. Explicit __index, __newindex, __namecall and __len, native method tables and duplicate member names conflict with generated dispatch and fail at registration. Metatables are protected by default (__metatable = false), and debug names are <__type>.<member>, <__type>.get.<member>, <__type>.set.<member>. The generated dispatchers run bound members directly on their own stack instead of lua_calling the member closure, so a member call costs one Luau call frame, not two.

Configures a metatable that lives at a fixed stack index for the builder’s lifetime. Not Clone. Handed to the configure closure of tagged::register, untagged::register, ModuleBuilder::userdata and the planner.

Conflicts are Error::Logic, in the C++ binder’s words: Explicit __index conflicts with setMethod, setMethod conflicts with native method registration, receiverTypeName mismatch for <type>, A property setter must accept one Lua value argument, <type>.<name> already registered, Metatable already has an __iter metamethod.

Iterators#

Module l3i::userdata::iterator. A stateless iterator reuses the iterated object as the generic-for state; a cursor iterator gives each loop a private cursor userdata, so nested and concurrent loops over one object never share state.

The private per-loop state of a cursor iterator, as the next function receives it. Derefs to C; mutation goes through interior mutability in C. A Param whose EXPECTED is iterator cursor.

A convenience return for iterator next functions: Some((key, value)) continues, None ends the loop.

Modules#

Module l3i::module: the component registration contract. A component crate implements LuauModule; the host owns the Runtime, decides which modules exist, and calls Runtime::register_module. The result is a frozen package table the host places wherever its script environment wants it.

NAME is a dot-separated package path rooted at one of the host’s debug roots, such as dreamweave.assets.

Builds one package table. Every function it binds is named <module>.<key>.

Read-only tables#

Module l3i::readonly. Two flavours: freezing a table in place (lua_setreadonly), optionally with a shared strict metatable whose __index raises Key not found; and a read-only view, a frozen proxy whose __index is the backing table, with shared __pairs/__iter/__ipairs factories that iterate the backing table without exposing it, a __len, and __metatable = false. A view’s backing table is recorded in a VM-private weak-keyed table so a view can be recognised later.

A table from another VM is Error::Logic.

Require#

Module l3i::require: Luau’s require-by-string runtime over a host RequireNavigator. Luau resolves require("./path") by walking the navigator: reset to the requiring module, step to parents and children, ask whether a module is present, load it. Luau supplies caching, cyclic placeholders, .luaurc alias handling and the error messages scripts see.

The host’s module space, with an implicit current position maintained between reset and load.

impl_scope::Requirer is bind::Call.

Navigate and ConfigStatus are Clone, Copy, Debug, Eq.

On Runtime:

Placeholder support for cyclic requires, implemented for every Scope, for use from RequireNavigator::load: create_require_placeholder(&self), lock_require_placeholder(&self, index: c_int) and populate_require_placeholder(&self, placeholder: c_int, result: c_int).

Libraries#

Module l3i::libraries: standard-library and VM utility entry points the C++ binder never needed but Luau offers.

One of Luau’s standard libraries; Class is Luau’s experimental class library. Clone, Copy, Debug, Eq, Hash.

On Runtime:

Luau’s luaL_Strbuf: builds a string in place, spilling to a mutable Lua string when the inline buffer fills, and pushes the finished string onto the scope it was opened on. The builder keeps its spill storage on the stack below anything pushed after it; finish it before popping through it.