Macro Manual Table of Contents General Information Types of Macros Attributes Variables Commands General Information How Clan Lord Loads Macro Files 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. If no such file exists then it creates a new one. It also creates the macro folder and a file named "Default" if they do not exist. You can tell Clan Lord to load other files located in the Macro folder by having a line like: include "Default" include "Item Macros" This statement loads 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 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 variable 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. // This is 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. */ Types of Macros Expression Macros "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 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: Keys: f1 - f15, escape, minus, delete, tab, return, space, help, home, undo, del, end, pageup, pagedown, up, down, left, right, clear, enter, click Modifiers: command, control, numpad, option, shift Option Key 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!). OS X Only: 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) command-control-numpad-option-shift-minus "BEER!\r" control-option-click {   if @click.name != ""     "Get out of my way " @click.name "!\r"   end if } The "Wheel" Keys OS X Only: 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're using OS X 10.2 or later, and 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 command 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. Examples @login {   "/action yawns and stretches\r"   pause 4   "/pose sit\r" } Attributes 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. A click macro using 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" } Variables 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, "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. "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! 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 besides the one in which there's now a local variable with the same name. set who "Kerial" "set1" {   set who "Ternia"   "Hello " who "\r" } "vartest1" {   "Hello " who "\r" } Now if you use set1 you get: Hello Ternia (return) But now if you use vartest1 you still get: Hello Kerial (return) CL-Defined Variables 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 @. The following 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 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 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 refer to the character clicked on to begin a click macro. @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. .num_letters The number of letters in a variable. Commands 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. You can only have one command per line. You can use variables for any of the parameters of the various commands. Text "<text>" <variable> If the first word of a line is not another command, then Clan Lord assumes this line is text. Any text in quotes is just inserted. Each item which is not in quotes is assumed to be a variable, and the value of the variable is inserted. As a macro executes, it concatenates text until it reaches an end-line character "\r", at which point it sends the text it has saved 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) // If 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) // If tou have typed "Where are you hunting?" and have Thyin selected. f13 "Tergon d\'Aleria mon\'Savreyte von Wendia" // Inserts your very complicated name as if you had typed it. Pause pause <number> Pauses the macro for <number> frames. 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 set <variable name> <value> OR set <variable name> <operation> <value> <operation> must be + - * / % Sets the local variable or does an operation on its current value (see the variable 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 setglobal <variable name> <value> OR setglobal <variable name> <operation> <value> <operation> must be + - * / % Sets a global variable or does an operation on its current value. Examples 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. f8 {   set num 1   num "\r"   set num + 4   num "\r"   set num2 6   num2 "\r"   set num + num2   num "\r" } help {   if @env.debug == true     setglobal @env.debug false   else     setglobal @env.debug true   end if } // toggle debugging on and off with this key option-return {   set on @text.num_words   set on - 1   label mark   @text.word[on]   if on > 0     " "     set on - 1     goto mark   end if   "\r" } // talk backwards Call call <function> <function> must be a valid declared function Executes the given macro function at this point in the macro. This function and the calling function share local variables. Examples subroutine {   who " is a " prof ".\r" } f6 {   set who "Zephyr"   set prof "Healer"   call subroutine   set who "Aki"   set prof "Mystic"   call subroutine } Random random <option>   <commands> or   <commands> or   <commands> ... end random <option> can be "no-repeat" 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" } f10 {   "/action "   random no-repeat     "smiles."   or     "grins."   or     "chuckles."   end random   "\r" } // The same expression will never result twice in a row If 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 from >,<,<=,>=,==,!= == means equal to != means NOT equal to This statement executes the commands after an "if" if the comparison is satisfied. If it isn't it goes to the next else statement. The expressions may be numerical or strings (in which case < and > are interpreted as "is a substing 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 @text <= 10     "/action tosses " @selplayer.name " a few coins.\r"   else if @text <= 100     "/action hands " @selplayer.name " a pouch of coins.\r"   else if @text <= 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 Label label <label name> Sets a place in a macro as a possible target for a goto command. Goto goto <label name> Goes to the specified label and continues execution from there. With goto and label commands you can make loops (If you ever get in an infinite loop, remember holding down control-escape stops all macros) Examples f12 {   set num 0   label mark   set num + 1   if num < 10     pause 5     "Counting: " num "\r"     goto mark   end if } Message message "<text>" message <variable> Works just like the text command, but the output is shown in the sidebar. It isn't necessary to end the output with a "\r" character though. (Naturally it is only shown in YOUR sidebar, and this won't show up in movies.) Examples "msg" {   message @text }