Create a WoW AddOn in under 15 Minutes

The AddOn system was designed by Slouken. Prior to Patch 2.0.1 you could even write an addon to be a full rotation and leveling bot or one that would travel for you. So how do you create a chat command? Play a John Cena sound on levelup? Automatically greet and annoy your guild members?

Getting started
For this tutorial you will need:
 * A basic understanding of Lua, otherwise see Introduction to Lua.
 * A simple text editor like VS Code or Notepad++.

Running scripts
You can execute Lua scripts from the chat window or in a macro with the  or /script command. There is no difference between them. /run print("Hello World!")

To quickly turn scripts like this into an addon, just remove the "/run" part and paste it into https://addon.bool.no/

Creating an AddOn
An addon consists of Lua/XML files and a TOC file. We won't be using XML since most things that are possible in XML can also be done in Lua.

Go to your AddOns folder and create a new folder:

HelloWorld.lua 

HelloWorld.toc  HelloWorld.lua
 * 1) Interface:
 * 2) Version: 1.0.0
 * 3) Title: Hello World
 * 4) Notes: My first addon
 * 5) Author: YourName

Load up World of Warcraft, the addon should show up in the addon list and greet you upon login.
 * The name of the TOC file must match the folder name or the addon won't be detected by the game.
 * The TOC Interface metadata  as returned by  tells which version of the game the addon was made for. If they don't match then the addon will be marked out-of-date in the addon list.

Development tips
See also: Lua Coding Tips
 * When updating addon code use /reload to test the new changes, you may want to put it on a macro hotkey; as well as temporarily disabling any unnecessary addons that would increase loading time.
 * Get an error reporting addon like BugSack or turn on
 * There is the /dump slash command for general debugging, /etrace for showing events and /fstack for debugging visible UI elements.
 * Export, clone, download or bookmark Blizzard's user interface code a.k.a. the FrameXML. If you don't know what a specific API does it's best to just reference it in FrameXML. Not everything is documented so we generally look through the code from Blizzard or other addons.
 * For VS Code the Lua extension by Sumneko adds IntelliSense features like code completion.

Responding to events
Almost every action in the game is an Event which tells the UI that something happened. For example fires when someone sends a message in a chat channel like General and Trade.

To respond to events you create a frame with and register the events to it.

Another example, to play a sound on levelup with you register for the  event. You can get a sound file from e.g. here, rename it to  and put it in your addon's folder. You can /reload instead of restarting the game client when adding a sound file.

Handling multiple events
When registering multiple events, consider dispatching them to their own function.



Slash commands
Slash commands are an easy way to let users interact with your addon. Any  globals will automatically be registered as a slash command. -- increment the index for each slash command SLASH_HELLOW 1 = "/helloworld" SLASH_HELLOW 2 = "/hw" -- define the corresponding slash command handler SlashCmdList.HELLOW = function(msg, editBox) local name1, name2 = strsplit(" ", msg) if #name1 > 0 then -- check for empty string print(format("hello %s and also %s", name1, name2 or "Carol")) else print("Please give at least one name") end end

We can also add a shorter /reload command.

SavedVariables
To store data or save user settings, set the  in the TOC which will persist between sessions. You can /reload instead of restarting the game client when updating the TOC file.

## SavedVariables: HelloWorldDB HelloWorld.lua
 * 1) Interface:
 * 2) Version: 1.0.0
 * 3) Title: Hello World
 * 4) Notes: My first addon
 * 5) Author: YourName

SavedVariables are only accessible once the respective event fires. This prints how many times you logged in (or reloaded) with the addon enabled.

This example initializes the SavedVariables with default values. It also updates the DB when new keys are added to the defaults table. The CopyTable function is defined in FrameXML. is an API function. Depending on the addon consider using AceDB for managing SavedVariables.

Tip: use  or   to show the contents of a global table.

AddOn namespace
The addon namespace is a private table shared between Lua files in the same addon. This way you can avoid leaking variables to the global environment. FileA.lua FileB.lua
 * 1) Interface:
 * 2) Version: 1.0.0
 * 3) Title: Hello World

FileA.lua 

FileB.lua 

Or you can use a unique global variable between your files. Either way, it's a good idea to modularize the addon if it grows too big.

Conclusion
You should now understand how to write a simple addon! To share it with other players zip up the folder and publish it on CurseForge (guide) and/or WoWInterface (guide).

For automatically packaging and pushing updates see Using the BigWigs Packager with GitHub Actions.