Editing WildStar:AddOn loading process

{{dev/uiaddon}}

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

== General steps ==
# Initial Load - When the WS client first starts, a smaller list of ''PreGame'' files and ''PreGame'' AddOn dependencies is built and loaded which run the pre-game UI.
# Game Load -  After the player selects a character and chooses to enter the world, general [[AddOn]]s and dependencies are found and loaded, and code is executed.
# Saved variables - After all AddOns have been loaded, the saved variables are loaded. ''OnRestore'' event fires for each AddOn, offering saved variables as tables.

=== Initial Load ===
* PreGame - First, the WS client loads a few pre-game UI AddOn components for the login, and other pre-game screens, from the same sets of UI files used for general AddOns, which are located in both "[usersettings]\NCSOFT\WildStar\AddOns" directory and the game data files in the asset path "UI". 

* Discovery - In the load process for any AddOn, the client looks for sub-folders containing a valid [[TOC file]]s, with a 'toc.xml' name and opens and executes the file to load the AddOn.  For a user AddOn to be considered valid, it must have a single word folder somewhere inside the "[usersettings]\...\AddOns" folder, and must have a file named 'toc.xml', such as a 'MyAddon' folder with a valid 'toc.xml' file underneath.  That is all that is required.

* Reload - During any load or reload of the UI, TOC files will be searched for again and AddOns or files that didn't exist during initial load, can be loaded by the game later on. This makes it possible to install additional AddOns, or load updated TOC files, without restarting the client.

=== Game Load ===
* Game - General AddOn loading, which includes all AddOns, occurs when the player enters the game world. The game world is loaded and AddOns are "delay loaded" afterward, where the loading of the playable world does not depend on the UI or AddOn process.

* Load Order - The scan and load process is opaque and should be considered indeterminate, however AddOns are generally loaded in the order they are found, where  first game data "UI" folder is scanned, and then the "[usersettings]\...\AddOns" folder is scanned for valid AddOns. Each AddOn gets its name from the ''Name'' setting in its TOC file, which is used as to uniquely identify a given AddOn in the process.

* Dependencies - Any dependency information resides in the AddOn [[Lua]] code itself and not in TOC files. AddOns should '''not''' assume other AddOns or Packages (library AddOns) will be loaded first. Each AddOn must in code explicitly declare itself as a dependent, and later ask for reference, for other AddOns. WS will load dependencies requested before the AddOns OnLoad event fires.

=== Saved Variables ===
* Post AddOn load - After an AddOns and all of its dependencies are completely loaded, settings are loaded. Settings are passed as in table structures to and from the AddOn for load and save, using event handlers on the AddOn, and are stored in ''General'', ''Account'', ''Realm'', and ''Character'' specific sets, in that order.  Settings are stored in settings files in "[usersettings]\...\WildStar" folder. AddOns choose which sets of setting types they will load and save.

* On Load - Each AddOn with an OnRestore() event handler, where a table is passed each time with the settings for each settings type. It is up to the AddOn to determine how to use the passed table and how to update state or refresh UI display. AddOns are expected to be able to load any settings they use, at any time, and still operate correctly. 

* On Save - Before or during reload or game world exit (player camp), settings are saved where each AddOn with an OnSave() event handler can submit a single table for each settings type for each specific event. If the game crashes during play or before these events are run, any new settings will be lost.

== Inside loading the TOC file ==
Files within an AddOn are loaded in the order they're listed in the AddOn's [[TOC file]], named "toc.xml", and as a part of the AddOn itself, which is defined using the ''Addon'' attributes. See [[TOC file]] for reference.

* AddOn attributes - When the ''Addon'' element XML in the [[TOC file]] is loaded, only the Apollo ''AddOn'' item itself is created and its meta data like name, author, version, are available immediately to any subsequent Lua code by Name attribute through Apollo API.

* AddOn files - File are loaded through XML <Script file="src.lua" /> or <Form file="src.xml" /> and Script files are loaded at the time the tag is encountered while parsing. Form files are accounted for but not fully loaded and created until expressly requested in code.

* AddOn Scripts - The TOC file, for regular AddOns, is responsible for loading a Lua file to define register its actual AddOn Lua instance. During Lua file execution in the AddOn load process, the world has already been loaded, and most of the game state is known and available through the [[UI API]].

* AddOn Forms - The TOC file, for regular AddOns, is responsible for itemizing Form .xml files to register AddOn relative Forms and UI widgets. Lua code can ask that an instance is generated from a registered form any time, which should normally be done during or after OnLoad.

* TOC loaded - Once all of the Script and Form children have been loaded, if a Lua AddOn instance was created, registered, its OnLoad event handler is then executed if exists, giving the AddOn a chance to finish the loading process and register any handlers and otherwise thereafter operate like a proper and complete AddOn. After OnLoad, the AddOn's OnRestore settings load events are run. Both OnLoad and OnRestore are run before the client moves on to load another AddOn. 

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

* toc.xml
 <?xml version="1.0" encoding="utf-8"?>
 <Addon Author="Bob" APIVersion="8" Name="LoadOrder" Description="Demo load order.">
     <Script Name="file1.lua"/>
     <Script Name="file2.lua"/>
     <Form Name="file3.xml"/>
 </Addon>
* file1.lua
 Print("This loads first")
* file2.lua
 Print("Files included in XML are executed as they are encountered")
* file3.xml
 <?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
 <Forms>
     <Form Class="Window" Template="CRB_NormalFrame" Name="BobForm">
         <Control Class="Window" Template="Default" Name="Title"/>
     </Form>
 </Forms>

== Inside the post-TOC AddOn process ==
After the running of TOC is complete and the AddOn code has been loaded, a standard series of events follows. There are three distinct phases, which are UI starting, UI stopping (as when reload and exit), and Instance transitions.

==== UI starting ====
# OnLoad - handler
#* This event fires whenever an AddOn TOC files has finished loading, and all of the requested dependencies were loaded. AddOns do not have to register for this event.
# OnRestore General - handlers
#* This event, and the other OnRestore events, fire after OnLoad, but before the client has moved-on to load another AddOn. ''General'' settings type is the first in a series of OnRestore events, and a table is passed each time with the settings for each settings type. AddOns do not have to register for these events.
# OnRestore Account
#* This event offers ''Account'' specific settings as a table.
# OnRestore Realm
#* This event offers ''Realm'' specific settings as a table.
# OnRestore Character
#* This event offers ''Character'' specific settings as a table.

==== UI stopping ====
# OnSave General - handler
#* This event, and the other OnSave events, fire before game world exit or as a part of reload. ''General'' settings type is the first in a series of OnSave events, and a table is offered by the AddOn each time, with the settings for each settings type.  AddOns do not have to register for these events.
# OnSave Account
#* This event offers ''Account'' specific settings as a table.
# OnSave Realm
#* This event offers ''Realm'' specific settings as a table.
# OnSave Character
#* This event offers ''Character'' specific settings as a table.

==== Instance transition ====
# {{\|api|API EVENT|ChangeWorld}}() - event
#* This event fires after player has changed instance servers, like when entering or exiting a dungeon.
#* Does not fire when player first enters game world from the character screen, as the UI and AddOns load after the player has entered. AddOns must register for this event.
#* Does not fire when UI is reloaded.

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