Create a WoW AddOn in 15 Minutes

This guide describes how to make a simple HelloWorld addon, use slash commands and store user settings.

• You need a basic understanding of Lua, otherwise see Introduction to Lua or other tutorials.
• A simple text editor like VS Code or Notepad++.

You can execute Lua scripts from the chat window or in a macro with the or /script command. There is no difference between them. To quickly turn scripts like this into an addon, just remove the "/run" part and paste it into https://addon.bool.no/

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 with the following files:

<font color="#4ec9b0">HelloWorld.lua

<font color="#4ec9b0">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.

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.

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 or you register for the event.

When registering multiple events it can be messy if there are a lot of them. Which can be refactored to this:

Slash commands are an easy way to let users interact with your addon. Any globals will automatically be registered as a slash command. <font color="#6a9955">-- increment the index for each slash command SLASH_<font color="#ecbc2a">HELLOW 1 = "/helloworld" SLASH_<font color="#ecbc2a">HELLOW 2 = "/hw" <font color="#6a9955">-- define the corresponding slash command handler SlashCmdList.<font color="#ecbc2a">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

• FrameXML: RegisterNewSlashCommand

We can also add a shorter /reload command.

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.

<font color="#ecbc2a">## 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 example 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.

Tips for troubleshooting tables:

• or or shows the contents of a (global) table.
• or empties the table.
• removes the table reference and reloads the UI; this essentially completely resets your savedvariables.

It would be more user-friendly to provide a graphical user interface. This example prints a message when you jump, if the option is enabled. It also opens the options panel with the slash command.

FrameXML:

• InterfaceOptions_AddCategory
• InterfaceOptionsCheckButtonTemplate
• UIPanelButtonTemplate

This reference example has a couple of checkboxes (with related functionality) and a reset button.

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.

HelloWorld.toc FileA.lua FileB.lua

• 1) Interface:
• 2) Version: 1.0.0
• 3) Title: Hello World

FileA.lua

FileB.lua

Or you can simply use a unique global variable.

FileA.lua FileB.lua

You know how to write a simple addon from scratch! Go and publish it on CurseForge (guide), WoWInterface (guide) and/or wago.io. If you want to cheat and rather start with a complete example it's available here: HelloWorld.zip

• Follow-up: Ace3 for Dummies

See also

• MMO-Champion: Creating Your Own WoW Addon