Basic Usage

Here's a concise Basic Usage section suitable for the beginning of the LibSavedVars documentation. It introduces the common workflow without getting into migration, versioning, or advanced features.

Before diving into advanced features, most addons only need the following pattern.

Basic Usage

LibSavedVars provides a consistent way to create and manage your addon's saved variables. In most cases, you only need to perform three steps:

1. Create your saved variables.

2. Read and modify settings during gameplay.

3. Allow LibSavedVars to automatically save your changes when the player logs out or reloads the UI.

Creating Saved Variables

Begin by defining a table containing your default settings.

local defaults = {
    window = {
        x = 100,
        y = 100,
    },
    enabled = true,
    opacity = 1.0,
}

Next, create the saved variables object.

local LSV = LibSavedVars
local settings = LSV:NewAccountWide(
"MyAddonSavedVariables",
1,
nil,
defaults
)

The parameters are:

Parameter	Description
Saved variable name	The name stored in the SavedVariables folder.
Version	The current data version for your addon.
Namespace	Optional subtable used to separate data. Pass nil if unused.
Defaults	A table containing the default settings.

For character-specific settings, use:

local settings = LSV:NewCharacterSettings(
    "MyAddonSavedVariables",
    1,
    nil,
    defaults
)

Reading Settings

Saved variables behave like normal Lua tables.

if settings.enabled then
    DoSomething()
end
local x = settings.window.x

Changing Settings

Simply assign new values.

settings.enabled = false
settings.opacity = 0.75
settings.window.x = 250

There is no need to manually save the data. LibSavedVars automatically writes the changes when ESO saves your addon's SavedVariables.

Using Defaults

If a setting has never been stored, LibSavedVars returns the value from your defaults table.

For example:

local defaults = {
    volume = 100
}

If the player has never changed the setting,

d(settings.volume)

prints:

100

Once the player changes the value,

settings.volume = 60

future reads return:

60

Complete Example

local defaults = {
    enabled = true,
    scale = 1.0,
}
local settings = LibSavedVars:NewAccountWide(
"MyAddonSavedVariables",
1,
nil,
defaults
)
if settings.enabled then
settings.scale = settings.scale + 0.1
end

This is all that is required for a typical addon. More advanced capabilities—such as migrations, version upgrades, account/character switching, and data cleanup—are covered in later sections.

This section intentionally stays focused on the 90% use case. It provides a foundation before introducing topics like versioning, migrations, LSV_Data, account-wide/character toggles, defaults trimming, and other advanced LibSavedVars features.