The Parser Tutorial Challenge

My brother’s favorite board game is Mage Knight, a spectacularly intricate Vlaada Chvatil creation. I think it took him three hours to teach me, and he’s good at teaching board games. (If you want to learn Agricola in five minutes, I refer you to my brother.)

My sister-in-law enjoys board games, but she has limited patience with learning them. Her standard rule is that she has to be playing within five minutes of setting up the game. My brother’s an amazing teacher, but I suspect they’ve never played Mage Knight together.

For every person like my brother, there are many more like my sister-in-law, and the ratio is even farther skewed in the digital world.

Players hate tutorials.

But before you can play a game, you have to understand how to play.


The perfect tutorial

The perfect tutorial doesn’t look like a tutorial, or a manual, or a help file. It looks like you’re already playing the game.

Three graphical games that excel at this:

In all cases, the tutorials are seamlessly integrated with gameplay. (In particular, Portal can be described as one giant tutorial.)



All three are well worth playing if you’re studying tutorial design. Some related resources:

  • Plants vs. Zombies: Check out George Fan’s insightful GDC talk “How I Got My Mom to Play Through Plants Vs. Zombies”.
  • Portal: Play with the developer commentary on, or view the extracted developer commentary on YouTube. (For context, it’s best if you’ve already played Portal.)
  • Dragon Box Algebra 5+: I don’t have a developer resource for this one, but you can watch the first few levels in this YouTube video series. In particular, notice how rarely the tutorial uses text. This is important for their audience, as a 5-year-old’s reading comprehension may vary greatly, and it has the side benefit of reducing localization costs.
DragonBox Algebra 5+

DragonBox Algebra 5+

…isn’t necessary in choice-based IF

Why are so many game authors using Twine? In part, it’s because Twine makes game creation easy, but it’s also because Twine games are easy to play. Instead of teaching a new interface, Twine relies on a well-understood interface (the hyperlink). It’s still possible to make a mechanically confusing Twine game, but authors have to go out of their way to do so.

For the most part, Twine games don’t need a tutorial.

…and is extremely difficult in parser IF

Among some parser IF veterans, there’s a common misunderstanding that parser game mechanics are easy to learn. I regret to say it isn’t so. The learning curve for parser IF isn’t Dwarf Fortress steep (official motto: “Losing is fun!”), but it’s pretty steep.

The parser game illusion is one of infinite choice. But in practice, the options available to the player are tightly circumscribed by convention, by the game engine, and by authorial choice.

Furthermore, it isn’t enough for the player to know what to do next. The player also has to phrase it in one of the limited ways that the parser can process.

Valid commands
> examine bucket
> get bucket
> inventory

Invalid commands
> what does the bucket look like
> I want to take the bucket
> what am I supposed to do now

This is not intuitive. As a result, most parser games self-select for an audience that already knows how to play parser games. And as a result of the audience self-selection, the majority of games are written for an audience that already understands parser games. It’s an ongoing cycle.

This problem hasn’t gone unexamined. In particular, Emily Short, Aaron Reed, and Andrew Plotkin have spent significant time on the problem of making parser IF accessible to new players.

A handful of parser games with excellent built-in tutorials:showimage

Key external documentation for new players:

There are also several Inform 7 extensions aimed at helping new players, most notably Player Experience Upgrade by Aaron Reed (partially outdated in the current version of Inform 7) and Basic Help Menu by Emily Short (built into Inform 7 as of the latest version).

Can we do better?

Interactive fiction has a huge audience right now. Many members of that audience are willing to pay for games, and the mainstream games press is paying an unusual amount of attention. Examples include not only various Twine games, but also 80 Days, Lifeline, Fallen London, and everything from Choice of Games, among many other examples.

hadean-landsIf parser IF is going to find a larger audience, now is the time. Hadean Lands (recently Greenlit on Steam!) proves┬áthat it’s possible to create commercially viable parser games, but it’s not reasonable to expect one game to drive a renaissance.

What’s the next step to increasing the parser IF audience size? Flattening the learning curve.

