Editing WoW:Getting started with writing AddOns

{{uiaddon}}
The following is a guide for getting started with building WoW AddOns. Creating your own AddOns can be a difficult process at first, but can be very satisfying and is a great way to learn programming in general.

If you are mostly interested in what files and structure comprise a WoW AddOn, you can skip to [[AddOn|WoW AddOn]], and come back here or move on from there.

== What should I make ==
Pick a simple goal or idea for your AddOn. It's often a good idea to just make an AddOn that only opens a window or prints a message to get started, especially when everything is new for you. After that works the way it should, and you have learned everything necessary to make an AddOn work at all, you can move on to adding one piece at a time toward your goals. Writting software in general is often a never ending process because you can always think of something new to add or improve.

Examples of good questions to ask yourself:
* What's my end goal?
* What information will I need from WoW for my AddOn to work?
* Will I need to make windows (called 'frames' in WoW)?
* Will I need to interact with Blizzard's windows or frames?
* Will I need to print messages to the chat box?
* Do I know how to talk to WoW in my AddOn to do everything I want to do?

== How do I make it ==
Research the programming environment:
* [[Lua]] - This is the programming language used by WoW for UI AddOns.
* [[AddOn]] - These pages explain the basic structure of a WoW AddOn.
* [[World of Warcraft API]] - These are the functions and ways to talk to WoW with Lua.
* [[\Curse Forge]] or [[\WoW Interface (site)|WoW Interface]] - Find a real but simple example of an existing AddOn. Most real AddOns, even the simple ones, however can be difficult to read for getting started, with many moving parts.
* [[Lua editors]] - A long list of code editors and other tools often used by other AddOn creators.

Start with making a simple AddOn that has almost no moving parts, where you can see what all of the basic parts are and move forward from there. Use the reference material described above, especially in [[AddOn|WoW AddOn]], as that describes what really makes up an AddOn.

After completing your first one you will then have enough skill to start to build the real AddOn you wanted to originally make.

The following sections help with some of the various aspects of completing these first steps.

== Lua ==
[[Lua]] is a language used by many different games for their customizable UI AddOn code and other code. In WoW, if you learn a few Lua basics it will go a very long way to creating your first WoW AddOn, and toward understanding all of the other documentation and help here.

== World of Warcraft API ==
The [[World of Warcraft API]] has a list of functions that you can interact with and to talk with WoW using Lua. These are your building blocks for manipulating WoW windows and chat boxes and so forth. Looking at these for the first time can be very daunting. But don't be discouraged. After getting more familiar with Lua the WoW API gets much easier, and the documentation gets much easier to read. Keep in mind there are many different ways to accomplish your goals, so when going though the API keep looking until you find a way that best suits what you need.

== Editing Tools ==
Before you can write any sort of code, you'll want to have a tool that lets you edit your AddOn files. However do not get overly distracted with the tools themselves while trying to get your first AddOn created. Any text editor, like Windows Notepad can edit the files. All AddOn files are plain text files. The editors can make the coding and many repetitive tasks easier for day to day editing, but it's often very difficult to learn the tools and try to learn the AddOn at the same time.

To review the list of tools and get one you'd like, head to the [[Lua editors]] page.

== Anatomy of a WOW Addon ==
Strongly suggest looking here: [[WoW AddOn]], and then come back here to this section, to review this mini-review of the same material to put into better context. The WoW AddOn page shows all of the AddOn elements, where then are explained here for getting started.

=== File Types ===
There are three main types of files that you'll need to worry about with AddOn editing:
* [[TOC file]] - This file is required for any WoW AddOn, and supplies WoW with information about your AddOn and its files.
* [[LUA file]] - This contains Lua code for your AddOn.
* [[XML file]] - This holds the layout of UI windows, buttons, and similar for your AddOn.

=== TOC File ===
This is the file that instructs WoW in some basics about your AddOn and what other files you want loaded. Here's a short example of one. If you pasted this code into a 'MyAddOn.toc' file it would work as a beginning toc file:

<pre>
## Interface: {{API LatestInterface}}
## Title: My AddOn
## Notes: This AddOn does nothing but display a frame with a button
## Author: My Name
MyAddOn.xml
MyAddOn.lua
</pre>

You can read more about what you need or can put in a TOC over at [[The TOC Format]].

