Script commands

Scripts are created in a style similar to C, with script blocks denoted by braces. Unlike C, there is no character to mark the end of a line - each script command is simply on its own line.

if (someVariable = 3) {
  msg ("Some text")
}

Comments

Comments are denoted by // - anything after it on the same line is ignored:

// this line will be ignored

Setting variables

To set an object attribute to a value:

object.attribute = value

To set a variable to a value:

variable = value

To set an object attribute to a script:

object.attribute => { script }

To set a variable to a script:

variable => { script }

ask

ask (string question) {script}

Superseded: this command is no longer offered when you add a script command - use the Ask function instead, which asks the same question the same way but hands the answer straight back, so it can go directly in an if and the script simply continues on the next line. ask still runs, and is still editable in games that already use it.

Shows “Yes” and “No” as numbered links in the transcript for the user to answer the specified question, and then runs the nested script.

The nested script can check the “result” boolean variable to see the user’s response - true for “yes”, false for “no”.

ask ("Do you want to eat an apple?") {
  if (result) {
      msg("Ahhh, very tasty")
  } else {
      msg("But you should eat your daily apple!")
  }
}

create

create (string name)

or

create (string name, string type)

Creates an object with the specified name. You can subsequently access the object using the GetObject function, or just use its name directly in an expression.

If you specify a type, the object created will be of that type. The command only accepts one type name - if you want the new object to inherit multiple types, you could create one type which inherits all of those types, and specify that here.

create exit

create exit (string alias, object from, object to)

or

create exit (string alias, object from, object to, string type)

or

create exit (string name, string alias, object from, object to, string type)

Creates an exit with the specified alias (usually the direction, such as “north”) between two objects/rooms.

An initial type can be specified e.g. “northdirection”. This will ensure that the correct alt names are applied to compass exits.

create exit ("northwest", fromRoom, toRoom, "northwestdirection")

You can also specify the object name to use. If not specified, an id will be automatically generated.

create exit ("exit_to_garden", "northwest", fromRoom, toRoom, "northwestdirection")

It is usually easier to make an exit in the normal way in the editor, but to set it so it is not visible; instead of then creating an exit during game play, you set this exit to be visible.

create timer

create timer (string name)

Creates a timer with the specified name. You can then use GetTimer to get the timer, and assign values to it - GetObject does not find timers. Here is a trivial example that will produce a timer that will tell you its name every 10 seconds:

create timer ("test_timer")
o = GetTimer ("test_timer")
msg (TypeOf(o))
o.script => {
  msg ("timer=" + this.name)
}
o.interval = 10
EnableTimer(o)

It is generally easier to create the timer in the editor, but have it disabled, and then enable it when required.

create turnscript

create turnscript (string name)

Creates a turnscript with the specified name. You can then use GetObject to get the turn script, and assign values to it. Here is a trivial example that will produce a turnscript that will tell you its name every turn:

create turnscript ("test_ts")
o = GetObject("test_ts")
o.script => {
  msg ("turnscript=" + this.name)
}
o.enabled = true

It is generally easier to create the turn script in the editor, but have it disabled, and then enable it when required.

destroy

destroy (string name)

Destroys the specified object. Note that this takes the object’s name, not the object itself, as a parameter.

dictionary add

dictionary add (dictionary, string key, any type item)

Adds an item to the specified dictionary.

See Using Dictionaries

dictionary remove

dictionary remove (dictionary, string key)

Removes the specified item from the dictionary.

See Using Dictionaries

do

do (object, string attribute name)

Runs an object’s script attribute.

do (object, string attribute name, dictionary parameters)

Runs an object’s script attribute, passing in parameters via dictionary. The key/value pairs in the dictionary will be turned into local variables for the script. The special variable “this” can be used in the script to reference the object.

error

error (string message)

Stops running the current script and raises the specified error message.

finish

finish

Ends the game - no further commands are accepted, and any pending timers, menus or other prompts are cancelled.

firsttime

firsttime { script1 } [ otherwise { script2 } ]

runs script1 if it is the first call, otherwise script2 is executed

for

for (iterator variable, int from, int to) { script }

There is an optional “step” parameter:

for (iterator variable, int from, int to, int step) { script }

Run a script multiple times, incrementing the iterator variable between the specified limits. If a “step” parameter is specified, the iterator variable will be incremented by that amount each time (if not specified, the default step size is 1).

Traditionally, i, j, k… are used as iterator variable names. This simple example runs from 1 to 5, printing each value in turn:

for (i, 1, 5) {
  msg(i)
}

Generally, foreach offers a neater way of going through a list, but for can be useful for iterating through a string. This example will print each character in the string, together with its position:

s = "Hello World!"
for (i, 1, LengthOf(s)) {
  msg(i + ": " + Mid(s, i, 1))
}

Note: The iterator variable should be a local variable, not an attribute. For example, consider this code, which uses an attribute of the game object:

for (game.i, 1, 5) {
  msg(game.i)
}

If game.i already exists, the loop will run 5 times as expected, but the value of game.i will keep its original value. If game.i does not exist, an error will be produced.

See Using Lists

foreach

foreach (iterator variable, list) { script }

Run a script for each item in a list. If the list is a dictionary, the loop iterates over the dictionary keys.

Note: Do not use an attribute as the iterator variable (see here).

For more on how and why to use foreach, see Using Lists

get input

get input {script}

Superseded: this command is no longer offered when you add a script command - use the GetInput function instead, which waits for the player in the same way but returns what they typed, so the rest of the script can just carry on below it. get input still runs, and is still editable in games that already use it.

Waits for the user to type some text, then runs the nested script.

The nested script can evaluate the “result” string variable to work with the user’s input.

Example:

msg ("What is your name?")
get input {
   msg ("Your name is " + result)
}

For more information see Asking the player.

if

if (boolean expression) { script } [ else if ... ]* [ else { script } ]

Conditionally runs the script. If the condition fails, the else script is run, if present. Multiple if/elses can be put together. Some examples:

if (result > 10) {
  msg("Great!")
}

An else can be added (no need for a condition)

if (result > 10) {
  msg("Great!")
}
else {
  msg("Rubbish!")
}

Or we can have a condition; nothing gets printed if result is between 2 and 10.

if (result > 10) {
  msg("Great!")
}
else if (result < 2) {
  msg("Rubbish!")
}

You can have as many if/else linked together as you need (but consider using switch).

if (result > 10) {
  msg("Great!")
}
else if (result > 2) {
  msg("Meh...")
}
else {
  msg("Rubbish!")
}

Complex conditions can be used with Boolean arithmetic.

if (result > 10 and not player.is_female) {
  msg("Good boy")
}

insert

insert (string filename)

Outputs the contents of the specified HTML file.

Not supported in Quest 5.4 or later, including Quest Viva - it raises an error rather than doing anything. Unlike Pause and WaitForKeyPress, this one was not brought back for ASL version 600. Output the HTML with msg instead.

invoke

invoke (script)

Runs a script.

invoke (script, dictionary parameters)

Runs a script, passing in parameters via dictionary. The key/value pairs in the dictionary will be turned into local variables for the script. See also the do script command.

list add

list add (list, any type item)

Adds an item to a list.

See Using Lists

list remove

list remove (list, any type item)

Removes an item from a list.

See Using Lists

msg

msg (string message)

Prints the specified text to the transcript.

msg ("You open the door.")

The text is a normal string expression, so it can be built up with concatenation, e.g. msg ("Score: " + game.score), and can include HTML for formatting.

on ready

on ready { script }

Runs the nested script when any callbacks have finished.

For example, when you use an ask or get input script command, Quest Viva will wait for a response from the player and then run the nested scripts from those commands. However, any other scripts at the same level will run immediately. If you don’t want this to happen, use “on ready” to make the script only run after the user has entered a command or responded to the question.

This is used by the Core library so that, for example, a room description is only displayed after any scripts which ask a question in “before enter” have run their nested scripts. This prevents the room description from being displayed while the question is still on-screen.

Generally there should be no need to use this command in your own games, as of course if you want script to run after an “ask”, you can just put it inside the “ask” script block.

Note that this does not wait for scripts attached to functions to work (such as Ask and ShowMenu). see Saving while a question is waiting

picture

picture (string filename)

Outputs the specified picture file. The file must already have been added to the game as a resource - reference it by filename only (e.g. "cave.jpg"), not a full path.

play sound

play sound (string file, boolean wait, boolean loop)

Plays a sound file (WAV or MP3 format), which must be in the same directory as the game file. If the parameter wait is “true”, the script will stop until the sound has finished. If the parameter loop is “true”, the sound will loop.

request

request (request name, string parameter)

Raises a UI request. The request name must be specified directly - it is not a string expression. For example:

request(UpdateLocation, "The Kitchen")

The request script command is really a throw-back to the original Quest 5.0 interface, which, while it did use HTML, was not a fully-fledged browser. As of 5.3, the interface is a version of Chrome embedded in the software, and all interaction between the game world and the interface is done with JavaScript. Since then request has become increasingly obsolete, and it is recommended that the alternative is used. It is just possible request will be taken out of Quest Viva at some date.

Valid request names, what they do, and their modern alternative:

Request name	Effect	Use instead
Background	Sets the background to the specified HTML colour.	SetBackgroundColour
ClearScreen	Clears the screen. Parameter is ignored.	ClearScreen
Foreground	Sets the foreground to the specified HTML colour.	SetForegroundColour
GameName	Sets the name of the game.	JS.setGameName(name)
Hide	Turns off an interface element.	JS.uiHide(…)
LinkForeground	Sets the link foreground to the specified HTML colour.	SetLinkForegroundColour
Log	Logs the specified text.	Log
PanesVisible	Shows/hides the side panes. “on”/“off” toggle them; “disabled” turns them off and removes the button to turn them back on (that button appears to no longer be available).	JS.panesVisible(true / false)
Pause	Pauses the game for the specified number of milliseconds.	Pause (which is just this request, in seconds)
Quit	Quits the game. Parameter is ignored.	finish
RequestSave	Requests the UI to save the game (may prompt a “Save As” dialog). Parameter is ignored.	requestsave
RunScript	Runs the specified JavaScript function.	the JS object, e.g. JS.myCustomFunction(15, "some string")
SetCompassDirections	Assigns compass direction names from a semicolon-separated list.	JS.setCompassDirections(…)
SetInterfaceString	Sets UI text via an "ElementName=Value" parameter.	JS.setInterfaceString(…)
SetPanelContents	Sets the static panel HTML contents.	SetFramePicture and ClearFramePicture
SetStatus	Sets the status area text (right of screen, under “Inventory”); blank removes it.	status attributes
Show	Turns on an interface element (“Panes”, “Location” or “Command”).	JS.uiShow(…)
ShowPicture	Shows the specified picture file from the game directory.	picture
Speak	Was intended to read the parameter aloud. Does nothing in Quest Viva - no player implements it.	—
UpdateLocation	Updates the location bar with the parameter text.	JS.updateLocation(location)
Wait	Waits for the player to press a key. Parameter is ignored.	WaitForKeyPress (which is just this request)

FontName and FontSize aren’t listed above: they now raise an error rather than do anything, so use SetFontName and SetFontSize instead.

requestsave

requestsave

Asks the player to save the game, as though they had clicked Save themselves. Takes no parameters.

This replaces request (RequestSave, ""), which does the same thing - see request above. There is also a RequestSave function that calls it, kept for older games.

requestspeak

requestspeak (string text)

Was intended to read the given text aloud. It does nothing in Quest Viva - none of the players implement it - and it is documented here only because the editor still offers it, and because games written for earlier versions of Quest may contain it.

This replaces request (Speak, "some text"), which is equally inert.

return

return (any type result)

Sets the return value of a function, and stops execution of the function immediately.

This command should only be used within a <function> element.

rundelegate

rundelegate (object, string attribute name, any type parameters ... )