Consider it a design challenge. Can you create something as seamless as the Portal tutorial? Can you improve on the Bronze tutorial, or the Dreamhold tutorial? Can you design – reinvent! – a parser tutorial that’s more intuitive, less obvious, more streamlined, and more fun?

Honestly, I don’t know if it can be done. I have incredible respect for the three authors above, and there’s a certain temptation to say “if that’s what they produced, then nothing better is possible.”

But if none of us try, then none of us will succeed. And then this opportunity will pass us collectively by.

I’m going to give it some thought. I hope you will too.

Bookmark the permalink.


  1. A friend pointed out to me that a steep learning curve is actually good, because learning curves measure how much you will learn over time, not how much you need to learn over time.

    But as Wikipedia notes, the expression “a steep learning curve” is used colloquially to mean that something is hard to learn. And if I asserted that parser games have a flat learning curve and we need to make it steeper, I think more people would be confused than the other way around.

    So I’m going to leave it as-is, but if it bothers you – sorry about that.

  2. Emily Boegheim

    Have you seen Ryan Veeder’s tutorial game, “So, You’ve Never Played a Text Adventure Before, Huh?” I think a lot of people missed it when he released it last year. It’s a standalone tutorial rather than a game with a tutorial attached, but it does some interesting stuff with teaching conversation systems, and is also a sequel of sorts to Robin & Orchid.

    I think about how to teach new parser IF to new players a lot, on and off. Tutorials are important, but I wonder if we have to go further and reconsider some of conventions we’re used to. For instance, it’s probably not obvious to first-time players that examining yourself might be important, and who would think to type INVENTORY if they didn’t already know it’s a standard command?

    • I haven’t seen it! I’ll go look.

      I agree entirely about “examine me” and “inventory”! I remember my surprise when I discovered the modern IF community and read a comment on raif to the effect of “I type x me, and if there’s no custom response, I quit on the spot.” I had never even considered typing x me until I read it.

      • “Examine me” is almost never important for players. It’s just a thing that IF folks have decided to use as a shorthand for “Has this author spent time polishing?”

  3. Leadlight Gamma has a very specifically programmed tutorial mode for a parser game. I only released it a couple of months ago.

    People thought the manual for Six doubled as a pretty good parser introduction document. It’s probably more recent (2011) than other cited print material.

  4. David Streever

    This is a great post; your blog (in general) has provided a lot of inspiration to me this year. I’m glad I started following it!

  5. I don’t think Portal’s good tutorial is *entirely* to credit for the relative ease with which players can pick it up. The difficulties with newbies to parser IF have to do with the interface, not with the individual game’s mechanics. Imagine taking someone who’s never played a single video game before, let alone a first-person game, and plopping them in front of a video game controller (which they’ve never seen before) to play Portal. Or worse — to play an “open world” video game, which has some small analogy with classic parser IF in that there is the (all-important!) illusion of unboundedness.

    I’ve heard it said that programmers (i.e., people who actually have used command-line interfaces to make computers do stuff) have an easier time understanding the parser IF “controls”. That also suggests to me that it’s a matter of control familiarity. Mainstream video games are everywhere, and children are exposed to their controls from an early age — if not personally, then at least in secondhand pop culture depictions (TV, comics, etc.)

    In fact, wasn’t there an article by someone who literally did put their unfamiliar-with-technology elder relative (parent?) in front of Portal and tried to get the relative to play it? The article documented how much gamers and young folks with tech access take video game conventions for granted, not realizing that there’s absolutely nothing universal or natural about “WASD to walk around” or “walk on health pack to heal”.

    A lot of it is about the relative ubiquity of certain technologies in people’s daily lives. It’s not that the ranks of parser IF authors are filled with stubborn old coots who refuse to make proper tutorials, it’s that parser IF is starting at a disadvantage due to the fact that CLI usage has become the domain of the specialist, while GUIs dominate the nonspecialist market.

    • (On a practical level, this means that someone writing parser IF tutorials with the specific intent of attracting newbies has *different* needs and considerations to keep in mind than someone writing a game-specific tutorial.)

Leave a Reply to Emily Boegheim Cancel reply

Your email address will not be published. Required fields are marked *