A Bare Framework

Technically, an addon only needs to have one file: the MOD file which defines some basic information about the addon. This file is an XML-type document which contains certain tags defined by Mythic. You can find a more comprehensive reference in TheWarWiki's API section here, so I'll go over the basics. In addition, most addons will also want to include some Lua and/or XML template files that provide code and layout information.

All addons are located somewhere within the directory at Warhammer Online\Interface\Addons. Most addon authors choose to create a subdirectory within the Addons folder to organize their addon's files. For instance, Warhammer Online\Interface\Addons\TimeToDie. When referring to files, all other paths are relative to the location of the MOD file.

Here's an example .mod file, this particular one is from an addon I wrote named TimeToDie.

<?xml version="1.0" encoding="UTF-8"?>
<ModuleFile xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <UiMod name="TimeToDie" version="1.0" date="12/11/2008" >

        <Author name="Aiiane" email="aiiane@aiiane.net" />
        <Description text="Data-gathering addon that tracks info about deaths." />
        
        <Files>
            <File name="TimeToDie.lua" />
        </Files>
        
        <OnInitialize>
            <CallFunction name="TimeToDie.Initialize" />
        </OnInitialize>
        <OnUpdate>
            <CallFunction name="TimeToDie.OnUpdate" />
        </OnUpdate>
        
    </UiMod>
</ModuleFile>

Let's break this down a little bit.

The pieces highlighted in blue are the generic wrapper for the data file; you can just copy-paste these into your own .mod file as they are, they don't need any modification.

The bit in red is the wrapper specifically for defining an addon. It has a few attributes which you should change to fit your addon: the name, the version, and the date. All of these are displayed when a user selects your addon from the list of addons in-game. There are two things to note here: first, the name you chose is the one that is used if anyone else wants to refer to your addon (such as if specifying it as a dependency). Secondly, if you change the version number of your addon at all, any settings stored for the addon from different versions will be reset.

The portion in green allows you to specify some additional information, for display purposes only. The author name will show up in the in-game addon window if specified, as will the description text.

The brown section allows you to specify other files (such as code files, or XML templates) to load as part of this addon. You can have as many <File name="..." /> tags (and thus as many other files) as you wish. The files will be loaded in the order they are listed, so if you have a definition in one file that you need to use in another, make sure to put the file with the definition first.

The tags in purple are specifications for what to do when certain events related to the overall addon occur. In this case, it tells the WAR client to call two functions, one once all the files for this particular addon have be loaded, and the other whenever the UI "updates" (once per rendered frame).

Adding some Lua

Once the .mod file is initially created. we probably want to add some code of our own. This is done with .lua files located within the addon's folder. Whether you put the Lua files in the same directory as the .mod or in subdirectories is up to you - just remember that when specifying the paths of code files in the mod file's <Files> section, all paths are relative to the location of the .mod file.

The first thing most addons do is create a table named after their addon that will hold the majority of their public functions and data. The reason for doing this is to keep everything compact and separate from other addons - this table serves essentially the same purpose that namespacing would in other languages.


TimeToDie = {}


After that, one can define functions that are part of that table. For instance, we can define the function that the .mod file says should be called once the addon's files are loaded:


function TimeToDie.Initialize()
-- code goes here
end


We can also use members of our main table to provide data that other code besides our addon might want to see:


TimeToDie.lastDeathTime = 0