Stage Export to Ink

Converts a Recital .stage file into an Ink file, which can then be consumed by any Ink parser to make interactive narratives.

Usage

CLI

stage-ink input-file.stage -o outputfile.ink

	Options:
		-v - outputs version number
		-o - output file (otherwise goes to stdout)
		-s - adds stats metadata to the ink file

In JS

const stageToInk = require('@a-morphous/recital-stage-ink')

const defaultOpts = {
	sceneToStartOn: 'name-of-scene',
	addStats: false,
}

return stageToInk(fs.readFileSync('input-file.stage', 'utf-8'), defaultOpts)

Basic Syntax

Follows Recital when possible

Scenes are converted into knots, and Recital fragments into stitches.

Specific metadata are converted into tags, and the rest wrapped up into a JSON object as a META tag, which can be parsed later.

Meta tag rules are:

• top-level keys are listed in all-caps, followed by : and the value
• any nested content is converted into JSON and fit on one line.
• any newlines get broken up, and put onto another tag with the same key

For example, the meta

#: passage
+++
title="Title"
list = ["one", "two", "three"]
description="This is a line
with a newline"
[map]
test="foo"
+++

should convert into

=== passage ===
# TITLE: "Title"
# LIST: ["one", "two", "three"]
# DESCRIPTION: "This is a line
# DESCRIPTION: with a newline"
# MAP: { test: "foo" }

all JSON will be without any newlines.

To get the meta back, read the tags and use JSON.parse() on the values.

Choices

