Interface Customization  

See also: Mods, Interface

Contents [hide]

Starting Out: Making your own AddOn Table of Contents File (.toc) LUA File (.lua) Giving your AddOn a purpose Scripting your first AddOn Create your UI element Authoring Resources Helpful Authoring Macro's Interface Reload Find Element on Mouseover

Starting Out: Making your own AddOn

AddOns for World of Warcraft are player-made scipts & game elements designed to enhance gameplay in some way. The core elements of AddOns consist of at least two primary elements, and a third optional element:

• TOC File (Table of Contents)
• LUA File (The "engine" of the AddOn)
• XML File (Optional)

AddOns can be as simple as modifying an already present element of the standard Blizzard WoW User Interface, or as elaborate as entirely new elements that consist of unique functions that help enhance gameplay in a variety of ways. Here, you will find some very basic examples of customizing some standard User Interface elements that already exist in the base WoW User Interface. But first, let's get started with some basics to make a custom AddOn that modifies the game interface.

Note: To create the files needed to make an AddOn, you can use a text editor as simple as the basic Notepad program supplied with almost every Windows application. You can also use customized text editors specifically used for creating and compiling script languages such as LUA, which you can find a few options below.

Table of Contents File (.toc)

The TOC file is used by the World of Warcraft game engine to identify & load the elements required to run your AddOn. Primary elements that are required here are the interface version, the AddOn name, and the files included you wish to load (typically at least a .LUA file). These can be added by opening your preferred text editor, and saving a new file with your AddOn name followed by .toc. For this example, we'll make a file named MyAddOn.toc. In this file, you will include the following:

 ## Interface: 24200
 ## Title: MyAddOn
 MyAddOn.lua

You can add additional fields such as "Notes" and "Author" to further specify details regarding your AddOn. Let's add some fields describing who the Author is and some notes to explain what the AddOn will do. We're going to make an AddOn that puts Mapping Coordinates on the Minimap, so:

 ## Interface: 20400
 ## Title: MyAddOn
 ## Author: <YourName>
 ## Notes: Adds coordinates to the Minimap that tell you where you are!
 MyAddOn.lua

Now save this file as MyAddOn.toc and put it in a new folder called MyAddOn. Next is the meat of the AddOn, the LUA file.

LUA File (.lua)

The LUA file is loaded by the TOC file when the game interface loads after logging on. As shown above, you have to make sure the LUA file is listed under the TOC notes so the game engine knows to load that file. Otherwise, you will see your AddOn listed in the "AddOns" screen (available at the character selection screen), but it won't do anything once you get into the game world. But we made sure to do it since it was detailed above, so we shouldn't have any problems!

We'll just put a comment in for now and save it into the MyAddOn folder. Comments used in LUA are helpful to notate things you might otherwise forget when scripting the source code for the AddOn. Also, it can be helpful to another user should they need to alter something either to their liking, or fix something that might not be working correctly. They are entirely optional, but it's good to at least put one comment at the start of the file to explain the purpose of the file. So open a new file in your text editor, and add the following:

 --[[ This is MyAddOn, it will add mapping coordinates to the game Minimap ]]

There are two forms of comments that can be used in LUA script. One, as shown above, is the block comment that begins (or opens) with

--[[

and ends (or closes) with

]]

It can consist of multiple lines between the block beginning and end. The other, which is a single line comment, consists simply of a line prefix of two hyphens "--" followed by any amount of text on that line only. Now that we've started our LUA file, let's save it as MyAddOn.lua and put it in the MyAddOn folder. Make sure your MyAddOn folder is in the ..\World of Warcraft\Interface\AddOns\ section of your game directory on your computer (the final path should look like ..\World of Warcraft\Interface\AddOns\MyAddOn\). Once it is, congratulations! The game will now load your AddOn when you log into the game.

Giving your AddOn a purpose

Now we have an AddOn that loads when you select a character to enter the game world. During that loading screen, the game engine is loading all the game world elements, including the User Interface and any AddOns in the Interface directory. But what do those AddOns do? Now we can actually do something in the LUA file that will translate into something in the game world of World of Warcraft!

One of the easiest ways to work on an AddOn is first, make sure the AddOn is loaded at the Character Selection screen. You will see a button in the lower left corner of the screen called "AddOns". Click that and make sure your AddOn is listed on the check list, and that it doesn't have any negative (red) notes such as "Outdated" or "Dependency Missing" next to it. If all is well, go ahead and enter the game world with the character of your choice. Next, there are a few things we can do to make editing your AddOn easy, and you can do it while in-game!

1. Once logged in, and in the game world, hit ESC to open your main menu and go to "Video Settings".
2. Check off "Windowed" mode so that you can work with both the World of Warcraft game on your desktop, and your text editor.
3. Once WoW is in Windowed mode, open your text editor so that both are visible on your desktop.
4. Any time you save changes to your LUA file, you can check them in-game by reloading your interface (type /console reloadui into the chat field)

The only time a /console reloadui will not work, is if you add actual file elements to your AddOn that were not present when you loaded the game (ie. a Font file, or another LUA file). Otherwise, any changes made to an already loaded file can be updated in-game using the /console reloadui text command. You might find it easy to make some helpful macro's to help with your AddOn creation effort. See Helpful Authoring Macro's below that you can add to your Action Bar and simply click for some easy in-game AddOn authoring help.

