Get started

How mods run

Where mods run, when they load, how errors are handled, the limits every mod has, and which parts of Lua you can use.

Publicidad

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.

Where mods run

Mods run everywhere: on the title screen, in menus, in your singleplayer worlds, in LAN worlds and on servers. They stay loaded when you join or leave a world.

Your mod can tell where it is. world_join gives you e.singleplayer and e.server, and game.isSingleplayer() and game.server() work any time.

On a server

On a server, only your own game runs your mod. Other players do not see what it draws, and the server does not know it is there.

  • chat.send and chat.command reach the server like chat you typed.
  • The player functions act like your own keys and mouse.
  • Servers have their own rules about client mods. Follow them.

Blocks, items and mobs

The blocks, items and mobs a mod adds are different: they only work in your own worlds, meaning singleplayer and LAN worlds you open. See Blocks, items and mobs.

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, and after Save & reload in the editor.

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. It also cancels unfinished web requests, stops your sounds, turns off the microphone and hangs up voice connections. 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.