Get started
How mods run
When mods load and pause, how errors are handled, the limits every mod has, and which parts of Lua you can use.
Read this page once before you build anything big. It covers the rules every mod follows, and most "why is my mod doing that" questions are answered here.
Singleplayer only
Mods run on the title screen, in menus and in your singleplayer worlds. They pause when:
- you join a server (from the moment you start connecting)
- you join someone else's LAN world
- you open your own world to LAN
This keeps mods from being used as cheat clients on servers. Every player on a server is on the same rules, mods or not.
What pausing does
When mods pause, every mod gets its unload event, its settings and storage are saved, and everything it added to the game is taken away. The Mods menu shows each one as Paused (singleplayer only).
You can still install, edit, turn on and off, delete, export and share mods while they are paused. Settings stays greyed out until mods run again.
When mods come back
After a server, mods come back as soon as you are on the title screen, the server list or the world list again. After LAN, they come back when LAN closes or you leave the world.
Coming back is a fresh start. Every mod runs its main.lua again from the top.
How a mod loads
Your mod's main.lua runs once, from top to bottom, when the mod loads. That is where you register everything: events, HUD panels, commands, keybinds and settings. After that, your code only runs when the game calls one of your functions.
-- runs once, when the mod loads
local count = 0
-- runs every tick, forever
on("tick", function()
count = count + 1
end)
Mods load when the game starts, when you turn one on, when you click Reload, after Save & reload in the editor, and when mods come back after a pause.
Each mod has its own Lua world. A global variable in one mod is invisible to every other mod, so two mods can both have a count without clashing. To share on purpose, use mod.export.
Mods load in the order of the Mods list, with any mods they depend on first. Use Move up to change the order. When several mods listen to the same event, they hear it in that order too.
If you are already in a world
The world_join event only fires when you join a world. If your mod loads while you are already in one (you turned it on, or clicked Save & reload), it never sees that event. Check for a world when your mod starts:
local function onJoin()
chat.print("Hello, " .. player.name())
end
on("world_join", onJoin)
if player.exists() then
onJoin()
end
Reloading cleans up after you
When your mod unloads, Zeus removes everything it added: events, timers, HUD changes, commands, keybinds, buttons it put on screens, textures and WebGL objects. You do not have to undo anything yourself.
If you need to do something right before that happens, like saving one last value, listen for unload.
on("unload", function()
storage.lastSeen = os.time()
end)
When your code has an error
Errors are normal, and they do not crash the game.
When a function in your mod throws an error, Zeus writes it to your mod's Log with the line it happened on, skips the rest of that call and keeps your mod running.
If your mod hits 30 errors within a minute, Zeus stops it. This catches the common case of a broken HUD function that fails 60 times a second. You see a popup that says your mod stopped, and its status in the Mods menu becomes Error with the reason.
If the error happens while main.lua is loading, the mod does not start at all. Its status says Error, and the Log starts with "Failed to load".
Your mod has a time budget
The game cannot wait forever for a mod, so every call into your mod gets a budget. One step is one function call or one pass through a loop.
| What runs | Budget |
|---|---|
loading main.lua | 100 million steps |
| every event, timer, command or button click | 25 million steps |
That is far more than any normal mod needs. You only hit it with an endless loop, or a huge job done all at once. When a mod runs out, Zeus stops it with "script took too long". pcall cannot catch this.
If you really have a lot of work to do, split it up and do a little every tick.
When a mod is stopped
A stopped mod keeps its settings and storage (both are saved first), but its unload event does not run. It stays turned on, so it starts again when you:
- fix the code and click Save & reload
- click Reload, or Reload all
- turn it off and on again
- open the game again next time
Saving
Settings and storage are saved every 15 seconds while your mod runs, and whenever it unloads. They are not saved when the player closes the tab, so up to 15 seconds of changes can be lost. After something important changes, call mod.save() to save right away. Settings and storage has the details.
What Lua can do
Zeus runs Lua 5.4. You get the parts of the standard library that make sense in a game:
| Library | What you get |
|---|---|
| basics | print, pairs, ipairs, type, tostring, tonumber, pcall, error, select, setmetatable and the rest |
string | everything except string.dump, string.pack and string.unpack |
table | everything |
math | everything |
utf8 | everything |
coroutine | everything |
os | os.time, os.date, os.clock, os.difftime |
debug | debug.traceback and debug.getinfo |
print and log both write to your mod's Log. require loads other Lua files from your mod (see Packaging). goto, <const> and <close> all work.
What is missing:
- No files or programs:
io,dofile,loadfile,os.executeandos.exitdo not exist. Usestorageto save data andmod.readto read files from your mod. loadonly takes Lua text, not compiled chunks.- Weak tables (
__mode) and__gcare ignored. os.clockcounts real seconds since your mod loaded, not CPU time.string.upperandstring.loweronly change the letters A to Z.



