Your last addon: Babysteps with Lua

AbstractThis guide will help you learn modifying the default UI in World of Warcraft. As a step on the way you will learn about the basics of the simplistic programming language Lua. However, you will not do any programming, just some configuration changes. The guide will help you get started and prepare you to take the dive into making your very own interface.

0 Introduction

The goal with this guide is to give the reader a better understanding of the World of Warcraft default UI, and the configuration possibilities within. More specifically you will learn how to alter the default user interface through the use of Lua.

"But why would I do that‽"- I'm so glad you asked...

A lot of the most popular addons are not doing anything besides presenting data, which we already have available through the default ui, in a new way. It is information like current amount o health points of you or your enemy, mana pools, buff durations or what have you. So, addons are not bringing anything new, in terms of information on the UI, to the table. What they offer is easy customization.

But that ease of customization comes with a prize. You have to keep your addons updated. The addons will take up resources that your computer could have spent on increased FPS (precious FPS!).

Some may say, that some addons make the UI more pretty... Go play some Ponyville - SHOO!

If you learn to customize the default UI through Lua code, you will no longer have useless addons cluttering up precious resources and you will no longer have to update broken addons every time a patch hits. And frankly, doing modifications with Lua is not all that hard.

0.1 Tools of the Trade

All you need to get started is a proper text editor. And no, MS Word is NOT a text editor. For Windows users Notepad should do the trick, and for Mac users there is TextEdit.

I would recommend getting a text editor with syntax highlighting for Lua, as it will be considerably easier to spot syntax errors with that, and thus you will save yourself a lot of headaches. It have been a few years since I've been working from a Windows environment, but was using EditPlus back then. On Mac I would recommend TextMate for anyone, any day.

0.2 A brief introduction of myself

I am a young man living in Copenhagen, Denmark. I have been studying Computer Science at the university in a few years, but changed subject recently. I am not very experienced with Lua, but I have a strong theoretical background and years of experience with programming from other languages.

I have been interested in getting more familiar with Lua in quite some time, but I have not really gotten around to it until now. World of Warcraft addons seemed like a good place to start. And I thought that I might as well share some of my recently gained insight with the rest of you.

What you can expect from this guide

If you have any experience with programming at all, you will pick up the basics of Lua in no time. Even if you have never thought of playing around with programming before, you should be able to modify the user interface when you have read this guide.

In this guide I will not go much further than explaining the key concepts of customizing the UI. Moving around frames and resizing them. I will however, if there is any interest in the community, write another guide that goes a bit more in depth. I'm thinking a simple cool down monitor, or something similar. Let me know in the comments :-)

1 Breaking Down The Default UI

What is "the default ui"? To answer that question I have to explain what a UI even is. A User Interface is the part of the program that the user is interacting with. Imagine that you are playing World of Warcraft - you look around in the world - everything that is not moving with the rest of the world is part of your UI. Health bars, mana bars, action bars, buff icons, the minimap and what not. All those elements are layed out atop of the game world - just like having sunglasses with a screen on the inside showing you information (like Tom Cruise in the opening scene of Mission Impossible 2)

The UI consists of all the before mentioned elements. Every element is build up by one or more frame. Each frame can contain other frame or content in the form of graphics or text or nothing.

Try to log into world of warcraft and type the following command in the chat:/framestackYou should see a tooltip appear in the corner. (Either bottom left or top right corner depending on where you put the mouse)

In the top right corner you see a coordinate set. The left bottom corner of the screen is 0,0 and the right top corner something like 1200, 768. Theres numbers are interesting when we want to place stuff. Beneath that you will see a list of names that at first may not give much sense. What it is telling us is what frames you are hovering - nothing more - nothing less.

Framestack is a default-ui-hackers best friend.

1.1 Our first move

Now - lets get dirty. The first thing I'll show you is how to scale up a frame. If we wanted to have a larger player frame we would start with finding the name of the frame containing our portrait, health bar and energy/mana/rage/runic power bar using the before mentioned /framestack command.

I am going to give you an example to put in your chat box right away:/run PlayerFrame:SetScale(2)

