Runtime and conventions
LuaJIT 2.1 runtime, available libraries, threading, signature notation and how API arguments are converted.
Scripts use LuaJIT 2.1, which implements Lua 5.1 with LuaJIT extensions, including 64-bit literals such as 1ULL and -1LL.
All standard libraries are available, including io, os, debug and package. LuaJIT modules are available through require, including bit, jit, ffi and string.buffer. ffi is not a global.
Security: scripts are not sandboxed. They have access to the filesystem, native libraries and the game process. Run only trusted scripts.
Each script has a separate Lua state. All API callbacks execute on the game's main thread, not on the render or input thread.
Signature notation
arg?denotes an optional argument.- Multiple return values are separated by commas. For example,
nil, reasonreturns two values. integerdenotes a whole numeric value unless a cdata type is specified.vector,vector2d,vector4d,angleandcolorare FFI value types, the only value types.- Object methods use
:unless documented otherwise. Namespaces use..
Argument conversion
Unless an API entry specifies stricter validation, bound functions use these conversions:
| Parameter | Accepted values |
|---|---|
| String | A string or a number converted to text. Other types raise stack index N, expected string, received <type>. |
| Number | A number, rounded where an integer is required. Other types are read as 0. |
| Vector | The matching FFI value (vector, vector2d or vector4d), a pointer to it (vector*), a reference such as an element of a vector[n] array, or a table with named ({x=, y=, z=}) or positional ({1, 2, 3}) components. Anything else raises expected vector, vector* or {x, y, z} (or the vector2d / vector4d analogue); functions implemented directly in C raise vector, vector* or {x, y, z} expected. |
| Angle | As for vectors; tables may also use pitch, yaw and roll. |
| Colour | color, a pointer or reference to it, or a table with named ({r=, g=, b=, a=}) or positional channels. Missing alpha defaults to 255; channels are clamped to 0..255. |
| 64-bit mask | A non-negative whole number below 2^64, or int64_t / uint64_t cdata. Signed cdata is interpreted by its bit pattern, so -1LL sets all bits. |
These conversions apply to API parameters, not necessarily to constructors. In particular, color({255, 0, 0}) has alpha 0, while color(255, 0, 0) has alpha 255.
Get started
Reference for Lua scripts loaded through Scripts > Library: runtime, lifecycle, callbacks, namespaces, objects and script UI.
Script lifecycle
Script directories, the require search path, metadata tags, Library actions, load and unload order, error handling and what the configuration persists.