Turn Your Writers Into Programmers: Greyboxing Narrative with Story Languages

[Music] hi everyone my name is john my name is ryan and we're going to teach you some amazing stuff of next little while we're going to teach about what narrative gray boxing is we're going to show you how to save time and money and write better stories and we're going to show you how it's a good idea for writers to be programmers even just a little bit so i am john manning i work at a studio called secret lab we're based down here in tasmania australia and we're best known for having worked on night in the woods and i'm also the lead developer of a project called yarnspinner which you'll hear quite a bit about over the next little while and i'm ryan i'm the author of a couple choose your own path books which are non-linear versions of shakespeare like to bear not to be in romeo and or juliet i've also written a bunch of comics and in terms of games i've contributed to destiny 2 dlc stick it to the man and ava which is a fun game where you play an avocado and i've also got some development

experience too not just as a writer so lots and lots of dialogue tools are node based and node based means that each line of dialogue is a node on a graph and those nodes are connected from one point to the next and if a node has multiple connections coming out of it that means there's options this is the paradigm used for lots of great commercial tools out there like chat mapper articy draft lots of particularly great dialogue tools on engine specific asset stores plus of course there are lots of studios who create their own tools to suit their own needs there are a lot of great gdc talks out there about these internal processes so for example kerry patel and david simchik gave a great talk at gdc 2019 about the obsidian internal dollar tool elon ruskin did a great talk uh rule databases the textual dialogue and game logic in 2012 and also jason gregory did a talk which is also fantastic about the internal dialog system used in the last of us at nudi dog now all of these are effectively

structured data entry uh you're working with a data structure that your designers have put together and that you're filling in and we can call these graph approaches to branching dialogue these are very very easy to visualize you can show some on the graph and see the structure these are less easy to write because you're often going in and out of node views and you're drawing lines between them and it can get it can get fiddly one of the most popular tools for this is spreadsheets where you simply have a grid of data with lines dropped in it works really well for simple things but for branching dialogue it's less effective i've used these tools as a writer before and they get the job done but you kind of wonder is there a better way spoilers so something that we've been working on is a bit of an alternate approach rather than working with a graph or a table we're going to talk about tools that combine a writer-friendly screenplay approach with a programmer-friendly language approach and we'll focus on a particular tool as

our example but as we'll make clear this is a pretty broadly applicable technique because we want to have flow control and ease of writing so yarn spinner is our tool that has been in use for a while now it is a combination of a screenplay and also a gameplay flow language it has designs that you can write lines of dialogue and just stop there if that's all you want but you can do more as well it's funny you should mention screenplay format because i've used that before spreadsheets are often used when the game is constantly calling out the state of line giving the next line and with screenplay it's more like the game is saying scene give me the next scene and this works great when you have uh sort of linear chunks of back and forth for your story if it's more like an interactive movie but you kind of get the sense of you know this is the tool we already have so this is the tool we're going to be using it's not designed for gameplay it's designed for screens for screenplays so to augment the screenplay format yarn spinner is also a full

programming language and here's where it gets interesting because when you turn your writers into programmers that's the title of the talk then you enable some really interesting workflows and possibilities so yarn spinner isn't the first system out there that tries to create a story programming language games going back to the infinity engine and earlier so games like baldur's gate and iceland dale those kinds of things use a scripting language to control their dialogue and double fine also has got some great talks on the on the dc vault about how they did this similar thing for brutal legend and broken age and sometimes you're not even that fancy i've done writing for games in word documents i've done it in google docs and when you're writing a branching narrative in a flat structure like a google doc it can get a little messy as you can see on this slide uh here's the situation adapted from an actual game i wrote where we're keeping track of whether or not this professor has chalk simply by saying if the professor has chalk in the document it made it decent for me to write so i can keep all that state in my

head but you're copying and pasting by hand into the game at this point it's not a super terrific workflow right also how do you encode player can't progress so yarn spinner is an open source project it is released under the mit open source license it's available on github and it's heavily inspired by twine and was used first in the darling system for night in the woods and twine can be a bit of a mess uh this is a screenshot of my book to be or not to be where you can see the nodes but it's very hard to get a sense of what's going on i try to keep things organized by using the horizontal axis as your position in the narrative of the story and the vertical axis is basically being what character you are but even with that i'm reduced to stitching together screenshots and circling to say which point represents which place in the story and it only gets more complicated when you add in things like variables to keep track of state which are going to be invisible in this sort of view one of the really good things about twine though is it's got a really really

