Scripting tutorial for AutoIT

[TinyTerror]

I wrote up a scripting tutorial for the rpgexpert forum before it went to hell. Here is the latest version of the tutorial. If you have any questions or comments, please post them in a different thread.

[TinyTerror]

In order to start scripting, there are a few basic things that you really need to know. The first concept that I will cover is the use of variables if an AutoIT script.

VARIABLES

In just about any programming language, there is a need to store data within a program. AutoIT is no different. Variables in AutoIT are used to store anything from numbers to strings (Strings are like lines of text). Fortunately for the beginner, AutoIT is really forgiving with variable usage. This is what your basic variable looks like in a script:

$MyVariable

You can call your variables whatever you like. All variables have a $ in front of them to tell AutoIT that you are reffering to a variable. So what can you do with variables? The most common use of variables is to hold some data given to them by the script. Here is an example of how to make a variable hold a number:

$MyVariable = 5

The variable $MyVariable now holds the value 5. You can also make a variable hold a piece of text like this:

$MyVariable = "Variables are fun"

Now $MyVariable holds the text "Variables are fun". You can also do math opperations on variables that hold numbers. This is really simple and works like so:

$MyVariable = 5
$MyVariable=$MyVariable + 10

Now $MyVariable is equal to 15. As you can see, the variable is initially assigned the value of 5. In order to add 10 to it, we tell $MyVariable that it is equal to itself + 10. The same thing can be done for +,-,* and /.

Now that the basics of assigning and manipulating variables have been covered, we can move onto a very important use for variables: passing arguments to functions. I will cover functions in the next post. One of the most popular and simple functions in FFXI scripting is the Sleep command. This command makes the script pause for the specified number of milliseconds. This is how to use a variable to control the Sleep command:

$MyVariable=1000
Sleep($MyVariable)

This has the same effect as saying:

Sleep(1000)

As we can see here, the Sleep command uses the value stored in $MyVariable as its argument. Some functions also return a value. One common function that does this is the PixelGetColor function. This function returns a number representing the color of the pixel at the specified x and y coordinates. Here is an example of how to use a variable to get a value returned from a function:

$x=100
$y=350
$MyVariable=PixelGetColor($x,$y)

Here the variables $x and $y are set with the coordinates of the pixel you want to check. $MyVariable is set equal to the return value of PixelGetColor. After this code runs, $MyVariable will be equal to the color number of the pixel at (100,350). Thats about all there is to variables. The best way to learn about them is to mess around with simple variable code. Here is some useful code to print out the value of a variable in a pop up box:

MsgBox(0,"Test",$MyVariable)

Just replace $MyVariable with one of your variables to use this command. You can put it in your code whenever you want to see the value of a variable.

[TinyTerror]

Now that variables have been covered, I will explain how functions work, and how to make your own.

FUNCTIONS

Functions are quite possibly the most important construct in any programming language. They allow the coder to take a section of code, give it a name, and use it repeatedly in other code simply by refering to it by name. Some of the most popular functions used by AutoIT FFXI scripts are Sleep, PixelGetColor, and Send. Before I get into making your own functions, I will explain how they work.

As I said before functions are essentially named sections of code that can be called elsewhere in your script simply by refering to them by name. Take fo example the Send command:

Send("/echo this is a simple echo command")

Here we see the send funtion taking the string "/echo this is a simple echo command" as an argument. Functions can take any number of arguments in the form of variables, but can only return a single value. Some functions don't take any arguments, and others dont have any return values. To use a function, all you need to do is this:

$MyReturnValue=MyFunction(argument1,argument2,argument3)

A full list of AutoIT functions can be found here.

This is easy enough and allows you to start doing things with your script besides adding numbers and playing with variables. Now comes the fun part, making your own functions. I can't stress how important this is. Say for example there are a bunch of places in your script where you need to pause for 5 seconds, bow, then say hello. Without using a function, you would have to put this code into your script whenever you want to perform these actions. This might not seem like a problem for a small script performing simple actions, but it is a huge problem for larger more complex scripts. Here is an example of how to make your own function:

Func MyFunction()
;Add your code here
EndFunc

Now that we have a function, it can be called like so:

MyFunction()

All that is needed to make a function are the Func and EndFunc keywords. These basically tell AutoIT where the function starts and ends. Now say we want a function that returns a value. This is quite simple to do, and looks like this:

Func MyFunction()
Return 10
EndFunc

It is used like this:

$MyVariable=MyFunction()

Now $MyVariable is equal to 10. It is important to note that the return command will exit the function that it is used in. Any code following a Return call will not be executed. For example:

Func MyFunction()
Return 10
$MyOtherVariable=19
Return $MyOtherVariable
EndFunc

This function still returns 10. The assignment $MyOtherVariable=19 never happens, and niehter does the second return. It is important to keep this in mind when returning values from your functions. You can have more than one Return statement in a function, but you have to keep in mind how the function will behave, and which Return will be used.

Now what if your function needs data from the code that is calling it? This is done with arguments. A function that takes two arguments, adds them together, then returns the result would looks something like this:

Func Adder($Argument1,$Argument2)
$MyReturnValue = $Argument1 + $Argument2
Return $MyReturnValue
EndFunc

Arguments are variable names seperated by commas. To call a function that takes arguments and returns values, you would have something like this:

$MyFirstNumber = 10
$MySecondNumber = 45
$MyResult=Adder($MyFirstNumber,$MySecondNumber)

Func Adder($Argument1,$Argument2)
$MyReturnValue = $Argument1 + $Argument2
Return $MyReturnValue
EndFunc

This code segment declares two variables, then gives them to the function Adder to work on. One sticky point about functions is how variables are refered to inside the function. If I pass in the variable $MyFirstNumber to Adder, why dont I see it inside of Adder? When you call adder, it expects two arguments. When you give it arguments during the function call, it sets $Argument1 equal to $MyFirstNumber, and $Argument2 equal to $MySecondNumber. This is done so that you can give the function variables named whatever you want. The function gets coppies of those variables named in a way that it understands. This allows you to use the same function over and over again in your code, even if the variables you pass it as arguments arent named the same thing. Very usefull. Here is a simple bot that demonstrates how not to act as a tarutaru in-game:


AutoItSetOption("SendKeyDelay", 30)
AutoItSetOption("SendKeyDownDelay", 30)

Func GetDrunk()
Send("/em drinks from his taru hipflask.")
Send("{ENTER}")
Send("/em stumbles and leers at the ladies.")
Send("{ENTER}")
EndFunc

Func HeyBaby()
Send("/em Slaps the closest mithra on the ass!")
Send("{ENTER}")
Send("/slap motion")
Send("{ENTER}")
Sleep(2000)
Send("/welcome motion")
Send("{ENTER}")
Send("/em Falls into the gutter and passes out.")
Send("{ENTER}")
EndFunc

GetDrunk()
HeyBaby()


This script is sure to be a hit with all the ladies.

[TinyTerror]

Now you should have a good idea of how simple variables and functions work. If all you want to do is write a simple script that runs once and quits, this is all you need. For most tasks we need something a little more. This is where loops and if statements come in. These allow parts of your script to repeat, and to check to see if a condition has been met. A proper understanding of loops and if statements is essential for writing more than just simple scripts.

IF STATEMENTS

If statements in AutoIT alot like if sentences in english. If some condition is true, then do this, this, and this. In our scripts, an if statement looks like this:

$MyVariable = 10

If $MyVariable == 10 Then
Your code here
EndIf

This code uses the if statement to check to see if $MyVariable is equal to 10. The double equals == is used to test for equality between two things in an if statement. To test if one thing is greater than or less than another, you can use > or <. >= and <= are used for testing greater than or equal to and less than or equal to. If you want to test to see if something does not equal another thing, use <>. There are other tests that can be used, but these are the most common. The full list of operators can be found here.

The basic structure of the if statement can be seen above. It starts with the If command followed by the condition to test, and finally by the Then command. Once you are done with the commands to be executed by the if statement, use the EndIf command to tell AutoIT that you are done with the if statement.

Another very useful feature of if statements is the ability to
test for more than one thing or combinations of things in a
single statement. Here is an example of how to do this:

If $MyVar1>$MyVar2 AND $MyVar3<=$MyVar4 Then
Your code here
EndIf

This code checks to see if $MyVar1 is greater than $MyVar2,
and if $MyVar3<=$MyVar4. If BOTH of these conditions are
true, then the Your code here section will be executed. A
common use of AND in an if statement is to check a bunch
of pixels. If all of the pixels match, then perform an action.

A less used but no less useful if statement tool is OR. OR is similar to AND, but will execute the body of the if statement if one or more of its conditions are true. Here is an example:

If $MyVar1<>$MyVar2 OR $MyVar3<$MyVar4 Then
Your code here
EndIf

The Your code here section will be executed if either $MyVar1 does not equal $MyVar2 or if $MyVar3 is less than $MyVar4. You can use any number of condition tests chained together by AND's and OR's to make your if statement as complex as you like.

Yet another useful feature of if statements is the Else command. The Else command goes in the body of your if statement and executes commands when the condition of your if statement is false. Here is an example:

$MyVariable = 10
If $MyVariable = 5 Then
I run when $MyVariable equals 5
Else
I run when $MyVariable doesnt equal 5
EndIf

The Else command essentially breaks the if statement body into a chunk to run if the condition is true, and a chunk to run if the condition is false. This is a powerful and simple way to handle basic logic within your script.

One last thing that needs to be mentioned is that it is possible and quite common to nest if statements within each other to perform complex tasks that might not be practical with a single if statement. Here is an example:

If Condition1 Then
If Condition2 Then
Here are some commands to run
EndIf
Else
More commands
EndIf

You can nest as many layers of if statements as you like in your scripts, but try to keep it simple so that others reading your code (and yourself) wont get too confused. Again the easiest way to learn about if statements is to play with them in your code. Give it a try.

Loops will be covered in my next post.

[TinyTerror]

The next topic I will cover is loops. Loops allow your script to run chunks of code more than once. This is really useful if you have a script that needs to do something over and over like casting your fishing line in final fantasy.

LOOPS

There are three types of loops in AutoIT. The first loop, the For loop, executes it's body a set number of times. The next type of loop, the While loop, executes its body while a condition is true. The while loop checks this condition before executing its body. Finally we have the Do loop. The do loop is just like the while loop, but it checks the condition after it executes it's body. All of these loops have thier uses, but the most common are the While and For loops.

For loops are pretty easy to set up. A For loop consists of a start condition, a stop condition, and a stap action. The start condition usually consists of a variable being set to 0 or 1, but can be just about any numerical assignment. The end condition is the state of the starting condition after a set number of loops. The step action is performed on the start condition every time the loop loops. After the body of your For loop, use the Next command to tell AutoIT that you are done with the loop. This all sounds pretty complicated, but its really not. Here is an example:

For $MyVariable=0 to 5 Step 1
Your commands here
Next

Thats all there is to it. As you can see, the starting condition sets $MyVariable equal to 0. The ending condition says that the loop should stop looping when $MyVariable is equal to 5. The Step action here is to add one to $MyVariable every time the loop loops. This is an optional parameter. If you leave out the Step command, $MyVariable would be increased by 1 each loop by default. The result of this loop is that the Your commands here section would be executed 5 times. A really useful feature of For loops is that the condition variable ($MyVariable in the example above) can be refrenced within the body of the loop. This is how its done:

For $MyVariable=0 to 5 Step 1
MsgBox(0,"For loop",$MyVariable)
Next

This example uses Msg boxes to display $MyVariable each time the loop loops. Because $MyVariable is just a normal variable, it can be used and changed within the loop just like a normal variable. I recomend that until you know what you are doing, you dont change the contents of $MyVariable from within the loop body. Doing so can lead to unpredictable results.

Now that I have explained for loops, its time to move on to Do and While loops. These two loops are really similar and are quite easy to use. Here is an example of both of these loop types:

$MyVar=0

Do
$MyVar=$MyVar + 1
Until $MyVar = 10

While $MyVar>0
$MyVar=$MyVar - 1
WEnd

The first loop is a Do loop. This loop starts with $MyVar equal to 0. The loop cycles until it sees that $MyVar is equal to 10. This check is done after the body of the loop has executed once, so keep this in mind.

The second loop is a While loop. Its just like a Do loop except that it tests its condition before the body of the loop is executed. This one loops while $MyVar is greater than 0.

Just like if statements and for loops, Do and While loops have the Until and WEnd commands to tell AutoIT that the loop is finished.

If for some reason you need to break out of a loop, you can use the ExitLoop() function. I recomend that you avoid this if you can, insted using the loop's condition to escape the loop gracefully.

There are a few tricks that you can do with loops. One of the most popular loop tricks is the infinite loop. This is a loop that will run forever. These are useful if you want your script to do something over and over until it is shutdown manually by the user. An infinite loop might look something like this:

While 1==1
Your commands here
WEnd

Obviously 1 will always equal 1, so the script will keep going forever. One thing to watch out for if you don't want your loop to run forever is to make sure you are doing something to the condition variable inside the loop. Here is an example of a loop that will run forever even though we most likely didnt want it to:

$MyVariable=1
While $MyVariable < 10
Your commands here
WEnd

This is going to run forever because the programmer forgot to put a command that adds something to $MyVariable. If you are using loops and find that part of your code gets cought in an infinite loop, check for this problem. Here is how this loop should look:

$MyVariable=1
While $MyVariable < 10
Your commands here
$MyVariable=$MyVariable + 1
WEnd

This will loop 9 times then quit. As I mentioned before, While and For loops are alot more common that Do loops, because these loops check thier condition BEFORE executing the body. They are easier to use because of this in my opinion.

[weeman]

hey awsome im kinda geting it now but still dont no where im puting all this stuff




(if you have aim and wana teach me ;D mines brittoman)

[TinyTerror]

I dont generally talk to people on this forum on aim. Its not because I dont want to talk to you guys, Im just a little concerned about getting 100 million IM's looking for scripting help 24/7. I check this forum often enough, so post your questions here

[monklikeban]

AWESOME TUT, nicely done Terror, I learned a TON. Now time to go browse some examples and secure the knowledge /em slowly grows a sly smile. ^.~

[TinyTerror]

If you have any questions, please post them here. Someone will answer them pretty quickly.

[Jubei]

How about an add on to the tutorial about simple array techniques in AT? If you don't fancy writing it i'll mabye have a stab at it

[TinyTerror]

Sounds good. Go ahead and write one up. When you finish, I will clean out the tutorial thread and post it as a sticky.

[Jubei]

i'll get onto it as soon as i've got this 1-10 bot finished and have a bit of spare time. Maybe sooner if my current state of lethargy goes into remission