wolfhacklua API 1.1 Forum

Configuration storage

The store#

store is a small persistent key/value table for your script's settings.

lua
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 key

It 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:

lua
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:

lua
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.

lua
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 wantUse
Read a picture or file you ship with the scriptassets.texture, assets.read (the installed folder, read only)
Read a file the script created earlierfile.read (the data folder)
Load a picture the script saved earlierassets.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:

lua
local old = store.get("opacity_percent")
if old then
  store.set("opacity", old / 100)
  store.set("opacity_percent", nil)
end

Removing a script from the Scripts page deletes its installed folder but keeps its data folder, so reinstalling it brings the settings back.

API 1.1 · source docs-src/pages/guide/storage.md