play.net SIGN UP FOR FREE! | MEMBER LOGIN · LOGIN HELP 
HOME MY ACCOUNT GAMES STORE WIKI HELP

, News
, Forums
, Platinum
, Premium
, Shattered
, Box Office
, Downloads
Policies
Untitled Document

StormFront Scripting Reference

Introduction

StormFront allows you to automate many of your routine game play tasks through a programming language called the Wizard Scripting language. Collectively these routines are called "scripts".

You can create a script by programming directly, or by recording your actions in the game. Scripts can be edited at anytime.

Running a Script

A script can be run from the Scripts dialog box by selecting it and pressing the run button.

The most useful way to run a script, however, is from the command box. By preceding your script name with the prefix character (which defaults to a period '.' character) you can run a script. For example, if you created a script named "killthing" then issuing the command ".killthing" would run the 'killthing' script.

You can also supply arguments to the script in this way, such as:

.killthing orc

This will run the 'killthing' script with the variable %1 set to "orc".

.killthing orc chair

This will run the 'killthing' script with the variable %1 set to 'orc' and %2 set to 'chair'.

Sometimes you want to use spaces in your arguments, so you can do this in several ways:

.killthing "a blue orc" chair

.killthing a_blue_orc chair

Both of these will set %1 to "a blue orc" and %2 to "chair"

You can have up to nine arguments, in this fashion, passed to a script. A script can then act on these arguments or use them to modify how it behaves.

Stopping a Script

A script ends when it reaches the last command.

Press Esc to abort a script. Press Shift-Esc to pause a script (and Esc again to resume).

Rules

A script has one command on a line. The exception is that the IF_# command can prefix any other command.

There may be any number of lines in a script (to some reasonable limit, like 1M of characters).

Blank lines are ignored.

Whitespace before a command is ignored.

All built-in variables are reset when a script runs except for %s.

Commands are case-insensitive, so GOTO is the same as Goto is the same as gOtO.

Scripts will wait automatically whenever there is a roundtime in effect.

Variables

The Wizard scripting language has very limited variable capability. In general, there are two types of variables:

1. User Defined Variables
You can edit variables in the Variables dialog box. To do this, go to the Macros dialog box or the Add Script dialog box and clicks the [Variables...] button.

You can use these in scripts by preceding them with a %. The name is terminated by a space, another % or the end of the line. For example, if you create a variable named "bob" then they can be used in a script as "%bob".

A variable can have a name and a value. These are most useful in macros.

2. Script Defined Variables
Variables can be created, changed and deleted with various script commands.

3. Build In Variables
Several built-in variables are provided for your convenience. All begin with the % character:

%1-9 Argument Variables

These are your nine command line variables. %1 is variable 1, %2 is variable 2 and so on.

When running a script form the command box, you can follow the script name with arguments. These arguments are passed into the script with the %1 through %9 variables.

When running a script from the command box you can preceed the script name with the prefix character (which defaults to a period '.' character) you can run a script. For example, if you created a script named "killthing" then issuing the command ".killthing" would run the 'killthing' script.

You can also supply arguments to the script in this way, such as:

.killthing orc

This will run the 'killthing' script with the variable %1 set to "orc".

.killthing orc chair

This will run the 'killthing' script with the variable %1 set to 'orc' and %2 set to 'chair'.

Sometimes you want to use spaces in your arguments, so you can do this in several ways:

.killthing "a blue orc" chair

.killthing a_blue_orc chair

Both of these will set %1 to "a blue orc" and %2 to "chair"

You can have up to nine arguments, in this fashion, passed to a script. A script can then act on these arguments or use them to modify how it behaves.

%0 contains all of the arguments, such that:

.doit thing stuff more

Then %0 would contain "thing stuff more"

%s SAVE Variable

%s is a special save variable which is set by the SAVE command.

%c Counter Variable

The %c variable is a numeric counter that stores a value rather than a string. There are commands for using this value and performing some calculations with it. This represents the extent of the Wizard Scripting language’s current computational capabilities.

Variables in Commands

You can use variables in arguments to commands. For example:

ECHO The first argument to this script is %1

