Can we make a better parser tutorial?

It’s hard to learn to play parser games. In general, they have a pretty steep learning curve, especially when compared to choice-based IF.

I won’t claim to be particularly skilled at writing parser tutorials. (It would be embarrassing if I tried, since none of my games have an integrated tutorial. I’ve always targeted experienced IF players as my audience.)

But if we want to promote the parser games as a medium (which I certainly do!), then I think our best bet is to flatten the learning curve. And the best way to do that is for more parser games to be accessible to new players, and for those tutorials to be of higher quality.

So - what does it take to make a good parser tutorial? Are there some new ideas to bring to the table, or have the prior experts already knocked it out of the park?

(I wrote about this at more length today, but I wanted to start the conversation over here.)


Are you interested in discussing only integrated tutorials? I ask because your post made me wonder if anyone has considered making a short video tutorial. I’m not volunteering to do it myself, but for someone with the right personality, it could be a lot of fun.

As you mentioned, conventions are a big part of the learning curve. I found reading ClubFloyd transcripts helped with that–just observing people’s playing strategies, how they’d almost always type “x me” first thing, for example.

1 Like

I feel like integrated tutorials are better than non-integrated tutorials, but I’m open to discussing anything in this thread that could improve the new user experience.

1 Like

I like the idea of integrated tutorials. Especially if they can be prompted to be disabled at the start of a game for veteran IFers. In my works, I’ve started to give the address of zarf’s how-to-play-IF card in the HELP section. But, of course, it’s not ideal, just helpful until maybe something better comes along.

The idea of a video tutorial is intriguing to me cuz I like making little IF-related vids. Maybe that’s something I will think about. Not saying I have the personality for it, just the time and drive maybe.


As far as tutorials that don’t look like tutorials, what about something like An Earth Turning Slowly? Could something hybrid like that be used as parser introduction, before trying a full-fledged parser game? Or, come to think of it, maybe it would actually be frustrating when you go on to try the parser game and no longer have the suggested commands. But maybe elements of that would be useful to try to incorporate into a parser game.

Hypertext is good at making it obvious what you can interact with, and parser can do this by highlighting objects with something like Aaron Reed’s Keyword Interface (even if you don’t go the rest of the way and use those nouns as keywords). I tend to think the standard actions are more of a challenge than nouns, but maybe this would be a step in the right direction for a beginner-friendly parser game.

Edit: I’m not sure what has already been tried in this area, but what about giving suggested commands to try when a player types something that isn’t understood? Similar to automatically suggesting conversation topics.

1 Like

I think we can split tutorials into at least two categories (There are probably more, this is just what comes to mind now).

  1. “Training wheels” at the start of the game.
Outside of House
You are outside a whitewashed house with a mailbox. The front door is to the east. To the west, a dark forest stretches out.

(You may want to try EXAMINE THE MAILBOX)

> examine the mailbox

It's your average white, suburban-looking mailbox.

(You may want to try OPEN THE MAILBOX)
  1. Parser responses that aim to teach the boundaries of the parser understanding.

[I don't respond to questions, only commands. You may want to try EXAMINE THE MAILBOX]

An important step in all of these are typographical enhancements to help readers distinguish between things they’re supposed to type, out-of-character help from the parser, and game content. Ideally, any instruction from the parser (like FLUNGE THE GOLDFISH) should be hyperlink players can click on to have them happen immediately.

Not exactly in the field of tutorials, but related, there is value in having the parser respond to certain “nonstandard” verbs by doing something. For example, implementing “GO TO”; that’s an example of an interaction that new players may very well expect to work even though historically it doesn’t.

1 Like

Juhana was working on one here:

1 Like

Two more entries for the list of existing tutorials:

Ryan Veeder’s “So, You’ve Never Played A Text Adventure Before, Huh?”, which is apparently more tutorial than game.

And Jimmy Maher’s The King of Shreds and Patches has a tutorial mode as well.

(Thank you respectively to Emily Boeghim and David Welbourn for tipping me off to these!)

1 Like

I think a big problem with tutorials is the reinventing-the-wheel aspect: someone can put in a ton of work on designing a tutorial feature for their game, but then the next game has to redesign the whole thing, and not every game is going to have a natural tutorial zone at the beginning, and this is a big obstacle to a new player being able to pick up whatever game they happen to hear about.

At the same time, one-size-fits-all approaches are problematic for new players, because approaches to implementing parser IF vary a lot. Standard verb lists aren’t super-helpful, for instance, because most games only use a subset of them - an experienced IF player holds lots of commonly-used verbs in their head without the expectation that they’ll be useful in every game.

(Tangent ahoy: I’ve wondered about the possibility of is something that would generate a verb word cloud for each specific game, based on successful play-throughs. There are some obvious problems with this - you wouldn’t want an optimal playthrough, since that would likely underestimate how much the player should be using things like X - but you wouldn’t want to include total-failure verbs, or verbs which effectively constitute spoilers, or whatever. But it’s a thing I have dreamed of. OK, in my dreams they float, glowing, in the air around your screen, swirling intelligently as the player reaches out a hand to tap one.)

1 Like

Is it just me or would it be cool to have basic code freely available to let people put in their games, like at a start screen (not just an extention but the code itself so we can alter it if our game needs it) were you can go
New / Game / Start etc
Restore / Load

Death off the Cuff and PataNoir both have integrated tutorials in the newest releases*. The fact that none of the mainstream DotC reviews complained about the parser seems to indicate that the tutorial was successful**. Of course, both of those games also streamline the parser somewhat.

*Using the same tutorial extension as “The King of Shreds and Patches”.
**Pocket Tactics even described the parser as “less burdensome than I expected”.

I did work on a tutorial game a few years ago, but to be frank I never really believed a separate game to teach how to play other games would be very useful and I’ve pretty much reversed my opinion on tutorials since then. (I’ve even had a presentation at a conference on the subject.)

In my personal opinion the first faulty assumption is that playing IF is so hard that you need a complex tutorial. The second faulty assumption is that the problem stems uniquely or primarily from the parser. The third faulty assumption is overestimating the actual scope of the problem. (To clarify: these are things that have generally come up during the years when tutorials are discussed, not in this particular thread.)

This is the basic pattern of commands understood by a parser:

  • Move around using compass directions (NORTH, SOUTH, SOUTHWEST…) and IN, OUT, UP, DOWN, ENTER, EXIT
  • Interact with the world using commands with only a verb (JUMP, LISTEN), with one noun (TAKE KEY, OPEN DOOR, PUSH BUTTON) or with two nouns (PUT CAT IN BOX, UNLOCK DOOR WITH KEY)
  • Type INVENTORY to see what you’re carrying, LOOK to see the room description again and remember to EXAMINE things

That’s it. The rest are minor details (abbreviations, pronouns, UNDO, saving/restoring) and story-specific things (custom verbs, conversation system, commanding NPCs). Does anyone here actually remember having to struggle with learning the verb-noun[-preposition-noun] pattern when first playing IF? Did anyone really, after reading or being told how to play, still try to command >WHAT’S INSIDE THE BOX YOU MENTIONED?

The real problem is not the parser but genre conventions that lead to game design that’s opaque to new players. By that I mean that it’s extremely common for a story to start with a short exploratory segment before the player’s immediate goals become obvious. The player is expected to walk around a bit and get to know the surroundings and the actual plot after a timer or after entering a certain location. The intro might give the long term goal (“save kingdom from the orc horde”) but there is no indication what the very first step to get there is (“pick up your backpack and your walking stick”).

Seasoned players start examining things and picking them up and wandering about, but that’s only because they already know that you usually have to poke around to find the trigger that gets the story going. This is all good and well for people who know these conventions, but when a new player types >WHAT AM I SUPPOSED TO DO, they’re not asking how the parser works. They literally don’t know what their goals are and what the story expects from them.

Ideally you’d have a short segment that makes the immediate goals always crystal clear, reaching them is trivial, and the game holds the player’s hand all the way through.

If the player still types >I WOULD LIKE TO PULL THE LEVER PLEASE after all this, I’m not sure that a more detailed tutorial would be of any more help. In fact if you do something like this:

…and the player doesn’t get how the game is supposed to be played, I’m pretty sure that they don’t want to play the game in the first place.

After this the following puzzles should be in the order of difficulty, starting with a very simple non-puzzle (a door is locked and the key is on the table in the same room) and gradually getting harder. This is something that’s very common in other games but traditionally not done in adventure games, other than perhaps having the most complex puzzle last.

Finally, when tutorials or improving the parser is discussed, it’s often silently implied that a lot more people would play IF if they only knew how. That I’ve never believed: enjoying parser IF requires a rather specific intersection of interests (literature, games, computers, puzzles) that, even with a best-case scenario where the parser is tuned to perfection and playing IF is taught to everyone in elementary schools, people who enjoy playing IF will still be in the minority. So even when you observe someone trying a game and immediately putting it down, it’s not necessarily the parser’s, the game’s, or the author’s fault. (This is of course equally true of all types of games.)

If a game grabs someone’s interest they’ll learn how to play it if the game itself doesn’t put hurdles on their way. This is why games like Lost Pig and Violet are quite universally praised even by people who have never played and might never play another parser game again, and comments like “would have wanted to play, but didn’t know how” are conspicuously missing.

(This is not to say that the parser couldn’t be improved. It certainly could be, in many ways, but that’s another discussion.)


FWIW, I had the most success showing a non-parser-fan a game when I used the introductory postcard. Knowing which particular actions were likely to work seemed to reduce the frequency of typing things that more or less fit the verb-noun pattern but were not understood.

That’s probably way more relevant than anything else about getting the player used to the parser. Vocabulary. The few handful of verbs that will get you most anywhere.

(I wish I could expand this into a more helpful and analytical discourse, but lately my brain feels fried. In my defence, yesterday, after a day’s work, I had singing class and I sang Wagner, Bellini and Leoncavallo one after the other - In fernem Land, the Pollione aria AND cabaletta, and Vesti la giuba. So I think I can be excused for feeling like I went three rounds against a steamroller, and writing accordingly)

I have literally sat and watched a couple of complete IF newbies play through their first parser game, separately, and can testify that at least for these two young people, the syntax was not a huge problem. Many young people nowadays understand the concept of web/computer languages, and even in MMORPGs and so forth you get, say, certain actions that can be triggered by typing a phrase in a specific syntax into the chatbox. (Now one of them was a bit of a geek, so maybe she had a leg up on that sort of thing, but the other wasn’t particularly.)

1 Like

I like what you wrote Juhana. So if there should be a tutorial, it shouldn’t be so much how to use the parser, but more how to go from a series of actions towards achieving a goal.

1 Like

Juhana, you make a number of excellent points, and I particularly agree with your point about parser game design and the problem surrounding lack of direction. However, there was one thing I wanted to respond to specifically.

I agree this is one of my starting assumptions - that parser IF has a larger potential audience than an existing audience. However, I’ve only come to believe this in the past few years, despite many years more of playing IF.

It was obvious to me in 2000, 2004, 2008, that text adventures (in any interface) were a dying medium with a lingering niche audience. I was happy to be part of that niche audience, but I didn’t see hope for some kind of renaissance. Graphical games wholly dominated the attention of the mainstream gamer.

But that’s not the current situation. Commercial IF is thriving right now. The mainstream gaming press routinely takes notice of IF, and there are paying audiences reliably supporting IF games and platforms such as Fallen London, 80 Days, Lifeline, Choice of Games, and Twine. However, parser games have not experienced the same upswing as hyperlink games have.

Are parser games so very different than hyperlink games, that an audience receptive to other types of text-based gaming will remain unreceptive to parser-based text adventures?

The answer might be “yes”. But I’d like to experiment with the idea that the answer is “no”.

Similarly, I may be wrong about whether or not the parser learning curve plays a part in the audience we don’t have, but it can’t hurt to have the conversation.

1 Like

While I agree with the game design lessons you’re drawing from this, I had a very different experience with IF novices. (It is definitely a problem for some non-novices, namely me; if I wind up in a short exploratory segment where I don’t know what my immediate goal I usually don’t make it past about five turns of banging my head against trying everything that seems like it might work. But that’s another story.)

I tried “Tea and Toast” on my non-IF writing group. I modestly believe doesn’t have these problems; there’s no navigation, your goal is in the title of the game, and you start out surrounded by implements that have fairly obvious uses for doing that. The IF card didn’t seem like it’d be much use here, since about half the command didn’t apply, so I sent them some instruction on how to play, which are under the rant. (They were playing it at home, without me there.)

[rant]OK, so here’s my thing. It shouldn’t take very long,
but it takes a little explanation for what you need
to do.

The thing is called “Tea and Toast” at … ast.zblorb

Basically, you’re playing a character. It starts with
a short bit of text and a > sign. Type a basic command
for something for the character to do at the >, and
you’ll get another bit of text and another > sign.
Rinse, lather, repeat. It shouldn’t take much more
than fifteen minutes once you figure out how it
works; in fact I’d recommend playing through two
or three times just so you can see how it works
(also you won’t get the same text every time).
In particular your second time through you
might be able to make the tea and toast more

About the commands: You want to type simple things
like VERB NOUN for the most part. One very useful
one is “Look at the teapot” (or whatever other objects
you see around), or “look at me” for that matter.
If you like you can abbreviate this as “x”, “x teapot”
or “x me.” (Short for “examine.”) With other commands,
hopefully it’ll be apparent just which verbs you want
to do from the things that you’re dealing with; “open
the cabinets,” “fill the kettle,” “pick up the teacup,”
“put the bread in the toaster” can all be useful, for
instance. You won’t ever have to talk about
more than two things at once (“fill the kettle
with water” is fine, “fill the kettle with water from
the sink” is too complicated).

[Actually I just noticed that the message you get
when you type “put bread in the toaster” but you
haven’t sliced the bread yet isn’t helpful, since
the game thinks you’re trying to put the breadbox
or the unsliced loaf of bread in the toaster. If
you see the sentence “You can only toast
bread in the toaster” please change it to “You
can only toast sliced bread in the toaster.”]

in any case, there isn’t meant to be anything here
to stump you – eventually the game will start
giving you hints about things you can do to make
the tea and toast, which should tell you some
commands you want to type. If you don’t want to
wait for a hint, type “help” or “hint” and you’ll get

Other commands: you can type “think about
[something]”, “look” to get a description of the
kitchen again, “inventory” or “i” to see what
you’re holding, and “z” or “wait” if you need
to kill time. But you might not need these.

This probably makes it sound more complicated
than I hope it is! Aside from “look at/x,” if you
type simple commands that express what
you want to do hopefully you won’t have too
much problem.

…oh, and it’s under the pseudonym “Maria del
Pangolin.” Long and uninteresting story.[/rant]

And they bounced off it hard. One person immediately tried “look out the window,” or something like that, and explained to me, “Well, in something like this, people are going to imagine their own kitchens, so I did what I would have done in my kitchen.” And I was like “Who tries to interact with a noun that isn’t mentioned in the room description?” But novices aren’t necessarily familiar with that convention.

Another person got a lot of stuff done and then typed “the kettle boils.” They wanted to jump ahead to the part where the kettle boiled, but they didn’t know how to do this. And even “wait till the kettle boils” wouldn’t have worked (exercise: on a scale of one to one billion, how much of a headache would it be to implement that?)

It isn’t entirely that they aren’t interested in interactive fiction, either, because when I gave them a Twine piece they played through it and gave me comments about the piece rather than about the interface, and the piece I gave them was terrible.

There were probably a lot of things I did that made this not as novice-friendly as it could’ve been–for instance, using a game where they might finish a task early and have to wait–but I felt as though the “tell people how the commands work and set them up on a game that’s not awfully verb-guessy” thing didn’t work at all. They just had no sense of what the game could and couldn’t do. I felt as though I had given them a certain idea of what they could do but I would have had to really explicitly tell them about a lot more limits (don’t try to interact with something unless it’s mentioned in those words)–I can suspend disbelief when I play because I naturally don’t try to push the limits, but it’s much more difficult for novices–and if I’m explicitly telling them “Only interact with stuff that’s named in the text” maybe I should just be giving them hyperlinks?

So I think it’s not just a question of players not knowing what their goals are. At least sometimes, they really don’t know how to interact with the parser, and just telling them a few commands they can type isn’t necessarily going to get them to the rest.

There’s a MUSH transcript from Brian Moriarty where he tells this story:

And my reaction at the time was, well, don’t lie to people about how to interact with your program. But now I feel as though I’m in a situation where I’m saying, “Look, I can do this magic trick” and pull a rabbit out of my hat. (Or set something up where “Fill the kettle from the sink” works.) And my players say, “OK, now make me levitate.” (Or type “look out the window” because there should be a window there.) And, well, I haven’t explained the limits of the magic, and if I tried to explain it in advance then it wouldn’t be magic anymore.


Even if the only audience for parser IF is people interested in the intersection of computing, games, puzzles and literature, that still sounds like a much bigger audience than parser IF is reaching right now. Hell, it sounds like a description of half the people who listen to NPR.

However, it is also true that it’s fine to design something intended for a niche audience or to bank on genre convention, especially in an experimental space like what a lot of IF is meant for. Dwarf Fortress has a one-of-a-kind interface that is also incredibly arcane, and yet it’s a big success in its own way. A lot of mainstream games only explain the mechanics that are particular to them, and not the basic left-stick-to-move-right-stick-to-aim interface that they share with many other games.

Rather than trying to incorporate a tutorial into every parser game as a standard feature, it might be best to steer people towards parser games that are particularly good for newcomers. In many ways, there is an issue of handling how new people are exposed to IF in general or parser IF in particular, and trying to 1. increase that exposure, and 2. manage that exposure so people’s first parser game isn’t Make it Good or something.

And yeah, it’s absolutely true that teaching people the boundaries of the parser is really difficult. There’s no one-sentence description of what the parser understands, and the role of the player relative to the parser (Is it an interlocutor, a blank line where I can continue the story I’m reading, or a command prompt?) is obscure to someone who hasn’t used one before.

In my opinion, Aaron Reed solved this problem in Blue Lacuna: highlight nouns in the text, and ask the player to type in highlighted nouns. Typing in an object with no verb would examine it, and examining would suggest verbs you could use. The first time you pick something up, suggest “inventory.”

The sad thing is that this problem requires not just solving the problem, but asking every IF author ever to solve the problem, too, and it’s obvious that most authors just don’t care about the problem. Most parser games have literally no documentation for newbies at all. They’re not even trying.

So maybe we’d want/need a major parser platform (Inform) to make games that are newbie friendly by default. (At a minimum, “have you played interactive fiction before? y/n” and highlighted nouns that can be examined without a verb.) But if it hasn’t happened by now, I’m guessing that it won’t ever happen.

1 Like