Skip to content

Public API Reference

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

This section provides a reference for the public LibSavedVars API. It is intended for addon developers who need detailed information about available functions, parameters, and return values.

The API is organized into several areas:

  • Creating saved variables.

  • Accessing and managing saved data.

  • Account-wide and character settings.

  • Versioning and migrations.

  • Defaults management.

  • Advanced data management.

For most addons, only the creation functions and basic table access are required.

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 | Name of the ESO SavedVariables table. version | number | Current version of the saved data. namespace | string/nil | Optional namespace within the saved variables table. defaults | table | Default values for the settings.

Example

data:AddAccountWideToggle("window")

GetIterator()

Returns an iterator over the active settings.

Syntax

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

Description

Provides a combined view of active settings, including pinned account-wide values.

Utility Functions

GetRawDataTable()

Returns the underlying SavedVariables table without default-value resolution.

Syntax

local raw = settings:GetRawDataTable()

Description

Useful for:

  • Debugging.

  • Inspecting saved values.

  • Migration work.

  • Data export.

The returned table contains only values actually stored in SavedVariables.

Migration Utilities

LibSavedVars includes helper functions for common migration tasks, including:

  • Moving data between account-wide and character storage.

  • Creating missing table paths.

  • Removing obsolete settings.

  • Copying values between locations.

These functions are intended for advanced migration scenarios where manually modifying tables would be error-prone.

Recommended Usage Pattern

A typical addon initialization follows this pattern:

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

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


settings:EnableDefaultsTrimming()


settings:Migrate(2, function(savedVars)
-- version 2 migration
end)

After initialization, the addon should use settings throughout its code rather than accessing the underlying SavedVariables directly.

API Design Guidelines

When using LibSavedVars:

  • Create saved variables once during addon initialization.

  • Treat defaults as a template, not storage.

  • Increase versions only when existing data changes.

  • Keep migrations small and independent.

  • Use LSV_Data only when multiple storage models are required.

  • Avoid depending on the internal SavedVariables structure unless using advanced APIs.

Following these practices keeps saved data stable, upgradeable, and easy to maintain.

Clone this wiki locally