Jul 30


Four Ways to Write a Vignette

Posted by: Adam Strong-Morse | Comments (10)

One of the hardest tasks in learning to write a ChoiceScript game is figuring out a process for writing vignettes that works.  We all have experience writing stories, essays, and other prose forms.  And many of us have written computer programs before.  But a ChoiceScript game isn’t like a normal story, although it needs to tell an effective story, and it depends far more on text and storytelling than a normal computer program, although it is a computer program.  So how do we go about writing a vignette?

In previous posts, I’ve talked about how we plan a ChoiceScript game and how to pick a vignette to start writing.  Today’s installment in our series on game design discusses ways to write an individual vignette.  Unlike the previous two topics, I don’t have any clear choice to advocate as the way that I think is “best.”  But I can describe several different approaches that I’ve seen used, and talk about some of the advantages and disadvantages of each.

Option 1:  Start at the beginning, write until you reach the end.

This is the most intuitive approach.  It has the advantage of being straightforward and logical, and of meaning that you do all of the fiddly annoying tasks (whether that’s filling in stat modifications, getting the flow control right, or writing the text for responses to individualized choices) at the same time as the rest of it.  When you’re done with a scene, you’re actually done with the scene (except for the inevitable editing and revision, of course), and you aren’t creating annoying work for yourself later.  But it has some problems.  It requires you to figure out all the complicated bits as you go along.  And if you get hung up on specific tasks, it can wreck your flow.  I find that when I try to do this, I inevitably hit bits of text that I need to write where I’m not inspired.  Then I stare at the blank section under the #option for a while.  Then I check my e-mail.  Then it’s five days later and I’ve totally lost my momentum.  In other words, I find that this approach works, but that it is dangerous.

Option 2:  Write the text first, fill in the ChoiceScript code later.

This is my least favorite approach.  If you’re new to ChoiceScript, it may seem to make sense to just sketch out the text without worrying about how the programming side of things will work.  Get into a groove writing, and just let the story develop.  Then, once you have a fully developed vignette, you can go back through and fill in the *ifs and *sets and *choice commands.

It seems really appealing, really easy.  But in my experience, it makes for a total mess.  First, it’s easy to not realize that something you’re setting up doesn’t make any logical sense.  “Hey, I wrote in an option here, but I never actually filled in the results of that.  Oops.”  “This is supposed to feed back in to that other section–but how exactly does that work?  Where does it feed in, how do we make the text consistent?”  Second, it seems to encourage sprawl and confusion, and to discourage player agency/meaningful choices.  When you start writing like this, it’s easy to start thinking that you’re writing a short story or a novel.  But you’re not–you’re writing a game, or a piece of interactive fiction, or whatever.  And so you need to be focusing on the interactivity, on the meaningful choices.  And the structure of ChoiceScript steers you towards focusing on the choices, which is good.  Third, and most importantly, writing the text first creates a huge chore.  Converting vaguely formatted text into ChoiceScript code is no fun at all–and I say that despite thinking that writing ChoiceScript code is a fun process.  The problem is, you end up doing work, where you’ve already done the fun part.  And it can be a lot of work.  When we wrote Choice of the Dragon, we wrote one or two scenes this way, and the process of filling in the code was awful.  It sucked momentum and fun out of the project, and that’s the worst thing:  you need to be having fun and you need to be maintaining momentum in order to finish your games.

Option 3:  Outline with ChoiceScript code first, fill in the text later.

I have found this to be a very effective approach.  I focus on the structure and the decisions that the player will make, proceeding basically from *choice to options lists to the next choice, with the *gotos and any *ifs built in from the start.  Even a pretty complicated scene usually doesn’t have that many choices–our most complicated scenes might have 20 or 30 choices, but most scenes have many less than that.  So this can be a fast way of outlining.  And all of the difficult literary craft work, the wordsmithing and paragraph building, can be punted until later.  To me, building the framework of a scene is fun and interesting.  If I need a bit of text to remind me of what’s going on, I’ll just write in a placeholder sentence (often in brackets so it will be easy to see that it was just a placeholder) without spending the time to write something good.

The reason I prefer this approach to Option 2 is that the clean-up work is not nearly as noxious.  Sure, you have to go back and fill in text for each of those placeholders, but writing the text of the game is part of the fun.  It can be work at times–often there will be one option that I just don’t want to write–but it’s not too bad.  So I find that this works well.

It also can be quite efficient, because you can see before you start writing large amounts of text where you can effectively reuse code with a strategic *goto.  Also, if you hit logical problems, you can spot them and fix them before you have to rewrite large blocks of text as part of the fix.  All in all, this is my favorite approach.

Option 4:  A mix of the previous three approaches.

Option 3 is how I theoretically write vignettes, but Option 4 is how I actually do it.  I use a mix of all three approaches, although mostly 1 and 3.  If I have a bit of story stuck in my head so that I really want to write it, I’ll write the actual text as I go.  And I frequently neglect minor ChoiceScript details like adjusting stat variables–“*comment Adjust stats here” is very common in my first drafts.  But mostly I concentrate on getting the scene outlined in ChoiceScript–making sure the choices are in place, that I’ve identified all the options, and that I’ve figured out where the options go.  If the text for a specific choice doesn’t come readily to me, I just put in a placeholder and move on.

