Markup Based Story Scripting

The following page describes some ideas for a scripting language for writing interactive text narratives based on Markdown. The script language described here is inspired by Ficdown and Squiffy in addition to ideas and constructs from my own "StoryEngine".

Text

Paragraphs have no special markup. Paragraphs are separated by blank lines.

Emphasis

 
*This text will be italic*

**This text will be bold**

Story, Scenes, and Passages

# [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. 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-".

Linking Scenes

Links can be used to travel between scenes. Lists are used to create a list of links at the bottom of a 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)

From the point of view of my game engine, a list of links at the end is the best way to handle this; but in theory there is no reason why such links could not be embedded anywhere in the text.

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.

It should be possible to link across multiple stories. For example:

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

Links can be one of three different possibilities:

Link to a story, scene or passage:

- [Option 1](/scene-link)

It can be a conditional:

- [Option 2|Option3](?picked-up-key)

It can be an action:

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

It can also be a combination of all three.

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

Attributes

Attributes are always prefixed with $.

Attributes can be objects, in which case dot notation can be used; e.g.

$object.attribute

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

{if $gender=male | You are a man.}
{elif $gender=female | You are a woman.}
{else You are non-gendered.}

This can be extended over multiple lines and include other constructs.

{if $gender=male | 

You are a man.

}
{elif $gender=female |
You are a woman.
}
{else 
You are non-gendered.

@act set_nongendered
}

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.