Rust API

[dependencies]
l3i = "1"

The crate is l3i. Its modules are public and are reached by their module path (l3i::runtime::Runtime, l3i::userdata::tagged::register); only the items below are also at the root.

The default feature set is empty. Networking is not a feature: dream-net is a dependency and every runtime plan carries the dream.net bridge.

The root#

Re-exported from their modules:

Error, Result          error
Runtime                runtime

Declared at the root:

pub mod ffi                          the raw Luau C API (raw::ffi, re-exported)
pub const TAG_LIMIT: u8              254: valid userdata tags are 1..TAG_LIMIT
pub const LUAU_VERSION: &str         "0.740"
pub const VERIFIED_TOOLCHAIN: bool   whether build.rs found the verified toolchain

Result<T> is std::result::Result<T, l3i::Error> and is what every fallible function in the crate returns. The raw C API covers ffi and the two VM constants; Building covers VERIFIED_TOOLCHAIN.

Conventions#

• Errors. A function returns Err for a host logic error (Error::Logic: misuse of the API, a registration conflict, a value from another VM) or for a Lua error that a protected call caught (Error::Runtime). Inside a bound function nothing raises on its own: returning Err from the callable, or a Result<T> whose Err the binder pushes, raises the message as the Lua error the script sees. Error::LuaErrorOnStack re-raises the error object already on top instead of replacing it with a message. Error::Permission is a capability the runtime policy did not grant, kept apart from Runtime so a denial never reads as an operating-system failure. Host-level calls that could raise (a __index metamethod, a store into a read-only table) run under lua_pcall and come back as Err; the same call inside a native call raises straight through to Luau’s pcall.
• Frames. Stack is the exclusive handle to a thread’s stack and never pops. Temporaries go through a Frame, and every view a frame returns borrows the frame. A scope has at most one open child frame: opening a sibling panics at its opening line. Inside a bound function read the arguments before opening a frame, or open the frame from the Call. Runtime::stack leases the root stack; a second root while one is alive and not suspended in a Lua call panics. Helpers that take &Runtime lease the root themselves, so call them between root stacks.
• Receivers are &T. A userdata can appear in several argument slots of one call, so no method receives &mut T. Mutation goes through interior mutability in the payload; tagged::test_mut is the unsafe escape hatch. Bound callables are Fn, not FnMut, for the same reason: a binding can re-enter itself through Lua.
• Result<T> from a bound function raises. Ok(value) pushes value’s results; Err raises the message with the caller’s location, in luaL_error wording where the C++ binder had it (invalid argument #2 to 'name' (number expected, got string)).
• Integers. Luau 0.740 integers (42i) compare with == only; < between two integers raises, and an integer never equals a number. l3i pushes identities (peer, event, channel and client ids, hashes, handles, packed scalars) as Luau integers through convert::Integer, Bits64 and Packed<T>, and everything scripts threshold or count (sizes, lengths, counters) as plain numbers: i64, u64 and the other Rust integers push numbers. Reading a plain Rust integer from a Lua number rounds half away from zero (OpenMW’s rule); convert::Exact<T> refuses a fractional or out-of-range value.
• Time. Watchdog and profiler times are std::time::Duration on the way in and milliseconds as f64 in the statistics. The network bridge’s transport clock is f64 seconds, monotonic, read from the plan’s clock or the host’s network_clock, never from a script. Runtime::clock is Luau’s own high-resolution clock in seconds.
• Names are host data. Every native function and userdata type is named under one of the runtime’s debug roots (dreamweave by default); tags, atoms and packed kinds are chosen by the host or the planner, never by the crate.