Defaults

Defaults define the initial values for your saved variables. They provide a complete template for your addon's configuration and ensure that every setting has a valid value, even before it has been saved by the player.

LibSavedVars uses the defaults table in the same way as ZO_SavedVars, allowing you to work with settings as though every value already exists.

Defining Defaults

Create a Lua table containing the default values for your settings.

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

    window = {
        x = 100,
        y = 200,
        locked = false,
    },

    colors = {
        background = {0, 0, 0, 0.5},
    },
}

Pass this table when creating your saved variables.

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

How Defaults Work

When you access a setting, LibSavedVars first checks whether the player has saved a value.

• If a saved value exists, it is returned.
• If no saved value exists, the corresponding value from the defaults table is returned automatically.

For example:

local defaults = {
    opacity = 0.75,
}

If the player has never changed the setting,

d(settings.opacity)

prints:

0.75

Once the player saves a new value,

settings.opacity = 1.0

future reads return:

1.0

Your code does not need to check whether a setting exists before using it.

Nested Defaults

Defaults may contain nested tables of any depth.

local defaults = {
    ui = {
        minimap = {
            visible = true,
            size = 250,
        },
    },
}

These nested values can be accessed naturally.

if settings.ui.minimap.visible then
    -- ...
end

settings.ui.minimap.size = 300

Adding New Defaults

As your addon grows, you can safely add new default values to the defaults table.

For example, version 1 of your addon might define:

local defaults = {
    enabled = true,
}

Later, version 2 adds another setting:

local defaults = {
    enabled = true,
    showTooltips = true,
}

Existing users automatically receive the new default value unless they explicitly save a different one.

Defaults Are Not Automatically Saved

One of the most important concepts to understand is that default values are not immediately written to the SavedVariables file.

If a setting has never been modified, its value is supplied from the defaults table at runtime rather than being stored on disk.

For example, given:

local defaults = {
    enabled = true,
}

A new user may have an empty SavedVariables table:

{}

Yet the following still works:

d(settings.enabled)

because LibSavedVars returns the default value of true.

The value is only stored when the player changes it or your addon explicitly assigns it.

Best Practices

When defining defaults:

• Include every setting your addon expects to use.
• Keep the table organized by feature or subsystem.
• Use descriptive names for nested tables.
• Avoid modifying the defaults table after creating the saved variables.
• Treat the defaults table as a read-only template.

A well-designed defaults table makes your addon's configuration predictable, simplifies future development, and provides a solid foundation for versioning and data migration.