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 runsBudget
loading main.lua100 million steps
every event, timer, command or button click25 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:

LibraryWhat you get
basicsprint, pairs, ipairs, type, tostring, tonumber, pcall, error, select, setmetatable and the rest
stringeverything except string.dump, string.pack and string.unpack
tableeverything
matheverything
utf8everything
coroutineeverything
osos.time, os.date, os.clock, os.difftime
debugdebug.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.execute and os.exit do not exist. Use storage to save data and mod.read to read files from your mod.
  • load only takes Lua text, not compiled chunks.
  • Weak tables (__mode) and __gc are ignored.
  • os.clock counts real seconds since your mod loaded, not CPU time.
  • string.upper and string.lower only change the letters A to Z.