XML elements

Note that this is about XML elements in the ASLX file, which is not quite the same as the elements in the game.

asl

<asl version="580">all game content</asl>

To load any game, the top-level element must be an <asl> element as shown above. All other XML elements in the file must appear within this tag.

library

<library>all library content</library>

The top-level element of any library must be a <library> element as shown above. All other XML elements in the file must appear within this tag.

include

<include ref="filename"/>

Loads the specified library.

template

<template name="name">text</template>

Creates a template of the specified name. You can print the template’s text using the Template function.

Within a language library, a template may define a templatetype of “command”, for example:

<template templatetype="command" name="undo">^undo$</template>

This simply is a flag to the Editor to prevent it from showing the template in the list of templates (as the way to edit it would be to edit the associated command pattern).

A template defined in your own game file always overrides one of the same name from a library, wherever you put it - before the language include, between the includes, or after them. The loader flags templates that come from the game file itself, and a library definition is never allowed to replace one of those. Older versions of Quest did depend on the order, and advised moving overrides in by hand to sit between the language include and the Core include; that is no longer necessary.

dynamictemplate

<dynamictemplate name="name">expression</dynamictemplate>

A dynamictemplate is used in a similar way as template, except that its value is an expression, not a static string. The expression will have access to an object called “object”, which you can use to craft a response.

You can print a dynamic template using the DynamicTemplate function. This takes an object or text parameter, which is then passed in to the template expression.

verbtemplate

<verbtemplate name="name">text</verbtemplate>

Creates or adds to a verb template of the specified name. Specifying multiple verb templates with the same name lets you handle multiple verbs with one template.

You can refer to verbtemplates within a verb element, or using the “template” attribute of a command element.

The text can optionally include #object# as a stand-in for the object name; if it is omitted, the object name is assumed to be at the end. For example:

<verbtemplate name="wear">wear</verbtemplate>
<verbtemplate name="wear">put on</verbtemplate>
<verbtemplate name="wear">put #object# on</verbtemplate>
<verbtemplate name="wear">don</verbtemplate>

function

<function name="name" type="type" parameters="parameters">script</function>

Creates a function. Only name is required; type and parameters are both optional.

If no type is specified, the function does not return a value.

If the function does return a value, the type should be one of the valid Attribute Types. Return a value within the function using the return command.

If the function takes parameters, the parameters should be specified as a comma-delimited list.

For example:

<function name="FormatObjectList" type="string" parameters="preList, parent, preFinal, postList">
...
</function>

The attributes of a function

name: This is the name of the function. Every function must have name, and that is the name you use to invoke the function in some other script.

parameters: These are the values (if any) passed into the function. You give them names, and when the function is called, those parameters must be set by giving values in the function call (e.g. MyFunction(a, b) ). The values are mapped to the parameters in the order they are given. If your function does not take input parameters, then you can omit this or leave it as an empty string.

type: This is the return type of the function (the value passed out), if the function returns a value. Some functions do, and some don’t. If you use a “return” statement in your function to send a value back to the caller, then you need to specify the return type, so that Quest Viva knows what type the function is expected to return. If your function does not return a value, then you can omit this or leave it an empty string.

Quest Viva will object if there is a return statement, but no type specified; or if there is a type specified, but no return statement.

A Working Example

Here is a trivial example. It’s a function to concatenate two strings and return the result. Clearly, you don’t need this function (since you can just use the “+” yourself), but hopefully it illustrates how functions are set up.

<function name="ConcatStrings" parameters="s1, s2" type="string">
  return (s1 + s2)
</function>

This basically says, “We have a function called ‘ConcatStrings’, it takes two input parameters, which we will call ‘s1’ and ‘s2’ inside the function, and the function returns a string value.”

The function would be invoked as:

s = ConcatStrings("Mama ", "Mia")

The resulting “s” would be “Mama Mia”

command

<command name="name" pattern="pattern" unresolved="unresolved text" template="template name">script</command>

or

<command name="name">attributes</command>

All XML attributes are optional.

Creates a command. There are two syntaxes - one syntax lets you specify a pattern, some text to display when an object is unresolved, and the script to run. The second syntax is more open and flexible, and lets you specify everything by directly setting the attributes of the command object. The second syntax is preferred, although the first may be more concise.

All commands automatically inherit a “defaultcommand” type if it exists.

Name

If a name is not specified, a unique name will be created. Using the first syntax allows Quest Viva to try and create a user-friendly name by taking the first word(s) of the specified pattern; otherwise the name will be something like “k1”. It is best to always specify a name, as it will make debugging easier - the Debugger will show you a sensible name for your command. It will also let you easily change the behaviour of the command by setting its attributes when the game is in progress.

Pattern

The “pattern” attribute of a command is a string - the regular expression that triggers the command. You can use friendlier syntax with type=“simplepattern”, which in Core.aslx is set as the implied type for a command “pattern” attribute, so you don’t need to specify it. This will convert friendly syntax such as “look at #object#” into a regular expression. If you want to specify a regex yourself, you need to explicitly set type=“string”.

Unresolved

The “unresolved” attribute is the text to print if the user enters the name of an object which is not in the current visible scope.

Template

The “template” attribute specifies the command pattern to use, if the command pattern is defined by a verbtemplate.

Allow all

To handle “take all” and “drop all”, the “take” and “drop” commands, for example, have “allow_all” set to true. When this is set to true, the script attribute will be sent an object list as “object” instead of a single object. In addition, it will be sent “multiple” which will be true to indicate the player used “all”, and so the items need a prefix saying what they are.

Scope

The scope attribute tells Quest Viva where to look first for objects for this command. See the “Alternative scope” section of this page for details.

verb

<verb name="name" pattern="pattern" unresolved="unresolved text" property="attribute name" response="default response text" template="template name">script</verb>

or

<verb name="name">attributes</verb>

All XML attributes are optional.

Creates a verb, which is a specialised type of command element - so everything that applies to a command also applies to a verb. Underneath, verbs are just commands - if you look at them in the Debugger, they are the same thing. But they are designed to be easier to use than commands for the vast majority of commands which are of the form “command object”, such as “look at thing”, “eat food”, “sit on bench” etc.

In addition to any “defaultcommand” type, verbs also inherit “defaultverb”. In Core.aslx this provides the standard verb implementation. We take the object the player entered, and look for the attribute as specified by “property”. Then:

• if the attribute is a script, run it;
• if the attribute is a string, print it;
• if the attribute is not set, print the default verb response (e.g. “You can’t eat it”)
• if the attribute is some other type, raise an error.

type

<type name="name">properties</type>

Creates a type. The type element can contain properties and <inherit> tags.

Use an <inherit> tag in an object definition to include all the type’s properties in that object.

See Types.

game

<game name="name">properties</game>

Defines the game and its global properties. Every ASLX file has exactly one <game> element.

Bibliographic metadata

These fields describe the game for players and catalogues. Most are optional; new games created in the editor are given a gameid, version, versioncode, and firstpublished automatically. You can edit them on the game’s Setup tab.

<game name="Cloak of Darkness">
  <subtitle>A basic IF sample</subtitle>
  <author>The Pixie</author>
  <version>1.0</version>
  <versioncode type="int">1</versioncode>
  <gameid>18ad63b5-78e2-4846-872b-9177d78cc5e6</gameid>
  <category>Fantasy</category>
  <firstpublished>2018</firstpublished>
  <cover>cover.png</cover>
  <description>From the specification here:...</description>
</game>

name (XML attribute)
The title of the game. Written as the name attribute on the <game> tag, but stored internally as gamename (game.gamename). It appears on the title screen (when showtitle is enabled), in the version command output, and as the default transcript name.

subtitle
An optional secondary title, shown under the game name on the title screen.

author
The author’s name. Shown on the title screen (when showtitle is enabled) and by the version command.

version
A free-form version string for display (for example "1.0" or "1.2-beta"). Shown by the version command.

