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. If not given, the link is 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. If not given, the link is active.
• choiceText: the text displayed on the choice button.

Examples

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

If the flag "hasTheChalice" is true, the choice is active and can be touched. It is visible, because the "isVisible" is set to "true". When a player chooses this link, the flag "hasVisitedTheTemple" will be set to "true" and the book jumps to the station "the_temple". The button text is "You have the chalice, you can enter the temple.".

{link(deeper_into_the_woods):Continue your path}

This is a simple link with no additional parameters, it simply displays a link button "Continue your path" which jumps to station "deeper_into_the_woods".

Inline Links

Links are always displayed as blocks and are treated as a seperate paragraph. To create inline links that are embedded into flowing text, the "ilink" statement can be used:

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

The ilink has the same parameters as the link statement and the same functionality. The only difference is, that ilinks can be stated inside of paragraphs, like links on websites. The statement has 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. If not given, the link is 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. If not given, the link is active.
• choiceText: the text displayed as the choice text.

Switch Buttons

In some cases, authors might create a possible decision for the player that does not have a necessary direct response in form of text. For example, if a player has the option to pick up an item, it might not be needed to create a new station just for storing the fact that he chose to pick up the item. In this case, it might be enough to just set a flag "hasPickedUpItemX" and remain on that station. The "button" statement enables autors to create switch buttons like this:

{button(flagName, isVisible, isEnabled):buttonText}

with the following parameters:

• flagName: the flag named "flagName" is set to true when the player touches the button.
• 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 button is shown. Otherwise the button is not shown. If not given, the button is 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 button is active. Otherwise the button is visible but disabled. If not given, the button is active.
• buttonText: the text displayed on the button.

Images

Images can be added to the text with an attached styling parameter. This parameter will become the CSS class when the text is rendered inside the StoryQuest app:

{image(cssStylingClass):imageName}

with the following parameters:

• cssStylingClass: the CSS class attached to the image for rendering the text display.
• imageName: the filename of the image.

The default styling includes some simple image style options, more can be added by editing the CSS document:

• left: left aligned image with text flowing around.
• center: centered and scaled to full width.
• right: right aligned image with text flowing around.

Examples

{image(left):someimage.jpg}

Displays an image "someimage.jpg" (uploaded using the "Media" tab in the editor) left aligned, with text flowing around.

Boxes

Boxes contain small excerpts of texts that are detached from the main text. Examples are description of terms or "intermissions". Boxes have an attached styling parameter. This parameter will become the CSS class when the box is rendered inside the StoryQuest app:

{box(cssStylingClass):TextContent}

Box contents can span multiple lines and can also contain Markdown markup. The default styling includes some simple box style options, more can be added by editing the CSS document:

• left: left aligned box with text flowing around.
• center: centered and scaled to full width.
• right: right aligned box with text flowing around.

Examples

` {box(left):

This is a headline

This is an example text. It can span multiple lines. } `

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