What's New in QML2

• Overview
• Not downwards compatible changes
• Downwards compatible enhancements
• Bugfixes
• Behind the scenes changes
• Adaptions to QML-Edit
• Limitations to the Beta Versions

Overview

QML2 includes many enhancements, bugfixes and changes, some of them not downwards-compatible to QML1x. If you want to upgrade a current project (old editors and files will still be provided on this site, so you have the option not to), check on this page for changes that need to be made and convert accordingly.

In a nutshell: QML has grown since the beginning, and many concepts I didn't see in the beginning had to be added. QML2 is a (mild) language redesign. I decided it was necessary, for the first time, to make some changes that are not downwards-compatible to the old syntax, taking a fresh start. It makes the syntax much more streamlined and got rid of many "special case" constructs that only added to complexity, in writing and interpreting the syntax. Many new powerful constructs, such as state checking, push the limits further.
Thanks to everybody who pointed out bugs, and suggested enhancements! Special thanks for version 2 go out to Fred Clarke.

Not downward compatible changes

State setting

States are now set like the following:

<state name="has sword"/>

The old syntax <set state="has sword"/> won't work anymore.

I did this to streamline the syntax, since numbers and strings are set in a similar way: <number name="x" value="1" /> and <string name="y" value="test" />

State checking

State checking constructs in various elements, such as <if state=""> (and number="...", string="...", input="...") are being replaced by a single, more powerful and flexible construct:
<if check="[has sword] and [gold] = 10" />

Inline states

Inline states are now only referenced by their name, not their type. What was [number gold] in QML1 is now just [gold].

Calculations

In QML2, you have much more power to do calculations. The old concept of

<number name="gold" value="+1"/>

has now been replaced with

<number name="gold" value="[gold]+1"/>

This brings with it flexible constructs, such as:
value="[gold] * (2 + [silver]) - 1"

Inline functions

The special case constructs for e.g. inline number output has been replaced by inline functions. These are written like the following, using curly brackets:

<if check="{random 0, 100} greater 50">

Also see the inline functions overview.

Randomize

The randomize element has been replaced by states that now can be also set before an if-else element couple. What was in QML1:

<randomize number="dice" value="1 to 6"/>

Is now in QML2:

<number name="dice" value="{random 1, 6}"/>

Information station

The information station is not supported anymore (this includes style settings for it). It can be completely replaced by the more flexible station inclusions.

XSLT link

The link to the XSLT conversion file has been taken out.

Folder rename

The folder "story" has been renamed to "quest". (Much more QML files than I expected actually aren't stories, but resemble more or a trivia quiz or other games.)

Changes in the HTML

The HTML file to run the Client-side version of QML has changed in multiple ways. You can use the sample files as reference when converting your existing files.

Components

User-scripted components have been removed. However, you could still create your own inline functions using the new syntax.

Input

QML2 has a new input syntax. (Inputs are used to get a text to be entered by the player.)

<station id="unicorn">
<text>
"Do you know what I am?" she asks you.
<break/>
<emphasis>What do you answer?</emphasis>
</text>
<input station="unicorn answer">OK</input>
<choice station="back">You don't answer and
        leave</choice>
</station>

<station id="unicorn answer">
<if check="[qmlInput] = 'unicorn'">
<text>"Oh, you do know me!" she cries.
</text>
<state name="knows unicorn"/>
<choice station="unicorn continue">Continue</choice>
</if>
<else>
<text>"So that's what you take me for?" she sighs.
</text>
<choice station="unicorn continue">Continue</choice>
</else>
</station>

This format is more flexible and intuitive. Instead of a choice link, the input element will simply put out a little text-box with a button next to it. In both client- and server version. (Via CSS, the button can be styled to look like a link.)
The author can include elaborate texts, with images and formatting, instead of a reduced question like now. Also, there can be multiple text-inputs, combined with multiple additional choices.

Cover station

The virtual cover station is not used anymore. You can create your own, more personalized cover stations using style classes.

QML encoding

QML files cannot be automatically encoded/ decoded anymore. (There is not much need for that anymore since the Server-side interpreter now has the full functionality of the Client-side version.)

Downward compatible enhancements

Flexible naming scheme for stations and states

Station names, as well as all variable naming (boolean states, numbers and strings) now allow spaces.

Flexible state setting

You can include state setting elements, such as <number name="x" value="1"/> right into choices.
Example:

<station id="start">
<text>
<emphasis>How much you want to bet?</emphasis>
</text>
<choice station="bet">
    2 gold coins and 3 silver coins
    <number name="gold" value="2"/>
    <number name="silver" value="3"/>
</choice>
<choice station="bet">
    4 gold coins
    <number name="gold" value="4"/>
</choice>
</station>

Debugging Server-side QML

Server side QML now supports the debugging features that were in QML1 only provided with the Client-side version.

More output formats

Output can include plain text, XML, and XHTML (the default). To request e.g. XML, you use the following URL:
http://host/default.asp?quest=test.xml&contentType=XML

User input

User input is now also supported in the Server-side version of the QML-interpreter.

Bugfixes

The following things didn't work as intended in QML1x and have been fixed:

• States are kept when switching chapters
• Choose works with back, as well as with inline values

Behind the scenes changes

Several changes are not directly expressed in the syntax. But large portions of the code to interprete QML has changed (higher encapsulation using classes, for one thing), and so certain different run-time behaviors — like speed — can be expected.

In short, Server- and Client-version of the QML interpreter are much closer connected now in terms of memory management (state memory is now itself held in XML). This results in a much faster and stable Server version. Now you can even change the Quest-XML file while still running the game, and simply reload the current station to see your changes become active (true for both Server- and Client-side QML).

Also, ASP session-handling in the server version has been replaced. The result is that the client browsing device doesn't need to have HTTP cookies enabled. Session IDs are now encoded within the URL itself to allow for more flexibility with end devices (such as mobile phones).

Adaptions to QML-Edit

QML-Edit 2 adapts to the changes in the QML syntax. E.g., the style tab for the deprecated information station is missing. Another change is that I got rid of the collapsable Syntax module at the right side of the Source editing tab. This has been replaced with both a better navigation to the offline help, and a context-sensitive state completion functionality. (If you type "[", you're presented with a list of all states in the current quest.)
Also, the Print view functionality has been rewritten and is now much better.

Limitations to the Beta Version

Currently, session data in the QML-Server version interpreter is saved to disk (/tool/session/*.xml), but older files are not yet removed. I'm planning on including a time-out of 48 hours in the next release.
Client-side saving has been removed completely for the moment until I find a more satisfying solution (QML1x uses keyboard events and cookies).