Skip to content

Instantly share code, notes, and snippets.

@JoshuaGrams
Last active September 2, 2017 16:54
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save JoshuaGrams/b121fa1f5e7ca45fa12a0d51ee8b2aa9 to your computer and use it in GitHub Desktop.
Save JoshuaGrams/b121fa1f5e7ca45fa12a0d51ee8b2aa9 to your computer and use it in GitHub Desktop.
Thoughts on Narrative Structure and Tools

Thoughts on Narrative Structure and Tools

My local gamedev group is having a meeting tomorrow, on the subject of narrative structure and design in games. I thought I'd collect some thoughts and links here beforehand. I'm a programmer, not a writer, so I'm sure I'm missing stuff and probably misinterpreting other things. Take this with a large grain of salt.

Parser vs. Choice

Historically there has always been a big distinction between parser-based and choice-based IF. Parser IF allows you to type in anything you want and tries to interpret your input as commands (go north; examine refrigerator; eat ravioli). Choice-based IF generally gives you a fixed set of choices from which to choose, either in an explicit menu, or as hypertext with links in the body of the text.

But while this distinction is clearly useful, I think it combines two things that are (at least theoretically) independent: complexity of command structure and visibility of available commands. I don't think the IF community has quite grasped this yet, but they seem to be reaching in that direction.

Parser IF is on the one end of both these spectrums. Usually it not only has single verb commands (sit, stand, wait), but also verb-noun commands (examine slug, take eggplant), commands where the verb has both a subject and an object (feed eggplant to hippopotamus) and sometimes even more complicated structures. This leads to an explosion of possibilities, since you can try any verb with any noun, or some verbs with any combination of two nouns.

But the commands are also largely hidden. There's no list of all the things you can do in the current situation. And fans of parser IF generally are attracted to this sense of open-ended possibility. But it also tends to provide a high entry barrier. Even many stories which are often recommended to beginners have parts which are all about carefully reading the descriptions and trying all the actions and objects which it hints at.

Choice-based IF tends to fall on the other end of both spectra, with commands that take no arguments and are always visible. This eliminates most (if not all) of the guess-the-command issues. But it also removes the sense of possibility and accomplishment you get from successfully understanding the hints and clues in parser IF.

There have been a few recent experiments in hybrid designs. Some Twine games expand the command structure very slightly by providing two kinds of links: those which perform an action and take you to a different page, and those which simply provide additional text (whether inserted into the main text or as a pop-up). More interestingly, Texture is a hypertext-like system which uses a verb-noun command structure. It lists the verbs at the bottom of the screen. When you start dragging one with the mouse, it highlights all the nouns that you can apply the verb to. I'd love to see further experiments with more complex and varied command structures.

I haven't seen as many experiments with visibility in choice-based IF. A few people have suggested links that don't look any different from the rest of the text. But that smacks of pixel-hunting in point-and-click adventures, which I think is generally considered a bad thing. But the commands in parser IF are usually signalled in some way, just more subtly. Are there ways that idea could be applied to choice-based IF? What if you had a flashlight (black light?) that you could swing across the text to find things? A "search" command or other actions that might turn up new possibilities? What if you could pick up and move pieces of text and uncover other words that lie behind them?

A Smattering of Tools

I haven't looked into the parser IF area as much, so I'm probably missing things. But Inform seems like the tool of choice. It is a complete development system along with an extensive user manual and a cookbook. It uses a programming language that tries to mimic plain English, so you might say things like:

The kitchen is a room.  The oven is in the kitchen.  The oven
is a container.

Out of the box it knows about things like containers (which can hold other objects) and supports (on which you can place other objects) and clothing and rooms with exits and doors. And you can define your own kinds of things and the rules for dealing with them, and there are libraries available for various things.

I found the English-like language a bit disconcerting: text which describes how the game works is structured very much like text that will be shown to the player. The editor has syntax highlighting which makes it immediately clear which is which, but personally I'd prefer something with a bigger divide between the two.

But yeah...Inform has been around for a long time, it has tons of experience and history behind it, and it seems like a great tool.


On the other end of the spectrum, Twine is a tool for choice-based IF with an extremely low barrier to entry. You can run it in your browser without downloading and installing anything. It acts much like a wiki: you edit a "passage" and put links to other passages in square brackets. It shows you a graph of all the passages and the connections between them so you can easily see the story structure.

It has some simple and fairly accessible coding for doing more complicated stuff (tracking stats or inventory or whatever), but you can go a surprisingly long way just with basic links and the text formatting stuff. Stories run in your web browser and philome.la provides free hosting (or you can host them anywhere you can drop web pages).


Texture (https://texturewriter.com/) is the previously-mentioned verb-noun hypertext IF tool. I haven't played with it much, but it looks pretty straightforward to use.


Choice of Games is a commercial operation for choice-based IF. They have their own language, ChoiceScript, which is a little verbose but provides all the basic functionality. If they accept your stuff, they have a mailing list of 160,000 (I think?) people that it goes out to. They have a bunch of guidelines about the kinds of things they're looking for and a whole bunch of good blog articles about how to make interesting stories that fit their mold.


Ink is a fairly new choice-based scripting language by Inkle Studios, the folks who made 80 Days and are now working on Heaven's Vault. It covers much the same ground as ChoiceScript, but is very focused on being concise and easy to write, edit, and rework. So text is just text (as with ChoiceScript), but choices are indicated by bullet points. So a star marks a single-use choice and a plus marks a multi-use choice, and a two-character arrow (hyphen greater-than) means "go to another story fragment".

They describe some of their features in fairly confusing ways (I don't know why they use the "threading" metaphor and talk about how the story "branches" instead of just saying that a left arrow merges the contents of another story fragment into the current one, for instance). And it is clearly an internal tool which has been open-sourced. Under the time pressure of producing games, features have been added in a sort of ad-hoc fashion, so some of the later features are more clunky and less convenient. But overall it's a great idea and it works quite well.

And it's designed as middleware, so you can embed it as a narrative scripting language in a larger game. It's written in C#. There are a couple of sample Unity projects that render the text for you so you can just drop in your story. And there's a Javascript port, and an interactive editor so you can easily compile and run stories for the web.

Jon Ingold also gave a great talk about story design at GDC 2015. Well worth the hour of listening. Many many good things here. He talks about managing stats, about having choices always matter but trying to track a different aspect of the action than the player thinks the choice is about. Some good stuff about how much to branch before merging. He comments that the choice is the basic unit of pacing in IF: you could have a wall of text describing a chase across a whole city, or you could have three little choices in one little interaction with a grabby carpet merchant in the bazaar.

There's also a great talk at the British Library with Jon and Meg Jayanth, the other writer on 80 days. It's less technical and more postmortem and stories about the making of the game, but if anything even more fun than Jon's GDC talk.

Story Structures

Some people think that branching is a big problem because of the combinatorial explosion: if each path has 7 left-right choices and none of them recombine, you have 128 possible endings, and each path is only 8 scenes long. Even on multiple playthroughs, players will miss most of the content. So there are various structures which get around that by having more controlled branching, or branching that rejoins in a certain pattern. Sam Kabo Ashwell's famous article Standard Patterns in Choice-Based Games covers a number of these.

But the modern thing is to have choices affect character stats or other state. That way choices don't have to branch right away, but can build up and affect the game later on. Choice of Games has a blog article By the Numbers: How to Write a Long Interactive Novel That Doesn't Suck which talks about branch-and-bottleneck games which use this strategy. They call it "delayed branching".

They're big on having interesting stats and choices that are interesting because they don't have a clear right or wrong outcome, only outcomes that push you in different directions. So they also have a bunch of other interesting articles about designing IF:

  • 7 Rules for Designing Great Stats: include personality and morality traits as well as skills, also stats about how your play is affecting the overall game world/culture. Expendable resources are also a kind of stat. Make some stats (probably personality or morality traits) oppose each other (Superstition vs. Rationalism, Cunning vs Naivete) as it makes it easier to write interesting choices where you can swing one way or the other and both have advantages and disadvantages.

  • 5 Rules for Writing Interesting Choices in Multiple-Choice Games: options should have real consequences, players should have a rough idea of the consequences before they choose, all options should be vaguely similar in value (shouldn't be one obviously "right" answer), etc.

  • 4 Common Mistakes in Interactive Novels which basically just summarizes the previous three articles.

  • End Game and Victory Design: design multiple independent (and possibly opposing) goals that the player can choose to go for.

  • Don't Start at the Beginning!, since that has to be a good hook, and set the tone of the piece, etc., which you don't necessarily have down cold yet. Instead start with a early middle scene that is fun and represents what excites you about the game. That will allow you to experiment with tone and give you good momentum by suggesting other scenes that lead into or follow on from this one, and so on.

  • A document about writing for Choice of Games, which includes quite a bit of story structure and design advice as well as their technical requirements and style guidelines.

  • A shorter document about creating game outlines

  • Writing IF in Six Steps is a guest blog giving a simple overall workflow.


Emily Short has written a wealth of material about interactive fiction. Some of her more interesting articles (to me, anyway) are:

  • Small Scale Structures talks about little patterns that pop up a lot, instead of large scale patterns to build your whole game around.

  • Beyond Branching talks about various large-scale structures that aren't strictly graph-based. She mentions two relevance-based structures. In one, story fragments have a set of conditions that answer the question, "Is this story available right now?" and you can play any storyline whose conditions are met. In the other, fragments have an expression that answers the question, "How relevant is this fragment to the current situation?" and the engine will show the player a few of the most relevant storylines. She also talks about some of the conversational work she has been doing more and more of recently, and a model where the engine tries to pathfind through a web of conversational topics to get to the ones it wants to talk about.

  • Narrative Deck-Building talks about the possibility of using a yes/no relevance-based system to to allow the player to manipulate stats to do deck-building, indirectly adding and removing stories which will then be randomly selected.

  • High-Agency Narrative Systems talks about implementing engines for relevance-based systems.

  • Set, Check, or Gate talks about strategies for being consistent about which choices will adjust stats and which will check them, and how to communicate that to players.

  • Loose, Tight, Flat, and Bumpy is about strategies for tuning your stat adjustments.

  • Five Strategies for Collaborating with a Computer is a video of a talk about ways to create interesting procedurally-generated text.


StoryNexus is the tool from Failbetter Games used for Fallen London. It's a predicate-based system (yes/no relevance), what they often call "Quality-Based Narrative" since a storylet's availability depends on "qualities" of the world or player.


Versu was a now-moribund tool that took some research about conversational rules (whose turn is it to talk next? What things are you allowed to talk about and when are you allowed to change the subject?) and made it into a working tool for telling stories where the player could choose to play any of several different characters and the others would be run by a sort of AI. It seemed to work reasonably well though some people suspected that the parts they liked were more scripted by the author and felt they could tell which parts were more AI chosen because they didn't work as well. Dunno why they stopped working on it...


The Elm Narrative Engine is written in Elm, a statically typed language which compiles to Javascript. It's some sort of rule-based thing, and the newest release abstracts away from the presentation. So he has a Little Red Riding Hood example which is presented in classic choice-based style, in point-and-click adventure style, and as an RPG-Maker-like thing.


Adliberum is a multiplayer (!) text adventure game engine, though it looks like it has some sort of graphical interactive editor thing hooked up as well? Their website was kind of slow, but it looked sort of interesting.

Managing Stats

When managing stats in a game, there are a bunch of ways to go about it, depending on how you want the effect of choices to change over the course of a game.

Generally, just having a single number that you add to or subtract from isn't a terrific idea. You may have to very carefully balance your game and make sure that you have the right number of choices to reach a given threshold and ensure that you can get all the endings, and that you have equal numbers of opportunities to push the stat in both directions, and that sort of thing. And of course, choices have less and less effect the farther you get from balanced. Which may well be what you want, but then again it may not. So there are a number of alternatives.

Inkle Studios likes to use two variable per stat, one for positive choices and one for negative choices. Then you can ask what percent of your choices were positive or negative. This causes your choices to matter less the longer you play (but again, this may be what you want). It's less finicky than a single variable because you can always reach the extremes, you just have to always make choices in one direction. So you don't have to worry about having a particular number of choices, you can just add stat changes to any choice that would be expected to affect it.

Choice of Games uses what they call "fairmath", which makes it harder to push the stat towards the extremes and easier to push it toward the middle. Basically they divide the stat adjustment by how close you are to the end. So if you're at 50/50, you move by half the adjustment in either direction. If you're at 70/30, you would go up by 30% of the adjustment, but down by 70% of it. As long as you don't apply an adjustment of more than 100, you'll stay in the 0-100 range.

Chris Crawford uses a system which he calls "bounded numbers". It uses floating-point numbers and maps the full number line onto the range 0-1 using the formula sign(x)*(1-1/(1+abs(x))). It gives a similar curve to Fairmath, but where fairmath makes it harder to move away from neutral and easier to move toward neutral, bounded numbers make it harder to change at all when you're near the extremes.

Interestingly, Chris Crawford is adamant that you need floating-point accuracy to express fine changes. But most people who have written a fair amount of well-received narrative games seem to say that you can't express tiny gradations to the player anyway and that it doesn't matter. It's more important to express the narrative consequences: will this be the decision that pushes the NPC over the edge? Emily Short says she usually just uses three to five sizes of stat adjustments and keeps them in variables so she can adjust them to balance the game. There's more about that argument in the comments on Emily's blog post about Chris's Encounter Editor.

So to summarize:

  • Single number: harder to change the longer you play. Unbounded, so you can go way off to extremes and choices will no longer matter. May need careful design to get around this.

  • Up-count and down-count: harder to change the longer you play, but fraction is bounded so less finicky than a single number.

  • Fairmath: harder to move toward extremes, easier to move toward neutral.

  • Bounded numbers: harder to change when you have a more extreme stat.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment