Comprehensive Beginner's Guide for WoW Addon Coding in Lua

By Armak Updated: 2025/05/07

This Is A User-Submitted Guide!

Wowhead only updates official guides, so information might not be up-to-date.

1 IntroductionIf you've never done any programming before, this isn’t something you'll fully grasp in one evening.
But don't worry — come back to it whenever you have time and motivation. Little by little, it will start to make sense.Note for Classic WoW players:2 Resources

https://lua.org/pil/contents.html - Lua documentation from 2003. Most of it is still relevant.

https://wowwiki.wikia.com/wiki/WoW_AddOn - A wiki covering nearly everything about WoW addons. It's fairly comprehensive, but sometimes lacks deeper background or misses important details on certain topics.

https://wowprogramming.com - A website listing everything you can use within your addons to interact with the game. The content is broad but often lacks detailed documentation or practical examples.

https://wow.gamepedia.com/World_of_Warcraft_API - Another API Website.

https://authors.curseforge.com/forums - A forum for WoW related Lua questions.

https://curseforge.com/wow/addons - One of several websites where you can upload your addons (in my opinion the most relevant).

https://twitch.tv/tomcat - Addon developer regularly streaming on Twitch.

https://wago.tools - A searchable archive of Lua files and more, extracted from various WoW builds. Useful for exploring the default UI’s functionality and seeing how Blizzard implements things, which can help you modify or extend game systems.

3 Preparationnotepad++WowLua/console scriptErrors 103.1 How To Execute Lua Code In WoW/run <code>WoWLuaWeakAuras4 Addon BasicsC:\Program Files\World of Warcraft\_retail_\Interface\AddOns

The actual code files

A file with meta information about your addon, like its full name and author

Images

Sound files

Additional information like a readme.md or a PDF document. WoW ignores these kind of files.

World of Warcraft\_retail_\Interface\AddOns/reload/reloadSavedVariables

World of Warcraft\_retail_\WTF\Account\<account_name>\SavedVariables\<addon_name>.lua which can be read by all your characters

World of Warcraft\_retail_\WTF\Account\<account_name>\<server_name>\<character_name>\SavedVariables\<addon_name>.lua which can be read by this specific character

whatDetails!5 Terms And DefinitionsAPI - Application Programming InterfaceHow6 About LuaRun

You are able to customise the user interface: its graphical representation and its functionality.

You can read and evaluate the combat log.

You can react to all kind of events (when a player dies, someone writes a message into the guild chat, you kill a mob, someone trades you, you start gaining fatigue ...).

Combining these things allows you to create mighty addons which have been with us for many years, like Deadly Boss Mods, Weakauras2, and Recount.

if rogue has six combo points, use Run Through7 Some Addons And How They WorkVicious Sliceaddon chat channel/dbm pull 10

Name colouring: Prat saves name, class and level of players you meet. When you receive a chat message, let us say in the guild chat, it will intercept this message, search for known player names in it and colour them accordingly. After you have seen a lot of players, Prat tends to noticeably slow down the chat if you e.g. send 20 messages at once with a script because Prat goes through your list of seen players everytime you receive a chat message.

URL copying: Prat searches chat messages for URLs in it, e.g. levelupgilde.de. It then makes this part of the chat clickable and displays an input box with the URL in it, already selected and ready to be copied.

Chat history: If activated, Prat saves the last x messages of your chat frames. When you log back into the game, it prepopulates your chat frames with those saved messages.

When a player starts casting a spell. You get additional information like the name and ID of the spell.

When a player successfully cast a spell.

When a player aborts casting a spell.

When a player deals damage. Among other data you can get the amount of damage done, the target, the spell which did the damage, the name of the player.

When damage is absorbed.

Warcraftlogs/combatlog8 Basic Programming Rules, Conventions And StructuresLua interpreterWowLua8.1 Variables\"string1 = "She said, "Oh, wow!"."escapingstring1 = 'She said, "Oh, wow!".'this\'George Booletruefalse8.2 Expressionsexpressions25.0-4925.0calculation1/2string concatenationgreeting = "Hello "..Wait, there is more to come! And just append it to our string!name1name2namesMichaelBrad8.3 Functionsconsole/run print("Hey, Azeroth!")argumentsprintwhatRandomRoll/rnd 1-54154print()RandomRoll()xyfunctionsquare(x)returnendreturnprint(x * x)multiplestring1Heynumber154.54

UnitName()

UnitLevel()

GetSpecialization()

GetSpecializationInfo()

UnitName()unitID"player""target""group2"UnitName()UnitLevel()unitIDGetSpecializationInfo()specIDspecIDGetSpecialization()GetSpecialization()8.4 Conditional Statements, Boolean Values, Relational Operatorstruefalsetruefalselogical connectives

AND

relational operatorscomparison operatorstruefalse

< (less than)

<= (less than or equals)

> (greater than)

>= (greater than or equals)

== (equals)

~= (not equals)

if statementsif statementif statementsIf the WoW API rules, then print "The WoW API rules!".if statementselseifGetAverageItemLevel()CalendarGetDate()

Logical operator

C (result)

true

AND

true

AND

false

AND

true

false

AND

false

A AND BtruefalsetrueA AND Btrue

Logical operator

C (result)

true

false

true

false

true

false

A OR BtrueA OR BtrueANDtrueORtruetrueNOTNOTNOT true AND NOT truetruefalsetrue

NOT A

Logical operator

C (result)

true

AND

true

false

true

AND

false

AND

true

false

AND

false

NOT A AND Btruefalsetrue

NOT A

Logical operator

C (result)

true

false

true

false

true

NOT A OR Bfalse

NOT A

Logical operator

NOT B

C (result)

true

AND

true

false

true

AND

false

AND

true

false

AND

false

true

NOT A AND NOT BtruefalseA AND Btruetrue

NOT A

Logical operator

NOT B

C (result)

true

false

true

false

true

false

true

false

true

NOT A OR NOT BtruefalseANDORtruetrue and falsefalsetruefalsetrue or truetruetrue and falsefalsemutual exclusionexclusive orA XOR Btrueortrue8.5 Loopsfor loopstartendincrement1i variablewhile ... doconditioniii = i + 1ifalserepeat ... untilwhile ... doafterHey.loopfalse8.6 TablesTablesarraystablesgreetings = {}indiceskeysindexkeyThrom-KaaddGreeting()greetings tablegetGreetings()greetings = "xyz"greetings.index = contentaddGreetingindex)
end
In this piece of code we fill a table with the first 12 potencies of 2.
We first declare our empty and to-be-filled table potencieswhile looptable.insert()#<tablename>potencies)

if(isCollected == true and faction ~= 1) then
numCollectedMounts = numCollectedMounts + 1
end
end

print(numCollectedMounts)
Used functions: C_MountJournal.GetMountIDs(), C_MountJournal.GetMountInfoByID. C_MountJournal.GetMountIDs()for loopC_MountJournal.GetMountInfoByID()18.7 Commenting Codereallywhy9 Variable Scopingvariable scopingglobalYouround(number, decPlaces)locallocaln1addlocalaprint(a)nilaaddlocalhttp://et.worldofwarcraft.wikia.com/wiki/Lua_variable_scoping10 Example Addon10.1 Eventseventssomething, that happens/etrace

UNIT_SPELL_CAST_START - When someone around you casts a spell

UPDATE_MOUSEOVER_UNIT - When you hover over a unit

PLAYER_STARTED_MOVING - When you start moving

PLAYER_DIED - When you die

CHAT_MSG_WHISPER - When you receive a whisper

CHAT_MSG_MONSTER_SAY - When an NPC says something

