Comprehensive Beginner's Guide for WoW Addon Coding in Lua

Von Armak Letztes Update: 21.03.2024 Änderungsprotokoll Patch: 10.2.6

Inhaltsverzeichnis
Wertung:

1 IntroductionThis is nothing you will be able to fully understand on a single evening if you have never been in touch with programming before. Always come back to it if you have time and motivation and you will begin to understand more and more.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 with pretty much everything about WoW addons. It is mostly written comprehensively but often lacks background information on a certain topic and often does not cover every important aspect of a subject.

https://wowprogramming.com - A website containing everything you can use within your addons to interact with the game. It is quite complete in its listing but lacks documentation and good examples.

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

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

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

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

https://wago.tools - Lua files and more ready to be searched which were extracted from the different WoW builds. Here you can look up the basic UI's functionality which can help you alter the game's 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 WorkBösartiges Schlitzenaddon 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

Kommentare

Kommentar von 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!

Kommentar von Anderphil

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

Kommentar von 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)

Kommentar von 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!

Kommentar von SpaceBarBob

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

Kommentar von 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.

Kommentar von 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)

Kommentar von zxeltor

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

Kommentar von 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?

Kommentar von 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!

Kommentar von 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!

Kommentar von 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 :)

Kommentar von 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?

Kommentar von 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.

Kommentar von 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!

Kommentar von 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...

Kommentar von 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

Kommentar von 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

Beitragen