Editing WoW:AddOn loading process

{{uiaddon}}
This document describes the WoW [[UI Customization]] aspect of load order for loading [[AddOn]]s. It covers when the WoW client first starts up, when AddOns load for the first time, and when user or WoW reloads the [[UI]]. The availability of the Lua environment at various points in the process is also detailed. The term '[[WoW Client]]' means: the WoW game program that's launched to play WoW. 

== General steps == 
# Initial Scan - When the WoW client first starts, a list of files and AddOn dependencies is built.
# AddOn Load - AddOn code is executed after the player selects a character and chooses to enter the world.
# After all AddOn code has been loaded, the saved variables are executed. ADDON_LOADED fires after each AddOn's SVs have been loaded.

=== Initial Scan ===
First, the WoW client scans through all of the folders in the '''Interface\AddOns''' directory, looking for sub-folders containing a valid [[TOC file]] with a '.toc' extension, and in turn then loads each AddOn's TOC file into memory. TOC files that were not found during this step cannot be loaded by the game later and only happens on client start-up. This makes it impossible to install additional AddOns, or load updated TOC files, without restarting the client. For a AddOn to be considered valid, it must have a single word folder directly in the '''Interface\AddOns''' folder, and must have a matching named '.toc' file, such as a 'MyAddon' folder with a 'MyAddOn.toc' underneath it.  That is all that is required.

=== AddOn Load ===
AddOn loading occurs when the player logs in. The dependency information in the .toc files is used, in part, to compute the order in which the AddOns files will be loaded, as well as the natural order in which the AddOns were discovered during the scan process. For AddOns with dependencies, an individual AddOn may '''not''' assume that all of the other AddOns that it depends on will be loaded first, without taking specific steps to ensure its dependencies are already loaded and available. When WoW loads a particular AddOn it uses the information in its [[TOC file]] discovered during initial scan and loads each file in order that it is found inside the TOC.

== Inside the TOC file ==
Files within an AddOn are loaded in the order they're listed in the AddOn's [[TOC file]], named [addonname].toc. Files included through XML <Include file="src.xml" /> or <Script file="src.lua" /> are loaded at the time the tag is encountered while parsing. XML OnLoad script handlers execute when all of a widget's children have been created.

When the addon code is first loaded during this step, only basic information about the player -- name, class, race and realm -- is available.

To illustrate the loading order, consider the following addon code example:


'''LoadingOrder.toc'''
 ##Interface: 30000
 ##Title: Loading Order Demo
 file1.lua
 file2.xml
 file3.lua


'''file1.lua'''
 print("This loads first")


'''file2.xml'''
 <Ui>
 
   <Frame name="TemplateFrame" virtual="true">
    <Frames>
     <Frame>
      <Scripts>
       <OnLoad>
         print("Inherited elements of the frame are processed first."); 
       </OnLoad>
      </Scripts>
     </Frame>
    </Frames>
   </Frame>
 
   <Frame inherits="TemplateFrame">
    <Frames>
 
     <Frame>
      <Scripts>
       <OnLoad>
         print("First child frame's OnLoad fires first")
       </OnLoad>
      </Scripts>
     </Frame>
 
     <Frame>
      <Scripts>
       <OnLoad>
         print("Second child frame's OnLoad fires second")
       </OnLoad>
      </Scripts>
     </Frame>
 
    </Frames>
 
    <Scripts>
     <OnLoad>
       print("Parent frame's OnLoad fires after its children's.")
     </OnLoad>
    </Scripts>
   </Frame>
 
   <Script file="file2.5.lua"/>
 </Ui>


'''file2.5.lua'''
 print("Files included in XML are executed as they are encountered");


'''file3.lua'''
 print("This concludes this presentation");

== Saved variables loading ==
After the addon code has been loaded, the loading process can be followed by registering for various events, listed here in order of firing.
# [[Events/A#ADDON_LOADED|ADDON_LOADED]]
#* This event fires whenever an AddOn has finished loading and the SavedVariables for that AddOn have been loaded from their file.  
# [[Events/S#SPELLS_CHANGED|SPELLS_CHANGED]]
#* This event fires shortly before the [[Events/P#PLAYER_LOGIN|PLAYER_LOGIN]] event and signals that information on the user's spells has been loaded and is available to the UI.  
# [[Events/P#PLAYER_LOGIN|PLAYER_LOGIN]]
#* This event fires immediately before [[Events/P#PLAYER_ENTERING_WORLD|PLAYER_ENTERING_WORLD]].
#* Most information about the game world should now be available to the UI.
#* All Sizing and Positioning of frames is supposed to be completed before this event fires.  
#* AddOns that want to do one-time initialization procedures once the player has "entered the world" should use this event instead of [[Events/P#PLAYER_ENTERING_WORLD|PLAYER_ENTERING_WORLD]].
# [[Events/P#PLAYER_ENTERING_WORLD|PLAYER_ENTERING_WORLD]]
#* This event fires immediately after [[Events/P#PLAYER_LOGIN|PLAYER_LOGIN]]
#* Most information about the game world should now be available to the UI. If this is an interface reload rather than a fresh log in, talent information should also be available.
#* All Sizing and Positioning of frames is supposed to be completed before this event fires.  
#* This event also fires whenever the player enters/leaves an instance and generally whenever the player sees a loading screen
# [[Events/P#PLAYER_ALIVE|PLAYER_ALIVE]]
#* This event fires after [[Events/P#PLAYER_ENTERING_WORLD|PLAYER_ENTERING_WORLD]]
#* Quest and Talent information should now be available to the UI

Until 3.0, VARIABLES_LOADED used to fire upon completion of the addon loading process; since 3.0, it is fired in response to CVars, Keybindings and other associated "Blizzard" variables being loaded, and may therefore be delayed until after PLAYER_ENTERING_WORLD. The event may still be useful to override positioning data stored in layout-cache.txt

== Load On Demand behavior ==
Load on Demand addons cannot rely on most of the event sequence being fired for them; only ADDON_LOADED is a reliable indication that the saved variables for your LoD addon have been loaded.

== See also ==
* [[Handling events]] for information on how to sign up to receive event notifications