Writing a Tutorial Mode in Inform 7

Before the tutorial says anything else, explain the convention that words in capitals are commands but the player is free to type them either way.


Thanks! I worry about over-explaining, but if anyone would know how to do this correctly, it’s you! I appreciate the guidance.

Sadly, it’s not difficult to find total novices to parser games. That camp includes almost everyone I know, so I’m rich in people to show me where I’m screwing up.


It’s also possible to use fixed-spaced text inline, and the typewritery look is suggestive of typing things out, though depending on the interpreter it sometimes looks a bit awkward.

[Another option is to quote your tutorial passages in square brackets. It’s a common idiom for games to quote a paragraph like that when saying “computer stuff” and not “game stuff”, so it might help train the player to recognize that in the future.]


To add to your options, there are also colors. I think with this extension, you could use italics for two different purposes (one colorized and one not colorized).


I think bold lowercase makes the most sense, though, since some of the most popular parsers (Gargoyle and Parchment at least) show the command line in bold text.


Thanks for bringing this up, because I’m unclear on how colors work with various interpreters. I think this would be a fabulous way to do it. I have ascii art with colors in the game, and I made pngs of the art to display, because I was worried about interpreters and color. And I’m not sure if I should have just used the extension and just done them without png images. The other thing about making pngs was that I could make the images bigger.

But if I use color for text, and some interpreters don’t support color, then I think it would be a bad tutorial experience for some users. Can someone clarify whether or not this is a viable option, and generally discuss interpreters and color?

1 Like

I’m writing a game for the same jam and agree that writing an in-game tutorial is HARD. The jam rules require a “give-away” puzzle at the beginning, which means that the game has to be designed around that. My initial draft had the tutorial elements, but my testers pointed out that I didn’t really have a give-away puzzle, so I now have to retrofit it with one that fits in at the start of the game.

I’m using Inform 6, but I struggled with the presentation because of the wide range of different interpreters out there. If you use colour, then some interpreters won’t support it, because the platform doesn’t support colour. If you use bold or italic, then some interpreters won’t support it, because the platform has no concept of bold and italic. If you use mono-spaced font, then some interpreters won’t support it, because all their fonts are mono-spaced.

In the end, I stuck with italic, but I think I will now add @bkirwi’s suggestion of square brackets, as well.

I used the same convention of upper-case characters for commands, but omitted to explain the convention in the tutorial. Another thing to add.

So, thanks for raising this topic and thanks to those who offered suggestions. It’s been very helpful.


@Warrigal Perhaps this is a dumb question, but if the game were made available to play online-only, let’s say through borogrove or iplayif (with no downloadable .ulx file available) wouldn’t that standardize the interpreter for everyone? If the game is hosted through borogrove, you would know which interpreter limitations your players would encounter, right? There are certainly trade-offs with the game not being available to download, accessibility options coming immediately to mind, of course. Just curious if I’m missing anything obvious that would render that option untenable.

wouldn’t that standardize the interpreter for everyone?

Mostly, but not absolutely.

The game file from a web-playable Inform is always downloadable if you really want to grab it. You might have to mess with URLs and do some base64 decoding, but the data is available.

Also, the interpreters on iplayif and borogove are sometimes upgraded. That’s up to the maintainers of those sites. So whatever you’re relying on in the interpreter could, in theory, change.

1 Like

Not ideal, true. Perhaps a disclaimer noting that you can’t guarantee that playing the game locally will work correctly would suffice though.

Good to know, thank you. What if you hosted the file and interpreter yourself? Would that effectively freeze the interpreter, preventing these issues? I know we’re getting into PITA territory here with site hosting, etc., but it may be worth it to control how your game is interpreted by the majority of players who simply click on the “Play Online” link. This may be especially true if you have a finicky tutorial section, as the target demographic of an interactive fiction tutorial aren’t likely base64 decoding.

Again, this is mostly out of ignorance and feeling around for options, so I appreciate you humoring me.

To a certain extent, yes, but the author would have to make a decision between Borogrove, iplayif, Parchment and Vorple. I’m not an expert on any of these, but I believe the features vary.

There is still a big interest in z-code interpreters for retro platforms and I was thinking mainly of those. The features of each interpreter vary depending on the platform. I am discovering that I can’t even use things like European characters with diacritical marks or copyright and trademark symbols, let alone colour and inverse video, if I want to support old platforms.

Do you pick one platform exclusively and insist that everyone use that and maybe alienate half of your potential players, or do you try to target as many platforms as possible and restrict the features? You’re damned if you do and you’re damned if you don’t.

That’s what I always do. This gives me full control over font, font size and window size so that I can do screen grabs for CASA. It’s also the preferred option for visually impaired players using screen readers. As a general rule, I hate playing games in a browser.

You can do that with Parchment and Vorple. This is the ideal option if your games are hosted on your own web site or somewhere like itch.io, which is what a lot of us use nowadays. I’m thinking of using Parchment for playing in the browser as an additional option to the downloaded z3, z5 or disk image file.


OK, I am very depressed about my tutorial, because I just had a player who simply WOULD NOT follow the tutorial directions. I am married to this person.

Every single step of the first few scenes is guided in this tutorial. The problem is that things are timed assuming you’re going to follow the tutorial directions, and of course everything gets out of whack if you don’t follow them.

So should I be draconian in the tutorial? Like, if you try to go south when the tutorial has told you to TAKE something, the game should smack your hand and say “NO! Follow the directions!”.

And there is a choice for whether or not to use the tutorial, and you can turn it off. I was just trying to test it out, and it went about as poorly as an initial test can go.



Sounds like it went well, actually. You got actionable feedback early in your effort. Better to get that sort of thing now than after the game’s release.

As for altering the tutorial, I find it interesting that you have it timed (guessing by the number of moves?) rather than triggered by player actions. The timing wouldn’t be an issue if the next tutorial direction waited until the item was picked up. Also, as far as forcing the player’s hand, I’d consider doing it less directly. Many tutorials start in a section of the game that can’t be left without either finishing the tutorial first or opting out of the tutorial. In the original HALO, you can ignore the doctor running diagnostics on you all you want, but you aren’t leaving that room until you finish that tutorial. Fallout 3 has the “grow up in and escape from the Vault” tutorial sequence that uses this over and over. You can avoid taking the GOAT however long you like, but the game won’t significantly advance until you sit down and take the test.

That’s just one take, however, so trust your gut as well.


I’m also trying to put together a game for the TALP jam and struggling much more than I’d expected with writing a tutorial.
I agree with @pinkunz that things should be triggered by player actions rather than be on a timer but it’s still a pain to write.
Currently I’m starting the player in an exitless hot air balloon with a limited inventory and will only trigger the balloon landing and the rest of the game opening when the player jumps through a few hoops (check their inventory, pick up the items I made them clumsily dropped, …).


In case anyone’s interested in a long read, there’s interesting thread about designing a tutorial mode here: Can we make a better parser tutorial?

I came away feeling like the two most promising options were:

  • Use a very restrictive approach, like Amanda’s exploring… require the user to type in precise commands in the correct order.
  • Use a more complex rules-based approach, like the one implemented in Emily Short’s Tutorial Mode extension.

The first approach has a lot of advantages: simpler to implement, harder to get into bad or untested states, avoids the early paralysis of choice. I have a theory that reading a transcript of gameplay, like Inform used to include in their manuals, was an effective way to learn… since people can often learn to imitate much faster than internalizing rules. A railroaded tutorial is a bit like a transcript you’re forced to type in yourself.

Of course, there are many advantages to the more flexible approach too… among other things, it allows learners to experiment with the rules. Also presumably Short has actually tried it out while I have only speculation and anecdotes.

Also, on the formatting question… I pulled some formatting details from the Z-machine spec. The TL;DR is that nothing useful for formatting help text is actually required by the spec. Glulx might be different of course.

Z-machine digression

Text may be printed in any font of the interpreter’s choice, variable- or fixed-pitch: except that when […] the text style has been set to Fixed Pitch, then a fixed-pitch font must be used.

So interpreters are required to support fixed pitch, but are allowed to print everything else in fixed pitch too, so it’s not always visually distinguishable.

Text can be printed in five different styles […] Roman (the default), Bold, Italic, Reverse Video (usually printed with foreground and background colours reversed) and Fixed Pitch. The specification does not require the interpreter to be able to display more than one of these at once (e.g. to combine italic and bold), and most interpreters can’t. […] An interpreter need not provide Bold or Italic […] and is free to interpret them broadly. (For example, rendering bold-face by changing the colour, or rendering italic with underlining.)

So Reverse Video (as used in the status bar) appears to be required, but nothing else.

If the interpreter cannot produce colours, it should […]

So colours are entirely optional.

This was a fantastic response to a different thread which I feel is very topical to what is being discussed here:

I feel the sandbox being discussed here is very similar to @nilsf 's hot air balloon, or many mainstream game introductions, like Fallout 3 as I mentioned earlier.

1 Like

I lean towards “yes”; and I think it’s the way many graphical games go about this.

If they have extensive UI elements (like strategy games), they’ll often highlight the exact button you have to press and won’t let you proceed otherwise or click on anything else. If they have less UI elements (like FPS), they’ll sometimes allow a small leeway (e.g., you may or may not be able to jump by pressing SPACE even before using WASD to move), but in general you’ll still have to demonstrate the knowledge in the right order.

Relevant quotes:

Emily Short:

Sam Kabo Ashwell:


I was about to link to the long thread; since Ben thankfully already did so, I just want to mention two things from there:

  1. Ryan Veeder’s tutorial game could be helpful: So, You've Never Played a Text Adventure Before, Huh?

  2. I’d like to quote Juhana Leinonen’s post at length for emphasis. :slight_smile:


It’s good you reminded me how simple this should be! TALP wants a tutorial for things like “South is opposite of north”, and to help the player solve the first two puzzles, but just because this particular comp wants such an extensive tutorial doesn’t mean you can’t do a simple and elegant tutorial for most games.


IMHO, the best SO is one who follows their own mind, and has opinions/habits/beliefs of their own that differ from yours. In the long run, such partners provide a much happier and healthier relationship.
Celebrate the fact that you have a partner like that.

Trust Uncle Joaz on this. He has made enough mistakes for both you and him.
Excessively cooperative partners are boring in the long run.

Yes…and…no. Errr…sorry…that’s not terribly clear, is it?
Let me elaborate.

You need to be draconian in your control of information. But you are trying to be draconian in your control of actions. By the time that the player his chosen an action, it is too late.
When the player tries to act, you have two choices, both equally bad: let the player do something that you do not want them to do, or forcibly stop them from doing what they want to do. Either way, cooperation is breaking down.

Be draconian early! Control what the player experiences.
If you do this carefully, the player will not even think of doing all of the things that you don’t want them to do.

Have a look at my post on sandboxes, very thoughtfully referenced upthread by Pinkunz:
( BTW, thanks, Pinkunz, for the compliment )

In the examples given, the writer is draconian, but only in control of information.
The player will not try to do something that the writer does not want them to do, because the game simply does not tell them that such options exist.

If the player learns quickly, they go on to the more complicated parts of the game, and the tutorial breathes a sigh of relief because it does not have to do anything at this point.
If the player flails, the tutorial offers some helpful advice. The tutorial never has to resort to arguing with the player, or retracting anything that they have done. No negative reinforcement is needed.

When the player finally grasps the ideas necessary to get out of the sandbox, they are rewarded with a bigger and more entertaining world. It is always positive reinforcement.


This idea can be extended to multiple levels, in what may be both logically and topologically called ‘concentric sandboxes’.

In the innermost sandbox, as described above, the player doesn’t leave the sandbox until they know basic commands like GET, LOOK, OPEN WITH KEY, and how to move from room to room.

When the game believes that they are competent, it lets them into the next level. Suppose, at this point, the writer wants them to have a basic understanding of conversations with NPCs.
So there may be one NPC with limited possible interactions.

“You can see the key on the floor, tied to a chain. The chain runs under a sleeping Arcturan MegaDonkey.”


“You cannot get the key. You pull with all your might, but the MegaDonkey is too heavy”


“Nothing happens. The MegaDonkey continues snoring.”


“The snoring is slightly lighter. One huge ear twitches in your direction.”


“An eye the size of a basketball opens, and slowly swivels in your direction. A deep voice echoes off the cave walls: ‘The key? That’s what this racket is about? You can have it. Just go away and let me sleep.’
The MegaDonkey ponderously rolls over. Fissures appear in the floor. The key starts slowly sliding into one of them…”


And so the player has they key that allows them to get to the next, less sandy sandbox, and the game knows that they are capable of talking to the more complicated NPCs that they will interact with on that level.


This wins my “post of the month” award.
Thanks for all the helpful advice. And if there is not a game with an Arctura MegaDonkey, that is a shame.