react/bowhttps://wowwiki.wikia.com/wiki/Events_A-Z_(Full_List)10.2 Getting StartedTestAddonC:\Program Files\World of Warcraft\_retail_\Interface\AddOnsTestAddon.tocTestAddon.lua10.3 .toc filehttps://wow.gamepedia.com/TOC_formattoctable of contentsInterfaceTitleNotesVersion0.11.0.38.2 build 1v1.010.4 .lua Fileprint("Hello, Azeroth!")/reload/run10.5 Addon IdeaCHAT_MSG_RAIDCHAT_MSG_RAID_LEADER10.6 FramesFrame/fstackActionButton{n}{n}/run ActionButton4:Hide():Show()/fstackUIParent/run UIParent:Hide()MEDIUMTOOLTIPBACKGROUNDFrameStratam10.7 Addon Loading ProcessTestAddon.luaPlayerFrame:Hide()ChatFrame1:Hide()HereADDON_LOADEDPLAYER_ENTERING_WORLDPLAYER_ENTERING_WORLDCreateFrame()selfevent...if statementif statementif code blockafterPLAYER_ENTERING_WORLDC_Timer.After()Hide()()OnShow scriptaddon loading process10.8 Our Main Event HandlerRaid Message Event Captured!Durability Check!...https://wow.gamepedia.com/CHAT_MSG_RAIDplayerNametextDurability Check!GetInventoryItemDurability(slotIndex)inventory slot indexhereGetInventoryItemDurability()here11 Conclusion

Object oriented programming with Lua: https://www.lua.org/pil/16.html

Make use of slash commands (like /addonname): https://wowwiki.fandom.com/wiki/Creating_a_slash_command

Regular expressions: http://lua-users.org/wiki/PatternsTutorial

Saved Variables (basically just a table which WoW can save and load for you): https://wowwiki.fandom.com/wiki/Saving_variables_between_game_sessions

Ace3: A library helping you with creating addons. You should probably not make use of it if you are still learning: https://wow.gamepedia.com/WelcomeHome_-_Your_first_Ace3_Addon

Invisible/silent communication between addon users: https://wow.gamepedia.com/API_C_ChatInfo.SendAddonMessage

/fstack/dump ObjectName

Comments

Comment by Vizions77

Thanks so much for the post! I know very little about coding and Lua, but with your guide I do feel a little more confident in learning. Would love to see a part two. Great work!

Comment by Anderphil

Thanks a lot, I was able to make my first functional addon from this. Great write up!

Comment by bando

I'm a python developer with no lua experience. This guide is extremely useful!
I've occasionally glanced at some of the code in addons and while it sometimes made sense, there were times I had no idea what it was doing. After reading this guide, I now see why.
Object.key = variable
The above is appending to a table! (rather than assigning an attribute of the object)
Or even the fact that arrays don't exist.
Also, understanding that things happen inside a frame makes so much more sense now.

Superb job!

I'd be curious if you have recommendations on an IDE for beginners. (something akin to JetBrains with excellent intellisense to help newbies from making mistakes)

Comment by Edglar

I am so incredibly grateful you put this together. I will echo a previous poster in saying I would absolutely love to see part 2 and beyond! I am no programmer, yet this guide was an excellent stepping stone towards creating simple addons...something I've been looking for forever. Bravo!

Comment by SpaceBarBob

Surely someone reading this can create a super basic "hide minimap during combat" addon in a spare minute and post a link <3

Comment by sconley

<> is not a valid operator in WOW lua. You have to use ~=. I tested this with the wowlua addon and with lua for windows for lua 5.1.

Comment by SubbyDK

I know it's way to late, but will post it anyway.

-- Register events
MinimapCluster:RegisterEvent("PLAYER_ENTERING_WORLD")
MinimapCluster:RegisterEvent("PLAYER_REGEN_DISABLED")
MinimapCluster:RegisterEvent("PLAYER_REGEN_ENABLED")

-- Call function based on event.
MinimapCluster:SetScript("OnEvent", function(self, event, ...)
-- Check to see if we are in combat.
if UnitAffectingCombat("player") then
-- We are in combat.
self:Hide()
else
-- We are not in combat.
self:Show()
end
end)

Comment by zxeltor

A great introduction. Thanks for taking the time to do this.

Comment by Arenvalde

I have watched and read about a dozen tutorials for wow addon coding over the last... 5 hours.

I still cannot get a ****ing WINDOW to appear in game. I do know how to send chat messages or play sounds, and I've read all about events, which I don't yet care about, but I literally cannot get a single visible element to show up. The only tutorial that seems remotely useful was made for 6.2, and even updated to what I can find in modern API, it does not do what the creator said it does.

