AddOn Studio for World of Warcraft Tutorial
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.
Internals of a World of Warcraft AddOn
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
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.
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 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.
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.
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.
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.
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.
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.
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.
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:
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.
In the File, menu select New, and then Project to create a new World of Warcraft AddOn project.
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.
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.
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.
Using the mouse,
select the FontString control from the Toolbox
and drag it to Frame1 to create a label.
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!".
Now let's add
a button below FontString1. First, using the mouse (or the Property
Grid), resize Frame1 to allow space for the button.
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.
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.
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");
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.
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).
The Code
Editor pane reappears where you can enter the code that will be executed
when an event is triggered.
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
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.
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();
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.
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.
Save the project
and all its files by clicking the icon on the toolbar.
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.
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:
Click on a new target. The addon should display the message "Hello <name of target>!"
Click the Close button. The addon should disappear from the game interface.
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:
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.
In the File, menu select New, and then Project to create a new Ace2 based World of Warcraft AddOn project.
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.
Click OK. The new project shows the code editor with the skeleton of an Ace2 addon.
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.
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.
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.
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.
Deploy the addon into World of Warcraft then launch the game. You'll see a new Frame which always displays your current location: