Build a mod
Settings and storage
Give players settings they can change, save your own data between sessions, and use files, JSON, the clipboard and the internet.
Most mods need to remember things. Some of it is chosen by the player, like a color or a key. Some of it is your own data, like a kill count or a list of waypoints. Zeus has a tool for each: settings for the first, storage for the second.
Settings
Settings are options the player can change. You describe them in code, and Zeus builds the page for you under Mods, your mod, then Settings. It also saves them for you.
settings.toggle("enabled", { label = "Enabled", default = true, description = "Turn the HUD on or off" })
settings.slider("size", { label = "Size", min = 1, max = 4, step = 0.5, default = 2 })
settings.choice("corner", { label = "Corner", options = { "left", "right" }, default = "left" })
settings.text("prefix", { label = "Prefix", default = ">" })
settings.key("zoomKey", { label = "Zoom key", default = "c" })
settings.color("textColor", { label = "Text color", default = "#FFFFFF" })
settings.button("resetStats", { label = "Reset stats", onClick = function() storage.kills = 0 end })
The first argument is the setting's key, the name you use in code. Every type takes a label, which players see, and a description, which shows as a tooltip.
| Type | Extra options | What the player sees |
|---|---|---|
toggle | default | a button that says ON or OFF |
slider | min, max, step, default | a slider |
choice | options, default | a button that cycles through the options |
text | default | a text box |
key | default | a button: click it, then press a key. Escape clears it |
color | default | a color picker with red, green, blue and alpha sliders and a hex box |
button | onClick | a button that runs onClick |
Each setting function also gives you back the setting's current value.
Read and change settings
Read a setting like a normal field, and assign it to change it.
hud.add(function(ctx)
if settings.enabled then
ctx:text("Hi", 4, 4, settings.textColor)
end
end)
settings.size = 3
settings.get("enabled") and settings.set("size", 3) do the same thing. settings.reset("size") puts one back to its default, settings.all() gives you every value in a table and settings.open() opens your settings page.
Never name a setting after a settings function: toggle, slider, choice, text, key, color, button, get, set, reset, all, onChange or open. settings.color is the function that makes color settings, so a setting called color can only be read with settings.get("color"). Names like textColor avoid the problem.
A few types store their values in a particular way:
- A
colorsetting holds a number, like0xFFFFFFFF, which every drawing function understands. To set one from code, pass a number, not a"#..."string. - A
slidersnaps to itsstepand stays betweenminandmax. - A
choiceonly takes one of itsoptions. Anything else puts it back to the default.
React to changes
settings.onChange(function(key, value, old)
chat.print(key .. " changed from " .. tostring(old) .. " to " .. tostring(value))
end)
The setting_changed event gets the same three values. Both fire whenever a value really changes, whether the player changed it or your code did.
The Settings button in the Mods menu only works while your mod is running and has at least one setting.
Storage
storage is a table that Zeus saves for you. Put numbers, text, true and false, and tables of those in it, and they are still there the next time the game starts.
on("tick", function()
storage.ticksPlayed = (storage.ticksPlayed or 0) + 1
end)
Always give a default with or like that. The first time your mod runs, storage is empty.
When it saves
Zeus saves storage (and your settings) every 15 seconds while your mod runs, and whenever your mod unloads. It does not save when the player closes the tab. Call mod.save() right after anything important changes, so it is saved for sure.
Three rules
- Change fields, never replace the table.
storage.kills = 0is fine.storage = {}makes a new table that Zeus never saves. - Only save plain data. Functions, textures and other game objects cannot be saved. If one ends up in
storage, nothing gets saved and your Log says why. - Lists should be real lists. A table with keys 1, 2, 3 and so on comes back the same. Number keys with gaps, like
{ [100] = "x" }, come back as text keys ("100").
Example: a death counter
-- name: Death Counter
-- version: 1.0.0
on("screen_open", function(e)
if e.screen == "death" then
storage.deaths = (storage.deaths or 0) + 1
mod.save()
end
end)
hud.add("deaths", function(ctx)
ctx:text("Deaths: " .. (storage.deaths or 0), 4, 4, "red")
end)
It counts a death every time the death screen opens, and saves right away.
Files in your mod
A packaged mod can carry extra files, like JSON data or text. mod.read(path) returns a file's contents, or nil if it is not there. mod.exists(path) checks for a file, and mod.files(prefix) lists every file whose path starts with prefix.
local names = json.decode(mod.read("data/names.json"))
for _, path in ipairs(mod.files("data/")) do
print(path)
end
JSON
json.encode(value, pretty) turns a table into JSON text. Pass true for pretty to get it spread over lines. json.decode(text) turns JSON text back into a table, and it is forgiving: comments and trailing commas are fine.
json.null stands for a JSON null. Check for it with value == json.null.
The clipboard
clipboard.set(text) copies text. Reading the clipboard is more sensitive, so clipboard.get() needs the clipboard permission (see Packaging). It returns "" if the browser says no.
clipboard.set("Copied from my mod")
local text = clipboard.get()
The internet
http.get downloads a URL. It needs the network permission.
http.get("https://example.com/data.json", function(body, err)
if not body then
print("Request failed: " .. err)
return
end
local data = json.decode(body)
end)
The download happens in the background, and your function runs when it is done: with the body if it worked, or with nil and an error message if it did not.
- It can only make GET requests. There are no custom headers, and you do not get the status code.
- The server has to allow requests from other websites (CORS), or the browser blocks it.
- Any error status, like 404, counts as a failure.



