This guide provides a reference that will help you to write a simple working WoW addon using the Ace3 framework libraries. With the foundations properly in place, you will then be able to extend your addon in all kinds of ways, subject only to your own imagination and ideas.
For the purposes of this guide, we’re going to create an addon called “DemoAddon” which will simply print the message “Hello World!” in the chat window whenever we first login to the game or reload the user interface thereafter.
To create any addon, we need to first put all the key elements in place that WoW requires so that our code will be understood by the game as an addon and loaded when the game loads. At its simplest level, this means we need a folder for our addon which will contain a “Table of Contents” file and our addon’s main code-file.
First locate the folder where your WoW installation is located. You should have a folder within the WoW installation folder called “Interface” and inside that folder there should be a further folder called “Addons”. Ensure these folders exist by creating them if necessary. Now create a folder inside the “Addons” folder called “DemoAddon”. This is your addon’s dedicated folder and we’ll work on it from here for convenience.
Within the “DemoAddon” folder, we’re going to create the following plain text files.
- DemoAddon.toc
- DemoAddon.lua
The first of these two files is known as the “Table of Contents” (aka: toc) file. It essentially just contains meta-data about your addon so that the game can understand what it is (‘an addon’), what version of the game it is compatible with, what it’s called and how to run it.
Listing 1 below shows the contents of our example TOC file. Copy/paste the contents of listing 1 into your “DemoAddon.toc” file. Remember to replace the “Your-Name” and “your.name@your.name.com” values with your own name and email address. you may also need to update the ‘interface’ number from ’40100′ as it’s given here. This number refers to the version of WoW with which the addon is compatible. A value of 40100 translates to patch 4.1 and its minor derivatives. 40200 would translate to patch 4.2 and its derivatives and so on. Just lookup the current version number for WoW addons via WoWWiki and replace
Listing 1: DemoAddon.toc
## Interface: 40100 ## Title: DemoAddon ## Notes: A simple demonstration addon. ## Author: Your-Name ## Version: 1.0 ## X-Email: your.name@your.domain.com ## OptionalDeps: Ace3 ## SavedVariables: DemoAddonDB #@no-lib-strip@ LibsLibStubLibStub.lua LibsCallbackHandler-1.0CallbackHandler-1.0.xml LibsAceAddon-3.0AceAddon-3.0.xml LibsAceDB-3.0AceDB-3.0.xml LibsAceConsole-3.0AceConsole-3.0.xml LibsAceEvent-3.0AceEvent-3.0.xml LibsAceLocale-3.0AceLocale-3.0.xml LibsAceGUI-3.0AceGUI-3.0.xml #@end-no-lib-strip@ LibsLibDataBroker-1.1LibDataBroker-1.1.lua LocalisationenUS.lua DemoAddon.lua
Examining the structure of the ‘.toc’ file shows that the first part is a list of meta-data items in “key: value” format. The meta-data items included in our example are the most common items required by WoW for our addon to function properly and should be left intact.
The next section contains a block of references to library (aka: Lib) files that our addon will need to refer to in order to function. It is not necessary to refer to other ‘libs’ if you only wish to write a bog-standard WoW addon but we’re writing an Ace3 based addon so we need to refer to the Ace3 library files. In our example, we’ve quoted most of the most commonly used Ace3 library files for convenience later.
We’ve also referenced the LibDataBroker library so that we can choose later on to build in support for ‘LDB’ integration of our addon. Should we decide later on that we’d like our addon to be able to appear on menu-bars or button-bars or to be able to supply output to various other ‘viewer’ addons, the LDB library makes that relatively simple to do in a nice standardised way which means other players will be able to “plug” our addon into their existing user-interface in the most convenient and pleasing way they prefer.
Next we’ve referenced a ‘localisation’ file from our “.toc” file. This file will nominally contain all the text we want our addon to output to the player when it’s working. By placing all the text in a single file to be referenced in a standard manner by our addon, it allows you or other contributors to later create alternative localisation files with the text translated into other languages. This makes your addon ‘international’ in its design which, given that WoW is played all round the world, is a good thing.
Finally, the “.toc” file references the “DemoAddon.lua” file that contains the main code of our demo addon. We’ll come to describe this file shortly but first, we’ll setup the localisation file because it’s pretty quick and easy to do.
Inside the main ‘DemoAddon’ folder, create a new folder called “Localisation” and then create a plain text file inside the ‘Localisation’ folder called “enUS.lua”.
Listing 2 shows the contents of our localisation file; “enUS.lua”.
Listing 2: enUS.lua
-- ============================================================================
-- == AceLocale Localisation File - enUS (US English Locale). ==
-- ============================================================================
local AceLocale = LibStub:GetLibrary("AceLocale-3.0")
local L = AceLocale:NewLocale("DemoAddon", "enUS", true)
if not L then return end
-- ============================================================================
-- == Localisation Data. Format: L["keyname"] = "value" ==
-- ============================================================================
L["welcome-message"] = "Hello World!"
Looking at the contents of the localisation file, you will note that lines beginning with “–” are comments, following the normal conventions of the LUA scripting language. This file creates a reference to the AceLocale library used to provide localisation functionality and then instantiates (fancy word meaning ‘creates a new instance of’) a locale object (or data-structure etc) which will be named “DemoAddon” and will contain data in the “enUS” language.
Finally, our one and only locale string is created in which the key “welcome-message” is associated with the value “Hello World!”. That’s all there is to creating a localisation file. We’ll see in the next section how to reference our localised data from our main addon code file.
Listing 3 shows the contents of our main addon code file; “DemoAddon.lua”.
Listing 3: DemoAddon.lua
-- ============================================================================
-- == DemoAddon - Our first addon. Prints "Hello World!" when loaded. ==
-- ============================================================================
DemoAddon = LibStub("AceAddon-3.0"):NewAddon("DemoAddon", "AceConsole-3.0", "AceEvent-3.0")
local L = LibStub("AceLocale-3.0"):GetLocale("DemoAddon")
-- ============================================================================
-- == OnInitialize() ==
-- == ==
-- == This function is called when the addon is initialised. ==
-- ============================================================================
function DemoAddon:OnInitialize()
end
-- ============================================================================
-- == OnEnable() ==
-- == ==
-- == This function is called when the addon is enabled. ==
-- ============================================================================
function DemoAddon:OnEnable()
DemoAddon:PrintMessage(L["welcome-message"])
end
-- ============================================================================
-- == OnEnable() ==
-- == ==
-- == This function is called when the addon is disabled. ==
-- ============================================================================
function DemoAddon:OnDisable()
end
-- ============================================================================
-- == PrintMessage() ==
-- == ==
-- == This function prints the value of 'messageText' to the chat window. ==
-- ============================================================================
function DemoAddon:PrintMessage(messageText)
print(messageText)
end
Finally, we’ve got to the most important file in our addon. The first line of our addon code file declares a reference for a new Ace3 addon called “DemoAddon” will also refer to the ‘AceConsole’ and ‘AceEvent’ libraries of the Ace3 framework. Next we declare a local reference ‘L’ that we’ll use to retrieve localised data from our localisation file that we created from listing 2 above.
The rest of our addon code file consists of function declarations. The first three functions are special functions that are often present in all such addons. They are called automatically when the addon is initialised, enabled and disabled.
If you want your addon to perform some task automatically when the user first logs into WoW or whenever they reload their UI, then you should place the task into the OnEnable function. You’ll note that we’ve made a call to our ‘PrintMessage’ function from the OnEnable function. We’ve told the addon to retrieve the localised data stored under the “welcome-message” key and send it to the PrintMessage function.
The addon is nearly ready to be run. The last thing we need to do before we’re finished is to download the Ace3 framework libraries that our addon references. Inside the main ‘DemoAddon’ folder, create a new folder called “Libs” and then download and install into this ‘Libs’ folder each of the Ace3 libraries.
- LibStub
- CallbackHandler-1.0
- AceAddon-3.0
- AceDB-3.0
- AceConsole-3.0
- AceEvent-3.0
- AceLocale-3.0
- AceGUI-3.0
- LibDataBroker-1.1
Great! You are now ready to run your addon for the first time. All you should need to do is to close down WoW (if you’re running WoW) and then restart the game. Once it loads, choose a character, enter the game and watch your chat-window carefully. You should see the phrase “Hello World!” scroll by. Congratulations. You’ve just written your first WoW addon. Well done!