View fullsize

We recently announced that we're building Night in the Woods for mobile! We're super excited about this, so we thought that we'd share a bunch of technical behind-the-scenes stuff on our blog over the coming weeks and months. This is the first of those posts! 

Yarn Spinner is the dialogue engine that we wrote, and was used in Night in the Woods. It’s open source, freely available, and we think it’s pretty powerful.

One of the reasons why we think Yarn Spinner is powerful is that it’s designed to focus on as little as possible. There’s literally only three things that Yarn Spinner can do with your game: it can send lines of dialogue, ask for a selection among a group of options, and send a command for your game to interpret.

The idea behind this is that your game can add what it needs to on top, rather than being forced to fit inside the ideas that we had when we first wrote the system. There are several excellent dialogue systems that are designed to be very good at operating within the structure of a role-playing game, or a choose-your-own-adventure system (Twine is a great example of this last one), but for Yarn Spinner, we wanted the system to be more generalised, and able to be applied to a wide variety of games systems.

The consequence of doing that, however, is that a game needs to do more work to add the features that it needs. While we built Yarn Spinner with NITW in mind, there are several features that are quite specific to the game. 

In this post, we’ll highlight some of the cooler things that Alec Holowka, the lead developer of Night in the Woods, built on top of the Yarn Spinner system to support its needs.

Example Dialog

Here’s an example of the kind of dialogue that exists in Night in the Woods. Here’s Mae and Gregg, planning on going to Donut Wolf:

Gregg: They got pancakes now! :)
<<close>>
//angus walks across the screen and off the left//
<<walk Angus AngusOffLeft>>
<<wait 3>>
Angus: fine.
<<lookUp Mae>>
<<lookUp Gregg>>
Gregg: \o/ D:
Gregg: RIDE THE CHARIOT!
<<dilate Mae .85 .5>>
Mae: TO DONUT HELL!!! \o/
<<runNextLinesTogether 2>>
Mae: {width=8}[shake=.05]AWOOOOOOOOOOOOOOOOO!![/shake]
Gregg: {width=8}[shake=.05]AWOOOOOOOOOOOOOOOOO!![/shake]

This dialogue is part of the raw source code of Night in the Woods. When the scene loads, the dialogue attached to the characters is parsed; first, it’s parsed into a data structure called a parse tree, which is then converted into a simple binary representation. This process is quite similar to how other code gets compiled into a binary that can be run on a machine.

At the end of this process, the resulting bytecode for the above dialogue snippet is this:

Node GreggFQ4Intro:
     0   L0:
             RunLine         GreggFQ4Intro-0           
             RunCommand      close                           
             RunCommand      walk Angus AngusOffLeft                      
             RunCommand      wait 3                          
     5       RunLine         GreggFQ4Intro-1          
             RunCommand      lookUp Mae                      
             RunCommand      lookUp Gregg                      
             RunLine         GreggFQ4Intro-2         
             RunLine         GreggFQ4Intro-3        
    10       RunCommand      dilate Mae .85 .5                      
             RunLine         GreggFQ4Intro-4       
             RunCommand      runNextLinesTogether 2                      
             RunLine         GreggFQ4Intro-5      
             RunLine         GreggFQ4Intro-6     
    15       RunCommand      close                           
             RunCommand      irisOut 1 wait                      
             RunCommand      sectionTitle GreggFQ4Intro BeaCar                      
    18       Stop                                            

String table:
GreggFQ4Intro-0: 
    Gregg: They got pancakes now! :) (GreggFQ4Intro:1)
GreggFQ4Intro-1: 
    Angus: fine. (GreggFQ4Intro:6)
GreggFQ4Intro-2: 
    Gregg: \o/ D: (GreggFQ4Intro:9)
GreggFQ4Intro-3: 
    Gregg: RIDE THE CHARIOT! (GreggFQ4Intro:10)
GreggFQ4Intro-4: 
    Mae: TO DONUT HELL!!! \o/ (GreggFQ4Intro:12)
