WoW:UI beginner's guide

Reference e
AddOns WoW API Widget API XML UI Event API WoW Lua Macro API CVars Battle.net HOWTOs Snippets UI tech Categories

→ UI AddOn

← WoW AddOn

This page goes through some of the basic concepts for UI Customization and WoW development through using Macros, Scripts and AddOns.

Slash Commands

To understand how everything else works, you need to know what a Slash Command is. WoW allows you to give simple commands to the game in the form of a slash (/) followed by the name of the command. You can give these commands directly by typing them into the chat box. An example would be the "/follow" command. If you target a friendly and type "/follow" (without the quotes), you start following them. You can get a list of some of the slash commands by typing "/help".

There are several types of slash commands. Some are designed to perform game actions (e.g. /follow, /assist, /cast), others are chat related commands (e.g. /yell, /chatlist) or give you information (/who). You also have emotes (eg /laugh, /bow, /dance).

Finally, there is one very special slash command "/script", explained later.

Macros

The purpose of a Macro is to allow you to create some very simple custom actions or tasks, based on the existing game actions. A macro is just a sequence of slash commands, which are executed in order when you execute the macro. To create a new macro, either type "/macro" (without the quotes), or click on the speech bubble next to the chat box and select macro. You can then give a macro a name, an icon and type in a few lines of slash commands. The macro is created in the form of an action that you can drag onto your hotbar. You can activate the macro by clicking on the resulting button on the hotbar.

An example macro would be:

/cast Fireball(Rank 1)
/say "I am frying it!"

This macro merely casts a fireball, and then has your character tell everyone nearby that you're casting it.

Another example would be:

/console farclip 177
/cast [button:1] Hearthstone
/stopmacro [button:1]
/console farclip 1500

This macro sets your view distance to minimal, then if you left clicked your mouse uses your hearthstone and stops the macro, if you used anything but left click it continues into setting your view distance to furthest. The usefulness of this macro would be if your computer can handle max graphics every where but Dalaran and your hearth is set to Dalaran, if you have problems in Dalaran if you set the view distance to minimal before hearthing it allows a much quicker load time with no lag, the reason to make it so that if you don't left click it it sets your view to max is so that when you leave Dalaran you can click the same button to put your graphics back up to the good looking view.

Macros have some severe limitations, and are only intended for very very simple tasks. The most important limitation is that it is difficult to cast more than one spell at a time using a macro (although it is possible, using API SpellStopCasting). This limitation exists so that macros can't automate too much for you. You can have as many other commands within the 255 character limit as you like.

See also The Blizzard World of Warcraft UI & Macros Forum and HOWTO: Make a Macro

Scripts

Scripts are small computer programs that manipulate and combine a small number of objects that exist outside the script. Scripts are usually written in a scripting language, which is designed so users can quickly express those small programs in a flexible way.

