Building Narrative Games with Yarn Spinner

[Music] hello and welcome to building narrative games with yarn spinner hello i'm john i'm a game developer at secret lab at tasmania australia based studio uh i am best known for working on night in the woods and i'm also an author of a bunch of books including the indie game programming cookbook and a few others for o'reilly and i also run a project called yarn spinner hi i'm mars i do machine learning at csiro which is australia's national laboratories equivalent i guess i'm a programmer but not a game maker and i have asked my best buddy here john to teach me about this thing that he makes called yarn spinner what's yarn spinner so what's great about narrative games they're really fun to play they're also fun to make they're a really easy way to get a lot of your like complex world building in where you don't have a big team before you get to the part where you have the scale and the skills to show really well it's really fun to get started on the tell and sometimes that

ends up standing alone in a really amazing way and especially for people who are new to making games making a text based game that then grows from there is a really great way to get the story beats going so narrative games here is like a story but interactive what a concept so they vary a lot in scale so just as there's a range of different kinds of narrative games there's a range of different tools so you might have heard of twine and ink and fungus and this project yarn spinner there are others and definitely in some of the really big studios in some cases if your game is a certain scope it's worth making your own it's probably not worth you writing your own when these alternatives that are out there are free they're open source and they're really supportive communities that exist to help you use them so there's a bunch of them out there as we just said the three that are possibly the best known right now are twine ink and yarn spinner yarn spinner kinda exists halfway between uh twines

complexity and ink's complexity twine is fantastic for working with lots of text ink is fantastic for when you need to have lots and lots of logic controlling the individual lines and yarn spinner gives you the best of both worlds so today we'll be showing off yarn spinner as that nice middle between the really simple getting started but might soon reach the limits of twine and they're really featureful but might struggle to get started if you're trying to make something smaller you have to start a lot of bits that are there for ink in yarn spanner it's really really easy to get started with something small but there's also a lot of room to grow so yarn spinner is a scripting language a domain specific programming language for dialogue it means that you can write it like a screenplay where there are lines of text and the options that follow it that people can choose between in the same space and the same script and same files between cues like you would write a screenplay about like moving a character or changing something about their stance or changing something

about the scene it means that you can have someone write it as if they're setting the scene for this dialogue it's super super fast to get started writing a branching tree of dialogue and they can grow very large without the files themselves getting too complex so if i want to get started with narrative tools john where should i start i'm glad you asked i think you should start with a visual novel because it's a great way to get started in managing assets and constructing scenes and telling a story without the complexity of making physics-driven gameplay or movement mechanics or all the rest that would other form otherwise form part of a larger game so what is a visual novel well the most well-known examples of these kinds of games are those games with like a 2d background where cartoon characters slide in from the sides of the screen and they talk to you the player uh because they're quite text based and almost always and often entirely text based they really quite lend themselves well to romance games uh social themes those kinds of things the genre though is very very broad and it includes anything where the primary

or the only mechanics are speaking to characters and making dialogue choices making textual choices and this is a perfect case for using yarn spinner because while yarn spinner can do a lot more than this if we focus entirely on dialogues then we can start simple and go from there so with that in mind let's make one so we had a bit of debate and i won because i like space so we're going to make a game about being on a spaceship this is why she's called mars so we're going to use unity we're going to use yarns minute we're also going to use visual studio code for doing our text editing and that's really it we're not starting from scratch because this is a talk about building a visual novel rather than learning how to model a 3d environment so we've got that already done ahead of time and we've also put together character models uh some textures some animations these all came from kenny.nl which is an excellent resource for public domain stuff with some additions by me as well we've also written some code which is just two very simple c-sharp scripts that include very minimal utilities just

