AddOn Studio for WildStar Tutorial

Overview

AddOn Studio for WildStar is an implementation of Visual Studio that provides WildStar add-on developers with an alternative, fully-featured IDE to easily build and maintain WildStar add-ons.

Tutorial Topics

1. Introduction

AddOn Studio for WildStar enables hobbyist, gamers, and seasoned developers to develop add-ons for the WildStar game, produced by NCSOFT and Carbine Studios. The add-ons created with AddOn Studio allow the developer to write code, deploy and publish WildStar add-ons using the Lua programming language, a lightweight scripting language similar to JavaScript.

2. Files of a WildStar Add-On

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

3. AddOn Studio for WildStar

AddOn Studio for WildStar, much like the built-in WildStar 'Houston' program, is where you develop the code to implement the functionality of your add-on. In the following illustration, click on the different parts of the development environment to read a brief introduction of them.

4. Creating a WildStar AddOn

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

Follow these steps to create an add-on using AddOn Studio for WildStar:

  1. Locate your AddOn Studio for WildStar install, or find any shortcut or Pinned shortcut you may have created, and then launch AddOn Studio for WildStar by launching the WildStarAddonStudio.exe file.

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

  3. In the New Project window that appears, select the "Basic WildStar Addon" template, enter the name of the new project, such as "MyFirstAddOn", and select the location where you want to store all the files associated with this project and the solution created for it. The new project location is by default a WildStarAddOnStudio folder in your normal user Documents folder.

  4. Click OK. The new project shows the visual designer and the user interface of your add-on, 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 add-on 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 add-on 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 add-on.

  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, now click the Events category button.

    Under the Events category, you can now see which events have handler functions defined.

    Here you can also create a new event handler function. To write some code to handle the PLAYER_TARGET_CHANGED event, that we registered for in an earlier step, create a new handler function for the OnEvent event by selecting the event drop-down

    and clicking on the Create button in the drop-down list.

  14. The Code Editor pane now reappears, showing the new OnEvent handler function 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 WildStar 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 add-on. 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 add-on (i.e. the Frame1 frame) whenever the Close button is clicked:
    Frame1:Hide();

  18. This add-on is now ready to perform some simple functionality in WildStar, 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 add-on. 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 main toolbar.

5. Deploying a WildStar AddOn

To deploy an add-on using AddOn Studio for WildStar, open the add-on's solution in Visual Studio, if it is not already open. (If you are continuing from the last tutorial above, your solution will already be open.)

Follow these steps to deploy an add-on using AddOn Studio for WildStar:

  1. 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.

    AddOn Studio for WildStar will then go ahead and build and deploy your add-on, coping the .toc file (table of contents) and all of the other necessary files and folders to the "Interface\AddOns" directory of your WildStar installation. This is where add-ons normally live inside the WildStar installation.

  2. The output pane will show the build and deployment progress as it runs, which should go very quickly.

    At this point your add-on is installed and up to date in WildStar, and is available like any other add-on for running WildStar.

For detailed information on "creating an add-on", please refer to the Creating a WildStar AddOn section.

Other helpful deployment options and tips:

  1. You can use Clean to also un-deploy, or remove, an add-on from WildStar.

    AddOn Studio for WildStar will then remove your add-on from WildStar, including all of it's files and folders.

    You will also need to restart WildStar to see it removed form the AddOn List on the log in screen.

6. Testing a WildStar AddOn

To test an add-on, you must first deploy it using AddOn Studio, as explained in the previous section. There are two things we can check: one is to see if WildStar recognizes our add-on and the second is to check our functionality in the WildStar game UI.

To test the installation of the add-on created in this tutorial:

  1. Launch WildStar and log on.

  2. After log on, access the AddOn List of available add-ons using the AddOns button in the lower left corner.

  3. Now make sure the new add-on is enabled. Normally, a new add-on will already be enabled after build and deploy in AddOn Studio. You can enable or disable your add-on by changing the check-box next to it. Alternatively, you can use the Enable All button to enable all add-ons, including yours.

  4. Next enter the world, by clicking Okay, which will close the AddOn List, then click Enter World which will start the regular game UI. The add-on should now automatically show in the game's interface.

To test add-on features in the game UI created in this tutorial:

  1. Click on a new target. The add-on should display the message "Hello <name of target>!"

  2. Click the Close button. The add-on should disappear from the game interface.

7. Creating an Ace2 WildStar AddOn

The following instructions walk you through the steps of creating a simple yet functional WildStar add-on based on the popular Ace2 framework. More tutorials can be found here. (note: this tutorial is for Ace2 and needs to be updated for Ace3. The links provided actually point to the current tutorials on WowAce, which refer to Ace3.)

Follow these steps to create an add-on using AddOn Studio:

  1. Locate your AddOn Studio for WildStar install, or find any shortcut or Pinned shortcut you may have created, and then launch AddOn Studio for WildStar.

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

  3. In the New Project window that appears, select the "WowAce WildStar 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 add-on.

  5. We can use the OnInitialize method of the class to initialize our add-on, subscribe to events, etc. The OnEnabled and the OnDisabled methods are called by the Ace framework when the add-on gets enabled/disabled. This sample add-on 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 add-on 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 WildStar 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 add-on into WildStar then launch the game. You'll see a new Frame which always displays your current location:

8. Additional Documentation

The following are additional resources that can be used to learn more about creating add-ons for WildStar, using AddOn Studio for WildStar, and going farther in WildStar add-on development.

Going farther:

  1. WildStar Wiki: Interface Customization
    WildStar Wiki is one of the original and most complete WildStar information sites. It hosts a large collection of information about WildStar add-on development, including a variety of well categorized documentation and help for WildStar UI development including references for the WildStar API for Lua, Form XML, the WildStar UI Widget library, and more.

  2. Carbine WildStar Forums: UI and Macro
    This is where you can get information from "the source" on API and UI development patch changes, including a good deal of technical community discussion.

  3. WowAce: Developer Home
    Home of 'AceLib', for WildStar add-on development. This site includes resources for developing 'Ace' add-ons and is home for the ace development community.

  4. AddOn Studio Product Site: Getting Started
    In-depth systems level guide and tutorial for getting AddOn Studio for WildStar up and running. This document is designed to help new users with concepts and issues surrounding managing their development tools, and provides an introduction to software development, and explicit verbose instructions for installing and setting up their tools using advanced concepts that most experienced developers would already be familiar.


Copyright © 2010-2017 AddOn Studio. All rights reserved.

AddOn Studio for WildStar is neither created nor endorsed by NCSOFT Corp or Carbine Studios. This is a third party tool and tutorial and are not supported by NCSOFT Corp or Carbine Studios. Protions of this turorial may include, in textual and/or image form, trademarks or registered trademarks of NCSOFT Corp or Carbine Studios. Portions of this tutorial may include reproductions of WildStar content and other artwork and/or otherwise elude to game functionality via "screenshot" which are property of NCSOFT Corp or Carbine Studios. "JavaScript" is a trademark of Oracle Corporation. All other trademarks are the property of their respective owners, including the WildStar icon portion of the AddOn Studio for WildStar "WildStar Add-on" icon image. NCSOFT, Carbine, WildStar and all associated logos and designs are trademarks or registered trademarks of NCSOFT Corporation in the U.S. and/or other countries. All rights reserved.