script-engine summary
← Back to docs · Architecture · Decisions · Previous: Prim meshing · Next: OSSL API
Status: accepted (all tracked tasks checked in openspec/changes/script-engine/tasks.md).
Commits cdb1913 through b57c2db. Second review verdict: CONDITIONAL PASS.
Tests: 601 in welkin-script-vm.
What was built
Scripts run on Luau through mlua 0.12 (luau feature, upstream Luau 740), one
VM per script. LSL reaches the VM by transpiling to Luau (see go/no-go below).
All code lives in crates/welkin-script-vm; welkin-script-api (1,894 lines)
and welkin-script-compiler (5,295 lines) are implemented.
Spike (cdb1913, 3fb1cbd, d413580)
- VM spike: compile, load, run and yield from Rust (8 tests).
- State serialization:
ScriptStateholds bytecode plus globals as JSON and round-trips into a second VM. Luau cannot snapshot a coroutine stack, so scripts persist through a checkpoint pattern (state lives in globals, the event handler is restarted). - Memory limits and pre-emption:
new_vm_with_memory_limituses the allocator hook; an interrupt callback (VmState) stops runaway scripts. - LSL corpus analysis (
docs/lsl-corpus-analysis.md): 18 scripts from OAR files, 10 unique, with a feature inventory and transpiler complexity breakdown. - YEngine comparison: the 4-stage CIL pipeline analysed against the Luau
approach (
docs/script-engine-spike-results.md). - Go/no-go: GO. Caveats: an LSL-to-Luau transpiler is needed, persistence is checkpoint based, about 400 host functions need implementing.
- Luau marking on upload: neither OpenSim 0.9.3 nor the Aurora crates have Luau support; language detection would be server-side at compile time.
VM crate (6efdaef)
ScriptInstance: one Luau VM, bounded memory, event queue and dispatch.ScriptScheduler: round-robin with an instruction limit per slice, timer heap,post_eventandbroadcast_event.RegionTransferBundle: serialises scheduler scripts to bytes and applies them in another scheduler, for region crossing.
Script API (5357247, 60241c6, a5539f5, ee60389)
- Generated function tables, constants, events and the
LslType/LslValuetype system (100+ functions, 120+ constants, 35 events). - 82
ll*functions over a sharedScriptContext(Arc<RwLock>): 49 implemented, 33 stubs. Areas: math, string, list, object, physics, communication (builtins/). - 27
os*functions (ossl.rs) gated byOsslThreatLevel: None, Nuisance, VeryLow, Low, Moderate, High, VeryHigh, Severe.OsslConfigsets the maximum allowed level and a per-function allow override. - Events and detected parameters (
events.rs): 16llDetected*functions,DetectedInfo,EventContext,dispatch_event.
Proof tests (3d0e331)
- 32 tests ported from the C#
LSL_TypesandLSL_Apisuites (math, string, list, constants, conversions, compile API). - 5 tests: vehicle script state survives a cross-region transfer.
- 6 tests: a Luau script and an LSL script in one object exchange link messages, including broadcast and survival across transfer.
Security review (dd1177d)
docs/security-review-script-sandboxing.md. CONDITIONAL PASS: 0 CRITICAL,
2 HIGH.
- H1:
ScriptInstancenever callssandbox(true)after registering functions (newandrestore_from), so globals are not frozen. - H2: the event queue is unbounded. Needs a cap (C# uses 300 per script).
- MEDIUM:
restore_script_statereturns an unsandboxed VM; transfer bytecode has no version check; transfer bundle size andglobals_jsonsize are uncapped, and the memory limit is applied after globals are injected.
Strengths: one VM per script, no io/os/debug, no network or file
functions registered.
Known gaps
- 206 ll* functions are registered and functional. About 104 SL-spec ll* functions are not yet bound (some permissions, land and sensor operations).
- 236 os* functions are registered; about 17 still return stub defaults where the backing service is not yet wired. 20 NPC and 19 terrain functions have real implementations.
- The LSL-to-Luau compiler (
welkin-script-compiler) compiles 68% of real-world scripts. 32% fail on unsupported syntax or missing builtins. - A coroutine stack cannot be serialised; mid-event state is lost on transfer unless the script uses the checkpoint pattern.
- Both HIGH findings must be fixed before production use.
- YEngine script state cannot be read; scripts restart once at migration.