Writing macros, a series of lessons (8 of…)

At long last, we’re going to dip our toes into scripting. First, a few resources and terms.

Resources… I know in an earlier lesson I was lamenting not having all of Iriel’s concise lists of changes to hand. I was being an idiot – I did have it, but had forgotten. It’s part of a set of resources – well, one resource with a lot of branches – that as a beginner you’re going to find almost mandatory. That’s the API resources at WoWWiki.com. (Note this is a category listing. You’re going to want the subcategory and the first six articles. The rest of the 199 PAGES of stuff is, at this time anyway, unnecessary.)

API is an abbreviation for Application Programming Interface. And that is… Remember I said the underlying script language was Lua. Well, if you’re programming in Lua you’re free to make up your own function and variable and so forth names. (Yes, we’ll get to those terms too if you don’t get them. Bear with me.) The thing is, since Blizzard wrote so much of WoW in Lua, they’ve already NAMED a bunch of these things. So you don’t have to make up your own command to play a soundfile from the game (PlaySoundFile). Or to run a macro (DoMacro). Or, well, you get the idea.

OK, let’s start our syntax learning. Actually, let’s digress for a public service announcement – if this makes no sense to you then you need not worry about it.

If you are an experienced programmer, please recognize I’m trying to introduce this to non-programmers, and be gentle with the corrections. Yes, I know functions and numbers and strings are types in Lua – but the nature of a dynamically typed OO language extension language is such that a lot of terminology can easily appear confusing – and recursive – with no relief in sight. If I make a GLARING error, please correct. If it’s a ‘well, sorta kinda’… use some judgment, ok? My skin is tough, but I don’t want to be the one cleaning all those exploded skulls off the walls. Anyway…

At the very core of our scripting system is this sytax:

function(arguments)

Function is “Do something” – what in macros we called a command.

Arguments are, well, paralleling our macro syntax, arguments are the parameters and conditionals (and more) for the function. They tell the function what to do something TO, and what type of something to do to that what.

Notice the parenthesis. The arguments for a function are ALWAYS in parenthesis, and there’s never a space. It’s worth adding here that if you see what appear to be two words with no space, the computer considers that one word. (Remember what I said about German language for ‘target’ and ‘focus’? It’s about to get moreso.) There CAN be spaces within the argument, however, in certain cases. Just none between the apparent words of the function, and none between function and opening parenthesis.

Now, there are a lot of things that can be arguments. And there are things that can go OUTSIDE the function that further control it. And we’re going to get to those – but slowly. And to that end…

I’ll be using some terms frequently, so let’s get them out of the way here. The first is “string”. A string is a series of characters – usually considered a word, but it can include numbers and (with caveats) symbols. The really important thing about a string I want you to keep in mind is that for now it’s immutable. It doesn’t change. If I tell the script to say “player” in chat, it puts in “player”, not “my character’s name”. Now when we write a script, a string is always in quotation marks.

The second term you’ll see a LOT is variable. A variable is a placeholder. We’ve used them before – target and player in macros are examples. During the script – at the time the script runs – we’ll either tell the script what the variable means at that instant, or it’ll pull it from the situation. (Am I targeting myself, my tank, that mob over there…?) Now, a variable can be a lot of things — types, in Lua speak — so it can get confusing. Just remember – it’s a placeholder. Oh, and generally we tell the variable what type it’s expecting and it will never be anything else (in that script). In other words, if we tell it the variable is a number, it’ll never accept or see a string.

There are also some reserved words. These words CANNOT be used as variables or functions or anything else – they have specific meaning to the computer, and that meaning will override what you wanted it to mean. These words are:

and break do else elseif end false for function if in local nil not or repeat return then true until while

Umm, let me take this opportunity to tell you, again, that case matters. To the computer, ‘and’ is a reserved word, but it doesn’t care at all about And, aNd, ANd, or any other combination of letters that isn’t ‘and’. Oh – it also doesn’t care about the word as a part of a longer string or label. The ‘and’ in ThisandThat (or thisandthat, or whatever) is not going to trigger the reserved behavior.

By the same token, some symbols are reserved. Now unlike the words above, if THESE show up in the middle of a label (function, variable, etc) they will have their effect. We can OVERRIDE this behavior (if, for example, we want to say it as part of a text string being sent to chat), but we have to make a specific effort. The list of these symbols is:

+ – * / % ^ # == ~= <= >= < > = ( ) { } [ ] ; : , . .. …

Ummm – a space has a reserved function too. It separates terms. (grin) Seriously, if you create a variable called this+that, the computer is going to see two variables that it’s supposed to be adding together.

OK, that’s rather dense, so even though there’s a lot more in the area let’s take a break. Let’s see the basic script structure in progress, and maybe learn something while we’re out it. Here, try this bit of fun:

/run PlaySoundFile(“Sound\\Music\\ZoneMusic\\Karazhan\\KA_OperaHarpsiWalkUni01.mp3”)

and

/run PlaySoundFile(“Sound\\Music\\ZoneMusic\\Karazhan\\KA_OperaOrganWalkUni01.mp3”)

Note that both are on one line.  As with almost every single line macro, you can type that into a chat box and have it run.

Yep, it’s the music from karazhan’s opera – the organ, and the harpsichord.  Thank Rickyk of Draenor-US for assembling the list of these and several hundred other sounds from the game – you can find it on the forums.   Now let’s dissect them to focus our learning.

The command that starts both scripts is \run – something we already knew.

PlaySoundFile is the function.  It tells the computer to find the soundfile and do all the necessary steps to play it over your speakers/headphones.  The argument for which this function is waiting is “what file?”  You will put the file inside the parenthesis.  And  since you’re going to tell it EXACTLY where to go, it’s a string — which means it’s enclosed within quotation marks.  By the way, the double backslashes (\\) are because single backslashes within the computer have a special meaning that is NOT “=>subdirectory”.

Though this has been relatively short (for me), I’m going to stop here.  Take some time to go through those references, though, as we’ll pull from them several times and it’s nice to be comfortable.  But mostly,

go have fun.

~ by Kirk on December 13, 2007.