Setting the Scene

Playable stories written in Ink need a beginning. So do lessons.

So before you begin writing your first scene, why not take a moment to play “Your First Scene”!

Once you are through, you can download the file: Your First Scene.ink and open it in Inky. We will be referencing this story throughout the lesson.

Knots

Knots are the largest units of an Ink story. They are typically bigger than paragraphs or pages (or screens), and they may contain several of both. However, it seems inappropriate to compare them to something as large as chapters. A chapter of a story might necessitate multiple knots. Perhaps it is best to think of them as scenes in a playscript.

As you will see, knots are, well… knots. They are the intersection of multiple threads, or perhaps they are bumps along a single thread. They are what you will build your stories out of. In “Your First Scene,” there is exactly one knot.

Skip line 1 for now; we want to look at line 2. It reads:

=== Your_First_Scene ===

The “===” (three equal signs) at the beginning of the line is your first piece of command syntax. Syntax, or “markup,” refers to the symbols or codes that communicate directly with the computer and are not meant to be seen by the reader.

In this case, using two or more equal signs (=) to begin the line tells the editor that you are creating a new knot. Using Inky, you can generate a pre-written knot snippet from the drop-down menu Ink > Basic Structure > Knot (main section).

Incidentally, the syntax:

==Your_First_Scene

will perform the same task as line 2 as it is written in the screenshot above. It will tell the machine to create a new knot named “Your_First_Scene”. While the above syntax is valid, the example in Illustration 5 (above) and the pre-written knot snippet (see Illustration 6 below) use three equal signs before and after the name of the knot, and we recommend that you follow this convention when using Ink (as we will in this book). This should be considered best practice for clarity and consistency: it helps to make knots more easily identifiable when writing longer works.

When using the drop-down menu to create a new knot, you will see the following boilerplate text appear in the editing window:

When using the pre-written knot snippet, you need only change “knotName” to something relevant for your story, and then replace the next line (“This is the content of the knot.”) with text to be displayed to the reader.

Stitches

A Stitch is a subsection within a knot. If we are continuing to think of our knots as scenes, then a stitch is a potential event within that scene. Thinking in terms of nodes on our story’s map, if a knot is the biggest possible node, a stitch is a smaller node that exists completely inside a knot.  A stitch is created using a single equal sign (=).

Line 22 in Illustration 7 (above) from “Your_First_Scene.ink” reads:

= How_did_you_happen_by_here_again

and it creates a stitch by that name. Note that a stitch is bound by the same naming convention as a knot. Because the stitch exists within a knot, its name is appended to the knot’s name with a period (.). The full name of this stitch reads:

Your_First_Scene.How_did_you_happen_by_here_again

A stitch can be referenced from within its home knot using only the stitch name. However, when referring to this stitch from within another knot, the full name is required—that is, the name of the ‘home’ knot, a period, and the name of the stitch. Inky will assist with predictive text suggestions based on the names of existing knots and stitches as well.

One example of an efficient use for stitches is within a knot that offers several characters with whom the reader can interact. Each character can be assigned their own stitch, containing their own potential dialogue options. As you practice writing your own playable stories, try to think of ways that knots and stitches can help you to organize your nodes.

Diverts

You create your story’s flow between knots and stitches by adding diverts. The command syntax for a divert is an arrow created with a dash and a greater-than symbol, “ -> ”.

Diverts reveal their true importance when paired with choices, which we will explore in the next section. Inserting choices into your playable story will allow you to create multiple paths for your reader to follow, but diverts are how you control the story’s flow. They are the instructions determining which path your playable story will follow and when.

Our “Your_First_Scene.ink” example begins with a divert on line 1 because the entire story takes place within the knot “=== Your_First_Scene ===”.

Choices

Knots and stitches are the major structural units of your story. Diverts are a way of constructing the flow between knots and stitches. However, what makes your story playable by the reader is the ability to make choices in how they explore the map of your story.

Allowing the reader to make choices is a key element of a playable story. And with Inky, it is easy to incorporate them into your text. When playing an Ink story, choices are presented to the reader as clickable links (hyperlinks) that will take them to another node in your story.

Ink has two types of choices: basic and sticky.

A basic choice is added by placing an asterisk, (*), at the beginning of the line. Alternatively, you can use the drop-down menus and select Ink>Choices>Basic Choice and Inky will insert a pre-written snippet. Of course, you need at least two lines, each starting with asterisks in order to present the reader with an actual (either/or) choice!

The example below demonstrates an elementary use of basic choices. In this case, each choice represents a compass direction, allowing the reader to move along four different threads.

Note that Inky has marked the lines with the diverts ( -> ) with a red x. It is reporting an error because we have not yet created the knots for each of those named directions (so the diverts have nowhere to flow). This error reporting is helpful because it alerts you to parts of your story that require attention (for example, something still needs to be written). In the example above, each of the four directions could lead to different knots, each containing its own adventure for the reader to follow!

An option marked up as a basic choice in Ink will no longer be available or visible once it has been selected by the reader, even if the story diverts back to the knot or stitch that initially contained it. In other words, a basic choice is used up once it is selected.

The example in Illustration 10 below (from the stitch named “How_did_you_happen_by_here_again” from “Your_First_Scene.ink”) shows one sticky choice on line 25 (we’ll discuss sticky choices in a moment) and two basic choices on lines 28 and 34:

If the reader initially selects the choice on line 34, the Ink story’s flow continues to line 36, printing that text. The flow then continues to line 37, which diverts the flow back to the stitch named “How_did_you_happen_by_here_again” (which these three choices are within). However, when this stitch is re-presented to the reader, there will only be two choices—the ones the reader did not initially select—instead of three. The choice on line 34 will not appear again because it has been ‘used up.’