Why is this so bloody frustrating?

Comment by Mvin

Coming from a webdev and Java/C# background, this guide is so very helpful. Compared to most other languages and libraries I've dealt with, the WoW Addon Api kind of seems like the Wild West. There are exhaustive references for all the available functions, but little explanation what they do, with many of them being deprecated or non-functional. On top of that, where to even start? Its hard to find a coherent guide out there that just lays out the basics of what is needed for a "Hello World"-addon. Obviously, your guide does this and more and its a godsend! With the info presented here, I'm confident I can already build what I need to gather some info about player collections.

You said in another comment that an additional chapter for building addon UIs is in the works, which would be the cherry on top of this already great guide.

Thanks for the work!

Comment by Taraezor

Nice job!

I'm a very old school programmer (any heard of Apple][ Machine Code or CList or JCL?), a journeyman if you like, and I love LUA. Sadly, I am well and truly trapped in a Structured Programming mindset and thus I find a lot of LUA code, which appears to have been shoe horned into a so-called OOP paradigm, to be unreadable.

One more thing... scoping or passing by reference and/or value in LUA... it's not entirely consistent and still tricks me up. Watch out!

Comment by Wraiyth

This is an amazing guide - thank you so much!

As a complete and utter novice and a definite member of the target audience there is one piece of crucial info missing that had me scratching my head for a good hour. If your TestAddon doesn't load in game read on:

Depending on how you create the text files in your TestAddon folder, even when naming them with the .toc and .lua file extensions they may still save as .txt files. In this case nothing will work and you may be staring blankly at the screen as you recreate the files and reload WoW repeatedly wondering what could be wrong.

When you create the .toc and .lua be certain to "Save As" and ensure it's set to "All File Types" and not just text files like mine was, this should be reflected in windows explorer as they will then correctly show as LUA/TOC under the Type column rather than as txt file.

Took me an embarrassingly long time to figure this out so hopefully it helps someone else at some point :)

Comment by TornJK

I tried to recreating "SAY" channel instead of Raid as I was too lazy to open a Raid for the addon testing.
However I always receive a error when I try to get the durability to print to chat.

AddOn 'MyExampleAddon' tried to call the protected function 'UNKNOWN()'.
:480: in function <Interface/AddOns/!BugGrabber/BugGrabber.lua:480>
"]: ?
"]: in function `SendChatMessage'
:30: in function <Interface/AddOns/MyExampleAddon/MyExampleAddon.lua:17>

I can use the function SendChatMessage from WowLua or /script just fine. Something I'm overlooking - is "SAY" treated differently than raid?

Comment by Tjark

This is a very helpful guide! Thank you so much for the introduction. I wanted to get into Lua but it was pretty daunting but this made for a great first stepping stone.

Comment by Sockemboffer

Not sure if this is a dumb question but does each major version of wow target a new version of Lua (pre and post Shadowlands), if so could that info be placed in a relevant section for environment setup? This guide is amazing, thank you!

Comment by DerpadinMcknight

I REALLY appreciate this guide as I am trying to develop (hopefully) some functions to a controller-based style of play (an addition to ConsolePort). Thank you for going out of your way to share this information! I would not mind (if you had a Patreon) supporting something! Is it possible some information is coming about frames and custom textures? I'd like to fiddle with the nameplates quite a lot...

Comment by OrghalPL

Hello,
thank you very much, I am reading and reading and moving forward. Absolutely the best article and manual as I found in last months. Perfect good Job, if you're still in wow it be nice to meeto you someday.
Now... back to learning hahaha
Orghal

Comment by OrghalPL

Only one small problem to the tutorial and cannot find out what is going on
Trying use SendChatMessage but it works only with my self (whisper)
always error if I try send something to SAY or directly to other player - nickname checked, e.g.
SendChatMessage(msg, "WHISPER", nil, "Luicidia")
what to do?

Comprehensive Beginner's Guide for WoW Addon Coding in Lua

Contribute