AddOn Studio for World of Warcraft Tutorial

Overview

AddOn Studio for World of Warcraft is a sample implementation of an isolated Visual Studio Shell that provides World of Warcraft addon developers a tool to easily build addons.

Tutorial Topics

Introduction

Internals of a World of Warcraft AddOn

AddOn Studio

Creating a World of Warcraft AddOn

Deploying a World of Warcraft AddOn

Testing a World of Warcraft AddOn

Creating an Ace2 World of Warcraft AddOn

Extending AddOn Studio for World of Warcraft

Additional Documentation

Introduction

AddOn Studio for World of Warcraft leverages Microsoft Visual Studio 2008 (VS2008) and enables hobbyist coders and gamers to develop addons for World of Warcraft, produced by Blizzard Entertainment. The addons created with AddOn Studio allow the developer to implement a graphical user interface as well as write code using the Lua programming language, a lightweight scripting language similar to JavaScript.

Internals of a World of Warcraft addon

Every World of Warcraft addon consists of a single Table of Contents (TOC) file, as well as Frame XML and Lua files. Frame XML files are ordinary XML files that express the user interface of your addon, whereas Lua files contain arbitrary code that runs when your addon is loaded in World of Warcraft. The TOC file contains the list of files that World of Warcraft should load when loading your addon and additional information, such as the name of the author and the description of the addon. For more detailed information, please refer to the Additional Documentation section.

AddOn Studio

AddOn Studio is where you develop the graphical user interface (GUI) and the code to implement the functionality of your addon. In the following illustration, click on the different parts of the development environment to read a brief introduction of them. For more detailed help, please refer to the Microsoft Visual Studio 2008 documentation.

FrameXML Visual Designer

This is the visual representation of the user interface of your addon as it would appear in the game, and also where you place the visual elements of your addon. Select the visual controls from the Toolbox. To change the properties of a control in the designer, select it and change its properties in the Property Grid.

Toolbox

Here you find the visual controls you can use to compose the graphical interface of your addon. Using the mouse, select a control from the toolbox and drag-and-drop it onto the Visual Designer surface.

Solution Explorer

The projects contained in the currently loaded solution are shown here, along with all their associated files. You will most often use this pane to deploy the addon you've created and change its properties, as well as open the files you want to work with. For more information, please refer to the Creating a World of Warcraft AddOn and Deploying a World of Warcraft AddOn sections.

Property Grid

Here you can change the properties of the control that is currently selected in the FrameXML Designer. You will also use it to view the existing event handler functions of the selected control, and to create new event handler functions. For more information, please refer to the Creating a World of Warcraft AddOn section.

Code Editor

Use the Lua programming language to implement the addon's functionality and logic. For Lua language reference resources, please refer to the Additional Documentation section.

This code editor supports IntelliSense, which is a form of automated auto-completion used in Microsoft Visual Studio that makes programming language references easy to access while coding. You do not need to leave the Code Editor pane to search on language elements (members, parameters, operators, brace matching, etc.). You can find the information you need, insert language elements into your code, and have IntelliSense complete the typing for you.

Menus and Toolbars

Standard menus and toolbars of Visual Studio 2008. For more detailed help, please refer to the Visual Studio 2008 documentation.

TODO: Explain custom menus and toolbar buttons, if any.

Creating a World of Warcraft AddOn

The following instructions walk you through the steps of creating a simple yet functional World of Warcraft addon. After completing these steps, go to the next section for instructions on deploying your addon.

