Pinned Account Settings

Pinned Account Settings

When an addon supports both account-wide and character-specific settings, some settings may need to remain shared regardless of the active storage mode.

For example, a user may want:

• Window positions shared across all characters.
• UI themes shared across all characters.
• Character-specific gameplay preferences.
• Character-specific filters or configurations.

LibSavedVars supports this through pinned account settings.

Pinned settings allow selected keys to always use account-wide storage while the remaining settings follow the currently active storage mode.

---

Why Use Pinned Settings?

Without pinned settings, an addon typically has to choose one storage model:

Account-wide:
    Everything is shared.

or

Character:
    Everything is independent.

Many addons need a mixed approach:

Account-wide:
    window position
    theme
    color settings

Character:
    build configuration
    filters
    preferences

Pinned account settings allow both behaviors at the same time.

---

How Pinned Settings Work

When character settings are active, LSV_Data normally reads and writes values from the character saved variables.

Pinned keys are the exception.

Example:

settings:AddAccountWideToggle("window")
settings:AddAccountWideToggle("theme")

With character settings active:

settings.window.x = 200
settings.theme = "Dark"
settings.build = "Tank"

The data is stored as:

Account-wide
{
    window = {
        x = 200
    },

    theme = "Dark"
}


Character
{
    build = "Tank"
}

The addon continues using one settings object.

---

Adding Pinned Settings

Pinned settings are added through LSV_Data.

Example:

local settings = LibSavedVars:NewData(
    accountSettings,
    characterSettings
)

settings:AddAccountWideToggle("window")
settings:AddAccountWideToggle("theme")

The specified keys are now always read from the account-wide saved variables.

---

Removing Pinned Settings

A pinned setting can be removed by removing the key from the pinned configuration.

After removal, the setting follows the active storage mode again.

Example:

Before:

theme → Account-wide

After removing the pin:

theme → Active storage mode

---

Nested Settings

Pinned settings can represent entire sections of data.

Example:

local defaults = {
    ui = {
        window = {
            x = 100,
            y = 100,
        },
        theme = "Dark",
    },

    combat = {
        autoAttack = true,
    },
}

Pin the UI section:

settings:AddAccountWideToggle("ui")

Result:

Account-wide
{
    ui = {
        window = {
            x = 100,
            y = 100
        },
        theme = "Dark"
    }
}


Character
{
    combat = {
        autoAttack = true
    }
}

All UI settings remain shared while combat settings remain character-specific.

---

Accessing Pinned Settings

Pinned settings are accessed normally.

The addon does not need special handling:

settings.ui.theme = "Light"

settings.combat.autoAttack = false

LibSavedVars determines where each value belongs.

---

Switching Storage Modes

Pinned settings remain account-wide regardless of the active storage mode.

Example:

settings:SetAccountSavedVarsActive(false)

Now character settings are active.

The effective storage becomes:

Account-wide:
    pinned settings

Character:
    all other settings

Switching back:

settings:SetAccountSavedVarsActive(true)

returns to:

Account-wide:
    all settings

---

Choosing What to Pin

Good candidates for pinned settings:

• Window locations.
• UI layout.
• Theme selections.
• Color preferences.
• Global display options.
• Account-wide unlocks.

Poor candidates:

• Character builds.
• Character progress.
• Per-character filters.
• Character notes.
• Character-specific preferences.

A setting should be pinned only when users would reasonably expect the value to be shared.

---

Migration Considerations

When adding pinned settings to an existing addon, existing data may need to be moved.

Example:

Before:

Character Settings
{
    theme = "Dark"
}

After:

Account Settings
{
    theme = "Dark"
}

A migration should copy the existing value into the new location.

Example:

settings:Migrate(2, function(savedVars)

    -- Move theme into account-wide storage

end)

Migration helpers can simplify these operations.

---

Best Practices

When using pinned account settings:

• Pin complete logical groups when possible.
• Avoid pinning individual keys unnecessarily.
• Document which settings are shared.
• Test switching between storage modes.
• Test existing users upgrading to the new structure.
• Use migrations when changing where data is stored.

---

Summary

Pinned account settings allow an addon to combine the advantages of account-wide and character-specific storage.

They provide:

• Shared settings where appropriate.
• Character customization where needed.
• A single interface for addon code.
• Automatic handling of storage locations.

For addons that support flexible configuration, pinned settings provide a clean way to give users control without complicating addon development.