Tutorial Mode by Emily Short

This topic is for discussions related to Tutorial Mode by Emily Short

We have been discussing this underrated extension! I have a bug report and a suggestion.

Bug report: In the teach compass directions rule

An instructional rule (this is the teach compass directions rule): if the teach compass directions rule is listed in the completed instruction list: make no decision; if the held rule is the teach compass directions rule: let delay be the time of day minus movement reminder; if delay is less than five minutes: rule succeeds; let way be nothing; if a room (called goal) is adjacent: let way be the best route from the location to the goal; otherwise if the player can see an open door (called portal): let far side be the other side of the portal; let way be the best route from the location to the far side; otherwise: make no decision; if way is nothing: make no decision; let N be "[way]"; say "[one of]Feel free to look around some more. When you're ready to move on from here, try[or]No rush, but just a reminder that when you want to move to a new location, you can go[stopping] [N in upper case]." (A); now the expected action is the action of going way; now the held rule is the teach compass directions rule; now movement reminder is the time of day; rule succeeds.

I believe the open door clause will never work, because the best route check doesn’t include “using doors.”

Suggestion: There could be a “teach opening doors” rule as well–if the player is in a room whose only exit is an unlocked door, Tutorial Mode will not tell them to leave until they open the door. Many games have no doors–but in those games this rule simply won’t fire, so it’ll be OK.

The PL version of this has the line

Understand “restore” or “quit” or “save” or “restart” or “version” as “[meta]”.

But this is never used for anything. Holdover from a previous version?

Yep–the old version used an “After reading a command” line to check whether the typed command matches the expected string, and uses “[meta]” to let the metacommands pass through. The new version doesn’t block unexpected actions so that’s not necessary.

Another bug: The initial look action that happens after printing the banner seems to move the “Teach looking” rule to the completed list before it gets to run.

For context: Tutorial Mode’s latest version is pretty similar to what was used by Counterfeit Monkey. (I think this also explains how the LOOK bug was missed – because CM tweaks how look is presented anyway.)

Though I originally wrote it in response to author requests for easy-to-add tutorial features in a previous conversation, I don’t know of any other authors who have included it in anything. Now that there’s increased interest, I’ll have a look at fixing this stuff. It may have to wait a few days – I’ve been traveling more than I’ve been home the last week, and I have a talk to give tomorrow as well, so there’s an assortment of urgent home and work stuff piled up on my to-do list. But I’ll try to get to it; or, conversely, if someone has a bug-fixed version they’d like to submit, I would be fine with that.

After some conversation with Emily, I’ve undertaken to come up with a bug-fixed and extra-featured version sometime in the next month or so. If you have any suggestions, let me know! Also if you really want the bug-fixed version without extra features, let me know and I’ll try to get that to you sooner.

One suggestion: In Hadean Lands, tutorial mode doesn’t auto-describe the first room, and instead, the first command is “look” which actually describes things. That’d be a good option/default.

I’m a little inclined to make it an option rather than a default, because there are a lot of games that use the first “look” as the second half of the introduction.

In fact, I think it’d make more sense to have the default be that the teach looking rule happen a few turns in (if the initial looking action is on) rather than right away–usually the purpose of LOOK is “I’ve been doing stuff for a few turns and what’s the room description again?” so it makes sense to teach it when a little time has elapsed after the room description has been printed. What do you (or anyone else) think?

Maybe a built-in option to ask if the player wants help / has played IF before before turning tutorial mode on?

It’s hard to know when the player needs to re-describe a room. By introducing “look” right away, you don’t have to solve that problem at all; the player is in complete control.

More broadly, my claim is that “examine” can teach you all the commands you need via object descriptions, except for one-word commands, especially “look,” “inventory,” “help,” “save/restore/undo”, and perhaps “wait.”

That means the tutorial has a special responsibility to teach one-word commands, especially “look,” because then the room description can teach “examine.”

The next hard one-word command is “inventory.” The easy path is where the player examines something portable, where the description suggests that you “take” it. Then “take” can teach “inventory.”

But some games have important inventory before you take anything; in those games, “inventory” needs to be brought up randomly, probably a few turns in. (Maybe suggest “examine myself” so it’s not such an unfamiliar command.)

The tutorial should certainly suggest “inventory” when players take something or examine themselves, and should probably just blurt out “inventory” or “examine me” after a number of turns.

So! “Look” and “help” first. “Look” teaches “examine.” “Examine” teaches all other commands, including “go” and “take,” and hopefully eventually “inventory.”

“Help” should remind the player of “look,” “examine,” and “inventory,” and introduce the other one-word commands: “save/restore/undo” and “wait.”

That’s a different approach than the one I envision for Tutorial Mode, though. I’d like Tutorial Mode to be something that has a semi-decent chance of working OK with a relatively small amount of tweaking when the author puts it into a game that they’ve already written without especially intending to gear it toward newbie-friendliness. If I put special emphasis on “LOOK” in Tutorial Mode and directed the author “You should make the description of takeable objects indicate that you can TAKE them,” that would be the opposite of that–it’d require a whole lot of tweaking of descriptions.

(I would say that navigation commands are much more important to teach than any of the ones you mention, by the way.)

The problem with this idea is that if the first thing we do is teach you how to look, it makes it seem like looking is super important, and it isn’t. It’s kind of a relic of the days of BRIEF mode, when moving to a previously visited room didn’t print a description, and you had to LOOK to remind yourself of the description. Reminding yourself of the description can still be important–especially in Gargoyle with that awful scrollback–but it’s hardly a core mechanism of most games. Examining everything is, and that seems like a good thing to teach first.

Also there’s the “making the author tweak the room description” angle. Also also putting tutorial commands in the room description seems like a bad idea for much the same reason as putting narration in the room description–the player will be stuck with it every time they LOOK or reenter the room. And if you’re going to write something so it only prints the hint about examining the first time, or until you’ve examined successfully, you may as well just have a special tutorial rule to tell you about LOOK.

Emily’s already taken care of this! The extension as it is already suggests “inventory” if you’re holding something, even if it’s in your initial inventory. And it suggests “Look at me” immediately after you first examine something else. I think it makes the most sense to cue just plain “look” immediately after cuing “look at,” though I definitely intend to include the Hadean Lands version (no initial description, “Look” prompted first) either as a use option or as something that I give code for in the documentation.

I’m not sure whether you’re saying that this is what the extension should do or this is what the game should do–does the description of the object teach all other commands, or are you saying that examining should unlock the tutorial bit for other commands?

If you’re saying that the author should’ve written a response to “look” that prompts examining (in the room description or an after looking rule), and also that prompts you to GO WEST if applicable, and that item descriptions should explicitly suggest the other verbs, etc.–well, if the author has already structured their game that way, then there are about two things for the tutorial to do, and they can probably code them themselves just as easily as including the extension.

I’m not really trying to make something for authors who’ve already structured their game around a tutorial or other help–the stuff they’ve done already will be more useful than any extension. This is more intended as something that can help authors who haven’t already designed a tutorial or anything similar.

I’m also a bit leery of putting rules for HELP in the tutorial extension–well, actually, I can’t, because any actual rules I write need to be keyed to actions that are already defined, and HELP isn’t a standard action. (Defining it in the extension would be a very bad idea; authors will have their own ideas about how HELP should work.) It’d be worth including as an example in the documentation, though.

Also you’re definitely right that the line for teaching metacommands should include “undo.” “Wait” is a tricky one–it’s often completely useless, but if it’s useful it doesn’t have an obvious hook, so I think the thing to do is include it as a suggestion (or maybe as a rule that doesn’t get activated unless a flag is triggered? Actually that seems like a good idea).

And I guess the parser error message, or some parser error messages, can teach “oops.”

A little of both. Let me explain.

I claim that the tutorial should at least cover these cases:

  • When you examine a portable object, suggest: [You could try taking it by typing, “TAKE KEY”.]
  • When you examine a closed door or container, suggest: [You could try opening it by typing, “OPEN DOOR”.]
  • When you examine an exit, suggest: [It’s to the west, so you could try going that way by typing, “GO WEST”.]

Authors should be able to add their own. Ideally I could write a description of an apple and be able to write something like, “If tutorial mode is on, suggest eating it.”

Maybe the author wouldn’t do that for every edible object, (maybe it’s a puzzle that you can eat the flower,) but the documentation should recommend that all/most of the relevant verbs of the game need to be either explicitly suggested by the tutorial or hinted at in the text.

Oh, they’re critical! But we can ask/expect the player to learn about them by examining an exit.

OK, this makes sense–with the caveat that usually exits aren’t things (unless they’re doors) so there isn’t a hook for examining an exit. It might be a good idea to include a prompt for examining a direction, though.

I’m also a little unsure about the proper order here. Do we want to teach “look at this–now you can take this–now you can do inventory–now you can drop it, if you like–oh by the way you can also look at yourself and other things” or “look at this–now look at that, because you can look at lots of things–now that first thing you looked at is something you can take”? I lean toward the latter, though both should be made easy.

Authors should be able to add their own. Ideally I could write a description of an apple and be able to write something like, "If tutorial mode is on, suggest eating it."

This is a great idea. There’s definitely going to be a hook to test “if tutorial mode is on”; maybe I could make it easier to suggest eating by writing a phrase to run one of the teaching rules.

…after a quick attempt, this will be a little tricky–I probably have to set up some variables that allow the author to force a favored thing (as it is, there’s no way to tell it that we want it to specifically suggest taking the rock). I’d also need to include a hook for telling it “Skip the checks and make this suggestion anyway.”

Maybe the author wouldn't do that for every edible object, (maybe it's a puzzle that you can eat the flower,) but the documentation should recommend that all/most of the relevant verbs of the game need to be either explicitly suggested by the tutorial or hinted at in the text.

Hmm, I think this is an aesthetic choice. Authors might want to try to set up an understanding that you should be able to type an obvious verb for something–set up an expectation that if you see a button you can push it, if you see a pie you can eat it, if you see a roulette wheel you can spin it. The first problem is teaching the verb-noun syntax.

Well, there’s the issue here that there usually isn’t an in-game exit object to examine. One thing that seems like it might be useful is to include an option (on or off by default?) to have mentioned adjacent rooms be examinable and suggest going, unless they’re excluded.

All of this has to run as a global, every turn rule, because it should be able to prioritise and not overwhelm the player. This is undesirable:

> examine pierogi
The pierogi looks much like other pierogis you have known.

[You could pick it up by writing TAKE PIEROGI]
[You could eat it by writing EAT PIEROGI]
[You can see what you're carrying by writing INVENTORY]

It should also be able to delay hints to be deployed later, after more urgent hints, and just generally pace the tutorial. It’s probably also desirable to introspect the player’s commands to make inferences about how the player is going; if the player is clearly exploring the game by themself, producing well-formed commands, it might be desirable for the tutorial to shut up for a while.

I agree–as it stands the Tutorial rules run as a separate rulebook rather than an every turn rule and you put “rule succeeds” when one prints its tutorial, so only one of those runs a turn.

(Maybe it’d make sense to give them default option success, so that when one doesn’t apply you write “make no decision” but otherwise you just let it go? Or maybe the author should specify “rule succeeds” themselves? Not sure. Changing this would break backwards compatibility, but I’m not too worried about backwards compatibility unless someone requests it, since it’s not clear that anyone’s using the old version.)

It also orders hints. One thing that I want to do is give more hooks for having tutorial rules run and not run, which would help with pacing. A sort of “teach compass directions once the player has pushed the button” thing. Introspecting commands might be desirable but difficult, and also tricky to customize. I don’t want to overwhelm the author–it’s important that this be something that can fit into games with a relatively small amount of customization that can be adapted from examples, or it’ll just wind up being as much work as rolling your own tutorial. Also I think

Handling parser errors will be very important, though. The player who is typing “what do I do now” is the one we really need to reach. (I was going to say something about "You’re my only friend in this awful town but she was doing fine with the syntax, the problem was more having a big map to wander with one puzzle to advance and getting brickwalled on the puzzle. One for the “Don’t start people on Anchorhead” files.)

I have a nit-pick with Tutorial Mode and the take-worthy adjective.

The rule, in version 5, ends up suggesting (during play) that the player attempt to pick up a worn item. It’s not the end of the world, but is probably not what was originally intended. As per documentation 3.20, carried and worn are not the same.

Unfortunately, the composition of the take-worthy definition makes it hard to add an additional clause to it.

So adding,

if it is worn by someone:
	no;

would be great, at would reformulating the rule to be more extensible.

My temporary workaround is to ensure that inventory is taught first, so at least the player will have seen the item suggested to be taken.

Thanks for the suggestion. I am way behind on getting started on updating this–I need to learn to Github so I can have it up in a reasonable way–but I will definitely add that clause as part of the first update.

(Plan: The first update will just fix a few easily-fixed bugs–the opening doors one and the initial look bug that I’ve mentioned. That should be doable very soon after I get this rolling. Then I’ll work on doing some reordering of hints, like pushing the suggest looking rule later on, and then maybe try to work up some more examples. Then probably some stuff that involves refactoring the rules so the author can force prompting specific actions with specific things.)

Nit-picking, which actualyl came up when I was trying to use the extension.

I have more than one PC in my WIP, so right at the start of the game I removed “yourself” from play and set the player to be, let’s say, John.

When I fired up Tutorial mode, it would stick on “There are other things around here that you can look at too, if you like. You can check out other things in your surroundings, or LOOK AT ME to see yourself.”. And it would not let go even after X ME many times.

Diving into the extension I quickly realised what happened - you use “yourself” a couple of times. Maybe you’d want to use “player” instead?