simple and approachable syntax that is great for people who are not full-time programmers so we basically just took that and ran with it so yarn spinner uses twine-like syntax combined with uh screenplay semantics to create well its entire language so in yarn spinner lines of text are individual lines of dialogue this means that a screenplay is valid young code we have a minimal syntax for options we have flow control we have commands and it scales to complex systems quite well as you'll soon see so what do we mean when we say a story programming language well yarn spinner works like this you the writer writes your dialogue out as yarn script in a text file it looks very similar to a screenplay with occasional flow control syntax it's quite easy to pick up and read the editor tools or the engine at runtime reads that text that you've written and passes it into nodes so the individual nodes on the graph that we were talking about earlier

during gameplay yarn spinner moves from node to node sending the game line to dialogue options to show the player commands to run and also makes decisions on which node to move to next based on player choices and on the game state so here's an example uh here's a chunk from night in the woods that shows all of these elements so up top you've got some flow control so we're checking the value of a variable called angus and then we set some new value into that variable angus we do another test on another one called dealing angus investigation quest uh a command there close all which in night in the woods happens to be a special command that gets rid of all the dialog boxes on screen then after that we've got some lines so we have lines back and forth between angus and a character b then at the very bottom we've got options so the player can choose to say lasagna or brownies and based on those choices different lines are run so yarn spinner is just running this script much like it would if it was a

program because it is a program so arrows are a feature that we really quite like in this because you don't have to create nodes and connect them with lines it makes creating branching dialogue super super cheap to do which means that writers are a lot freer and they don't have to go oh i could add a choice but that would mean a whole 10 more clicks yeah and it also lets you experiment with the story quickly when you're writing you can throw in a choice and see where it takes you and then decide you know what this is great i'm going to follow up on this or you know what this is horrible i'm just going to cut it and keep going with the narrative it's very much an experimental sort of play space for the writer we also found it to be really useful for cut scenes so every cut scene in night in the woods is a yarn script and it was really really useful for solving the problem of general linear content delivery so in addition to having lines run we also have stuff like uh in this script here we tell a fountain to stop playing an animation we

fade out the music over the course of three seconds and we also wait for three seconds and we and then we run some some lines of dialogue so when you're writing it lets you imagine the kind of things you'd like to see and even drop in roughed in code for what that might look like which lets you just build the story and then have these pieces left over for the developer to you know actually develop for you so story languages like this are kind of the halfway point between screenplays and graphs you're writing a top to bottom text document in a text editor in a very familiar way for most people to write but you're also expressing more complex branching structures much like a programmer does and you're doing both of these in the exact same place so with that in mind as we were building this we went hey this is getting more interesting more popular more people are using it that's great and it turned into a full project so why not make a cool demo game for it so this is where i come in uh john contacted me and said hey are you interested in writing say a short five minute sort of demo game just to

show what yarn spinner can do and i said sure and then came back with this pitch for a story called i feel fine about a robot pinned to the floor of this space station that's going to be destroyed by an asteroid in three days so it's very simple one room nailed to the floor you can't even move we'll just have conversations with characters throughout this story as we go and this is what i sent to john at the end of the pitch saying hey you know what do you think there's a lot of options here it's very open i presume we're going to iterate on this and there'll be a whole bunch of conversations we'll have to have where do you want to take it from here and where we took it from there was john basically just sending me a little unity app that i could drop scripts into and saying have fun let me know what you come up with which i was not expecting but made for a really interesting development cycle because i could just start writing i started writing a game what john sent me is what you can see on

the screen here basically a little demo script that showed here's how characters talk here's what choices look like here's some basic controls and go for it have fun let me know if you need anything and based on the system that we had put together it actually honestly didn't really occur to me to send ryan anything different because we'd already built up the system that allowed a writer to just sit down and write so um yeah i was surprised that he was surprised that i was surprised um so we built this thing it took about a day to throw together this little demo thing and i sent off to ryan um and ryan took that and turned it into something just staggeringly huge yeah i sort of ended up with a uh about an hour long worth of gameplay a three-day structure multiple endings character romance options it turns out by giving me the tools to do that i i would start doing