(Scripting languages are a popular way to teach new programmers, so don't be afraid!)

The World of Warcraft client embeds a powerful scripting language called Lua in its client software. This lets you create specialized commands, similar to the macros described above. However, scripts can be much more complex, making decisions on what to do based on what is going on in the world rather than the fixed sequence offered by a macro.

Lua scripts are used in the following places:

• /script [command] : If you type the slash command "/script" in the chat box, you can follow it with one or more valid Lua language statements (i.e. a script), separated by semi-colons ( ; ).
• Macros: you can enter scripts as part of macros, by putting one or more "/script" commands in your macro.
• Addons: these extend the WoW client with new slash commands and often user interface elements. This additional functionality is provided through Lua scripts (containing the actual addon logic). User interface extensions are defined in XML files. (XML is, incidentally, not a programming language. It's a "mark-up" language which contains source code but can also contain media contents or structured references to external, possibly remote network media resources ... including other XML files. However, XML is stored as structured, syntactically complex text and is parsed and interpreted in ways that make it similar to a programming language).

So what can a script do? There are many resources on Lua scripts. See our page on Lua to find out more about the language. Browse the rest of the Interface Customization page for additional resources. The most important point however is that scripts are able to perform many more game actions than slash commands. This is done via a set of functions (called API or Application Programming Interface) that WoW makes available for use in scripts. There is a quite extensive list of all the API functions available for use in scripts at World of Warcraft API.

After all that explanation, here is an example of a script:

if (IsPartyLeader()) then
  ChatFrame1:AddMessage("I am the leader of my party!")
end

This script is very simple. When you execute this script, if you are the party leader, then you get a message saying you are the party leader. To use this script, you would have to do so via the "/script" command. e.g.:

/script if (IsPartyLeader()) then ChatFrame1:AddMessage("I am the leader of my party!"); end

You can type this directly into the chat box, or make that line part of a macro, so that it's reusable.

In summary: a script in WoW is a short program written in the Lua language, able to interact with the game and perform game actions. You use a script by including it as part of something else, e.g. by putting it in a macro via the /script command, or by putting it in an addon.

Note that Blizzard has taken great efforts to limit the functionality of scripts and macros to prevent players from automating too much of the game play. If too much were automated by some players then they would have unfair advantages against others in PvP and they'd be able to farm far too quickly which would cause instabilities in a realm's virtual economy (as well as potentially ruining play for other players by having too many of the materials and world drop items rapidly consumed by automated "bot" players.

AddOns

Blizzard has made the decision that the user interface of World of Warcraft is fully customizable, modifiable and extendable. This is completely legal, and is encouraged by Blizzard. A User Interface Modification (UI Mod for short) and AddOn is exactly the same thing, the difference is merely in their names. Usually "Mods" tend to refer to smaller things that only modify existing functionality of the user interface, whereas AddOns tend to add extra functionality. From here on, we will simply use "AddOn".

The user's point of view

From a user's point of view, what you need to know is that AddOns come in the form of one or more text files, ending in the ".toc", ".xml" and ".lua" extensions. These files are supposed to go into a folder called Interface in your World of Warcraft folder, or into one of its sub-folders. Usually AddOns are distributed as zip files by their authors, and you "install" them by simply unzipping them in your World of Warcraft\Interface folder.

Warning: Be very very careful with AddOns that come as executable ".exe" files. Always triple-check before you use these to make sure that they really do what they say they do, as executable files can do anything whatsoever to your computer. AddOns are supposed to be written in text format in .xml and .lua files, so that anyone can check that there is nothing malicious about them. You have no such check available with executable files. Also, since AddOns only operate within WoW, they can't harm your computer, whereas executable files can.

Having said that, some authors do distribute their AddOns as executable files. Most of the time these executables don't do any more than just unzip the AddOn's files and place them in your WoW folder in the appropriate places. Occasionally the executables are used to automatically download updated versions of the AddOn, or to upload data collected by the AddOn (for example item statistics to be put on a web-site, etc.).

Uninstalling: You can always uninstall any AddOn and reset the WoW UI to its clean default state by merely deleting or renaming the Interface, WTF, and Cache folders in your WoW folder, then restarting WoW.

The developer's point of view

AddOns mainly consist of two types of files:

• Lua files, which contain the brunt of the logic
• XML files, which define how your dialogs, buttons, etc look. These elements are commonly referred to as "Widgets".

You list these files in a TOC (Table Of Contents) file together with some additional parameters.

If you have programmed before, you may be used to having your program start, and keep running, until you don't want it to run any more. Not so in WoW. AddOns are event driven, i.e. everything that happens does so in response to an event, e.g. the user clicking one of your buttons, the client receiving a chat message, someone hitting the character, etc. Those events are delivered to widgets, and to grab hold of them, you need to embed little snippets of Lua code in the right places that calls functions in the .lua files.   It is possible to implement a whole addon in just the .xml files, but it gets clunky, and you need to HTML-encode < and > characters and so forth.

Good places here on WoWWiki to look for more information:

• Interface Customization
• World of Warcraft API
• XML User Interface
• AddOns - a guide on how to create an addon from scratch
• Category:HOWTOs
• XML Basic - needs help of pro addon developers to fill up reference

External guides:

• A Beginner's Guide to Interface Modification at mmhell.com (Marian 'Fyrn' R, Aug. 2004) - out of date
• Your first AddOn at mmhell.com - out of date

Addon packages

If you look around the forums a bit, you may see names like Titan Panel, Cosmos, and CTMod popping up. These were major AddOn packages that contained a large number of UI AddOns. Their authors often working in teams were respectable members of the WoW community who worked hard to create useful AddOns, and have bundled them together into one easy-to-use package.

Feel free to use any and all of these packages. They are legal, Blizzard allows and encourages their use, although you won't get technical support from Blizzard if something is wrong with them. There are many of these around, download and try a few of them and see if you like them. Usually the authors make these packages highly configurable so that you can adjust them to your needs.

Note: a lot of these major AddOn packages conflict with each other, so you won't be able to use them together.

Standalone addons

Standalone, pure AddOns, what is so good about them?

You will sometimes see AddOn authors being proud of their AddOn being "standalone", or "pure addon". In the past, often AddOns modified existing UI functionality by changing something in the existing, core UI files provided by Blizzard. This has led to conflicts as different AddOns all tried to modify the same file. A "pure addon" is one that does not modify any existing files, and merely adds its own files. This is a very good thing, because you can have any number of such AddOns happily coexisting side-by-side. For this reason in WoW patch 1.10, Blizzard has completely disabled the ability to change the core UI files themselves. Therefore, all modifications to the UI can now only be done via pure AddOns. (Note that this doesn't mean that existing functionality of the UI can't be modified, it just means that it has to be done via an AddOn without modifying Blizzard's files themselves).

Also, a lot of AddOns depend on other AddOns for their operation. For example, most AddOns in the Cosmos package wouldn't work by themselves, and need the whole Cosmos package to be present to work. A "standalone" AddOn is one that is capable of working by itself, with nothing more than just that one AddOn being present. Again, this is a good thing, because it allows you to pick and choose just those exact AddOns that you want, without having anything you don't want. Many addons are aware of the major addon frameworks though and can interact with them if they're present.

Having said that, from the point of view of an AddOn's author, you will find that often a lot of AddOns do very similar sort of things. It is much more easy and quick for an AddOn author to create a new AddOn if they can rely on existing functionality in other AddOns or some common core "libraries". That's why there are AddOns out there that depend on things such as the Sea (AddOn) function library, which in itself is just an AddOn. If you find an AddOn that requires some other core AddOn, don't be afraid of it. Just make sure you also download the core AddOn.

See also

• The UI FAQ
• The AddOns primer
• Category:AddOns
• Interface Customization

External links

wow.go-hero.net Available FrameXML Builds (.lua, .toc, and .xml viewer)

World of Warcraft Programming Web site for the book of the same name

WoW Mastery Full review of the LvL86 Software