Lesson 1: Creating your first mod

Posted 04/09/09 at 6:40 AM by zork
Updated 04/09/09 at 10:08 AM by zork

Lets start by creating your first mod. I make all the sourcecode available at my GoogleCode project page under the trunk-folder called blog.
You could checkout my whole project via SVN.

Quote:

Tip: Find all the tutorials at my GoogleCode page: rothui - Google Code

So what I want you to show you today is how you can create your first mod and make it available in the game World of Warcraft. I set up a small mod for this, that can nothing special, but atleast it can talk.

Response is important. Input -> Output. I provided all files needed under the folder myFirstMod.

Quote:

Tip: If you start modding or if you are editing LUA code always activate the LUA error messages in your interface options. While ingame hit Escape, go to the interface options->others and check "show LUA error messages". Additionally install a debug mod, this will give you more specific error messages if something went wrong. Two examples:
- BugSack : WoWInterface Downloads : Developer Utilities
- BaudErrorFrame (Fan Update for WotLK) : WoWInterface Downloads : Miscellaneous

Back to our first mod, the files used are:
- core.lua
- core2.lua
- core3.lua
- myFirstMod.toc

Download the files (blog attachment) or read them via browser. Optimal would be a LUA editor so you could view and edit them locally.

Where do I have to put the myFirstMod-folder? You need to put this folder under your AddOns folder. The local is:
YOUR_PATH_TO_YOUR_WOW_FOLDER\World of Warcraft\Interface\AddOns

Now lets take a closer look at the files and what they do.

First the toc-File. What is a toc-file? Here is the WoWWiki definition:

Quote:

TOC is short for "table of contents".
The TOC format for files defines information about each addon installed, as well as specify which .xml and/or .lua files need to be loaded. It is currently required for an addon to be recognized, show up in the addons list and be loaded. The TOC filename must match the folder name in order for it to be recognized by WoW; however, any other files can be named whatever you want as long as they have the proper extension and are listed in the TOC or in an XML file inside <Script> or <Include> tags.

Source:
AddOn - WoWWiki - Your guide to the World of Warcraft
TOC format - WoWWiki - Your guide to the World of Warcraft

So, if you check the myFirstMod.toc the following lines of code can be found:
myFirstMod.toc

Code:

## Interface: 31337
## Author: roth
## Title: myFirstMod
## Notes: The is my first mod. Its simple and can talk.

core.lua
core2.lua
core3.lua

We define the interface ID, the author name, the mod title and the mod description that will be displayed in the ingame addon list.
Additionally we define all the lua files that will be called.

Now take a look at the core.lua. What does it?
core.lua

Code:

  --say Hello World!
  DEFAULT_CHAT_FRAME:AddMessage("core.lua: Hello World!")

This file is really simple. All it does is an output to the chatframe which says: "core.lua: Hello World!". But atleast you know that the files is called since you got some kind of reaction.

Ok, now lets take a look at the core2.lua.
core2.lua

Code:

  -- Hello World function
  local function am(text)
    DEFAULT_CHAT_FRAME:AddMessage(text)
  end
  
  -- Call the Hello World function
  am("core2.lua: Hello World!")

So, this is more interesting. We define a small local function called "am" that does the chat output for us.
Under the function is the call, we call the function with the string "core2.lua: Hello World!". This string is parsed into the variable "text" of the function "am" and then used for the chat output.
A function is called local if its only known to this specific lua file that defines it. Global functions can be called by any lua file around. To make a funtion global and not local, just don't use the prefix "local " infront of the function
Code will be read from top to bottom so the function call must be always below the definition of the function, otherwise the function is unknown.

So let's step further and let's look at the core3.lua
core3.lua

Code:

  -- Hello world function
  local function am(text)
    DEFAULT_CHAT_FRAME:AddMessage(text)
  end
  
  -- Create a local variable of the type Frame
  local a = CreateFrame("Frame")
  
  -- Register a Event on that Frame
  a:RegisterEvent("PLAYER_LOGIN")
  
  -- Set a script that will be run on a given Event
  a:SetScript("OnEvent", function(self,event)
    
    -- Unregister the Event, so that I will only be called once
    self:UnregisterEvent(event)
    
    -- Unset the Script
    self:SetScript("OnEvent", nil)    
    
    -- Call the Hello World function
    am("core3.lua: Hello World!")
    
  end)

Much bigger, ehh? So what we are doing here is: We use the same function as before, but the function call will be only used on a specific Event. To track that Event we need to create a small helper frame, called "assistant". So we define a local variable "a" of the type CreateFrame.
We can then register a Event on that frame "a" and set up a script that will be run upon "OnEvent" is returned. If we get a result some variables are delivered back. This will be "the frame who called this" (self), "the event return" (event) and some other arguments, mostly knows as "arg1,..." or "...".
What we are doing next is, we only want WoW to use this script once, so we unregister the Event and we unset the script.
At last we do the function call.

So what this addon does is: It will print out 3 lines of "Hello World!" into the chat.

Remember Bob Ross: Its not important what it does, its important what you can do with the information learned by making it happen.

Quote:

Tip: WoWWiki is your knowledgebase, always remember that. If you want to know anything about WoW API, Widgets or Events its the first address you should look at.
WoW API World of Warcraft API - WoWWiki - Your guide to the World of Warcraft
Widget API Widget API - WoWWiki - Your guide to the World of Warcraft
Events Events (API - WoWWiki - Your guide to the World of Warcraft)

Bob Ross quote of the day

Quote:

Remember our Golden Rule: A thin paint sticks to a thick paint.

Hope you learned something today, see you next time.

Attached Files