All translation of variables occurs before the command is processed, so you can actually create some interesting effects, such as:

GOTO jumpLabel%c

If the counter variable had 5 in it, then this would jump to the label "jumpLabel5".

In some cases you may not want a space to appear after an evaluated variable, so you can terminate a variable name with another % in such cases:

ECHO %1 and %2 hyphenated looks like: %1%-%2

Comments

Any line that begins with a # character is a comment and is ignored. For example:

# This script does cool things with my sword.

Labels

A label is a spot in the code where a command can branch to with certain commands. They are given unique names followed by a colon. For example:

loop:
move n
goto loop

This script contains one label named "loop". As written, this script will continually move north until it is stopped by the user (ESC key stops a script). Because of the goto loop, it will never end on its own.

A script label can be any string of characters, so long as it does not have a space. Each label must be unique in a script. You cannot have two labels with the same name. For the purposes of matching labels, case is ignored. Therefore "Bob" is the same as "bob" is the same as "BOB" etc.

There is a special catch-all label:

labelError:

If a script command tries to branch to a label that is not found the script will abort with an error unless there is a "labelError:" label. In that case it will branch this catch-all label.

Label names can be constructed from variables in such commands as GOTO. For example:

COUNTER SET 2
GOTO my%c
my1:
PUT It was 1
exit
my2:
PUT It was 2
exit
my3:
PUT It was 3
exit

This example uses the %c counter variable to branch to one of three labels "my#" where # is substituted with the value in %c.

Commands

ECHO {text}

The ECHO command will display the string {text} in the Game window. This text is not issued as a command. Use this to display information about the script run status.

Example:

ECHO I see dead people!

PUT {text}

The PUT command will send the {text} string to the game as if typed by the user.

Example:

PUT attack orc

This will issue the command "attack orc" to the game.

PUT attack %1

If %1 had "bob" as a value, this would issue the command "attack bob" to the game.

MOVE {text}

The MOVE command works like PUT and sends the {text} argument to the game as a command. However MOVE will then pause until a new room description appears before the script continues. It is, therefore, only useful for issuing commands which cause a new room description to appear, such as movement. This is equivalent to doing a PUT command followed by a NEXTROOM command.

Example:

MOVE N

This command will issue the command "n" and then wait for a room description before proceeding.

WAIT

The WAIT command causes the script to pause until a prompt is received. Note that the appearance of the prompt may be suppressed by the settings for the story window, but this will not affect the command working properly.

Example:

PUT look under couch
WAIT
PUT look behind couch

This script will issue the command "look under couch", then wait for a prompt, and then issue the command "look behind couch".

It is important to wait for prompts in scripts because there is a limit to how many commands you can issue at once (called the "type ahead" limit).

NEXTROOM

The NEXTROOM command pauses the script until a room description is sent. Can be useful for waiting until the user types "look" or "observe".

Example:

PUT pull lever
NEXTROOM
MOVE n

This script issues the command "pull lever" and then waits until a room description appears, after which it issues the movement command "n". This example makes sense in a room where pulling a lever leads to the player being transported to another room.

WAITFOR {text}

The WAITFOR command will pause the script until the text specified by the argument {text} arrives from the game. Only an exact match will cause the script to continue.

Example:

PUT pull lever
WAITFOR the trolly has arrived
PUT go trolly

This script pulls a lever which (presumably) calls for a trolly car. It waits for the tell-tale text "the trolly has arrived" before continuing and issuing the "go trolly" command.

WAITFORRE /{regular expression}/[i]

The WAITFORERE command works like the WAITFOR command but accepts a Regular Expression argument between slash characters. Optionally the Regular Expression can be treated as case-insensitive by following it with an "i" character.

The WAITFORRE command pauses the script until the specified Regular Expression is matched from text coming from the game.

Regular Expressions allow for very sophisticated string matching.

Example:

PUT pull lever
WAITFORRE /(blue|green) ball bounces by/
PUT get ball

This script will pull a lever and then wait for either "blue ball bounces by" or "green ball bounces by" to appear before proceeding and issuing the command "get ball".

Note that the regular expression must appear between / characters. Follow all of this with an "i" character to treat the match as case-insensitive. Thus:

