Verify, Check, and When to Use Which

by Steve Breslin
compiled from discussions on rec.arts.int-fiction

The TADS 3 command execution model gets the command's objects involved in the execution process, via the dobjFor(verb) and iobjFor(verb) groups of methods. Part of this process is to decide whether or not to allow the command to proceed in the first place. The execution model offers not just one but two distinct places for each object to make those go/no-go decisions. One is the "verify" routine, and one is the "check" routine.

Broadly speaking, both verify() and check() have the the same mandate, namely to determine whether or not allow the command to proceed. But they're not interchangeable; there are definite differences in their effects. The distinction between the two is a bit subtle, and at times it can be confusing. This article aims to clarify exactly what each one is for, and to help you develop a sense of when to use which one.

Strictly speaking

The verify() stage of action processing is designed to interrupt the action processing only when there's a "logical" problem with the command. Pouring a desk or eating a topic - such actions would be illogical.

In contrast, the check() stage is for commands that seem logical enough, but nonetheless won't work. In these cases, the action still needs to be quashed, but not until after the parser has decided which objects could logically be involved. For example, the player tries to wear some jeans, but the jeans are too small. Maybe the player tries to melt something with the match, but the match isn't producing enough heat. In such cases, check() can interrupt the action, and explain the failure.

So why the two phases?

The benefit of having a check() stage separate from the verify() step is not in making the verification stage purely logic-oriented, nor in removing some of the conditional statements from the action stage. Such cosmetic adjustments would hardly justify the added complication of the check() stage.

The point of separating verify() and check() is that it lets the parser ask the game if a command makes logical sense, separately from determining if the command can actually be executed. It might seem difficult to separate these two ideas, but the distinction isn't just philosophical or cosmetic - there's a practical need for it. The practical need is "disambiguation."

When the player types a command, the parser tries to figure out what the command means by looking up the associations between words and objects. Sometimes, a word or phrase might refer to multiple objects. When this happens, the command is ambiguous.

For example, suppose a room contains two cardboard boxes, one white and one black, and the player types OPEN BOX. Does the player want to open the white box or the black box? One way of answering the question is to ask the player to be more specific: "Which box did you mean?" But the player will be annoyed if we ask this sort of question too often, especially if a human listener wouldn't need to ask. For example, if the white box is already open but the black box is closed, a human listener would assume the player means OPEN BLACK BOX, since that's the only way the command is useful.

The parser uses verify() to get this sort of information about what ought to be obvious to the player. When there's enough information to make the same kind of decision a human listener would, the parser can successfully resolve the ambiguity without asking the player for help - that is, the parser can disambiguate the command by itself.

check(), in contrast, is for enforcing conditions that aren't obvious to the player, and thus can not be used to resolve ambiguous references. For example, suppose we have our two boxes again, but this time they're both closed. Furthermore, suppose that the white box is an ordinary box, but the black box has been glued shut, so that it can't be opened without some kind of tool.

Now, if the player types OPEN BOX, what does the player mean? The game knows that OPEN BLACK BOX won't work - but the player doesn't know this until she tries it. So from the player's perspective, OPEN BLACK BOX is a perfectly logical command: the box is closed, and to all appearances it's something that can normally be opened, so OPEN BLACK BOX makes perfect sense. OPEN WHITE BOX likewise makes perfect sense. So it's equally logical for the player to mean either one: the parser has to ask the player which box she meant in this case. The parser can't assume that the player meant OPEN WHITE BOX just because the game knows that OPEN BLACK BOX won't work. If the parser did this, it could take the player by surprise - the player might really have meant OPEN WHITE BOX, and would be surprised if the parser interpreted the command to mean something else.

The point of separating verify() and check(), then, is to let the parser ask whether an action is logical, and then separately determine whether the action is actually possible.

Now, this discussion raises another question. We can see why we need to separate verify() and check(), but why do we need to separate check() and action()? In other words, why not just check the "possibleness" conditions - the box being glued shut, for example - during the action() phase?

