This is a somewhat opinionated piece that I originally put together to clarify my own thinking on a couple of things; the opinions expressed should probably be toned down. Nonetheless…
I’ve come to think that one of the jobs of a work of IF is to teach its player — constantly, in every kind of feedback — what sorts of interactions are appropriate to the game. The listed/unlisted command issue is only part of this larger problem, as you suggest (though I’m coming at it from a different angle). A few months ago I wrote up a sort of manifesto about how the parser, world model, and output should work together to achieve this; and here it is. Since it is theoretical, it sometimes describes behavior that no current IF system actually supports, but which I think would be nice to have.
World model
1. The purpose of the world model is to allow the player with a range of action greater than the author of the IF could have anticipated specifically. This distinguishes IF from a Choose Your Own Adventure.
2. There is no point to elements of the world model that do not contribute to the range of interaction important in the game. A game about treason and loyalty, where the interaction mostly involves personal relationships, probably does not need a detailed implementation of realistic water.
2A. The type of interaction should be as much as possible appropriate to the type of story. It is difficult to have a story about people where the interaction is principally about moving things from one place to another. Sometimes it can be done, but it’s challenging.
2B. The “world model” is a broad term as applied here. A world model may model things besides space and physical objects, such as character moods and topics of conversation; time; sequence of events (what has or has not happened so far); or anything else the author wants the player to be able to affect.
2C. It is understood that a world model based on a library will have some few base features that will likely not be excised even when they are not being used. For this reason a basic library should remain compact, and extra aspects of the world model be added by extension through the deliberate choice of the author. Having extraneous features in a model world that do not lead to any productive interaction for the player may be counterproductive, because it distracts from the interaction type intended in this particular game.
3. There is no point to a model that cannot usefully be described in text. A model that incorporates exact physical location to the inch is appropriate to a graphical representation, not to a text representation.
3A. Aspects of the world that cannot be *mechanically* translated from the model representation into text need not be modeled in any complexity. They will need handwritten text anyway.
3B. Effects of action can be quantitative (changing the value of something along a gradual scale) or qualitative (switching between several discrete states). Qualitative effects are as a rule easier to describe in text. Describing a quantitative effect often, though not always, involves throwing away some information when describing an outcome to a player. (After buying something, the player might know exactly how much money he has left: this is a quantitative effect described exactly. On the other hand, after hitting someone, the player might know only that he has caused his opponent to “look weaker”. The problem here is that divulging the opponent’s exact number of hit points goes counter to the realism of the description — since in real life people do not have hit points — but concealing this information leaves the player at a disadvantage in terms of game play. We are more or less arbitrarily concealing from him information that he might want to use to interact intelligently with our model world. It’s possible that the point of the game is to require the player to gamble and make educated guesses about outcomes, but this is challenging to make work well; the player will likely UNDO after a failure, but depriving players of the UNDO command may irritate them so much that they won’t play.)
3C. Modeled states of objects should always in some way affect the output at some point in the game (though it may be indirectly). If a state of an object in no way affects what the player sees at any time, that state information is irrelevant and might as well be excised from the world model.
4. There is no point to a model that cannot usefully be manipulated via text commands. Models involving speed of action, or type of motion, are usually more appropriate to arcade-style games. Models involving high degrees of abstraction are challenging as well.
4A. It is valid for the model to track effects that the player does not directly control (e.g., moods of characters, even though the player cannot directly act on those moods, only do things that cause changes to them). On the other hand, the less direct the player’s control over the important aspects of the model, the less his sense of agency and the greater the risk of confusion.
4B. If the player is indirectly causing a quantitative effect — e.g., slowly changing the attitude of another character along multiple axes — representation becomes particularly challenging and it is easy for the player to become confused about the effects of his action.
4C. It should in general be obvious to the player *that* he has manipulated the model when he succeeds in causing a change. If his actions have indirect effects, there should usually be some hint that an indirect effect has occurred: e.g., the changing expression on an NPC’s face, a sound from a distant room, etc.
Parser
1. The purpose of the parser is to allow the player to manipulate the model world. It is not the author’s job to provide the player with a parsing that will accept anything the player wants to type. It would not in fact be helpful to do so unless the author has also constructed a model world capable of sustaining any type of action the player chooses to describe in natural language. It *is* the author’s job to try to lead the player towards phrasings that are useful — that is, that indicate meaningful manipulation of the model world.
1A. Teaching the player what sorts of commands are appropriate is effectively one and the same with teaching the player what the world model can do.
1B. Where the standard command set, or the world model, diverge from IF convention, the author should be extra careful to provide hints and suggestions. New commands should be implemented with an extensive supply of synonyms and alternate phrasings. The thesaurus and good beta-testers may help.
1C. Unless the new commands represent actions which are to be hidden from the player until partway through the game, explicit instructions should be included in the game, and the player encouraged to read these instructions on starting play.
2. The structure of a command should require that the player provide all the information necessary to specify an action fully given the terms of the model world.
2A. The same action might be implemented with different degrees of complexity in different world models. One game might allow cutting with only one implement, while another might have different cutting implements offering different effects, for instance. The command set of a standard library will often need adjustment for a given implementation.
2B. It should never be the case that, e.g., CUT FOO is accepted by the parser (but fails to do anything interesting), while CUT FOO WITH BAR does something useful. If the player can be seen to be attempting a valid command, but is inadequately specific about it in the present context, he should receive guidance about the correct form.
2C. The basic implementation of a command should always be one that incorporates all the information needed. Thus if it matters what weapon the player is using to ATTACK someone, the basic form of the command should be ATTACK FOO WITH BAR. It is valid to attempt to understand ATTACK FOO rationally, but the command should always resolve back to the complex form.
3. The structure of a command should not require that the player provide any information that can reasonably be determined by default from the world model. If the player is only carrying one key, e.g., it should be understood that this is the key he wishes to try using.
3A. This does not invalidate the points in 2 above. The correct thing is to implement the most complex form of command, then provide intelligent defaulting.
3B. When a default is selected, the player should always be told what the default selection was. This will help train him in the correct command structure, and prevent confusion based on incorrect assumptions.
4. The parser should always prompt for information missing from a command, if the player offers incomplete information and a reasonable default cannot be deduced.
4A. If a small list of reasonable default possibilities can be assembled, and the knowledge of these items is not itself a puzzle, the list may be presented to the player as a selection of options. (FIX FOO WITH THE HAMMER OR THE WRENCH?) This is not something that most systems currently do, to the best of my knowledge. Maybe TADS 3 lets you set a disambiguation list, but I wouldn’t be too sure.
4B. If the list of reasonable default possibilities is large, it is reasonable merely to ask the player for more information.
4C. If the requested information is a value rather than a thing, the usable values should also be listed when disambiguation is requested. (“You may open your snuffbox insouciantly, or in a sneaky manner.”); or, if it is not reasonable to list the values (e.g., we are expecting the numeric code for a safe), one should at least indicate what sort of value is expected.
5. If the parser needs to distinguish between multiple items when the player has named one but named it ambiguously, the disambiguation (“Which do you mean, …”) should be designed to make the difference between the items on the list obvious.
5A. Ideally, it should indicate to the player which properties/aspects/adjectives/etc. would distinguish between the two (or more) objects proposed. Thus “Which tea do you mean, the tea in the pot or the tea in the cup?”; or “Which baseball do you mean, the dirty baseball or the clean baseball?” — even if the baseballs are not ordinarily listed in those terms.
Output
1. The purpose of what gets printed to the screen is to reveal to the player everything he needs to know to interact with the world in the way intended. The output should draw the player’s attention to the important parts of the world model.
1A. This does not mean that there can be no aesthetic purpose to what is printed. Nonetheless, the text will be ineffective as prose for interactive fiction if it does not fulfill this requirement.
2. Different aspects of the model world may be important at different times in the work.
3. At output time, therefore, information about the world model may be emphasized (presented on its own paragraph, made the first or last item in a list, bold-faced, etc.); of ordinary significance (listing as part of “you can see here”, properties of openness/containment/light/etc. which happen to be critical to the world model); or secret, ignored, or unlisted (scenery, concealed items; properties of secondary importance; or those properties which the player might reasonably deduce from the object’s name [e.g., it is likely unnecessary to indicate in inventory listings et al. that an object called “fork” has the property of being metal]).
3A. The information displayed should not overwhelm the player. If there is a great deal of information presented in emphatic form, the emphasis becomes useless.
3B. In general, hand-crafted prose suggests greater focus or emphasis than mechanically-generated prose.
4. It should be possible for the player to recover any world model information which he has been told once, even if it is not currently considered important enough to be listed under ordinary circumstances. Thus, if he has discovered some property of an item (e.g., that the teapot is enchanted), he should be able to tell this thereafter in some way (by examining it, inspecting it through the enchantment-detecting lens, etc.), even if we do not from then on call it “the enchanted teapot” on every occasion.
4A. Barring special tools/circumstances (e.g., the game features a microscope/geiger counter/etc.), examining an object should give the player all the useful information it is currently possible for him to detect. There should not be important world-model information about an object which gets mentioned in the general room description but not when one looks at the object directly. Or, to put the rule in a more general form: if the player attempts to recover information about an aspect of the world model using a command devised for that purpose, he should be given a complete view of everything he is currently allowed to know.
4B. IF modeling conversation, plot events, time, etc., should provide some command by which the player can review what has been said or what has occurred. Said summary need not be exhaustive but should convey everything critically affecting the current world state.
5. The status bar is useful for presenting information that is simple (e.g., the room we are in, but not the list of things we are carrying); important (likely to have an effect on most or all actions the player performs); rapidly-changing (unlikely to remain the same throughout the game, or even from turn to turn); and/or from an isolated part of the world model.
5A. By isolated, we mean things such as systems of conversation, time, emotion, etc., which are modeled but only weakly coupled with the rest of the world model. Because these systems may be important but have few, sporadic, or subtle effects on the way the model world works, the text output may otherwise not remind the player very often of the time/conversation state/etc. Having this information in the status bar tells him that it is nonetheless important information and allows him to review it.
Emily Short's Interactive Storytelling 