The examples used in this chapter, in *.ink files, can be found online on GitHub: https://github.com/PacktPublishing/Dynamic-Story-Scripting-with-the-ink-Scripting-Language/tree/main/Chapter1.

When holding a physical book, a reader moves through a story by turning its pages. The movement between pages is also a movement through the story. What is experienced by the reader is called a narrative. The story is the packaging of its content into different parts called pages. The reader's narrative, however, is the experience of the story across those pages.

In a digital setting, there are no physical pages. The words of a story could be stored as part of a simple text file or bundled together in something more complex. Parts of a digital story, which are the pages in a physical book, can also be arranged much more easily, and the reader might experience them in different configurations, creating new narratives from the same story content.

Consider the following example, where each sentence is a part of a story:

The sun was shining in a clear blue sky.
Clouds rolled in and it began to rain.
The clouds cleared away and the sun emerged.

When taken in order from the first sentence to the last one, there is a story where the major parts are the sun shining, the clouds coming in, but then the clouds leaving and the sun shining again. However, what happens if the parts are rearranged?

Example 1:

The clouds cleared away and the sun emerged.
The sun was shining in a clear blue sky.
Clouds rolled in and it began to rain.

With a different ordering, a new narrative is created for the reader. In this version, the progression begins with the sun emerging and shining. Next, the clouds move in and it begins to rain. In either case, only three events are used, but their order affects the narrative experience of the reader.

Nonlinear storytelling

In the second example, the story still makes sense. This time, however, the events start with the clouds, move into the sun shining, and end with the clouds returning. The second example, in moving around the events, is an example of nonlinear storytelling, where the events or parts of a story are experienced in a new or different way than created or originally written. The progression is not linear from one part to another as created in the story, but a cohesive narrative is still created:

Figure 1.1 – Mapping nonlinear storytelling

The structures created by navigating a nonlinear story are often compared to trees. They start with a trunk and then, as different parts are encountered over others, a branching pattern is created, with each branch representing a movement through parts of a story from one end to another. The narrative traversal through a nonlinear story creates a branching narrative, where different parts were or were not encountered. The map of the experienced narrative represents a particular branch of the overall tree of the story and its parts.

While nonlinear storytelling can be done with a printed book, it is often much more difficult. In a digital setting, where events can be broken up into different parts, rearranging them can often be as easy as selecting them and dragging them to a different part of the same document. This consequence of representing stories as data makes writing code to handle arranging the different parts easier too. This is known as narrative scripting.

Introducing ink

ink is a narrative scripting language. It determines which part of the story comes next for the reader. As a user clicks or presses buttons, the code written in ink makes the decision between which branches they should visit and when. Based on rules written by an author, the code can even repeat the same part of the story with new values.

Because ink is designed for the purpose of scripting narratives, it understands navigation through a story as a special concept called flow. As the reader moves through the different parts, they are creating their own experienced narrative, which ink calls the flow. In fact, one of the most common errors encountered by authors is where the flow runs out of a story. Even when writing a nonlinear story with different branches, the story must start and end somewhere. Even if all the parts between the start and end of a narrative change each time a user traverses the parts of a story, these two points define the range of possible branches.

Text flowing down

The concept of flow also extends to how code is understood in ink. All movement across a story in ink moves down from the top of the code to the bottom unless told to navigate to a different part in the story.

The example stories shared earlier in this chapter are both also code examples. ink is designed to create branching narratives and supplies the ability to write code to create these structures. This means text or words written in a story without any other special characters or syntax are valid in ink.

Spacing within a line of text is important in ink. Because the text is considered a form of code, ink assumes any use of spacing is a deliberate choice on the part of the author. For example, adding extra spaces between words is not removed in its output:

The sun was        shining in a clear blue sky.

Output:

The sun was        shining in a clear blue sky.

ink ignores any empty lines. It assumes each line of text is important and any spacing between them should be ignored as something unimportant to the story itself.

Example 2:

The sun was shining in a clear blue sky.
Clouds rolled in and it began to rain.
The clouds cleared away and the sun emerged.

Output:

The sun was shining in a clear blue sky.
Clouds rolled in and it began to rain.
The clouds cleared away and the sun emerged.

The smallest unit is a line

The use of three lines as part of a story when introducing nonlinear storytelling was not a mistake. The smallest unit within an ink story is a single line:

This is a story.

Because ink considers text to be a part of the code, a single line with only four words is a completely valid story. Adding more lines would also extend what would be presented to the reader, but a single line can be a story by itself:

This is a story in ink.
It has two lines.

The use of the term line is important in ink. When reading a physical book, the smallest unit in a story is usually a sentence. This is often the smallest complete thought in a larger work. In a digital context, and specifically within ink, a line is the smallest unit. When ink loads a story, it moves through the story line by line. It treats each as equally important as the last.

