Coming to Yarn Spinner from Twine
A lot of Twine will feel familiar in Yarn Spinner. Passages become nodes, links become options, and <<set>> and <<if>> look almost the same as they do in SugarCube.
The biggest change is that a Twine story is a web page, and Yarn Spinner isn’t. Yarn Spinner sends your game one line at a time, and then a set of options. Your game decides how they look. There’s no HTML, CSS or JavaScript in a Yarn script.
This guide covers Harlowe and SugarCube, the two most common Twine story formats.
Passages become nodes
Each Twine passage is a node. A node has a header with its title, a --- line where the content starts, and === where it ends.
title: Cellar
---
It's dark down here.
===Node titles must start with a letter or an underscore, and can only contain letters, numbers and underscores. A passage called “The Cellar” needs a new name, such as The_Cellar or Cellar.
Twine passage tags become a tags: line in the node’s header.
Text becomes lines
In Twine, a passage is a block of text that appears all at once. In Yarn Spinner, each line of text is sent to the game separately, and the player usually advances through them one by one.
If a line starts with a name and a colon, as in Ada: Mind the step., Yarn Spinner treats the name as the character speaking and sends it to your game separately.
Links become options
Twine links sit inside the text. In Yarn Spinner, options come after the lines, as a list starting with ->. To go to another node, put a <<jump>> under the option.
[[Go down->Cellar]] or [[Stay here->Hall]]-> Go down
<<jump Cellar>>
-> Stay here
<<jump Hall>>An option doesn’t need to jump anywhere. Lines indented under an option run when it’s picked, and then the dialogue carries on from the next line that isn’t indented. A lot of small Twine passages that exist only to show one reply can become options inside the same node.
When a node ends without a jump, the dialogue ends.
Going to another node without a choice
| Harlowe | SugarCube | Yarn Spinner |
|---|---|---|
(go-to: "Cellar") | <<goto "Cellar">> | <<jump Cellar>> |
(display: "Notes") | <<include "Notes">> | <<detour Notes>> |
A detour runs another node and then comes back to the line after the <<detour>>. See Detours.
Variables
| Harlowe | SugarCube | Yarn Spinner |
|---|---|---|
(set: $gold to 10) | <<set $gold to 10>> | <<set $gold to 10>> |
$gold in text | $gold in text | {$gold} in text |
_count (temporary) | _count (temporary) | No equivalent |
Yarn Spinner variables start with $, like Twine’s. A variable holds a number, a string or a boolean. Every variable lasts for the whole story, so there are no temporary variables.
Arrays, datamaps and objects have no equivalent. Use a separate variable for each value, or an enum where a variable has one of a fixed set of values.
Twine’s startup passage (a passage tagged startup in Harlowe, or StoryInit in SugarCube) usually sets starting values. In Yarn Spinner, use <<declare>>. A declaration takes effect without the node it’s in being run. See Logic and Variables.
Conditions
(if: $gold > 5)[You can afford it.](else:)[Not enough.]<<if $gold gt 5>>You can afford it.<<else>>Not enough.<</if>><<if $gold > 5>>
You can afford it.
<<else>>
Not enough.
<<endif>>Yarn Spinner uses <<elseif>> and ends the block with <<endif>>. The words is, and, or and not work as they do in Twine.
To show an option only when something is true, put the condition at the end of the option:
-> Buy the lantern <<if $gold > 5>>
<<set $gold to $gold - 5>>Visits
| Harlowe | SugarCube | Yarn Spinner |
|---|---|---|
(visited: "Cellar") | visited("Cellar") > 0 | visited("Cellar") |
visits | visited() | visited_count("Cellar") |
Yarn Spinner counts 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.
To show something only the first time, wrap it in <<once>> and <<endonce>>. See Once.
Randomness
| Harlowe | SugarCube | Yarn Spinner |
|---|---|---|
(random: 1, 6) | random(1, 6) | random_range(1, 6) or dice(6) |
(either: "a", "b") | either("a", "b") | A line group |
A line group is a set of lines that each start with =>. Each time the group runs, Yarn Spinner picks one of them.
Things Yarn Spinner doesn’t have
- Links inside text. Options always come after the lines.
- Revealing text in place. Harlowe’s
(link:)hooks and SugarCube’s<<link>>change the page without moving on. In Yarn Spinner, use an option with the new lines indented under it. - HTML, CSS and JavaScript. Styling is up to your game. Yarn Spinner’s markup marks up text, such as
[b]bold[/b], and your game decides what each marker looks like. - Undo. Going back to an earlier passage is something your game would have to build.
Things Twine doesn’t have
- Commands. Anything in
<<and>>that Yarn Spinner doesn’t recognise is passed to your game, such as<<play_sound door_creak>>or<<camera close_up>>. See Commands. - 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.