Skip to content

Public API Reference

Jump to bottom
Shadowfen edited this page Jul 29, 2026 · 5 revisions

This section documents the public API provided by LibSavedVars. The public API is the supported interface addon developers should use when creating, accessing, and managing saved variables.

Internal implementation functions and classes are not covered here and may change between library versions.

API Overview

LibSavedVars provides APIs for:

  • Creating account-wide saved variables.
  • Creating character-specific saved variables.
  • Managing defaults.
  • Handling version upgrades and migrations.
  • Switching between account-wide and character settings.
  • Pinning selected settings to account-wide storage.
  • Accessing raw saved variable data.
  • Iterating over active settings.

Creating Saved Variables

LibSavedVars:NewAccountWide()

Creates an account-wide saved variables object.

Syntax

local settings = LibSavedVars:NewAccountWide(
    savedVariableName,
    version,
    namespace,
    defaults
)

Parameters

Parameter Type Description
savedVariableName string ESO SavedVariables table name.
version number Current saved data version.
namespace string/nil Optional namespace within the saved variables table.
defaults table Default settings values.

Returns

A saved variables object.

Example

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

LibSavedVars:NewCharacterSettings()

Creates character-specific saved variables.

Syntax

local settings = LibSavedVars:NewCharacterSettings(
    savedVariableName,
    version,
    namespace,
    defaults
)

Parameters

Same as NewAccountWide().

Returns

A character-specific saved variables object.

Example

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

Accessing Settings

Saved variables returned by LibSavedVars behave like normal Lua tables.

Reading Values

local enabled = settings.enabled

If the value has not been saved, LibSavedVars returns the value from the defaults table.

Writing Values

settings.enabled = false

Values are automatically persisted by ESO during normal saved variable processing.

Nested Values

Nested tables can be accessed directly.

settings.window.position.x = 200

Defaults Management

:EnableDefaultsTrimming()

Enables automatic removal of saved values that match defaults.

Syntax

settings:EnableDefaultsTrimming()

Description

When enabled, values equal to their default values are removed before saving. These values are restored automatically from the defaults table when the addon loads.

Example

settings:EnableDefaultsTrimming()

Versioning and Migration

:Migrate()

Registers a migration callback for a specific version.

Syntax

settings:Migrate(version, callback)

Parameters

Parameter Type Description
version number Version produced by this migration.
callback function Function that updates saved data.

Example

settings:Migrate(2, function(savedVars)

    savedVars.newSetting = savedVars.oldSetting
    savedVars.oldSetting = nil

end)

Notes

  • Migrations run only when the stored version is lower than the migration version.
  • Multiple migrations execute in ascending version order.
  • Migration functions should update only the data required for their version.

LSV_Data API

LSV_Data provides advanced management for addons that support both account-wide and character-specific settings.

:GetActiveSavedVars()

Returns the currently active settings table.

Syntax

local settings = data:GetActiveSavedVars()

Returns

Type Description
table Active settings table.

:SetAccountSavedVarsActive()

Selects whether account-wide settings are active.

Syntax

data:SetAccountSavedVarsActive(accountActive)

Parameters

Parameter Type Description
accountActive boolean true for account-wide settings, false for character settings.

Example

data:SetAccountSavedVarsActive(true)

:GetAccountSavedVarsActive()

Returns the current storage mode.

Syntax

local accountActive = data:GetAccountSavedVarsActive()

Returns

Type Description
boolean true if account-wide settings are active.

:AddAccountWideToggle()

Pins a setting key to account-wide storage.

Syntax

data:AddAccountWideToggle(key)

Parameters

Parameter Type Description
key string Setting key to store account-wide.

Example

data:AddAccountWideToggle("window")

Description

Pinned keys remain stored in account-wide settings even when character settings are active.

:AddCharacterSettingsToggle()

Marks a setting as character-specific.

Syntax

data:AddCharacterSettingsToggle(key)

Parameters

Parameter Type Description
key string Setting key to store per character.

:GetIterator()

Returns an iterator over the active settings.

Syntax

for key, value in data:GetIterator() do
    -- process setting
end

Description

Provides a merged view of active settings, including pinned account-wide keys.

Raw Data Access

:GetRawDataTable()

Returns the underlying stored data table.

Syntax

local rawData = settings:GetRawDataTable()

Description

Unlike normal settings access, this returns only values actually stored in SavedVariables.

Useful for:

  • Debugging.
  • Writing migrations.
  • Inspecting saved data.
  • Exporting settings.

Migration Utility API

LibSavedVars provides helper functions for common saved data operations.

Common operations include:

  • Creating missing table paths.
  • Moving values.
  • Copying values.
  • Removing obsolete settings.
  • Migrating between account-wide and character storage.

These utilities are intended for use inside migration callbacks.

Example:

settings:Migrate(3, function(savedVars)

    -- migration operations

end)

Lifecycle Guidelines

LibSavedVars performs saved variable management during addon initialization and ESO save events.

Addon authors should:

  • Create saved variables during initialization.
  • Register migrations immediately after creation.
  • Avoid manually modifying the underlying SavedVariables tables.
  • Allow LibSavedVars to manage persistence.

API Stability

The functions documented in this section are considered the supported public API.

Developers should avoid depending on:

  • Internal tables.
  • Private fields.
  • Undocumented helper functions.
  • Internal class implementation details.

Using the public API ensures compatibility with future LibSavedVars releases.

Quick Reference

Function Purpose
NewAccountWide() Create account-wide settings
NewCharacterSettings() Create character settings
EnableDefaultsTrimming() Remove redundant default values
Migrate() Register saved data migrations
GetActiveSavedVars() Get current active settings
SetAccountSavedVarsActive() Switch storage mode
GetAccountSavedVarsActive() Check storage mode
AddAccountWideToggle() Pin keys to account storage
AddCharacterSettingsToggle() Pin keys to character storage
GetIterator() Iterate active settings
GetRawDataTable() Access stored values only

This API provides the building blocks needed to manage simple settings as well as complex, evolving saved data structures.

Clone this wiki locally