Yarn Tutorial ‐ Basic

Table of Contents

• Introduction
• Yarn File Structure
• Writing Dialogue
  • Lines
  • Expressions
  • Commands
    • Jump
    • Stop
    • Declare
    • Set
    • Flow Control
    • Directions (Custom Commands)
  • Options

Introduction

Yarn is a scripting language designed for writing interactive dialogue. It is designed to be easy to use for both writers and programmers. Yarn uses nodes which are the basic fundamental building blocks of Yarn. Each node contains a header for metadata, and a body for dialogue content. Nodes and their connections between them are what give Yarn its flexibility and power. Although all of your dialogue can be contained within a single node, using multiple nodes leads to better organization and will make your dialogue easier to manage.

Yarn File Structure

A simplistic breakdown of Yarn files is as follows:

1. [File Tags Section]

2. [Node Header]
3. [Node Header Delimiter]
4. [Node Body]
5. [Node Body Delimiter]

6. Repeat 2 - 5 for multiple nodes

1. File tags are file-level metadata. The only requirement is the content must be preceded by a # character, otherwise file tags can contain any character. The file tag section is optional within the Yarn file. An example of a file tag would be #file_version: 2.
2. Node headers contain header tags which are used for node-level metadata. Header tags follow the key:value syntax. Every node header must contain a Title:node_name tag to denote the title of your node and these must be unique within your file.
3. The node header delimiter is ---. This just tells the program reading your Yarn file that the header section is done being read.
4. The node body is where the actual content of your node will go. This is where you will place all your dialogue and expressions.
5. The node body delimiter is ===. This tells the program reading your Yarn file that the node body section is done being read and if anything follows, it's the start of a new node.
6. You would just repeat sections 2 - 6 if you wanted to create multiple nodes.

The following is a basic example of a Yarn file:

#file_version: 1
Title:Start
---
My dialogue goes here.
===

For a more advanced breakdown of Yarn file structure, please check the Yarn Syntax Reference.

Writing Dialogue

Lines

The majority of your Yarn file will normally be dialogue - lines spoken by your characters in the game. When writing dialogue within your nodes it is important to keep in mind that each line of dialogue you want to display generally corresponds to each line within the the node's body. Here is an example of dialogue and how it might be displayed within your game:

Mae: Well, this is great.
Mae: I mean I didn't expect a party or anything
Mae: but I figured *someone* would be here.
Mae: ...
Mae: Welcome home, Mae.

Note - The Mae: tag at the beginning isn't required but some users like to use nametags at the beginning of dialogue to assign lines to different characters as a form of per-line metadata.

As you can see in this example each line is fed to the character one by one. This is generally how Yarn dialogue works and is structured. Each line within the node body is meant to be a new line of dialogue. Although some implementations of Yarn might feed multiple lines of dialogue into the game at a time. This can be useful depending on the style of game being created, but for now we'll stick to thinking about the one dialogue per line approach.

Expressions

Description about in-line expressions here

Commands

Description about commands here

Jump

Stop

Declare

Set

Flow Control

Directions (Custom Commands)

Options

Description about options here