As more complex code is introduced, the concept of a line will become more important as well. However, just like the single-line example, a story need not be complex to be important. To ink, a story is composed of lines. This could be one or potentially many more.

Gluing lines together

An author may need to use multiple lines of text as one "line" of code. For these situations, ink provides a concept called glue. When the less-than and greater-than symbols, <>, are used together, they glue the content of one onto the next, creating one long line:

Example 3:

This <>
is <>
considered <>
one <>
line of text.

Output:

This is considered one line of text.

Spacing when using glue is important. As with spacing within a single line, ink respects the choices of the author when presenting text in a single line. When using glue, these spaces are also respected.

Without the spaces after each word, the use of glue in the previous example would glue all the words together:

This<>
is<>
considered<>
one<>
line of text.

Output:

Thisisconsideredoneline of text.

Using comments as notes to authors

As a scripting language, ink also provides the ability to include notes within the code of a story. Borrowing from a more general programming term, ink calls these notes comments. They begin with two slashes and then contain the content of the comment. Any part of the line is also considered part of the comment:

Example 4:

The sun was shining in a clear blue sky.
// Change this next line in the future.
Clouds rolled in and it began to rain.
// Maybe update this story in a future version?
The clouds cleared away and the sun emerged.

When run, the text of the story would be treated as its code. However, any use of comments would not appear in the output of the story. Comments are only designed for human audiences and allow an author to explain the code to other audiences, or, more generally, as notes to themselves or other members of their team about how something works.

Working with Inky

To help authors more quickly develop a story in ink, Inkle Studios has created a program called Inky. This editing tool allows an author to write code and see it run as a preview of its output:

Figure 1.2 – Screenshot of the Inky editor

While initially developed by Inkle Studios, Inky is now an open source project and often sees dozens of commits by the community to fix small issues or add new functionality. A new minor version usually comes out every year.

At the time of writing, Inky does not have a Windows installer but provides builds for macOS X and Linux systems. When running on Windows or Linux, the ZIP file needs to be unzipped to an existing folder and the Inky.exe (for Windows) or Inky (for Linux) file run to open the editor.

Using Inky

Inky presents an interface with two panes:

• The left is where ink code is written.
• The right shows a preview of the code while it is being developed.

This allows users to quickly see how their code would produce different outputs depending on what code was used.

Inky's most useful function is the ability to "rewind" a story to an earlier point and try a different branch of the narrative. This allows authors to test branches of their story more quickly, without needing to restart the story each time.

Figure 1.3 – The "Rewind a single choice" and "Restart story" buttons

Important note

This book will use screenshots from Inky to show the resulting output of different code.

While having code pick parts of a story to produce a new possible narrative for a user could be exciting, most users want some input on what happens next. They want an interactive story. In ink, interactivity is created by presenting the user with choices. Depending on which choice the reader makes, the narrative could then branch in different ways.

Making weaves

Choices in ink are a part of another important concept, weaves. As a user creates a flow from one part to another, they often encounter intersections within a story where branches might be possible depending on what choice is made. This is what is known as a weave within ink. These are collections of choices where each one has the potential to branch the story in different ways.

Choices are written in ink using an asterisk, *. What might appear as a list of things is, in ink, each a different choice within a single weave:

What did I want to eat?
* Apples
* Oranges
* Pears

In the previous code, each line starting with an asterisk is a choice. It starts from the asterisk and extends to the end of the line. Everything that is part of the line becomes a part of the choice. Each asterisk on a new line creates a new choice within the weave:

We smiled again at each other across the coffee shop. I had seen her coming in at this same time for over a week now. We had spoken a couple of times, but I could not bring myself to talk to her more.
As I looked back down at my coffee, I needed to decide.
* I decided to go talk to her.
"Uh. Hi!" I said, maybe a little too loud as I approached her.
* I gave up for now. Maybe tomorrow.
I shook my head to myself and looked away from her and out the window. Today was not the day.

Each choice in a weave has the potential to branch the narrative. In the previous code, there are two choices. However, after each choice is another line of code. When run, ink would understand each line following a choice as being the result of choosing the reader. To help to visually differentiate the result of the choice better, the line following a choice is often indented at its start.

Changing the previous code to use indentation would look as follows:

Example 6:

We smiled at each other again across the coffee shop. I had seen her coming in at this same time for over a week now. We had spoken a couple of times, but I could not bring myself to talk to her more.
As I looked back down at my coffee, I needed to decide.
* I decided to go talk to her.
    "Uh. Hi!" I said, maybe a little too loud, as I approached       her.
* I gave up for now. Maybe tomorrow.
    I shook my head to myself and looked away from her and out       the window. Today was not the day.

Choices within choices

