The sandbox
A mod’s Luau runs in a sandbox: a fresh environment with the standard libraries, your own files, and the mod table. Nothing else.
mod: the whole APImathstringtableutf8bit32buffer, as frozen copiesrequireof your own filesprintandwarn, which go to the log
osiodebugcoroutineloadstringgetfenv_G- the engine and the game’s modules
- other mods’ files and variables
- the file system and the network
The full list, read from the sandbox code: Sandbox globals.
Random numbers
Section titled “Random numbers”math.random is not there. Use mod.rng(seed): it gives the same numbers on every machine for the same seed, so the server and clients agree. See random.
Talking to other mods
Section titled “Talking to other mods”Mods cannot read each other’s variables. A mod can offer functions on purpose: it puts them in mod.exports, and a mod that loads after it calls mod.use("its_id") to get them. See identity.
Time limits
Section titled “Time limits”The game runs mod code inside its own frame. To keep a broken mod from ruining the game, it switches off code that misbehaves and says so in the log:
| Code | Switched off after |
|---|---|
| An event handler | 5 errors, or 3 calls over 4 ms |
A UI draw or visible callback |
3 errors, or over 3 ms for 30 frames in a row |
| A timer, a plan hook | no limit: keep them short |
Only that handler stops. The rest of your mod keeps running.
What the sandbox does not cover
Section titled “What the sandbox does not cover”Be clear with your players about these:
- CPU and memory. Luau cannot stop a loop that never ends or a table that grows forever. A mod can freeze the game.
- Bytecode. Luau does not check compiled bytecode, and crafted bytecode can escape any sandbox. The game only takes binary code from
.luaucfiles and packs built with--bytecode. Install those only from people you trust. "overrides": true. A mod with this flag can replace any of the game’s own files, and a replaced Luau file runs with full access. The MODS page marks such mods. This is also what breaks first when the game updates.- Shared data. Two mods that change the same field both run; the later one wins and the log reports the conflict. See Load order.