Inevitably, as I write out some of those placeholders, I’ll realize there should be another choice in there, so I’ll just add it without worrying about it.  The process is a little more organic, a little more haphazard than a plan.  And while it follows the general approach of start with an outline and then fill in progressively, sometimes parts of that outline will be broad brushstrokes that will ultimately contain many subchoices.  I might start a vignette with the choice of what to do when bandits attack, and split that into three options:  fight, run, or hide.  In theory, I would outline all three.  But I might actually just put in “You fight the bandits.” as a placeholder while I work on the “run” branch, sketching out choices, writing descriptive text for the mad dash, and so forth.  And then once the “run” branch is finished, I might go back and start outlining the fight branch.  The key is doing whatever is easy at the time, while not leaving too much annoying work to the end.  Sure, there can be some clean-up, but you don’t want to ever get to the point where you have hours of slogging ahead of you.

Whatever you do, debug as you go.

I can’t stress this enough.  If you end up with a fully written vignette that’s riddled with errors, you will find it very difficult, and probably very unfun, to turn that into a working vignette.  It will be easy to have an error at line 25 that causes the vignette to crash at line 400, and that’s really hard to fix.  Conversely, if you debug as you go, it’s quick and easy to fix new errors.  So as soon as I have a substantial block of code–say, one choice, with the options in place and with gotos to a set of empty labels–I’ll run the autotester on it and make sure it works.  Whenever I add another substantial block of code, I’ll pause, run the autotester again, and fix any new bugs I’ve introduced.  That way, by the time I have a finished scene, I’m only debugging the last 10 or 20 lines, not the whole scene.  That’s one of the reasons I like Option 3, and don’t like Option 2–it’s hard to debug as you go if you’re not producing real ChoiceScript code–but it’s not too bad with Option 4.  Trust me on this one–I’ve written scenes and then debugged at the end, and I’ve debugged as I go along, and debugging as you go is faster, easier, more reliable, less frustrating, and just plain better.  So take whatever approach you like to writing your scenes–but debug as you go.


  1. […] This post was mentioned on Twitter by Writing Novels, Choice of Games. Choice of Games said: Four Ways to Write a Vignette http://bit.ly/8Yztda […]

  2. Erana says:

    I’ve been musing on the most effective way for me, personally, to write a hypothetical Choicescript game. Knowing my habits in learning new tools and systems, I wound up with the notion of Brainstorming story concepts to get myself excited about developing, and aimlessly tinkering with the script ’till I got the hang of it. (I have done a bit of reading up on it, but I have yet to actually give it a go)
    With a basic understanding Of what choicescript can do, I’d proceed with what you dub “Option 2.” I can understand why you’re wary of the “write first, code later” mentality, but honestly, I find writing on a computer absolutely stifling. Anyway, with code involved, I’d need it to be as complete and straightforeward as possible, or my mind would be boggl’d. If I were to ever be able to write a choicescript game, it would be through the use of string and (large) post-its. I’d first write my story and have it visually branch out all over the wall. (much to the bewilderment of anyone who saw my studiospace) Then I’d manually write the choicescript on an additional piece of paper that would divide my story into scenes. The translation to the computer would then be a third draft and would, with a divine blessing, have many of the kinks worked out by then.

    Anyone think this’d work?
    I’m not too serious about authoring a game at this point, but I find figuring out processes a most enjoyable form of problem solving.
    (sheesh, I can be a bit long-winded. I probably should make this an email or a forum message, but I don’t particularly trust my iPod’s cut/paste clip board)

  3. Kate14 says:

    Hello can anyone tell me when the next game will be released?

  4. CPFace says:

    Always a pleasure to get some insight into how you guys design your games. My approach has traditionally been Option 1, but I’m starting to lean more toward 3 as I’m planning a game. The thing that fascinates me most about Dragon and Broadsides is the underlying structure of the narrative; I want to see if I can understand it well enough to make something comparable.

  5. […] – and quite intelligently done. You get several chapters, several vignettes (they explain how to write your own, the blog is great at explaining the choices behind their games. Also; nice […]

  6. Kevin says:

    So I just started writing a choice of game a few days before this post was made, and I realized I went with option 2. Should I keep going or rewrite it with the programming now?

  7. Kamer says:

    I also started writing a script for choice of game. I’m about 1/4 done right now (or so I presume), but I just read this and realized I couldnt make any coding for my life. So I was thinking that maybe I could send scene by scene through email to u guys and u could release it as ur own. Would that be acceptable by you?

    • Adam says:

      @Kevin: That’s really hard to say. If you’ve made progress writing it this way, it may not be worth stopping and starting over. But I would recommend trying to get it coded as quickly as possible.

      @Kamer: That’s not really feasible. Adding the code in is too much work, and we’re too busy with our own projects. But I would suggest that you try writing some ChoiceScript code. It’s really pretty straightforward, at least if you’re not doing really crazy stuff.

  8. Michael A. says:

    Interesting discussion. For my own games (which have an embedded multi-choice system as well for “mini-adventures”, not too dissimilar from what is in the Choice games), I find that I usually have to plot out the (ideal) story first (i.e., similar to option 2). As I write the story, I usually fall over the decision points – i.e.,here the protagonist could do this, but there is also an option to try this – which I then develop into the various branches. It seems to work so far, though I have yet to implement the “big” storylines – perhaps once I do, I will find that they work less ideally than I’d hope. 🙂

  9. Ian Holmes says:

    In support of your option 3 I thought I’d just give another plug for my graphviz stubs generator:

    I find this a very quick way of prototyping scene (and story) structure.

Leave a Comment

Your email is never published nor shared. Required fields are marked *

Subscribe by E-mail