Documentation for Addons?

Guides UI and Macro
1

The past week or so I’ve been trying to learn the underlying ideas of wow’s addon system.

Why is this so terribly documented? I can find lots of information about how to hack together functions, but why isn’t something simple–like how xml template inhereitance works–explained?

Maybe I’m just an idiot, but I can’t for the life of me create xml frame templates in a file and then import them using CreateFrame() in my lua code. I genuinely do not understand how this isn’t something that I can’t find information about.

Do I really have to buy some addon book to get some basic information as to how this stuff works “under the hood”? How is this information that hasn’t been leaked out into the public after 20 years of this game existing?

I’ve got to be missing something.

2

XML frames without the attribute virtual="true" are created automatically when the file they are in is loaded.

CreateFrame is used in lua code to do “programtically” what the XML version of a frame does with the exception being the frame is created “on-demand”.

XML frames with the virtual attribute are not created but can be inherited by other frames either in XML or by using CreateFrame.

3

That’s what I understand, but I still cannot load those XML frames with virtual=“true” with CreateFrame in lua–probably because I’m not doing something with my file hierarchy because it doesn’t seem documented? Is this all done through the *.toc file? Or do I need to flag template xml files in another way? Maybe I have to call my lua file in the xml script?

How does lua know where to look to find these frames to inherent from? How are naming conflicts resolved? How are conflicts of attributes with multiple inheritance resolved?

Why can I not just find an information source that will explain this stuff? Is there something out there? Its really frustrating because I’m just “guessing” how this is all working, and I really don’t feel like reverse engineering wow’s client just to write an addon.

4

The .toc is essentially a catalogue card that lists some information about the addon and has a list of files that contain the code (lua and xml) that make up the addon.

https://wow.gamepedia.com/World_of_Warcraft_API is probably the most consistent source of addon information available but the subject is large and ever evolving and the approaches to creating them is so varied there is no “one approach fits all” quick list.

A few starter points, the .toc file has to be the same name as the folder it is in (the folder directly under \Interface\Addons).

XML templates (with the virtual attribute) are inherited using their name eg. the game has a default virtual template for the standard red button. To inherit it in XML you add inherits="UIPanelButtonTemplate" attribute to your XML frame declaration or use it in the 4th parameter of CreateFrame

local f = CreateFrame("Button", "MySpecialButton", UIParent, "UIPanelButtonTemplate")

All frame names (including virtuals) are global so make sure yours are unique.

Frames don’t have a size, are not placed on-screen or display anything by default (inherited templates can supply these defaults or it can be done in code).

