What this Lua has and lacks
Scripts run in Lua 5.4 with a deliberately small standard library. The full, current list of what exists is generated from the host itself (see the Lua library); this page explains the shape of it.
Available#
| From | Functions |
|---|---|
| Base | assert, collectgarbage ("count", "collect", "step" only), error, getmetatable, ipairs, load (text only), next, pairs, pcall, print (goes to the script console), rawequal, rawget, rawlen, rawset, require, select, setmetatable, tonumber, tostring, type, unpack, xpcall, _G, _VERSION |
string | byte, char, find, format, gmatch, gsub, len, lower, match, pack, packsize, rep, reverse, sub, unpack, upper |
table | concat, insert, move, pack, remove, sort, unpack |
math | all of Lua's, plus clamp, lerp, round, sign, remap (math) |
utf8 | char, charpattern, codepoint, codes, len, offset |
coroutine | close, create, isyieldable, resume, running, status, wrap, yield |
os | time, clock, date only |
On top of those the host adds its own modules: api, app, time, log, events, timer, task, store, file, json, anim, color, ui, draw, assets, data, media, theme, input, net and mem. They are the API reference.
Removed#
There is no io, no os.execute, os.remove, os.getenv or other os functions, no package, no debug, no loadfile or dofile, no string.dump, no ffi, and no way to load a DLL. load accepts source text only; compiled bytecode is refused because malformed bytecode can crash the interpreter. setmetatable cannot change the string metatable. collectgarbage("stop") and "generational" are refused.
The reasons: files go through the file module so a script can only touch its own data folder; network goes through net so the user sees which hosts it can reach; and native code would run with the overlay's full privileges, which no limit in the interpreter could contain. A manifest that asks for "native": true is refused.
Limits that look like language behaviour#
| Limit | Effect |
|---|---|
| Time per callback: 3 ms (4 ms for drawing and tabs, 400 ms for the first load) | The call is abandoned with an error and counted as a strike. Five strikes within 20 seconds stop the script. |
| Instructions per callback: 3 million (120 million at load) | Same. |
Memory: 32 MB by default (memory_mb 8 to 96) | An allocation that does not fit raises not enough memory. |
| Pattern matching: 8 million steps per call | pattern too expensive. |
string.rep and similar | Refused when the result would not fit in the memory limit. |
Lua 5.4 is a bit slower than LuaJIT would be, so write scripts to do little per frame. Performance shows how.
Differences from Lua 5.1 and LuaJIT code you may have seen#
- Integers and floats are separate subtypes;
//is integer division; there is a nativegoto. unpackis available as a global for convenience, as well astable.unpack.- There is no
bitlibrary; use the integer operators& | ~ << >>. #on a table with holes is unreliable; build lists without gaps.