Markup Based Story Scripting

The following page describes the syntax of the Story Script used in the MicaByte Story Engine. It is based on Markdown, and heavily inspired by the Ficdown and Squiffy interactive fiction tools.

Story is the definition of the story itself. Heading level 1 is used to define the story itself. Each file must define exactly one story.
Scenes are the main unit of the story. Moving to a new scene deactivates any links/actions in previous scenes (and may clear the screen). Heading level 2 is used to define a scene.
Passages are smaller units of text which occur within a scene. Linking to a passage will display the text from the passage, but other links in the section will remain active. Heading level 3 is used to define a passage.

# [Story Title](/first-scene)

Heading level 1 is used to define the story itself. The story title should be an anchor that links to the first scene.

## First Scene

Heading level 2 is used to define the scene.

### A passage

A passage is a line of text that is shown when a link is clicked, but which does not change the scene.

Scenes are referenced by a sanitized version of their names; all non-word characters are removed, and spaces are replaced with hyphens (except the last space). Names can be truncated to 16 characters; so e.g. "a very long and convoluted scene name" can be referenced as "a-very-long-and".

Links

Each scene makes up a single page of text in the game that is ended with at least one link for the player to select. There must be a minimum of one link in each scene, because otherwise the player is going to get stuck in the game interface. Links in Story Script are defined using the inline style.

[This is Text](/this-is-the-link)

Links can be used to travel between scenes. We use a list syntax to create a list of links at the end of each scene.

## Second Scene

This is scene number two.

What would you like to do?

- [Go back to the first scene](/first-scene)
- [Repeat this one](/second-scene)

Markdown allows links anywhere in the text, but in the context of the Story Engine, links must be defined as a list at the end of the scene. This is primarily due to limitations in the Android game engine (though it also simplifies security not having to block http).

A link to a passage disappears after that passage has been shown. It returns if you return to the scene later.

Section and passage names are only unique within their story or section. To link to a scene or passage from a separate story (possible within the Story Engine), use a nested link. For example:

- [Link from another place](/story-title/first-scene/a-passage)

Advanced Link Syntax

The link syntax is not just used to connect one scene or passage with another, though; it can be used to perform a variety of useful manipulation.

Basic link syntax; linking to a story, scene or passage (designated by a backslash):

- [Option 1](/scene-link)

The link syntax can also be used to display text conditionally, dependent on the value of a variable or expression. This is denoted using a question mark, as follows.

[Option 0|Option 1|Option 2](?$picked-up-key)

Resolution is very simply "count" based; if $picked-up-key evaluates to 0 or less, "Option 0" is shown, if it evaluates to 1, "Option 1" and for values of 2 or more, "Option 2" is shown. Boolean false evaluates to 0, while Boolean true evaluates to 1.

If no variable is specified (as in the following example), then one of the options is picked randomly.

[Option 0|Option 1|Option 2](?)

It can be an action (designated by @):

- [Option 4|Option5](@set picked-up-key)

It can also be a combination of all three (or two).

- [Option 6|Option7](/new-scene?first-condition&second-condition@set $first-variable =100 @set $second-variable=200)

Text

Text in the Story scripts is just text. Like this one. Paragraphs are separated by blank lines.

Text can be beautified, using the basic markdown tags.

 
*This text will be italic*

**This text will be bold**

Variables

Variables in the Story Script are always prefixed $. They can be inserted directly in the text, and the parser will try - as best it can - to translate the variable to a meaningful text string (e.g., an integer variable gets converted to the number it represents, a string will be replaced by the actual string, etc).

Variables can also be objects in the Story Engine, in which case dot notation can be used to extract more detailed information; e.g.

$object.attribute

Actions can be performed using the @ to set, unset, and otherwise manipulate variables.

Set attribute inside text:

@set $variable = 1000

Unset attribute

@uns $variable

Increase and decrease number values

@inc $number1
@dec $number2

Also:

@set $variable += 1
@set $variable = $variable + 1
@set $variable -= 2
@set $variable = $variable - 2
@set $variable *= 3
@set $variable = $variable * 3
@set $variable /= 4
@set $variable = $variable / 4

Random numbers:

%Random number between 0 and 10 (both inclusive)
@set $variable ~ 0 10

%Standard d6:
@set $variable ~ 1 6

%Random number from 0 to 10 (both inclusive), increment of 2
@set $variable ~ 0 10 2

Calls to internal code

@act do_something

Conditional

StoryScript allows conditional evaluation of entire blocks of script using the @if, @elif, @else evaluation

@if $gender = male
You are a man.
@elif $gender=female
You are a woman.
@else
None of your business.
@endif

Each block is implicitly its own paragraph. Note that the if-then-else block must always be closed with an @endif statement. You cannot nest one @if statement within another @if statement.

Text Manipulation

%Switch randomly between the various text entries:

[TEXT0|TEXT1|TEXT2|...](?)

%Select a text based on the value of the variable:

[TEXT0|TEXT1|TEXT2|...](?$variable)

Images

Background image

![bkg](image-uri)

Overlay images (used for visual novel style compositions):

Centered

![gfx](image-uri)

Centered

![gfx](image-uri)

Centered

![gfx](image-uri)

Comments

Any line starting on % will be ignored by the parser.