When you add new (or rename) files (code, art, sound etc. they will not be available in-game until you completely exit the game and re-start.

You can export the Blizzard UI code to peruse:
https://wow.gamepedia.com/Viewing_Blizzard%27s_interface_code

Install a debugger, it will make your life easier:
BugGrabber and BugSack work together.
https://www.curseforge.com/wow/addons/bugsack
https://www.curseforge.com/wow/addons/bug-grabber

A quick addon to create a button that inherits the in-game red button template, anchors it to left of screen and prints some text when clicked. (you can paste the code into the website addon.bool.no to create/download the “addon”)

local f = CreateFrame("Button", "MySpecialButton", UIParent, "UIPanelButtonTemplate")
f:SetSize(70, 25)
f:SetText("Hellooo!")
f:SetPoint("LEFT", UIParent, "LEFT", 10, -20)
f:SetScript("OnClick", function(self) print(self:GetText(), self:GetName(), "was just clicked") end)

You don’t NEED XML to create a frame, it can all be done in lua.
A simple frame anchord to the right of screen filled with an all white texture that is set to yellow:

local sqr = CreateFrame("Frame", nil, UIParent)
sqr:SetSize(50, 50)
sqr:SetPoint("RIGHT", UIParent, "RIGHT", -20, 0)
sqr.Texture = sqr:CreateTexture()
sqr.Texture:SetAllPoints()
sqr.Texture:SetTexture("Interface/BUTTONS/WHITE8X8")
sqr.Texture:SetVertexColor(1, 1, 0)

And you don’t NEED lua or templates (virtuals) to actually create/display a frame in-game.

The yellow square above in XML

<Ui xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.blizzard.com/wow/ui/">
  <Frame name="FizzleXFRAME" parent="UIParent">
	<Size x="50" y="50" />
	<Anchors>
		<Anchor point="RIGHT"  x="-20" y="0" />
	</Anchors>
	<Layers>
		<Layer level="BACKGROUND">
			<Texture parentKey="Texture">
				<Color r="1" g="1" b="0" a="1"/>
				<Anchors>
					<Anchor point="TOPLEFT" />
					<Anchor point="BOTTOMRIGHT" />
				</Anchors>
			</Texture>
		</Layer>
	</Layers>
  </Frame>
</Ui>
2 Likes
5

Ok, but what about a resource to answer the questions that I was asking. A debugger is great, but without an understanding of how things are working you can only make guesses as to how to fix the bugs

6

Which question(s) did I miss?

Apart from the books that are getting old (although al lot is still relevent in them), Gamepedia or asking specific questions and digging in UI code or addons that do something like you are wanting to do.

There are other wow addon communities including this one
https://www.wowinterface.com/community.php
https://discord.gg/sVQCHr5
https://discord.me/addons

1 Like
7

I’m not asking how to implement the code.

I’m asking how the code works as to avoid problems down the road, I.e. how not to break things or rely on non standard “features”

Seriously, all I want is an overview of how the add-on system actually understands what I’m telling it, sort of like how I can go to something like the w3 consortium and get a list of standards for web development.

Is there anything like that for wow addons, or is it just a bunch of hacked together documentation? I’m not dogging anyone here, I’m just surprised that there isn’t more documentation about how this works underneath the syntax of Lua and xml; namely, how does wow interact with Lua and xml.
I have a hard time understanding something if I don’t understand how something is working.

8

There is no official documentation other than the more recent inclusion of the function/event/table docs that make make up a Blizzard addon (type /api in-game). It is by no means complete and just gives raw prototypes, no examples etc.

The version of lua (5.1) used by the game is very much trimmed down to only include those things Blizzard want addons to be able to do. No file io. other than via a controlled Saved Variables mechanism, no external libraries etc. etc. No access to the web. Secure frameworks to control what can and can’t be done during combat.

There are also game engine interaction functions (like CreateFrame) which once again only do what Blizzard want addons to do and are just wrapped up and exposed to your lua code via the API like any other function.

XML is used for defining frames and templates and that’s pretty much where its use ends (it can also be used to extend the .toc functionality of specifying files to include in the addon). Very early days I believe there was no CreateFrame and supporting functions so now we have both mechanisms.

Everything else is done in WoW lua.

For most addons, you would use an event type model. You create a frame (or more) and register it/them to receive certain events. When those events occur in-game your frame is notified and your OnEvent script responds with whatever you want your addon to do for the event. Frames also have scripts for handling other things like mouse interaction (enter/leave click along with others depending on the type of frame). Hierarchy of “frame”/widget types: https://wow.gamepedia.com/Widget_API

Then again, an addon might have no frames itself and say just move some of the default UI frames around when you character logs in. Many possibilities.

So, no w3c like body, just us hacks… more importantly, the kindly hacks that have kept what documentation there is going over 15 odd years largely unsung :clap:.

1 Like
9

Oh you’re 100% right about this being unsung work. Going through this is a giant mess, so please don’t think that I’m suggesting that add-on developers are at fault here.

It is just absolutely insane that blizzard has done such poor work documenting how it’s add-on system works. I mean even look at your links (which have been the ones I’ve been using, plus a few here and there). They are all third party. That’s absolutely ridiculous that blizzard has no official documentation on their system.

I mean, just imagine if python didn’t document it’s standard library, or ansi c, oracle’s Java, or whatever.

Maybe it’s because I’m mostly amateur, but I thought that the says of people creating apis and not documenting them was something that was considered unacceptable 20 years ago.

But whatever I’ll figure it out.

10

The api is for creating addons for one game from one company. The audience for w3c, php, apple, google, MS… is slightly larger than one game.

The company has figured out that they don’t have to spend money/developer time documenting the api and they can change it if they feel the need (they quite often feel the need).

If you’re having trouble working something out, this and the communities I linked are the place to ask questions. Everyone that creates addons has been through the same thing at some point.

11

I really appreciate that, and I’ll add the discords and create an account on wowinterface.

Its just so incredibly different, since in just about any other “community” of coders you get berated for not reading documentation and having a basic understanding of the tools. Here, it seems backwards, and that’s quite disorientating.

12

Here nobody cares about documenting, addon copyright means nothing and wowwiki is the best resource because it’s the top on google search results

1 Like