AddOn programming tutorial / Introduction Square One . You have to start someplace , and the traditional place to start is with " Hello , World " . To accomplish this first task you will need the following items : An AddOn lives in a very specific place . To find that place , first go to the WoW directory ( also sometimes called a folder ) using whatever file management software you have available . On a Windows platform , that would be Windows Explorer ( not Internet Explorer ) . The program is usually installed on the C : drive of the computer , under the directory ' s named " Program Files " or " Program Files ( x86 ) " ( on well supported 64 - bit OSes like Windows 7 ) . From pretty much any address bar , simply type " C : \ Program Files \ World of Warcraft " ( or " C : \ Program Files ( x86 ) \ World of Warcraft " ) and press enter . On a Macintosh system , you would use Finder ; and on Linux there is a similar mechanism . Whatever you use , you are looking for the installed location for WoW . This is usually at " / Applications / World of Warcraft / " on a Macintosh . Once you find the WoW directory , there is another directory called Interface and within that is another called AddOns . AddOns is the home of all AddOns in WoW . Each AddOn has its own directory under the AddOns directory . Now go ahead and do these steps : Note that the only difference in the names is the suffix . These denote , in order , Table of Contents , the Lua code file , and the XML user interface visual elements file . The name of your AddOn directory and the name on the . toc file must match . Now to put something into each of these files , and this is where the editor that works with text files comes in . The files must be saved as text , not as some document format . Notepad is a pure text editor , but it is very limited . There are many out there , some of which can help with your programming efforts by understanding the syntax of the Lua language ( more on that later ) . A favorite text editor is UltraEdit ( not free , but cross - platform : Windows , Mac , and Linux ) . For additional Lua Editors check out the additional Lua editors page , with which Notepad + + ( MS Windows only ) is highly recommended ; it comes with all the basic features of Notepad along with more advanced features for progressed programmers including syntax highlighting for LUA . The . toc or Table of Contents . This file tells WoW about your AddOn : what files to load and what order to load them in . Later you will want to peruse the TOC format page for all of the gory details about what you could put into this file . For now we are just going to give you some basic stuff to include . Using your trusted text file editor , place the following into the HelloWorld . toc file and save it : See the line with # # Interface : 30300 in it ? The 30300 is the TOC Version and the value shown is obsolete . You will need to put in the current value . WoW has a function , , which contains the current TOC Version and you can extract the number to your chat window by entering : in the chat input area . See Getting the current interface _ number . for other ways to get the TOC Version . What is this number ? The TOC Version is the user - interface ( UI ) version for the AddOn . The " 30300 " is version 3 . 03 . 00 ( or 3 . 3 . 0 ) . This number tells WoW that your AddOn is compatible with Blizzard UI level 3 . 3 . 0 . If your TOC Version does not match the Blizzard UI number , your AddOn will be considered out of date . This is to minimize problems caused by old UI modifications hosing Blizzard ' s UI . Starting from the first line we are saying : For more details on stuff you can put in here , please visit the TOC format page . The . lua or Lua code file . The . lua files are where the main " what to do " instructions for the add - on reside . You will see a variety of terms for this such as logic and executable code ( or simply " code " ) . Lua logic , or executable code or a script , does its thing in response to something that happens in the game . Things that happen in the game are called Events . Events . There are two basic kinds of events . The first is when something happens in the game . This might be somebody saying something , something happening to your character , or another character ' s stats changing . Nearly everything that happens in the game causes events . The second kind of event is when you do something to a UI Element ( a UI Element is something on the screen and is affectionately called a widget . We ' ll get to that more in the next section ) . This second kind of event might be clicking on something in your bags or button bar . There is a technical difference between the two types of events , and we will discuss that as the tutorial progresses . For more detail on the first kind of event see Events ( API ) and for the second see Widget handlers . These concepts are extremely important because absolutely nothing happens in the game except in response to an event . Furthermore , should you happen to write a piece of code that runs for an extended time ( perhaps forever ) , absolutely nothing new will happen in the game . Your screen will be frozen and nothing will move . That would be classified as " not good " . So , how do you tell WoW that you are interested in a particular event ? There are two ways : first , you can tell WoW which code to run when a particular event happens . This is called registering your event . Second , you can tell the XML to run a piece of code when a UI Element is manipulated ( such as clicking on it or moving your mouse over it ) . Pieces of code that run in response to events are called " functions " . Functions . Functions are groupings of code that accomplish a specific purpose . There are numerous predefined functions provided by WoW ( called API functions ) , or you can make your own user - defined functions . While there are multiple ways to create functions in Lua , the easiest to understand looks like this : Note that this only defines or declares the function . The function is not actually run until some other piece of code references ( or calls ) it . For more information on functions , see the Lua 5 . 1 Reference Manual or Programming in Lua ( first edition ) . Also see the Lua page which lists more Lua resources . HelloWorld . lua . Now to continue with our Hello , World code example . Place the following into your HelloWorld . lua file and save it : You should understand everything in here by now . This function is named HelloWorld and it has zero arguments . The code part is simply the ' print ( " Hello , World ! " ) ; ' portion . And it ends with " end " . This is a fine piece of code , but by itself is useless unless something calls the function . Onward to UI Elements ( aka Widgets ) . The . xml or XML visual elements file . UI Elements , or Widgets , are all of the tiny bits of graphics that make up the User Interface . WoW uses XML to layout everything that you see on the screen . Additionally , when things happen ( called Events , remember ? ) to the widgets on the screen , Widget Handlers can be called to perform whatever action you want . We will see shortly how we tell WoW which widgets we are interested in and which Events we want handled by which Widget Handler . Blizzard XML format declared . For those of you who don ' t know , XML stands for eXtensible Markup Language and is a means of tagging content with identifiers . What the identifiers are and how they are organized can be defined in something called a Schema . In our case , we want to create XML documents that WoW will understand , so we will use the Schema provided by Blizzard for the Wow User Interface . We declare that our document conforms to the Blizzard schema with the following bit of magic : The exact meaning of all of the above is beyond the scope of this tutorial . Consider it a magic formula that you always put in every . xml file you will create for the WoW user interface . For those of you that like to reformat things , the first three lines can be merged into one line ( use spaces ) , but the fourth line ( . . \ . . \ FrameXML \ UI . xsd " > ) needs to be on a line by itself starting in column 1 . There are a few general notes that you need to know about concerning XML , particularly as it is used by WoW . The generalized format of a tag is : A tag must have a tagname , and it may have zero or more attributes along with the attributes ' associated values in double quotes . The tag is everything between the ' < tagname ' and the trailing ' > ' . The tag is closed by an end tag with the same name as tag : ' < / tagname > ' . Tagnames do not have spaces , are case sensitive , start with a capital letter , and additional words are also capitalized . A valid tagname might be ' BackgroundWidgets ' , while ' backgroundwidgets ' would not be valid . Blizzard defines all valid tagnames in their UI . xsd . The XML user interface page has a good list under Widget Elements which will aid you until we get further along . Everything between the tag and the end tag is content to the tag . Everything . Even other tags along with their content . In the case where there is no content to a tag , the end of the tag has ' / > ' instead of just ' > ' and there is no separate end tag . A complete tag with no content looks like : Using the below piece of magic as an example , we can see that it is a tag with the name ' Ui ' and it has three attributes ( the funny fourth line is a part of the prior attribute ) . Content is represented by the space between the end of the tag ( the ' > ' on the fourth line ) and the ' < / Ui > ' end tag . HelloWorld . xml . Now to continue with our Hello , World XML example . Place the following into your HelloWorld . xml file and save it : Now before we create the frame for our add - on , we have to add a simple line of code that tells the WoW engine where to find our function in our . lua file . Notice this is a tag with no content , which gets a ' / > ' and no end tag . This is because this tag is solely for the engine . WoW connects everything to a frame , even other frames . So , in order to create something that WoW will interact with , we create a frame : The tagname is ' Frame ' and we have used the ' name ' attribute and given the attribute the value of ' HelloWorldFrame ' . Our frame tag is included as content to the Ui tag and so goes between the start Ui tag and the end Ui tag . To help keep track of what is surrounding what , we indent the content with respect to the enclosing tags like this : It is very important that you do not mix up the various end tags , and indenting helps keep things straight . Notice that the ' Frame ' and ' Script ' tag ( and for the ' Frame ' both the start tag and the end tag ) are completely surrounded by the ' Ui ' tag . Inside the frame , one of the many things we can define are Scripts . Scripts are nothing more than small pieces of Lua code . Where we place the script determines when it will be invoked . Because Scripts live within a Frame , we include the ' Scripts ' tag inside the ' Frame ' tag . Notice the difference , in the ' Scripts ' tag , the ' s ' sets it apart from the ' Script ' tag . The various widgets have several Events that can occur ; and if we want to declare a Widget Handler to process the event , we include the event name under the Scripts tag of the widget we are interested in . Not every widget has the same set of events . In this example , we are interested in an event named ' OnLoad ' . The OnLoad event happens when the widget is loaded into the UI . For this example , we want the OnLoad event to run the script named HelloWorld . This script was defined in the HelloWorld . lua as a function . Take a look at the Widget handlers page for a list of widgets and the events you can write widget handlers for . The complete HelloWorld . xml file should look like this : There is an important item you should note in the above : the HelloWorld ( ) ; is the only piece which is NOT a tag or an attribute . It is important to note that content in a WoW . xml UI document is always a piece of code if it is not another set of tags and their associated attributes . The only valid place for a piece of code is under the tag for an event . Having gotten this far , it is time to run your new add - on . Running your HelloWorld AddOn . You should have a directory under your AddOns directory named " HelloWorld " and in that directory should be three files named HelloWorld . toc , HelloWorld . lua , and HelloWorld . xml . The contents of these three files should be EXACTLY as described above . Now start WoW and log into your account , but don ' t select your character yet . Click the red ' AddOns ' button on the lower left of the character - selection screen to see all of the AddOns WoW has detected ; there will be one for every folder in your AddOns directory except for the AddOns starting with Blizzard _ . You should see your new HelloWorld in this list . The name should be yellow , and the checkbox to the left should be checked . If the name is red and you see an Out of date message to the right , you probably didn ' t change the # # Interface : 30300 value as described above under The . toc or Table of Contents . Review that section and make the appropriate change . Running your AddOns with the ' Load out of date AddOns ' checkbox checked is not recommended . That ' s asking for trouble as an AddOn that attempts to use old UI features can corrupt a new UI . Nearly every patch that changes the UI level has had problems with old AddOns that have not been updated to conform to the new UI standards . If you don ' t see the name at all , make sure that you have placed the HelloWorld directory in the AddOns directory , which is in the Interface directory under the WoW installation location . On a Windows system , it would be ' C : \ Program Files \ World of Warcraft \ Interface \ AddOns \ HelloWorld ' . The files inside that directory should all start with ' HelloWorld ' and have the . toc , . lua , and . xml endings . A note for Windows users ; make sure that you have not saved the files as HelloWorld . toc . txt , etc . , as an option in Windows Explorer will hide the . txt on the end . Please note the CaSe of the names . While Windows is insensitive to case for directory and file names , the case is important to other systems ( e . g . Mac , Linux ) . Also , inside the game itself , WoW is sensitive to the case for the names of its variables and filenames . Keep the case the same to avoid problems . Now you have a yellow Hello , World ! showing up in your AddOn list . Note the ! in the name . The name of the AddOn shown in this list is taken from the # # Title : Hello , World ! line in the HelloWorld . toc file . In the future , we will see how to change colors and languages . If you move your mouse cursor over the Hello , World ! name , you should see a tool - tip pop up with two lines in it . The first line is the same as the Title , and the second line is taken from the # # Notes : My first AddOn line in the . toc file . This can also be customized for color and language . Cancel out of the AddOns display and enter the world with any of your characters . Once your character loads , you should see a message in the default chat window that says " Hello , World ! " . Success ! ! Review . You have created your first AddOn and have successfully run it . Now let ' s review a bit about what was accomplished . The ' Hello , World ! ' text is taken from the line in the HelloWorld . lua file that reads ' print ( " Hello , World ! " ) ; ' . Wrapped around that is a function named " print " which is responsible for displaying the text in the default chat window . The print function is inside a function we created called " HelloWorld " that had no parameters . Our function will do the same thing every time it is called . The name of our function was then placed in the HelloWorld . xml file as the action to be taken when the " Onload " event of the " Scripts " tag of the Frame we created . We placed the name of our function in this specific place because we wanted our function to be executed ( run , called , processed ) when our Frame was fully loaded . WoW knew that it should create our Frame because we placed the name of the . xml file into the . toc file . The . toc file must have the same name as the AddOn ' s directory and is the first of the files in our AddOn that Blizzard processes . Inside the . toc file is where we tell WoW about our AddOn ( the # # statements ) and what files that need to be loaded . Every line that does not start with a # # is a file to be processed by WoW . The order in which the file names appear is important because WoW processes the files in the order listed . Knowing this , we place the . lua file before the . xml file because we want the function HelloWorld declared ( or defined ) before we try to call it in the . xml file . Even though this is a trivial example of an AddOn , important concepts and information have been covered . Further pages in this tutorial will cover other areas and expand upon topics initially presented here .