versioncode
A non-negative integer version number (type="int"). Use version for the human-readable label and versioncode for a number that tools and catalogues can compare. Bump versioncode whenever you publish a new release.

gameid
A unique identifier for the game, also known as an “IFID” under the Treaty of Babel. Stored as a UUID string (for example 18ad63b5-78e2-4846-872b-9177d78cc5e6). The editor creates one when you start a new game. Keep the same gameid across updates of the same game; only generate a new one if you have copied a game to create a different game. The version command displays this as the IFID.

category
A genre or category string used when listing the game (for example Fantasy, Mystery, Puzzle). The editor offers a dropdown of common values, but any string is allowed.

firstpublished
The year the game was first released, typically a four-digit year such as 2018.

cover
The filename of the cover image, relative to the game folder (for example cover.png). Recommended format is a 512×512 PNG.

description
A plain text blurb describing the game for catalogues and listings. This is not the same as an object’s description attribute (which describes a room or item in play).

difficulty (legacy)
A difficulty rating string. Typical values were Easy, Medium, Hard, and Very Hard. Removed from the editor in Quest 5.6.2; still present in some older games.

cruelty (legacy)
A Zarfian cruelty scale rating. Typical values were Merciful, Polite, Tough, Nasty, and Cruel. Removed from the editor in Quest 5.6.2; still present in some older games.

Game attributes handled by Core.aslx:

• allobjects
• appendobjectdescription
• autodescription
• autodescription_description
• autodescription_description_newline
• autodescription_youarein
• autodescription_youarein_useprefix
• autodescription_youarein_newline
• autodescription_youcango
• autodescription_youcango_newline
• autodescription_youcansee
• autodescription_youcansee_newline
• autodisplayverbs
• backgroundimage
• backgroundopacity
• clearframe
• compassdirections
• defaultbackground
• defaultfont
• defaultfontsize
• defaultforeground
• defaultlinkforeground
• defaultwebfont
• displayroomdescriptiononstart
• echohyperlinks
• enablehyperlinks
• gridmap
• languageid
• mapscale
• mapsize
• menubackground
• menuforeground
• menufont
• menufontsize
• menuhoverbackground
• menuhoverforeground
• parserignoreprefixes
• setbackgroundopacity
• showdescriptiononenter
• showhealth
• showpanes
• showscore
• start
• statusattributes
• useframe
• underlinehyperlinks

object

<object name="name">attributes</object>

Creates an object.

Objects can contain nested object definitions. In that case, all sub-objects are children of the parent object. This is how rooms work - rooms are just objects which contain other objects.

Object attributes handled by Core.aslx:

• alt
• alias
• article
• ask
• askdefault
• autoopen
• autounlock
• beforefirstenter
• canlockopen
• close
• closescript
• containerfullmessage
• contentsprefix
• dark
• darklevel
• descprefix
• description
• displayverbs
• drop
• dropmsg
• enter
• exitslistprefix
• firstenter
• gender
• give
• giveanything
• givesingle
• giveto
• givetoanything
• grid_border
• grid_bordersides
• grid_borderwidth
• grid_fill
• grid_label
• grid_length
• grid_parent_offset_auto
• grid_parent_offset_x
• grid_parent_offset_y
• grid_render
• grid_width
• hidechildren
• inventoryverbs
• isopen
• key
• lightstrength
• locked
• lockmessage
• listchildren
• listchildrenprefix
• look
• maxobjects
• nokeymessage
• objectslistprefix
• onclose
• ondrop
• onlock
• onopen
• onswitchoff
• onswitchon
• ontake
• onunlock
• open
• openscript
• parent
• picture
• pov_alias
• pov_alt
• pov_article
• pov_gender
• pov_look
• prefix
• scenery
• selfuseanything
• selfuseon
• statusattributes
• suffix
• switchedoffdesc
• switchedon
• switchedondesc
• switchoffmsg
• switchonmsg
• take
• takemsg
• transparent
• tell
• telldefault
• unlockmessage
• use
• useanything
• usedefaultprefix
• useon
• visible
• visited
• volume

