API:Addon Format

From TheWarWiki

WAR API Help

Addon Format Overview

The Addon format in Warhammer Online consists of a few files. The first is the .mod file which tells the game what the Name of the addon is, what it does, and what files to load when events fire. The .mod file is a basic XML document as is documented below. Outside of the .mod file you have your standard .xml files and .lua files. Below is the standard directory structure for an Addon, however please note it is possible to change the default addon path by modifying the user_config.xml file.

<?xml version="1.0" encoding="UTF-8"?>
<ModuleFile xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<UiMod name="AddonName" version="1.0" date="DD/MM/YYYY" autoenabled="true">

		<Author name="Author" email="user@domain.tld" />
		<Description text="What the mod does" />
		<Dependencies>
			<Dependency name="EA_Some_Default_Module" />
			<Dependency name="libAddon" />
		</Dependencies>
		<Files>
			<File name="Source\AddonName.lua" />
			<File name="Source\AddonName.xml" />
		</Files>
		<OnInitialize>
			<CallFunction name="AddonName.Initialize" />
			<CreateWindow name="AddonNameWindow" />
		</OnInitialize>
		<SavedVariables>
			<SavedVariable name="AddonName.SomeTableOfVariables" />
		</SavedVariables>
                <OnUpdate>
                        <CallFunction name="AddonName.OnUpdate" />
                </OnUpdate>        
		<OnShutdown>
			<CallFunction name="AddonName.Shutdown" />
		</OnShutdown>
	</UiMod>
</ModuleFile>

Details

A note on XML

The .mod file is an XML file, which means that it is based on tags. Generally, tags take one of two formats - either a single-tag format like <TagName param="value" param2="value2" />, or a double-tag format like <TagName>...(other stuff)...</TagName>. One can usually replace a double-tag format with no inner content with a single-tag format of the same tagname, i.e. <TagName /> is identical to <TagName></TagName>.

Valid .mod tags

• ModuleFile
  • UiMod
    • Author, Description
    • Dependencies
      • Dependency
    • Files
      • File
    • SavedVariables
      • SavedVariable
    • OnInitialize, OnUpdate, OnShutdown
      • SystemAction, CallFunction, CreateWindow

ModuleFile, UiMod

These two tags are required in every .mod file to enclose the rest - you can pretty much just copy them from the above example. You'll want to change the parameters to UiMod to match your addon. The addon name and version specified here are displayed in the in-game UiMod window.

Author

Use this tag to specify information about the addon's author. Possible params are name and email. The name is displayed in the in-game UiMod window.

Description

Use this tag to specify a description of your addon. Displayed in the in-game UiMod window.

Dependencies

This tagset denotes a list of addons which should be loaded before your addon is loaded (this list can include default EA addons, if your addon requires functionality from some of them to work). Each addon should be specified with an enclosed Dependency tag.

Dependency

Designed to be included inside a list specified by a Dependencies tagset, this takes a single param name which specifies an addon that must be loaded before your addon is loaded.

Files

This tagset denotes a list of files which comprise your addon. Each of these files will be loaded in the order which they appear in this list - XML files will be parsed by the parser, and Lua files will be run as Lua scripts when loaded. Each file should be specified using a File tag.

File

Used inside a Files list, this specifies an individual file to load. Takes a single param name which provides the path of the file to load, relative to the base directory of the addon. If you have a Sources folder that contains your Lua files, you'd use name="Sources\MyFile.Lua" or similar.

SavedVariables

Specifies a list of variables that should be persisted across interface loads.

SavedVariable

Each of these entries (within a SavedVariables list) specifies a single global Lua variable that should be saved and restored from each session to the next. Tables can be saved as well, so you can create a single table variable to use for all of your saved settings if you wish (and its the preferred practice, to keep pollution of the global namespace to a minimum). Takes a single param name which is the name of the variable to persist. (If there was no saved value for the variable, it will be nil on load, which your code should look for an initialize with a proper default.)

OnInitialize, OnUpdate, OnShutdown

These three tagsets allow you to specify tasks that should be performed on certain conditions. OnInitialize specifies a task list to perform when initializing addons, OnShutdown when closing down the interface, and OnUpdate for periodic update events. Please use OnUpdate with caution, as it is called every frame. There are various options for what can be included in these task lists:

CallFunction

Adds a task to the list to call a given Lua function. Takes a single param name which specifies the entire name of the function, including any necessary dot notation (but not including the parentheses). For instance, many addons will define an "Initialize" method of their object, which would be called as in the example. If a function is called from the OnUpdate task list, it will be based an argument equal to the number of seconds elapsed since the last OnUpdate event.

CreateWindow

Adds a task to create a window. Required param name which must be equal to the window name specified in XML for that window and an optional boolean param show which can be set to false to have the window be hidden at creation.