Skip to content

Advanced Topics

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

The previous sections covered the features needed by most addons: creating saved variables, defining defaults, versioning, migrations, and optionally using LSV_Data.

This section explores the more advanced capabilities of LibSavedVars. These features are intended for addons with more complex storage requirements or developers who want finer control over how saved variables are managed.

Namespaces

Namespaces allow multiple systems within an addon to share the same SavedVariables file while keeping their data logically separated.

For example:

local combat = LibSavedVars:NewAccountWide(
    "MyAddonSavedVariables",
    1,
    "Combat",
    combatDefaults
)

local inventory = LibSavedVars:NewAccountWide(
    "MyAddonSavedVariables",
    1,
    "Inventory",
    inventoryDefaults
)

Each namespace has its own defaults and version while sharing the same SavedVariables file.

Namespaces are useful for large addons or addon suites that manage multiple independent features.

For more detail see the Namespaces page.

Raw Saved Variables

Normally, LibSavedVars provides a table that automatically falls back to the defaults table when a value has not been stored.

In some situations, it is useful to work directly with the underlying SavedVariables table.

Examples include:

  • Inspecting only the values that have actually been saved.
  • Debugging migrations.
  • Exporting or importing settings.
  • Measuring the effect of defaults trimming.

LibSavedVars provides methods for accessing the raw data when required. Most addons, however, should continue using the normal saved variables interface.

For more details, see the Raw Saved Variables page.

Iterating Over Settings

When using LSV_Data, especially with pinned account settings, the active configuration may be assembled from more than one underlying table.

Rather than iterating each table separately, use the iterator provided by LSV_Data.

for key, value in settings:GetIterator() do
    d(key, value)
end

The iterator presents a unified view of the active settings, regardless of where individual values are stored.

For more details, see the Iterating Over Settings page

Iterating over Characters and Accounts

LibSavedVars can manage saved data at multiple levels:

  • Account-wide settings.
  • Character-specific settings.
  • Multiple characters within an account.

For advanced addon features, it may be useful to inspect or process saved data across characters or accounts.

For more details, see the Iterating over Characters and Accounts page.

Versioning Strategies

For simple addons, sequential version numbers (1, 2, 3, ...) are sufficient.

For larger projects, consider these guidelines:

  • Increment the version only when existing saved data requires modification.
  • Keep migrations focused on a single version.
  • Never change or remove old migrations after release.
  • Always test upgrades from older versions.

Following these practices ensures users can upgrade from any previous release without losing their settings.

For more details, see the Versioning Strategies page.

Debugging Saved Variables

When troubleshooting saved variable issues:

  • Inspect the SavedVariables file to verify the stored structure.
  • Compare the stored data with your defaults table.
  • Test upgrades using data created by previous addon versions.
  • Verify that migrations execute in the expected order.
  • Confirm that defaults trimming removes only values equal to their defaults.

Testing with realistic saved data is often the fastest way to identify migration or versioning problems.

Performance Considerations

LibSavedVars is designed to minimize runtime overhead.

A few recommendations can help keep your addon efficient:

  • Create each saved variables object only once during addon initialization.
  • Reuse the same object throughout the addon.
  • Avoid repeatedly creating temporary saved variable objects.
  • Keep migration code focused on one-time startup work rather than gameplay.

For most addons, saved variable operations represent a negligible portion of overall execution time.

Best Practices

The following guidelines apply to nearly every addon:

  • Define complete and well-organized defaults.
  • Increase the version only when existing data changes.
  • Keep migrations small and focused.
  • Enable defaults trimming unless you have a specific reason not to.
  • Use LSV_Data only when managing multiple storage models.
  • Keep the rest of your addon independent of where settings are stored.

Following these practices will make your addon easier to maintain as it grows.

Summary

LibSavedVars provides considerably more than a replacement for ZO_SavedVars. Features such as namespaces, migration helpers, LSV_Data, pinned account settings, defaults trimming, and flexible version management allow addons to evolve while preserving users' settings.

Most addons will use only a subset of these features, but together they provide a solid foundation for projects ranging from simple utilities to large, feature-rich addons.

Clone this wiki locally