SteonMod
Sign in
SteonMod docs
View as Markdown

0002: One Luau VM per addon, with a time limit instead of an instruction count

  • Date: 2026-10-02
  • Status: accepted (step 0.11)

Context

BUILD.md §3.9 asks for a Luau sandbox with a per-script memory limit and an interrupt callback that stops runaway loops, with addons loaded from a folder and hot-reloaded.

What we found in mlua 0.12.1 (feature luau):

  • Lua::set_memory_limit limits a whole VM, not one script inside it.
  • Luau has no instruction-count hook (no debug.sethook). It has an interrupt callback, which Luau calls at loop back-edges and function calls. Returning an error from it raises a Lua error at that point.
  • A Lua error can be caught by pcall, so a script could catch "out of time" and keep looping.
  • mlua gives Luau a default require that reads files from disk.
  • Lua::sandbox(true) makes the libraries and globals read-only; the script's own globals go into a private table on top.

Decision

  • Each addon (a folder with init.lua) runs in its own Luau VM, with its own memory limit (64 MB) and its own guard.
  • Time limit, not instruction count: before every call into an addon, Fusion sets a deadline (250 ms for loading init.lua, 50 ms for one event across all of that addon's hooks). The interrupt callback reads the clock every 64th call. Once the deadline passes, the guard is tripped: every later interrupt and every API call in that VM fails, so pcall can't rescue the loop.
  • An addon that runs out of time or memory is stopped: its VM is dropped (hooks and memory go with it), the player sees a plain message, and the other addons keep running. Saving the addon's files loads it again.
  • require, loadstring, getfenv and setfenv are removed before sandboxing. Multi-file addons will get a require that only sees the addon's own folder.
  • Lua never touches Godot directly: API calls queue commands (e.g. spawn a prop), which the FusionLua node turns into signals each frame. fusion-lua has no Godot types and is tested on its own.

Consequences

  • Fault isolation like a process boundary, inside one process: one broken addon can't freeze Fusion or break other addons. A test shows an endless loop wrapped in pcall is stopped within the 50 ms budget. In the playground the hitch is one frame of about 90 ms, then everything carries on.
  • Hot reload is simply dropping the VM and making a new one; nothing leaks between versions.
  • Addons don't share globals (unlike Garry's Mod, where all addons share one state). Addons that need to talk to each other will do it through Fusion: events, and later shared values. That's in line with "Lua talks to blocks only through ports, actions and events".
  • Each VM costs a little memory (a fresh Luau state is small, tens of KB). If Devices (step 4.4) create many small scripts, they can share one VM per scenario.
  • Long-running C functions (e.g. a huge string.rep) aren't interrupted mid-call; the memory limit catches the big ones. Good enough for v0.