You can prevent a choice from disappearing by making it a sticky choice. Sticky choices are created by using a plus sign, (+). Line 25 in Illustration 10 (above) is a sticky choice. As with basic choices, there is a drop-down menu available for sticky choices, Ink>Choices>Sticky Choice, that will add a boilerplate Sticky Choice snippet to the editor.

In the example in Illustration 11 below, the first choice the reader is presented with (on line 8) is a Sticky Choice. Every time the knot “=== Your_First_Scene ===” is re-presented to the reader, the reader can continue to select “Do nothing,” as many times as they would like: the divert (“->Your_First_Scene”) will always flow the story back to the beginning of the knot, and the option will still be there.

Display of Text in Inky

On a basic level, the text you write into a numbered line in Inky equates to a paragraph of text. In other words, you can write as many words and sentences as you like into a numbered line in the editor pane, and they will appear as consecutive words and sentences in the preview pane (and, in turn, in the finished story that your reader will ultimately see). It is only when you press [Return] or [Enter] that the editor pane advances to the next numbered line. In turn, the text in the preview pane will show a line break between one block of text and the next. Used in this manner, Inky behaves somewhat similarly to a common word processor.

For example, consider the writing in the editor pane shown in Illustration 12 (below).

By writing text as shown in the editor pane in Illustration 12 (above), the result in the preview pane will look like Illustration 13 (below).

However, when you use Inky to introduce choices for the reader, you also give yourself more presentation options to consider.

By default during the reading of an Ink story, when a choice is selected (choices are by default presented in grey and centre-justified), the Ink story will first display whatever text is included as a part of that choice’s numbered line. The flow then continues to the numbered lines that immediately follow that choice, displaying any text they contain, one after the other (quite quickly), until a new syntax command—for example, a divert, or another choice—is encountered.

For a demonstration, let us return to Inky’s sample story, “Once upon a time…”, shown below.

If we select the first choice listed, “There were two choices”, then that line will be added to the story in the preview pane, followed by the text from line 6, and then the flow is directed to end. The result is shown in Illustration 15 (below).

But what if you do not want the text from a choice, after it has been selected, to be added word-for-word to the story? Perhaps, instead, you would like something different to appear. Perhaps you would like the choice to disappear completely after the reader has made their selection.

Thankfully, Inky makes it easy to differentiate between the text contained in the choice itself and the text that displays to the reader as a result of making that choice.

Square Brackets

You can control how the text in a choice displays before and after that choice is selected by using square brackets ([ and ]). There are a variety of techniques for controlling the display of text that make use of square brackets, but they all follow a few basic rules.

1. Anything that appears before the bracketed portion of the text will appear in BOTH the initial choice text and in the display text.
2. Text that is enclosed within the brackets will ONLY display in the initial choice text. It will not be displayed after the choice is selected.
3. Text that follows the bracketed text will ONLY appear in the display text after the choice has been selected.

As mentioned previously, controlling the text that is displayed following the selection of a choice can be useful for writing playable stories that do not immediately reveal the outcome of the reader’s decisions. Perhaps you want the choice described as “Stay quiet,” but when the reader selects that prompt, the text reads, “You coldly stare them down, sweating them out with your silence.”

Square bracket techniques can also be crucial for maintaining proper grammar and punctuation.

There are three potential uses for brackets demonstrated in the sample Ink story, “Your_First_Scene.ink”.

The text of line 8 is completely enclosed in straight brackets, as shown in Illustration 16 (above). Therefore, after it is selected, the text “Do nothing” will not appear in the display at all. Instead, the flow proceeds to print lines 9 through 15 before reaching a divert that takes the reader back to the beginning of the knot. The text in the preview pane, after “Do nothing” is selected, will look like Illustration 17 (below).

You can also use square brackets to create choices that allow your reader to select exact lines of spoken dialogue while also allowing you to maintain proper grammar and punctuation when they are displayed in the preview pane.

Illustration 18 (above) shows an example of using an empty set of square brackets. This is one method of adding additional text immediately following the choice text without that text displaying on a subsequent line. The text preceding the square brackets appears both before and after the choice is selected. The brackets, which contain no text, are included to prevent the text following them from displaying until after the reader has selected that choice. The initial text of the choice and the text displayed when this choice is selected are each shown below (Illustrations 19 and 20).

In Illustration 21 (below), lines 25, 28, and 34 each demonstrate another common use for square brackets.

Instead of containing no text, as in the example in Illustration 18, this time the square brackets contain alternate punctuation. With line 25, when the choice text initially displays, it ends with a period (and a closing double quotation mark) after “remember” because that is the end of the sentence before being chosen. But when that choice is selected and the choice text is re-presented with the added “you say,” the period after “remember” has to be changed to a comma (and closing double quotation mark) in order to include “you say” in the sentence. You can see the result in Illustrations 22 and 23 (below). The same process is followed in lines 28 and 31.

Putting It All Together

The elements presented in this chapter make up the basic tools used to create branching narratives with Ink.

By breaking your story up into separate knots, you create a map through which your reader can travel along the various flows you have created. You can think of this literally, offering choices asking the reader if they would like to go left or right, up or down. Or perhaps your reader’s journey will be a bit more philosophical. Does your reader choose to confront the beast guarding the door? Or do you give them the option to use cunning and stealth to slip past the monster?

Can you think of some situations in which it would be important to use a sticky choice instead of a basic choice?

These are examples of just some of the most basic uses of Ink and Inky. Try to make a scene for yourself. Play around in the software. Experiment. Practice.

In the next chapter, we will add a few more tools to the belt, allowing for a more nuanced presentation of the text and the ways it can be changed based on the reader’s choices, as well as adding another layer of depth onto the choices themselves.