QML - Create Your Own Adventure

QL

QL, the Quest Language, is a simplified text-based format for QML that can be used optionally. It is not XML and has to be converted to QML before the QML-interpreters can parse it.

Text based QL is interpreted by ASP/ VBScript and Visual Basic. QML is interpreted by ASP/ VBScript, Python and PHP. QL can be converted to QML, and vice versa. Finally QML is converted to XML based and HTML compatible XHTML, which can be interpreted for different media, like print, or text-to-speech.

The QL file (with the extension .ql) is put in the quest folder of the QML-Package (see download page). The following is a simple example:

"Simple sample", Philipp Lenssen

start
    ---
        There's a treasure chest here, and
        a door leads to the north.

    --> open chest ? not [chest open]
        Open the treasure chest

    --> northern path
        Leave the room

open chest
    ---
        You open the chest and take two
        silver coins.

    _ chest open
    % silver = [silver] + 2

    <--
        Continue

northern path
    ---
        You walk a bit, get tired, go to
        sleep & dream about your [silver] silver coins.
        *The End*

Syntax explained

QL is very strict when it comes to indention. Use 4 spaces to create a new indention. (Vertical space -- like a double return -- has no effect and can be used independent of scopes.)
E.g. when you create a text section, you first have to indent once to have it belong to the current station, then write "---", and on the new line indent twice to make the text belong to this block.

Purpose QL Syntax
About the quest "Untitled", Anonymous
Station
Station my station
Comment (ignored) //
Comment (kept in QML) -//
Include +++
Text
Text ---
Text with class --- surprise
Text with class & check --- shop ? [has gold]
Emphasis  *my text* 
Strong emphasis  **my text** 
Break ||
States
State _ my name
Number % my number = 10
String $ my string = Hello World
Outputting values [my value]
Branching
If ?
Else ...
NOT (in check) !
Choice --> my station
    Continue
Choice with check --> my station ? [has key]
    Continue
Choice back <--
    Go back
Choose ->>
Media
Image ( my_image.gif )
Music ( my_music.mid )
Embed ( http://questml.com )

Converting to QML

Currently, there's a QML-Edit import function as well as an ASP-based converter script. I might add additional support (it could be translated on-the-fly by QML-interpreters).

QML-Edit: Click on import and choose a QL file.

ASP: You can see a translated output by running
/script/convert.asp?quest=battle
on your Windows Server (PWS/ IIS) -- "battle.ql" must be located in the "quest" folder for this example.

QML result

The above simple sample in QML after the QL-Converter translated it:

<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE quest SYSTEM "../script/quest.dtd">
<quest>

<about>
    <title>Simple sample</title>
    <author>Philipp Lenssen</author>
</about>

<station id="start">
    <text>        
        There's a treasure chest here, and
        a door leads to the north.
    </text>
    <choice station="open chest" check="not [chest open]">
        Open the treasure chest
    </choice>
    <choice station="northern path">Leave the room
    </choice>
</station>

<station id="open chest">
    <text>        
        You open the chest and take two
        silver coins.
    </text>
    <state name="chest open" value="true"/>
    <number name="silver" value="[silver] + 2"/>
    <choice station="back">Continue
    </choice>
</station>

<station id="norther path">
    <text>        
        You walk a bit, get tired, go to
        sleep &amp; dream about your [silver] silver
        coins.
        <emphasis>The End</emphasis>
    </text>
</station>

</quest>

QML to QL

To convert QML back to QL, use the following on your Windows Server:
/script/convert.asp?quest=battle&output=ql&preview=true
("battle.qml" must be located in the "quest" folder for this example.)

Battle sample in QL

This is a simple battle system. The QML version and an explanation can be found in Practical examples:

"Battle sample", Philipp Lenssen
// Being a sample of QL

start
    ---
        There's a big monster in front of you
        blocking the path.
        *This could be dangerous!*

    ( monkey.gif )

    % player skill = 10
    % player stamina = 10

    % enemy skill = 10
    % enemy stamina = 10

    $ after win = new path

    --> battle
        Let's start the battle

battle
    -// This battle functionality can be reused

    % player power = [player skill] + {random 2, 12}
    % enemy power = [enemy skill] + {random 2, 12}

    ? [player power] = [enemy power]
        ---
            Both of your swords miss the other.
            Stamina stays the same.
        --> battle
            Battle again
    ? [player power] > [enemy power]
        ---
            You hit the enemy and wound him.
        % enemy stamina = [enemy stamina] - 2
        --> battle result
            Continue
    ...
        ---
            The enemy hits you and it hurts.
        % player stamina = [player stamina] - 2
        --> battle result
            Continue

battle result
    ? [player stamina] lower 1
        ---
            The enemy wounds you deadly.
            **Game over.**
    ? [enemy stamina] lower 1
        ---
            You kill the enemy.
            You can continue your game.
        --> [after win]
            You continue
    ...
        ---
            Both of you are still standing.
            Your Stamina is [player stamina], the
            enemy stamina is [enemy stamina].
        --> battle
            Battle again

new path
    ---
        You're on a new path, leaving the monster behind
        you... ||
        *This is just the beginning of the quest,
        but this sample is over.*