QML - Create Your Own Adventure

FAQ: Frequently Asked Questions

This document in german

What is QML?

QML is a language to define station-based text-adventures, like you find them in some interactive books where you can choose your own adventure.

What does it do?

QML handles stations, choices, states (like certain events in the game history). You can include image and music. There's numbers, strings, image maps, automatic forwarding, if-else branching, and more.

What do I need to get started?

All you need to do is to install QML-Edit (7MB). It comes with a help which should answer further questions.

Do I need to be a programmer?

No. It helps if you like to learn a thing or two about programming, but you don't have to for very straight-forward adventures.

Do I need to pay anything?

No, everything concerning QML is free.

Program/ browser

Can the game be played from an executable?

It's very easy to make an executable using the Internet Explorer control in Visual Basic. One could then compile to have a self-executable that runs the game without the user having to start an HTML file. However, the good thing about the browser is that people already know it and trust it. Some are actually more reluctant to start executables, especially if they downloaded them from the World Wide Web. QML is suited for online play and that will introduce the least hassle for users.

Can the game be started in a new window without menu bar etc.?

You can link to the starting HTML file any way you want, and you could create a popup window for that with JavaScript. If you distribute the game for offline play, this is ok. Online however, many people don't like it when that happens.

How do browser buttons work with QML?

If the game is played on the client (IE5), the Back button won't take the player to the last station (but the page he visited before the quest), and the Reload button won't reload the current station (but instead, the whole quest).
You can however use <choice station="back">...</choice> to send the player to the last visited station.

If the game is played on the server, the back button will take the player to the last station. However, when the game is over (when there was a station without any choices), choosing a new path from older station will result in a text being displayed, telling the player that the quest is over (for the time being, this is only true in QML1x).

Technical issues

What is XML?

XML means eXtensible Markup Language. It is an industry-wide standard for data exchange. The W3C (World Wide Web Consortium) introduces such standards to make it easier for different systems/ people/ parser to use the same data structure. This page for example uses XHTML, which is held in XML.
For more informations, see Introducing XML on this site or XML in 10 points by the W3C.

How does the QML interpreter work?

The XML file is loaded with VBScript and validated against the Quest DTD (Document Type Definition). This means when there is no script error on load, the file is valid QML syntax. All parsing is done through the DOM (Document Object Model) of the Microsoft.XMLDOM object. Each station is dynamically written to the browser window. Clicking a link will call a VBS function that will output another station and handle states, user input, etc.

How does the QML-Edit program work?

The MSXML parser is used to handle a Quest-object. Any editing is done to it in memory. There's a lot of form-controls (like input areas) to XML conversion, and vice versa. If you save or chose the preview mode, the HTML files are saved to disk. Preview mode is just an IE browser control, the rest is handled by the client-side VBS routines.


Can I use animations?

You can use GIF animations. Note however that animations (as well as all images, sounds...) can be turned off in the browser options.

My story seems to load slowly. Can I speed it up?

If the game loads too slowly, you can try to:

Can I display states, numbers and the station name?

Yes, if the quest attribute debug is set to value "true".


Are there restrictions to the story size?

There are no restrictions whatsoever. You should however break the story up in multiple chapters (XML files) to make for faster loading.

Do I have to use images and sounds?

No, these are purely optional.

Is the setting restricted to fantasy adventures?

Most of the CYOA books are fantasy stories in which the player takes up the role of a wizard or warrior. But you can do whatever story you want in any genre. It doesn't even need to be an adventure: you could do a technical support system in an Intranet, for example. Or a casino game, without any plot.

Does all text have to be english?

No, you can write adventures in other languages.


Which files have to be included in the distribution?

You can use QML-Edit's File -> Export function to easily create a distributable package.

Which files can be altered to change the functionality?

You should not alter any Script (*.js, *.vbs) or Document Type Definition (*.dtd) of the QML package and redistribute it under my name. (If you find a bug, please let me know.)
However, you are encouraged to come up with your own interpreter for the Quest Markup Language for other systems.

Can I sell my adventures?

You are allowed to do whatever you want with your adventures. You can include all files necessary to play the game. You can copyright the story XML file on your name. However, you may not sell the QML system itself, as it belongs to the public domain.