for moving cameras around or for placing textures on characters that we'll go through as we use them all of this is available right now on github for free that you can download at this point so that you can do this along with us and make your own which we would love to see if you do make your own please tweet at us thank you so what are we going to do today well we're going to download and store yarn spinner we're going to make a basic yarn script and hook it up we're going to block out our story structure and logic we're going to set the scene by incorporating multiple characters and locations we're going to add a bit of polish and then we're going to replace our placeholder text with the final saucy story fantastic we don't have time to cover every single feature of yarn spinner in a very short talk so we're going to focus on a few of the core features of it we're going to talk about branching dialogue variable driven options and also making some custom commands for managing the camera characters and the transitions so i've created a new empty unity scene i'm using uni 2020.3 today this is a completely blank situation let's begin by adding the yarn spinner package so i'll go to the window menu and choose

package manager i'll click on the plus button and add a package from the git url and i'll enter in the url for yarn spinner today i'm using the most recent beta of yarn spinner but if you're watching this in the future then a future version might have been released since then so make sure you use the most recent version so uni will download and install yarn spinner into my empty project cool now that we have yarnspirator installed we should also have a good text editor i like visual studio code me too so luckily for both of us we've got a good extension for visual studio code that we can just install i'll go to the extensions list and i'll type in yarn spinner and hit enter and there it is the official yarn spinner plugin i'll click install click the reload button and now the extension is installed so before we get started with our yarn script we have to decide what kind of story we want to tell and so we made this little slice where you're starting on a spaceship because i love them

and you have the choice between speaking to one of three different people on the ship and if you could choose to speak to the engineer he has a big complaint to you about his job and if you speak to a crewmate you end up chatting and it slowly derails and you try to convince her to give you more of her rations uh and if you speak to the captain she talks about how ready she thinks you are for a crisis and you have this back and forth where you can either convince her that you are totally ready for a crisis or that you're woefully unprepared and then moments later pirates attacked the ship and depending on whether you spoke to the captain and whether you convinced her that you were totally ready for a crisis if you succeeded she'll send you to go and save the day against these pirates but if you didn't speak to the captain or if you did but you didn't manage to convince her that you're prepared for a crisis she will send the garbage crewmate instead to go and save the day and she probably won't save the day so we have this tree structure where you always start in the same spot in the corridor on the ship

you have one of three conversations that you can have with one of the different people on the ship and in different ways they end up in one of these two different endings so how can we represent that in yarn so to get started let's drop in the basic skeleton of the scene so just the bare bones of what we need to start telling our story so here we have a fresh download of the assets that i mentioned earlier and we'll add them to our empty unity project we'll click import and they'll all get copied into the project the place to start is in the scenes folder so in scenes start point so here's our scene we also have a couple of additional things in here that aren't visible so two of these game objects corridor and bridge these are containers that contain just objects that are markers for where the camera is going to go to and where the uh where the characters should get placed that's our environment let's now start adding in some yarn spinner objects into the scene yarnsman works with a collection of script files that we call yarn files these are just

plain text documents and you'll write the contents of your dialogue into them so let's begin by creating our very first yarn script we'll go into our dialog folder that i've made here and we'll right click create yarn spinner yarn script and we'll call it space journey great so here's our new empty file we'll also create a second file called a yarn project and a yarn project exists to link multiple yarn scripts together now today we're only going to work with one yarn script but in larger projects you'll end up working with many and they all get linked together using the yarn project please do not make a large game using only one yarn file even though it is technically possible it is highly irresponsible don't do that you'll get headaches and knives you ryan so let's also create our yarn project we'll right click create yarn spinner we'll create a yarn project and we'll call it space journey project great we'll now add that script into the project so we'll drag the space

journey script onto source scripts there we go now it's in the list and we can click apply and we're good to go now that the file exists let's create some game objects in the scene that will use these files the dialog runner is a component on a game object that runs yarn code it receives lines and options and also commands from the yarn scripts and uses them in the scene it makes lines appear it shows options to the player and also responds to commands which we'll get to in a second you can find a prefab version of the dialog runner inside the packages folder by going to packages yarn spinner prefabs and there you'll find thing called dialog system which contains among other things a dollar grunder as well as a full canvas for showing lines so let's drag it into the scene i'll select it and just hit the f key in the scene view to see it all here is our canvas for showing lines and options the key thing to know about the dialog system is that it's got the dollar

