WoW:Saving variables between game sessions (source)
Revision as of 03:39, 1 April 2005
, 1 April 2005Added more details about using them later.
m (changed category) |
m (Added more details about using them later.) |
||
| Line 5: | Line 5: | ||
With the exception of a few game-managed properties (slot contents, graphics settings, etc), all custom values which need to be saved between sessions are maintained in a single file, <tt>SavedVariables.lua</tt>, which is written whenever the UI engine shuts down (either at game quit, or at the start of a forced UI reload), and then executed when the UI is started (after logging in or at the end of a forced UI reload). | With the exception of a few game-managed properties (slot contents, graphics settings, etc), all custom values which need to be saved between sessions are maintained in a single file, <tt>SavedVariables.lua</tt>, which is written whenever the UI engine shuts down (either at game quit, or at the start of a forced UI reload), and then executed when the UI is started (after logging in or at the end of a forced UI reload). | ||
The <tt>SavedVariables.lua</tt> file is executed as code (just like your addon code) some point shortly after all addons have been loaded. Since it is just executed as code, all of the values in it are loaded (regardless of whether they're still registered as saved variables). Once it has been loaded, the <b>"VARIABLES_LOADED"</b> event is fired, so that addons can update themselves. | |||
When the UI engine shuts down, only those variables which have been marked for saving will be written into the <tt>SavedVariables.lua</tt> file. | |||
== Designating variables to save == | |||
=== SavedVariables in AddOn's .toc === | === SavedVariables in AddOn's .toc === | ||
| Line 11: | Line 15: | ||
The best way is to use the SavedVariables keyword in your Addon's .toc file. Thus, an addon with some saved variables would have a .toc like: | The best way is to use the SavedVariables keyword in your Addon's .toc file. Thus, an addon with some saved variables would have a .toc like: | ||
## Interface: | ## Interface: 1300 | ||
## Title: Demo AddOn | ## Title: Demo AddOn | ||
## Notes: This is a test to show how to save variables between game sessions | ## Notes: This is a test to show how to save variables between game sessions | ||
| Line 21: | Line 25: | ||
This method is best because it works even if your module is not active (based on the ui addons menu), has a version mismatch, or fails during startup due to compilation, dependency, or other issues. | This method is best because it works even if your module is not active (based on the ui addons menu), has a version mismatch, or fails during startup due to compilation, dependency, or other issues. | ||
=== The RegisterForSave function === | === The RegisterForSave function (Do not use this) === | ||
'''IMPORTANT:''' This information is really for reference only, you almost never want to use this. Use SavedVariables instead. | |||
LUA code can explicitly request that a variable be saved by calling the [[API RegisterForSave|RegisterForSave("varName")]] function with the variable name that should be saved. That variable then becomes flagged for saving at the end of the session. It's important to note that since this is an active process, the variable will only be saved if it is registered during a session, so compilation execution failures that prevent the call from being made will end up without the variable being flagged. | LUA code can explicitly request that a variable be saved by calling the [[API RegisterForSave|RegisterForSave("varName")]] function with the variable name that should be saved. That variable then becomes flagged for saving at the end of the session. It's important to note that since this is an active process, the variable will only be saved if it is registered during a session, so compilation execution failures that prevent the call from being made will end up without the variable being flagged. | ||
| Line 31: | Line 37: | ||
ADDON_SETTINGS = {} | ADDON_SETTINGS = {} | ||
<nowiki>ADDON_SETTINGS["dynamic" .. something] = value</nowiki> | <nowiki>ADDON_SETTINGS["dynamic" .. something] = value</nowiki> | ||
== Using previously saved variables == | |||
If your needs are simple, then you just have to mark your variable as saved in the <tt>.toc</tt> file, and initialize it with a reasonable default value at startup or OnLoad time. If there is a previously saved value, then it will simply overwrite the default one, otherwise the default value will remain. At the end of the play session whatever value it has ended up as will be saved. | |||
If your addon drives configuration from the saved variables, you will likely want to be informed when they've been loaded so the addon can reconfigure itself. In this case create an event handler and register for the <b>"VARIABLES_LOADED"</b> event. Once this is called you can re-check your configuration and set things appropriately. | |||
Finally, if you wish to do logic involving both the default and loaded value, you can use a technique as follows: | |||
When the addon sets up the default value, you do: | |||
Demo_foo = { "bar" } | |||
local initDemo_foo = Demo_foo; | |||
In your OnLoad handler you add: | |||
this:RegisterEvent("VARIABLES_LOADED"); | |||
Then, in your OnEvent handler, you have | |||
if (event == "VARIABLES_LOADED") then | |||
if (initDemo_foo == Demo_foo) then | |||
-- No change - Must be new user | |||
else | |||
-- Changed - Previous user | |||
end | |||
end | |||
== Settings are per-ACCOUNT == | == Settings are per-ACCOUNT == | ||
It's important to note that settings are saved per-account, not per-character. If you wish to do per-character settings in your AddOn then you should use something like the player name as a key into a table for settings. This does give the AddOn author some flexibility in being able to make some settings global, some per-class, some per-user, etc. | It's important to note that settings are saved per-account, not per-character. If you wish to do per-character settings in your AddOn then you should use something like the player name as a key into a table for settings. This does give the AddOn author some flexibility in being able to make some settings global, some per-class, some per-user, etc. | ||
[[Category:Interface Customization]] | [[Category:Interface Customization]] | ||