WoW:Saving variables between game sessions

Reference e
AddOns WoW API Widget API XML UI Event API WoW Lua Macro API CVars Battle.net HOWTOs Snippets UI tech Categories

→ HOWTOs

← HOWTOs

An Addon may need to save settings and data between game sessions - that is, some information may need to persist through a user log out. To enable this, the addons may specify a number of variables to be saved to disk when the player's character logs out of the game, and restored when the character logs back in. Variables that are saved and restored by the client are called SavedVariables.

Summary: to save a global variable FOOBAR, add ##SavedVariables: FOOBAR or ##SavedVariablesPerCharacter: FOOBAR to an addon's .toc file.

Specifying which variables to save

To tell the WoW client that you want a variable to persist through log out, you need to add it to your addon's .toc file. There are two directives you may add to your .toc file, both should be followed by a colon and a comma-delimited list of variable names in the global environment (for most addons, this means variables that haven't been defined using the local keyword) that the addon wants to persist.

##SavedVariables

Variables listed after this directive are saved on a per-account basis: if any of the characters on that account logs in, those variables will be restored. This may be more useful for global addon settings, or addons that implement profiles one can freely switch between.

##SavedVariablesPerCharacter

Variables listed after this directive are saved on a per-character basis: a separate copy of the variable is stored and restored for each character. This may be more useful for simple per-character options or history data.

The loading process

The variables saved by those directives are not immediately available when your addon loads; instead, they're loaded at a later point. The client fires events to let addons know that their saved variables were loaded.

1. WoW FrameXML code is loaded and executed.
2. Addon code is loaded and executed.
3. Saved variables for one addon a time are loaded and executed, then <b>ADDON_LOADED</b> event is fired for that addon.
4. VARIABLES_LOADED event is fired to let addons know that all saved variables were loaded.

Addons should generally use ADDON_LOADED to determine when their saved variables are accessible; the first argument of the event is the name of the addon for which it is being fired; VARIABLES_LOADED should be avoided as it is will not be fired for load-on-demand addons.

Saving to disk

The client saves variables to disk automatically when you log out, disconnect, quit the game, or reload your user interface (/run ReloadUI()). If an addon needs to make last-minute updates before the variables are saved, the <b>PLAYER_LOGOUT</b> event can be used: it notifies you that the character is about to log out, and lets you alter your saved variables before they are serialized.

Code Example

To illustrate the concepts, let's consider a simple addon, HaveWeMet, shown below. The greets your characters when you log on: if it's seen you log into that character before, it outputs "Hello again, <Character Name>", and it if has not, it outputs "Hi; what is your name?" to the chat frame. When its slash command, /hwm, is used, it tells the player how many characters it has met before.

There are two pieces of information that need to persist between sessions: the number of characters the addon has met, and whether it has met any particular character. To save the count, a global variable, HaveWeMetCount is used (and saved on a per-account basis through #SavedVariables); while HaveWeMetBool is saved per-character and used to determine whether the addon has seen this character before.

HaveWeMet\HaveWeMet.toc

## Interface: 30000
## Title: Have We Met?
## SavedVariables: HaveWeMetCount
## SavedVariablesPerCharacter: HaveWeMetBool
HaveWeMet.lua

HaveWeMet\HaveWeMet.lua

local frame = CreateFrame("FRAME"); -- Need a frame to respond to events
frame:RegisterEvent("ADDON_LOADED"); -- Fired when saved variables are loaded
frame:RegisterEvent("PLAYER_LOGOUT"); -- Fired when about to log out

function frame:OnEvent(event, arg1)
 if event == "ADDON_LOADED" and arg1 == "HaveWeMet" then
  -- Our saved variables are ready at this point. If there are none, both variables will set to nil.
  if HaveWeMetCount == nil then
   HaveWeMetCount = 0; -- This is the first time this addon is loaded; initialize the count to 0.
  end
  if HaveWeMetBool then
   print("Hello again, " .. UnitName("player") .. "!");
  else
   HaveWeMetCount = HaveWeMetCount + 1; -- It's a new character.
   print("Hi; what is your name?");
  end
 elseif event == "PLAYER_LOGOUT" then
   HaveWeMetBool = true; -- We've met; commit it to memory.
 end
end
frame:SetScript("OnEvent", frame.OnEvent);
SLASH_HAVEWEMET1 = "/hwm";
function SlashCmdList.HAVEWEMET(msg)
 print("HaveWeMet has met " .. HaveWeMetCount .. " characters.");
end

Common Pitfalls

There are a few common issues beginners may experience:

Variables are saved and loaded in the global environment

If you want to save a local value, you have to first read it from the global environment (_G table) on ADDON_LOADED, then return it into the global environment before the player logs out

Saved variables are loaded after the addon code is executed

They cannot be accessed immediately, and will overwrite any "defaults" the addon may place in the global environment during its loading process.

Only some variable types may be saved

Strings, booleans, numbers and tables are the only variable types that will be saved (functions, userdata and coroutines will not). Circular references in tables may not be preserved.

Saving tables

Tables are a great way to avoid having to use a large number of names in the global namespace. However, they may be more difficult to initialize to default values when your addon is updated and you add or remove a key. Multiple saved variables that reference the same table will each create a separate (but identical) instance of the table, and as such will no longer point to the same table when they are loaded again.

Storage

Saved variables are stored on a per-account basis in three file classes:

• WTF\Account\ACCOUNTNAME\SavedVariables.lua - Blizzard's saved variables.
• WTF\Account\ACCOUNTNAME\SavedVariables\AddOnName.lua - Per-account settings for each individual AddOn.
• WTF\Account\ACCOUNTNAME\RealmName\CharacterName\AddOnName.lua - Per-character settings for each individual AddOn.

Deleting the WTF folder, or simply moving its contents will therefore reset the settings for all of your addons.