Namespaces

Namespaces provide a way to organize multiple sets of saved variables within a single ESO SavedVariables file.

LibSavedVars supports namespaces to allow addons to separate related data while sharing the same underlying SavedVariables table.

Namespaces are useful when an addon has multiple independent components that should share:

• The same SavedVariables file.
• The same account or character scope.
• The same lifecycle.

---

Why Use Namespaces?

Without namespaces, an addon may place all data into one large table:

MyAddonSavedVariables
{
    enabled = true,
    window = {},
    profiles = {},
    history = {},
    cache = {},
}

As an addon grows, this can become difficult to manage.

Namespaces allow separation:

MyAddonSavedVariables
{
    Settings =
    {
        enabled = true,
        window = {},
    },

    Profiles =
    {
        Tank = {},
        Healer = {},
    },

    History =
    {
        entries = {},
    },
}

Each namespace has its own logical data area.

---

Creating a Namespace

The namespace parameter is passed when creating a saved variable object.

Example:

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

The data is stored under:

MyAddonSavedVariables.Settings

Another component can use the same SavedVariables file with a different namespace:

local profiles = LibSavedVars:NewAccountWide(
    "MyAddonSavedVariables",
    1,
    "Profiles",
    profileDefaults
)

Stored data:

MyAddonSavedVariables
{
    Settings = {},
    Profiles = {},
}

---

Multiple Namespaces in One SavedVariables File

A large addon may organize data like:

local settings = LibSavedVars:NewAccountWide(
    "MyAddonSavedVariables",
    5,
    "Settings",
    settingsDefaults
)

local profiles = LibSavedVars:NewAccountWide(
    "MyAddonSavedVariables",
    3,
    "Profiles",
    profileDefaults
)

local cache = LibSavedVars:NewAccountWide(
    "MyAddonSavedVariables",
    2,
    "Cache",
    cacheDefaults
)

The resulting structure:

MyAddonSavedVariables
|
+-- Settings
|
+-- Profiles
|
+-- Cache

Each namespace is managed independently.

---

Namespace Versioning

Each namespace has its own version.

Example:

local settings = LibSavedVars:NewAccountWide(
    "MyAddonSavedVariables",
    4,
    "Settings",
    settingsDefaults
)

local profiles = LibSavedVars:NewAccountWide(
    "MyAddonSavedVariables",
    2,
    "Profiles",
    profileDefaults
)

The versions represent:

Settings namespace:
    Version 4

Profiles namespace:
    Version 2

A change to one namespace does not require changing the version of another namespace.

---

Namespace Migrations

Each namespace maintains its own migration chain.

Example:

settings:Migrate(2, function(savedVars)

    savedVars.scale = 1.0

end)

settings:Migrate(3, function(savedVars)

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

end)

Profiles can have separate migrations:

profiles:Migrate(2, function(savedVars)

    savedVars.Default =
        savedVars.defaultProfile

    savedVars.defaultProfile = nil

end)

The migration history of one namespace does not affect another.

---

Namespace vs Multiple SavedVariables Files

Both approaches allow data separation.

Namespaces

Example:

MyAddonSavedVariables
|
+-- Settings
+-- Profiles
+-- Cache

Advantages:

• One SavedVariables file.
• Shared file lifecycle.
• Easier organization.
• Good for related data.

---

Multiple SavedVariables Files

Example:

MyAddon_Settings
MyAddon_Profiles
MyAddon_Cache

Advantages:

• Complete separation.
• Independent file management.
• Easier removal of large data sets.
• Useful for unrelated data.

---

Choosing Between Namespaces and Files

Use namespaces when:

• Data belongs to the same addon subsystem.
• Data should be loaded and managed together.
• The data is relatively small.
• The same addon owns all components.

Example:

MyAddonSavedVariables

    Settings
    Profiles
    UI

Use separate files when:

• Data has a different lifecycle.
• One data set may become very large.
• Data may be cleared independently.
• Different components manage their own data.

Example:

MyAddon_Settings
MyAddon_Statistics
MyAddon_Cache

---

Namespaces and Storage Scope

Namespaces can be used with both account-wide and character settings.

Account-wide namespace:

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

Character namespace:

local characterSettings =
    LibSavedVars:NewCharacterSettings(
        "MyAddonSavedVariables",
        1,
        "Character",
        defaults
    )

Result:

MyAddonSavedVariables

Account-wide:
    Settings

Character:
    Character

---

Namespaces and LSV_Data

Namespaces work well with LSV_Data when an addon separates different categories of settings.

Example:

Account-wide
|
+-- Settings namespace
|
+-- Profiles namespace


Character
|
+-- Character namespace

Each saved variable object can participate in its own storage model while still using the same underlying SavedVariables file.

---

Namespace Naming Guidelines

Use clear, stable names.

Good:

"Settings"
"Profiles"
"Characters"
"Cache"

Avoid:

"A"
"Data1"
"Temp"

Namespaces become part of the saved data structure and should remain understandable for future maintenance.

---

Best Practices

When using namespaces:

• Use namespaces to separate logical data groups.
• Give each namespace a clear purpose.
• Maintain independent versions per namespace.
• Keep migrations limited to the affected namespace.
• Use separate files when data has a different lifecycle.
• Avoid creating unnecessary namespaces for small addons.

---

Summary

Namespaces provide a lightweight way to organize saved data inside a single SavedVariables file.

They allow addons to maintain separate:

• Defaults.
• Versions.
• Migrations.
• Data structures.

Use namespaces when related data should remain together. Use multiple SavedVariables files when data should be managed independently.

A well-designed namespace structure makes large addons easier to maintain and allows saved data formats to evolve safely over time.