=== Lua Files ===
[[Lua]] files contain functional pieces of code. You may choose to only have one of these or break up your code into multiple files for a specific purpose. Here's a short example of one:

<pre>
function MyAddOn_OnLoad()
    SlashCmdList["MyAddOn"] = MyAddOn_SlashCommand;
    SLASH_MYADDON1= "/myaddon";
    this:RegisterEvent("VARIABLES_LOADED")
end

function MyAddOn_SlashCommand()
    print("Hello, WoW!")
end
</pre>

=== XML Files ===
XML files can be used to specify the visual style of your frames. More importantly though a frame allows you to easily pass events to your Lua files. [[Frame XML]] files are how [[Blizzard]] defines most of their own UI windows in the game. Check out [[XML User Interface]] for details. Here's a short example of an XML file:

<pre>
<Script file="MyAddon.lua"/> 
<Frame name="MyAddon"> 
    <Scripts> 
        <OnLoad> 
            MyAddon_OnLoad();
        </OnLoad>
    </Scripts>
</Frame>
</pre>

== Start Coding ==
Start with the tutorials extracted by the [http://us.blizzard.com/support/article.xml?locale=en_US&articleId=21466 Interface AddOn Kit]. The [[HOWTOs]] here has a ton of great examples to help you learn. Don't be shy to dig through someone else's AddOn for help, just be sure to not steal code, and give credit where credit is due.

Beware Lua functions and variables are globals by default and are directly visible to the other addons. If authors blindly use simple and common names, like:
<pre>
addonEnabled = true;
function GetArrowsCount()
   ...
end
</pre>

An addon will easily conflict with variables of the same name from other addons or from the Blizzard interface. Instead, you should write your addon more like a Lua module: place all the data and functions in a single global table, named after the addon, and use local declarations otherwise (no other globals), like:
<pre>
MarksmanAddOn = { };              -- about the only global name in the addon
local addonEnabled = true;        -- local names are all ok
function MarksmanAddOn:GetArrowsCount()
  v...                             -- function is now inside the global table
end
MarksmanAddOn.arrowsCount = MarksmanAddOn:GetArrowsCount()
</pre>

For large add-ons this can get complicated, and the current version of Lua doesn't offer much to help. Use a full, clear, name for the global table, and assign a shorter name in your .lua files, like:
<pre>
local mod = MarksmanAddOn;
 
-- then you can write
mod.arrowsCount = mod:GetArrowsCount()
</pre>

Other than the global table for the addon, you may still need globals for the saved variables and the addon slash commands (see below) if you have any.

== Slash Commands ==
A slash command is one way for the user to interact with your AddOn. These will be the easiest way for a beginner to let the user supply command and change options.
The [[HOWTO: Create a Slash Command]] page covers this pretty well.

== A Basic UI Frame ==
The [[XML User Interface]] page covers a lot of a great basics.

== SavedVariables ==
The [[Saving variables between game sessions]] article covers the key points. For folks new to AddOns but not other programming languages, just bear in mind that:
* The SavedVariables is only read from on UI loading, not real time, and only saved to on UI unloading. This will generally be from a user logging in or logging out.
* Basically, WoW makes a SavedVariables file for you named after your AddOn. You only get to specify in your TOC *which* variables get saved into that file.

== Advanced but Important Topics ==

=== Getting the WoW API ===
After learning all of the basics, there are times where you may want to see how the Blizzard UI code works to help you in making your own AddOn. And getting information on how the WoW UI works can be helpful to making your AddOn function.

See [[Extracting WoW user interface files]] for getting the Blizzard UI AddOn source code which can also be used as a reference.

=== Localization ===
It's a good idea to plan from as early as possible to have your AddOn be localizable, even if you yourself only speak one language. Review this great article for some things to think about: [[HOWTO: Localize an AddOn]].

== External links ==
{{Sectionstub}}
{{elink|site=FreeKode.org|link=http://freekode.org/wow-first-addon/|desc=World of Warcraft first addon|bydate=May 3, 2015}}
{{elink|prefix=&nbsp; &nbsp; &nbsp;|site=GitHub|link=https://github.com/freekode/TestAddon/|desc=freekode/TestAddon}}
[[Category:WoW HOWTOs]]