Pardon our dust! Docs for Yarn Spinner for Unity 3.2 and Yarn Spinner for Godot C# are on docs.yarnspinner.dev (the old docs site). Docs for Yarn Spinner for Unity 3.3 (pre-release, out ASAP), Yarn Spinner for Godot GDScript and Yarn Spinner for Unreal Engine (work in progress) are on /docs/ (the new docs site).

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.
Ink: a knot.
title: Harbour
---
The boats are all tied up.
===
Yarn Spinner: the same content as a node.

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.
Ink: two choices, then a gather.
title: Harbour
---
-> Ask about the boats
    Fisher: Storm's coming.
-> Leave
    You head back up the hill.
The wind picks up.
===
Yarn Spinner: two options, then the line that follows both.

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!
A once-only option and a conditional option.

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

InkYarn Spinner
VAR gold = 10<<declare $gold = 10>>
~ gold = gold + 5<<set $gold to $gold + 5>>
{gold} in text{$gold} in text
~ temp count = 0No equivalent
CONST LOBBY = 1No equivalent
Ink variables and their Yarn Spinner versions.

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>>
Yarn Spinner: choosing between two lines.

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

InkYarn 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 cyclesTrack a number variable and use <<if>>
Ink alternatives and the closest Yarn Spinner feature.

A sequence that sticks on its last line looks like this:

<<once>>
    Fisher: You're new here.
<<else>>
    Fisher: You again.
<<endonce>>
Yarn Spinner: the first line once, then the second line every time after.

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, plural and ordinal markers 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}.
One line that changes with two variables.

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.
Options from different parts of the story, each with its own condition.

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>>
Separate flags, with a smart variable that checks them all.

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>>
Checking how long ago something happened.

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.