WildStar:AddOn loading process

Reference e
AddOns UI API UI Form UI XML UI Event WS Lua UI Macro CVars Changes Guides Snippets Categories

→ UI AddOn

← UI AddOn

This document describes the WildStar load order for loading AddOns. 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

1. 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.
2. Game Load - After the player selects a character and chooses to enter the world, general AddOns and dependencies are found and loaded, and code is executed.
3. 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 files, 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

1. 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.
2. 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.
3. OnRestore Account
   • This event offers Account specific settings as a table.
4. OnRestore Realm
   • This event offers Realm specific settings as a table.
5. OnRestore Character
   • This event offers Character specific settings as a table.

UI stopping

1. 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.
2. OnSave Account
   • This event offers Account specific settings as a table.
3. OnSave Realm
   • This event offers Realm specific settings as a table.
4. OnSave Character
   • This event offers Character specific settings as a table.

Instance transition

1. 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