Older version (diff) | current version (diff) | Newer version (diff)
Interface Customization
| Contents [hide] |
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)
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.luaYou 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.luaNow 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!
- Once logged in, and in the game world, hit ESC to open your main menu and go to "Video Settings".
- Check off "Windowed" mode so that you can work with both the World of Warcraft game on your desktop, and your text editor.
- Once WoW is in Windowed mode, open your text editor so that both are visible on your desktop.
- 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 mmc = CreatFrame("Frame", nil, Minimap)
mmc:SetWidth(125)
mmc.SetHeight(15)
mmc:SetPoint("BOTTOM", 0, -10) -- Puts our frame at near the center bottom of the Minimap down 10 pixels from the bottom of the Minimapmmc.coord = mmc:CreateFontString(nil, "OVERLAY")
mmc.coord:SetFontObject(GameFontNormalSmall)
mmc.coord:SetJustifyH("CENTER") -- Sets the text justification
mmc.coord:SetPoint("CENTER", 0, 0) -- Puts the text dead center in our frame element
What we've done first is created a frame element that uses the Minimap as a parent. This means if the Minimap hides or is altered, our element with hide or alter with it. We've localize our element frame with a easy string mmc we can reuse throughout our LUA file. Making it "local" means that this mmc string will only be usable in this LUA file only and will not exist anywhere else. This helps ensure that other AddOns do not accidentally interact with your AddOn. We've also given our frame a width & height, and placed our frame where we want it to appear in association to the Minimap.The mmc.coord creates a sub-element associated to the mmc element that you can again reference throughout your LUA file and it will remain unique to the mmc element which is localized to this LUA file. We've defined this sub-element by creating a new FONTSTRING associated to the mmc element that we can use to insert text into. We have not named the FONTSTRING because we will not be accessing it outside of this LUA file (see nil), and we've set it as an OVERLAY so it stays on top of the Minimap frame.
Next, we've associated some font attributes to the FONTSTRING we created. Without font properties, you cannot actually add text to the FONTSTRING because the game engine doesn't know how to actually produce it without this information. Using the :SetFontObject() API, we can define an already existing font style associated to the game interface. Once we've done this, we're ready to input some text into the element! We've also set the text justification and set a location for the FONTSTRING to reside, otherwise it would just float in space and not show anywhere.
Using your UI element
The WoW game interface works with Events produced by the game engine. These are simply defined as events that happen when a certain condition is met. For example, if you kill a mob, loot it, and get money...when the money enters your inventory the event PLAYER_MONEY fires in the game engine to indicate your currency amount has updated. We will not be using Events with this AddOn, but with some research, you could.
Instead, we will be adding an "OnUpdate" script to our element that will simply update the coordinates in the text. Add the following:
mmc:SetScript("OnUpdate", function()
local x, y = GetPlayerMapPosition("player")
local posX, posY = abs(x*100), abs(y*100)
mmc.coord:SetFormattedText("%.1f, %.1f", posX, posY)
end)
Here we gather the player location information via the GetPlayerMapPosition() API, and then translated it into a usable format in the next like by multiplying it by 100 to move the decimal point. Next, we use SetFormattedText() to create a usable text string that we can insert into our FONTSTRING element. Now, when this frame updates, it will constantly keep the coordinate values up to date and current to what is true of your location. Your final LUA file should look like:
local mmc = CreatFrame("Frame", nil, Minimap)
mmc:SetWidth(125)
mmc.SetHeight(15)
mmc:SetPoint("BOTTOM", 0, -10) -- Puts our frame at near the center bottom of the Minimap down 10 pixels from the bottom of the Minimapmmc.coord = mmc:CreateFontString(nil, "OVERLAY")
mmc.coord:SetFontObject(GameFontNormalSmall)
mmc.coord:SetJustifyH("CENTER") -- Sets the text justification
mmc.coord:SetPoint("CENTER", 0, 0) -- Puts the text dead center in our frame element
mmc:SetScript("OnUpdate", function()
local x, y = GetPlayerMapPosition("player")
local posX, posY = abs(x*100), abs(y*100)
mmc.coord:SetFormattedText("%.1f, %.1f", posX, posY)
end)
Check to make sure it works by saving the LUA file and reloading your UI in-game. If it does, congratulations! You've successfully created your first simplistic AddOn usable in World of Warcraft! There's obviously immeasurable amount of additional things you can do that are much more advanced than this, but this is a stepping stone into the world of AddOn creation. Note: This code has not currently been tested in the current 2.4.2 version of the game and is not guaranteed to work at this immediate moment. I will game-test this code shortly to ensure it's accuracy.
Authoring Resources
- LUA Website
- SciTE-WoWInterface WoW-specific LUA/Script Editor
- WoW Compares Interface Patch Tracker
Helpful Authoring Macro's
Interface Reload
/console reloaduiThis 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).
|