grunter component on it the dialog runner needs a yarn project which is what we created a second ago so we'll drag this into the right position here we'll go to our dark folder and we'll drag the yarn project into the yarn project slot cool if we hit the play button right now nothing would happen because we haven't written any lines yet so let's do that now so because a yarn project can be made up of multiple yarn files when you make a new yarn file it gives the first node the name of the file you gave it however a yarn project will always start running lines from the first node called start so we need to call this node start we want to give it some very basic content so here's some i prepared earlier we've got two lines of text in a node called start and if we run this in unity it should feed us these two lines one at a time now that we're back in unity we're almost ready to hit start we're going to turn off a couple things we don't need right now we'll turn off the fade layer and we'll also turn off the title for the moment we'll come back to those later on and now we'll hit play there's our first line hello world

and click continue to move to the next one this is me oh i made you say it so i made you a quote to sell juicy yarn spinner will send lines one at a time into the game it'll also send other things like options and commands we'll come to those so let's get started with our three different characters if we want to make it so that you can pick between which of these three different characters you want to speak to let's make this note again we're going to give it some options here we're using the first and probably most popular part of the yarnsmith syntax which is these little arrows that mean options after this first line is played another day in space fleet might go have a chat these three options will be presented the things that are preceded by arrows you can choose to go see the engineer as per the orders you were given you can choose to meet up with your friend the crewmate or you can choose to go and talk with the captain then depending on which one you chose the nested dialogue is shown

so we're going to save when you go back into unity and if we play again this time it should present us with that option so it's another day in space fleet and i might go have a chat i'm gonna decide to go and talk to the captain and she says hello i am the captain so now that we have these different options what if we wanted to add further and more complex branches we could add them inside the same node we could keep nesting and they would give us more options but at a certain point that would become way too complex so instead we use this node system let's instead make it that each of these sub-branches of that first conversation are instead their own node here's one i preferred earlier instead of having those nested dialog options here they just jump using the jump command to go to the node that's called that thing if we played this it would do exactly the same thing as before but it's a more nicely laid out file that better lends itself to expansion so the game starts the same way every time in that we get the choice to speak to the captain the engineer or the crewmate but no matter which one we choose we end up on the bridge because space pirates have

attacked and we want to now add in that ending here we add a new node called bridge ending and if we want to add jumps to it we can just put it at the bottom of each of those conversation nodes now no matter which one you pick afterwards you jump to the bridge ending node let's see this in action we'll run the game we'll talk to the captain everyone picks the captain everyone picks the captain and then pirates oh no crewmate go deal with those pirates fantastic that's our story well done that's going to win awards but what if we want to make the ending change depending on what you did let's instead make it have those multiple endings that we talked about before where either you can save the day or they'll send the useless crewmate we have to make it so that when you talk to the captain you have different conversation options that let you convince her that you are totally up for the challenge if a crisis happens but we also want to make it that you can fail if you choose the wrong thing here we're just going to make it really simple she's going to ask her if you think you're ready you're going to say i want to go on more missions and she's going to say do you think you're ready and if you say yes instead of saying no we're going to set a variable

variables store information in yarn spinner right now we're just using a number we're storing it inside of a variable called away mission readiness and so we say set away mission readiness plus equals one which means it goes up by one variables in yarn spinner begin with a dollar sign after we have set that we'll see another line where the captain says really and then we'll get another set of options these options and that line will only appear if we chose yes at the start if we say yes then away mission readiness will go up by one again now that's important because we want the good ending to only happen if away mission readiness is high enough and high enough in this case means two and now we're going to start with our first conditionals where we're going to get different behavior in the ending depending on the value of this numeric variable here we're going to replace the contents of the bridge ending node to add this extra part now either way the captain will say pirates and you will say oh no and if you didn't manage to speak to the

