Introduction - how to use functions
Game Functions - return game, object and timer information
String Handling and Variable Functions - process string variables
Miscellaneous Functions - generating random numbers, check if speech is enabled, print a symbol
Parameter Functions - use when creating your own functions
Obsolete Functions - additional functions which are rarely needed
Quest has several useful internal functions for string handling etc. These should all be used inside parameters for other tags or script commands, as they return a value - they don't do anything on their own. For example, a use of the $rand$ function is:
if ( $rand(1:10)$ = 1 ) then do <lucky procedure>
And a use of the $capfirst(...)$ function is:
msg <Enter your name:> enter <playername> set string <propername; $ucase(#playername#)$> msg <Hello there #propername#!>
$findexit(from room; to room)$
Returns the object name of the specified exit For "go to" type exits, enter the room name as the second parameter. For directional exits, enter the direction, for example:
$findexit(street; bakery)$ $findexit(bedroom; north)$
$locationof(object name)$
Returns the location of the specified object (the name of the room that it is currently in).
Returns the timer interval of the specified timer, in seconds. Returns "!" if the timer name specified does not exist.
- see also Timer Definition Blocks, set interval.
Returns "1" if the specified timer is on, "0" if the specified timer is off, and "!" if the timer name specified does not exist.
- see also Timer Definition Blocks, timeron, timeroff.
$capfirst(string)$
Capitalises the first letter of the string passed to it. E.g.:
$capfirst(bill)$
returns "Bill"
$instr( [ start position; ] search string; string to find)$
Returns the position of the start of the specified string to find within the search string, optionally starting the search from the specified start position. E.g.:
$instr(Potato to go;to)$
returns "5"
$instr(6;Potato to go;to)$
returns "8"
If you want to search for something that has spaces at the beginning and/or end - for example, the single word "to" in the above example rather than "to" as a part of the word "potato" - you'll need to search for something like " to " - however, Quest will automatically strip function parameters of leading and trailing spaces. To get around the problem, use the underscore character "_". So, to search for the single word "to" in the above examples, use:
$instr(Potato to go;_to_)$
which returns "8".
$lcase(string)$
Returns a lower-case version of the string passed to it. E.g.:
$lcase(thIs sTRinG)$
returns "this string"
$left(string; length)$
Returns the specified number of characters from the left of the string. E.g.:
$left(Hello there!;5)$
returns "Hello".
$lengthof(string)$
Returns the length of the specified string. E.g.:
$lengthof(Hello there!)$
returns 12.
$mid(string; start [ ; length ])$
Returns the middle characters from the specified start point up to the length specified. E.g.:
$mid(Hello there world!;7;5)$
returns "there".
Note that length can be omitted - Quest will then return the rest of the string from the "start" position. E.g.:
$mid(Hello there world!;7)$
returns "there world!".
$right(string; length)$
Returns the specified number of characters from the right of the string. E.g.:
$right(Hello there!;6)$
returns "there!".
Returns the upper bound of the specified array.
$ucase(string)$
Returns a capitalised version of the string passed to it. E.g.:
$ucase(thIs sTRinG)$
returns "THIS STRING"
$rand(num1; num2)$
Returns a random number between the specified num1 and num2. E.g.:
$rand(4;7)$
will return 4, 5, 6 or 7.
Returns 1 if speech is enabled, and 0 if speech is disabled.
$symbol(symbol code)$
Prints a symbol.
This function accepts two symbol codes - "gt" returns a greater-than sign ">", and "lt" returns a less-than sign "<". These cannot be normally typed into parameters as these characters form the start and end points of parameters - msg <You see a sign: < Brussels London >> would severely confuse the Quest code parser, so the above should be coded as:
msg <You see a sign: $symbol(lt)$ Brussels London $symbol(gt)$>
Parameter functions are used for functions and procedures you write yourself. Within these functions and procedures, you can find out how many parameters were passed to it and what they were:
$numberparameters$
Returns the number of parameters passed to this function.
$parameter(parameter number)$
Returns the specified parameter.
For example, if you call a procedure using do <myprocedure(My text; 5)>, then your procedure definition might look like:
define procedure <myprocedure>
if ( $numberparameters$ < 2 ) then msg <error>
else {
for <i; 1; $parameter(2)$> msg <$parameter(1)$> }
end define
The procedure would then print the text "My text" five times.
$displayname(object name)$
Returns the displayed name of an object, when passed the real name of an object. This is obsolete as it is equivalent to using #@(object name)#. For example,
$displayname(object001)$
and
#@object001#
both return the same thing - namely, "object001" if the object called "object001" has no alias, or its alias if it does have one.
$getobjectname(object name [ ; container room ])$
This is the opposite of $displayname(...)$. This returns the actual name of an object from the displayed name, and it can be used when processing player input for object names. If there is an ambiguity (i.e. when two or more objects have the same alias), it displays the standard Quest disambiguation menu and the player is asked to choose which object they mean. By default, Quest will check for the object in the current room and in the inventory, unless you specify a container room, in which case Quest will check that instead (you can make Quest check the inventory as well by adding "; inventory" to your container room, e.g. $getobjectname(myobject; someroom; inventory)$). You can make Quest look throughout all rooms in the game by specifying game as the container room parameter, for example:
$getobjectname(rabbit; game)$
When using "game", you can use an optional second parameter "seen". This restricts the search to objects that the player has already seen. An object is counted as seen if its "seen" property is set, or it is in the inventory, or the room it is contained in has its "visited" property set.
The use of this function has now been largely superseded by the use of the #@...# form in command statements - see How To Add Your Own Commands to a Game for full details. This means that:
command <ignite #@thing#> doaction <#thing#; ignite>
is equivalent to the older, and lengthier form which uses the $getobjectname(...)$ function:
command <ignite #thing#> doaction <$getobjectname(#thing#)$; ignite>
$loadmethod$
Returns "normal" if the game was loaded from new; returns "loaded" if the game was restored from a QSG file. As of Quest 4.0, the game startscript is only run when the game is loaded for the first time (it is not run when the game is started from a QSG), which means that this function no longer serves any useful purpose.
$objectproperty(object name; property name)$
Returns the value of the specified property of the specified object. Returns "!" and reports an ASL error if the specified object or property does not exist. This function is obsolete as it is equivalent to using #object:property# - see Reading Properties for more information.