Coming to Yarn Spinner from Ink
If you’ve written in Ink, most of what you know carries over. Both languages are plain text, both break a story into named sections, and both leave presentation to the game. This guide goes through Ink’s features one at a time and shows the Yarn Spinner version.
Knots and stitches become nodes
An Ink knot is a node in Yarn Spinner. A node has a header, a --- line where the content starts, and === where it ends.
=== harbour ===
The boats are all tied up.title: Harbour
---
The boats are all tied up.
===Yarn Spinner has no stitches. Make each stitch its own node, and use the node title to show which part of the story it belongs to, such as Harbour_Night. Node titles must start with a letter or an underscore, and can only contain letters, numbers and underscores.
Ink runs any content above the first knot automatically. In Yarn Spinner, every line is inside a node, and the game chooses which node to start from. Most projects call it Start.
Diverts become jumps
-> harbour in Ink is <<jump Harbour>> in Yarn Spinner. A jump is a statement on its own line. It can’t sit in the middle of a sentence the way a divert can.
When a node ends without a jump, the dialogue ends. That covers most uses of -> END. To stop part-way through a node, use <<stop>>.
Choices become options
Ink choices start with * or +. Yarn Spinner options start with ->. The lines that belong to an option are indented below it.
* [Ask about the boats]
"Storm's coming," she says.
* [Leave]
You head back up the hill.
- The wind picks up.title: Harbour
---
-> Ask about the boats
Fisher: Storm's coming.
-> Leave
You head back up the hill.
The wind picks up.
===A few differences to watch for:
- Choice text isn’t repeated. Ink prints the choice text again after the player picks it, unless it’s in square brackets. Yarn Spinner never does. If you want the player’s line shown, write it as a line inside the option.
- There are no gathers. After the player picks an option and its indented lines run, the dialogue carries on from the next line that isn’t indented. That’s where an Ink gather would go.
- Options are sticky by default. Every Yarn Spinner option works like Ink’s
+. For Ink’s once-only*, add<<once>>to the end of the option. - Conditions go at the end. Ink puts a choice’s condition before the text, as in
* {has_key} Open the door. Yarn Spinner puts it after:-> Open the door <<if $has_key>>.
-> What's going on? <<once>>
Guard: The kingdom is under siege!
-> Open the door <<if $has_key>>
<<jump Inside>>
-> Lovely day today!Yarn Spinner has no fallback choices.
Tunnels become detours
-> knot -> in Ink runs another knot and then comes back. In Yarn Spinner, that’s <<detour NodeName>>. Use <<return>> where Ink uses ->->, or let the node reach its end, and the dialogue goes back to the line after the detour. See Detours.
Variables
| Ink | Yarn Spinner |
|---|---|
VAR gold = 10 | <<declare $gold = 10>> |
~ gold = gold + 5 | <<set $gold to $gold + 5>> |
{gold} in text | {$gold} in text |
~ temp count = 0 | No equivalent |
CONST LOBBY = 1 | No equivalent |
Yarn Spinner variable names start with $. A variable holds a number, a string or a boolean. Every variable lasts for the whole story, so there are no temporary variables.
A <<declare>> takes effect without the node it’s in being run. Many projects keep all their declarations in one node. See Logic and Variables.
Ink’s comparison and logic operators work in Yarn Spinner: ==, !=, <, >, <=, >=, and, or and not. Yarn Spinner also accepts is for ==.
Conditional text
Ink’s inline conditionals, such as {has_key: The door is open.|The door is locked.}, become <<if>> blocks around whole lines.
<<if $has_key>>
The door is open.
<<else>>
The door is locked.
<<endif>>Read counts
In Ink, a knot’s name is also a count of how many times it has been seen. In Yarn Spinner, call visited("NodeName") for true or false, or visited_count("NodeName") for the number.
Both functions count a visit once the node has been entered and left. While a node is running for the first time, visited_count for that node is still 0.
Sequences, cycles and shuffles
| Ink | Yarn Spinner |
|---|---|
Once-only {!a|b} | Wrap the line in <<once>> and <<endonce>> |
Shuffle {~a|b|c} | A line group, with each line starting => |
Sequence {a|b}, two steps | <<once>> with an <<else>> |
| Longer sequences and cycles | Track a number variable and use <<if>> |
A sequence that sticks on its last line looks like this:
<<once>>
Fisher: You're new here.
<<else>>
Fisher: You again.
<<endonce>>In a line group, Yarn Spinner picks one line each time the group runs, so it’s closest to a shuffle.
Functions
Ink scripts can define functions. Yarn Spinner scripts can’t. Functions and commands are written in your game’s code and called from Yarn Spinner, much like Ink’s EXTERNAL functions. See Functions and Commands.
For a value worked out from other variables, use a smart variable.
Ink’s RANDOM(1, 6) is random_range(1, 6) in Yarn Spinner, and dice(6) also gives a number from 1 to 6.
Tags
Ink tags (# tag) work the same way in Yarn Spinner. Put them at the end of a line or option, and your game can read them. See Tags and Metadata.
Things Yarn Spinner doesn’t have
Some Ink features have no direct match. These are the approaches that work well in Yarn Spinner.
Glue
Ink’s glue (<>) joins text from different places into one line. In Yarn Spinner, each line is sent to the game on its own, so write the whole sentence as one line.
When part of the sentence changes, put the change inside the line instead of splitting it:
{$gold}puts a variable’s value into the line.- The
select,pluralandordinalmarkers choose a word or phrase from a value. - For larger differences, write each version as a full line inside
<<if>>.
Baker: I baked [plural value={$pie_count} one="a pie" other="% pies" /] for you, {$name}.Keeping whole sentences together also helps translators, because each line can be translated as a complete sentence.
Threads
Ink’s threads (<-) collect options from several knots into one set. In Yarn Spinner, the options the player sees together are written together, as one block. Write the full set of options in one place, and give each option the condition that decides whether it appears.
Innkeeper: What'll it be?
-> A room for the night <<if $gold >= 5>>
<<jump Room>>
-> Ask about the missing ship <<if $heard_about_ship>>
<<jump Ship_Rumours>>
-> Show her the map <<if $has_map>>
<<jump Map>>
-> Nothing, thanks.If the same set of options is needed in several places, put it in its own node and <<detour>> to it.
Lists
Ink lists can hold several values at once. In Yarn Spinner, choose based on what the list was for:
- One state out of several, such as a door that’s open, closed or locked: use an enum.
- A set of flags, such as which clues the player has found: use one boolean variable for each.
- A question about several flags, such as “has the player found every clue?”: use a smart variable.
<<declare $found_letter = false>>
<<declare $found_key = false>>
<<declare $found_map = false>>
<<declare $found_all_clues = $found_letter and $found_key and $found_map>>TURNS_SINCE
Yarn Spinner doesn’t count turns, because what counts as a turn is up to your game. Keep a number variable for the turn, and add to it wherever a turn passes in your story or from your game’s code. When something happens, store the current turn in another variable, and compare the two later.
<<declare $turn = 0>>
<<declare $turn_saw_ghost = -1>>
<<set $turn_saw_ghost to $turn>>
<<if $turn_saw_ghost >= 0 and $turn - $turn_saw_ghost < 3>>
You're still shaking.
<<endif>>If you only need to know whether a node has been seen, or how many times, use visited or visited_count instead.
CHOICE_COUNT
Ink uses CHOICE_COUNT() to check how many choices have been offered so far. In Yarn Spinner, the conditions on the options already decide which ones appear. If you need different content when none of them would appear, check the same conditions in an <<if>> before the options.
Things Ink doesn’t have
- Character names. Text before the first colon in a line, as in
Fisher: Storm's coming., is the character’s name, and your game receives it separately from the text. - Node groups and saliency. Several nodes can share a title and have
when:conditions, and Yarn Spinner picks the one that best fits the current state. See Node Groups. - Line IDs for localisation and voice-over. Each line can carry an ID that stays the same when the text changes, so translations and audio files stay matched to their lines.