Yashima Plays

I am trying to learn to program my own addons. I’ve been installing other people’s addons for a few years now. Being a software developer I am thinking I should be able to do it myself.

Yet I am having a very hard time getting into it and there are very few tutorials especially current ones are rare. It is not trivial to learn from other people’s code either because so many addons use libraries and not all code is equal in readbility.

1) Documentation

Online you can find quite a few resources that all help in certain aspects.

I like learning from other people’s code. My best source for code so far has been Tekkub (whose code you like is very much a question of personal preference). Together with his repositories, the APIs published on WoWWiki and the Lua Manual,  I was finally able to put together a small “Hello World” style addon. One of his simplest addons is the tekJunkSeller. Just take a look at it.

For a bit of offline documentation I ordered a book about WoW addons. Actually there are several books available. I checked the table of contents and this one sounded most promising.

2) Developer Utilities

First things first: installing a few resources.  There are quite a few lua editors out there and a few other developer utilities. Here’s my current list:

• WoW UI Designer: a nice looking lua ide
• tekPad to evaluate lua code in the game.
• BugSack to be able to see errors and stacktraces (I’ve had that forever actually)
• svn repository. I already had one. I guess most people will not need revision control immediately. I do because I want to be able to access my stuff from different places.
• Macro to obtain the name of a frame/script DEFAULT_CHAT_FRAME:AddMessage( GetMouseFocus():GetName() );
• Macro to obtain an item ID /script local infoType, info1, info2 = GetCursorInfo(); if infoType == "item" then DEFAULT_CHAT_FRAME:AddMessage( info1 ); end

3) The Basic Structure

Now that your preparations are all done on to the addon programming stuff. Here’s the basic structure of the simplest WoW Addon:

• HelloWorld.toc: contains meta information on the addon. For example: name, author, website and loading information. It also has to has a “toc” = table of contents for all the files or libraries included with the addon.
• HelloWorld.lua: contains the actual code of your addon.
• You could have an xml file as well to define your frames. Personally I want to try the all-lua approach.
• Put these files in a HelloWorld folder in your Interface\Addons directory and once you filled them with content you can test your addon.

4) The HelloWorld.toc File

The toc file is more important and versatile than you would think at first. But right now I want to keep it very simple (the LineNumbers are not included in the actual file!):

1-- ## Interface: 30300
2--
3-- ## Title: HelloWorld
4-- ## Notes: Say "Hello!" to the world
5-- ## Author: Yashima
6-- ## Version: Alpha
7--
8-- HelloWorld.lua

Just a quick explanation, most of this is self explanatory.

• Line 1: contains the version of the interface this addon was written for
• Line 3-6: basic information on the addon and its’ author
• Line 8: the table of contents consists of a single file in our case

What you can also do here:

• control load on demand behaviour (nice example)
• insert dependencies or optional dependencies
• give more information on the author etc.

5) The HelloWorld.lua File

Here’s a sample file.

1-- UIErrorsFrame:AddMessage("Hello World",0.5,1.0,1.0,5.0);

As far as I was able to find out all code (except functions which must be called) in the lua file will be executed when the addon is loaded. The one line in this file will simply print a message to the in-game error frame with the AddMessage method. Of course the message here is “Hello World”. The additional parameters control the color and fade time of the message.

Of course keeping it so simple won’t get you far. Here’s another example with some very simple event handling.

1-- local function OnEvent()
2--   UIErrorsFrame:AddMessage(arg1,0.5,1.0,1.0,5.0);
3-- end
4--
5-- local f = CreateFrame("Frame")
6-- f:RegisterEvent("CHAT_MSG_SYSTEM")
7-- f:SetScript("OnEvent",OnEvent)

This code does some very simple event handling. There is a local function called OnEvent() (lines 1-3) that will be executed when the registered event(s) occur and does the same as the previous example: it prints a message to the error frame.

The lua code in the global scope that will be executed on load is found on lines 5-7. In Line 5 we create a simple frame with CreateFrame and on this frame we can register events to listen for in our case the CHAT_MSG_SYSTEM (line 6), an event that is fired when a system chat message (they are displayed in yellow) is received.This event has a single argument arg1 that contains the chat message. On line 7 we finally define that when a registered event is fired we want the OnEvent() method to be called. Since we only have a single event registered all this is pretty simple.

So here’s a tiny first addon. I will continue with this topic once I learn how to do more.