Choices can also appear inside other choices. These are sub-choices and use an additional asterisk to indicate that they are the result of a previous layer of a weave:

Example 7:

Should I really forgive her again? I thought about the options in front of me as I considered what she told me.
* I forgive her.
    ** She does the same behavior again.
        I just end up hurt again.
    ** She really does change.
        She does not have another affair and maybe we can save           our relationship.
* I do not forgive her.
    ** I would have to move out.
        I would need to find another apartment.
    ** I stay with her and try to live again without being in a          relationship.
        I could try going back to being friends like we were           before our relationship.

In the previous code, there are two choices that each lead to their own choices, branching off the central set. This is an example of a complex weave. The first layer of the weave is the initial two choices. The result of either choice is then another weave, which then ends in text. Depending on the user's flow, they might only see part of the overall story when moving between these parts.

One possible branch within the complex weave could be the following output for the reader:

Output

Should I really forgive her again? I thought about the options in front of me as I considered what she told me.
I forgive her.
She does the same behavior again.
I just end up hurt again.

A different series of branches within the story might also create the following output:

Should I really forgive her again? I thought about the options in front of me as I considered what she told me.
I do not forgive her.
I would have to move out.
I would need to find another apartment.

Selective choice output

When using choices, the text of the choice itself appears in its output. This can be changed by using a special concept with choices called selective output. By using open and closing square brackets around any text in the line of the choice, it will not appear as part of the output as a result of making the choice:

What did I want to eat?
* [Apples]
* [Oranges]
* [Pears]
I got some food.

In the previous code, the output, regardless of the choice made by the reader, would be the same:

What did I want to eat?
I got some food.

In the cases where the text of the choice is different from what is shown to the reader, the term option is used. A choice is created in ink using code. What is ultimately shown to the reader is an option.

In more advanced code examples, ink can generate choices dynamically. In these cases, as with selective output, it can be important to understand the use of a choice as something written by a developer and an option as selected by the reader. Often, these can be the same thing, but they do not have to be when writing code in ink.

Selective output also allows creating more dynamic output by selectively showing text from an option in the output. An effect of using selective output is that the closing square bracket in a line signals an end to what is shown to the reader. Any additional text on the same line is ignored:

Example 8:

I looked at the timer again and then at the wires in front of me. I had five seconds to stop this bomb from exploding.
* [I cut the wire.] It was the green one.
* [I cut the wire.] It was the red one.
* [I cut the wire.] It was the blue one.

Possible output:

I looked at the timer again and then at the wires in front me. I had five seconds to stop this bomb from exploding.
It was the green one.

From the reader's perspective, the previous code would show three options. Each one would read I cut the wire. However, the use of selective output is telling ink to ignore the additional text of each color. After making a choice, the user would then see the result of the choice as a new line, with the use of square brackets excluding anything they enclose.

Selective output can often be useful to hide additional information behind a choice where the reader must pick an option and then see the additional text of a line.

Gathering points

Each choice in a weave can potentially branch a narrative. However, sometimes there is a need to gather one or more branches back to where they began. Instead of leading off in a new direction, a gathering point can be used to collapse a more complex weave into a central point. In ink, gathering points are created using a single minus sign (-) on a line:

You peer down at the desk with two drawers.
* Try to open the top drawer.
    It does not open.
    ** Try again more forcefully.
    ** Give up for now
* Try to open the side drawer.
    It does not open.
    ** Try again more forcefully.
    ** Give up for now
- All the drawers seem locked tight.

In the previous code, there are two choices with two sub-choices each. However, at the bottom of the weave is a gathering point. No matter what branch is taken across the first weave and then into the next layer, the flow will always gather at the last line. This is the power of gathering points: they allow a complex weave with multiple layers to collapse into a single point.

The placement of gathering points is important. In ink, stories flow down from the top to the bottom. If the gathering point appeared before the weave, it would be ignored. Without anything to gather, the gathering point does nothing. This also only affects weaves. Multiple gathering points in a story would do nothing without a weave above them to act as a point of collapsing them.

Gathering points only work on a single weave at a time. As the last line of a weave, they act to gather the choices. However, they only apply to one branching structure at a time. A new gathering point is needed per weave to collapse those branches back together:

Example 9:

You peer down at the desk with two drawers to open.
* [Try the top drawer.]
* [Try the side drawer.]
- All the drawers seem locked tight.
You give up on the drawers and look at the top of the desk.
* [Look at the papers on top of the desk.]
* [Pick up the papers and look through them.]
- You find nothing of interest.

In the previous code, both selective output and gathering points are used to create the illusion of two weaves with two choices each. The outcome of each, because they are using gathering points, is the last line of each. Options are presented to the reader, but the code itself collapses any possible branching of each weave and flows the story from the first weave to the second layer.