Basic Usage

Basic Usage

LibSavedVars provides a simple interface for creating and managing your addon's saved variables. In most cases, an addon only needs to:

1. Define default settings.
2. Create a saved variables object.
3. Read and modify settings during gameplay.

LibSavedVars handles loading and saving the data automatically through ESO's saved variable system.

---

Creating Saved Variables

Begin by defining a table containing your default settings.

local defaults = {
    enabled = true,
    scale = 1.0,

    window = {
        x = 100,
        y = 100,
    },
}

The defaults table defines the initial values used when a setting has not been saved yet.

Create an account-wide saved variables object:

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

The parameters are:

Parameter	Type	Description
savedVariableName	string	Name of the ESO SavedVariables table.
version	number	Current version of the saved data.
namespace	string/nil	Optional namespace for organizing data.
defaults	table	Default values for the settings.

---

Character Settings

If settings should be unique for each character, create character-specific saved variables instead:

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

Character settings are stored separately for each character while account-wide settings are shared across the account.

---

Reading Settings

Saved variables behave like normal Lua tables.

Example:

if settings.enabled then
    EnableFeature()
end

Nested settings can be accessed normally:

local x = settings.window.x
local y = settings.window.y

If a value has never been saved, LibSavedVars automatically returns the value from the defaults table.

---

Changing Settings

Settings can be modified using normal Lua assignment.

settings.enabled = false
settings.scale = 1.25

settings.window.x = 250
settings.window.y = 150

There is no need to manually save the data. ESO automatically saves the SavedVariables when appropriate.

---

Complete Example

A simple addon settings setup:

local defaults = {
    enabled = true,
    scale = 1.0,
}

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

if settings.enabled then
    settings.scale = 1.1
end

The addon can now use settings throughout its code.

---

Adding New Settings

As an addon grows, new settings can be added by updating the defaults table.

Version 1:

local defaults = {
    enabled = true,
}

Version 2:

local defaults = {
    enabled = true,
    showTooltips = true,
}

Existing users automatically receive the new default value.

A migration is only required if existing saved data must be changed.

---

Recommended Pattern

For most addons:

1. Create saved variables once during addon initialization.
2. Store the returned object in a local variable.
3. Use that object throughout the addon.
4. Let LibSavedVars handle persistence.

Example:

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

-- Use settings everywhere
settings.enabled = true

---

Next Steps

Basic usage is enough for most addons. As your addon grows, additional features may become useful:

• Account-wide vs. Character Settings — choosing where data is stored.
• Defaults — managing initial values.
• Defaults Trimming — reducing SavedVariables file size.
• Versioning — tracking saved data changes.
• Migration — upgrading existing user data.
• LSV_Data — managing both account and character settings together.
• Advanced Topics — additional management features.