View source

Well, you've decided to start an AddOn for Runes of Magic. Or at least you're contemplating it.

== Making the folder ==

You start out by choosing a folder name for your AddOn. It should be something simple, and no funny characters (just letters, numbers, dashes, underscores, periods, basically).

For this exercise, we're going to make the cliché HelloWorld AddOn.

Assuming you installed RoM to <tt>C:\Program Files\Runes of Magic\</tt>, you'll want to verify that <tt>C:\Program Files\Runes of Magic\Interface\</tt> and <tt>C:\Program Files\Runes of Magic\Interface\AddOns\</tt> exist, otherwise you should create them, case-sensitive.

You'll then want to create the <tt>C:\Program Files\Runes of Magic\Interface\AddOns\HelloWorld\</tt> folder (or whatever you want to call it), which will house all your AddOn's files.

== Laying the groundwork ==

There are three kinds of files used for AddOns (outside of image and sound files):

; .toc file
: Each AddOn should have one .toc file, it will match the name of your AddOn's folder. In our example, this will be <tt>HelloWorld.toc</tt> and will be placed as <tt>Interface\AddOns\HelloWorld\HelloWorld.toc</tt>. This will provide metadata about your AddOn as well as providing information on what files to load.
; .lua files
: This is where the bulk of your code lies, all the actual business logic should take place here.
; .xml files
: XML files can load Lua files and well as define frames. (At least until a way is provided to create frames in Lua.) Try not to put any actual logic into your XML files, but rather delegate it to a function or method inside your Lua.

We need to start with your TOC file. It should look something along the lines of this:

<code><pre>
## Title: Hello World
## Version: 0.1
## Notes: Says "Hello, World!"
## Author: YourNameGoesHere

HelloWorld.lua
</pre></code>

As you can see, you specify your AddOn's name (<tt>Title</tt>), what version number it is (<tt>Version</tt>), a one-line description (<tt>Notes</tt>), and your author handle (<tt>Author</tt>). You can specify other information, but if you do, prefix with <tt>X-</tt>, so that there are no conflicts in the future.

For right now, we're only loading one file, <tt>HelloWorld.lua</tt>, which will contain some simple code.

== Let's get our code on ==

Here's what we'll stick in <tt>Interface\AddOns\HelloWorld\HelloWorld.lua</tt>

<code><pre>
local HelloWorld = {} -- the AddOn namespace, all your functions should be placed inside here instead of as globals.
_G.HelloWorld = HelloWorld -- expose it to the global scope

--- Print out "Hello, World!" to the chat frame
-- @usage HelloWorld.Print()
function HelloWorld.Print()
    DEFAULT_CHAT_FRAME:AddMessage("Hello, World!")
end

HelloWorld.Print() -- call print
</pre></code>

At this point, if you start up RoM, you'll get the message "Hello, World!" in your chat frame.

You can also run <tt>/script HelloWorld.Print()</tt> at any time from the in-game command line to print out the text again.

===Addendum===

For performance reasons, according the [http://www.lua.org/docs.html lua documentation] and [http://lua-users.org/wiki/ lua developer community] it is a good practice to:
* make use of [http://lua-users.org/wiki/ModuleDefinition code modules] and package calls through namespaces;
* use as many local function calls as possible;

How to implement this? Assume you created an addon called ''MyRomAddOn''. It's possible to have more than one lua coded files within your addon.Each file then represents a separate ''module'' within your addon-package. So, you'd have your addon's folder  <tt>%RoMInstallPath%Interface\AddOns\MyRomAddOn\</tt>, containing your lua table of content (MyRomAddOn.toc) file which describes the internal file structure and any other lua files. Suppose your addon has 2 lua files, ''MyRomAddOn.lua'' and ''Tools.lua''.

The file ''MyRomAddOn.lua'' could look like this:

<code><pre>
--[[
    Interface section: Definition of your addon's public interface.
	This should match the name of your addon folder's foldername, e.g.
		%RoMInstallPath%Interface\AddOns\MyRomAddOn\
	and this lua file's filename, e.g.
		MyRomAddOn.lua.
--]]
local MyRomAddOn= {};
_G.MyRomAddOn = MyRomAddOn;

--[[
    Private section: Definition of your addon's private API.
	In object-oriënted programming terminology, here you should define
	all external APIs used within your addon,
	as well as any private functions, properties and methods of your addon
	by referencing them using the local operator.
--]]
local RoMAPI = _G;--external Runes of Magic game API.
local ParentFrame = MyRomAddOn_Frame;--external file MyRomAddOn.xml;same as _G.MyRomAddOn_Frame or RoMAPI.MyRomAddOn_Frame.

local function SysMsg(msg)
	RoMAPI.DEFAULT_CHAT_FRAME:AddMessage(tostring(msg), RoMAPI.ChatTypeInfo["SYSTEM"].r,  RoMAPI.ChatTypeInfo["SYSTEM"].g,  RoMAPI.ChatTypeInfo["SYSTEM"].b );
end

--[[
    Public section: Definition of your addon's public API.
	In object-oriënted programming terminology, here you should define
	all public functions, properties and methods of your addon
	by referencing them using the dot operator.
--]]
function MyRomAddOn.Load()
        SysMsg("MyRomAddOn loaded.");
end

--[[
    Remark the final return statement in your MyRomAddOn.lua!
    This exposes the public API of your addon.
--]]
return MyRomAddOn;
</pre></code>

To test, type ''/script MyRomAddOn.Load();'' in the game's chatwindow.

== Event fun ==

Code which can't react to the game isn't very useful, which is why we need to start messing with some events.

To do this, we have to unintuitively make a frame, which is how we can listen in on events.

So, let's add <tt>HelloWorld.xml</tt> to our .toc file (before the <tt>HelloWorld.lua</tt> file). It would look like this:
<code><pre>
## Title: Hello World
## Version: 0.1
## Notes: Says "Hello, World!"
## Author: YourNameGoesHere

HelloWorld.xml
HelloWorld.lua
</pre></code>

And create the <tt>Interface\AddOns\HelloWorld\HelloWorld.xml</tt> file:
<code><pre>
<Ui xmlns="http://www.runewaker.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.runewaker.com/UI.xsd">
    <Frame name="HelloWorld_Frame">
        <Scripts>
            <OnEvent>
                -- call the OnEvent method on our AddOn, passing in any relevant args.
                HelloWorld:OnEvent(event, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9)
            </OnEvent>
        </Scripts>
    </Frame>
</Ui>
</pre></code>

Now we need to define an OnEvent method as well as register any events, so let's return to our lua.

<code><pre>
local HelloWorld = {} -- the AddOn namespace, all your functions should be placed inside here instead of as globals.
_G.HelloWorld = HelloWorld -- expose it to the global scope
local frame = _G.HelloWorld_Frame -- made in the XML

--- Print out "Hello, World!" to the chat frame
-- @usage HelloWorld.Print()
function HelloWorld.Print()
    DEFAULT_CHAT_FRAME:AddMessage("Hello, World!")
end

frame:RegisterEvent("VARIABLES_LOADED")

function HelloWorld:OnEvent(event, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9)
    -- this is a fun trick that will call a method named the event, passing in all the relevant args.
    self[event](self, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9)
end

function HelloWorld:VARIABLES_LOADED()
    self.Print()
end
</pre></code>

Now let's explain what <tt>self[event](self, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9)</tt> does.
It allocates the events to each function corresponding to the <tt>event</tt> variable, without having to use structures like
<code><pre>if event == "VARIABLES_LOADED" then 
    self:VARIABLES_LOADED()
elseif 
    ...
end</pre></code>

Alright, now instead of printing <tt>Hello, World!</tt> when the Lua loads, it will do it when <tt>VARIABLES_LOADED</tt> is fired.

== Timers ==
Unlike in a single-threaded environment, you can't just run a <tt>sleep</tt> command to wait to execute something, you need to use timers.

If you were to manually sleep, then you'd freeze up the entire UI, which nobody wants.

<tt>OnUpdate</tt> is a script that runs every frame tick, similar to an event firing every tick.

In the following, we'll run a command every 5 seconds:

For your XML:
<code><pre>
<Ui xmlns="http://www.runewaker.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.runewaker.com/UI.xsd">
    <Frame name="HelloWorld_Frame">
        <Scripts>
            <OnEvent>
                -- call the OnEvent method on our AddOn, passing in any relevant args.
                HelloWorld:OnEvent(event, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9)
            </OnEvent>
            
            <OnUpdate>
                -- call the OnUpdate method on our AddOn
                HelloWorld:OnUpdate(elapsedTime) -- elapsedTime fix provided by Alleris.
            </OnUpdate>
        </Scripts>
    </Frame>
</Ui>
</pre></code>

And in the Lua:
<code><pre>
local HelloWorld = {} -- the AddOn namespace, all your functions should be placed inside here instead of as globals.
_G.HelloWorld = HelloWorld -- expose it to the global scope
local frame = _G.HelloWorld_Frame -- made in the XML

--- Print out "Hello, World!" to the chat frame
-- @usage HelloWorld.Print()
function HelloWorld.Print()
    DEFAULT_CHAT_FRAME:AddMessage("Hello, World!")
end

frame:RegisterEvent("VARIABLES_LOADED")

function HelloWorld:OnEvent(event, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9)
    -- this is a fun trick that will call a method named the event, passing in all the relevant args.
    self[event](self, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9)
end

function HelloWorld:VARIABLES_LOADED()
    self.Print()
end

local time_remaining = 5 -- in seconds
function HelloWorld:OnUpdate(elapsed)
    -- elapsed is the amount of time in seconds since the last frame tick
    
    time_remaining = time_remaining - elapsed
    if time_remaining > 0 then
        -- cut out early, we're not ready yet
        return
    end
    time_remaining = 5 -- reset to 5 seconds
    self.Print()
end
</pre></code>

You can stop <tt>OnUpdate</tt> from firing by calling <tt>frame:Hide()</tt> and starting it again with <tt>frame:Show()</tt>.


This code will generate an error in the current release. The error may come from the XML OnUpdate(elapsedTime) or from the function HelloWorld:OnUpdate(elapsed)
needs investigation

== Slash Commands ==

We will now learn how to register <tt>slash</tt> (<tt>/</tt>) commands. Lets start out by doing a simple slash command, with no other parameters. The only changes will be in the .Lua file.

<code><pre>local HelloWorld = {} -- the AddOn namespace, all your functions should be placed inside here instead of as globals.
_G.HelloWorld = HelloWorld -- expose it to the global scope
local frame = _G.HelloWorld_Frame -- made in the XML

SLASH_HelloWorld1 = "/HelloWorld" -- First slash command
SLASH_HelloWorld2 = "/hw" -- Second slash command
SlashCmdList["HelloWorld"] = function(editBox, msg) -- Definition of a slash command, having to use editBox and a message
	HelloWorld.Print()
end

--- Print out "Hello, World!" to the chat frame
-- @usage HelloWorld.Print()
function HelloWorld.Print()
	DEFAULT_CHAT_FRAME:AddMessage("Hello, World!")
end

frame:RegisterEvent("VARIABLES_LOADED")

function HelloWorld:OnEvent(event, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9)
	-- this is a fun trick that will call a method named the event, passing in all the relevant args.
	self[event](self, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9)
end

function HelloWorld:VARIABLES_LOADED()
	self.Print()
end

local time_remaining = 5 -- in seconds
function HelloWorld:OnUpdate(elapsed)
	-- elapsed is the amount of time in seconds since the last frame tick

	time_remaining = time_remaining - elapsed
	if time_remaining > 0 then
		-- cut out early, we're not ready yet
		return
	end
	time_remaining = 5 -- reset to 5 seconds
	self.Print()
end</pre></code>

Now, to declare a slash command name, we need to use the SLASH prefix to a variable, then the name of the slash variable, and a number after it. Note that the number has to be an integer. Examples of slash names:<tt>

SLASH_thisIsASlash1

SLASH_lulzSlash1</tt>

A more complex slash command, in which you have extra parameters, but still keeping it simple.
<code><pre>
local HelloWorld = {} -- the AddOn namespace, all your functions should be placed inside here instead of as globals.
_G.HelloWorld = HelloWorld -- expose it to the global scope
local frame = _G.HelloWorld_Frame -- made in the XML

SLASH_HelloWorld1 = "/HelloWorld" -- First slash command
SLASH_HelloWorld2 = "/hw" -- Second slash command
SlashCmdList["HelloWorld"] = function(editBox, msg) -- Definition of a slash command, having to use editBox and a message
	if string.lower(msg) == "hide" then -- If the 2nd string is <tt>hide</tt>
		frame:Hide()
		DEFAULT_CHAT_FRAME:AddMessage("OnUpdate now stopped.")
	elseif string.lower(msg) == "show" then
		frame:Show()
		DEFAULT_CHAT_FRAME:AddMessage("OnUpdate now started.")
	elseif string.lower(msg) == "print" then
		HelloWorld.Print()
	else
		DEFAULT_CHAT_FRAME:AddMessage("Not a viable command")
	end
end

--- Print out "Hello, World!" to the chat frame
-- @usage HelloWorld.Print()
function HelloWorld.Print()
	DEFAULT_CHAT_FRAME:AddMessage("Hello, World!")
end

frame:RegisterEvent("VARIABLES_LOADED")

function HelloWorld:OnEvent(event, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9)
	-- this is a fun trick that will call a method named the event, passing in all the relevant args.
	self[event](self, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9)
end

function HelloWorld:VARIABLES_LOADED()
	self.Print()
end

local time_remaining = 5 -- in seconds
function HelloWorld:OnUpdate(elapsed)
	-- elapsed is the amount of time in seconds since the last frame tick

	time_remaining = time_remaining - elapsed
	if time_remaining > 0 then
		-- cut out early, we're not ready yet
		return
	end
	time_remaining = 5 -- reset to 5 seconds
	self.Print()
end</pre></code>

== Frame Tutorial ==

Needs additional information on how to call a frame to show it for the user including a working example



Now lets take a Look at Frames and the xml.

Before we look at Frames and all this Stuff lets take a look at xml.

An easy XML example would be:

<code><pre>
<MyRoom>
    <MyBookshelf height="1,5m" width="1m">
        <Book name="A book" pages="666"/>
        <Book name="Another book" pages="123"/>
    </MyBookshelf>
</MyRoom>
</pre></code>

We see that XML has something like tags in HTML. (called elements in XML)
An element can be opened and closed again (<code><element></code>; <code></element></code>) or be empty, which is shown through the "/" at the end of the element.

Elements can have attributes (height) with a value (1,5m), but they aren't necessary.

Elements hav parents (the outer element; parent of MyBookshelf would be MyRoom) and children (a child has only one parent but a parent can have multiple children).

To make a frame fir our AddOn we'll do the following in our .xml:
<code><pre>
<Ui xmlns="http://www.runewaker.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.runewaker.com/..\..\WorldXML\UI.xsd">
    <Frame name="MyAddon_MainFrame" parent="UIParent" inherits="UICommonFrameTemplate" hidden="false" enableMouse="true">
	<Size>
		<AbsDimension x="320" y="300"/>
	</Size>
	<Anchors>
		<Anchor point="CENTER">
			<Offset>
				<AbsDimension x="0" y="0"/>
			</Offset>
		</Anchor>
	</Anchors>
	<Layers>
		<Layer>
			<FontString name="MyAddon_MainFrame_Title" inherits="GameTitleFont" text="Title">
				<Anchors>
					<Anchor point="TOP" relativePoint="TOP">
						<Offset>
							<AbsDimension x="-10" y="8"/>
						</Offset>
					</Anchor>
				</Anchors>
			</FontString>
		</Layer>
	</Layers>
    </Frame>
</Ui>
</pre></code>

What does everything do?

<code><pre><Frame name="MyAddon_MainFrame" parent="UIParent" inherits="UICommonFrameTemplate" hidden="true" enableMouse="true"></pre></code>
Starts a Frame with the apperance of a default-frame. (like the bag- or guild-frame)
name = Name of the frame. Must be unique and is used to identify the element in the .lua.
parent = The parent of the frame (i don't know if you can leave this out).
inherits = Some default-values for the element rather then setting everithing by hand (UICommonFrameTemplate can be found in "ui.xls" in "interface.fdb/interface/worldxml/".
hidden = Defines if the frame is hidden or not.
enablemouse = If the frame can get mouse input.

<code><pre><Size></pre></code>
Defines the size of the element
<code><pre><AbsDimension x="320" y="300"/></pre></code>
An element to define sizes.
x = Width.
y = Height.

<code><pre><Anchors></pre></code>
Contains the location of the element via anchors.
<code><pre><Anchor point="CENTER"></code>
An anchor for the element.
point = A relative point. If no element to align relative to is given then the parent will be used. CENTER aligns the frame in the center of the parent element.
<code><pre><Offset></pre></code>
An Offset of the element. Can be used to align it e.g. 200 px right from the center.
<code><pre><AbsDimension x="0" y="0"/></pre></code>
Again AbsDimension. Here the Offset is set.

<code><pre><Layers></pre></code>
Layers are texts on the frame. <Layers> contains all of them.
<code><pre><Layer></pre></code>
One layer.
<code><FontString name="MyAddon_MainFrame_Title" inherits="GameTitleFont" text="Title"></code>
FontString is a layer with Text in it.
text = The text that is displayed on the FontString.

This displays a Frame with the title set in the FontString.

But just a frame with a title isn't enough for a real addon. Where are the buttons, textfields and that stuff?
To Use all that Stuff wee first need to set a Frame where all this is going. (I don't know why it cannot be put into MyAddon_MainFrame, but it can't.
So add the following code:
<code><pre>
<Ui xmlns="http://www.runewaker.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.runewaker.com/..\..\WorldXML\UI.xsd">
...
...
        </Layers>
        <Frames>
            <Frame name="MyAddon_Content">
	        <Anchors>
		    <Anchor point="TOPLEFT"/>				
	        </Anchors>
    	        <Frames>
	    	    <!-- Here our button will go -->
	        </Frames>
            </Frame>
        </Frames>
    </Frame>
</Ui></pre></code>

What does <code><Frames></code> do? It gives us a space inside an element, where we can add frames inside of it.
In our example we add a frame called "MyAddon_Content" into "MyAddon_MainFrame" to put the button in.
In the MyAddon_Content frame we open <code><Frames></code> again to add the button. (because the button is threaded as a frame itself)

The Text between the <code><!--</code> and <code>--></code> is a commentary.

Now lets replace this commentary with our button:
<code><pre>
<Button name="MyAddon_TestButton" inherits="UIPanelButtonTemplate" text="Test">
    <Size>
        <AbsDimension x="50" y="25"/>
    </Size>
    <Anchors>
	<Anchor point="TOPLEFT" relativeTo="MyAddon_Content" relativePoint="TOPLEFT">
	    <Offset>
		<AbsDimension x="0" y="0"/>
	    </Offset>
	</Anchor>
    </Anchors>
    <Scripts>
	<OnClick>
            <!-- Add vour script to call when the button is clicked here -->
	</OnClick>
    </Scripts>
</Button>
</pre></code>

We see that we use an element called <code>Button</code>.
With inherits="UIPanelButtonTemplate" we will use the standard-button used in RoM,
which prevents us from the need to define a texture and stuff like that.
You can unpack "interface.fdb" and look into the files in "/interface/worldxml/" to see other templates.

There are still some things to lern about placement of elements in frames.
as seen in <code><Anchor point="TOPLEFT" relativeTo="MyAddon_Content" relativePoint="TOPLEFT"></code> and in the frame ingame the button is places in the top left corner of the frame.
This is done defining a relative anchor.

point = The point where the element should be "grabbed" at to place it relative.
possible are:
TOP
TOPRIGHT
RIGHT
BOTTOMRIGHT
BOTTOM
BOTTOMLEFT
LEFT
TOPLEFT

relativeTo = An element to place relative to. If not set then outward element will be used.

relativePoint = Where at the relativeTo-element the at "point" defined point should be attached to. Cas have the same values as point.

There are more elements like CheckButtons, EditBoxes and stuff, which are used pretty similar in the code like the button.
And maybe some examples out of WoW can be used to.

The complete code would look like
<code><pre>
<Ui xmlns="http://www.runewaker.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.runewaker.com/..\..\WorldXML\UI.xsd">
<frame name="MyAddon_MainFrame" parent="UIParent" inherits="UICommonFrameTemplate" hidden="false" enableMouse="true">
	<Size>
		<AbsDimension x="320" y="300"/>
	</Size>
	<Anchors>
		<Anchor point="CENTER">
			<Offset>
				<AbsDimension x="0" y="0"/>
			</Offset>
		</Anchor>
	</Anchors>
	<Layers>
		<Layer>
			<FontString name="MyAddon_MainFrame_Title" inherits="GameTitleFont" text="Title">
				<Anchors>
					<Anchor point="TOP" relativePoint="TOP">
						<Offset>
							<AbsDimension x="-10" y="8"/>
						</Offset>
					</Anchor>
				</Anchors>
			</FontString>
		</Layer>
	</Layers>
	<Frames>
		<Frame name="MyAddon_Content">
			<Anchors>
				<Anchor point="TOPLEFT"/>				
			</Anchors>
			<Frames>
				<Button name="MyAddon_TestButton" inherits="UIPanelButtonTemplate" text="Test">
					<Size>
						<AbsDimension x="50" y="25"/>
					</Size>
					<Anchors>
						<Anchor point="TOPLEFT" relativeTo="MyAddon_Content" relativePoint="TOPLEFT">
							<offset>
								<AbsDimension x="0" y="0"/>
							</offset>
						</Anchor>
					</Anchors>
					<Scripts>
						<OnClick>
							<!-- Add vour script to call when the button is clicked here -->
						</OnClick>
					</Scripts>
				</Button>
			</Frames>
		</Frame>
	</Frames>
</Frame>
</Ui>

</pre></code>

	Core Sites: Curse.com Curse Forge WoWAce
	Database Sites: WoWDB WarDB Conan Armory Runes of Magic DB Aion Armory
	Community Sites: Arena Junkies FFXIV Core World of Raids Aion Source Warhammer Alliance Zybez Runescape Help Tera Fans
	Wikis: Runes of Magic Wiki Evony Wiki Diablo Wiki Wonderking Wiki Empire Craft Wiki