Lua Scripting
Overview
TinyMUX 2.14 embeds Lua 5.4 as an optional scripting language. Lua scripts run in a sandboxed environment and can interact with MUX data through a bridge API. Lua support is optional and enabled at build time.
Sandboxed Execution
Each Lua invocation runs in a restricted sandbox. The sandbox removes access to dangerous Lua standard library functions (file I/O, process execution, module loading) while retaining safe operations like string manipulation, math, and table handling. This prevents Lua scripts from affecting the host system outside the MUX engine.
Lua source is compiled to bytecode on first use. The bytecode is cached so that subsequent invocations skip the parsing and compilation steps.
The mux.* Bridge API
Lua scripts access MUX game data through the mux.* namespace. This bridge API provides functions for reading and writing attributes, querying object properties, and invoking softcode functions from Lua. The bridge ensures that all access respects the same permission model as normal softcode evaluation.
Commands and Functions
@lua
@lua <lua-code>
Executes <lua-code> as a Lua script. The script runs in the context of the enacting object. Output from print() calls and return values are sent to the enactor.
lua()
lua(<lua-code>)
A softcode function that executes <lua-code> and returns the result as a string to the calling softcode expression. This allows Lua to be embedded inline within softcode.
luacall()
luacall(<object>/<attribute>, <arg1>, <arg2>, ...)
Calls a Lua script stored in an attribute on <object>. The arguments are passed to the Lua script as string parameters. This is useful for invoking reusable Lua routines stored on code objects.
JIT Compilation
Lua bytecode is also compiled through the TinyMUX JIT pipeline. All 83 Lua 5.4 opcodes are supported by the JIT backend. When JIT compilation is enabled, Lua scripts benefit from the same optimization passes applied to native softcode: constant folding, peephole optimization, superblock merging, and native code generation via dynamic binary translation.
Infinite Loop Protection
To prevent runaway scripts, the Lua sandbox enforces a back-edge iteration budget. Each backward branch (loop iteration) decrements a counter. When the budget is exhausted, execution is terminated and an error is returned. This prevents infinite loops from stalling the server without requiring a wall-clock timeout.