Welcome Clanners!

Codus: " Welcome @my.name I can teach you to make new macros and fix your old ones. You have much to learn. ZAP!

This started as a way to help Cinnamon, a new clan member, fix his ailing macros. As I mentioned this, several other people chimed in saying they needed help. So, I posted this default file and then relaized I'd only help if you copied them. So, avoiding fish cliches, I decided to annotate this file for more public consumtion. Any errors? Got a better technique?let me know. I hope this helps those that have never taken any programming courses, and those that never wish to.

Okay here's all the basics in the Macro File:
//escape sequences:
What is an Escape sequence? Well, simply it's a command that takes you out of a running process. The process that's running in this case is text insertion of things between the quotes (more accurately the inch marks - but let's keep proper typography out of this) into the text field we all know and love and type into.
When you Escape this mode, you are asking the macro language to go do something else uselful like get the highlighted players name (@selplayer.simple_name) or insert the text in the text field (@text), then come back and do the next thing.

//		\\						backslash
//		\"						double quote
//		\r						return
//		@my.name				your character name
//		@selplayer.name			selected player real name (with spaces)
//		@selplayer.simple_name	selected player simple name (no spaces)
//		@text					the complete text in the panel
//		@textsel				the selected text in the panel
//		@my.right_item			the name of the item in your right hand
//		@my.left_item			the name of the item in your left hand
//
//	special macro keys:
//		f1 - f15, escape, minus, delete, tab, return, space, help,
//		home, undo, del, end, pageup, pagedown, up, down, left, 
//		right, clear, enter

Special Macro keys are keys you hit and automatically act without hitting return. They are most useful for quickly switching weapons, posing, pulling pushing, or doing anything that you need to do quickly and can't take your eyes off the screen too long, nor your fingers off the mouse/trackpad.

//	macro key modifiers:
//		command, control, numpad, option, shift
//
//	using the option modifier with letters is a bit tricky because typing
//	option-letter often changes the letter. for example: option-s changes 
//	to the character §. so to use option-s as a macro you will need to use
//	the option-character in the macro definition.
//	that is, macros defined like this:
//		option-s	"this fails"
//		option-§	"this succeeds"
//	will set the text to "this succeeds" when you hit option-s.

The § above is one of those lovely upper ASCII characters.
What they don't tell you is that standard commands, such as "/action" or "/ponder", that have upper ASCII characters after a space will commonly case an error, and that if you use upper ASCII characters as the macro trigger, it will often ignore them as well.

//
//	examples:
//		shift-enter
//		command-option-p
//		command-control-numpad-option-shift-minus


These are my settings for the first bank of F-keys. You'll notice a few things which are the basics of this new macro language which has many a 0 mentus exile baffled.

f1			"/pull " @selplayer.simple_name "\r"
f2			"/push " @selplayer.simple_name "\r"

First you'll note the addition of a few quotes (inch marks). Next, if you aren't paying attention you might miss the space after the command ("/pull "). The space is there because unlike the previous macro language, this one does not put in a space between the text it is outputting to the text area and the command you are calling.
Here's a quick (okay, not so quick) example of the wrong way (without the space):
You're in noids fighting a Greenie when a clumsy exile decides it's a good time to stand behind you after you've swung out, thus blocking any chance you'll be able to avoid the, now angry, Green Noid's pinchers. We'll call this clumsy person "Clum". So you highlight Clum with a quick cmd-click and hit F1.
What you get without the space is "/pullclum", to which the text message area returns "/pullclum is not a command." And now you're taking hits, and Clum -- now just realizing he's trapped you in -- executes a pull by typing it out longhand! The common outcome to this is often you lying dead cursing the new macros and Clum.

The next fundamental thing to note is the quote marks come in sets:

the first encompasses the command with the space, the last set encompasses the escape sequence command "return". Without the "/r" the previous scenario would have played out the same except that you'd see "/pull clum" in the text window, but it wouldn't have been sent. It's just sitting there waiting for you to hit the return. And in that brief millisecond it takes you to realize it, Greenie has tried his Cuisinart setting on you. So as a rule you should always include "/r" in your marcos that return text.

//Swap Weapon Macro (explanation in code)
f3
{
	pause 1
	if @my.right_item == "Axe"
// comparing values isn't limited to numbers, you can also compare text strings
		equip "Short Sword"
	else if @my.right_item == "Short Sword" 
//"else if" is handy for multiple tests
		equip "Taintless Club"
	else if @my.right_item == "Taintless Club"
		equip "Axe"
	end if
}
//Swap Shield<>Stone 
f4
{
	if @my.left_item == "sunstone"
		equip "Shield"
// Notice the parser doesn't evaluate upper- or lowercase when comparing
	else @my.left_item == "Shield"
		equip "sunstone"
	end if
}

// think shorthand
// this feature was causing some confusion to new players
// it's no longer the default action
// enable it by removing the double slashes from the next two lines
command-enter		"/think " @text "\r"
command-return	"/thinkto " @selplayer.simple_name " " @text "\r"


Now you'll notice the addition of a quote set encompassing a space. This is so that the command won't come out "/thinkto clumget out of my way!" [Text Message: Clumget is not in the lands.]
This is the next lesson, for multiple @commands in a row you must make sure to pad them by placing " "s between each one. Got it? Good. You should be ready to overhaul your marco file.

// macro expansions (shorthand is case sensitive)
// command lines that start with the shorthand are expanded.
"??"		"/help"
"aa"		"/action " 	@text 	"\r"
"g"		"/give " 	@text	"\r"
"ii"		"/info " 	@selplayer.simple_name"\r"
"kk"		"/karma " 	@text	"\r"
"m"		"/money " 	@text	"\r"
"mm"		"/money \r"
"n"		"/news " 	@text	"\r"
"p"		"/ponder " 	@text	"\r"
"pp" 		"/ponder "  	@text	"\r"
"sh"		"/share " 	@text	"\r"

There's nothing revelutionary in the previous block. But you may notice the use of good formatting techniques. It's only important to use good formatting when you or someone else might have to come back to the marcos someday and edit them. So, in my opinion it's always important to use them.

This one I got off the newsgroup and changed it to suit me a bit more. Thanks to whoever it was that wrote it. It's for when you want to leave the Clan Lord unattended for more than the 10 minutes the server is set to disconnect idle people. So, go ahead, make breakfast; go to the store to buy more Coke; maybe even, GASP!, relieve that bladder pressure to!

"sl"
{  
   set @env.key_interrupts "true"
   set @env.click_interrupts "true"
   set count 0
      "/pose lie\r"
      pause 5
      "/action feels sleepy and takes a nap\r"
      pause 5
      "/sleep\r"
      label start
         if count < 15
            set count + 1
            pause 500
               "/ponder "
                  {
                  random
                     "ZZzzzzz.......\r"
                  or
                     "zzzZZZZzzzz...\r"
                  or
                     "...zzzzZZZZzzz\r"
                  or
                     ".z.z.z.Z.Z.z.z\r"
                  end random
                  }
      goto start
         end if
}

Okay, "here's the whole ball of yarn" as a certain one-eared kyttyn might say after playing with her Dead Lucero yarn ball and keychain. Note the proper formatting that matches the levels of commands with an indent for each command that is a subset of another.
1 "sl"
The first line start different, you'll notice that the short hand "sl" is the only thing on that line because...

2 {
When you're setting up complex commands it's often easier to break them up into lines. But in order for the macro language to understand them as a single macro, not a bunch of errorneous macros, you have to enclose them in curly brackets {}. The other one is at line 29.

3 set @env.key_interrupts "true
4 set @env.click_interrupts "true"
Either pressing a key or clicking the mouse button in the game window will halt the macro.
5 set count 0
Here you are initalizing a counter to keep track of how many times you go through a loop. It's important to note that you intialize the count outside the loop. To initialize the loop inside the loop would casue a nasty endless loop since you'll constantly be setting the counter to zero!.

6 "/pose lie\r"
Note the "\r" does not need a space before it because "\" is reserved to tell the complier the following word is a command.

7 pause 5 Pauses are a nice way to separate commands that are chained together so it gives other people time to read multiple dialogs. the number, is (from what I remember) the number of frames to wait before reading the next command. 5 Frames is 1.25 seconds during off-peak, and 1.66 seconds on peak (6-9PM PDT).

8 "/action feels sleepy and takes a nap\r" 9 pause 5 10 "/sleep\r" 11 label start
This mean that you are labeling this function in the macro "start" so you can recall this function in a later command. It's good to label functions when you are building complex stricts so that instead of a shotgun style linear script that has many repeat commands, you can simply call a nice little code nugget and save your wrists (for important things -- like perfecting your running beasts in a circle).

12 if count < 15
The first run through the "start" function the counter is zero, as it was set in Line 3. This line means aslong as the count is less than 15, do the following commands. If the counter is equal to of greater than 15, the macro interpreter will skip to the end if statement in line 28 and continue from there.

13 set count + 1
Now one is added to the counter. Each pass through the counter will add one. Without line 11 to add to ther counter the loop keeps running since it would never hit 15.

14 pause 500
Wait for 125 seconds, then continue.

15 "/ponder "
You aren't forgetting the spaces after commands are you?

16 {
Next after the ponder command there's a complex command within the macro. When you place a command within another command It's called "nesting". Note that all the lines of this nested command are lined up with each other vertically on the lines, so if the programmer wants to change anything he or she can easily isolate separate commands of complex macros.

17 random
"random" with the use of the "or" makes for some very powerful possibilities. If you nested function calls in each statement you could mimic life while you're out getting pizza. Random says to the complier, "pick one or the following statements to do, then continue." Note that when you call on the random command, you must call an end random (in line 25) just like the end if command.

18 "ZZzzzzz.......\r"
19 or
20 "zzzZZZZzzzz...\r"
21 or
22 "...zzzzZZZZzzz\r"
23 or
24 ".z.z.z.Z.Z.z.z\r"
These are the possibilities of random, denoted by or. Important things to note are the inclusion of the "/r" and the fact that the ors are on separate, single lines. This is more for ease of editing than a need to have a line to themselves. Just don't forget the brakets (lines 16 and 26) to allow you to break up commands.

25 end random
26 }
Don't forget to close your function. This bracket matches up with line 16. Now the value of vertically aligning functions should be making itself clear.

27 goto start
Here you are telling the compiler to go back to the start function and begin the loop again.

28 end if
Without an end if statment, the complier would just think everthing following the if statement is part of the loop, and end up erroring out or worse. Don't let functions run away from you, I suggest always following the beginning of a statement with the end, then inserting the commands between. That way you don't forget to close a function when you're done writing the commands. This is a good habit to get into in any scripting evironment, whether it be C, HTML, Java or Clan Lord Marcos.

29}
Yup, a closing bracket to match the one in line 2 of the macro, just as Gaia intended.

Okay, the rest of this should be easier to digest now.
This /think and /thinkto macros that follow are executed two ways, if the item is the same "==" or if it is not the same "!=".

"t"	
{
	if @my.left_item == "sunstone" // If the item in the left is a sunstone...
		"/think " @text "\r"
	else
		set saveItem @my.left_item // save whatever is in the left hand
		equip "Sunstone"
		pause 1
		"/think " @text "\r"
		pause 1
		equip saveItem // equip whatever was saved
	end if
}

Entil'Zha, BU's Earth Draka, wanted a quick macro to check the time and then re-equip whatever she was holding before the swap. I quickly modified the healer's moonstone swap macro in the old "Macro Instructions" file and gave her this "time" macro. Just don't let Algernon catch you doing this, he'd be jealous.

"time"
{
	set saveItem @my.right_item
	equip "Green Token"
	pause 1
	"/use\r"
	pause 1
	equip saveItem
}

Let's quickly break it down. 1"time"
2{
3set saveItem @my.right_item
The set command creates the saveItem variable and copies whatever is in your right hand to it. In pretty much all languages I've seen, when a variable is initialized it's before the value to be set.
4 equip "Green Token"
equip is the magic word to switch to an item. The Item names include "axe", "short sword", "dagger", "moonstone", "sunstone", "shield", etc.
5 pause 1
After you equip or unequip an item, it takes a second for the parser for the relay the command to the server and be free for input again. So, if you chain these commands without placing pauses in, you'll get the ¥ MACRO Execution Error. Busy; add a pause error. At best you don't change the item, at worst you don't change the item and it causes your death.
6 "/use\r"
7 pause 1
8 equip saveItem
Now you tell the parser to equip whatever was in your hand when you started the macro by calling the variable that you set in line 3.
9}

"tt"	
{
	if @my.left_item != "sunstone"
		set saveItem @my.left_item
		equip "Sunstone"
		pause 1
		"/thinkto " @selplayer.simple_name " " @text "\r"
		pause 1
		equip saveItem
	else
		"/thinkto " @selplayer.simple_name " " @text "\r"
	end if
}
"u"		"/use " 	@selplayer.simple_name "\r"
"uu" 		"/use " 	@selplayer.simple_name "\r"
"uuuu" 		"/use " 	@selplayer.simple_name "\r"


How many times have you set up a macro before entering a dangerous area, only to retype it and screw up chaining that exile and almost killing yourself in the process? Well, that's why these are here.

"un"		"/unshare " 	@text "\r"
"w"		"/who " 	@text "\r"
"wh"		"/whisper " 	@text "\r"
"y"		"/yell " 	@text "\r"

One last thing. Notice all my Macros are in alphabetical order so when I want to edit one, I don't have to go looking all over the file for it. A little effort designed into something is worth all the headaches not doing it may cause later. It's one of my rules to live by.

I hope this answers more questions than it creates, and that you feel as comfortable scripting in new macros as I do. I really don't use a lot of them, which you could see if I posted my character's macro file. However, those that I do use, and have taken the time to figure out have saved my bacon a thousand times over. Just ask Clum.

This scroll brought to you by the Black Unicorn.