Can we make a better parser tutorial?

It turns out that Tutorial mode is updated for 6L38 and is in the Public Library. (This confusion is my fault–I linked the old version.) And the new version solves one of the big issues with the old one–it now reacts to actions rather than texts, so that “TAKE OVOID” will be accepted even if it asked you for “TAKE THE SILVER OVOID.” (Which is an important lesson to teach, I think–at least we don’t want to be teaching players that if you don’t put every ‘the’ exactly where it’s expected, your command won’t be understood.)

One thing that arises here that I think didn’t arise with the older version is that parser errors print their normal messages. It might be nice to have the messages modified by default for the tutorial to something slightly more explanatory.

I also agree that it’d be good to remark on the tutorialiness of works–not to say that every game must have a tutorial as such (as Neil said about definitions of “tutorial”), but to at least talk about whether the game has anything that facilitates comprehension for novices. I don’t even think every game needs this–some games want to be Starseed Pilgrim–but it’s worth remarking on, and since reviewers tend to be experienced IFers it’s something we might not pick up on.

“Does your game provide clear, immediate guidance for new players, without requiring them to go look for it? Is the guidance sufficient to let a parser novice play your game successfully?”

Since a plug-and-play tutorial exists for I7 - it seems reasonable to expect games to provide either that level of help, or to provide something that is superior but tailored to that specific game - if there is a movement to adopt new-player-friendliness as a general community standard.

In Hypothetical World, where everyone has easy access to a tutorial extension in their chosen development system, I can see three valid reasons not to provide new player help.

  1. There’s a tight time constraint (such as speedIF).
  2. The game doesn’t use standard parser mechanics (such as Pong or This Is A Real Thing That Happened.)
  3. For whatever reason, the author actively wants to discourage new parser players from trying their game. (I have no examples, though I’m sure they exist.) In that case, it would be reasonable to give a disclaimer at the front and some options for good alternate starter games.

Are there any other good arguments for leaving a tutorial off?

(I do know we are not in Hypothetical World. I somehow entirely missed the existence of Emily Short’s extension, and I can’t be the only one. But if we were there.)

  • Extension might interfere with game logic in ways too tedious to track down.
  • Extension might trip up the intended pacing of the opening scene. (This could presumably be adjusted by customizing the extension, but again, this might be too tedious.)
  • Author might disagree about the effectiveness or approach of the extension.

(Not intending to be a downer about this.)

All valid arguments - if I were exclusively suggesting use of the extension.

But see the same part of my post where I suggested that a good measure of tutorial existence would be

My point re: the tutorial extension is that it makes adding an interactive tutorial easy. Not that it should be exclusively used.

Largely agreeing with zarf, but I think the basis of comparison would have to be something like “Does the game provide at least the level of help you’d get if you just plugged the extension into this particular game, with maybe a little more tweaking?” For example, in Terminator the extension would be pretty much useless. (Though this probably falls under “non-standard parser,” and of course I had to roll my own tutorial because the mechanics of the game would’ve been incomprehensible to everyone without one.) Or if you have a one-room game where inventory isn’t important, like Tea and Toast or Engima, Tutorial Mode only gets you look, examine, and the metacommands. And a game like Moonbase Indigo where the fun is mostly in the nonstandard commands won’t work that well in tutorial mode, though maybe it supplies its own tutorial…

…it’s not that I’m arguing against the general idea, that people should use the extension or come up with their own tutorial. Just that even if the extension is well known, it won’t be the case that everyone will have it or a similar tutorial unless they Just. Don’t. Care. On the other hand, testing has become a generally accepted norm, and that requires a fair amount of effort, so we might think that most authors should be willing to put in at least the fraction of effort that goes into testing into making the tutorial work.

For a cautionary tale, I tried putting Tutorial Mode into the one project of mine in which it might be expected to work (Faithful Companion–this is 6G60 so I had to use the old version). The first thing that happened was that it told me to LOOK and then told me I was done. I don’t usually Bracket Every Notable Thing in room descriptions, and apparently this meant Tutorial Mode didn’t detect that there were examinable things around. I hastily threw in a bracket and got this (emphasis added):

The old version of Tutorial Mode picked out a random visible thing for further examining… and this time it happened to grab a dummy (and privately-named) thing I’d put in there in case the player sees something on the bench and types “x something.” The new version replaces this with LOOK AT ME (and mentions that you might want to look at other visible things), which is much nicer.

And then:

Anyway, it seems as though you may need to hammer out some quirks when dropping this into your game. Which is something worth doing!

Yyyeah. The thing with adopting any standard in the parser-IF world is that it has always been a community with at least as many malcontents, experimentalists and oddballs with weird unorthodox concerns as Exemplars of Accepted Good Practice, however that has been constituted at any given time. This is one of the big things I value about it, but it does make make intentional movement in any unified direction rather difficult.

But I think the “Hey, everybody, have your game tested!” movement did work very well, to the extent that mini-comps now build in a mandatory testing window.* Perhaps we can come at least a little closer to attaining consensus here–maybe building in a tutorial window, or maybe saying “Hey! Part of the purpose of the testing window is to get your tutorial going!” (This was in fact when I did my tutorial.)

Yes, I just switched sides in the argument.

*Maybe only the two ShuffleComps and ParserComp.

If offering help were adopted as an informal community expectation, I’d be inclined to be flexible about the form of help offered: whether the main source of help is a tutorial integrated into the game or whether it’s the IF postcard released along with the game, whether the in-game help is offered up-front or only in response to the HELP command. (I do think most games could reasonably be expected to have a response to the HELP command, and this is another area where a new extension could come in handy.)

In terms of encouraging more tutorials, I’d want to focus on making it appealing and easy for authors,* even authors who aren’t fans of Tutorial Mode for one reason or another. Take Caleb’s suggestion, for instance. It’d be neat to see a game that offered a mock transcript in the HELP section. Get some community involvement, have a Mock Transcript Comp to select a handful of winning mock transcripts to go into an extension. I’m just throwing out ideas, but my point is to give game authors helpful tools along with room to exercise their own judgment about what kind of help is appropriate for their game.

*As opposed to some of the more punitive approaches I associate with the “credited beta-testers” community standards. Not as opposed to other forms of positive encouragement.

Yeah. Other intentional changes include cover art, which was facilitated by tech (IFDB) and community events (the IF Art Cover Drive), and a lot of the principles of the mimesis and Player’s Bill of Rights manifestos (a lot of which seems dated now, largely because the good bits are now things we take for granted).

(So, perhaps a IF Tutorial Drive? How might that work?)

I can’t take credit for this one - as far as I know it was first employed in Apollo 18+20.

But for some games, it will genuinely not be easy. Is what I meant. Telling people “you should do a lot of work for this goal” is not the same as telling them “just drop in this extension and that’ll cover it.” And no extension will work for everybody, so…

(Mind you, we could wind up with a couple of different extensions.)

I like the idea of adopting this goal as a community thing. It has the very desirable attribute of achieving positive value without universal adoption; if even half the parser entries in next year’s Comp have tutorial elements that will be a huge accessibility win.

(Thus also a problem of the commons – maybe everybody waits for everyone else to carry the load. But we’re a small enough group to avoid that, hopefully.)

FWIW, the “no reviews unless there are credited beta-testers” policy of mine wasn’t meant to be punitive – on the contrary, it was meant to end a situation where I was writing numerous, almost identical bad reviews about games whose authors had different polish standards from mine to start with, or in other words to remove negative feedback that I had previously been supplying in this situation.

In any case, I’ve changed the policy, post-feedback on my parsercomp reviews, to “no reviews of hobbyist work unless I can basically recommend the game,” since the sentiment was that I was still being too harsh. I imagine this will probably still exclude untested stuff most of the time, as a side effect.

But in any case, this wasn’t some widely-agreed community policy; it was a thing that I personally did, so if you think it was mean, that’s on me.

(Summary of my post for the time poor: I am pro game-specific tutorials!)

A tutorial specific to your game is going to be the best thing for a player. The logic mechanism of Emily Short’s tutorial extension is very good and I expect would be applicable to the majority of games, but you need to add to it and hook it into all the specifics of your game if you use it. Unless your game is as generic as a generic tutorial - which wouldn’t be a good thing.

When it comes to adding a tutorial, I don’t really see any way around doing the extensive work of customising the tutorial to your game any more than I see a way around creating the specifics of your game in the first place, at least if you want the best possible result.

I’d encourage everyone to do it for their games once they think those games are of a certain standard and going out to a certain number of people, but for a community to lean towards the idea of, ‘Your game must have a tutorial’, I see that as a bigger ask in general than just having your game debugged. I mean, debugging makes your game work in the first place, for you and others. You can have a perfectly working game, but adding a tutorial mode to it can be a significant increase in work. The one I did for Leadlight Gamma recently certainly was. I used the rules arrangement from Emily’s Tutorial mode, but I checked for actions using grammar matches, not literal text matches. This added flexibility for synonyms and different ways of doing things (and if your tutorial is of any length, checking for everything literally is going to be exhausting and impractical. Too many things can be typed in too many different ways) but it also opened up a world of possible bugs and omissions. Which I then jumped up and down on until they went away.

The cards and books and such are better than nothing, but in-game tutorials specific to games are better than the cards and books and such.


Sorry, I wasn’t clear. I didn’t mean to imply that there was anything wrong with your policy. It makes sense to me.

But this

almost sounds to me as though it is suggesting that the community agree, for example, not to review games without tutorials, as a means of motivating game authors to include them. Unlike your policy, this sounds more like a boycott. Perhaps I am misunderstanding the intent here.

Also, with “punitive” I was thinking of things like

giving low comp scores to games with no listed testers, without having played the game. But I really didn’t want to get into a discussion about whether or not this is a fair practice for tester-less games, which is why I didn’t mention it specifically.

In any case, I didn’t mean “punitive” to be a judgment of meanness, only a description of negative incentives as opposed to positive ones. Perhaps my word choice wasn’t the best.

But what I wanted to get across is this. In my opinion, even policies that make sense for tester-less games won’t necessarily make sense for a game that, for example, offers instructions behind a HELP command instead of offering instructions as soon as you start the game.

No, that’s exactly what I was suggesting. But I’m willing to look at it from the carrot side instead of the stick side.

What carrot could we give to authors/games with tutorials, that would be a convincing motivator for people who normally wouldn’t bother?

When you talk about the “best possible result,” there might be a “perfect is the enemy of the good” problem here. A lovingly crafted game-specific tutorial is definitely the best thing, but if a lightly tweaked Tutorial Mode extension is better than nothing, then I wouldn’t want to discourage people from including it if they don’t have the time or inclination or technical skill to add a completely hand-rolled tutorial.

Part of what you say about the generic tutorial only working for a generic game might be solvable by Bruno’s suggestion of demonstrating a non-generic verb. This could be simple as “open door.” It might be hard to automate but perhaps we could work up an example for the extension that shows how it’s done? It seems as though adding a couple of things to the tutorial extension shouldn’t be too much work in most cases. (The new Tutorial Mode extension does use action matches rather than literal text matches.)

You’d definitely need to test that the Tutorial Mode worked, and sometimes it might require some time to fix. (I just tested it out in someone else’s game and it didn’t work great, partly because of a bug that preempted the teach looking rule, and also because the teach examining rule didn’t fire because notable things weren’t bracketed.) So it’ll be some work and some people might reasonably decide it wasn’t worth it. But to say “Make a specific in-game tutorial once the game is a certain standard and going out to a certain number of people,” well, that does kind of sound like “Most people shouldn’t try to make their game accessible.” Which seems unfortunate–you never know when someone will come across your game or event.

cvaneseltine–maybe the carrot could be that some reviewers make an effort to try a tutorial (second playthrough if necessary), praise authors for making the effort, like that? It seems like just talking about it might help.

Some sort of fun community event that gets people involved and invested in making tutorials, like the Cover Art Drive got people involved in making/using cover art? (Not that it would have to work exactly like the Cover Art Drive, just that it would hopefully have a similar effect.)

Edit: Even putting together some resources and how-tos might offer a certain amount of incentive. Figuring out ways to deal with potential obstacles, and talking or writing about that. E.g. If you’re concerned about a opening prompt with a tutorial affecting the pacing of your game, this extension will let you create a title screen so that you can offer instructions before getting into the game itself. And here are some games that use that extension, so you can see what it looks like. Sharing what we learn. And finding out what kind of tools people wish they had, or how they’d like to tweak existing tools, to make it easier to incorporate tutorial elements. If they want a more self-contained tutorial, for instance, that won’t interfere with the dramatic opening moments of their game, would it be possible to create one that takes place in a separate part of the map, unconnected with the main action? Just an example.

Brief thoughts:

Feedback. Knowing that you’ll get useful feedback is a big incentive to authors. A tutorial’s effectiveness can only really be measured by its usefulness for actual new players. Design an event which guarantees authors feedback of some kind from such players.

Build on existing works. Since tutorials are, as has been stated, a good deal of work to develop and customise, make the event be about improving an existing work rather than making a new game and a tutorial for it. (This does shut out new authors, of course. Maybe it could just be an option.)

See, for this to be easy to implement, you would need ways of easily examining a player’s actions, and in effect you would need “a description of a class of actions” as a data type in I7. Which itself would need to be flexible enough to express concepts such “any action not explicitly mentioned in the tutorial text” (Which is itself crucial - if the player doesn’t understand that they can try pretty much any verb, they don’t really understand how to play parser IF and the tutorial hasn’t worked, unless the game is restricted enough that it can enumerate all implemented verbs at the start). Ideally this would be a table and/or a set of rulebooks, pre-populated with content that is sensical for most games; so that games with different mechanics from the norm can blank out rows they won’t use and insert their own, up to and including fully replacing the table.

I think this approach could very well make it worthwhile to build this into I7 as a feature of the system. Even if one size doesn’t quite fit all, making it so that authors can easily fit the tutorial to the needs of their game might be a good idea. It could, also, make it possible to delineate the tutorial into tiers, in a similar way that a lot of games in established genres do:

Are you new to parser games? (Answer yes or no) > no
Is this your first time playing Miserablist Sunrise? > yes

[Turning on game-specific tutorial messages. You can change this later with TUTORIAL FULL or TUTORIAL OFF]

One side-effect of this would be that the tutorial mode could be active throughout the game, and authors could use this as a way to explicitly bypassing guess-the-verb problems or introducing mechanics later in the game:

A rule for teaching the player when the player is in the Oorblex Chamber:
  say out of story "You may want to FLUNGE THE FUNICULEX here."

One side-effect of the push towards tutorials, though: If we decide, “parser games need a tutorial to be really playable, so we’ll be disregarding or docking points from parser games without one,” this at least for me means that unless I intend to make a game specifically as a platform for testing a parser tutorial, or a game where the premise is so unusual I anticipate needing a tutorial anyway even for experienced players, I’d probably consider writing a parser game a poor return on time investment until such a time as when better, broadly accepted tools are available for building a tutorial.

I think we can keep expectations in line with the tools on hand.