Runs an object’s delegate implementation script attribute, with the specified parameters.

See Using delegates

set

set (object, string attribute name, any type value)

Sets a named attribute on the object.

Note that you can also use this syntax to do the same thing:

object.attribute = value

You only need to use the “set” command if you are constructing the attribute name using an expression.

show menu

show menu (string caption, stringdictionary or stringlist options, boolean allow cancel) {script}

Superseded: this command is no longer offered when you add a script command - use the ShowMenu function instead, which shows the same menu but returns the chosen option, so the rest of the script can just carry on below it. show menu still runs, and is still editable in games that already use it.

Shows the options as a numbered list of links in the transcript and then runs the nested script. The script can access the variable “result” which contains the result of the user selection - if a dictionary of options is passed in, the key is returned. If a list of options is passed in, the list item is returned.

If the “allow cancel” parameter is set to true, entering any command other than one of the option numbers dismisses the menu, and the variable “result” is null. If it is set to false, anything else the player types is ignored.

This command suspends the script mid-turn, so the player can’t save while the menu is up. For a menu that ends the turn first, leaving saving available while the player chooses, use the ShowMenu function’s callback form, ShowMenu (caption, options, allow cancel) { script }.

example:

menulist = NewStringList()
list add (menulist, "first entry")
list add (menulist, "second entry")
list add (menulist, "third entry")
show menu ("please choose now", menulist, true) {
  msg ("--" + result + "--")
  if (result<>null) {
     msg ("You have chosen the " + result)
  }
  else {
     msg ("You have chosen to press cancel")
  }
}

start transaction

start transaction (string command)

Starts a transaction in the undo-logger for the specified command, and ends the previous transaction (if one was open).

stop sound

stop sound

Stops playing sounds.

switch

switch (any type value) { case (any type value) { script } [ default { script } ] }

Switch is used with one or more case statements and an optional default statement. It is used to test a variable or object attribute against 2 or more possible values; a shortcut instead of writing many if statements.

switch (LCase(answer)) {
  case ("north", "n") {
    msg ("You head north.")
  }
  case ("south", "s") {
    msg ("You head south.")
  }
  default {
    msg ("That's not a direction.")
  }
}

The cases are checked in order, and only the first one that matches runs. A case can list several values, separated by commas, and it matches if any of them does. If no case matches, the default script runs, if there is one.

Each case must match exactly, but you can check ranges by switching on true and giving each case a condition:

switch (true) {
  case (player.strength > 20) {
    msg ("You are strong!")
  }
  case (player.strength > 10) {
    msg ("More training required!")
  }
  default {
    msg ("Weakling!")
  }
}

A strength of 25 matches the first case only - once a case has matched, the rest are skipped.

For using switch with a menu, see Asking the player.

undo

undo

Reverts the game state to how it was before the current transaction - see start transaction for how transaction boundaries are controlled. Without any explicit start transaction calls, this means undo undoes the whole of the previous turn in one go, not just a single script line. It reverts every attribute change; text already printed stays on screen.

wait

wait {script}

Superseded: this command is no longer offered when you add a script command - use the WaitForKeyPress function instead (which is just request (Wait, "") under the hood), as that waits without needing a nested block at all. wait still runs, and is still editable in games that already use it.

Waits for the user to press a key or click on a “Continue” link, and then runs the nested script. Each successive part needs to be nested inside the one before, like this:

msg ("First bit")
wait {
  msg ("Second bit")
  wait {
    msg ("Third bit")
  }
}

With WaitForKeyPress there is nothing to nest:

msg ("First bit")
WaitForKeyPress
msg ("Second bit")
WaitForKeyPress
msg ("Third bit")

while

while (expression) { script }

Runs a script repeatedly for as long as the given expression evaluates to true, checking the condition again before each pass.

count = 1
while (count <= 5) {
  msg (count)
  count = count + 1
}

Make sure something inside the script eventually makes the expression false - otherwise the loop (and the game) never moves on. For a fixed number of iterations, for is usually clearer.