Raw vs Proxy in LibSavedVars

LibSavedVars provides two different ways to access saved variable data:

• Proxy access — the normal interface used by addons.
• Raw access — direct access to the underlying ESO ZO_SavedVar data (which is itself a proxy we are not discussing here).

Understanding the difference is important when working with:

• Defaults.
• Migrations.
• Defaults trimming.
• Account-wide and character settings.
• Advanced saved data management.

---

Proxy Access

A proxy is the normal LibSavedVars settings interface.

Example:

settings.enabled = true

local scale = settings.scale

The proxy behaves like a normal Lua table, but internally LibSavedVars manages:

• Defaults.
• Account-wide storage.
• Character storage.
• Pinned account settings.
• Missing values.
• Data routing.

The addon works with the settings as if they were stored in one table.

---

How Proxy Access Works

Suppose the defaults are:

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

The actual SavedVariables table is empty:

{}

Using the proxy:

settings.enabled

returns:

true

even though there is no enabled entry in SavedVariables.

The value comes from:

Proxy
 |
 +-- Saved Data
 |
 +-- Defaults

---

Proxy Example

if settings.enabled then

    EnableFeature()

end

settings.scale = 1.25

The addon does not need to know whether scale is stored:

• Account-wide.
• Character-specific.
• From defaults.
• Through a pinned key.

LibSavedVars handles the details.

---

Raw Access

Raw access exposes the actual saved data table.

Example:

local rawData = settings:GetRawDataTable()

The raw table contains only values physically stored in SavedVariables.

Example:

Stored data:

{
    scale = 1.25
}

Raw access returns:

{
    scale = 1.25
}

It does not include defaults:

rawData.enabled
-- nil

because enabled has never been saved.

---

Raw vs Proxy Example

Defaults:

{
    enabled = true,
    scale = 1.0,
}

Saved data:

{
    scale = 1.5,
}

Proxy View

settings.enabled

returns:

true

settings.scale

returns:

1.5

The proxy view is:

{
    enabled = true,
    scale = 1.5,
}

---

Raw View

local raw = settings:GetRawDataTable()

returns:

{
    scale = 1.5,
}

Only explicitly stored values exist.

---

When to Use Proxy Access

Proxy access should be used for normal addon operation.

Recommended for:

• Reading settings.
• Updating settings.
• UI options.
• Gameplay logic.
• User preferences.

Example:

settings.showMessages = false

This is the preferred way to modify settings.

---

When to Use Raw Access

Raw access is intended for advanced operations.

Common uses:

• Writing migrations (used internally by migration helpers).
• Inspecting saved data.
• Debugging.
• Exporting settings.
• Cleaning saved data.
• Implementing custom conversion logic.

Example:

local raw = settings:GetRawDataTable()

if raw.oldSetting then

    -- migrate old data

end

---

Raw Data and Migrations

Migrations normally operates on raw data.

Example:

Version 1:

{
    oldName = true
}

Version 2:

{
    newName = true
}

Migration:

settings:Migrate(2, function(savedVars)

    savedVars.newName =
        savedVars.oldName

    savedVars.oldName = nil

end)

The migration works with the stored structure.

Using the proxy would be incorrect because defaults and other behaviors may hide the actual stored state.

---

Raw Data and Defaults

The difference between raw and proxy is especially important with defaults.

Example:

Defaults:

{
    enabled = true
}

New installation:

{}

Proxy:

settings.enabled

returns:

true

Raw:

settings:GetRawDataTable().enabled

returns:

nil

The user has not saved the setting yet.

---

Raw Data and Defaults Trimming

Defaults trimming removes stored values that match defaults.

Before trimming:

{
    enabled = true,
    scale = 1.5,
}

Defaults:

{
    enabled = true,
    scale = 1.0,
}

After trimming:

{
    scale = 1.5,
}

Proxy access remains:

settings.enabled
-- true

settings.scale
-- 1.5

The user experience does not change.

Only the raw stored data changes.

---

Raw vs Proxy with LSV_Data

LSV_Data adds another layer because settings may come from multiple sources.

Example:

              Proxy View

              LSV_Data
                 |
       ---------------------
       |                   |
 Account Settings    Character Settings
       |
 Pinned Keys

The proxy provides a combined view.

Example:

settings.window.x
settings.theme
settings.build

may internally come from different saved variable tables.

Raw access exposes the individual storage locations.

---

Raw vs Proxy Summary

Feature	Proxy	Raw
Normal addon access	Yes	No
Includes defaults	Yes	No
Shows stored values only	No	Yes
Handles account/character routing	Yes	No
Handles pinned settings	Yes	No
Used for migrations (internal)	Usually no	Yes
Used for debugging	Sometimes	Yes
User-facing settings	Yes	No

---

Best Practices

Use the proxy interface when:

• Building addon features.
• Reading user preferences.
• Updating settings.
• Creating UI controls.

Use raw access when:

• Migrating data.
• Inspecting storage.
• Debugging saved variables.
• Performing cleanup.
• Working with the physical SavedVariables structure.

Avoid mixing the two approaches unnecessarily.

---

Summary

The proxy view represents:

"What value should my addon use?"

The raw view represents:

"What data has actually been saved?"

For most addon code, use the proxy.
For advanced saved data management, migrations, and diagnostics, use raw access.