Chapter 10: Understanding player input

Player input is mapped to actions using (grammar $ for $). For instance, the following definition causes TAKE A NAP to be recognized as an attempt to perform the [sleep] action:

There is no automatic rule for recognizing the words that make up the internal name of the action, so the following definition is probably also desired:

But in this case, there is also a shorthand form:

Slash-expressions are useful:

The left-hand side of a grammar definition may contain special tokens, standing in for objects. Thus, [object] represents an arbitrary object in scope, or even many objects (separated by commas or AND). On the right-hand side, a wildcard ($) indicates the place in the action where the object is supposed to go:

Alternatively, [single] represents a single object in scope. Attempts to specify multiple objects are then rejected with:

A grammar definition can contain multiple tokens, which are then mapped to the wildcards in left-to-right order. It is recommended to restrict all except one of them to a single object, to prevent combinatorial explosion. Thus:

or:

Sometimes you want the tokens mapped to wildcards in right-to-left order. Use (grammar $ for $ reversed) for that:

The basic set of grammar tokens are:

In addition to the above, you can guide the parser towards certain classes of objects, to help resolve ambiguities as well as decide what the word ALL refers to. The following constraints are not enforced strictly—you must use (prevent $) rules for that.

Finally, a list of words that isn’t recognized as a special token will match any of the words in the list. This results in slightly faster and more compact code than a slash expression, but either syntax is fine, really. The following two definitions are functionally equivalent:

Grammar rules must start with a regular word, typically a verb. Tokens and other lists are allowed everywhere else, just not at the very beginning.

Here the story author has introduced a new action, [yodel], triggered when the player types YODEL. But so far, there is no code to handle the action. The fallback implementations of the six action-handling predicates will cause the action to succeed without printing anything at all. This is a no-no in parser games, so the story author should at least add a perform-rule:

When the player’s input can be understood in multiple ways, it is up to the game to weigh the different interpretations against each other, and select the one most probably intended by the player. This is achieved by looking at the actions from a semantic point of view, and discarding the unlikely ones, as determined by the predicate (unlikely $):

If that’s not enough, and several equally likely (or unlikely) interpretations remain, the library will ask the player a disambiguating question.