WAITFORRE /(blue|green) light/i

Will match on "BLUE light" or "Green light" or "green light" etc.

This command is not supported by the Wizard but works in eScape and StormFront.

PAUSE [{time}]

The PAUSE command causes the script to pause for a specified number of seconds indicated by the {time} argument. If there is no argument, it pauses for 1 second.

Example:

PUT get sword
PAUSE 2
PUT attack %1

This command will issue the command "get sword", wait 2 seconds then continue on with an attack.

GOTO {label}

The GOTO command will branch immediately to the spot in the code indicated by the {label} argument. If there is no label that matches, it will go to the label named labelError if one exists. If neither of these two conditions are met a script error will result and the script will terminate.

Example:

loop:
move n
goto loop

This script contains one label named "loop". As written, this script will continually move north until it is stopped by the user (ESC key stops a script). Because of the goto loop, it will never end on its own.

EXIT

Will abort the script.

Example:

IF_1 doit
EXIT
doit:
PUT attack %1

This command will issue the attack command followed by the argument passed to the script, assuming there is one.

MATCH {label} {text}

Defines text, specified by {text}, to be watched for by the MATCHWAIT command. You specify any number of MATCH and MATCHRE commands followed by a MATCHWAIT to setup a series of strings to match for. When a match occurs, execution of the script branches to the label specified for that match.

The MATCH and MATCHRE ordering is important. Matches are processed in the order they appear, so if there is any overlap you want to move the priority ones first.

After a MATCHWAIT all MATCH and MATCHREs are cleared.

Example:

MATCH gotTowel a towel
MATCH gotBook a book
PUT inv
MATCHWAIT
gotTowel:
PUT wear towel
EXIT
gotBook:
PUT read book

This script sets up a match for "a towel" and "a book" branching to gotTowel and gotBook labels respectively. Then it issues an inventory command and waits for either of the matches to occur to decide what to do next. If a towel and a book both appear in the output, the first one matching takes precedence.

MATCHRE {label} /{regular expression}/[i]

Defines text, specified by Regular Expression {regular expression}, to be watched for by the MATCHWAIT command. You specify any number of MATCH and MATCHRE commands followed by a MATCHWAIT to setup a series of strings to match for. When a match occurs, execution of the script branches to the label specified for that match.

Note that the Regular Expression must appear between / characters. Follow all of this with an "i" character to treat the match as case-insensitive.

The MATCH and MATCHRE ordering is important. Matches are processed in the order they appear, so if there is any overlap you want to move the priority ones first.

After a MATCHWAIT all MATCH and MATCHREs are cleared.

Example:

MATCHRE gotTowel /a (blue | red) towel/
MATCH gotBook a book
PUT inv
MATCHWAIT
gotTowel:
PUT wear towel
EXIT
gotBook:
PUT read book

This script sets up a match for either "a blue towel" or "a red towel" as well as "a book" branching to gotTowel (for the first two) and gotBook labels respectively. Then it issues an inventory command and waits for either of the matches to occur to decide what to do next. If a towel and a book both appear in the output, the first one matching takes precedence.

This command is not supported by the Wizard but works in eScape and StormFront.