Choices are created as wikilinks, with the double bracket [[]], with the id of the scene or fragment after the displayed text linked with -> (note that this is exactly how Twine's Chapbook does its links), e.g. [[This is a link text->Scene Name]]

By default, they are also prepended with a > , though you can omit them for top-level choices. (However, you cannot omit them if you want to have any modifiers onto your choice)

The > can have a character or more after it to modify the choice:

>! Makes the choice 'loud', meaning that the choice displays again in the response (note that this is Ink's default)

>+ Sticky choices are not hidden when chosen (if we loop back to a previous knot)

>. are fallback choices, and don't get displayed normally, only showing up if all other choices have been exhausted.

>!+ you can combine sticky and loud choices.

Diverts

...are used totally normally, since they don't need to be converted to anything else.

Put a -> in normal text to produce a divert.

Auto-slugifying diverts

Since Recital is less strict about the titles of scenes than Ink is, all diverts are slugified, or turned into ink-compatible forms, when compiling.

This means that knots, stitches, and diverts are all:

• Converted to lowercase
• stripped of non alpha-numeric characters
• spaces get turned into underscores

This also means that, functionally, name_of_knot and name of knot will point to the same knot.

However, this also means that there are a few gotchas:

Diverting to different stitches

Ink's syntax for diverting to a stitch for a different knot is as follows:

-> knot.stitch

. symbols are not allowed as Ink titles, so the conversion process will get rid of the . if there are any in the knot or stitch title. However, since we need . characters to remain consistent in the divert itself, the auto-conversion in diverts will not strip . characters, unless they're at the end of the knot title. So this:

-> Title with. a period in it.
#: Title with. a period in it.

...will fail, since the knot will slugify to title_with_a_period_in_it, and the divert will slugify to title_with.a_period_in_it.

Diverts as variables

Ink allows you to store a divert in a variable, and then divert to that variable later to go to the knot or stitch specified.

However, stage-ink's auto-slugify feature might cause the variable name to be changed in the divert, which will break the story.

To avoid this, you can escape hatch the slugifying process. Any string that begins with $ will not be changed except for stripping out the leading $ in a divert or knot or stitch title. So, to make sure that your variable diverts are untouched, you can do

VAR current_scene = ->name of scene
-> $current_scene

Weaves

AKA nested content.

Weaves are created when a choice doesn't have a divert in it, and instead has text afterwards. By default, > is considered the top-level weave.

Every level of weaves adds an extra bracket. > is the top-level, >> is the second level, and you can continue nesting them.

Gathers are created via prepending the line with <. Nested gathers add more brackets, e.g. <<.

To nest weaves, ink has you create multiple * marks. Recital instead nests > and < symbols. A nested choice looks like >> [[this is a nested choice]]

Glue

Glue at the end of a line can be written as normal; Ink uses <>:

This is glued <>
to the next line.

However, you can't use this form to write glue at the beginning of a line, since <> is also used to define fragments. In that case, you use $<> to denote it as glue:

This is glued
$<>
like so.

(You can use $<> in a line too, if you want. E.g. This is glued $<>.)

Tunnels

Tunnels are written as they are in Ink: with a divert that ends in ->, and then in the tunnel, with a double divert that has no endpoint ->->.

The parser expects the divert after a tunnel to be on its own line. It probably works if it isn't, but will skip other parsing of that line.

Tunnels are auto-slugified like other diverts.

Basic Example

See the /test/data/kitchen-sink.stage for up to date versions.

Recital File:

#: title
+++
meta="This is some metadata"
title="Title"
+++

This is a passage.

> [[Choice]]
	This is the aftermath of that.

> [[Choice2]]
	This is the syntax for weaves.

>! This is the syntax for Weaves.

< gather the choices. No matter what you choose you end up here.

  >> [[Nested Choice 1]]
  >> [[Nested Choice 2]]

  << nested gather.

> [[Another Choice->divert]]
> [[Last Choice]]
	You can use ink diverts normally, since they don't need to be converted.
	-> divert
< This works, right?
This is a passage.
>! [[Loud choices are displayed again in the answer.]]
	Aftermath 1.
	
>+ [[Sticky choices are not hidden when chosen.]]
	Aftermath 2.
	
>. [[Fallback choice with text.]]

< Gather it all up.

>!+ [[You can combine all of those. For nested, the extra symbols go after the `>`]]
	-> fragments start stitches

<> fragments start stitches

Final content
END

<> divert

Hmmm.
END

Storylets

Ink doesn't natively support storylets, but this exporter will produce tags and metadata to help mark passages for storylets, for use in engines further down the line.

How are Storylets formatted?

• A scene with a flag storylet=true in the TOML frontmatter.
• All the fragments in that scene are the storylets.
• stage-ink will also generate a 'hub' stitch, which contains a $hub command that needs to be handled in the parser running this ink story. Ink doesn't natively have storylet support, so all storylets when displayed in the Ink editor will immediately end the story, or move on beyond the whole storylet section.

The generated stitch looks a bit like

// the hub is autogenerated, and should not be created regularly
= _hub
Choices go here...this pulls from existing data or a special `choices` fragment to give content every time there are choices.

// it creates a specific command that the engine will then use
// to populate the choices
$HUB

// to make the compiler happy. This end should never be reached.
->END

When converted to ink, a STORYLET tag will be added to the knot.

$hub

Note: this functionality is not within the parser, and must be implemented in the engine that consumes the output Ink file.

The $hub command contains one argument, which is the title of the knot that starts that storylet section.

When the hub command is reached, the engine MUST:

1. stop moving forward in the story
2. iterate through all the stitches (storylets) in the knot
3. display to the player the choices that link to the storylets whose prerequisites are met:
   • the values in the storylet's prereqs field all evaluate to 'true'
   • the storylet has not been visited before, OR has a persistent field.

Once a choice is clicked, the engine should divert to that storylet.

Metadata

• label: what the choice is called, or the title of the storylet if title doesn't exist
• title: internal title of the storylet. Can be used to list it outside of choices. Distinct from label only for logistical purposes and can be ignored.
• description: longer form description. Can be multiple lines.
• persistent: boolean. If true, a storylet can be visited multiple times, even after it's been seen.

Prereqs

Created as an array, as eval'd statements. All statements in the prerequisites must evaluate to true in order for the storylet to run.

Statements in prereqs key off of global variables in ink.

<> 
+++
prereqs=[
	"started === true",
	"keys > 3"
]
+++

In Javascript, this would check to make sure that the ink global variables started and keys are set properly. See https://github.com/y-lohse/inkjs#getting-and-setting-ink-variables for how to make sure we fetch the variables from ink.

Those are saved in the ink as tags that are a part of the stitch. See https://github.com/inkle/ink/issues/249#issuecomment-271532488

Variables

Inspired by https://klembot.github.io/chapbook/guide/state/the-vars-section.html These are variables that are set immediately before or after the storylet is finished.

(Note that you can do this as commands inside of the storylet as well.)

enter is used to set logic when a storylet is entered. Like with prereqs, these are all eval'd strings, and are processed in order.

<>
+++
enter=[
	"keys = 1"
	"started = true",
	"keys += 1",
	"success = Math.random() > 0.5",
	"use_ink_function = ink!my_ink_function(arg1, arg2)"
]
+++

keys is 2 throughout this section.

You can in fact use Ink's VAR syntax to set variables as well, which will use Ink functions (rather than JS ones)