All of the commands documented in this section can be used in any part of the code where some script code is required or allowed, for example in an object's "look" tag, the game's "afterturn" tag, and within procedures.
add <object name; parent object name>
Adds an object to the specified parent object.
- see Using Containers
action <object name; action name> script
Creates or replaces the specified action script for the specified object.
- see also object action tags, doaction script command, Changing an Object's Behaviour
animate [ persist ] <picture filename [ @ width x height ] [ ; caption ]>
Plays the specified animated GIF file in the picture window. The file extension must be specified. The syntax of this command is the same as that for picture. For some GIFs the size of the picture window may need to be specified manually. If persist is specified, the background frame persists throughout the animation.
- see also picture, picture close
Changes the background colour to the colour specified. Valid values for the colour are white, black, red, green, yellow, blue. You can also specify hexadecimal RRGGBB values from 00 to FF. For example, FF0000 is equivalent to red. Players may override this by forcing a game to use Windows default colours, so don't rely on this command always working.
- see also foreground script command, foreground, background tags (game definition block), How to Format Text
Shows the menu as defined by the specified selection block.
- see also the Selection Definition Blocks section
clear
Clears the text window.
clone <object to clone; new object name [; new object room ]>
Creates an identical copy of the object specified with the new name specified. The new object will have an alias of the name of the old object, so both objects will appear identical to the player. (You can of course change the object's alias after cloning by setting its alias property). Unless you specify otherwise, the new object will be created in the same room as the old object.
Closes the specified object.
- see Using Containers
conceal
see reveal
Creates a room, object or exit:
create exit [ north | south | etc... ] [ locked ] <from room; to room [; lock message]> [ script ]
Creates an exit in the direction specified from the "from room" specified to the "to room" specified. So,
create exit north <hallway; bedroom>would create an exit in the "hallway" room, north to "bedroom". In this example you'd probably also want to similarly create an exit south from "bedroom" to "hallway".
If the exit specified already exists (for example, there is already a way "north" from "hallway"), that exit will be replaced with what you specify here.
When creating an exit, if no direction such as "north" is specified, the exit is created as a "go to..." type exit. For example:
create exit <barber shop; street>To remove an exit, use the destroy exit command.
create object <object name [; container room]>
Creates an object with the specified name, in the room specified, if any. If no room is specified, the object does not exist within a room, but can be moved into a room as required using the move command.
create room <room name>
Creates the specified room.
debug <debug text>
Writes the specified debug text to the current Quest log file. This is useful for debugging purposes - you can write the contents of a specified variable to the log file whenever required, for example, to see where your code is going wrong.
dec <variable name [ ; decrement amount ]>
Decrements the specified numeric variable. If the variable has not been initialised, it is created first. dec will decrement the variable by one if no decrement amount is specified.
For example:
set numeric <mynum; 2> dec <mynum> msg <%mynum%>
returns the output 1.
destroy exit <from room; to room/direction>
Removes the specified exit. To remove an exit from the room "bakery" to the room "street", use:
destroy exit <bakery; street>
- see also create
displaytext <name of text section>
Displays the specified text block.
- see also the Text Blocks section
Executes the specified procedure, with any parameters specified. For example:
do <myprocedure> do <eatthing(asparagus; tasty)>
- see also the Procedure and Function Blocks section
doaction <object name; action name>
Executes the specified object's specified action script.
- see also object action tags, action script command
Use this command in a game beforeturn or room beforeturn script to stop Quest from processing the player's command when the script finishes.
enter <string variable>
Overrides handling of keyboard input for the next turn. The next thing the player types will be put into the string variable specified, and will not be executed as a normal command. This is useful if, for example, you want the player to type something in when requested. For example:
msg <Enter your name:> enter <playername> msg <Hello there #playername#! How nice of you to be here.>
Executes the specified command, just as if it were typed by the player, except that the command is not echoed to the screen (though its output is, of course). For example, exec <look at sign> would make Quest do the action associated with looking at the sign object in the current room, just as if the player had typed "look at sign".
A word of warning - if you use this as part of a command statement, you could feasibly end up in an infinite loop. The following example will cause Quest to hang:
command <take #object#> {
if ( #object# = potato ) then do <specialtake(#object#)>
else exec <take #object#> }
You may have coded the above, for example, if "potato" isn't a real object but you want Quest to react to "TAKE POTATO". However, if the player types another "TAKE" command, such as "TAKE LAMP", this will cause Quest to execute the exec statement, which will execute "TAKE LAMP", which will execute "TAKE LAMP"... Quest will end up in an infinite loop, causing it to hang.
In order that you don't end up hanging the interpreter when coding something like this, Quest has a normal parameter which will execute the command from Quest's built-in command set, disregarding all user-defined overrides of that command. To modify the above statement, you'd use:
command <take #object#> {
if ( #object# = potato ) then do <specialtake(#object#)>
else exec <take #object#; normal> }
This will cause the exec command to execute Quest's built-in form of the "TAKE" command, rather than the user-defined version which would normally have priority. This will mean no infinite loops, and Quest will behave as you'd expect.
When using the exec command, Quest will allow you to use real (i.e. unaliased) object names, whereas the player wouldn't be able to when using the command prompt. For example, if you have an object called BOOK01, with an alias of "book", the player can only refer to this object as "book". However, Quest will let you use exec <look at book01>.
If you have included files into a CAS file using !resource, you can use this command to extract those files. Files are usually extracted automatically whenever they are required, so you only need to use this command if you don't refer to pictures, sounds etc. directly using their filenames - e.g. if you use string variables to generate the filename.
- see also !resource
Sets or unsets the specified flag. You can use flags to keep track of whether a particular event has occurred in your game. To check whether a flag is set, use if flag.
Changes the current font to that specified. E.g.:
font <Verdana>
If no font name is specified, the font is set to the default font.
- see also default fontname and default fontsize in the Game Definition Block section and How to Format Text
for <counter variable; start value; end value [ ; step ]> script
Executes the specified script for all integer counter variable values between the specified start and end value, in steps of whatever step value is specified (or 1, if no step value is specified). For example:
for <mynum; 7; 15; 2> msg <mynum reads %mynum%>
Here, the counter variable is the numeric variable "mynum". The start value is 7 and the end value is 15, and here we've specified a step value of 2. This means that the above command prints:
mynum reads 7
mynum reads 9
mynum reads 11
mynum reads 13
mynum reads 15
You can "jump" out of the loop by setting the counter variable to a value equal to or higher than the end value within the script.
- see also repeat
for each { object | room | exit } in { game | <room name> } script
Executes the specified script for each object/room/exit, either in the whole game or in the specified room. Each time the loop script is executed, the current object/room/exit is returned in the #quest.thing# string variable.
Changes the foreground colour (and hence the colour specified by the |cb formatting code) to the colour specified. Valid values for the colour are white, black, red, green, yellow, blue. You can also specify hexadecimal RRGGBB values from 00 to FF. For example, FF0000 is equivalent to red. Players may override this by forcing a game to use Windows default colours, so don't rely on this command always working.
- see also background script command, foreground, background tags (game definition block), How to Format Text
Gives the specified object to the player.
Moves the player to the specified room.
helpclear
Clears the help window.
helpclose
Closes the help window.
helpdisplaytext <text section>
Used in the same way as displaytext, but prints to the help window rather than the main Quest window.
- see also displaytext
helpmsg <message>
Used in the same way as msg, but prints to the help window rather than the main Quest window.
- see also msg
Hides the specified object so it does not appear and does not interact with the player.
- see also show, reveal / conceal
if [ not ] condition1 [ { and | or } [ not ] condition2 ... ] then script [ else script ]
Evaluates an expression or series of expressions. If true, the script after then is executed. If false, any script after else is executed.
If the conditions are separated by "and", all of the conditions have to return "true" for the script after "then" to be executed.
If the conditions are separated by "or", only one of the conditions need return "true" for the script after "then" to be executed.
Valid conditions are:
( { string | value } { = | <> | < | > | <= | >= } { string | value } )
This is the basic condition form and it takes an expression in brackets. e.g.:
if (%myvariable% = 12) then msg <Twelve> else msg <Not twelve> if (#something# = blue) then do <blueprocedure> else do <otherthing> if (%somenumber% > 15) then picture <fifteen.gif; Over Fifteen> if (%something% <= 2 * (1.5 + %threshold%)) and (#place# = mansion) then playerlose if (%score% <> 100) then displaytext <notfullscore>action <object; action>
Returns a "true" if the specified object has the specified action defined.
ask <question>
Asks the player the question specified. If they select "Yes", a "true" is returned.
exists <object name [ ; report ]>
Returns a "true" if the object exists; i.e. is a real object in the game that is available, in any room. The optional "report" parameter can be used if you want the ASL log to log any time this check is used and the object is unavailable due to it not being defined in the game. The related condition, real, does not check that the object is available, only that it is defined.
Returns a "true" if the specified flag has been set. You can set flags using the flag command.
got <object>
Returns a "true" if a player has the specified object
here <object name>
Returns a "true" if the specifed object is in the same room as the player and is available.
property <object; property name>
Returns a "true" if the object specified has the property specified.
real <object name [ ; report ]>
Similar to the exists condition, but does not check that the object is available - only that it is defined in the current game.
type <object; type>
Returns a "true" if the object specified is of the type specified (i.e. it includes the relevant type tag).
E.g.:
command <eat #object#> if got <#object#> and property <object; edible> then doaction <#object#; eat>
would allow the player to type "eat" followed by any object name. Then, if the player had that object and the object were edible, the object's "eat" action would be executed.
To prevent ambiguities caused by having if commands within if commands, you can use braces. For example there is ambiguity associated with:
if got <A> then if got <B> then msg <1> else msg <2>
Here it is unclear whether the else msg <2> belongs to the first if or the second if. Using braces makes everything clear:
if got <A> then { if got <B> then msg <1> else msg <2> }
Or,
if got <A> then { if got <B> then msg <1> } else msg <2>
inc <variable name [ ; increment amount ]
Increments the specified numeric variable. If the variable has not been initialised, it is created first. inc will increment the variable by one if no increment amount is specified.
For example:
set numeric <mynum; 2> inc <mynum> msg <%mynum%>
returns the output 3.
Locks the specified exit.
- see also unlock
Takes the specified object away from the player, if it is in their inventory, and puts it in the current room. If you want to take the object from the player and don't want it put in the current room, use hide instead.
mailto <email address>
Starts the default email program for a message to the specified email address. Useful if you want to implement a feedback command, for example.
Moves the specified object to the specified room.
Prints the specified message. If nospeak is specified, the text will never be spoken by the text-to-speech engine, even if the player has set the option to speak all text.
Opens the specified object.
- see Using Containers
Stops all text output to the Quest window. This is useful if you want to move the player to some location without displaying that location's description. Remember to turn output back on again using outputon, or the player won't be able to read anything.
- see also outputon
Turns output back on again after being turned off with the outputoff command.
- see also outputoff
panes { on | off }
Turns on or off the "panes" on the right-hand side of the Quest window.
Pauses the game for the specified number of milliseconds (1000 milliseconds = 1 second).
- see also wait
Shows the specified picture in the main window. Quest supports .BMP, .ICO, .RLE, .WMF, .EMF, .GIF and .JPG formats.
- see also picture popup
picture popup <picture filename [ @ width x height ] [ ; caption ]>
Shows the specified picture in a separate popup picture window (equivalent to the "picture" command in Quest 3.53 and earlier). Quest supports .BMP, .ICO, .RLE, .WMF, .EMF, .GIF and .JPG formats.
If a caption is specified, that caption is used for the window title, rather than the default "Picture". You can resize the picture by setting the width and height in pixels. For example:
picture <dragon.jpg@400x320; Dragon>
would show "dragon.jpg" with the caption "Dragon", resized to be 400 pixels wide by 320 pixels high.
- see also picture, picture close, animate
Closes the picture window.
- see also picture popup
The player loses (and the text in the define text <lose> block is displayed)
The player wins (and the text in the define text <win> block is displayed)
- see also playerlose, stop
playmidi <MIDI filename [ ; loop ]>
Plays the specified MIDI file in the game directory, or relative to it - note that the .MID or .MIDI extension is required. The MIDI file is played in the background. playmidi <> will stop any MIDI file from playing. Specifying the loop parameter will cause the MIDI file to loop.
Plays the specified MP3 file in the game directory, or relative to it. playmp3 <> will stop any MP3 file from playing.
playwav <WAV filename [ ; sync ] [ ; loop ] >
Plays the specified WAV file in the game directory (or relative to it - for example if the game is in C:\MY-IF\GAME1\ then playwav <wavfiles\welcome> will play C:\MY-IF\GAME1\WAVFILES\WELCOME.WAV). The file extension is optional - .WAV will be added if no extension is specified. Quest will silently ignore any attempt to play a non-existent file. playwav <> will stop any WAV file from playing. Specifying the loop parameter will cause the WAV file to loop.
Usually, Quest will start playing the WAV file and immediately return to the rest of the script, leaving the WAV to pay in the background. If the sync parameter is specified, Quest will wait for the WAV to finish before resuming processing - useful for things such as intros where you want some text to display after a sound ends, for example.
property <object name; property data ...>
Changes the properties of the specified object. For example:
property <potato; not edible; age=15; smelly>
will turn off the "edible" property, set the age to "15" and add the "smelly" property.
- see also the object properties tag, Changing an Object's Behaviour
Removes the specified object from its parent.
- see Using Containers
repeat { until | while } condition[s]... script
Repeats the specified conditions while, or until, the specified condition or conditions are true. The conditions you can specify here are the same conditions you can use for an if command. For example:
repeat until (#answer# = yes) or (#answer# = no) {
msg <Do you really want to go into that big, dark pit? Answer YES or NO.>
enter <answer> }
- see also for
{ reveal | conceal } <object name>
reveal and conceal take the same parameters as hide and show etc., and act in a similar way. However, rather than being used in conjunction with the hidden tag of objects, these commands act with the invisible tag - so when you use conceal, the object is hidden but it is still accessible to the player and can be interacted with as before. This is different to hide, which would completely remove the object from the room so it couldn't be interacted with.
select case <value> {
case <value1 [; value2 ...]> script
.
.
[ case else script ]
}
This is equivalent to the BASIC Select Case command, or the switch statement in C. It allows you to specify script based on the value of e.g. a string variable, without having to use lots of nested if commands. An example should make things clearer:
msg <Enter a telephone number:>
enter <phonenumber>
select case <#phonenumber#> {
case <911; 999> msg <There's no need to call the police now.>
case <94672> {
msg <Madame Buxom, Queen of Pain, is on her way.>
do <hideous-experience> }
case <32461> msg <A voice at the end of the line says "Stop calling this number you pervert!">
case <15629> do <order-pizza>
case else msg <Sorry, wrong number!>
}
set ...
set <string or numeric variable name; string or value>
For an existing variable, changes the value or string contained in it. To declare a new variable use either set string or set numeric.
set interval <timer name; new interval>
Sets the interval (in seconds) of the specified timer.
- see also Timer Definition Blocks
set numeric <variable name; value>
Sets the value of the specified numeric variable. The "value" parameter supports mathematical expressions using + (addition), - (subtraction), / (division) and * (multiplication) operators, for example:
set numeric <withtax; 1.175 * %total%> set numeric <mynumber; (%something%/2) * (%whatever% + (%thing% * 6.022))>set string <variable name; string>
Sets the string contained in the specified string variable. The "string" specified will be stripped of leading and trailing spaces. To set a string variable containing spaces, use [ ] characters around the whole string parameter. e.g. set string <space; [ ]>.
To read the contents of a string or numeric variable in any parameter, surround a string variable name with "#" characters and a numeric variable name with "%" characters.
Examples:
set string <mytext; This is the text I'm storing.> set numeric <mynumber; 7> set <mynumber; %mynumber% + 7> msg <The text I stored was #mytext#.> msg <My number is %mynumber%.>Notes:
- If you need to increment or decrement a variable, it is easier to use the inc or dec script commands. For example, inc <mynumber> is equivalent to set <mynumber; %mynumber% + 1>
- When setting a variable do NOT use # or % characters around the string or numeric variable name. You only use # or % characters when displaying and comparing the value of variables.
- Division by zero results in an ASL logfile error message, and a message on-screen.
Shows the specified object - the opposite of hide.
- see also hide, reveal / conceal
Speaks the specified message through the text-to-speech engine. The message is not printed to the screen. Speech must be enabled for this command to have effect. To see if speech is enabled, use the $speechenabled$ function.
Finishes the game. Unlike playerwin and playerlose, this does not automatically print any text sections.
- see also playerwin, playerlose
Turns on the specified timer.
- see also timeroff, Timer Definition Blocks
Turns off the specified timer.
- see also timeron, Timer Definition Blocks
Adds all the properties and actions of the specified type to the specified object.
- see also object type tags, Type Definition Blocks
Unlocks the specified exit.
- see also lock
Waits for the user to press a key before continuing execution. Useful when printing large amounts of text to the screen for example. If used on its own without any parameter, wait will print the default "Press any key to continue..." (or whatever is specified as the defaultwait message). If used with an empty parameter (i.e., wait <>), wait won't print anything. If there is text in the parameter, wait will print that instead of the default text.
- see also pause