Things I’ve recently learned about hypertext

Prior to writing Swan Hill, I had never tried to make anything in Twine but standard “choose your own adventure”-type stories with text prompts and choices. They were fun to write but left me feeling a little bit cold. To be honest, the CYOA text-prompt-and-choice structure– the stilted, awkward way it seems to constantly interrogate the reader– doesn’t always fit very well with my writing style.

After almost a year of reading great Twine stories without the CYOA structure, I came across Breakfast on a Wagon With Your Partner, which uses Leon Arnott’s replace macro super-effectively. It reminded me that I’d never actually experimented with replace myself!

I’d recently attended a loud, busy party for the first time in months, and had left feeling pretty sick and overwhelmed. I quite liked the idea of using the replace macro in a party scene to give a reader that same sense of wandering overwhelmed-ness. I imagined a paragraph which slowly expands from concise sentences into long, confusing ones as detail upon detail is added.

The idea excited me. To prepare, I went back and read a bunch of other stories that feature this macro. I immediately noticed two things:

  1. Writers do not usually distinguish replace links from other links. This can lead to confusion and missed content, particularly if the page is covered in links that all behave differently.

  2. The use of color in Breakfast on a Wagon With Your Partner was really helpful! It distinguishes your speech from Sam’s without cluttering up the page.

I wondered why I hadn’t seen color used to distinguish replace links from non-replace links in more Twine stories. In the end, I decided to give my story color-coded links. It was going to use a LOT of replace, and I wanted the reader to anticipate and understand what each replace link would do. I thought I could write the story in two weeks. There were really only a few things I wanted to illustrate with it.

But I didn’t realize how complicated the replace macro could be! The first night I sat down to write the story, I wrote straight up up to the first +++ in one go. When I wrote the scene where the Chancellor lights the Duke’s pipe, however…


I realized that I could use replace in more interesting ways. I’d been thinking of using replace simply to add more detail, but now I realized that I could also use it to give scenes a sense of timing and suspense.

Then I discovered the combined replace macro, which includes replace, insert, revise, and other macros. With this expanded toolset, I realized that I could use replace and the other macros to:

  1. …Illustrate the main character’s style of thinking. He spends a lot of time in self-reflection. I could use replace to show these moments of reflection and make the reader replicate his way of thinking.

  2. …Replicate various feelings, like confusion, the sensation of being overwhelmed, the passage and transformation of one kind of physical pain into different kinds of physical pain, etc.

  3. …Apply timing to specific events. The pipe-lighting scenes are good examples of this.

  4. …Avoid walls of text. “Unfurling” the text makes sure that the reader is “checking in” at various points during a longer passage, and prevents that longer passage from being so overwhelming at first glance.

  5. …Make the reader focus on specific words and pieces of information by inviting a click, but not whisking them away to another page. Many Twine games use page links to direct attention to specific words, but page links can be disruptive, because they replace all the text on the page. Replace let me keep the text on the page, and even keep the clicked word on the page, if I wanted. This let me use the clickable-word attention-directing mechanism multiple times in one passage, if I wanted.

I was so excited by replace that the first completed draft of my story used it WAY too much. Here are some of the pitfalls I ran into when I began over-applying replace:

  1. Although replace is often less disruptive than a page link, it is still disruptive. Some passages– particularly those which do not contain a rhythmic series of events– suffer if the reader is forced to “check in” with clicks. I ended up removing replace from many passages where the events taking place were contemplative or slow.

  2. Replace can draw too much attention to something. Applying it overenthusiastically caused me to “unbalance” some of my paragraphs.

  3. Using replace to insert one idea inside of another is not always the best choice. Too many disparate ideas on one screen can diminish one another.

I also ran into some problems when readers began reporting that they could not understand the difference between red and black links. This was pretty confusing to me, since I’d constructed the first several passages with an eye toward teaching the player how red and black links differed. The first screen after the title screen, for example, forces the player to click a black link in order to expose a red link. Other passages in the first section of the story give the player a good opportunity to see how black links behave. I thought that by the time the player got to the pipe lighting scene, they’d understand completely.

However, it turns out that some people didn’t. I spent a good week trying to figure out how to communicate the color-coding effectively. It was a pretty weird problem, since some people were telling me, “man! I love the color-coded thing!” while other people were telling me, “HELP! I DO NOT UNDERSTAND COLORS.” There was very little difference between these two groups of people. Some people who had never played hypertext were fine with the colors, while some people who had already played a handful of diverse Twine games were intimidated by the colors.

In the end, I realized that most of the people communicating a confusion with link colors were communicating the confusion they had first felt with the link colors, and that an initial confusion with the the link mechanics did not prevent them from finishing the game or appreciating the tale. I was worried about cluttering up the story or diminishing the simplicity of the beginning by introducing an explicit tutorial. It was very important to me that the first part of the story focus 100% on the brothers and the way they interacted. I decided to add the three small clicks on the first page– “to begin the story, click here; now click this word; now start”. This, I guess,  pretty much doubled the “tutorial” on the first two screens. I’m still not sure it was completely effective, but by that point my feedback was getting so contradictory that I was eager to give up and let the story go.

I have another idea in the works for a different “link mechanic” that I also plan to use with color. Even though some of my playtesters reported difficulty understanding what was going on with the links at first, I think the colors were ultimately an accessibility boost, and they gave me more tools to tell a more complicated and nuanced story.

I’ve played a lot of Twine games where the player was supposed to feel unsettled or confused, and confusion about what a link was likely to do helped to create this feeling. However, my stories are usually about specific characters whom the player “plays” like a character in a play. They are “controllable,” but they have personalities, and I want to convey very specific things about their personalities and experiences. This requires a precision of communication that is not possible when all links look confusingly alike.

Anyway, I’m still excited to figure out cool new stuff to do with replace! I feel like I’m really starting to “get hypertext” in a way that I couldn’t when I was exposed to lifeless, dull, academic hypertext stories in college. There’s a huge difference between learning about interactive story structure by reading dull writer dudes from the 90s, and learning about it by actually examining how it affects your own work. I learned a lot while writing Swan Hill and I can’t wait to apply it to my next project.


  1. Pingback: Aquarium notes | Down for the Barbecue

  2. Pingback: October Link Assortment | Emily Short's Interactive Storytelling

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s