QuestML Language Reference

QuestML is the language which is used to create StoryQuest stories. The author has to provide the story's text in QuestML format. QuestML is based on Markdown, which is a lightweight format for adding markup to plain text. QuestML adds some simple commands in a common format to Markdown to enable authors to interact with StoryQuest's internal services.

Basic Terms

Station Nodes

A "station" or "station node" is a single node in the story tree. A station ususally has some text attached. Think of a station as the "chapter" in a common adventure book. As this, a station has some metadata associated with it: the station id is equivalent to the chapter number (and is also used in "links") and possibly other data like style of text display, colors, fonts, and other data.

Links

Links are the "binding elements" that lead from one station to other stations. In an adventure book, the player will "jump" to other chapters at the end of one chapter. These "jumps" are conditional, either by choice of the player or by other conditions, like "you can use this path if you have the sword". This concept is also present in StoryQuest and QuestML in the form of "links".

Statements

QuestML is basically a text only format. Authors write their story in plain text. They can use some markup to style text. For example, to style a text in italics, enclose it with "*". More on the possible markup below. In addition to the text markup (which follows the "Markdown" concept), QuestML also contains "statements" that can be used to tap into the internals of the StoryQuest system. With statements, you can "remember" choices, remember values or create advanced formatting for text. It is also possible to do advanced scripting, like getting a random value inside the text or even let the player do some input (for example, a character's name) and refer to it later in the text. With statements, it is possible to let the player enter his name and all people in the book can directly address the player by his name. It is also possible to play sounds or video from statements and, for example, create a dynamic weather system that plays rainfall sounds when it is applicable.

Variables

Variables are named values that can change. With variables, a story can remember values like the name of the player, or the numeric value of a sword.

Flags

Flags are special variables, that can only hold a boolean value: "true" or "false". So a flag can either be "set" or "not set". Authors can use flags as a shorthand to remember values like "the player has already visited this place".

Markup Reference

QuestML contains some lightweight markup to enable light styling on the text. The used markup is based on Markdown and most of the syntax can be used inside of a QuestML document. The following section only describes the most commonly markup used in StoryQuest books. Please refer to the Markdown syntax guide for more details.

Headlines

Headlines can be created with lines starting with "#". The count of "#" at the beginning of the line determines the level of headline:

## This would be a second level headline

Headlines are converted into HTML while displaying the chapter in the StoryQuest app. Styling can be achieved by creating rules in the CSS styling document inside the StoryQuest project.

Emphasis

Emphasis highlights a phrase inside a paragraph. In the default styling, emphasised text would appear in italics. To emphasis a phrase, enclose it with "*":

In this sentence, *this part* would be in italics.

As ususal, the actual styling can be changed in the CSS document.

Strong Text

Strong text works the same as emphasised text, but with a different styling in the output. In the default styling, strong text would be displayed in bold font and must be enclosed with "**":

In this sentence, **this part** would be in bold.

As ususal, the actual styling can be changed in the CSS document.

Statement Reference

The following describes all currently available statement types.

Links

Links provide a way to link from one station to another station. They represent one of the basic building blocks for branching text. To add a link to the text, add the following statement:

{link(targetStationId, flagName, isVisible, isEnabled):choiceText}

with the following parameters:

• targetStationId: the id of the station node to be linked to.
• flagName (optional): if this is set, the flag named "flagName" is set to true when the player touches the button (in addition to switching to the new station node).
• isVisible (optional): this can be "true", "false" or a flag name. If the value is "true" or a given flag name is evaluated to "true" (either the flag being set or a value with the same name is set to something not empty), the link is shown. Otherwise the link is not shown.
• isEnabled (optional): this can be "true", "false" or a flag name. If the value is "true" or a given flag name is evaluated to "true" (either the flag being set or a value with the same name is set to something not empty), the link is active. Otherwise the link is visible but disabled.

Examples

{link(the_temple, hasVisitedTheTemple, true, hasTheChalice):You have the chalice, you can enter the temple.}

{link(003):Go to 003}

{ilink(002, someKey, true, true):consectetuer}

Inline Links

Examples

Switch Buttons

Images

Examples

{image(center):image-square.jpg}

Boxes

Examples

` {box(left):

Donec pede justo, fringilla vel, aliquet nec, vulputate eget, arcu.

In enim justo, rhoncus ut, imperdiet a, venenatis vitae, justo. Nullam dictum felis eu pede mollis pretium. Integer tincidunt. Cras dapibus. Vivamus elementum semper nisi. } `

Flags, Variables and Scripting

Examples

{set(42):someKey} {set:someOtherKey} {someKey}

Lists

Examples

Conditions

Examples

{when(<"true" or flag>):someKey ist true}

Whishlist

• Choices only usable once.
• "Silent choices", content will be "included" seamlessly, possibly with a condition.
• Lists with empty elements
• Nested lists