GreggFQ4Intro-5: 
    Mae: {width=8}[shake=.05]AWOOOOOOOOOOOOOOOOOOOOOO!![/shake] (GreggFQ4Intro:14)
GreggFQ4Intro-6: 
    Gregg: {width=8}[shake=.05]AWOOOOOOOOOOOOOOOOOOOOOO!![/shake] (GreggFQ4Intro:15)

Each line of this bytecode is then executed, one after another, by Yarn Spinner, which sends along the lines, options and commands that it encounters. This is part of the standard behaviour of how Yarn Spinner works in any game; where Night in the Woods differs is what it does with its lines.

Character Names

Night in the Woods shows its dialogue in speech balloons that are attached to the characters. In order to correctly position them, NITW needs to know which character a line should be shown attached to; to figure that out, NITW looks at the start of each line, and figures out if it begins with a name followed by a colon.

If it does, then the game checks to see if that character is in the scene; if they are, the speech balloon for the line is attached to that character.

Emoticons

Emoticons, or “what we used to use before emoji were a thing”, are those little faces that are composed out of plain text - stuff like :) and :(. Night in the Woods uses these to control player expressions, by looking for any emoticons that it recognises. When it encounters one, it triggers a corresponding animation action, such as animating from the neutral expression to a smile.

There are several different kinds of emoticons. In addition to the smileys that control facial expressions, the game also includes several gestures as well; for example, whenever Mae puts her hands on her hips, it’s because the line included the emoticon “<o>”; when she throws her hands up into the air, it’s triggered by “\o/“.

This is true for other characters as well. When Gregg starts flailing his arms after Mae meets him in the Snack Falcon at the start of the game, it’s the result of using the emoticon sequence “:) \o/“

Markup

Night in the Woods responds to custom syntax within lines that let a writer mark up the dialog for visual effects. For example, when a character needs to shout, the line contains markup like this: 

Mae: {width=8}[shake=.05]AWOOOOOOOOOOOOOOOOO!![/shake]

This causes the specific range of letters to be delivered in a shaky style. The markup also supports effects like character size, color, and balloon position, as well as fun effects like making a line of text wave.

Commands

Finally, Night in the Woods makes extensive use of commands. In Yarn Spinner, if you wrap some text in <<angle brackets>>, it won’t be sent to the game like a line of dialogue. Instead, it’s delivered as a command; the intent is that the game will manually parse its contents, and perform some action in the game.

Every time you see a character do anything besides talk, it’s the result of an action. There are a huge number of possible commands in the game; on top of the usually expected actions like sit, stand, walk, and jump, commands can also be used to control where and how a character is looking, the dilation of their eyes, and whether they’re visible or not. This last command is extremely important, since it’s used to control whether a character is present in a scene on a given day.

What’s interesting about NITW is that just about all of the gameplay logic is driven through Yarn Spinner. The language wasn’t designed to be a general game logic control system but it turns out it’s pretty good at this. That’s cool.

Taking it further

Several of these are very specific to NITW and its systems, while others are things that could probably apply to most games. As we continue to work on Yarn Spinner, we’re looking forward to making the project the best dialogue system it can be. For more information on Yarn Spinner, visit the project’s page on GitHub at https://github.com/thesecretlab/YarnSpinner.

If you're interested in more information on how we made Night in the Woods better with our open source software, check out Jon's talk from GDC 2017 on YouTube. 

Follow us on Twitter for more news and updates: @thesecretlab

---

Earlier this year, we were approached by the rad folks at Infinite Fall with a very interesting challenge: could we please add support for localisation in Yarn Spinner, the dialogue system we wrote, for Night in the Woods?

Yarn Spinner was written to be a more advanced interpreter for the Yarn language, a Twine-inspired tool for writing interactive dialogue. Yarn Spinner lets you write your game's dialogue in a very natural way, with minimal technical syntax and a strong focus on getting your words into the game.

Because Yarn Spinner has such a strong focus on minimising the amount of stuff you have to write on top of your dialogue, we have to be careful whenever adding new features to the language. Our goal is always to reduce the amount of stuff you have to think about when writing. However, any kind of localisation system requires you to add additional information, in the form of a key that links a line's original text that of a translated version.

