QML - Create Your Own Adventure


Here's a first station with the id "start". This is the default station to begin with (you can use a different one).

A very simple station with just a bit of text:

<station id="start">
    <text>Welcome to the adventure. Which is over now, since there are no paths away from this station.

The station has a unique ID: never take the same ID for several stations. You may use spaces in the ID.
The text element inside the station is the text the user will read. There are no choices to continue here, so the adventure would be over. Always use at least one choice to continue, unless you want the station to be the last! (When the player dies, you might want to suggest to reload the game to play again.)

Here is a more complete station, with some choices, and also an image:

<station id="start">
<image source="room.gif" default="true" />

    You're home.<break />
    You can see a backyard and a TV. And a small, <emphasis>silver treasure chest</emphasis>. There's also a book called "XML in 21 Days". </text>

    <choice station="backyard"> You go to the backyard </choice>
    <choice station="treasure"> You open the treasure </choice>
    <choice station="tv"> You go to the TV </choice>
    <choice station="book"> You open the book on a page     </choice>

To link back to the last station, use "back" as station name.

All the formatting regarding spaces is purely a matter of tutorial readability! In a real QML file, you might not want to indent at all. Just remember to never leave an element (a "tag") open, or if it is a single element, close it like the image above with an additional "<... />"

Text formatting

In the example above, there was some use of formatting that actually shows up when the player reads the text: the break will break the text at that part and continue in the next line. To have a stronger break, use the optional attribute type with the value "strong" (instead of "normal"). emphasis will put emphasis on a word: typically, this means the font will be rendered italic.
Other elements are display (for a pub sign, a book title, a computer screen etc.) and poem (for poems). Using poem around multiple lines saves you putting <break /> at the end of every line.


You may want to comment on a station. This is information the player won't see, but it might be helpful for yourself (or anybody reading the source) to understand/ remember why you did something in a certain way.
A comment is put at the start of a station, enclosed in <comment>...</comment>.

(An alternative way for comments everywhere throughout the QML document is to use <!-- this is a comment -->)


A choice is some text that is displayed as a link the user can follow. It's like a path to a new location, or like a certain action within a location. (Something the player says, takes, etc.) The number of choices is theoretically unlimited.

Here's the attributes a "choice" can have:

<choice station="(id of station)"
    state="(name of state)"
    number="(name of number)"
    is="('true' | 'false')"
    relation="('and' | 'or')"

The attribute station of a choice element must be used and contains the ID-value of the station you want the choice to lead to. Many choices can lead to the same station.
State, number, chance, is and relation are all optional attributes related to states discussed later on. If the value is false, the link will not show up.
The Text is the text-line that will be displayed as link to the station.


You can include a station in many others automatically.

<station id="dog">
    <include state="not dog ran away">
        <in station="backyard*" process="after"/>
    <text>A dog is walking by your side.</text>

This will "merge" this station's text and choices with any other station with an id starting with "backyard".
You can process the include after, before, or exclusive (relative to the other station). You can use multiple include commands in a single station (always at the top) plus multiple "in" elements in each include. Both can have state and variable checking (more on that in the chapter on states).

Continue with QML Media