I've been asked by several people to write a document about script writing. I'm not sure how they decided I was some sort of authority on it, but I do know that there really isn't much of an extensive documentation that comes with it, so, this is more or less a supplement to what is available, and might explain it a little better. This guide will be for the basics, and I may be inclined to write more advanced guides in the future. You can download all the scripts on this page {Script Tutorial Scripts}. :) ~Rumor Airinette

The Absolute Basics

This script, obviously performs a single function, then ends. This is the most basic script. It will attempt to cast Guard I on yourself. It takes no arguments. The put command tells the script to issue the command following to Gemstone. If you neglect to use the put command, the script will fail to function.

Arguments in Scripts.

Now, quite honestly, most scripts are useless unless they take an argument. This script takes a single argument. Many scripts will normally take an argument or multiple arguments. That's supposed to be the entire point of a script.. otherwise, you could accomplish the same thing with a macro. A script allows you to specify an argument, so you don't have to type the same commands over and over again. With that in mind, lets try a script that takes an argument.

The %1 in this script indicates a variable argument. A variable argument is something that you can change each time you use the script. The %1 in this script denotes the FIRST argument you used on the command line (such as: .silveries joe) when issuing this script. Simutronics claims you can use 9 arguments in scripts (%1-%9).

Using an argument other than %1.

Generally, you won't be doing this, but, you can have your script address a second or third argument. Lets say for the sake of posterity you want to cast silveries on the first and second argument of your script (.silveries joe bob). You -could- do it like this:

Now, I will be the first to tell you this isn't really the best way to accomplish this, but it does, in-fact, work. Using shift is a much better way to do this.

The Shift Command in Plain English.

Okay, lets say you wanted to cast one shot of Silveries on three different people. But, you really didn't want to have to start one the above scripts multiple times. How would you do that?

All right, let me explain the above. main: is a define for a section of the script, the Main Loop, if you will, the part that is going to get repeated.

Whenever you issue a command to the game in a script, the line MUST start with put. so, That is the prep and cast lines.

waitfor You gesture is an output that you are going to wait from the game. If this line is not outputted, the script will not continue. This is good to do if you need to wait for a specific thing to happen (and also can help with issuing commands too quickly).

pause 3 tells the script to wait for the specified amount of time to pass (approximately 3 seconds in this case).

Now, to explain shift may get confusing, but it really isn't. You see, scripts allow you to have multiple targets. Say you named this script silvermulti To start the script in motion on three people, you would type: .silvermulti joe tom bob So, how does it know when to go to the next person? That's what shift is for. It tells the script to delete the first target from memory and move all the arguments following it up one level. So, the first time it hits shift, it will delete joe from the list and move tom and bob up one level.

if_1 goto main means that if there is an argument left, then the script should go to section main:.

This tells the script to jump back to the main: section if there is still an argument remaining. After shift removes each variable from memory, it will eventually come to no argument, and will continue with the commands following if_1 goto main line when all the variables have been exhausted.

exit tells the script to stop running.

What Is the Deal With the SAVE Command?

Next, I will discuss the basics of the SAVE command. The SAVE command will take the first argument you supply to a script and save it as the variable %s. This allows for some flexibility in designing some scripts. For instance, lets use the idea with the last script and expound on it. Say you wanted to cast three different spells on someone, but didn't want to have to type it all out. Say those spells could vary, and may not always be the same. (In other words, you might want to use this spell when you play your bard as well as your cleric.) How would we accomplish this?

Now, what is happening here? The command save %1 tells the script to save the first argument into the %s variable. It will continue into Main : the section, and hits the shift command, which then removes the first argument from the %number variables, but leaves it in the %s variable. If you were to issue another save %1, it would replace that variable with the new %1 value (which you don't really want to do for this script). As I stated in the last script, if_1 goto Casting will continue the script by sending it to the Casting: section only if there is still an argument left to be processed. When all the arguments have been exhausted, the script will process the exit command and stop.

The Casting: section has the commands to prep, a waitfor command to pick up the output from the game, and the casting command: put cast at %s. The %s target is the first argument that you sent when you started the script because the save %1 command stored that argument as variable %s. The script pauses, and then loops back to Main : the section.

If you started the script by typing: (.cast jim 406 401 103) then the first argument would be saved into %s. The script would then prep 406, 401, and 103 in succession and cast them at Jim. Obviously, if you don't know the spell, the script could hang. But, there is a way to fix that. It's called MATCHWAIT.

And Just What is a MATCHWAIT?

MATCHWAIT is basically a glorified waitfor. It allows different actions to occur when there is a chance for multiple responses to a command issued. MATCHWAITs actually allow you to make the meatiest scripts devisable. So, lets see what the CAST script would look like "fixed" so it wouldn't hang.

The only thing added to this script is basically the MATCHWAIT. Also, two new sections were added to accomodate the MATCHWAITs possible. To use a match wait, you start the line with match and the first word following it is the section that it will go to if the appropriate match is found. The match it looks for is any string or letters or words following the FIRST word after the word match. In our example, the line: match Known Your spell means that if the phrase Your spell is found after prepping the spell, continue the script by going to the Known section. And, the second line offers the other alternative to prepping the spell: match Unknown You don't know which means if the phrase You don't know is found after prepping the spell, continue the script by going to the Unknown section. Now, I put the echo command in the Unknown: section. Since I haven't used it yet in this document, I'll explain what it does. All the echo command does is show YOU and only YOU the text following the command. It doesn't issue any commands to the game, itself. It's only real purpose is to provide you information about how the script is behaving.

One-Touch Scripts? What's that?

A one-touch script is a script that is assigned as a macro key. Of course, it's just a glorified macro unless you use variables. So, we can take advantage of the variables available in the Configuration Section of the Wizard!

Here is a simple One-Touch Script.

Now, to explain this short script. (First off, it's obviously for a mage, since warding spells don't require you to stance. You could easily remove these two lines for other spells.) I'm sure if you are new to scripting, the %user0 and %user1 are absolutely greek to you. You need to specify these two variables under your Configuration -> Options -> Variables section. The first, %user0 is the spell you're planning to use (This is actually a script for hunting zombies I used with my mage.). So, you would define %user0 as 906. The second, %user1 is for the target, which, in this case is zombie. So, you would fill in the two variable fields in your configuration for this script, and it could change whenever you change the critters you are hunting. Now, you would define this under a macro. If this script was called "casthunt", for your macro assignment, you would put the following in: {=casthunt.cmd}. This will call the script for you when you hit that macro key.

In Closing

The above techniques can be used to write just about any script you can think of hunting scripts to cast the specific spells you use, healing scripts, spell-up scripts, guild and artisan scripts, and the like. Scripts are great for repetitive things in the game. I do not, and will state so loudly that I DO NOT approve of unattended scripting! In Platinum, if you script unattended, you likely WILL get caught, so don't do it! :)

--------------------

Rumor Airinette
Baker Mage Extraordinaire

www.arkati.org/library/scripttutorial.zip

Posted: Aug 21 2003 , 07:49 PM

Retrieved: May 01, 2004