Scripting your first AddOn

Alright, so you have both World of Warcraft and your text editor open. You're ready to begin creating your first AddOn! At this point, you at least read over some of the basic information you can find at the LUA Website to get some bearing about the scripting language we're working with. If you haven't, head over there and read up a bit, and come on back once you get some basic information soaked in. If you're ready to go (or just extremely anxious to begin), let's move on!

Create your UI element

In this tutorial, we're going to create elements to use in the game world simply by using already available game elements and WoW API to handle the structure rather than creating a seperate (and optional) .XML file. We will strictly be adding an additional FONTSTRING to the MinimapCluster portion of the interface.

The Minimap already exists. We know this because we can see and interact with it in the game interface. What we need to do is add a text element to it for our AddOn to use. Start out by adding the following to your LUA file:

local addon = CreateFrame("Frame", "MyAddOnFrame", UIParent)
local coord = addon:CreateFontString("MyAddOnText", "OVERLAY")

We define addon as our main frame element, and coord as our FontString. The Frame is needed to give our FontString something to "belong" to, and the FontString is needed to create text. Next, we need to create defining situation where we want our AddOn to load.

addon:SetScript("OnEvent", event)
addon:RegisterEvent("PLAYER_LOGIN")

First, we assigned a Script property to our Frame, so that it knows to look for something "OnEvent". The event we're going to use is PLAYER_LOGIN so it fires the addon up when you log in. So in order for the Script we assigned to our Frame to fire, we need to register the PLAYER_LOGIN event to the Frame. That way, when the game engine fires the PLAYER_LOGIN event, it's going to activate the function associated to the OnEvent Script in this case, the function is called "event". Now that we have our primary setup done, we need to create the event that the Script activates, and add what we want it to do:

local event = function()
   addon:SetWidth(125)
   addon:SetHeight(15)
   addon:SetPoint("TOP", Minimap, "BOTTOM", 0, -5) -- Puts our frame at near the center bottom of the Minimap down 10 pixels from the bottom of the Minimap
   coord:SetFontObject(GameFontNormalSmall)
   coord:SetJustifyH("CENTER") -- Sets the text justification 
   coord:SetPoint("CENTER", addon, "CENTER", 0, 0) -- Puts the text dead center in our frame element
   coord:SetText("Hello")
   addon:SetScript("OnUpdate", function()
      local x, y = GetPlayerMapPosition("player")
      local posX, posY = abs(x*100), abs(y*100)
      coord:SetFormattedText("%.1f, %.1f", posX, posY)
   end)
end

Here, we're giving the addon Frame a width, a height, and setting it's location using WoW API functions. Then, we're giving the coord FontString font properties and setting it's location to the addon Frame so it exists and knows where to show on the screen. And finally, we want our text to always show the correct Coordinates. So we're using an "OnUpdate" script so that it constantly updates the coordinates text. We use the WoW API functions to get the player location, do some math to ensure it creates values we can use, and then set a formatted text string to the coords FontString with the information we've fetched. We want this portion defined prior to the OnEvent script because the function needs to exist prior the the event calling so that it can actually do something. If the function doesn't exist yet, nothing will happen when the PLAYER_LOGIN event fires. Your final LUA file should look like:

local addon = CreateFrame("Frame", "MyAddOnFrame", UIParent)
local coord = addon:CreateFontString("MyAddOnText", "OVERLAY")
local event = function()
   addon:SetWidth(125)
   addon:SetHeight(15)
   addon:SetPoint("TOP", Minimap, "BOTTOM", 0, -5) -- Puts our frame at near the center bottom of the Minimap down 10 pixels from the bottom of the Minimap
   coord:SetFontObject(GameFontNormalSmall)
   coord:SetJustifyH("CENTER") -- Sets the text justification 
   coord:SetPoint("CENTER", addon, "CENTER", 0, 0) -- Puts the text dead center in our frame element
   coord:SetText("Hello")
   addon:SetScript("OnUpdate", function()
      local x, y = GetPlayerMapPosition("player")
      local posX, posY = abs(x*100), abs(y*100)
      coord:SetFormattedText("%.1f, %.1f", posX, posY)
   end)
end
addon:SetScript("OnEvent", event)
addon:RegisterEvent("PLAYER_LOGIN")

Authoring Resources

• LUA Website
• SciTE-WoWInterface WoW-specific LUA/Script Editor
• WoW Compares Interface Patch Tracker

Helpful Authoring Macro's

Interface Reload

/console reloadui

This macro will reload the game interface, which is helpful when saving new changes to an already loaded AddOn file.

Find Element on Mouseover

/script ChatFrame1:AddMessage(GetMouseFocus():GetName())

This macro needs to be placed in an Action Bar slot that is keybound. Often you may find yourself needing to quickly identify a User Interface element or frame while in-game, and this macro can do just that. As an example, put your mouse cursor over any interactive element of your UI that you can click with your mouse cursor (ie. the Player Unit Frame). While the mouse cursor is hovering the element, activate this macro and the name of that element associated to the User Interface will print in the main chat frame (ie. you should see "PlayerFrame" in your chat window).

World of Warcraft Wikibase™