wolfhacklua API 1.1 Forum

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#

FromFunctions
Baseassert, 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
stringbyte, char, find, format, gmatch, gsub, len, lower, match, pack, packsize, rep, reverse, sub, unpack, upper
tableconcat, insert, move, pack, remove, sort, unpack
mathall of Lua's, plus clamp, lerp, round, sign, remap (math)
utf8char, charpattern, codepoint, codes, len, offset
coroutineclose, create, isyieldable, resume, running, status, wrap, yield
ostime, 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#

LimitEffect
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 callpattern too expensive.
string.rep and similarRefused 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 native goto.
  • unpack is available as a global for convenience, as well as table.unpack.
  • There is no bit library; use the integer operators & | ~ << >>.
  • # on a table with holes is unreliable; build lists without gaps.
API 1.1 · source docs-src/pages/learn/restricted-lua.md