things like that and here's an example of the game code as it is today if you look it's exact same stuff that john sent me the same control structures the same ways to make characters speak only now it's for an actual game having passed through the hands of an actual writer this is what the tool that john sent me looks like and to use it i would just hit the reload script button in it which reloaded the game and let me debug my story exactly the way a developer would debug their code and once i got used to that once i was used to this development cycle i asked him to send me a new version that displayed the content of variables in the game on the screen which made it even easier for me which unlock this this standard development cycle of test correct test correct this iterative process until i could get the story to a point where it's done it's it's ready to go in the same way developer would debug their code to a point where they're confident with it to send it off to somebody else and i'm the writer doing this instead of the developer doing it so here's what worked well uh it was fast authoring and easy editing even at a late stage this was a

game with a three-day story structure that i wrote in about three days i just could go off in the corner with my computer get in the zone and and just write it functioned effectively as a story document a text file that i could play which was great and of course since it is just text it's really easy for any sort of version tracking software to work well with this but it wasn't perfect uh the sandbox the aaron spinner gave me wasn't quite as big as i would have liked there was one point where i wanted to use an array and i emailed john saying hey john how are we looking on a raise and he wrote back and said hey ryan how are we looking on if statements which actually speaks to the power of yarn spinner because i could implement what i needed using that workaround of if statements and i'll give an example uh here's a shot of the tool at the beginning of the game well there's a couple of characters who want to speak to you there's annex who's rich who says i'm waiting in line i want to talk to you there is beef chief i got to name my own characters who's also waiting in line there is chomsky the dog who's saying i

do have been waiting in line it's my turn and annex offers to pay you to go first and you have to choose who goes first and what i wanted to have was an array where you just kept track of who you've already spoken to but i didn't actually need it i could emulate that as you can see on this slide with just a series of if statements a variable for each character keeping track of whether or not we've spoken to them and you've built effectively the same structure out of a simple series of ifs and else so lots of programming languages think in terms of domain specific languages so syntax and apis that are good for describing a solution to a very limited problem domain yarnspinner is a domain specific language for branching dialogue this is really useful in many narrative games because the logic of a scene so who says and does what is the story of the game and this leads us to a thing that we've been calling narrative grey boxing so level designers are used to grey boxing their environments blocking out their

geometry with rough shapes to get the idea of the shape and flow of the environment because you can figure out that environment before you commit to the production of expensive art in lots of narrative games the logic of a scene is the same thing as the scene story so control over the logic of a game is useful because it means that a writer can set up whatever small scale mini systems that they need without having to wait for a programmer to to add support and the inverse is also true a programmer can anticipate a need for a system build it and then add in some temporary placeholder lines that a writer can come in and replace so this screenshot is actually what the ending of night in the woods looked like initially uh the ending was completely temped out and very very easily replaced uh towards the very end of development so this scene in night in the woods the logical structure of it didn't actually change but the content of the lines actually did it got filled out and so this kind of temping out can be done very very early on and you can fill

in the rest of the lines quite late john mentioned this idea of gray boxing narrative systems and that's actually something that fully organically happened during the development of i feel fine i wanted to have these multiple endings that were chosen based on your reputation with different characters so i just built a very simple reputation system using variables keeping track of points for each character you've spoken to that would then unlock endings and it was very simple very easy very natural for me to just build this as i decided i wanted it that's the kind of system that like normally you'd need to plan ahead for this one it's very rare for an entire system that affects the ending of the game to organically develop on its own but we did it we did it and a few ways in which we designed this language to support this kind of workflow is not a huge amount of information is required to be carried through lines in the yarn spinner are just strings and we send the entire string

anything that does need to be user-facing so for example a line code for localization can just be encoded in a hashtag that's attached to the end of it this is very easy to write it's very easy to understand and quite intuitive it also allows us to do stuff like again in the words you can use emoticons to control facial expressions so you can see that happening here in the in the scene right now we also don't need to nail down ahead of time what commands can be sent to the game they can be built as needed case by case with a generic command syntax the writer can strip the game in their heads working ahead of the developers and anything that needs changing can be done and tested quite quickly if the feature isn't available you can just write around it so the result is highly iterative narrative systems development where the writing can go off and explore and iterate and build systems until they found the system that they want that the story needs and then they can lock it down and complete what they're trying to do it also keeps developers from trying to solve interesting problems which are a

lot of fun and very cool and very fascinating work on but they're rarely immediately useful yeah it insists the developers build the scaffolding for the game while letting the writers to sort of go off and explore it it gives the writers powerful tools but still sandboxes them and it also keeps the writers from becoming developers which i imagine can be a danger what it's less good at is data that really should be in a table so just as it's kind of fiddly to store lots and lots of hard-coded data in c-sharp it's fiddly to store non-linear data in yarn spitter this is the kind of thing that's better stored inside tables and when i feel fine and night in the woods and i imagine most of the yarn spinner games need to do this it turns into a gigantic huge if else tree which is a mess that said support for storylights and condition based content selection is a feature that you could conceivably add to the language so how do you get started doing this well building a parser for a language is

actually slightly easier than you may think because really it's two separate independent problems one is build a tool that reads a text document and converts it into a syntax tree and then the second part is you walk that syntax tree sending data to the game as you go skipping over other parts of the tree based on game state it's very very easy to get too excited about this like i just mentioned so big thank you to my colleague tim nugent for hitting me with a rolled up newspaper every time i got too excited about language features so we use a tool called antler which is a tool that lets us describe the grammar of the language and then generates the source code to a parser for us then we feed that pass a yarn script we get an abstract syntax tree and we work with that antler is very popular in the programming language development community it's not essential we just find it very useful in fact the very first version of yarn spinner didn't use this at all it used a handwritten password that i wrote and gave me headaches and nightmares

but using a parser generator means that it will take care of a lot of edge cases for you which is quite quite handy as a tools developer you also don't need to solve every problem certain questions are totally fine to just leave open and you can avoid building overly ornate systems by punting on entire design questions what data do we need per line i don't care that you send the entire string you can attach whatever data you need to inside that line what data needs to be captured in an option don't care you can attach any non-user-facing data as a hashtag at the end of the line it's a string what signals do i need to be able to send to the game i don't care you can use commands which are just basically strings that are never shown to the user and it's up to the game to interpret them so my advice for tools developers is don't try to build a full programming language you are not trying to make a replacement for c sharp you're adding logic to dialog yarn spinner doesn't support half the features that

are required for a systems programming language it barely supports adding data it doesn't support functions it thinks only in terms of numbers bulls and text don't try to solve the interesting language problems solve the specific problems that your writers are facing your job as a tools developer is to build the scaffold and then stand aside what it's great at is letting writers and developers focus on their core competencies do what they're good at without having one arm tied behind their back it leads to easy and rapid prototyping easy and rapid development and easy and rapid testing because we're also working with the same kinds of tools that full programming languages and compilers work with we also can explore some interesting new areas so for example we can do things like basic block analysis control flow graph analysis and all kinds of things to analyze the dollar trees in a really complicated and interesting way yeah it let us build a narrative in a few days and most of that time was spent on writing not on struggling with tools and of course once the narrative exists then the engine can be enhanced assets can be

brought in you can build everything around that scaffold that you build and of course once you've seen those assets you can easily alter the narrative if you want to so we're really really excited about this approach it's already been used in a lot of games including the ones you can see on screen right now and there's some huge potential for letting games be written almost as fast as stories are and also even more excitingly we can onboard traditional writers into non-linear storytelling even faster and that's great are we possibly overselling this i don't think so i think we've just solved all storytelling forever thank you all so much for watching uh hopefully you found this interesting at the very least thought-provoking um we're looking forward to seeing where this technique goes in the future i'm dispersed on twitter and you can follow my studio at secretlab.games and i'm ryan q north on twitter and you can find me at ryannorth.ca don't forget to leave a rating it really helps speakers like us come back to gdc and deliver great talks and so with that thanks again bye bye [Music]