captain or convince her that you are ready for this then she will have the same ending as previously where she will ask the crewmate to go and deal with those pirates however in the else clause which will be activated if your away mission readiness is two which means you said yes twice then you were just telling her how ready you are for crisis so she tells you to go deal with those pirates and you're very excited about that so let's go back in unity and see how we can get to these different endings john do you want to have a go i do so let's talk to the captain all right they are the captain and we want to go on more missions do you think you're ready you're so in love with the captain every time you pick the captain my one true love am i ready yes really yes pirates oh no okay but we were just telling the captain how ready for this we are so time to go deal with the pirates hooray however let's run that again but this time we're going to do a bit of a different way

we're going to talk to the captain and this time only listen i got reasons for this am i ready yes am i really ready no okay now when we get to the ending the crewmate goes and deals with them so because we didn't hit both of the points where we changed the value of that variable the condition wasn't met and that means that different content ran you were only away mission readiness one john step it up one day i'll get there so we've had a great time looking at this empty sky and watching our story unfold thus far but what about all those assets that john made how are we going to see the visuals of this story and how are we going to make that work through yarn spinner without having to write too much code over to john so so far we've been working with lines and options lines and things that we get to see on screen that's the text options of the buttons we get to click on but there's a third kind of thing that we want to be able to send from yarn spinner into unity and that's commands commands are like stage

directions they tell the game to do something that isn't show some text so what we need to do is to have a command that makes the camera be in a certain location now remember how we showed you those markers in the scene the corridor on the bridge we're going to add some code that makes the camera be in that right location and also make it so that yarn spinner can invoke those functions we've written some scripts that contains the code that we need to make this happen so that's in a file called visualnovel.cs being a component it needs to be added to a game object so we'll add that in now in the scripts folder here's visual novel so i'll go to the game object menu create an empty i'll name it visual novel and i'll drag the visual level component into it let's open up the code for visual novel and in here i've got my function change camera location so our next step is to make it so that yarn spinner can

call this function we need to make sure that the commands are known to yarn spinner before any yarn scripts run because otherwise we might end up in a situation where the yarn script tries to run a command that doesn't yet exist so we'll do this in the awake function which is called before anything else happens for the script so inside awake we'll find the dialogue growner and store it in a variable dialogrunner we'll also get the fade overlay that's for later and then i'm going to add in the call to add command handler add command handler registers a command with the dialog runner here we're saying the command is called camera it takes a parameter which is a location and when the command is run it calls this function change camera location that's this here now we can use this command in our yarn scripts to change the camera location so if we go back to our yarn script we know that at the start of the game we want to start in the corridor so at the start of the start node we put a camera corridor it's

going to call that set camera location with the parameter corridor that's going to go and find in the scene that marker we put at a location in the corridor called corridor now when we want to switch to the bridge we're going to put a line in that says camera bridge the camera will move to the bridge and it will seem like you as the player point of view have moved to the bridge now if we play it this should display us moving around the different parts of the environment and there we are we begin in the corridor we're gonna go see your favorite captain we do the conversation about whether we're ready to go on away missions totally not ready and now oh no but now it's pirates on the bridge because we've moved the camera into the right location i must admit it's way scarier than pirates in the corridor what if they end up in the caribbean so as nice as it is speaking to an empty corridor we probably want to use those characters that jon has made for us so if we have a look at our characters we can see that we have that engineer that crewmate and that captain as different models but how can we make them appear in the different scenes as if we're speaking to them depending on our

actions back in our visual novel.cs we actually have a function for that we're going to have place character take a character name which is either going to be engineer crewmate or captain and a marker name in the scene to move that character asset too this is then going to find the prefab if it has never been in the scene before it's going to make it and if it has been in the scene a different location it's going to move it to the new spot we want it to be in then like before like we did with the camera we're just going to find the marker with the name that we wanted and then we're going to set the character asset's position and rotation to that we can add a command for this in our awake function in the same way that we did for camera now we're going to have a command in yarn called place and it's going to take two parameters string and string for the character model you want to move and the location marker you want to move it to this means now we can put cues in our yarn file that move our characters around if we want to speak to the engineer we want the engineer to appear if we speak to the crewmate instead we want the crewmate to appear if we speak to the captain instead we want the captain

to appear the bridge ending is different because we want different characters to appear based on what our ending is going to be so we'll always have the captain visible and the engineer but we'll only see the crewmate if the captain decides that the crewmate should go and deal with the pirates otherwise the crewmate doesn't even come to the bridge probably shamed by how awesome you are getting chosen to go on the away mission i would be so we're almost done let's go back to unity the visual novel script makes use of an asset called character list which just contains the collection of references to character prefabs so that's this asset here and all this is is just a list of prefabs so to make the visual level script aware of that list we'll just drag it in and then we'll hit play we see our opening lines and just to annoy mars i'll talk to the captain and there they are great so there's our character appearing on screen and now we have the engineer on the left and the captain on the right in the right locations on the bridge so maybe it's a bit weird that the captain is so happy about there being pirates and we want the models to look slightly different in

different contexts so how about we change the character poses and facial expressions to one of a few predefined options the last two commands we added were done by calling add command handler on the dialog runner and that works really well because those kinds of commands are things that relate to the scene as a whole we're changing the location of the camera where creating a new object into the scene but setting the expression or the pose of a character is something that's quite specific to that character so what we should do is add our commands onto scripts on the characters themselves all three of these character prefabs have a character script attached this exists for two reasons it contains just the list of all the expressions that they can have and it also contains a bit of logic there's two methods in here that we want to make use of set pose and set expression set pose uses an animator to set the pose of the character and set expression finds an appropriate texture and applies it to

the face we want these two methods to be able to be called the yarn command attribute allows you to make a function on a script visible to yarn spinner so by saying yarn command pose we're able to say pose name of a game object and then any other parameters that we want to pass in so we could say for example pose engineer hand on hip and what yarn spin will do is it will find the appropriate game object and call the appropriate method so we've added the pose command while we're at it we'll also add the expression command which works in the exact same way and now we can make use of these commands inside of our yarn script the most emotional part of the entire story is the high stress situation where the space pirates attack so what we'll do is we'll have our characters react with emotion when the engineer and the captain are visible in the scene we'll use the pose and expression commands that we just added

to tell these two characters to adjust their pose and expression will tell the engineer to have a hands-on hips pose and we'll have the captain have a hand at mouth pose the engineer will be angry and so will the captain if we're not going to go on the away mission then when the crewmate arrives we'll have the crewmate be extremely happy we'll change the expression to a happy one after the captain says crewmate go deal with the pirates we'll also make the captain have a pointing gesture as well but if the uh captain doesn't want to send the crewmate they want to send you the player then we'll use a different expression and actually the same pose all right with that i think we're going to test it out okay so let's get to that point in the story so we'll go talk to this character great and now they're responding with different expressions and different poses so by adding in that attribute onto those methods it makes it very easy to just call those functions from within your scripts

mars hand on hip intrigued john i bro raised all right so we have our visuals but it's not very zazzy yet so how about we add that magical polish that everyone talks about john polish now yes so one of the greatest ways to establish that we're changing a location is with the classic fade out fade back in let's do that the ui overlay just contains a fade canvas group and the canvas group you can modify the alpha value of so what you just animate this inside that by the way is just an image set to fully black so that's how we get our fade to black so we want to be able to make the fade overlay fade in and fade out we could do this with the yarn command attribute like we did with the poses and the expressions but because the fade is kind of like a global scene thing rather than a per object thing it makes more sense i think for it to be a command that we register globally using add command handler so let's go back into

visual level.cs and in our awake function we will add in the two commands fade in and fade out and these just invoke these functions here fade in and fade out one thing that's different about these commands is you'll notice these return a co-routine which means when we say return start corrupting yarn spinner will actually wait for that co routine to finish before continuing so now if we go back to our space journey.yarn we can add fade ins and outs every time we change something about the scene here when we move the camera to the corridor at the beginning of the game we then fade in we're going to fade in from black as we start each other node we're going to fade out place all the characters we want to be in the scene and then fade in so that they're already there and when we move to the bridge we're going to fade out before we move the camera place all those characters change their pose and expressions so that when we fade back in all of that's already there it should seem a bit cinematic

that's cinema baby baby and as we go from node to node we'll also see fade outs and then fade back in and that's great this is pretty good but mars i think it's missing something you mean my zazzy title i mean your zazzy title yeah you do so back in our yarn script just like we did before to move the camera to different parts of the scene we can also move the camera to right in front of that title we had floating out in the void in space and it's going to look like a 2d effect has appeared on screen so we can use that same corridor command but then we can also add that fade in and fade out like we wanted to for cinema effect and in between we have a weight so that it doesn't just fade in and immediately fade out before you had a chance to read my awesome title screen so weight is a command that's built into yarn spinner we don't have to define it it's just there and it takes one parameter which is an amount in seconds so we are going to fade in wait for two seconds then fade out easily adjustable if you want to be gratuitous so back in unity we actually have to turn our title canvas back on because we hit it earlier before we were doing anything with it

and now we press play we should get some gravitas some fanfare space journey all right there's one last bit here and because this is nothing to do with how to use yarn spinner and more what if you just had the script written we're just going to go to the script that was written and structurally this is the exact same thing we start with uh our fade ins and our open lines and our initial choices our start node yep and then based on what we chose we go into a longer conversation the only difference to what we did before is there's just more lines as well as some more instructions to pose the character or set an expression we've got some additional choices um here we are in the captain node and we're using the away mission readiness variable here as before we also have uh another variable called captain is friend uh we set that to true uh if we hit a certain point in the conversation tree otherwise it's uh set to false uh

and it defaults to false as well the bridge ending remains again very very similar if our away mission readiness is less than the threshold it needs to be then we get the crewmate going off to have adventures um or to betray us who can say otherwise we get to go and defeat the pirates and then we make use of the captain is friend variable that we set earlier to control whether the captain says i'll miss you if you die friend or i'm sure somebody will miss you if you die and that's it that's the visual novel we made that super super quickly and while we didn't start from completely scratch there wasn't really much beyond what we did here this is a template that you can make use of the code and all the assets are available for free on github for you to use and build off if you end up doing something more with this i'd love to see it please let us know so today we've only covered a tiny fraction of what yarn spinner can do and you might be wondering if i've become an expert at this level i've made awesome little visual novels where do i want to go to

next to find more functionality of yarn spinner well you can try adding voiceover support or localization which are very easy with built-in systems for yarn spinner and unity you can add more advanced logic like we started to hint out in our longer script and it can expand as far as you like with those same conditionals there are other conditionals in yarn spinner and other types of variables we haven't shown examples of and of course using those commands that speak to c sharp and unity you can have all sorts of behavior that is only bounded by what your game engine can do the game that yarn spinner was originally written for night in the woods makes extremely heavy use of the command system that's available so everything ranging from camera locations character poses triggers of animations sound effects it's all done through commands in yarn spinner basically every time there's a cut scene then that's yarn spinner at work yarn spinner is available from github at this address it is freely available under the terms of the mit open source license which basically mean that you can use it for commercial and personal work as long as you just give

us a credit you can find the official site for yarnspinner at yarnspinner.dev and the official twitter at yarnspinnertool although really that is just me posting online you can also join our wonderful and super friendly community on discord at discord.gg yarnspinner thank you so much for following along with us today this has been john and you can find him at dysplaster on twitter and that was mars you can find her at the martian life on twitter again thank you so much for being a part of this we hope you find that inspirational uh educational uh go and make something cool with this and then show us please do and also don't forget to fill out your speaker reviews because it helps us make more awesome content like this thank you and have a great gdc bye [Music]