We created what we think is a pretty neat solution to this: hashtags. To localise a line of text, you add a hashtag that contains a short tag, like this:

However, Night in the Woods has a lot of dialogue. Like, buckets of it. Tagging each and every line would be hugely laborious. Fortunately, we already have a tool that's very good at quickly and thoroughly processing large amounts of Yarn dialogue: Yarn Spinner itself!

We therefore put together a little tool that can extremely quickly (like, 2 seconds quickly) tag every single line of dialogue that needs it. The tool only counts text that needs localisation - that is, anything that a player will see. It ignores all other stuff, like if statements and other behind the scenes stuff, as well as any line that already has a tag, which allows you to run the tool on files that have been partially tagged. In other words, it's a tool you can feed your dialogue through without worrying about anything it's doing.

Once you have some tagged dialogue, you can then generate a file that contains every line's text, as well as its localisation tag. The tool generates a CSV spreadsheet, which is the easiest format for most people to read.

Once you have the spreadsheet, you can send it off to your translators. In our case, we sent it off to a translation team in Italy, who converted the entire text of the Night in the Woods demo into Italian. They then sent back a spreadsheet that contained the Italian versions of all of the lines. We then dropped this into the Night in the Woods demo, and presto: localised!

The code for the localisation tool has already been merged into the development branch of Yarn Spinner, and we'll be putting out more info on how to use it soon. We can't wait to see more games in more languages using Yarn Spinner. Stay tuned for more!

Complicated stories don't have to be complicated to build. We've already seen how Twine has made it easier than ever to create interactive fiction. Another tool, Yarn, has taken inspiration from Twine, and made it awesomely simple to craft interactive fiction.

This is where we come in. We also love telling stories, so we're absolutely delighted to introduce Yarn Spinner, an open source implementation of the Yarn language that's designed to make dialogue in your games a snap.

We built a tiny little demo game, which is set in space and available for you to play right now! It requires a keyboard to play it, and is compatible with most modern browsers.

View fullsize

View fullsize

What's Yarn?

Yarn is a very simple text based format, designed to let you write interactive, branching conversations with the greatest of ease. Here's a snippet:

    // Check to see if we've spoken to Sally already
    <<if $spoken_to_sally is 0>>
        // We haven't spoken to her - run the initial conversation
        Player: Hey, Sally.
        Sally: Oh! Hey.
        Sally: You kind of snuck up on me.
        Sally: Don't do that.
        
        // Remember that we've spoken to her
        <<set $spoken_to_sally to 1>>
    <<else>>
        // Run a different conversation
        Player: Hey.
        Sally: Hi.
    <<endif>>
    
    // Now present some options to let the player choose how they'll respond.
    [[Anything exciting happen on your watch?|Sally.Watch]]
    [[See you later.|Sally.Exit]]

Yarn's used in a number of cool games, including Night In The Woods and Knights and Bikes.

What's Yarn Spinner?

Yarn Spinner is a parser and runner for Yarn. It's written in C#, and is designed to be super simple to integrate into Unity games. You just drag and drop a few objects, drag in your Yarn file (which you've written using the excellent Yarn editor), and you've got dialogue running!

I'm already using Yarn's original parser. What does Yarn Spinner do differently?

Yarn Spinner adds a number of useful features:

• Functions are now part of the language, and you can write your own in C#, where they'll be available to your scripts.
• The expression parser is quite a bit more powerful, and can handle most things you throw at it.
• Yarn Spinner is available as a separate .DLL file, which means that it's more separated from your Unity code.
• Yarn Spinner adds more types of values to the language. Where you previously only had numbers, you now also get strings, booleans and null! Woo, programmer toys!

Is it Open Source?

Yes! The whole source code is available under the MIT license, which means that you can use it in commercial games if you want! The only requirement is attribution.

Where can I learn more?

Check out the Yarn Spinner page, here on our site, or the GitHub page to learn more.