Basics

Settings

Saving a plugin's settings as JSON.

config keeps a plugin's settings as JSON in the injector's config folder, in config/lua-<plugin folder>.json. config.init(defaults) gives you the settings as a table; change its fields and they are saved.

local cfg = config.init({
    enabled = true,
    range = 1200.0,
    colors = { ring = Color.hex("#4FC3F7C0") },
    favorites = {},
})

cfg.range = 900          -- saved by itself

function on_tick()
    config.save()        -- writes when something changed
end
config.init(defaults)table
The settings: the saved values over defaults. Calling it again reads the file again.
config.save()true | nil, message
Writes the settings if anything changed, at most every two seconds. Call it every tick.
config.save_now()true | nil, message
Writes the settings right away, for a "Save" button.
config.filestring
Where the settings are saved: "config/lua-<plugin>.json".

Settings are also saved after every tick and once more when the plugin stops (after on_stop), so they are never lost by forgetting config.save().

How saved values are merged

The defaults set the shape and the types of the settings:

  • A saved value is used only where the defaults have the same key with the same kind of value. A hand-edited file with a typo falls back to the default for that key.
  • Keys that aren't in the defaults are dropped. A file that isn't valid JSON gives the defaults.
  • Nested tables merge key by key. A default that's a list, or an empty table, takes the saved value whole.
  • Vec2, Vec3 and Color are saved as [x, y], [x, y, z] and "#RRGGBBAA", and come back as those types. Functions aren't saved.

So to add a setting, add it to the defaults. To rename one, rename it in the defaults; the old saved value is then forgotten.

PreviousVec2, Vec3 and Color