Making the Game: An Introduction to the AddOn Environment

For this Making the Game entry I will be giving an introduction to the addon programming environment, and taking a look at the features that we will be taking advantage of to build our mini-game inside of World of Warcraft.  Also, I'm looking for an artist!  More info at the end of the post.

AddOn Basics
If you've played WoW for any extended period of time, it's probably a rational assumption that you've installed an addon at some point or another.  Sure there are some UI purists and maybe a small percentage of players who are still in the dark about mods, but interface customizations have become fairly commonplace now.  Though even if you've downloaded and unzipped the files from your favorite unit frame replacement or action bar mod, what are those files really doing?

The simplest (functional) addon requires two types of files: a table of contents (.toc) and a source file.  Lua code is contained in .lua files, but can also be included in the XML frame declarations in .xml files; however, most of the core code for addons will be found in separate .lua files.  XML files are typically used in addition to .lua source files to provide a clean, standardized way of declaring UI elements (frames).

The table of contents file is a short text file that lists information about the addon, such as the title, version, author, notes, etc.  The other important thing the .toc file specifies is the load order for the rest of the addon's files, as it is the first file the game looks at when it begins to load the addon.  Here is an example from Primal Defense:


This is what WoW will first see when it tries to load the Primal Defense addon.  The Interface line at the top specifies which version of the game the addon is compatible with (3.1.x), while some of the other lines are self-explanatory.  SavedVariables is a method of storing data when the player exits the game so that it can be used at a later time, and the variable name listed is generally a table value, which could be used to store a variety of things later on (settings, history data, other important stuffs).  The last lines of the file, the ones not pre-empted with ##, tell the game what other files it needs to load for the addon.  As you can see from the example, the Primal Defense .toc references an XML file, which will be loaded next.

XML is a markup language for describing data, and WoW uses it to describe UI elements that will be used in an addon.  wowwiki has a pretty good overview of XML as a whole, as well as good coverage of the elements commonly used in WoW addon development.  The Lua code (likely found in the .lua files) provides the logic for the addon, and can reference the frame elements created in the XML file as well.  These three types of files, in addition to any supplemental files (images or other media), work together to create the entire addon.

Event-Driven Programming
WoW addons are primarily event-driven, as opposed to batch or procedural programs.  Some addons may serve a very specific purpose, load and run once then finish, while the majority perform some kind of action in response to an event either from the interface or the game world.

UI frames can have a number of script handlers that will perform code based on player interaction with them.  Actions such as mousing into a frame, moving it, or clicking inside of it all call handlers for the respective frame to run code when they happen.  Snippets of code to execute when these handlers are called can be specified in the XML file in the Scripts element, or in Lua with the frame:SetScript() function (the wowwiki interface portal has a wealth of information on everything involved with addon programming, so to avoid too much clutter I'll probably end up leaving out most of the intricacies from the blog).  Since we will be creating a mini-game and aren't too concerned with what is happening in the WoW game world, these are the main events that we will be concerned with.

The other event system in WoW involves the game itself, and what is happening around the player.  Combat, looting, chat, and the auction house are just a small sample of the categories of things that can spawn event messages, which are then sent to the event script handler of any UI frames that have registered to watch for them.  At this point the addon can read the event message and determine what is happening in the game world, and do something if necessary.  We shouldn't need to worry about utilizing this too much, but it's good to know for future projects.

The Game Loop
Games aren't like programs that execute a bunch of lines of code and quit (well, technically they are, but at a higher level no), and the core of the game is generally contained within some form of infinite loop.  Two major tasks need to be handled within this loop: an update call to all of the objects in the game, which will take care of the gameplay and state of the game; and a draw call to display the new game state visually to the player.  The WoW environment takes care of some things for us, but it will still be up to us to implement our game logic.

UI frames have a script handler called OnUpdate that can be used to execute code every time the game renders a new frame.  This is where we will update all of our game objects and perform any game logic that needs to be done to change the current game state.  WoW isn't really able to help us out too much with this, but at least it gives us a nice place to put all of our update code (plus, each entry into the OnUpdate handler is provided with a reference to a variable named 'elapsed', which lets us know how long it has been since the previous frame was rendered).

As far as drawing goes, this is where we get a bit of a break.  We don't need to learn a complicated graphics API, or a native 2D API, or even call any function at all to draw!  Once a UI element (a frame, image, etc.) is created, if it has a valid size and is marked as visible, it will be drawn automatically every time the game renders a new frame.  All we really need to do is declare the images to load them in and update their positions (and/or frames if they're animated) during the OnUpdate call.

What's Next
Now that we have a feel for how the addon system works and know how to use it, the next step is to start building some of the visual elements that we'll need for the game.  This includes the layout of the game screen as well as some artwork for various objects in the game.


Speaking of art, I'm pretty terrible at it now.  I like to think that I used to be good at it years back when I used to draw and paint a lot, but anymore I just don't.  So... I'd like to put a call out to any artists who might be interested in helping out with some images for the game.  It will be a labor of love (read: unpaid), but you will have my eternal gratitude and I will be sure to include your name/email/website/whatever with the game as well as wherever it ends up hosted at.  I don't need top-notch professional art, but something simple with a fun, cartoony feel to it.  Images that will be needed are: background map, object sprites (towers, enemies), and possibly a title logo.  I'm pretty flexible at this point as to how I want things to look, so if you are interested but have a certain style please let me know anyways.  If you are interested in helping out, please send me a PM here on GameRiot, and if you have a portfolio or art samples online that you would like to show off, include links to those as well!