Some terms questions

I have a terms (and best practices) question here. What is the phraseology around portions of writing in a choicescript story?

A hierarchy like:

  1. Novel
  2. Chapters
  3. Scenes
  4. Choices
  5. Pages

In specific, i’m wondering what that pageful is called — which doesn’t always have a choice but frequently does. I feel like there is some best practices for writing attached to these portions of work, and i’m super curious.

The reason i’m asking is i’m trying to separate drafting from markup and coding sessions. Not because i am afraid of the code — the opposite. I keep ruining my writing sessions obsessing over how to structure things correctly and get the stats checks and modifiers in when i really need to be focusing on prose and getting through huge clusters of story so that i can work it. It is very engaging and probably somewhat useful to the project. But i’m pretty sure that i should do this more as an “editorial” pass working with a lot of prose instead of slow. Ing. things. Down. So. Much….

So i was thinking to divide up chunks in my writing-only sessions with some indicators of where i’m pinning stuff, and in separate coding sessions grab that chunk, mark it up with pronouns flips and structure in the multireplace I want. There is value in having the two types of draft, even if i’m sorta blocking out and commenting “sent to cside” for portions in the real choicescript. I’m trying to do “unit testing” (well, just building and making sure i didn’t break the choicescript) as i go to bot have really tough surprises later. I expect to spend a LOT of time load balancing and tuning and rewriting when i shift to choicescript only after this month of writing.

I’d bet those really familiar with this format don’t feel the need to separate the activities, but i’m trying to stay in one mode at a tike when working to make use of limited time. And would love terms and best practices if any have suggestions. I have hunted throughout the forums and haven’t found super clear suggestions — which again might be a terms thing.


If any longterm forums folks have suggestions for terms and past discussion related to this topic, that would be amazing! Even if you don’t have an opinion about this topic yourself. I simply haven’t succeeded in finding stuff, and what i’m looking for is very much choicescript specific! (Or is it? There is probably a hypertext or IF concept for this elsewhere as well.)

1 Like

There isn’t a set one. :slight_smile: And your post makes it clear that we’d need a couple of different taxonomies.

Sometimes we need to talk about user experience. Every reader sees “pages” between choices or next buttons. The often-discussed issue of “how often should I break up my text” (e.g. How often should you use page_break? - #3 by Gower) is about the ideal size for this unit. Most readers also see chapters, since the majority of COG writers choose to divide the story that way.

But there’s only a loose connection between that classification and the CS coding categories of scenes and choices. Plenty of writers (including me) end up with multiple-scene chapters, and some use scenes called in a gosub_scene that aren’t in the chapter hierarchy at all. Choices aren’t the only thing that breaks up text into pages.

Pages and chapters seem to me like useful labels to describe the reader experience, given the book-like interface. Their length and rhythm will vary according to genre and authorial style.

Why not just one scene per chapter? Well, if you write long stories (like me) having multiple shorter scene files for a chapter can make it easier to find my place. A scene has its own temp variables, so if you have more than one distinctive challenge per chapter, it’s easy to split them. One half of my Chapter 3 needs a bunch of temp variables tracking the interrogation of the noble travelers; the other half needs a bunch of temps that track your response to an attack on your band. There’s no reason those all need to be in one scene file, and dividing them into two makes it easier for me to jump into the coding.

Why not make those two different chapters, each focused on one challenge? Partly, that’s a stylistic question; but it also has to do with how free the reader is to make choices that shortcut a chunk of story. If my whole Ch 3 was about the noble travelers, it could be cut almost laughably short if you choose to shoot them first and ask questions later. But I wanted to allow that choice.

In connection with how you plan to write, I’d just note that I find it very hard to gauge while writing how the “page” will actually look, especially with coding variation involved. Whenever I read back over what I’ve written, I end up making tweaks so that it reads more smoothly on the actual screen. Do what works for you, but be mindful that if you’re not coding and reading your text as you go, it’s easy to end up with one option yielding a textwall and another a staccato sequence of super-short pages. That isn’t ideal for reader experience.


I’m not exactly sure of what you’re looking for. However, generally speaking, IF gamebooks can be most accurately represented as node trees. This is an actual name for a data structure in computer sciences and software engineering.

So you can call each page a node or a leaf and each path a branch in techno-jargon. But, I mean, you might as well call it a page (though, “branch” is commonly used around here to refer to paths). I don’t remember any discussion on this forum about formal nomenclature.

In Ink, nodes would be called knots and in Twine, they are called passages. But neither of these two engines keep as close to a book interface, as @Havenstone mentioned above, as ChoiceScript does, so their more-generic categories make sense. I think that “pages” and “chapters” offer a good mental model. Scenes are too broad and even in traditional novel writing, they eschew easy definitions.

On the GDC youtube channel, there are talks that touch on the development process for interactive narrative structures. It is well worth it to scavenge around there. In one of the talks, a representative of Episode (IIRC) lays out how they go about plotting their stories.

  1. Overarching plot

    A "railroad" sequence of events.

  2. Branches

    Different paths in the story. Each path will offer actual different experiences, different scenes, etc.

  3. Choices

    Here choice takes on the meaning of immediate choices, which won't change the current path. Flavour (or fake) choices would fall into this category. In ChoiceScript I believe this is something of a grey area, because of the concept of delayed branching, in which branches occur due to the cumulative effects of choices.

  4. Dialogue

    This refers only to dialogue. Again, this can also be something of a grey area, since dialogue options may influence personality traits, which, in some games, may also influence branching.

I probably got something wrong here, but the basic idea is that each level is more specific than the previous one. They would all be represented in ChoiceScript by labels and gotos and choices, but they’re actually different structures.


Each author/designer comes into this community from very different backgrounds and training.

With that said, there often is a disconnect between “story-telling” and “game-making” and often people run into trouble because they do not make the connection between the two necessary elements of a Choice Script game.

The vast majority of people in this community have a background related to writing a narrative, so the dominance of writing terms and concepts is a powerful reality.

My personal experience has been that each author/designer is best served by developing their own processes … usually models that attempt to unify and standardize fall flat here because everyone has such a diverse and often unique background and training history that leads them to unique needs.


This discussion is exactly what i was dreaming for! Please keep it going, am reading closely and will respond shortly!


A four-level hierarchy like this one, where the real variation comes at Level 2, with a railroaded top-level plot and two lower levels of fundamentally cosmetic choices, is certainly going to be a commercially efficient way to produce interactive fiction.

And sometimes IF needs to be efficient, like when it comes with graphics and voice acting. I really enjoyed Telltale’s first Walking Dead game, which basically follows this pattern. I also enjoyed the Heroes Rise trilogy, which doesn’t have a whole lot of “real” branching but a whole lot of cosmetic “how do you feel about that?” fake choices. There’s a huge audience of people who read their CoGs just one time, who come to IF more for the sense of freedom it gives than to actually explore the variety on offer. Efficiency works great for that audience (and that audience probably buys more games overall than customers like me who read most games 3-5 times, and our favorites rather more, so it’s good business for CoG to aim there too).

At the same time, it seems to me that with ChoiceScript we trade the artistic/storytelling possibilities that are tied in with voice acting and graphics for – among other things, but probably first among them – a greater ability to produce real variation in our interactivity.

We can write stories you explore, much much less railroady than the map described by Episode, stories with odd corners to discover and factors that play into each other in emergent, hard-to-map ways throughout the story.

Choice of Rebels definitely has a Level 1 backbone plot. Your rebellion starts with you disrupting a public execution and fleeing to the greenwood; you bring your band through a hard winter, meet a few people in the spring, have an army come for you in the summer, and end up on your way across the border into the wilderness. None of that varies based on player choice. I wasn’t writing a rebellion sandbox. Them’s the rails.

But there’s no clear hierarchy of branches below that. There are lots of ways through the thicket of the story; there are characters you may or may not meet, and most chapters have extensive pathways that many readers will never see. The handful of basic stats interact with chapter-specific challenges to produce overarching outcomes that you can’t easily map (some of which have, to my surprise, taken dedicated readers literal years to hunt down).

That’s less efficient to write, obviously, but I found the results very satisfying both as a writer and a reader. I don’t mind my IF on rails, but the stuff I love, like the COG work of Kevin Gold, Kreg Segall, and Kyle Marquis (the three K’s!.. no, wait, scratch that) roll out an elaborate world to explore. I think Kevin, Kreg, and Kyle have each found ways of doing it much more efficiently than I do – there’s much more method and less messiness in Kevin’s process, certainly. So if you’re going to code dive, look to Choice of Robots and Choice of Magics rather than Rebels. Compared to the GDC/Episode schematic structure, I think Gold’s games offer a much more satisfying model for writing IF.


Very helpful observation. Which is why I’m looking to be bringing my writing into code as I go instead of waiting for the end. Though it does still seem better for the writing to not be thinking about coding and tweaking layout while getting the ideas sorted. But this may just be first timer stuff.


Seems like it might be as useful to see each of these as an anatomy label – components that are recognizable, but some are territories and some are specific features. This is helpful, even if isn’t useful to treat them precisely as hierarchy levels in an outline. Similar to when writing prose there are many motivations for paragraph divisions within a chapter, and experiences when reading the chapter beyond just the first line and last line being special.


That’s fair. I have gravitated to reading CoG titles and checking out this community precisely because I felt the experiences were notably richer and more rewarding than many of the game narratives I had encountered elsewhere. So I don’t need it to conform to a rigid taxonomy and process of production any more than I want every movie or piece of music to be structured the same.

I suspect my challenge will be countering my tendency to get too focused on technical matters of implementation when I’m actually more anxious about a compositional/storytelling moment. So there probably won’t be a scaffolding approach that resolves that complexity and I should just consider this part of the process. :wink:


Well, I’m starting to wonder if for an attentive reader if you need pure choice (ie more choices = more satisfying) as even fake choices can really pull you in and engage you even if there is not a bit of branching. Just being in a choicescript title when you feel confident in the author’s use of the medium, it enlarges as an experience more than even the options that you are offered (or that you take). (Note that sometimes when I read IF i switch into this foolish “just watch the changes” race-through mode that isn’t really the same thing, and have to stop myself so I don’t miss out.)

I think Choice of Rebels is amazing, and part of it is because I felt as a reader the impact of choices on what kind of experience unfolds, even if there are these big tentpole elements holding the structure together. Yours is exactly the kind of project that feels VERY rich in terms of the potential story space even if I don’t work my way through as a completist to try to read everything. Just reading a single well orchestrated path as a novel wouldn’t have been as rich as feeling the consequences of moving through Choice of Rebels as it stands – even if I was totally wrong where I thought I was accomplishing what.

I like your taste there, even if maybe the reason to read those others is partly because you went at the coding aspects of Choice of Rebels in more unique manner such that it is a bit more difficult for another reader to parse out when reading through. :slight_smile:

I love those three as well, and have read source for Gold’s Choice of Robots and Marquis’s Silverworld after reading a bunch of paths through each. (And on my list is Tally-Ho, but I wanna do some more paths thru before peeking behind the curtain! Which is time intensive.) And one of the things I have found in general is that often as a reader parsing through the code afterwards that I’m wrong in what I’m expecting is happening under the surface “mechanically” (as far as setting up for branch switches or allowing or preventing various scenes), and I really love that as a reader. I think these two sources made me love their published projects even more – sort of gave me a “quantum reading” where i could “feel” some of the unexplored territory even if I’m not sure i could really navigate my way there without min-maxing or doing a really targeted read. I did get some good ideas how to offer juicy outcomes regardless of choices and routes, which has a lot to do with why I’m trying to write one now. I should probably read those sources again entirely now that I’ve been a beta reader on a bunch of projects. I’ll bet I’ll understand so much more!

But with Choice of Robots and Silverworld – and with Heart of the House – I just couldn’t quite imagine how these pieces were planned and written short of writing them as code from the beginning. And I don’t have a knack for that yet.

Frankly, Joel, with your project I found how well your piece worked even more inscrutable after attempting to read your source, and it made me love how your piece worked even more. :wink: both damned ambitious and satisfyingly delivers on those ambitions. Can’t imagine encountering your story in any other mode.

1 Like

This is going off-topic a bit, but I want to reiterate something that both @Eric_Moser and @hustlertwo give out as their most important advise: Writing is the only way to actually improve your writing. Havenstone lays out the practical aspects of getting everything down in writing above, but from everything said here, I feel the following is very relevant here:

They both say this stuff better than I could, so it is worth repeating here: write, and then write some more.


Thanks, Eiwynn, these encouraging quotes are appreciated. And this addresses my needs even if it is drifting off my initial proposed topic. Thanks for sharing. I’ll be back at my writing desk at 5am tomorrow to keep soldering on!

I think your level system is good, I would write it out a bit differently but still good.

However, there are some problems with the things being said here. I am not trying to attack anyone personally, simply pointing out some flawed statements.

“Efficiency is the kind word for laziness.” True words from an unknown source.

Well, that’s partially true, It is not completely true. Take the mainline Fallout series, any one of them from 1-4 They all had player choice, and they had graphics/voice acting. I think what you’re trying to say is that there isn’t enough time/money as those had more than one dude, duct tape, and a wish.

All of those games however had more choice than Telltale games, and Telltale choices are the only thing they have going for them. Their stories without choice are average, and nothing to look up to. Luckily they are gone, and we don’t have to pretend they were good.

(Not trying to say it was any individual employees fault, as they probably would have been able to make better things if it wasn’t for management who thought that releasing the same thing with different brands of paint was making their games more popular.

That is a very corporate mindset. Things are already bad enough, so hopefully, they don’t follow it. Besides why fake freedom, when you can make freedom. It has that effect on casuals, and it also makes sure that people who actually care aren’t getting short-changed. Writing wouldn’t make us rich 9/10 so if it’s going to generate little income either way why would we sacrifice integrity for it. That rarely works.

Time is finite, I understand, but why have a massive picture of a tree when you can have a real bush.

I notice, my friends notice. Some fake choices can help with flavor, but you can’t eat seasoning, you still need the meal of real choice. Otherwise, you will never be full. The reason authors get away with serving pure seasoning is because there isn’t a source of analytics to show readers what’s behind the curtain. I am working on our own projects, and cannot do that for the moment. None the less I can assure you there is no food behind the curtain, just seasoning a lot of times, and the food is actively being hidden by the COG staff. This is why I generally avoid The Choice of Games app, the food in Hosted Games might occasionally spoil, and sometimes it’s also just seasoning, but at least there isn’t a shortage of food.

I hope the day comes when people see what’s going on, I might start the pushback on the wider internet, I might just be moral support. I don’t know, I just know that as it becomes more popular, and when analysis inevitably comes people will be held to a standard higher than a bottle of seasoning.

Re terminology, there’s a wide diversity of approaches and terms. I always recommend Standard Patterns in Choice-Based Games by Sam Kabo Ashwell, and Emily Short’s blog which is generally about IF but whose principles apply widely, and she also has some excellent articles about ChoiceScript and long-form IF structure.

I also found End Game and Victory Design on the CoG blog very useful. This explores the sort of structure seen in work by Kevin Gold and others (including erm, me) that results in wide-ranging endings for these kinds of games. In fact all the blogposts under the Game Design tag are helpful, as are the CoG Game Design Guidelines. Whether or not you want to follow them, it’s really helpful to know a bit more about what goes on under the hood, and to make design choices consciously.


You’re overanalysing. Trying to do writing the “right” way, the most efficient way. Getting lost in the weeds. Here’s a sickle for you: nobody sees the choices you make while you write. There is absolutely not even one single reason to worry about the terminology used to describe the choices you’re making as long as what you write is sincere.


Thanks, Hannah, I really appreciate these resource shares. I have definitely been studying these for a while and have found them useful. I thought I had read all of them, but just noticed that I never did notice “End Game and Victory Design” when reading through those tags before. I’ll check it out immediately!

I read Creme-de-la-Creme obsessively and then read the source – and learned SO MUCH. So you are kinda already one of my primary choicescript mentors whether you know it or not. :wink:

In your author interview when launching that game, you had mentioned this which I am just noticing now:

Making and polishing up the outline was much easier having made one before, and I found that having that sense of the broader plot affected everything positively. I still had points where I changed my mind about scenes or chapter events, but I felt much more clear about what I was doing.

After the outline was greenlit, I wrote broad strokes summaries of scenes and major choices for the chapter I was about to start. I then coded everything with placeholder text, and did automated testing often to check that it all worked, and to check balance. Then I filled in the writing. I’d often shuffle things around at that stage, but it was great to have it in place first

Did you find that doing the work in this order freed you up to compose the natural, engaging prose itself right into the structure? Heck, even though I had seen this in the CoG Game Design Guidelines, part of me had suspected I wouldn’t really understand how to make the choices really count until I had written a few chapters and really experienced how it was working. Though maybe it mattered tremendously that this was your second title and you had some clear goals after Blood Money that made this process extra useful. Do think getting this structure / armature in place (with the stats changes functioning decently) will be a model you’ll use in the future?

Good point, and I think you are likely right about my over-analyzing here. I think I’m maybe avoiding some of the writing itself. Though I’ve picked up some solid advice and encouragement here that pushed me back to writing again. This really helped, even if I leave this discussion without a whole system of terms to arm myself with. :wink:

1 Like

Coming from a writing background, I generally write each scene as prose (with pronoun and minor code), occasionally putting in shorthand for choices I don’t write yet. Then, when I am in more of a coding mindset I go back and adds choices and branching.


Have you found that this helps you find more natural intervals and inflection points, or is it just what is more natural to you?