This page details how AddOns load and unload, including the order when information becomes available such as SavedVariables and character details.

AddOn loading order

Main article: TOC format

Blizzard's AddOns usually load first (the native UI), followed by custom AddOns in alphabetical order of directory names. However, LoadOnDemand and other directives in a .toc file can override this behaviour.

The .toc file also squences XML and Lua files within the AddOn, and XML tags <Include> and <Script> can also load files when the tag is parsed.

When saving variables between game sessions, SavedVariables and SavedVariablesPerCharacter load after the last file listed in the .toc file. This overwrites any default values set earlier.

Finally, ADDON_LOADED fires to indicate the AddOn has finished loading. This is the earliest time for an AddOn to read its SavedVariables.

Events during login

AddOns begin loading before all information is available to the client. For most AddOns, events will occur in the following sequence. However, LoadOnDemand AddOns might trigger part-way or after all steps have finished:

    • Fires each time an AddOn finishes loading, including all files and the SavedVariables.
    • Check the first argument to see which AddOn has finished -- do not assume your AddOn will finish first, because LoadOnDemand can break this pattern.
  2. SAVED_VARIABLES_TOO_LARGE (Error Condition)
    • Generally does not fire. This event indicates an error state where the SavedVariables of an addon failed to load due to an out-of-memory error. (The old error state was a client crash!)
    • The upshot here is that your addon could be in a state where the saved variables did not load. This event's purpose is to indicate that you are in this error state.
    • If you are in this state your addon's SavedVariables will NOT be saved back to disk at the next logout. This was done with the reasoning that it will prevent valid data from accidentally being wiped by defaults.
    • It is possible for an addon's account wide SavedVariables to load, but for the character specific SavedVariables to fail, or vice versa. There is no way to detect the difference between no variables loaded and some.
    • This event fires shortly before the PLAYER_LOGIN event and signals that information on the user's spells has been loaded and is available to the UI.
    • This event fires immediately before the first 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 PLAYER_ENTERING_WORLD.
    • This event fires (for the first time) immediately after 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 during logout

    • Does not imply logout, as it may preceed another loading screen (instances, continents, etc.).
    • All AddOns commit SavedVariables prior to reloading, quitting or logging off. Called once only, rather than for each AddOn. This does not occur during a crash or Alt-F4.[citation needed] 



##Interface: 90105
##Title: Loading Order Demo
##SavedVariables: LoadingOrderSavedVar


print("This loads first")


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


print("Files included in XML are executed as they are encountered")


LoadingOrderSavedVar = 0  -- default value until ADDON_LOADED
print("The last file has loaded.")

local frame = CreateFrame("Frame")
frame:SetScript("OnEvent", function(self, event)
  if event == "ADDON_LOADED" and arg1="LoadingOrder" then
    LoadingOrderSavedVar = LoadingOrderSavedVar + 1
    if LoadingOrderSavedVar then
      print("The demo has now loaded .." LoadingOrderSavedVar .. " times".)

Patch changes

  • Wrath of the Lich King Patch 3.0.2 / API (2008-10-14): VARIABLES_LOADED is no longer a reliable part of the addon loading process. It fires in response to CVars, Keybindings and other associated "Blizzard" variables being loaded, and therefore may happen after PLAYER_ENTERING_WORLD.
    The event remains useful to override positioning data stored in layout-cache.txt.
  • Mists of Pandaria Patch 5.4.0 / API (2013-09-10): Circa 5.4.0, PLAYER_ALIVE stopped firing during login. It now only fires when a player is resurrected (before releasing spirit) or when a player releases spirit.
    Previously, AddOns could use PLAYER_ALIVE to signal that quest and talent information were available because it was the last event to fire, even later than PLAYER_ENTERING_WORLD.

See also

  • Handling events for information on how to sign up to receive event notifications