Object types defined by Core.aslx:

• container
• container_base
• container_closed
• container_limited
• container_lockable
• container_open
• defaultobject
• edible
• editor_object
• editor_room
• female
• femaleplural
• male
• maleplural
• namedfemale
• namedmale
• openable
• plural
• surface
• switchable

exit

<exit alias="direction or displayed exit name" name="name" to="to room">attributes</exit>

Creates an exit from the exit’s parent room to the specified room.

The alias might be something like “east”, “north”, or the name of a room that the player can go to.

The name is optional. If no name is specified, Quest Viva will generate a name for the exit.

Attributes:

alias
string exit alias

grid_length
int length of exit line on map in grid units

grid_offset_x
X offset of exit position on grid

grid_offset_y
Y offset of exit position on grid

grid_render
see grid_render object attribute

lightstrength
see lightstrength object attribute

locked
boolean specifying if exit is locked

lockmessage
string to display when exit is locked

look
string description to print when the player looks in this direction, or script to run

lookonly
boolean - if true, the player can’t move in this direction, only look

prefix
string to print before exit name in room descriptions

script
script to run instead of moving the player

suffix
string to print after exit name in room descriptions

visible
boolean - if false, exit is not available (as if the exit’s parent was null)

walkthrough

<walkthrough name="name" > <steps>steps</steps> </walkthrough>

Defines a walkthrough with a list of steps. Each step should be on its own line.

Walkthrough elements can be nested within each other to create a hierarchy.

See Walkthroughs.

timer

<timer name="name">attributes</timer>

Timer attributes:

enabled
boolean specifying whether timer is ticking

interval
int specifying number of seconds between tick events

script
script specifying what to do when timer ticks

turnscript

<turnscript name="name">attributes</turnscript>

Turnscript attributes:

enabled
boolean specifying whether turnscript is active

script
script specifying what to do after each turn

Note that as of 5.7.2, turnscripts run in alphabetic order (in earlier versions the order could change unexpectedly). To have turnscripts in a certain order, prefix them “ts01_”, “ts02_”, … .

implied

<implied element="element" property="attribute name" type="type"/>

Specifies an implied type. For example, the “alt” attribute on an object is usually a list, so to save having to specify the type each time we can use this:

<implied element="object" property="alt" type="list">

This means we can specify an alt attribute without specifying the type:

<alt>telly; television</alt>

delegate

<delegate name="name" type="type" parameters="parameters">properties</delegate>

Only name is required; type and parameters are both optional.

Creates a delegate type. Delegates are script properties that can be called like functions. The delegate tag defines the function signature (the parameters passed to the function and its return type, if any), and then an object can provide its own implementation of the delegate function.

You can run delegate functions on objects using the rundelegate command (if the delegate does not return a value) or using the RunDelegateFunction function (for delegates that do return a value).

See Using delegates

javascript

<javascript src="filename"/>

Adds the specified Javascript file to the player interface.

editor

<editor name="name">attributes</editor>

This defines the Editor tabs and controls for a particular element type or script command.

It should have nested tab elements and control elements. “Name” is optional, but if specified it means the nested tab controls can set their parent attribute without having to be nested in the parent editor XML definition.

Attributes:

appliesto
string specifying which element type or script command this editor definition applies to

tab

<tab>attributes</tab>

This defines a tab within an editor element.

It should have nested control elements.

Attributes:

caption
string specifying the caption for the tab

control

<control>nameattributes</control>

This defines the controls within a tab element.

Attributes:

attribute
string specifying the attribute name that this control applies to

caption
string specifying the label for the control

controltype
string specifying the control type

See Script commands for your functions

resource

<resource src="filename"/>

Specifies that a particular file should be included when building a .quest package.

This is usually not required - the Packager will pick up all supported files in the same directory as the game. The only time this is required is when an additional file in the library directory is required - so this element is only intended to be used by the Core library.

inherit

<inherit name="name"/>

Within an object, type, command or exit definition, inherits properties from the specified type.

See Types.