WoW:Saving variables between game sessions (source)
Revision as of 04:48, 15 August 2023
, 15 August 2023Move page script moved page Saving variables between game sessions to WoW:Saving variables between game sessions without leaving a redirect
(→The loading process: expand LoD: first instance) |
m (Move page script moved page Saving variables between game sessions to WoW:Saving variables between game sessions without leaving a redirect) |
||
| (8 intermediate revisions by 8 users not shown) | |||
| Line 1: | Line 1: | ||
{{ | {{wow/uihowto}} | ||
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. | 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 <code>#SavedVariables: FOOBAR</code> or <code>#SavedVariablesPerCharacter: FOOBAR</code> to an addon's .toc file. | '''Summary:''' to save a global variable FOOBAR, add <code>##SavedVariables: FOOBAR</code> or <code>##SavedVariablesPerCharacter: FOOBAR</code> to an addon's .toc file. | ||
== Specifying which variables to save == | == 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. | 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. | ||
; <code>#SavedVariables</code> : 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. | ; <code>##SavedVariables</code> : 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. | ||
; <code>#SavedVariablesPerCharacter</code> : 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. | ; <code>##SavedVariablesPerCharacter</code> : 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 loading process == | ||
| Line 25: | Line 25: | ||
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. | 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. | ||
<!-- This code in the middle of an article to illustrate a point; but it shouldn't fill everything. put it in a scrollable box --> | |||
This code in the middle of an article to illustrate a point; but it shouldn't fill everything. put it in a scrollable box --> | |||
=== HaveWeMet\HaveWeMet.toc === | === HaveWeMet\HaveWeMet.toc === | ||
<code> | |||
## Interface: 30000 | ## Interface: 30000 | ||
## Title: Have We Met? | ## Title: Have We Met? | ||
| Line 33: | Line 33: | ||
## SavedVariablesPerCharacter: HaveWeMetBool | ## SavedVariablesPerCharacter: HaveWeMetBool | ||
HaveWeMet.lua | HaveWeMet.lua | ||
</code> | |||
=== HaveWeMet\HaveWeMet.lua === | === HaveWeMet\HaveWeMet.lua === | ||
<code> | |||
local frame = CreateFrame("FRAME"); -- Need a frame to respond to events | local frame = CreateFrame("FRAME"); -- Need a frame to respond to events | ||
frame:RegisterEvent("ADDON_LOADED"); -- Fired when saved variables are loaded | frame:RegisterEvent("ADDON_LOADED"); -- Fired when saved variables are loaded | ||
| Line 59: | Line 61: | ||
print("HaveWeMet has met " .. HaveWeMetCount .. " characters."); | print("HaveWeMet has met " .. HaveWeMetCount .. " characters."); | ||
end | end | ||
</ | </code> | ||
== Common Pitfalls == | == Common Pitfalls == | ||
| Line 66: | Line 68: | ||
; 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. | ; 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. | ; 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. | ; 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 == | == Storage == | ||
| Line 72: | Line 74: | ||
* <tt>WTF\Account\ACCOUNTNAME\SavedVariables.lua</tt> - Blizzard's saved variables. | * <tt>WTF\Account\ACCOUNTNAME\SavedVariables.lua</tt> - Blizzard's saved variables. | ||
* <tt>WTF\Account\ACCOUNTNAME\SavedVariables\AddOnName.lua</tt> - Per-account settings for each individual AddOn. | * <tt>WTF\Account\ACCOUNTNAME\SavedVariables\AddOnName.lua</tt> - Per-account settings for each individual AddOn. | ||
* <tt>WTF\Account\ACCOUNTNAME\RealmName\CharacterName\AddOnName.lua</tt> - Per-character settings for each individual AddOn. | * <tt>WTF\Account\ACCOUNTNAME\RealmName\CharacterName\SavedVariables\AddOnName.lua</tt> - 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. | Deleting the WTF folder, or simply moving its contents will therefore reset the settings for all of your addons. | ||