QML - Create Your Own Adventure


A state is a a logical flag that describes a certain situation in your adventure. A state could be "has key", meaning if it's true, the player has a key, if it's false, the player has no key. All states are false by default unless you set them. You do that by writing (in a station, after the text):

<state name="(name of state)"
    value="('true'|'false')" />

The name of the state has to be given, whereas the value of attribute value is optional (and defaults to true). Here's a list of possible states (states are not case-sensitive):

Try to avoid the past tense, since the state may change again; ie., "took magic statue" is not as useful as "has magic statue", since maybe the magic statue will be put back, be thrown away, be given to someone etc., and in that case you would want to reflect that by setting the state back to false.
However if there's the chance to get back to the original place, you have to make sure not to make the statue "appear" there again! In that case, you'd use an additional state of for example "treasure chest is empty" which you'd check again.

Now once you set a state, you can check for it in a station:

<station id="treasure">
    <if check="[has gold]">
        <text>You open the treasure, but it's empty.
        <choice station="back">You go back</choice>
        <text>You open the treasure and find some gold.
        <set state="has gold" />
        <choice station="back">You go back</choice>

In this example, everything surrounded by the if will be shown if the state is true (or false, if is would have been set to false).
Everything surrounded by else will be shown if the above state is false.

As you can see, to check the value you need to wrap it in square brackets. You can combine several states by using e.g.:
"[has gold] and not [has sword]"

Automatic redirection

In each if or else you can use an automatic station redirect. This is useful if a single station can be accessed from many stations which check a different state. For example, the player has the option to attack a wizard, the player can choose from 3 different weapons: each successful attack brings another text, but each unsuccessful attack redirects to the same description of the wizard being too powerful.
Use a single
<choose station="wizardIsTooPowerful" />
(without any additional attributes).

Processing states

By default, a state will processed before the text is displayed. To handle the value assignment after the output is generated, use attribute process="after" within the state.

The following example processes a state after the text is displayed. It also makes use of directly putting the state in the text element.

<station id="dragon cave">
<text check="not [saw dragon]">
You're a proud knight in a land full of dragons.
The medieval world being the dark place it is,
you have no choice but to fight.
<text>There's a dragon here.
<state name="saw dragon" process="after" />
<choice station="dragon cave">Attack the dragon</choice>

If this station is visited for the second time, the reader will only see the short version displayed, since "saw dragon" is now set to true.

You can use the special number "visit()" discussed later on to more easily check the visits to a station.

Continue with States Part 2