Thus, if the player is located in a room with a wooden door (open), and holds a wooden box (closed), and attempts to OPEN WOODEN, that will be understood as a request to [open #woodenbox]. The alternative, [open #woodendoor], gets discarded due to the second rule above. But if both the door and the box are open, both actions are deemed equally unlikely, and the game resorts to asking the player what they meant.

Story authors may override (unlikely $) to influence this proceduce. For instance, if a room contains a red lever and a red indicator light, it’s up to the author to specify:

which makes PULL RED do the expected thing.

Sometimes it is necessary to override (unlikely $) with a negated rule, when a more general rule would identify it as unlikely by default. For instance, suppose a location contains a wall-mounted ladder, and the story author wants the game to understand CLIMB LADDER as going up. The functionality itself is implemented by redirecting [climb #ladder] to [go #up]:

But [climb #ladder] is still considered unlikely by the parser, because (we assume) the ladder is not an actor supporter, i.e. it is not possible to be located #on the ladder. Now, if the player were to attempt to CLIMB LADDER while also holding the ladder instruction manual, the game would ask which one of the objects to climb. To prevent that slightly surreal question, a negated rule can be defined:

When a Dialog program is compiled to run on the Å-machine, the text may contain clickable links that resolve into text input. Selecting a link has the same effect as typing the words of the link target and pressing return. This can simplify text entry on mobile devices.

Links are created using the special (link $) …​ syntax:

Often, as above, we want both the link target and the clickable text to be the same. In this case a short form is available:

If we want both the link target and the clickable text to be the printed name of an object, we can use the tersely named predicate ($) from the standard library:

The same predicate can be used for exits:

To use the printed name of an object as a link target, but supply a different text, use the predicate ($ $). The first parameter is an object, and the second is a closure:

Be aware, however, that hyperlinks are an optional feature of the Å-machine, and not every interpreter will support them. While it can be tempting to create a jarring effect by having links resolve into unexpected input text, some players will simply not see it.

By default, library-generated messages never contain hyperlinks. The behaviour of the library should be consistent with the rest of the story, and whether or not to sprinkle room descriptions with clickable links is a decision best left to the author.

To enable clickable links in disambiguation messages, the game over menu, default appearances, and queries to (a $) and (A $), add the following rule definition to the source code:

Since link targets are appended to the current line of input, readers who are playing on a touchscreen device can type a verb using the on-screen keyboard, and then complete the sentence by tapping on a recently printed object name. Compass directions can of course be used directly as commands.

However, when we turn our nouns into hyperlinks, players will (understandably) attempt to click on them without first typing a verb. To handle this situation, the standard library provides an optional feature called default actions. It is enabled like this:

When this feature is enabled, the parser will understand noun-only input as a request for the default action, which is examine. The default action can be changed, and may depend on the object, as in the following example:

Story-specific actions are typically defined towards the end of the source code file. This allows object-specific rules, defined earlier in the file, to override them.

The following example relies on a special property of the [held] token: When the first token of a grammar rule is [held] and the player uses ALL in that position, then whatever matches the second token is excluded from the set of objects. Thus, if the player types PEEL ALL WITH PEELER, the ALL will expand to every held object except the peeler. Note that this may still not be what the player intended (because in addition to fruit, they might be holding a brass key and a lamp), but at this stage we are primarily interested in grammar, not semantics.

Remember, put the longest grammar definition first:

Either variant is deemed unlikely for non-edible objects:

The likelihood of an action helps resolve ambiguities, but it won’t prevent the action from being attempted: If the player unambiguously tries to peel the kitchen floor, that request is going to go through, unlikely or not. Thus we also need:

Likewise, because we specified [held], the library will try to satisfy the parser rules using objects that are held by the player, so that e.g. PEEL FRUIT will prioritize held fruit over non-held fruit. But an unambiguous PEEL BANANA will be understood even when the banana isn’t held.

Thus, we need a rule to prevent the peeling of a non-held object. The standard library provides a number of handy when-predicates that check for common conditions, and print appropriate responses when the conditions are met.

But, out of the kindness of our hearts, we might decide to pick up the mentioned objects automatically before attempting the peel action:

Finally, there needs to be a default response for the [peel $ with $] action (we already have one for the [peel $] action):

Of course, the story should also contain a couple of objects that would make the peel action succeed. The following object-specific rules must be defined before the generic rules described above, otherwise they will never match:

Finally, we could smoothen gameplay by implicitly assuming that if the player is holding the peeler, that’s probably their tool of choice for peeling:

This section provides an outline of how the parser works, and describes advanced techniques for understanding arbitrary turns of phrase that cannot be represented by ordinary grammar definitions. Most story authors do not need to dig this deeply, and can safely skip ahead to the next chapter.

The parser makes queries to (understand $ as $), a predicate that is normally defined by the library, but which can also be extended by the story author. One of the library-defined rules for this predicate is responsible for querying the table of grammar definitions. But there are also rules for special cases like GO TO ROOM, or ACTOR, COMMAND. We will discuss how to add such special cases.

During parsing, the standard library works with an intermediate representation of actions, called complex actions. Like regular actions, complex actions are lists of dictionary words and objects, but the following subexpressions are also allowed in them:

Thus, a complex action might be:

and its printed representation makes an appearance in the following message:

This section explains how to add new grammar tokens, like [worn] or [single held]. It’s an advanced topic, and most story authors can safely skip ahead to the next chapter.

Let’s create a [spell] token, to be used like this:

Recall (from How the parser works) that the library defines a generic (understand $ as $) rule that queries a table of grammar definitions. This table is called (grammar entry $ $ $), and it is constructed at compile-time from instantiations of the (grammar $ for $) access predicate.

A definition like the following:

is transformed into the following table entry:

The first parameter of the grammar entry is the first word of the grammar rule. This helps the compiler create efficient lookup code. The second parameter corresponds to the rest of the grammar rule, with numeric values instead of symbolic tokens (e.g. 22 instead of [held]). The third parameter is the action template, exactly as supplied in the grammar definition.

There are two reasons for translating the grammar tokens into numbers: It makes the code more compact (and therefore faster on old systems), and it prevents the grammar tokens from cluttering the game dictionary.

Grammar tokens are converted to numbers using a set of access predicate definitions in the standard library. For instance, here is the rule for converting [direction] to 50:

It operates by removing one element from the incoming list (first parameter), tacking on a new element to the outgoing list (second parameter), and leaving three more parameters intact.

Numbers in the range 90-99 are reserved for story authors. To create our new [spell] token, we add a similar rule to map the token to an unused number in this range:

Next, we supply a rule for what to do when the number 90 is encountered in the grammar table:

In the above example, we delegate to a separate custom predicate for handling spells. Under other circumstances, we might have queried an existing predicate such as *(understand $Words as object $Obj preferably { …​ }).

The third parameter of (match grammar token $ against $ $ into $) is rarely used. It contains matches from later grammar tokens (they are parsed from right to left). These can be objects, plus-prefixed lists like [+ #foo #bar #baz], or anything else; it depends on the type of the next token. This feature allows you to craft rules for e.g. PUT ALL IN BAG, where the bag should not be included in “all”.

TODO: