The sandbox and limits

A script runs with your rights, but Tilde shuts the doors that would let it touch the system. This page says what a script cannot use, how long it may run, what happens when it fails, which files require and the editor files can reach, and the [scripting] table that sets the limits.

What a script can use

The Lua state opens the base, string, table, math, coroutine and module libraries. These are not there:

io, os and debug, so a script has no files, no clock of the system, no processes and no network.
dofile, loadfile and rawset.
coroutine.create, coroutine.wrap and coroutine.resume: a coroutine would escape the limit on instructions.
package.path, package.cpath, package.searchpath and package.loadlib.

Two things are changed. print writes to the Tilde log, and string.rep refuses a result over 16 MiB (16,777,216 characters). Try both:

print(io, os, debug, dofile, loadfile, rawset)
print(pcall(function() return string.rep("x", 100000000) end))

tcli scripts

Lua: nil nil nil nil nil nil
Lua: false string.rep: a result of 100000000 characters exceeds the script string cap of 16777216 characters

There is no sleep and no wait. To run something later, use jobs and timers.

How long a script may run

Every unit of Lua work is keybind.lua, init.lua, one call of a handler, one run of a command or a key function, one run of a job and one run of a timer. Units run one at a time. Each has a budget of 10,000,000 Lua instructions. A unit that goes over is stopped, pcall cannot catch it, and the rest of the unit does not run. The stop is reported as a script_error with the message stopped after exceeding 10000000 instructions.

The budget counts instructions and not memory. Lua strings are UTF-16.

Errors

A script error never reaches the program. Tilde logs it, publishes it as the event script_error (see Events) and goes on: the other handlers, commands and jobs still run. A failure in init.lua stops the rest of that file, and what ran before it stays in place. The text of the Lua error goes to the log as it is, so error(e.subject) writes the subject there.

The scripts folder

require("lib.util") loads scripts/lib/util.lua. It reads nothing outside the scripts folder, and a symbolic link that leads out of it is refused: the module is reported as not found.
init.lua and keybind.lua may be symbolic links, as dotfile managers make them. The target must be a regular file that you own and that group and others cannot write. On Windows links are not followed. A link that does not pass is not run: the reason is logged and reported as a script_error, and for keybind.lua the built-in copy runs.
Tilde writes init.lua and keybind.lua when they are missing. Apart from them it writes only the editor files below, when you turn them on.

Help from your editor

With write_definitions = true, Tilde writes definitions.lua into the scripts folder at every load, with an entry for every module, function and event name, and writes .luarc.json when it is missing. The Lua language server then completes commands., log. and events.on(" in an editor opened on the folder. definitions.lua is rewritten each time, so do not edit it. A definitions.lua that Tilde did not write, and an existing .luarc.json, are never overwritten. A folder that cannot be written is logged, and the scripts still run.

The [scripting] table

[scripting]
enabled = true
max_instructions = 10000000
write_definitions = false

enabled = false starts no engine at all.
max_instructions is the budget of one unit.
write_definitions is off by default.

The keys of every section are in the reference of config.toml.