# Stage Export to Ink

Converts a Recital `.stage` file into an [Ink file](https://www.inklestudios.com/ink/), 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

```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](https://klembot.github.io/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**:

#### 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 $<>`.)

## 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](https://emshort.blog/2019/11/29/storylets-you-want-them/), 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)