Introduction to Ink (by Jon Ingold)
Jon Ingold is the co-founder of independent studio inkle (www.inklestudios.com), and co-designer of ink, alongside Joseph Humfrey. Jon wrote inkle’s games Heaven’s Vault, Steve Jackson’s Sorcery!, and co-wrote 80 Days with Meg Jayanth.
This article was originally published in Wireframe magazine.
Weaving branching narratives in ink: a beginner’s guide
Ink is the open-source narrative scripting language behind inkle’s massively-branching narrative games 80 Days and Heaven’s Vault. It’s free to use, and good for writing stories with lots and lots of choice. Here’s how to get started.
What is ink?
Ink is scripting language a bit different from other narrative engines. It’s not graph-based like Twine; there are no nodes and boxes to wire up. And it’s not code-based, like writing a game in Javascript. The simplest ink story looks, well, like this.
Hello world!
And adding a choice is as easy as putting in a bullet-pointed list:
Hello world!
* “Hello computer!”
It’s nice to meet you.
Let’s get started!
Ink aims to give writers a way to write quickly, to read back quickly, and best of all, to edit quickly.
So that’s the sales pitch (though ink is free.) Let’s get stuck in.
All the resources you’ll need are available on ink’s homepage: https://www.inklestudios.com/ink/, along with more tutorial material, full documentation, Unity integration code, examples and places to get support.
Getting started
Ink can be written in any text editor, but it’s simplest to use the editing tool, inky. You can get inky from the ink page, or directly from GitHub (http://www.github.com/inkle/inky/releases/latest).
Inky has two panes: one on the left where you write, and one on the right where you play. If we type up the short ink story above, it’ll look like Figure 1.
Inky has started playing the story on the right-hand side, and presented us with the first choice. If we click the choice in the right-hand pane, it’ll play that choice. (Figure 2.)
(By default, ink will repeat the text of the choice into the flow of the story, but that — like most things! — can be changed with a bit more markup.)
For now, let’s expand our story to have some choices in, by using ink’s core construction: the weave. (All the main element of ink use weaving metaphors: label lines are called ‘gathers’, blocks of content are called ‘knots’ and ‘stitches’; and an ‘inkle’ itself is a kind of loom for creating long, narrow woven straps.)
The idea of a weave is that it starts at the top, and gets to the bottom, but maybe branches along the way. Something like this:
Code
Hello world!
* “Hello computer!”
It’s nice to meet you.
Let’s get started!* “I’m not the world. I’m just one person.”
Ah! A pedant, I see!
This is going to be fun.- Now, what should we talk about?
* “I’m here to learn about ink.”
Ink? Sounds messy. Let’s do it!
The weave starts at the top, branches with two possible responses. Those choices both gather together again (at the ‘-’ sign), and then we offer another choice. You can see how it plays in Figure 3.
Using conditionals to change the story
The beauty of a weave format is things can get branchy, fast. Let’s throw a bit more detail into our example, by labelling one of lines, and then using is to make a conditional choice later on.
We’re also going to add some sub-choices — these are nested bullet-points, that sit under the choice that triggers them.
code
Hello world!
* “Hello computer!”
It’s nice to meet you.
Let’s get started!* (pedantic) “I’m not the world. I’m just one person.”
Ah! A pedant, I see!
This is going to be fun.- Now, what should we talk about?
* “I’m here to learn about ink.”
Ink? Sounds messy. Let’s do it!
* {pedantic} “Technically we aren’t talking.”
And yet, you can hear my voice in your strange meat-filled head, can’t you? What’s with that?
* * “It’s called reading. It’s no big deal.”
You say that, but I can’t read.
* * “I’d never thought about it like that before.”
Happy to expand your mind a little, human.
* {not pedantic} “I want to learn ink, but what do you want to talk about?”
Do you know, no one has ever asked that before?
So I don’t know the answer.- Anyway, let’s talk about ink.
One possible playthrough is shown in Figure 4, but there’s already a lot of different ways it could go! And our decisions are causing consequences into the future, with new options opening up and closing off.
Diverts and knots
We can take this much, much further by introducing blocks of content — knots — and the ability to jump out of one and into another — what ink calls a divert, written as “->” (we couldn’t think of anything weaving related where you jump off one loom and onto another.)
Mixing all this together gives us the quick-and-messy interactivity of the weave alongside the structure of a classic gamebook, while still altering the text on the fly based on what the player’s done so far.
Check this example out!
code
I walked into the saloon of the Dusty Gulch Bar.
* My six-shooter was holstered. I didn’t want no trouble.
-> peaceful_like* I had my Colt in my hand. I knew Billy was in there.
-> shooty_like=== peaceful_like
The piano was playing. The barman was mixing rye and whiskey and calling it a Mudslinger. A lady by the bar was telling fortunes for a silver coin, while her little boy picked the pocket of whoever was listening to her.
-> sit_by_bar=== shooty_like
The piano music stopped dead as I came in. Every head turned. The barman dropped a bottle and didn’t stoop to sweep it up. A lady telling fortunes by the bar grabbed her purse and ran out the door.
* “Is Billy here?”
“Billy? Billy who?” the barman stuttered back.
* * “Billy the Kid,” I explained.
“We don’t serve kids, Mister, this is a bar.”
* * I ignored him and scanned the room. “Billy? Where are you?”
There was no sign of him and for a moment I thought I was in the wrong town.
-> then_the_door_flew_back* (no_trouble) “I don’t want no trouble…” I began.
“Mister,” the barman replied. “If you don’t want no trouble, why don’t you put those six-pins away?”
- -> sit_by_bar
=== sit_by_bar
* I took a seat by the bar.
The barman served me a glass of his curious concoction {shooty_like: and I laid my weapon down on the counter}.
* {shooty_like.no_trouble}
“I like to keep my guns close.”
“They’ll be closer at your hip,” the barman grumbled, but he served me a drink anyway.
* {peaceful_like}
I went over to the fortune-teller and asked my fortune.
She looked me up and down.
“It’s not looking good, I’ll you that for free.”* “I’ll be on my way,” I told the room at large.
- -> then_the_door_flew_back
=== then_the_door_flew_back
Then the door flew back and there he was. The very goat I’d come here to catch: Billy the Kid.
- -> END
Figure 5 shows one way through this scene … and of course, we could spin the story off in very different directions if we wanted to, instead of bringing them back together, and anything that happens along the way could become important later on…
Why no flow chart?
One thing that always strikes people as strange when they first come to ink is that there’s no flow-chart. Ink doesn’t use them, and generating them can be hard, too, once you start taking advantage of the full feature set. So why is that?
To illustrate the answer, let’s look at a real-world example. Figure 6 shows the first scene of 80 Days (somewhat simplified), written in ink. It’s a classic weave: it starts at the top, there are longer or shorter ways the conversation could play out, but they all end in the same place.
Now compare that to the same scene as laid out as a chart:
The flow chart isn’t unreadably complex: and it demonstrates the structure of the scene well. But it is big. For one minute of gameplay we need a whole screen’s-worth of diagram. And if you want to edit this scene — say, to add another choice in the middle of a branch — you have to take the whole graph apart, move it around, just to insert a few extra nodes.
The ink version, on the other hand, is compact: it’s quick to read through, the structure is clear, and best of all, if you want to redraft it, maybe adding in a few sub-choices on one branch, or simply cutting a line, it’s extremely quick and safe to do it.
In short: ink scales up. 80 Days’ script stands at over 600,000 words and 12,000 “nodes” of content. As a flow-chart it’d be impressive — but not much use.
So the ink manifesto is: ditch the flow-charts! If you want to see how your story is structured, then play it! If you want to plan it using a flow-chart, use paper!
But when it comes to getting out of your head and onto the computer, we say: take a leaf from the coder’s handbook.
Coders don’t use visual interfaces for their code: neither should writers.
Sophisticated state tracking
The examples here use labelled content to track what you’ve done in your story. But ink offers a wide range of ways to track state.
There are variables — numbers, strings, boolean true/false values and an exotic type called a LIST which works like a rack of numbered flip-switches, which can be used for things like inventories or tracking which characters are present.
And you can do complex decision making — there’s full logic, bracketing, and the ability to author functions.
Low floor, high ceiling
Inky allows you to export your ink stories for the web directly, so turning your story into something playable requires no coding at all. But it’s also designed to integrate with game-engines via a Unity plug-in, and the open-source community is working on integrations for other engines, such as Unreal and Godot.
Here at inkle we’ve used ink inside a 3D world in Heaven’s Vault, but we’re not the only ones: ink runs the narrative in PSVR title Falcon Age, upcoming indie titles Sable and Over the Alps. Other games, such as Valve’s Valley of the Gods, Banner Saga 3, Dream Daddy, and Rare’s Sea of Thieves use ink as part of their writing pipeline.
