#Settings and storage

#Settings

Settings are declared in mod.json. The game saves them, keeps every value valid, and sends server settings to every player. Scripts read them, react when they change, and change them:

local speed = mod.settings.get("speed")

mod.settings.onChanged(function(key, value)
  if key == "speed" then speed = value end
end)

mod.settings.set("speed", 4)   -- a user setting, from a client script

mod.settings.all() returns every setting with its current value. Values always fit their declaration: a number is within min/max, a choice is one of its options, a colour is a "#rrggbb" string, and a key is a short string meant to hold a key name. A hand-edited settings file or a script cannot store anything else: mod.settings.set raises an error for a value that does not fit.

The Mods screen does not show a mod's settings, so give players a control in a panel of your own for the ones they should change, and save their choice with mod.settings.set. The radio panel of Crater Canyon does this for its music switch.

#User and server settings

A server setting is the host's choice for the whole session. A player joining a server reads the host's value, and sees every change the host makes as it happens, with onChanged called. When they leave, their own value applies again. Use server settings for rules ("rounds", "cooldown", "allow unlocking") and user settings for preferences ("show the panel", "music volume", "key").

-- server.lua: the host's cooldown applies to everyone
local cooldown = mod.settings.get("cooldown")

-- client.lua: the same value, for showing it
cooldownLabel:setText(("%d s"):format(mod.settings.get("cooldown")))

#Storage

storage keeps data between game sessions: high scores, the last position of a window, what a player has unlocked.

local best = storage.get("bestTime", 999)
if time < best then storage.set("bestTime", time) end

storage.set("window", { x = 40, y = 120, open = true })
for _, key in ipairs(storage.keys()) do log.info(key, storage.get(key)) end
storage.remove("window")

• Values may be tables, strings, numbers, booleans, vec3, quat and color. Setting nil removes a key.
• Changes are written to disk every 30 seconds, when the mod stops, and when you call storage.save().
• Client and server scripts have separate storage, and each has a 4 MB quota. storage.usage() returns the bytes used and the quota.
• Storage belongs to the mod id on this computer. It is not sent to other players and not shared between mods.

Note Storage on the server side belongs to the host's computer. A dedicated server keeps it in its own data folder. Nothing in storage reaches another player unless your script sends it.

#Replicated state

For values every player in a session must see, such as the current round or a scoreboard, use net.state instead. It lives only for the session, and players who join later receive it automatically.