Introduction
Wrayth 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 Wrayth.
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 Wrayth.
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 Wrayth.
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 Wrayth.
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 Wrayth.
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 Wrayth.
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 Wrayth.
HOME
