When you join a game or choose “Reload Macros” from the Options menu,
Clan Lord will load the file with the same name as your character from the Macros folder.
For example if your character’s name is “Gaia” then the client will look for a file
called “Gaia” inside the “Macros” folder, and attempt to load all the macros therein.
If no such file exists then the client creates a new, blank one.
It also creates the macro folder and a file named “Default” if they do not exist.
Within a macro file, you can tell Clan Lord to load other files,
located in the Macro folder, by having a line like:
include "Default"
include "Item Macros"
The “include” statement loads the contents of the other file exactly as if
it were inserted where the “include” is.
Macro Declarations
A macro consists of a “trigger” which explains when it should be done,
and “commands” which define what it should do.
There are two possible ways of declaring a macro: a short form and a long form.
If you have more than one command in the macro, you must use the long form;
but with one command you can use either.
SHORT FORM
trigger command
LONG FORM
trigger
{
command
command
command
(as many commands as you want, 1 per line)
}
Controlling Execution
Whenever a macro is executing, the text box will display a thicker outline.
Typing control-escape will stop all executing macros.
More than one macro may be executing at the same time.
Some environmental variables can also be set to control how a macro behaves.
See the CL-Defined Variables section, below.
Escape Characters
In order to use special characters which control how CL loads macros in an expression,
you must use a backslash (\) before them. Commonly used ones:
\\ backslash \" double quote \' single quote \r return
NOTE: When you type a command directly in CL, you can begin it with either
a forward or backward slash: either / or \ will work.
However, within a macro expression, you must use '/':
write /action, not\action.
Comments
Any line beginning with // is a comment and will be ignored.
More accurately, the two characters “//” signal the beginning of a comment
that extends to the end of the line.
Any text preceding the // is not a comment, and is retained.
// This is a comment
command // this line has both a command and a comment
Any text between /* and */ is also a comment.
This kind of comment can span multiple lines.
/*
This is a longer comment
that occupies more than one line.
*/
"expression"
(the expression in quotation marks - case sensitive)
These are triggered when you hit the Return key and the trigger expression begins the line.
An expression with spaces in it will not work as a trigger, because only the first word
of the line will be examined to see if it matches.
Examples
"lol" "/action laughs until he cries.\r"
"jump" "/action nimbly jumps over the " @text "\r"
"grfem"
{
"Hello fair lady "
@text
"!\r"
}
Replacement Macros
'replacetext'
(the word to replace in single quotation marks - case sensitive)
These are triggered when you are typing and hit any key that isn’t
a letter or a number, and the trigger is the last word before the
insertion point. If you hit return, the last word of the line is
compared to the trigger. You can type a space or a return without
triggering a replacement macro by holding down the control key
while typing them. Replacement macros end execution immediately, so
you cannot use any commands that cause a delay, nor any return (\r)
characters. One good use of replacement macros is for
abbreviations that automatically expand themselves, as in the first
two examples below.
Examples
'OC' "Orga Camp"
'ELF' "E\'las Loth\'mon Ferindril"
'hi'
{
random
"H\'loi"
or
"Greetings"
or
"Good day"
or
"Good morning"
end random
}
Key Macros
key
modifier-key
modifier1-modifier2-key
(the key to be pressed, with as many modifiers as you want)
Key macros are triggered by hitting the specified key combination.
If a key combination would normally do something and you define a macro for it,
your macro will be used instead of the normal action.
For example, a command-p macro would override the Command menu “Pull”
that’s usually attached to that key combination.
For most keys, the character that is printed when you type the key is the key name,
but some have special names:
Using the option modifier with letters is a bit tricky because typing option-letter often changes the letter.
For example: On most U.S. systems and keyboards, typing option-s actually produces the
single character ß. So to use option-s as a macro key, you
will need to use the option-character in the macro definition.
That is, macros defined like this will set the text to “this succeeds”
when you hit option-s:
option-s "this fails"
option-ß "this succeeds"
The “Click” Keys
The “click” key lets you make clicking on a player
with certain modifiers do something.
The macro executes if you click on a player in the Players window or in the game window.
The one exception is that a macro defined for a plain click with no modifiers won’t work
in the Players window (this would override you being able to use the Players window!).
If you have a multi-button mouse, you can also use the names “click2”,
“click3”, etc. These are triggered when you press the corresponding mouse button.
You may need to experiment a bit to find out what the button numbers are for your mouse.
“click2” is almost always the secondary or right button; but beyond that,
the ordering is hardware-defined.
You’ll have to do some tests to figure out which buttons are which for your mouse.
“right-click” is a synonym for “click2”.
Examples
f1 "/action twitches his tail.\r"
command-m "/give " @selplayer.simple_name " 1\r"
shift-enter "/action " @text "\r"
command-option-µ "/pull " @selplayer.simple_name "\r"
// Must be µ, not m, because of the option key)
control-option-click
{
if @click.name != ""
"Get out of my way " @click.name "!\r"
end if
}
The “Wheel” Keys
If you have a scroll-wheel mouse, you can write macros that are triggered by
moving the wheel.
If you assign a macro to the “wheelup” pseudo-key, it’ll be triggered
when you scroll up; “wheeldown” works in the other direction.
You can also assign macros to “wheelleft” and “wheelright”,
but they’ll only work if: (a) you really do have a horizontal wheel,
or (b) you hold down the shift key while turning the regular (vertical) wheel.
Function Macros
trigger
(just the word that is the function name)
Function macros are triggered by a “call” command from within another macro.
See the Commands section for more information.
The “@login” Macro
If you have a function macro called “@login”,
it will run automatically when you log into the game,
or whenever you choose the “Reload Macros” menu item.
An attribute is a line that you can put in a macro to change how it behaves.
An attribute is not executed at a certain place in a macro;
rather, it controls how CL and the macro interact.
Therefore, you can put an attribute anywhere in a macro.
All attributes begin with a $ character.
Supported Attributes
$ignore_case
Only affects expression and replacement macros; makes the macro execute disregarding case.
$any_click
Normally click macros only execute if you click on a player.
But a click macro having this attribute will execute whenever
you click anywhere in the game window.
$no_override
Normally macros override any further handling of a key, click, or typing.
With this attribute, the macro will be executed, and the normal action
for the click or key will also be done.
Examples
A pair of macros that let you hold shift and click
if you want to use click-toggles mode, and click
normally for click-and-hold movement:
shift-click
{
$no_override
$any_click
"/pref movement toggle\r"
}
click
{
$no_override
$any_click
"/pref movement hold\r"
}
A variable is the programming term for a name that is set to another value.
For example, we might have a variable called race;
we can set this variable to hold the value “Thoom”.
Now whenever we refer to the name, race,
the text “Thoom” will be substituted.
Later we could change race to be “Sylvan”.
Now we could do exactly what we did before, but every reference to
race will now be substituted with “Sylvan” instead.
Global Variables
These variables are defined the same for every macro that you run.
To define one, use a set statement that isn’t inside any macro.
set num 1
set who "Keriul"
Notice that if the variable is text, you enclose it in quotation marks;
and if it is numerical, you don’t. Now we can use these values in any macro:
"vartest2"
{
"Hello " who " you are " num "\r"
}
This will output:
Hello Keriul you are 1 (return)
Local Variables
These variables are defined only for the macro they are declared within.
You declare them the same as you would a global variable, except they are within a macro
(that is, inside the curly braces { } surrounding the macro’s contents).
"vartest2"
{
set num 1
set who "Keriul"
"Hello " who " you are " num "\r"
}
This will output:
Hello Keriul you are 1 (return)
Now assume that we didn’t have those global variable declarations described above,
but we had these macros named vartest1 and vartest2
in the same macro file:
"vartest1"
{
"Hello " who " you are " num "\r"
}
"vartest2"
{
set num 1
set who "Keriul"
"Hello " who " you are " num "\r"
}
vartest1 will output:
Hello you are (return)
In vartest1 the variables who and num are not defined,
so they count as nothing! (i.e. as empty space.)
Setting Global Variables from Within a Macro
Suppose you had a global variable named who and you wanted a macro to
be able to change it. To do this, you use the setglobal command from within a macro:
set who "Kerial"
"set1"
{
setglobal who "Ternia"
}
"vartest1"
{
"Hello " who "\r"
}
Now if you use vartest1 you get:
Hello Kerial (return)
But now if you type
set1 (return)
the set1 macro executes, changing the global variable,
so that when you do vartest1 again you get:
Hello Ternia (return)
Global and Local Variables with the Same Name
This is best shown by example.
You can have the same variable name for both a global and a local variable.
If you change the local one, the global one won’t be affected;
it will remain the same in all other macros, apart from the current one —
in which there’s now a local variable with the same name.
By setting some special variables you can control how CL loads and uses macros.
By putting others in your macros, you can get information about your character
or other characters.
All special variables start with an @.
Here is a list of all of these variables.
@env Variables
Variables with an @env prefix control how macros execute.
@env.echo (true/false)
When true, then after any \r in a macro, replace the text in the input box
by the text that was sent.
@env.debug (true/false)
When true, give extra information on macro loading and execution.
@env.key_interrupts (true/false)
When true, stop executing a macro when a key is pressed.
@env.click_interrupts (true/false)
When true, stop executing a macro when you click in the game window
(where clicks move your character).
@my Variables
Variables with a @my prefix concern your character.
@my.name
Your character’s full name.
@my.simple_name
Your character’s simple name (no spaces or punctuation).
@my.right_item, @my.left_item
The names of the items in your right and left hands.
@my.right_item, @my.left_item,
@my.forehead_item, @my.neck_item,
@my.shoulders_item, @my.arms_item,
@my.gloves_item, @my.finger_item,
@my.coat_item, @my.cloak_item,
@my.torso_item, @my.waist_item,
@my.legs_item, @my.feet_item, @my.head_item
The names of the items equipped in other locations.
@my.selected_item
The name of the item that’s currently selected in the Inventory window.
@selplayer Variables
Variables with a @selplayer prefix refer to the selected character.
@selplayer.name
Selected character’s name.
@selplayer.simple_name
Selected character’s simple name (no spaces or punctuation).
@click Variables
Variables with a @click prefix are used within a click macro
to refer to the character that was clicked on.
@click.name
The clicked-on character’s name.
@click.simple_name
The clicked-on character’s simple name (no spaces or punctuation).
@click.button
A number (from 1 to 8) that identifies which mouse button was just pressed.
The main or left button is #1, the secondary or right button is #2,
additional button numbers are hardware-dependent.
You’ll have to perform some tests to figure them out for your particular mouse.
@click.chord
A number that indicates the state of all the mouse buttons.
This value is actually a bitmap of all the currently pressed buttons,
where the lowest-order bit corresponds to button #1.
Miscellaneous Variables
@text
The complete text in the typing box when the macro started
(minus the expression of an expression macro).
@textsel
The selected text in the typing box when the macro is started.
@random
A number between 0 and 9999, randomly generated each time this variable is referenced.
Words and Letters
By appending these trailers on the end of any variable,
you can refer to words or letters of that variable’s value.
.word[n]
The nth word of a variable. The first word is numbered zero.
.num_words
The number of words in a variable.
.letter[n]
The nth letter of a variable. The first letter is numbered zero.
If a line starts with a command word, then Clan Lord takes special action
(described below for each command).
Otherwise, the words in the line are just interpreted as text,
as if you had typed them into the input box directly.
You can only have one command per line.
You can use variables for any of the parameters of the various commands.
If the first word of a line is not another command, i.e. one of “pause”,
“set”, “setglobal”, etc., then Clan Lord assumes that the line
is regular text.
Any text in quotes (the straight kind, like "this" — not the curly kind,
like “this”) is just inserted as-is (after removing the quotes).
Anything else, not in quotes, is assumed to be the name of a variable,
and the value of that variable is inserted in its place.
As a macro executes, it concatenates text until it reaches an end-line character “\r”,
at which point it sends all the text it has saved so far up to the server,
and pauses one frame.
If there is text after the last “\r” of the macro,
then this text is inserted into the text field.
This means that if there are no “\r” characters,
the text is simply inserted into the typing area, without being sent to the server.
Examples
"gr"
{
"Hello "
@selplayer.name
"!\r"
}
Outputs:
Hello Joe! (return)
(Assuming you have Joe selected.)
"/sleep"
{
"/pose lie\r" "/action lies down and closes his eyes.\r"
pause 10
"/sleep\r"
}
Outputs: /pose lie (return) /action lies down and closes his eyes. (return)
(Waits ten frames) /sleep (return)
f1 "/thinkto " @selplayer.simple_name " " @text "\r"
Outputs: /thinkto Thyin Where are you hunting? (return)
Assuming your input box already contained "Where are you hunting?" and
you have player Thyin selected before pressing F1.
f13 "Tergon d\'Aleria mon\'Savreyte von Wendia"
Pressing F13 inserts your very complicated name,
as if you had typed it out in full.
Pauses the macro for number frames.
One frame is approximately equivalent to one-quarter of a second.
(A little bit slower during “prime time”; a little faster during off-peak times.)
Examples
shift-#
{
"/pose sit\r"
pause 1
"/pose leanleft\r"
pause 1
"/pose leanright\r"
pause 1
"/pose stand\r"
pause 1
}
// Makes your character do a simple dance (on shift 3)
"pn"
{
"/action sits down and scratches his head.\r"
pause 20
"/ponder " @text "\r"
}
// If your character is dim-witted, adds a pause to every ponder.
set <variable name> <value>
OR set <variable name> <operation> <value>
<operation> must be one of: + - * / %
Sets the local variable, or does an operation on its current value
(see the Variables section).
The + operator can be used to concatenate two string variables,
but all other operators assume numeric variables, and give a numeric result.
string + string = concatenation ("a" + "b" = "ab")
number + number = addition (1 + 2 = 3)
string + number = concatenation ("a" + 2 = "a2")
number + string = not allowed (1 + "b" : "Syntax error")
setglobal <variable name> <value>
OR setglobal <variable name> <operation> <value>
<operation> must be one of: + - * / %
Sets the value of a global variable, or does an operation on its current value.
Examples
f8
{
set num 1 // the value of ‘num’ is now 1
num "\r"
set num + 4 // adds 4 to ‘num’, which is now 5
num "\r"
set num2 6 // ‘num2’ has the value 6
num2 "\r"
set num + num2 // adds 6 to num, yielding 11
num "\r"
}
// Outputs 1, 5, 6, and 11. Your character will say each result aloud
// (i.e. in a plain text bubble).
set @env.echo true
f7
{
set @env.echo false
"/action spins around until he falls down.\r"
}
// During this macro, text will not be echoed
// -- despite the global variable.
help
{
if @env.debug == true
setglobal @env.debug false
else
setglobal @env.debug true
end if
}
// toggle debugging on and off with the ‘help’ key
option-return
{
set whichword @text.num_words
set whichword - 1
label mark
@text.word[whichword]
if whichword > 0
" "
set whichword - 1
goto mark
end if
"\r"
}
// talk backwards
// (by looping in reverse order through each word of @text)
call <function> function must be a valid declared function-macro
Executes the given macro function at this point in the macro,
and, when it’s finished, resume the current one where we left off.
Local variables in the calling function(s) are available to the called one.
Examples
subroutine
{
who " is a " prof ".\r"
}
f6
{
set who "Zephyr"
set prof "Healer"
call subroutine
set who "Aki"
set prof "Mystic"
call subroutine
}
// pressing the 'F6' key will produce:
// "Zephyr is a Healer." (return)
// "Aki is a Mystic." (return)
random <option>
<commands>
or
<commands>
or
<commands>
...
end random
option can be no-repeat, or you can omit it entirely.
Randomly chooses one of the choices to execute from the list.
If option is no-repeat, then it will never choose the same one
twice in a row, unless there’s only one choice total
(in which case no-repeat is impossible).
If you don’t specify no-repeat, then each alternative is equally likely.
Examples
"greet"
{
random
"Greetings "
or
"H'loi "
or
"Good day "
end random
@selplayer.name "\r"
}
// If Gaia is selected, then typing "greet" will emit one of:
// Greetings Gaia (return)
// H'loi Gaia (return)
// Good day Gaia (return)
f10
{
"/action "
random no-repeat
"smiles."
or
"grins."
or
"chuckles."
end random
"\r"
}
// The same expression will never result twice in a row
// so you will get any of:
// /action smiles. (return)
// /action grins. (return)
// /action chuckles. (return)
if <expression> <comparison> <expression>
<commands>
else if <expression> <comparison> <expression>
<commands>
else
<commands>
...
end if
expression may be a variable, test, or a number comparison must be one of: >, <, <=, >=, ==, != == means “equal to” != means “NOT equal to”
This statement executes the commands after an “if”
if the comparison is satisfied.
If it isn’t, execution skips to the next “else” statement.
The expressions may be numerical or strings (in which case
< and > are interpreted as “is a substring of”).
Examples
f11
{
if @text <= "kill"
"/action screams in rage!\r"
else if @text <= "peace"
"/action smiles and offers a bouquet of flowers.\r"
else
"/action sits there doing nothing.\r"
end if
}
// Looks for the substrings in @text
"/give"
{
"/give " @selplayer.name " " @text "\r"
set num @text
if num <= 10
"/action tosses " @selplayer.name " a few coins.\r"
else if num <= 100
"/action hands " @selplayer.name " a pouch of coins.\r"
else if num <= 1000
"/action lugs a brimming bag of coins over to " @selplayer.name ".\r"
else
"/action tells " @selplayer.name " where he keeps his secret treasure hoard.\r"
end if
}
// For some facetious coin-giving
Goes to the specified label and continues execution from there.
With goto and label commands, you can make loops.
(If you ever get stuck in an infinite loop,
remember that holding down control-escape stops all macros.)
Use “if” statements within your macros to forestall such loops.
Examples
f12
{
set num 0
label mark
set num + 1
if num < 10
pause 5
"Counting: " num "\r"
goto mark
end if
}
// counts from 1 to 9, slowly
Works like the text command, except that the output is shown in the sidebar only.
It isn’t necessary to end the output with a “\r” character.
(Naturally the message is only shown in YOUR sidebar, not anyone else’s;
also such messages won’t show up in movies, since they did not come from the server.)
