Skip to content

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.

Your script sees
  • mod: the whole API
  • math string table utf8 bit32 buffer, as frozen copies
  • require of your own files
  • print and warn, which go to the log
It does not
  • os io debug coroutine loadstring getfenv _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.

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.

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.

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.

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 .luauc files 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.