A robust community resource aimed to help game writers understand every nuance of writing branching choice-based dialogue using the ChoiceScript Scripting language.
After writing the award-winning Creatures Such as We, the commercially successful The Sea Eternal, and the internationally-commissioned Learning to Be Human, I wanted to give other writers a definitive and comprehensive resource to learning the popular ChoiceScript software created, used, and made available by the Interactive Fiction publisher, Choice of Games.
While many ChoiceScript guides existed, they were mostly written in ChoiceScript itself, which made stepping back to visualize the nuts and bolts of the mechanics more difficult, and made navigation a little clunky. This guide was written in Twine, which offered more tools to explain complicated mechanics.
Visuals
ChoiceScript has no "What You See is What You Get" user interface, instead creating gameplay with scripting commands that must be handwritten in text-only user files. This style of game writing can be intimidating, and I wanted to demystify it.
I broke each aspect of the scripting language down into simple, easy-to-understand steps, starting with the visualization of story branches as indents.
 |
 |
 |
 |
| Branching Storylines | Flipped Left-to-Right | Represented as Points | Represented as Indents |
|---|
These images are used in the high-guidance version of the tutorial that introduces concepts before commands or strategies, and go on to explain more elaborate gameplay scripting commands.
Examples
Each example gave very simple, self-contained breakdowns relating scripting to player-facing results.
|
This is some text in the game. *fake_choice _#This is a choice line. It has no child text. _#You can space out choices lines, if you want. _#This is another choice line, with child text below. _ _The extra indent makes this the child text of option three. _#This choice has two paragraphs, and sets some variables. _ _*set Vehicle "motorcycle" _ _*set Gasoline +5 _ _Those two variables were set. _ _Extra line break makes a second paragraph. _#You can make as many choice lines as you want. |
 |
| User-facing Scripting | Player-facing Interface |
|---|
After explaining the basics of a ChoiceScript command, additional information could be toggled via a menu on the side bar.
This form of navigation has multiple advantages. It allowed users to get a general idea of a command’s abilities, which could then be explored top-to-bottom for complete immersion or easily skimmed to find specific information. Showing examples this way also forces users to see the list of common errors and (hopefully) consider them more preemptively. See how it functions below.
Each page focused on a specific command or command group, indexed by utility and complexity for easy and intuitive browsing. For example, the *choice and *fake_choice commands are both similar and extremely important and so grouped together high on the list. In contrast, a group of obscure math commands are grouped together, much lower on the list.
In addition to interactable examples, and an intuitive index, I included downloadable templates for especially easy plug-and-play implementation:
Design Advice
•Make the Game Balanced
•Make Choices Meaningful
•Make the Game Respectful
•Use Good Programming Sense
I wanted to also give some high-level game design advice of best practices learned over the years of game design: ways to avoid wasting time & energy, ways to avoid player frustration, and ways to create satisfying experiences.
Narrative structure advice example: avoid writing long branches that never merge: long gameplay will be difficult to write, maintain or expand upon.
Internal Documentation
A quick internal structure visual overview.
•Accessible
•Maintanable
•(By anyone)
Documentation is in the top left.
Shared programmatic functions are in the top right.
The body of boxes down the center are pages visible to users, with high-level advice pages on the left, and specific command pages on the right.
Each user-facing page has several key functional elements: descriptive text up top, menu to toggle markup options, markup examples, and user-facing visuals matching the markup examples. The functional elements of these pages are organized cohesively and consistently.