When you have pressed return, you should see your player frame doubled in size. Try doing the same with your targets frame.

You could save those commands as macros to avoid having to write them each time you log in. But you should not do that. You should write your own addon instead.

2 Reconstructing The Default UI

Lets shut down World of Warcraft for a second, shall we? I promise you will get to open it again soon! (Notice the missing TM!)

Now call down! I know that all that talking about writing addons, programming and shutting down WoW may sound intimidating, but hold on. It is not all that bad.

Before we get back into WoW we only have to do a few things:

Create a folder in the Addon folder (Wow-folder/Interface/AddOns/). What it is named is not important. You can choose yourself - in this example I'll call it "MyOwnAddon".

Inside that folder you create 2 new files using your PLAIN TEXT EDITOR. One named MyOwnAddon.toc and one named MyOwnAddon.lua

The surname of the file (.toc) stands for Table of Contents and that is what it is. It tells WoW what your addon is and what should be loaded. The above is a absolute minimum of contents in that file. You can change the information to whatever you want - but you cannot change the format. Ie. you can change ## Author: Your Name into ## Author: John Doe - but not into ## Builder: Bob.

The first line is the title of your addon - what will appear in the Addon management interface on the character screen.

The second line is the description, which will appear in the tooltip under the title in the addon interface.

The third line is your name.

The fourth line is the interface version. WoW will per default not load outdated addons. As of know the most recent patch is 4.2 and that is written as 40200. You do not need to update this very often, as they almost never make significant changes to how Lua work. If your addon someday stop working, it is due to major changes in the default UI.

The fifth line is the version of your Addon. You can set it to any number you wish.

The last line references the lua file in which we will do our customization, and tells WoW to load the Lua code in that file.

The MyOwnAddon.lua file can contain any code that you can run via /run commands in the chat. So we could for example put the player frame script into the lua file:PlayerFrame:SetScale(2)TargetFrame:SetScale(2)

NOTE: There is two ways of separating commands in Lua; 1) Separation by line breaks like in the above example. 2) Separation by semi colon as in the below example.PlayerFrame:SetScale(2);TargetFrame:SetScale(2)

Both things work equally well. However, the semicolon is most often used in /run scripts and not very often in lua files. The reason is that the readability is a lot better when you have short lines. But when you are scouting the web for snippets you will see both ways and now you will not be confused!

NOTE: When we are talking about readability; Comments is a very important part of programming. If you comment your code well, you will be able to understand it, even if you return years later. Sadly many people do not comment enough because of laziness. So you might as well start now. Comments in Lua are noted as two dashes at the start and ends at the next line break. Examples:-- Making the PlayerFrame biggerPlayerFrame:SetScale(2)

TargetFrame:SetScale(2) -- Doing the same to the TargetFrame!

Now you should have the two files in your folder and you are ready to start WoW. Start with logging in and check if your addon is present in the addons list. If it is not, then you probably have some naming inconsistencies in your files. It is important that your .toc file is named the same as the directory.

From now on, you do not have to close WoW again. When you make changes to the .lua file, you can reload it by typing /reload in the chat. However, you have to relaunch wow if you add additional .lua files to the .toc file. But you should not do that at the moment, as that is beyond the scope of this guide.

Try adjusting the scale up or down until you are satisfied. Just for the practice.

2.1 The Basics

Before we proceed I will give you a template to use. I must admit that this may not be the ideal solution, but it works and I have yet to come up with something smarter. One of the first problems I experienced is that your customizations will disappear or not persist. To solve this, we have to add an event handler - it is a bit more complicated than the rest, so just take it and leave it. You do not need to understand this part. What we are doing is adding an empty frame, that will reload our settings if WoW chooses to override them with defaults.