IF_{#} {command}

The IF_ command is used to prefix other commands (usually GOTO). If the built-in argument variable specified by {#} contains anything, then the {command} is executed, otherwise it is not.

For example, if you issue a script command with two arguments then %1 and %2 will have the first and second arguments respectively, but %3 through %9 will not have anything.

In this case, you might do:

IF_1 GOTO myLabel

Which would goto myLabel, but

IF_3 PUT we had three arguments!

Would do nothing, because there was no third argument.

This is used to control the behavior of scripts that require arguments. See the SHIFT command for additional capabilities.

SHIFT

The SHIFT command moves all values in the %# variables down one. For example, %1 will be set to whatever %2 was which in turn will be set to whatever %3 is and so on. This effectively shifts the arguments down by one. This is very useful for making a command that does an operation on everything in a list.

Example:

loop:
IF_1 GOTO continue:
exit
continue:
PUT examine %1
WAIT
GOTO loop

If this script was named lookat, then issuing the command ".lookat book rock log" will cause each of the items mentioned to be examined in order by this script.

%0 is modified such that as you SHIFT the arguments are removed from the front. So if %0 had "a b c" then after SHIFT it would be "b c" and after another SHIFT it'd be "c" and after another SHIFT it would be empty.

SAVE ["]{text}["]

The SAVE command puts the argument {text} into the %s variable. The %s variable is the "save" variable and is not reset when a script is run. This is useful for having a value that passes between different script executions.

Due to backwards compatibility with the Wizard front-end, if {text} contains spaces you must enclose the entire thing in quotes. This is different than most commands which will accept everything until the end of the line.

Example:

SAVE %1
ECHO %s has been saved for the next script.

This script puts whatever is in the first argument into the %s variable and lets the user know.

Note that the SAVE/%s feature is mostly obsolete because of the user variables exposed through the SETVARIABLE command.

ADDTOHIGHLIGHTSTRINGS string="{text}" [options]

The ADDTOHIGHLIGHTSTRINGS command adds or changes the options for a custom highlight string. This is a script version of adding/changing a highlight string as usually done from the Highlights dialog.

{text} specifies the string to highlight.

[options] are optional arguments, as follows:

foreColor={color}

Foreground color, see {color} below.

 

backColor={color}

Background color, see {color} below.

 

highlightEntireLine={True | False}

If TRUE, highlights enitre line (default is FALSE).

 

notOnWordBoundary={True | False}

If TRUE, matches partial words (default is TRUE).

 

matchPartialWord={True | False}

Alias for notOnWordBoundry.

 

caseInsensitive={True | False }

if TRUE, case is not checked (default is TRUE).

 

ignoreCase={True | False}

Alias for caseInsensitive.

 

{color}

A hexadecimal RGB or palette index color specification. For example:

foreColor=#FF0000
backColor=@1

A number by itself will be interpreted as a palette index for compatibility with old Wizard scripts.

Example:

ADDTOHIGHLIGHTSTRINGS string="my nose" foreColor=#FF0000 backColor=@0 notOnWordBoundary=true ignoreCase=True

ADDTOHIGHLIGHTNAMES string="{text}" [options]

Same as ADDTOHIGHLIGHTSTRINGS but adds/changes the Names highlights.

DELETEFROMHIGHLIGHTSTRINGS string="{text}"

Removes string specified by {text} from highlight strings.

This command is not supported by the Wizard but works with eScape and StormFront.

DELETEFROMHIGHLIGHTNAMES string="{text}"

Removes string specified by {text} text from Names highlights.

This command is not supported by the Wizard but works with eScape and StormFront.

SETVARIABLE {variable name} {value}

The SETVARIABLE command adds the variable {variable name} and sets it to the value of {value}. Any variables used in the value, as usual, are evaluated first so you can use this to do interesting concatenations of values (for example).

Example:

COUNTER SET 3
SETVARIABLE myVaraible I like the number %c
ECHO %myVariable

This example will output the text "I like the number 3" to the window.

This command is not supported by the Wizard but works with eScape and StormFront.

DELETEVARIABLE {variable name}

Deletes the indicated variable {variable name}, if it exists.

This command is not supported by the Wizard but works with eScape and StormFront.

COUNTER {SET|ADD|SUBTRACT|MULTIPLY|DIVIDE} {value}

The COUNTER command is used to manipulate the value in the %c counter variable. You set the value with COUNTER SET {value}, for example.

The counter is an integer value (no decimal value). A DIVIDE operation will ignore any remainder.

Example:

COUNTER SET 10
ECHO Counter is %c
COUNTER ADD 4
ECHO Counter is %c
COUNTER DIVIDE 2
ECHO Counter is %c (I expect it to be 7)

You can do interesting things with %c. For example:

COUNTER SET 2
GOTO my%c
my1:
PUT It was 1
exit
my2:
PUT It was 2
exit
my3:
PUT It was 3
exit

This example uses the %c counter variable to branch to one of three labels "my#" where # is substituted with the value in %c.

This command is not fully supported by the Wizard but works with eScape and StormFront.



Simutronics Corporation

Go Play!