Writing Yarn in VS Code

Learn how to use Yarn Spinner for Visual Studio Code as your Yarn editor.

Now that you've got Visual Studio Code and Yarn Spinner for Visual Studio Code installed, it's time to learn how to use it to write Yarn Spinner Scripts.

Writing Yarn Spinner Scripts with VS Code

Yarn Spinner for Visual Studio Code is designed to work with a folder, not single files.

You should always work on a project-by-project basis with folders containing your .yarn file or files in it, even if your narrative only has one .yarn file, put it in a folder of its own.

If you're working on Yarn Spinner Scripts that are part of a game—for example a Unity game—you're likely to have a folder for your narrative/dialogue within the project structure.

If you're using VS Code as your C# editing environment with Unity, you can reach your Yarn Spinner scripts by choosing the Assets menu -> Open C# Project from within Unity, and then navigating to the appropriate folder within VS Code to work with your Yarn Spinner Scripts.

If you're not using VS Code as your C# editing environment with Unity, you can still open the Narrative folder with VS Code to work with your Yarn Spinner Scripts.

Opening a folder

For this example, we'll assume you have a folder that you want to use to work on your story. The folder in our example is called YSDocsDemo . Inside this folder, we've made a single Yarn Spinner Script named Chat.yarn.

You can also open an empty folder, and make the Yarn Spinner Scripts within VS Code.

A folder on disk containing a Yarn file.

If we open VS Code, the default screen will have an Open button right in the middle.

The Open button on the Visual Studio Code start screen.

Click this button, or choose the File menu -> Open Folder..., and then open the folder containing your .yarn file:

Opening a folder containing .yarn files.

When the folder opens, you'll see the sidebar of VS Code change to reflect the contents of the folder. You can click on a .yarn file to open it in the text editor:

Choosing a .yarn file to edit.

You can also use the File menu to make a new file inside the folder:

Choose New File... from the File menu.

VS Code will then ask you to name your new file:

Name a file with a .yarn extension.

Working with Yarn in Visual Studio Code

With a .yarn file open in VS Code, you can verify that the Yarn Spinner for Visual Studio Code Extension is active by looking in the bottom right-hand corner of the screen, and locating the words "Yarn Spinner":

The status bar of VS Code showing that the Yarn Spinner extension is active.

The bottom right-hand corner of Visual Studio Code window will only show "Yarn Spinner" if both the Yarn Spinner for Visual Studio Code extension is installed, and the currently active file is recognised as a .yarn file by its extension.

You can use the text editing view to work with .yarn, and to write your narratives. The Yarn Spinner for Visual Studio Code extension provides all sorts of features to make this process easier.

This section of the documentation will talk about Yarn Spinner Script features, like <<jump>>, and others, that you won't have encountered yet. Review it, and then as you work through Scripting Fundamentals and Advanced Scripting, revisit this page and see how the features you've learned about work with the Yarn Spinner Editor.

For example, if you hold the Command key (on macOS) or the Control key (on Windows or Linux) and hover over names of nodes in, for example, `<<jump>> statements, you'll be able click on them to move the editor view to the Yarn that represents that node:

Command/Control allows you to click a node name to jump to its definition.

You'll also be offered autocomplete suggestions based on node names that exist in your project. For example, if you create a new <<jump>> statement, you'll be able to pick from your nodes:

Choosing a node to jump to with autocomplete.

If your Yarn Spinner Scripts also use variables, which you'll learn about shortly, Yarn Spinner for VS Code will help out as well. For example, when you <<declare>> a new variable, you can add a comment with three / in front of it to provide a description of the variable:

Using the the special /// comment syntax to describe a variable.

Then, when you use the variable, you can hover over it in VS Code for a reminder of its purpose (and its default value):

Viewing a variable's description.

Variable names will also autocomplete when you try and use them, and errors will be show if there are type isues. So, if you <<declare>> a variable to be a certain type, for example a boolean:

Using `<<declare>> to declare a boolean.

... and then attempt to use that variable in a way that would produce an error. For example, by attempting to assign a number to it, then Yarn Spinner for Visual Studio Code will show an error:

An error arising from trying to use a boolean like an integer.

You'll also be able to see documentation comments from commands defined in your game's C# source code:

Comments from C# commands in your Yarn scripts.

{% hint style="warning" %} Nodes can be spread across as many .yarn files in a single folder as you like. {% endhint %}

Working with nodes

While Yarn Spinner is a text based language, our Yarn Spinner for Visual Studio Code extension provides a handy Graph View.

You can open the Graph View for whichever .yarn file you're currently working with by clicking the Graph View button in the top right-hand corner:

The Graph View button.

You might notice that, when you first look at the Graph View for a .yarn file, all the nodes appeared stacked on each other, like this:

Nodes stacked on each other in the graph view.

To make sense of things, and better understand the <<jump>> use between nodes, you can rearrange the nodes by clicking and dragging to wherever you want them:

Rearranging your nodes.

Any time the <<jump>> command is used, it will be visualised as a line with an arrow, leading to the note that's being jumped to. If you <<jump>> to a node in another .yarn file, it will be visualised as a line leading to a small circle:

The position of the nodes will be stored in each node's header:

The position of each node is stored in the header.

You can use the Add Node button, found at the top of the Graph View, to add new nodes. New nodes will appear in the Graph View, and in the text editor:

The Add Node button.

Double-clicking a node in the Graph View will jump to that node in the Text View:

Double-clicking a node in the Graph View to edit it in the Text View.

If you have a lot of nodes, you can use the Jump to Node menu, in the top right-hand corner of the Graph View, to jump the Graph View to a specific node:

The Jump to Node menu.

At any point you can also click Show in Graph View, found above each node in the Text View to jump the Graph View to it:

Show in Graph View

Customising the Graph View

You can add some additional metadata to the headers of each node to customise your Graph View, for ease of understanding the relationships between areas of your script.

Colouring Nodes

For example, if you add the color field to the header, you can colour-code your nodes:

Colour-coded nodes.

{% hint style="info" %} You can use red, green, blue, orange, yellow, or purple. The colours that you see may be different, depending on your VS Code theme. {% endhint %}

The `

colorfield works like any other header element, and goes below thetitleand above the---`:

title: NodeName
color: purple
---

===

Grouping Nodes

You can also group your nodes by adding the group field to your node headers. For example, if you add group: Main_Options to the header of the Volcanos, Dogs, and Trees nodes, you'd end up with this:

Grouping nodes in the Graph View.

Sticky Notes

You can also use the Add Sticky Note button, found at the top of the Graph View, to add Sticky Notes to your Yarn Spinner Scripts:

Sticky Notes are just like normal nodes, but styled to stand out, so you can use them to leave notes for yourself, or your team, to add context to your narratives:

Because Sticky Nodes are just normal nodes with an extra header field (they become a Sticky Note when you add style: note to their header), you can use the color: field to set their colour. For example, the notes in the above screenshot are created with the following Yarn Spinner Script:

title: Note_Evil
style: note
position: 521,336
---
TODO: Add more evil options in here.
===

title: Note_Love
style: note
color: red
position: -128,171
---
I don't like the fact that the witch is totally unaware of what love is. Can we give them some more lines here?
===

Using the Command Palette

The VS Code Command Palette has a number of useful Yarn Spinner features as well. Summon the Command Palette by pressing Shift + Command + P (Mac) or Ctrl + Shift + P (Windows/Linux), or choosing the View menu -> Command Palette..., and type "Yarn Spinner" to filter the available commands to those provided by the Yarn Spinner for Visual Studio Code Extension:

The Command Palette

From here you can Preview Dialogue, which will allow you to play through your narrative, right inside Visual Studio Code. To learn more about this, read Previewing Your Dialogue.

The Export Dialogue as HTML... option will export a self-contained playable version of your narrative as an HTML file, which is otherwise the same as the experience your get when previewing.

The Export Dialogue as Graph... option will allow you to export a .dot file of your graph. To learn about .dot files, check out the GraphViz documentation: https://graphviz.org/doc/info/lang.html

And finally, the Export Dialogue as Recording Spreadsheet... option will allow you to export a spreadsheet, which can be useful for voice actors recording dialogue.

You can also use the Command Palette to turn off all the Microsoft-provided "AI" "features by typing Chat: Hide Copilot and hitting Return/Enter.