writing guide

A quick note: If you’d like to write a story for the Choosatron, but use your own software/writing method, feel free. Just send me the content and I’ll format it for you!

Getting Started
First thing you need is the Twine software. Download Twine for Mac, or download Twine for Windows. The homepage for Twin is here. (If it won’t launch on windows, download this zip file, and unzip it into the Twine installation folder. It’s a single DLL file that should fix the problem)

Next download my test story called “Thanksgiving of Despair“. Unzip story_test.zip to get the file called “Thanksgiving.tws”. Notice the name of the first passage, “Start”. This is ALWAYS the title first passage. Case is important if you want to test your story using Twine. Try the demo story out online!

To test a story you go to the ‘Story’ menu and click ‘Build Story…’. Pick a name for it and it will save as an HTML file. It should automatically open your browser, otherwise you can drag the file into an open browser to try it out.

Writing a Linear Story (without Twine)
If you’d rather write a story using a standard word processor, here are links to some Choosatron stories laid out in a linear fashion to help guide you. If you are using Twine, skip to the next section.

Slugfest – Linear: about 1,300 Words – [Play it Online]
Thanksgiving of Despair – Linear: about 2,800 Words – [Play it Online]
The Chandos – Linear: about 1,350 Words – [Play it Online]
Another Day at the MIA – Linear: about 900 Words – [Play it Online]
The Spy Who Killed Me – Linear: about 4,000 Words – [Play it Online]
The Librarian’s Apprentice – Linear: about 1,900 Words – [Play it Online]
Gauche Criminal – Linear: about 2,600 Words – [Play it Online]

Remember that all the passage text you write will be printing out on a thermal printer; essentially the same as a receipt printer. Technically speaking, there is no limitation to the length of the text, but be mindful not to waste paper. It is also probably not ideal having the player read too much before getting to make a choice. I will post a video online soon playing a story so you get a sense of what a live play is like. Each row of text is exactly 32 characters (with default thermal printer settings assumed). This wraps by the character, spaces treated the same as letters/symbols.

First thing to know is that choices ALWAYS come after the passage text. They can be listed one after the other, or on separate lines, it doesn’t matter. My scripts will also cleanup any extra whitespace or newlines. Choices will have 30 characters for their first line because of the number and period preceding. If your desired choice text is close to 30, try to get it to 30 or less to save paper. If you wrap to a second line, you will have 32 characters for each other line. Make good use of them!

Here are the two choices in the first passage of Thanksgiving:

[[Take a nap.|1A]] [[Talk to your fiance.|1B]]

The above will print:
1.Take a nap.
2.Talk to your fiance.

Start with two square brackets, then the text you want printed for the choice. Follow with a vertical line (not the letter L), and the title of the passage it links to. Close with two square brackets.

The titles I use in Thanksgiving are not required, but were just an easy way for me to organize. You can name them whatever you want, though refrain from having spaces. Twine will automatically link two passages visually if the choice passage title matches an existing passage title.

There is one exception! You may have a single choice in a passage, without choice text, to auto-jump to the linked choice. If you test with Twine you will have to click it manually, but the Choosatron will use it correctly. This is useful if you have two paths you want to merge with custom preamble text for each, but ultimately the same passage text and choices.

Example: Take a look at passages 3B and 4C. They both link to passage 3A like this: [[3A]]. Same format, but excluding the choice text and vertical line. This way I could have different text leading into 3As text.

The Tags field (visible with a passage open) is how special attributes are set on passages. Some are optional to give the author more control over how their game is played, and others are required, like setting an endings quality. Each tag has a long and short form, the latter is what I’ve used in Thanksgiving.
Currently valid tags:

Start Passage Tags
sv or version: Only valid in the “Start” passage, used to tag your story with a version number for tracking.

ps or perfect: Defines what a ‘perfect’ score is if you are using points. If a player reaches an ending quality 5 with a perfect score, they receive a special message. Valid values are 0-65535. They must achieve this EXACT score, no more, no less (this help if they find a way to ‘cheat’), so make sure your math is right!

cp or penalty: Defines the number of points, if any, to take off a players score when they use a coin to continue play, values from 0-255 (NO negative sign). Useful if you don’t want two players to achieve the same score for the same path when one of the players paid to continue and the other didn’t. When they choose how many choices back to move, the Choosatron already removes any points they received after the continue point, so you don’t need to compensate for this.

Any Passage Tags
pp or points: Can be set on any passage, values from 0-255. When a player arrives at a passage with points, they are added to any points they already have. This is fun because they get a score at the end, and allows the author to design a game in such a way that there are multiple paths to the ‘ideal’ ending, and each path would net you a different score. In Thanksgiving, if you converse with your fiancé at the beginning you earn more points than going right to sleep, but either will still allow an ideal ending. This is zero by default. WARNING: If you create a loop in your story, the player will continue to gain points as they navigate through the same passages over and over.

Ending Passage Tags
cc or continue: This should only be set on an ending. It tells the Choosatron if the player is allowed to insert a coin to continue (by allowing them to move backward choices they’ve made). Again, this is to allow the author to decide how their game should be played. Valid values are either ‘true’ or ‘false’. You can also put 1 for true and 0 for false as well. This is set to true by default.

eq or quality: This is the ending quality. Valid values are 1-5, 1 being the worst kind of ending, and 5 being the best. Keep in mind that a bad ending doesn’t mean dying. In Thanksgiving your purpose is to bond with a family you’ve never met and not cause a scene. All endings must have this tag.

To enter a tag, type either the short or long version, a colon, and the value. No spaces are allowed. A space is what separates tags. In the “Start” passage you’ll see sv:1.0 to set the story version. It doesn’t have to be a valid number, so you could have sv:1.0.1 if you wanted. If I wanted to set an ending with quality 3 and 20 points, I would type this in the tag field:

eq:3 pp:20


quality:3 points:20

That’s it! Wordy I know, but hopefully it makes sense.


  • Add true word wrapping on passage/choice printing.
  • Add logging for stories played/choices made, and total coins inserted.
  • Research adding a scannable barcode/QR Code at the end of plays that contain play data.

Future Features
I’d love feedback on what would make writing a story more fun and versatile for you, the authors. So far we have everything a CYOA book can do, points, and slightly more advanced navigation.

Negative Points
I was thinking of adding a negative points tag ‘np:5’ or ‘negative:5’ would remove 5 points.

I’d like to include more formatting that will allow you to set simple variables, or values, when certain choices are made. This along with being able to have future choices dependent on those set values opens up possibilities akin to text adventure games made for PCs decades ago.

For example, you could set a variable if the player picks “Take the crystal skull”. Then later in the story instead of having to ask the player if they picked it up (which means the ability to cheat, like in the books), you could have a choice only print out if that variable is set. The control you could have over the flow of your story is limited only to your imagination!

Visual Feedback
I’m looking into adding an RGB LED to the hardware, and adding a new tag that would allow the author to set the LEDs color in each passage. Could be feedback on how they are doing, how close to danger they are, or be an actual clue that assists gameplay.

Audio Feedback
I’m looking into adding a piezo speaker (like an old internal computer speaker), and adding a new tag or formatted item like choices to allow the author to create sound/music that can be played when a player arrives at a passage. Would be great for nostalgic video games noises (dying, victory sounds) or simple tunes to enhance the story.

Ending Multiplier
Currently, unless I print it out, the player doesn’t know the ending quality they found (1-5), except that with quality 5 it is indicated that they essentially ‘won’. Would it be interesting to have the points of an ending (if any) multiplied by the ending quality automatically to help create a greater range of possible scores. Of course an author could do this manually. Perhaps a tag like ’em:true’ or ‘multiplier:true’ to turn this feature on.

Comments ( 0 )
2015 ©: Monkey with a Mustache, LLC. All rights reserved.