The main reason to separate check() from action() comes into play with two-object commands, such as PUT X IN Y. In these cases, we might have action() handlers for both the direct and indirect objects. The order of execution for the action handlers depends on the verb - for PUT X IN Y, we run the indirect object handler first, but for some verbs it's the other way around. Now, if we did all of our checking in one or the other action handler, we might run into a slight problem: what if the action handler that runs second needs to block the command?

The separate check() phase solves this problem. We run the check() handlers for both objects before we run either action() handler. This ensures that either object can cancel the command before any part of the command has been carried out.

This means that it's important to remember that check(), like verify(), shouldn't actually carry out any part of the command. In particular, these routines shouldn't make any changes to "game state" - they shouldn't move any objects around, change properties, etc. All game state changes should be put off until the action() phase, when we know that we've passed all of our tests and that the action is allowed to proceed.

Thinking about this from disambiguation: an extended example

Without recourse to a potentially confusing philosophical distinction between logical and illogical, we can understand the use of the check() stage as one which enables us to make extra adjustments to interactive disambiguation questions. (Interactive disambiguation questions are the questions which the game generates when the player makes an ambiguous command: "Which fan do you mean? The....")

An object which fails in the check() phase is favored over an object which fails in the verify() phase, as far as disambiguation is concerned. In fact, during disambiguation, the parser doesn't even call the check() method. The parser calls the verify() method to narrow down the field, and then might have to ask the player to choose from the remaining objects, but the parser doesn't call check() at all until after the objects have been chosen.

For example, we have three fans, one which is a fixed ceiling fan, which can be turned on and off, one which is a takeable oscillating fan, but which can only be taken when it is off, and one which is a hand-fan, a stylized pingpong paddle if you will. First we'll discuss verify() by itself, and then we'll discuss verify() in combination with check().

Good use of verify()

Say the player types:

>turn fan on

We definitely want to exclude the hand-fan, since it's obvious that the hand-fan can't be turned on or off, so this exclusion goes in the verify. So we might get the following disambiguation question:

>turn fan on
Which fan do you mean, the oscillating fan, or the ceiling fan?

Now let's say that one of these fans is already on -- we would want to eliminate this option also, or else we're effectively asking: "Which fan do you mean, the fan that's already on, or the fan that is off?" The verify() stage is designed to eliminate the obviously silly interpretation of the command when there are other good options.

So if the ceiling fan is on, and the oscillating fan is off, we want something like this:

>turn fan on
(the oscillating fan)
Done.

Now let's think about the case in which all three fans fail the verify() stage: the hand-fan obviously cannot be turned on, the other two are already on, so they can't be turned on either. If the player types:

>turn fan on

-- we need to ask which fan is intended, so that we can print the appropriate failure message. So when all three fail the verify() stage, a disambiguation question like this is asked:

>turn fan on
Which fan do you mean, the hand-held fan, the oscillating fan,
or the ceiling fan?

All of these will fail, of course, but they'll fail for different reasons, so we need to ask which the player meant before we explain why what the player is trying to do isn't going to work.

Combining verify() and check()

So far we have an example of how verify() is used. Let's continue with this example to explore how check() is used in combination with verify() to make the intended disambiguation messages. We'll change the verb from "turn on" to "take".

The ceiling fan cannot be taken ever, since it's attached to the ceiling. The oscillating fan can be taken when it's off. The hand-held fan can be taken at any time. Let's say the oscillating fan is off:

>take fan

It's pretty clear what we want here:

>take fan
Which fan do you mean, the oscillating fan, or the hand-held fan?

Note that the ceiling fan isn't an option, since it can't be taken: it has failed the verify() stage. The two good options are offered in interactive disambiguation.

Now what if the oscillating fan is on:

>take fan

What do we want here? The answer to this question determines whether or not we want the oscillating fan's takeable-condition to be in check() or verify(). Is it obvious to the player that the oscillating fan cannot be taken when it is on? If not, we want this:

>take fan
Which fan do you mean, the oscillating fan, or the hand-held fan?

The above is produced when the fan.isOn condition goes in check(). If we instead put this condition in verify(), we will get this:

>take fan
(the hand-held fan)
Taken.

If we want to eliminate the oscillating fan during object resolution, then we put the condition in verify(), so that the game will know that it's supposed to assume the player is referring to the hand-held fan when the oscillating fan is on. We should only do this if it should be obvious to the player that the oscillating fan cannot be taken when it's on. (Making too many assumptions about what the player means can spoil puzzles sometimes, and is somewhat intrusive generally speaking. In this sense, "logical" means "what's logical or obvious to the player." The verify() stage being a logic test should be understood in this spirit.)

We can make one other consideration: let's say that the hand-held fan is directly contained by the player character. The oscillating fan is on, and standing on the desk, and the ceiling fan is circling overhead. How do we want to handle this:

>take fan

Deciding this will also help us determine whether or not we want the fan.isOn condition to be in check() or verify(). If it's not obvious that the oscillating fan cannot be taken, we want the following:

>take fan
(the oscillating fan)
You try to take it, but it's too awkward to grab while it's oscillating.
Maybe you should turn it off first.

But if we want the following:

>take fan
Which fan do you mean, the ceiling fan [which cannot be taken], the
hand-held fan [which you already have], or the oscillating fan [which
cannot be taken because it's on]?

-- then we should put the oscillating fan's isOn condition in verify(). Whether you want to assume that the player means the oscillating fan in this case is up to you; the "logic" will be different between games, based on the context, how obvious the situation is to the player, and based on the game author's sense of taste in deciding what player knowledge should or should not be assumed.

The point is that you should choose where the condition goes based on what you want to see in the disambiguation phase.

Of course, you don't need three fans to make up your mind about where the code should go, but you can imagine other objects in your game that could be competing with your object, to help you determine where the code should go from a stylistic point of view.

From a goal-oriented perspective, it all comes down to the practical implications of putting a condition in one place or another, and often there are no practical consequences, in fact, to the distinction between check() and verify(); but you can imagine disambiguation conflicts to insure you're using the right style in principle.

check() and beforeAction()

Traditionally, the library ran the "before" notifiers - beforeAction and roomBeforeAction - before the check() phase. Starting with version 3.0.15.1 of the library, however, you can optionally enable a new, alternative ordering that runs the check() phase first.

To enable the alternative ordering, set gameMain.beforeRunsBeforeCheck to nil. By default, this property is set to true, which tells the library to use the traditional ordering - "before" first - this ensures that existing code will work as it always has.

The reason you might want to use the alternative ordering is that it lets you consider a command to be more or less "committed" by the time the "before" handlers are reached. In other words, the "before" handlers can assume that the command will run to completion. The reason they can make this assumption is that they know that they're running after the check() phase. If the action makes it as far as the "before" handlers at all, the check() phase will have already judged the command to be acceptable as far as the check() tests are concerned.

So, when we get past the check() stage, we know that a viable action is under way. Any objects which want to interfere with that action can then do so with beforeAction(). This means that check() can interrupt an action before other objects, say NPC's, have a chance to react to it. So a good use of check() can avoid sequences like this:

>ask stu about chair
As you are about to speak, Mary kicks you under the table. Glaring at
her, you redirect your question to Dave.
The large chair isn't something you need to be asking about.

In the above example, Mary's response was a beforeAction(), and the line about the large chair being an unimportant topic was mistakenly placed in the action phase rather than the check() phase. By failing the command before the action phase, we could have avoided printing Mary's beforeAction() message. So if we want to tell the player that the chair is an unimportant topic before Mary becomes involved, we need to use the check() phase.

It is important to remember, therefore, that check() really is another verification phase, and not a preliminary action phase. Only if a command passes check() should a change in game state be made. In other words, some initial conditional statements should be part of the action stage. The check() stage should not perform preliminary checks which determine which action methods are called.