User:Leethal/Dongle For Beginners

Note: This is my Dongle for Beginners tutorial temp page. Work in progress kinda.

Learn Lua!
This tutorial assumes you're familiar with Lua. If you're not, take a look at. Follow some other Lua tutorials. Write a couple of Lua scripts which isn't WoW addons. Learning the language is the first step of creating good addons.

Your first addon, using Dongle
This tutorial will teach you the basics of WoW addons. Because reinventing the wheel is silly, it will use the Dongle library. Dongle is a collection of functionality, containing the basic stuff most addons needs.

The WoW addon
A wow addon has at least two things - a TOC file (Table Of Contents) and a main script file. It's an index file, containing information about which version of WoW the addon supports, the name of the addon, a short description etc. It looks like this:

script_file.lua
 * 1) Interface: 20003
 * 2) Title: Your Addon Name
 * 3) Notes: A short description
 * 4) Author: Your Name
 * 5) Version: The version of the addon (such as "1.0", "0.3.25 beta" and so on)

The only mandatory fields are Interface and Title. The other fields (there are also many fields not listed in this example) is optional.

This TOC file, the index file. To make it detectable by WoW, put it in "[wow directory] / Interface / AddOns / AddonName / AddonName.toc". It's important that the directory name and the name of the TOC file is identical.

The script file is a Lua file containing Lua code. You can have as many script files as you like. For instance, you can have the main functionality in one file, the GUI stuff in another file, a separate file for each language translation your addon supports and so on. It's common to name the main script file the same as the name of the toc file. This is the most common structure:

[wow directory]/Interface/Addons/YourAddon -- YourAddon.toc -- YourAddon.lua -- YourAddon.en.lua (english tranlation) -- YourAddon.fr.lua (french translation)

The WoW stuff
WoW adds lots of functionality to your Lua. There is mainly two "kinds" of functionality you get. Data:


 * The name of your current target
 * The amount of HP you have
 * Your quests
 * The kind of realm you're on (PvP/PvE/RP/RP-PvP)

And events:


 * Someone whispered you
 * You get a buff
 * You killed another player
 * A mob resisted someones spell

The list is endless, and you can basically get the data and hook the events of everything in the entire game. This is all available through Lua code. Details later on.

The Dongle stuff
Dongle is simply a lua script file. Download it at WTF NEED DOWNLOAD LINK (svn instructions perhaps?), add it to your addon directory ([wow directory] / Interface / Addons / YourAddon / Dongle.lua) and make sure it's listed in the TOC file. This is all you need to make a Dongle addon, all the functionality of Dongle is now available.

Making an actual addon
This section explains how to make a very simple addon using Dongle. The addon is called "Hello, Dongle!".

The TOC file
Make a directory in [wow directory] / Interface / Addons</tt> called "HelloDongle". Inside that directory, make the corresponding TOC</tt> file - HelloDongle.toc</tt>. This is what the file should contain:

Dongle.lua HelloDongle.lua
 * 1) Interface: 20003
 * 2) Title: Hello, Dongle!
 * 3) Notes: A tutorial addon
 * 4) Author: Santa Claus

Get the Dongle.lua</tt> from DONGLE DOWNLOAD LINK. Create the HelloDongle.lua</tt> yourself.

Making use of Dongle
HelloDongle.lua</tt> is the main script file, where the functionality itself will be. Open this file using your favourite code editor. If you have none, use Notepad or Wordpad if you're on windows - allthough an editor such as SciTE-WOWInterface is recommended. If you're on OS X, try TextMate. Recommondations for Linux editors is welcome!

First, make sure it's actually using Dongle.

HelloDongle = DongleStub("Dongle-1.0"):New("HelloDongle")

The  Lua function was added to the addon thanks to the Dongle.lua</tt> file and the fact that the file was listed in the addons TOC</tt> file. This function initializes dongle, assigning it to the  object.

Adding a login message
An addon has certain events associated with this. One of these events is the Enable event. This happens after the loading screen has finished loading and the log in process is completely over. This is how it's done.

function HelloDongle:Enable self:Print("Hello Dongle is enabled!") end

A number of things happens here. The  is a Lua function definition. A function is a chunk of code with a certain functionality and a name used to call it. In this case,.

is a function being called. self</tt> inside the  function is just the same as saying HelloDongle</tt>. Here's the very same function as above, using  instead of  :

function HelloDongle:Enable HelloDongle:Print("Hello Dongle is enabled!") end

It's considered better coding style to use self</tt>, though. It makes the code easier to read and understand, and is also easier to write! What if you for instance change the name of the object from HelloDongle</tt> to SomeOtherName</tt>?

The HelloDongle:Print</tt> is also a fuction call, and it's a Dongle function. Same goes for HelloDongle:Enable</tt> function. You can find it inside the Dongle.lua</tt> file (look for ). That function adds a message to the chat frame, prefixing it with the addon name. Instead of explaining how it looks - log in to WoW and take a look for yourself!

Responding to an in-game event
When things happen in the game, addons can be notified about that thing. There is a shitload of events you can be notified about (full list here). For tutorial purposes, the event used in Hello, Dongle! is CHAT_MSG_SAY. That event is fired when someone says something in the "SAY" channel (e.g. "/s Hello, dude!") and you're close enough to get it (you won't get "SAY" messages from the other end of Azeroth).

WoW needs to know that the addon is listening to this event. Register it in the  function.

function HelloDongle:Enable self:RegisterEvent("CHAT_MSG_SAY") self:Print("Hello Dongle is enabled!") end

The event is registered. Nothing extraordinary will happen as of now when someone says something, but WoW will now call the addon when this event occurs.

To make something happen when you recieve a "SAY" message, do this:

function HelloDongle:CHAT_MSG_SAY -- The code here... end

A side note:  marks a comment. Everything to the right of the  on that line will be a comment, not executed as Lua code.