User:Leethal/Dongle For Beginners
From WoWWiki
Note: This is my Dongle for Beginners tutorial temp page. Work in progress kinda.
Contents |
Learn Lua!
This tutorial assumes you're familiar with Lua. If you're not, take a look at [1]. 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:
## Interface: 20003 ## Title: Your Addon Name ## Notes: A short description ## Author: Your Name ## Version: The version of the addon (such as "1.0", "0.3.25 beta" and so on) script_file.lua
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 called "HelloDongle". Inside that directory, make the corresponding TOC file - HelloDongle.toc. This is what the file should contain:
## Interface: 20003 ## Title: Hello, Dongle! ## Notes: A tutorial addon ## Author: Santa Claus Dongle.lua HelloDongle.lua
Get the Dongle.lua from DONGLE DOWNLOAD LINK. Create the HelloDongle.lua yourself.
Making use of Dongle
HelloDongle.lua 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 DongleStub() Lua function was added to the addon thanks to the Dongle.lua file and the fact that the file was listed in the addons TOC file. This function initializes dongle, assigning it to the HelloDongle 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 function SomeFunction() ... end 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, HelloDongle:Enable().
self:Print() is a function being called. self inside the HelloDongle:Enable() function is just the same as saying HelloDongle. Here's the very same function as above, using HelloDongle instead of self:
function HelloDongle:Enable()
HelloDongle:Print("Hello Dongle is enabled!")
end
It's considered better coding style to use self, 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 to SomeOtherName?
The HelloDongle:Print is also a fuction call, and it's a Dongle function. Same goes for HelloDongle:Enable function. You can find it inside the Dongle.lua file (look for function Dongle:Print). 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 HelloDongle:Enable 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.
