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. However, .toc directives can override this behaviour (e.g. LoadOnDemand or LoadWith).

Within an AddOn:

  • XML and Lua files load sequentially as listed in the .toc file, and also when reaching <Include> or <Script> tags in XML.
  • Saved variables load after the last file, overwriting 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 saved variables.

Events during login

AddOns load in parallel to the login screen, but can register for events to access information as it becomes available. However, LoadOnDemand AddOns might trigger part-way or after all steps have finished:

Normal sequence:

  1. ADDON_LOADED → addOnName
    • Fires when each AddOn finishes loading, including all files and saved variables.
    • Confirm which AddOn loaded using the first argument (in case a LoadOnDemand AddOn loaded in parallel), access saved variables, and deregister from ADDON_LOADED to avoid repeated callbacks.
    • Fires during the loading screen when logging in or reloading, before the first PLAYER_ENTERING_WORLD. Most information about the game world is available to the UI.
    • Finish any one-time initialization and frame placement, so they are in place when the load screen disappears.
  3. PLAYER_ENTERING_WORLD → isInitialLogin, isReloadingUi
    • Fires during any loading screen including logging in, reloading or entering an instance. The first time happens after PLAYER_LOGIN. If this is a reload, talent information is also available.
    • Finish any reoccuring (ie, instance-dependent) initialization and frame placement, so they are in place when the load screen disappears.
    • Fires when the player is entering combat lockdown. If the player is in combat while reloading, it will follow PLAYER_ENTERING_WORLD.
    • Finish any outstanding modifications to secure frames, as they are unalterable during combat lockdown.
    • Fires when spells in the spellbook is populated, and again when it changes. Currently, this event fires after the preceeding events (but it was not always this way).
    • Update any pertinent non-secure frames.

Error condition:
  • Fires when the client runs out of memory while attempting to load saved variables, after ADDON_LOADED.[1]
  • Usually there is no further action; the client displays a popup informing the user of the error.

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: 90207
##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

  • Mists of Pandaria Patch 5.4.0 (2013-09-10): SAVED_VARIABLES_TOO_LARGE added.[1]
  • Mists of Pandaria Patch 5.4.0 (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.
  • Wrath of the Lich King Patch 3.0.2 (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.

See also

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