NOTE: I have not been able to figure out what elements that need to be within our bogusFrame. Castbars and PvPicons do not need to. You can place all your code inside that wrapper template if you wish. If you find snippets of Lua code from other sources it is best to test them outside the template first, and then put them inside the wrap if they do not persist. I will update this when I get to the bottom of it. (If you can fill me in feel free to comment.

3 Commands

I feel that you are tired of scaling the target and player frames now, so lets get on with some movement instead.

You can find the frame names using /framestack as described earlier, so I will give you a list of commands and a description of what they do and how to use them. I trust that you can find the names yourself. If you take PlayerFrame:SetScale(2) as an example: PlayerFrame is the name of the frame you want to work with, SetScale() is the command, and 2 is the input to the command.

3.1 SetScale

Makes the scale of the frame and all frames within it into the new scale given as a argument.Example:SomeFrame:SetScale(1.5)

3.2 ClearAllPoints

Resets all anchor points of a frame. If you do not seem to be able to move a frame, you just have to call this method on the frame before you use SetPoint.

SomeFrame:ClearAllPoints()

Sometimes it is needed and sometimes it is not.

3.3 SetPoint

Sets a new anchor point for a frame.

Can be used with a wide selection of different arguments.

SomeFrame:SetPoint(point, relFrame, relPoint, offsetX, offsetY)

Argument explanation

point: Which point of the frame you should use to anchor it. Valid values are center, bottom, top, left or right. This argument must be specified.

relFrame: Relative Frame. What frame should it be anchored to. Most of the time you will want to use UIParent as the value of this argument. But you can use any other frame, as long as its not a frame which is contained by the frame that you are positioning. If this argument is not specified it defaults into UIParent.

relPoint: The relative point of the relative frame that the frame should be anchored to. It can be center, bottom, top, left or right Defaults to the value of point if not specified.

offsetX: You can specify a offset from the anchor point, and this is the offset on the x-axis. It defaults to 0 if not specified.

3.4 SetAlpha

Takes one integer as an argument. If it is 0 its invisible, if it is 1 it is fully visible. If it is 0.5 you can see through it. You get the picture.

ExampleSomeFrame:SetAlpha(0.5)

NOTE: Using this you can turn off the annoying "Not ready yet"-text in red in the middle of your screen. Simply making the error frame invisible:UIErrorsFrame:SetAlpha(0)

4 Tips and Tricks

4.1 Define per class differences

More often than not, there are differences on how one would want his or her UI, depending on what class they are playing. This is easily done with a simple if statement in Lua. I will explain this in depth in my next guide.

local _, Class = UnitClass("player") -- getting the player class

if Class == "DEATHKNIGHT" then -- do lua magic for dksend

if Class == "ROGUE" then -- do other lua magic for roguesend

The value of the variable Class will be the name in CAPS without spaces.

NOTE: Things done outside of the if statements will affect said class anyway. So do non-class-specific stuff above the if's, so you can overwrite class-specific stuff afterwards.

External Ressources

WoWWiki is one of the best sources for documentation of WoW-specific lua methods and functions. Their search function sucks, so you are better off searching on google, like this: SetAlpha site:wowwiki.com (site: tells google only to search on that website)

This thread on ArenaJunkies contains a lot of good examples. It is a long read, but shim through it there may be something useful. There are a lot of more complicated examples as well.

There is not a lot useful information out there on this subject, and that is part of the reason I chose to write this guide. If you have any additional links, please post them in the comments.

Questions and Farewell

Feel free to post questions in the comments, I will try to answer them as much as I can. Please tell me, if you would like a more complicated guide, digging a bit deeper into the world of custom default ui scripts. I consider doing a simplistic cool down watcher for my next article if there is interest in the community. I hope you enjoyed the guide.

Commenti

Commento di asakawa

There's some great info in here but, while reading it I couldn't help thinking "This needs pictures!"the guide interface makes uploading and including images super easy so all that's left is spending a couple of hours in game grabbing screenshots.

Commento di Draikan74

Great guide, if i hadn't already found dominos i would definantly start doing this. Also thanks for introducing us to Ponyville ;) Best game evar

Commento di Tamardia

This was a very great guide .. With some minuses ... Most of it, basically everything but the 'SetScale' doesn't work. I don't know why, but even with your original configurations, it doesn't work. Is this because of the new patch?

Commento di GalacticGlum

Hey Nice Guide, I actually Wrote a guide myself on writing a basic addon here is the link if you want to check it out: