Learning Twine: Part 1

Maybe you have heard about Twine before this post. If not, it's a tool being used by an increasing number of independent developers and writers to make their first game. Or even their twelfth.

At its most fundamental level, Twine is a combination of Twee, a command-line tool, and a graphical interface used primarily to create interactive stories. It allows a user to create a Tale, a collection of Passages, and create links between those passages. It's seeming simplicity has allowed many to make their first game with very little programming knowledge and, for those who know JavaScript and CSS, to make more intricate projects.

However, all begin with the same screen.

All Twine stories flow from Start, the first passage. From this single point, all links, other passages, and even advanced programming, well, starts. It all begins there.

By adding two opening and then two closing brackets around some text, a Link can be created to direct Twine to transition, after the user clicks on it, to move to another passage. This is the hidden strength of the tool. Using Links to move betwene passages creates the appearance of a choose-your-own-adventure game, but can also be used to test command-flow for a more advanced project too.

As an example, I have created two passages. The first is the default, Start, and another is named Cry for help. I have also written a Link in the Start passage to connect the two together.

Note: Passage names are case-sensitive. "Cry For Help" and "Cry for help" are two different passage titles.

Notice that, on the map, there is an arrow going from Start to Cry for help. When able, Twine will try to show you visually how you have connected passages using Links and other connective commands.

When editing passages, each will have a separate window for its title, tags, and content. This allows you to quickly compare what you have written in different passages at a glance.

Note: As best as it can, Twine will color-code certain items when you use special tokens like two brackets or two less-than signs to begin a selection of text.

Adding an additional Link to the Start passage is as easy as typing two opening brackets, writing the name of the passage, and then ending with two closing brackets. However, this does not immediately create the new passage. To do that, you can either select Passage->Broken Links from an individual editing screen, or use the menu to select Story->New Passage and then name it correctly.

Note: Remember to save the story often. Get into the habit of saving after a change so, should something unexpected happen, you will be able to restart with your latest work.

In my example, I now have three passages: Start, Cry for help, and Search for an exit. There are two Links from Start passage to each of the others. As far as a story goes, it is not very exciting, but it demonstrates the basic functionality.

At this point, it is worth running the story in a web browser in order to show exactly what a user would see. This also allows us to change something, view the visual output afterwards, and then change something again. Using this method, we can iterate very quickly on our story while both editing and viewing the result after each new change.

To build a story, go to Story->Build Story from the menu. This will prompt you to save the story as a HTML file and will then open the output of your work in your default web browser for you to see how a user might view what you have created.

The default Story Format is Sugarcane. It uses a black background with white text for passages and grey text for Rewind, Restart, and Share. Personally, while I find it useful for some stories, it taxes my eyes to switch between the Twine editor, with a grey background, and the story with a black background as I test things.

Note: Story Formats can be changed from the Story menu. Going to Story->Story Format will show the current formatting options.

Using the Jonah Story Format, my example looks slightly different. Instead of the black background, there is a grey one with the Restart option now in the top-right of the page. The passages too are now centered on the page.

With both Story Formats, however, neither the Story Title nor Story Author was set. This is because Twine expects each to be in separate and specifically named passage. In order to set the Story Title, a passage name StoryTitle must be created. For Story Author, a passage named StoryAuthor must exist.

Finally, now that StoryAuthor and StoryTitle have both been set, the story must be Rebuilt. From the Story menu, this is Story->Rebuild Story. In the background, Twine will rebuild the story, but will not display the new results.

To see what the story now looks like, refresh the web page. If needed, open it again using your default web browser. Now, it will show the passages created as well as the Title and Author for the story.

In my next part, I will show how to use Choices, change the visual layout with CSS, and make the content of passages dynamic using variables and conditional statements.

(If you would rather follow videos instead of reading along each time, I have also released a series that covers this same material, variables and conditionals, and using CSS with a simple macro.)