[highlight]** Notice **[/highlight]
Some of the links provided may no longer work due to the forum restructuring. I'll fix them up when I can.
Notes:
See also post #6 below for more slash commands and equivalent Lua code.
Introduction
I've been seeing a lot of questions regarding macros as well as many basic mistakes in their use. Further, the existing macro creation guides are woefully out of date. So I decided to write up this guide in the hopes of correcting this problem even just a little bit (if anyone bothers to read this thing, that is).
The goal of this guide is to take the reader from knowing nothing about macros, to being able to write complex macros with Lua support, including writing custom commands. This is going to be a information dense guide because it needs to cover a lot of ground, so lets get started.
What's a Macro
Macros are quick little helper commands that you can create and assign an icon to, then place on your action bars to use. The commands themselves are things you can type directly in the chat edit box and typically start with a slash (for this reason they are commonly known as slash commands).
For an example of a slash command, open the chat edit box (press the
[ENTER] key) and type the following to make your character start dancing (press
[ENTER] again once you have finished typing):
|
Source code
|
1
|
/dance
|
This slash command is one way to perform an emote. Press the
[H] key to bring up a window with all the emotes in the game. Note how they all show the slash command for the emotes (try them out). Of course there are other commands, but we'll get to those a little later.
Now lets actually create a basic macro. For our first macro we'll have it perform this same dance emote (or another of your choosing). First we need to open the macro window. We do this either by pressing
[ESC] and selecting the
Macro button from the main menu, or by typing
/macro in the chat edit box (yes, this last uses a slash command to open the macro window).
With the macro window up, click
New to create a new macro. In the macro edit window that opens, click the little arrow button at the top to select an icon for this macro, then in the small edit box next to this same arrow, type a name for this macro.
In the larger edit box, add the same emote slash command we had before (or another of your choosing):
|
|
Source code
|
1
|
/dance
|
Save the macro and close the macro edit window. You should now see the icon you selected in the macro window. Using the mouse, drag the icon for the macro you just created to an empty slot on an action bar. Close the macro window.
To test this macro out, click the macro icon you just placed on your action bar and your character will perform the emote indicated in the macro.
Multiple Commands in a Macro
We can have multiple commands in a macro. There is a limit to the number of characters we can place in the code body of a given macro (namely 255 characters, including spaces), but as long as we are under this limit, we can add more commands. However, to make macros more useful, we'll need to know about a few more commands.[INDENT]
/wait time to wait, in seconds[INDENT]Waits the specified number of seconds before continuing execution of the macro.
[/INDENT]
/cast name of skill or spell[INDENT]Casts the named spell or skill. The name must
exactly match the name in the skill book, including case. The skill/spell must be in your skill book in order to be used.
[/INDENT]
/use name of item to use[INDENT]Uses the named item. The name must
exactly match the name of the item, including case. You must possess the item in your inventory in order to use it. If the item is equipable, it will be equiped. If it is consumable (such as a healing potion), it will be consumed. If the item cannot be used at all, nothing happens.[/INDENT][/INDENT]
Given the commands above, we can have our avatar start dancing and then cast a spell or use an item. Open the macro panel again, select the macro we created earlier then click the
Modify macro button. Change the macro's code to something like this:
|
|
Source code
|
1
2
3
|
/dance
/wait 5.5
/cast Wave Armor
|
As can be seen, this macro makes the character dance, then five and a half seconds later (a little more than the duration of the dance) the character will cast Wave Armor (a priest buff spell). You will likely need to change the spell being cast to something your avatar can do, or have it use an item instead of using a spell.
We can have the macro send text as well. We do this via the same methods used to send text on different chat channels. Here's a table of some of the slash commands for sending text on specific channels.
[INDENT]
/s text to be sent
/say text to be sent[INDENT]Sends text to the say chat channel. This is the normal, default chat channel.[/INDENT]
/z text to be sent
/zone text to be sent[INDENT]Sends the text to the zone chat channel.[/INDENT]
/g text to be sent
/guild text to be sent[INDENT]Sends the text to the guild chat channel. Must be a member of a guild for this to work.[/INDENT]
/p text to be sent
/party text to be sent[INDENT]Sends the text to the party chat channel. Must be a member of a party for this to work.[/INDENT]
/world text to be sent[INDENT]Sends the text to the world chat channel. Must have a megaphone for this to work.[/INDENT]
/w Player Name text to be sent
/whisper Player Name text to be sent
/t Player Name text to be sent
/tell Player Name text to be sent[INDENT]Sends the text to the player specified by
Player Name. This command is less useful in a macro since you must specify the name of the player you are sending the text to.[/INDENT]
/1 text to be sent
/2 text to be sent
...
/9 text to be sent[INDENT]Sends the text to one of the custom chat channels. Must join or create a custom channel for this to work. The first custom channel joined becomes
/1, the second becomes
/2 etc.[/INDENT][/INDENT]
Given this, we can modify our macro to say something to one of the custom channels. As an example, modify the macro to something similar to this:
|
|
Source code
|
1
2
3
4
5
|
/s Wheeeee....
/dance
/wait 5.5
/s Protection time!
/cast Wave Armor
|
Of course, you might want to change what your character says
Save and try out this new version of the macro.
Some Caveats with Macros
One question that often comes up at this point is how to have different spells/skills cast depending on the current situation. A variant of this question is how to cast a given spell/skill over and over. The answer to the first is that it cannot be done directly (we'll see that there are a few ways to actually achieve this, so not a real problem).
The second simply cannot be done, and this is by design. Runewaker does not want bots to be written and macros that perform loops can actually help lead to this. Runewaker has gone out of their way to stop this type of macro behavior (among other things) and so don't expect to be able to do it, nor to be smiled at by Frogster/Runewaker if you do manage to find a workaround.
For those coming to RoM from other games with macro support, this at first may seem a little more restrictive, but in the end it isn't really. As proof of this (and one way to get around the first little problem), check out the add-on called
WoW 'Like' Slash Commands (
http://rom.curse.com/downloads/rom-addon…ils/wowlsc.aspx). This add-on allows extra functionality for use in macros. Worth the look.
However, even without this add-on, there is much we can do by using a feature that Runewaker specifically added. The ability to execute Lua commands directly from a macro.
Embedding Lua into a Macro
When a macro needs to perform actions for which there are no slash commands, we need to start accessing the Lua function API instead. Lua is the scripting language embedded into the game and is what is used by add-on makers to create the addons we've come to enjoy. Indeed the entire Runes of Magic user interface is also written in Lua.
The way to get a macro to execute some Lua code is by using either of the following commands (they are in fact synonymous):
[INDENT]
/script Lua code to execute
/run Lua code to execute[INDENT]Compiles and executes a line of Lua script code.[/INDENT][/INDENT]
As these commands do exactly the same thing, it is advised to use
/run since this will save you three characters when used in the limited character space of a macro's code body.
As an example of using this command, lets modify our macro so that instead of sending text to the chat channel, we'll have the text display in the chat box, but only to ourselves (and thereby not annoy everyone around us). We do this via the Lua function
DEFAULT_CHAT_FRAME:AddMessage with the text we wish to display like this:
|
|
Source code
|
1
2
3
4
5
|
/run DEFAULT_CHAT_FRAME:AddMessage("Wheeeee....");
/dance
/wait 5.5
/run DEFAULT_CHAT_FRAME:AddMessage("Protection time!");
/cast Wave Armor
|
Note the use of the
/run commands here. When calling Lua functions, the information we need to pass to the function is specified in between parentheses. These are called the
parameters to the function. Note also that the text we want to display is enclosed in double quotes. If we had more than one parameter, we would seperate them with commas.
In fact, the
DEFAULT_CHAT_FRAME:AddMessage function allows a color to be chosen for the text by giving the individual red, green and blue amounts as parameters to the function (in that order). Modify the macro like this:
|
|
Source code
|
1
2
3
4
5
|
/run DEFAULT_CHAT_FRAME:AddMessage("Wheeeee....",1,1,1);
/dance
/wait 5.5
/run DEFAULT_CHAT_FRAME:AddMessage("Protection time!",0.9,1.0,0.2);
/cast Wave Armor
|
The difference here is that the text will come out white for the first line, and a shade of greenish-yellow for the second.
Conditional Code
Now that we've seen how to execute Lua commands, lets revisit the problem of having conditional code in our macros.
Even though macros do not have a way to directly run different parts based on some condition, Lua does allow it. There is a catch however, due to how macros work. Each macro line is executed individually and independently. Therefore, we must specify the entire condition within one macro line. This does give some restrictions, but we'll later see how we can get around this as well.
The basic conditional in Lua is the
if statement and works like this:
[INDENT]
if condition then statement to do if condition is true end[/INDENT]
The parts in bold are required, while the parts in italics are what you need to change. For the condition, this must be something that translates to a true or false value. This can be a variable, a comparison, or a function that returns a true or false value (we'll get to these things in a bit).
To see this is action, lets make a macro that will display different messages to ourselves in the chat window depending on whether or not the shift key is held down. Create a new macro and add the following for the macro's code:
|
|
Source code
|
1
2
|
/run if IsShiftKeyDown() then DEFAULT_CHAT_FRAME:AddMessage("Shift is held down") end
/run if not IsShiftKeyDown() then DEFAULT_CHAT_FRAME:AddMessage("Shift not being held") end
|
Here, we use the Lua function
IsShiftKeyDown to ask the game if the shift key is held. This function returns a true or false value based on the state of the shift key and therefore satisfies our need for the condition part of the if statement. Also note the use of the
not operator in th second if statement. This operator inverts the true/false value returned by the function.
Try running the macro without holding the shift key, then while holding the shift key to see the difference. Notice that we needed to have two seperate lines, one for each message we wanted. This is a little wastefull. Thankfully, Lua's if statement also has the ability to selectively execute some code if the condition is false. The more complete version of Lua's if statement looks like this:
[INDENT]
if condition then when true statements else when false statements end[/INDENT]
Given this, we can rewrite our macro onto one line like this:
|
|
Source code
|
1
|
/run if IsShiftKeyDown() then DEFAULT_CHAT_FRAME:AddMessage("Shift is held down") else DEFAULT_CHAT_FRAME:AddMessage("Shift not being held") end
|
Try this new version out. It now acts like before, but only uses one line (and fewer characters).
With the above under our hats, what about casting spells or using items. We can't use the normal macro slash commands inside the Lua script part because it is Lua script, not macro code per-se.
The answer lies with the Lua functions
CastSpellByName and
UseItemByName. These functions take the name of the spell or item as their parameter much like the macro counterparts (in actuality, the macro slash commands re-direct to these Lua functions). So to have the macro cast a spell if the shift key is held, and another if it isn't we could do something like this:
|
|
Source code
|
1
|
/run if IsShiftKeyDown() then CastSpellByName("Regenerate") else CastSpellByName("Wave Armor") end
|
Modify the spells/skills to be used to something your character can do, or modify the code to use an item instead. Now try it out.
At this point, you are likely starting to get a feel for just how powerful such macros can be. But we can push things further still.
Using Custom Functions and DIYCE for advanced macros
DIYCE or Do-It-Yourself Combat Engine is a rather popular add-on created by Sixpax to allow even more complex macroing using Lua functions. This add-on does require you to understand Lua and Lua functions in a more fundamental way and a tutorial on its use is beyond the scope of this guide, though you can get more information on its use in these threads:
[INDENT]
http://forum.us.runesofmagic.com/showthread.php?t=33610[INDENT]The DIYCE thread itself. Includes links to the add-on itself on Curse. Use the version on Curse, not the Zip file linked as an attachment.[/INDENT]
http://forum.us.runesofmagic.com/showthread.php?t=12682[INDENT]Thread on creating your own Lua functions, either for DIYCE or just generic helper functions. Consider this recommended reading.[/INDENT]
[/INDENT]
Creating Your Own Slash Commands
As promised, we'll be covering how to create our very own slash commands for use with macros. In order to fully appreciate this part, you will need to familiarize yourself with Lua and how to create your own Lua functions. In fact, we'll mostly be leaving the world of macros behind and entering the world of add-on creation. In short, this is a very advanced topic, so don't feel bad if you don't understand it all.
In order to get this working, we'll need to actually create a small add-on for RoM. This is needed so that we can get the game to load our slash commands that are in reality Lua functions.
The first thing is to ensure that we have the correct folders created so that the game can find and load our little add-on. Within the game folder (typically this is
C:\Program Files\Runes of Magic\ ), make sure that there is an
Interface folder (if not, create it). Now inside this
Interface folder, make sure there is an
Addons folder (again, if this folder doesn't exist, create it). This
Addons folder is where RoM will look for any add-ons that may need to be installed.
When RoM looks for an add-on, it looks for any sub-folders in the
Interface\Addons folder and when it finds one, will look inside this sub-folder for a text file with the same name as this sub-folder and a
.toc file extension. This file is the Table Of Contents for this add-on and lists all the files the game will need to load in order to activate the add-on.
So first, we need to decide what we want to call our slash command add-on. For this guide I'll call it
MySlashCommands though the you can give it some other name. Therefore, create yet another folder within the
Interface\Addons folder called
MySlashCommands and within this sub-folder, create a new text file called
MySlashCommands.toc. Now open this file in a text editor and add the following:
|
|
Source code
|
1
|
MySlashCommands.lua
|
Save the file (make sure that it is saved as
MySlashCommands.toc and not adding a .txt extension to the name or anything.
What this says then is that when the game loads the add-on, it should load the file
MySlashCommands.lua and execute it in order to activate this add-on. Obviously, we'll need to create this file as well, so create and open the file
MySlashCommands.lua.
This file is where we will define our new slash commands. For our first example slash command, enter the following:
|
|
Source code
|
1
2
3
4
|
SLASH_FirstTest1 = "/firsttest"
SlashCmdList['FirstTest'] = function(ebox, msg)
DEFAULT_CHAT_FRAME:AddMessage("It Worked!");
end
|
Save the file (again making sure that it is saved as
MySlashCommands.lua) and then start the game. Once in the game, try typing
/firsttest in the chat edit box. If our add-on loaded successfully, our slash command will run displaying the message
It Worked! in the chat window. If it works in the chat edit box, try it in a macro.
Okay, here's how this Lua code works. The first line is specifying what the actual slash command that needs to be typed in the chat edit box or in a macro. What is important to know here is that the slash is included in the name we give (the part that is between the double quotes), and the name given should be unique otherwise it may interfere with some other slash command.
The second thing to notice is what the variable being assigned is actually called. It has the following form:[INDENT]
SLASH_SomeName1 = "slash command"[/INDENT]
The
SomeName part is chosen by us and again should be something unique, though it need not be the same as what the slash command is called. This part is used in the second line of our Lua file, where we declare the slash command's function. It has the form:
[INDENT]
SlashCmdList["SomeName"] = function (ebox, msg)[/INDENT]
Note the part of the name we used in the first line of the Lua file is identical to the name in double quotes used in the second line. This is how the game associates the slash command with our function to be executed when the slash command is typed and therefore it is important to keep these the same, including case.
The
ebox and
msg parameters for our slash command function are a little special and so deserve a little explanation. The first (
ebox) is a reference to the chat edit box that the slash command was typed into. You can generaly ignore this parameter, though it is required to be present for the slash command function to work correctly. The second parameter (
msg) is a string containing any extra text after the slash command itself.
This last is something important since it allows us the ability to pass information from the chat edit box or macro to the slash command function. To demonstrate, lets create another slash command to display whatever text we give it. Exit the game and open
MySlashCommands.lua and add the following at the end of the file:
|
|
Source code
|
1
2
3
4
5
6
7
|
SLASH_Echo1 = "/echo"
SlashCmdList['Echo'] = function(ebox, msg)
if msg == nil then
msg = "<No Text Given>"
end
DEFAULT_CHAT_FRAME:AddMessage("Text passed in was: "..msg);
end
|
Note how we first check to see if the
msg parameter is not
nil. This ensures that there is some text to display otherwise we may get an error. If no text was present, we set the text the be
<No Text Given> so we can see this fact. Also notice the use of the double-periods (
..). This is Lua's concatenation operator and concatenates a string or number to another string.
Save the file and restart the game. Try typing
/echo with and without text such as:
|
|
Source code
|
1
2
|
/echo Some text to show
/echo
|
Also try it in a macro. Though you will likely note that it never seems to show the
<No Text Given> text, it is still important to check in this fashion as there are times where this may be required.
Further Reading
We've reached the end of our whirlwind tour of macro creation. As can be seen from the amount of information in this guide alone, macros are an incredibly powerful feature of Runes of Magic. Though they come at the cost of the amount of knowledge needed to make them. I hope this hasn't been too overwhelming. Here are some links that contain yet more information for you to digest:
[INDENT]
https://forum.runesofmagic.com/showthread.php?t=16065 (EU Forum)
http://forum.us.runesofmagic.com/showthread.php?t=229 (US Forum, has link to EU forum post)[INDENT]The original macro guides.[/INDENT]
http://forum.us.runesofmagic.com/showthread.php?t=33610[INDENT]The DIYCE thread itself. Includes links to the add-on itself on Curse. Use the version on Curse, not the Zip file linked as an attachment.
[/INDENT]
http://forum.us.runesofmagic.com/showthread.php?t=12682[INDENT]Thread on creating your own Lua functions, either for DIYCE or just generic helper functions. Consider this recommended reading.[/INDENT]
http://www.theromwiki.com/Runes_of_Magic_Wiki[INDENT]The Runes of Magic Wiki. Lots of info on Lua scripting[/INDENT]
http://www.lua.org/pil/index.html[INDENT]Programming in Lua online book. First stop to learn Lua programming.[/INDENT]
[/INDENT]
Runes of Magic US / AU »
Runes of Magic - (US) »
Game Guides »
Quoted from "bugman543;427151"
this is my full marco, after linking