Follow these steps to create an addon using AddOn Studio:

  1. In the Windows Start menu, select Programs, AddOn Studio for World of Warcraft, and then click on the AddOn Studio for World of Warcraft shortcut to launch AddOn Studio.

  2. In the File, menu select New, and then Project to create a new World of Warcraft AddOn project.

  3. In the New Project window that appears, select the "Basic Warcraft Addon" template, enter the name of the new project (e.g. name it "MyFirstAddOn"), and select the location where you want to store all the files associated with this project and the solution created for it.

  4. Click OK. The new project shows the visual designer and the user interface of your addon, where you can add various controls selected from the Toolbox. By default, a single frame named Frame1 is shown, which you may resize and move using the mouse, or change any of its properties using the Property Grid.

  5. By default, Frame1's position is stationary on the gamer's screen, so to make the addon movable, click the icon and then click on the Make frame movable option.

  6. Using the mouse, select the FontString control from the Toolbox and drag it to Frame1 to create a label.

  7. To change the text it displays and its other properties, select the FontString1 object and use the Property Grid. For example, change the "text" property to show "Hello world!".

  8. Now let's add a button below FontString1. First, using the mouse (or the Property Grid), resize Frame1 to allow space for the button.

  9. Select the Button control from the Toolbox and drag it to place it anywhere on Frame1. Using the mouse and/or the Property Grid, resize it, move it, change its background and foreground colors, change its label, or any other properties, as you like.

  10. Now that the user interface of this simple addon is ready, let's add some code to the project. Double-click on an empty area of Frame1 to create the OnLoad event handler function for this frame. The Code Editor appears where the Frame.lua source code file is loaded and is ready to use for adding code for this addon.

  11. In the body of this function, enter the following line of code, which will register for the PLAYER_TARGET_CHANGED event that we are interested in.
    this.RegisterEvent("PLAYER_TARGET_CHANGED");

  12. To handle the PLAYER_TARGET_CHANGED event, you will need to define a handler function for the OnEvent event. To do this, return to the visual designer by clicking on the Frame.xml [Design] tab and select the Frame1 object using the mouse.

  13. In the Property Grid, under the Events category, you can see which events have handler functions defined (highlighted in red in the screenshot below), and here you can also create a new event handler function. To write some code to handle the PLAYER_TARGET_CHANGED event we registered for in an earlier step, create a new handler function for the OnEvent event by selecting the event and clicking on the Create button in the drop-down list (see illustration below).

  14. The Code Editor pane reappears where you can enter the code that will be executed when an event is triggered.

  15. In the body of the Frame1_OnEvent function, enter the following code, which will change the text property of the FontString1 control to a message that includes the name of the current target in World of Warcraft whenever the player changes its target:
    if (event == "PLAYER_TARGET_CHANGED") then
    FontString1:SetText("Hello " .. UnitName("target") .. "!");
    end

  16. Now, for the Button1 control (i.e. the Close button), let's create an event handler function that hides this addon. Return to the game environment by clicking on the Frame.xml [Design] tab and select the Button1 control using the mouse. In the Property Grid, under the Events category, select the OnClick event, and in the drop-down list click on the Create button. You can also create this event by double-clicking on the button in the visual designer.

  17. The Code Editor appears where, in the body of the Button1_OnClick function, enter the following code, which will hide the addon (i.e. the Frame1 frame) whenever the Close button is clicked:
    Frame1:Hide();


  18. This addon is now ready to perform some simple functionality in World of Warcraft, but before deploying it, let's change the project's properties to something meaningful. In the Solution Explorer, right-click on the name of the project (i.e. MyFirstAddOn) and then click on the Properties item in the context menu that appears.

  19. The General properties pane appears where you should enter the details of this addon. The details you enter here are used to generate the table of contents file (a.k.a. the TOC file) so you do not need to modify it directly. Of course, you only need to provide personal details if want to.

  20. Save the project and all its files by clicking the icon on the toolbar.

Deploying a World of Warcraft AddOn

To deploy an addon using AddOn Studio, open the addon's solution in Visual Studio (if it is not already open), in the Solution Explorer right-click on the project you want to deploy (in this case MyFirstAddOn), and then click on the Build item in the context menu that appears. The AddOn Studio will go ahead, generate a TOC (table of contents) file and copy all the necessary files to the correct directory under the "World of Warcraft Installation Path" that is set for the project. For detailed information on creating an addon and setting project properties, please refer to the Creating a World of Warcraft AddOn section.

Testing a World of Warcraft AddOn

To test an addon, deploy it using AddOn Studio, launch World of Warcraft and log on. You can enable or disable the addon by bringing up the AddOn List using the AddOns button in the lower left corner after you have logged in and selecting the checkbox next to it. Alternatively, you may click on the Enable All button.

Notice the information displayed when you move the mouse over the addon. These project details are stored in the table of contents file contained in the addon's project. For more information about changing the project details, please refer to the Creating a World of Warcraft AddOn section.

Click Okay and press Enter World to start playing the game. The addon will automatically show up on the game's interface.

To test the features of the addon created in this tutorial:

Creating an Ace2 World of Warcraft AddOn

The following instructions walk you through the steps of creating a simple yet functional World of Warcraft addon based on the popular Ace2 framework. More tutorials can be found here.

Follow these steps to create an addon using AddOn Studio:

  1. In the Windows Start menu, select Programs, AddOn Studio for World of Warcraft, and then click on the AddOn Studio for World of Warcraft shortcut to launch AddOn Studio.

  2. In the File, menu select New, and then Project to create a new Ace2 based World of Warcraft AddOn project.

  3. In the New Project window that appears, select the "WowAce Warcraft Addon" template, enter the name of the new project (e.g. name it "HelloAce"), and select the location where you want to store all the files associated with this project and the solution created for it.

  4. Click OK. The new project shows the code editor with the skeleton of an Ace2 addon.

  5. We can use the OnInitialize method of the class to initialize our addon, subscribe to events, etc. The OnEnabled and the OnDisabled methods are called by the Ace framework when the addon gets enabled/disabled. This sample addon will display the name of the current Zone the player is in, so we need to respond to the zone changing events in order to update our UI. There are two events we are interested in: ZONE_CHANGED and ZONE_CHANGED_NEW_AREA.

    Event handling is very straightforward. We need to call the RegisterEvent method to indicate we want to be notified when the event fires and we need to declare a method in our addon with the same name as the event.

    Everything else is handled by Ace.

  6. We need a Frame to display the current zone name, so let's add a Frame to our project. Bring up the context menu in the Solution Explorer and choose Add/New Item...

    Select the Frame in the Add New Item dialog box.

  7. Drop two FontString instances to the Frame from the Toolbox and arrange them. The first one will display a static text ("Welcome to"), while the second one will show the zone name. Change the Name property of the second FontString to "$parentLocationLabel". $parent is substituted by WoW and it is always the name of the parent object. In our case the real name of the FontString will be MainFrameLocationLabel.

  8. Change to the Code View of the MainFrame. (Open MainFrame.lua in the Solution Explorer.) Add the following code to the Lua file. This will be a simple helper function which lets us to change the LocationLabel's text from the AddOn.

  9. Deploy the addon into World of Warcraft then launch the game. You'll see a new Frame which always displays your current location: