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.

TypeExtra optionsWhat the player sees
toggledefaulta button that says ON or OFF
slidermin, max, step, defaulta slider
choiceoptions, defaulta button that cycles through the options
textdefaulta text box
keydefaulta button: click it, then press a key. Escape clears it
colordefaulta color picker with red, green, blue and alpha sliders and a hex box
buttononClicka 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.

A few types store their values in a particular way:

  • A color setting holds a number, like 0xFFFFFFFF, which every drawing function understands. To set one from code, pass a number, not a "#..." string.
  • A slider snaps to its step and stays between min and max.
  • A choice only takes one of its options. 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

  1. Change fields, never replace the table. storage.kills = 0 is fine. storage = {} makes a new table that Zeus never saves.
  2. 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.
  3. 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.