Configuration storage
The store#
store is a small persistent key/value table for your script's settings.
local size = store.get("size", 16) -- the default is used until a value is saved
store.set("size", 20)
store.set("size", nil) -- nil deletes the keyIt stores booleans, numbers, strings and tables of those (nested is fine). Functions, tables with cycles and empty keys are refused. The store is limited to 512 KB. It is written to Documents\Base\script-data\<id>\settings.json about a second after a change and again when the script unloads, so a crash can lose the last second; store.save() writes immediately.
Controls save themselves#
Every control that takes an id reads and writes the store under that key. You rarely call store.set yourself for settings:
ui.tab("My script", function()
ui.card("Options", function()
ui.toggle("show", "Show it", true) -- store key "show"
ui.slider("size", "Size", 8, 40, 16, { int = true })
ui.color("accent", "Accent", 0x750851FF)
end)
end)
events.on("draw", function()
if not store.get("show", true) then return end -- read it anywhere
draw.text(20, 20, store.get("accent", 0x750851FF), "hello", { size = store.get("size", 16) })
end)Use the same default in the control and in store.get; the default only matters until the user first changes the control.
Pass nil as the id (ui.toggle(nil, "label", false)) for a control that should not be saved.
Reacting to a change#
The settings event fires with the key whenever a value changes, whether by a control or by store.set:
events.on("settings", function(key)
if key == "visible" then ui.widget_visible("my-widget", store.get("visible", true)) end
end)For simple drawing you do not need it: reading store.get every frame is cheap.
Files for bigger data#
For anything that is not a setting, use file: it reads and writes the script's data folder. Paths are relative to Documents\Base\script-data\<id>\; .., drive letters, device names and settings.json are refused. Limits: 4 MB per file, 16 MB and 256 files in total.
file.write("log/session.txt", "started\n")
file.append("log/session.txt", os.date("%H:%M") .. "\n")
local text = file.read("log/session.txt")
local rows = json.decode(file.read("data.json") or "[]") or {}
file.write("data.json", json.encode(rows, true))Shipped files versus saved files#
| You want | Use |
|---|---|
| Read a picture or file you ship with the script | assets.texture, assets.read (the installed folder, read only) |
| Read a file the script created earlier | file.read (the data folder) |
| Load a picture the script saved earlier | assets.texture("data:name.png") |
Changing your settings later#
Saved values outlive script updates. When you rename or change the meaning of a key, handle the old value once at load:
local old = store.get("opacity_percent")
if old then
store.set("opacity", old / 100)
store.set("opacity_percent", nil)
endRemoving a script from the Scripts page deletes its installed folder but keeps its data folder, so reinstalling it brings the settings back.