6. Commands

Recipe Book

RB §6.1 Designing New Commands

Quite a bit of interactive fiction design involves the creation of custom commands to expand on the library's existing set. There is more to know than we can review in this section; instead, this is to serve as an overview of the process, with hints about where in Writing with Inform we might find more technical details.

Before we even start to write our source text, we should think about the following things:

(1) What words will the player use to make this new action happen?
(2) What will the action change about the world model?
(3) What circumstances might make the new action go wrong or produce silly outcomes?

To take these one one by one:

(1) We may have a general idea of the phrasing we want the player to use – say we want to add an SHOOT command which allows the player to fire a gun at something. (This is an intentionally tricky choice of verb, because it shows off so many possibilities.) So we might decide the base form of the action will be

SHOOT THE PISTOL AT HENRY

So now we're going to need an action that applies to two objects – the pistol as the noun, and Henry as the second noun. The problem is, though, that there are lots of other ways that the player could reasonably formulate the command, some of which leave out information:

SHOOT HENRY
SHOOT PISTOL
FIRE PISTOL
SHOOT AT HENRY
SHOOT AT HENRY WITH GUN

To avoid frustrating the player, we should make a guess about what the player means whenever we're sure that guess will be reliable (we might, for instance, have only one gun in the story, so we know that SHOOT HENRY will always mean SHOOT HENRY WITH PISTOL), but ask the player for clarification whenever there might be ambiguity (SHOOT PISTOL gives no clue about the target, nor can we safely guess, so we want Inform to ask "What do you want to shoot the pistol at?"). The next section goes into more detail about how to handle these variations.

Conversely, there are cases where the player is offering too much information for the command we've defined – say we have a BURN command which doesn't look for a specified fire source, but the player is trying to BURN BOX WITH MATCH. We probably don't want to throw away the extraneous information as though it had never been typed, because the player might have typed something quite specific. BURN BOX WITH ACID, say, should not be cavalierly reinterpreted as BURN BOX (with a fire source). Instead, we want to give the player a bit of gentle guidance, perhaps using "Understand as a mistake", as in

Understand "burn [something] with [text]" as a mistake ("Your choice of lighter isn't important in this story: BURN SOMETHING will suffice.")

Finally, there are some cases where we want to understand a phrase to mean a specific form of a more general action. For instance, we might want TURN DOWN THE MUSIC to mean the same thing as SET VOLUME KNOB TO 1. In this case, we may want to make a sort of dummy action which converts into the main action, as in

Understand "turn down volume" or "turn down music" or "turn down the volume" or "turn down the music" as lowering the volume. Lowering the volume is an action applying to nothing.
Instead of lowering the volume, try setting the volume knob to 1.

More about this can be found later in this chapter, under Remembering, Converting and Combining Actions.

Sometimes these kinds of details can be caught in play-testing, but it's a good idea to think about them specifically and in advance rather than leaving them to our beta-testers to sort out.

(2) To generalize very broadly, there are two possible kinds of command in IF: those that only exist to give the player new information (like EXAMINE, INVENTORY, LOOK, TASTE), and those that change the world model (like TAKE FISH, OPEN DOOR, UNLOCK GATE WITH BLUE KEY). The Inform library has some commands that really do none of these things by default – commands like JUMP that do nothing interesting at all most of the time – but those exist as hooks, in case there is ever something important for them to do.

Commands that ask for information are usually easier to implement. Very often we're looking to offer the player a new kind of information about specific objects, and these can be handled by adding new text properties, as in

A thing has some text called the sacred emanation.
Carry out perceiving something:
   say "[sacred emanation of the noun][paragraph break]".

Commands that affect the world model, on the other hand, can range from simple to very complex indeed. Sometimes we need to do nothing more than add an attribute to an object, like

A thing can be folded or flat. A thing is usually flat.

so that our FOLD command can change the object into its folded form. At other times, we need quite intricate rules to account for a subtle multi-stage process – how fire is burning and spreading to objects, say, or how a conversation is progressing. Other parts of the Recipe Book offer solutions to some of these challenges.

(Strictly, we might count a third kind of command: the kind that controls the story itself. The Advanced Actions chapter discusses how to add actions out of world, as these are called, but the difficult ones are already built into Inform – saving, restoring, restarting, undoing a turn, and so on. Mostly when we need to add new actions out of world, they will be help or hint systems of some kind. More about these can be found in the Helping and Hinting section of the Recipe Book, under Out of World Actions and Effects.)

(3) Most commands that change the world require certain preconditions: the player needs to be holding the gun before he can fire it; the gun must be loaded with ammunition; if we're being especially detailed in our simulation, the safety must be off.

Often, there are also subtler details about how the command should interact with special items. For any new command we create, it's worth asking: should anything special happen if the player performs this action…

On himself?
On another living character?
On an object he (or another character) is carrying or wearing?
On an object he (or another character) is inside or on?
On a door?
On an object that is impossible to move (defined as "scenery" or "fixed in place")?
On an intangible object (such as a beam of sunlight)?
On an object far away (such as the sun)?
On an object that is part of something else (such as a doorknob)?
On an object that itself has parts (such as a desk with drawers)?
If there are two objects required by the action, can both the noun and the second noun be the same thing?

For instance, we might have written code so that if the gun is fired at anything but a person or a fragile object, the default response is "The bullet bounces harmlessly off [the second noun]." Our checklist would remind us to write special cases to prevent

SHOOT GUN AT MY SHOE (while he's wearing it)
SHOOT GUN AT ME
SHOOT GUN AT GUN

and so on. Actions that destroy objects are especially tricky, because there are many things that aren't safe to destroy without carefully adjusting the world model. (What happens if we burn a door connecting two rooms? a wooden desk with a drawer containing an asbestos vest? the armchair Cousin Fred is sitting on?)

RB §6.2 Writing New Commands

Once we've considered all the design issues pertaining to a new action, we're ready to start writing the source text. First we need to give the player a way to issue the command:

Understand "smile" as smiling.
Understand "fold [something]" as folding.
Understand "shoot [something preferably held] at [something]" as shooting it with.
Understand "wrap [something preferably held] in [something preferably held]" as wrapping it in.

(Note how "it" stands in for the first item when we have an action requiring two objects.) The things that go in square brackets are called "tokens": they are blank spaces for the player to fill in with story objects. The different kinds of tokens are explained in the chapter on Understanding.

We can add synonyms with

Understand the command "grin" as "smile".

and we can create reversed versions of commands with

Understand "shoot [something] with [something preferably held]" as shooting it with (with nouns reversed).

These variations are also covered in the Understanding chapter. If the action needs to work on things that aren't within the player's sight or reach in the normal way, we may need to use an [any thing] token (see the Understanding chapter), as in

Understand "contemplate [any thing]" as considering.

We may also need to modify reach or light levels (see Changing reachability and Changing visibility in the Advanced Actions chapter), or rely on the Deciding the scope of… activity.

As for guessing the player's intention when he isn't clear, we may want to consult the Does the player mean rules (to help Inform make guesses between multiple possible targets) and the activities Supplying a missing noun and Supplying a missing second noun (to help Inform guess an appropriate item when the player leaves something entirely out of his command). For instance, if the player typed SHOOT HENRY, it is the supplying a missing noun/second noun activity that would allow us to make Inform draw the obvious conclusion that he shoots Henry with the pistol in his hand. The Does the player mean rules are discussed in the chapter on Advanced Actions; the activities in the Activities chapter.

Next we need to define our new action, as in

Smiling is an action applying to nothing.
Folding is an action applying to one thing.
Wrapping it in is an action applying to two carried things.

In cases where we're using an "[any thing]" token to let the player affect objects that aren't normally visible or reachable, we'll need to define the action to apply to visible objects. This tells Inform that the player doesn't have to be able to touch the object for it to work. So for instance

Considering is an action applying to one visible thing.

For more on this topic, see Visible vs. touchable vs. carried in the Advanced Actions chapter.

The next step is to create rules for Inform to follow when the action happens. These can be check rules (which make sure that the conditions for the action to occur are fulfilled); carry out rules (which perform the action); and report rules (which describe the results of the action to the player). Any new action should have at least a report rule to let the player know what has happened (if anything), and a carry out rule if there are any ramifications for the world model. For instance:

Carry out folding:
   now the noun is swan-like.
Report folding:
   say "You deftly fold [the noun] into the shape of a swan."

It's important to remember that report rules may be describing something whose name is plural, such as papers or shoes, and write our text so that it sounds right either way; see the chapter on Adaptive Text and Responses.

More about defining actions and creating carry out and report rules may be found in the chapter on Advanced Actions.

Meanwhile, the check rules give us a chance to provide sensible restrictions on how the command works, as in

Check folding:
   if the noun is not a napkin:
      say "[The noun] won't bend." instead.
Check shooting something with the noun:
   say "[The noun] is incapable of aiming at itself." instead.
Check burning something which contains the player:
   say "You're not quite desperate enough to make a funeral pyre for yourself just yet." instead.

The chapter on Advanced Actions explains how check rules work. In the special case where we want the player to take things automatically before using them, we may want to define the action to work only on carried objects, as in

Wrapping it in is an action applying to two carried things.

The activity Implicitly taking something (documented in the Activities chapter) allows us to modify what should happen during this process.

Lastly, a word or two about trouble-shooting. If a newly created command seems not to be working, we can discover what action Inform is really generating with the ACTIONS testing command, as in

>actions
Actions listing on.
>i
[taking inventory]
You are carrying nothing.
[taking inventory - succeeded]

If the desired command is not happening, we may need to review our understand lines. A common problem is that our new action conflicts with one already defined by default. In that case, we may want to check the Actions index and see whether there are already-defined actions which might conflict with it. If so, we may need to redefine a command with a line like

Understand the command "stand" as something new.

If that's not enough, we can get a comprehensive view of everything that happens during an action with RULES: this will list all the check, carry out, and report rules that Inform is using to perform the command.

See Also

Memory and Knowledge for more about the any token and the concept of scope to control what the player may refer to in a command.

RB §6.3 Modifying Existing Commands

Much of the rest of this chapter discusses the behavior of specific commands in Inform's command library, and how we might change and build on these. This section is instead an overview of the general principles: where and how can one intervene?

Whenever we are dealing with actions, the Actions Index is likely to be useful: it lists all the actions currently implemented, whether in our own source or in extensions or the Standard Rules, and lists the rules pertaining to each.

The lightest and easiest way to change behavior is with an Instead rule:

Instead of eating the apple:
   say "It turns out to be made of beeswax, so that's a non-starter."
Instead of tasting an edible thing:
   say "It's delicious!"
   rule succeeds.

The addition of "rule succeeds" tells Inform that the instead action was a success rather than a failure; this is not usually very important with the player's own actions, but can be useful for actions performed by other characters, so that a successfully replaced action is not followed by the disconcerting line

Clark is unable to do that.

Before and After offer alternative easy forms of modification; the Basic Actions chapter explains all three.

Changing the way an action works in all cases is usually better addressed by changing the main rulebook, rather than with one (or many) instead rules. We may add new check, carry out, and report rules to existing action rulebooks. The Advanced Actions chapter describes these, and ends with some guidelines on when to use before, instead, and after, and when to use check, carry out, and report.

Similarly, we may delete, move, or replace rules that are already present (see the chapter on Rulebooks). This is handy if we decide that an action has restrictions that we dislike and want to abolish. If the restriction we need to change is part of the accessibility rules – those which check whether the player can take, see, and touch items – we may need to look at Changing reachability or Changing visibility in the Advanced Actions chapter (to revise what is allowed), at Deciding the scope of something in the Activities chapter (to influence what can be seen when).

If, for instance, the player character is a burly fellow who can lift any other character he likes:

The can't take other people rule is not listed in any rulebook.

…and rip knobs off doors:

The can't take component parts rule is not listed in the check taking rulebook.

…and commit petty theft:

The new can't take people's possessions rule is listed instead of the can't take people's possessions rule in the check taking rulebook.
This is the new can't take people's possessions rule:
   if someone (called the owner) carries the noun:
      say "(first waiting until [the owner] is distracted)";

The right approach to use also depends a bit on how systematic a change we anticipate. We may find that instead rules become cumbersome when we want to specify behavior for a very large number of objects. It's fine to have

Instead of tasting the arsenic:
   say "You'll live to regret this very very shortly.";
   end the story.

but a bit more tedious to have to write

Instead of tasting the peppermint: ...
Instead of tasting the plate: ...
Instead of tasting the banister: ...
Instead of tasting the donkey: ...
(etc.)

in a story in which most items have unique flavor descriptions. In that situation, it may be more sensible to overhaul the design of the action: create a new text property for things, and revise "tasting" so that it now consults this property:

The block tasting rule is not listed in any rulebook.
A thing has some text called the flavor. The flavor of a thing is usually "Nothing special."
Report tasting something:
   if the flavor of the noun is "Nothing special.":
      say "You taste nothing unexpected." instead;
   otherwise:
      say "[the flavor of the noun][paragraph break]" instead.
Report someone tasting something:
   say "[The actor] licks [the noun]."

Finally and most sweepingly, we can rip out whole passages of the Standard Rules and replace them – or not. This is a drastic measure and rarely necessary (or so we hope); but see the Extensions chapter for ways to replace sections of existing source, or even revise the Inform 6 template files on which Inform depends. By these means almost anything can be changed. We can throw out a whole range of existing commands and start from scratch, for instance, if we want Inform to know about a completely new and different command set.

See Also

Magic (Breaking the Laws of Physics) for a hat that lets the player walk through closed doors, and an NPC able to reach through solid containers.

Example

214.
Creating an amulet of tumblers that can be used to lock and unlock things even when it is worn, overriding the usual requirement that keys be carried.

RB §6.4 Looking

Looking is quite a complicated command, since the production of a room description takes many steps. A detailed description of this process may be found in the Room Descriptions section.

By convention, a player sees full descriptions of rooms he enters more than once, but may type BRIEF in order to see shorter descriptions, and SUPERBRIEF tells the story never to print room descriptions at all. VERBOSE restores the default behavior.

These conventions are not always appropriate, however, especially in works where experiencing a changing environment is essential. The use option

Use brief room descriptions.

changes the default behavior so that rooms are not always described fully to the player. Verbosity demonstrates how this works.

The player always has the option of turning room descriptions to BRIEF or SUPERBRIEF mode. Verbosity 2 demonstrates how we might remove the player's ability to change the default behavior.

See Also

Room Descriptions for a detailed description of how Inform creates room descriptions and how to change the results.
Going, Pushing Things in Directions for ways to change just those room descriptions that are shown as the result of the player's movement.
Memory and Knowledge for ways to change the room description in response to the player character's knowledge at any given stage of play.

Examples

3.
Making rooms give brief room descriptions when revisited.
395.
Making rooms give full descriptions each time we enter, even if we have visited before, and disallowing player use of BRIEF and SUPERBRIEF.

RB §6.5 Examining

By default, examining an object shows its description, and – for devices – tells us whether the object is switched on or switched off.

This kind of additional information is not always what we want, so if we have a device whose on/off status we want to conceal, we may write

The examine described devices rule is not listed in any rulebook.

On the other hand, there are times when we may want to add a similar line or two to the descriptions of other kinds of objects. Crusoe ★★★ allows us to append an "It is charred." sentence to the end of descriptions of things we have burned in the fire. Since it works by introducing a "printing the description" activity, Crusoe is also a good example to start from if we want to introduce more complex, flexible descriptions of items throughout our story.

Odin rewrites the "You see nothing special…" line with other text of our own, for items that otherwise do not have a description.

Finally, we may want to look at multiple things at once. The Left Hand of Autumn ★★★ demonstrates how we might provide a different response for EXAMINE PAINTINGS than for examining each individually; Beekeeper's Apprentice ★★ provides a SEARCH command that will show the descriptions of all the scenery in the current location.

See Also

Actions on Multiple Objects for an alternative EXAMINE ALL command.

Examples

44.
Odin
Replacing "You see nothing special…" with a different default message for looking at something nondescript.
Making the SEARCH command examine all the scenery in the current location.
The possibility of using a [things] token opens up some interesting complications, because we may want actions on multiple items to be reported differently from actions on just one. Here we look at how to make a multiple examination command that describes groups in special ways.
337.
Crusoe ★★★
Adding a "printing the description of something" activity.

RB §6.6 Looking Under and Hiding

Finding hidden objects is a classic puzzle in IF. Beachfront provides the most basic example, an object that becomes visible only when we have searched the papers on a cluttered desk. Beneath the Surface takes this further, giving all large furnishings the ability to conceal items, and allowing the player to put things underneath other things, as well as find them. Flashlight adds an extra twist to the puzzle by requiring that the player have a flashlight to shine under a bulky object in order to find what lies underneath.

Looking inside an object is generally handled by the searching action, and we could extend that to allow the player to search multiple or complex objects. Matreshka turns the puzzle on its head by allowing the player to search a whole room systematically with only a single command.

See Also

Kitchen and Bathroom for the related case of needing to look in a mirror.

Examples

98.
An item that the player can't interact with until he has found it by searching the scenery.
172.
A SEARCH [room] action that will open every container the player can see, stopping only when there don't remain any that are closed, unlocked, and openable.
218.
Visibility set so that looking under objects produces no result unless the player has a light source to shine there (regardless of the light level of the room).
An "underlying" relation which adds to the world model the idea of objects hidden under other objects.

RB §6.7 Inventory

Occasionally we would like to change the way the name of something is printed as part of our inventory, and we can do this with a printing the name rule such as

Rule for printing the name of the dead rat while taking inventory:
   say "dead rat (at arm's length)"

There are also several possibilities for redesigning the inventory list as a whole. Persephone ★★★ shows how to divide an inventory list into two parts, a "You are carrying: " section and a "You are wearing: " section. Equipment List ★★ goes further, and shows how we might use Inform's specialized listing functions to create a variety of differently formatted inventories.

Sometimes the way Inform by default lists properties such as "(closed)" or "(open but empty)" isn't quite what we want. Oyster Wide Shut offers a flexible alternative to the standard behavior, allowing finer control over which properties are listed and how they are described.

Trying Taking Manhattan ★★★ replaces the inventory behavior for other characters: instead of silently looking through their possessions (but not describing them to the player), they now describe to the player what they're carrying and wearing.

Examples

Replacing Inform's default printing of properties such as "(closed)", "(open and providing light)", etc., with our own, more flexible variation.
177.
Overview of all the phrase options associated with listing, and examples of how to change the inventory list into some other standard formats.
65.
Persephone ★★★
Separate the player's inventory listing into two parts, so that it says "you are carrying…" and then (if the player is wearing anything) "You are also wearing…".
Replacing the inventory reporting rule with another which does something slightly different.

RB §6.8 Taking, Dropping, Inserting and Putting

We may want to change the default refusal message when the player tries to pick up scenery: Replanting demonstrates this case simply.

Removal modifies responses to successful TAKE commands, with the effect that when the player picks up an item, he gets a response such as "You take the book from the shelf."

Croft ★★★ modifies the DROP command, so that objects dropped on specific surfaces get reported in a special way. Celadon allows the player to drop even objects he is carrying indirectly, for instance on a tray or in a sack.

Morning After introduces a simple rule that changes the behavior of the whole story: whenever the player takes an item he hasn't already looked at, he automatically examines it. This picks up the pace of exploration passages where the player is likely to be collecting a large number of objects.

By default, when the player tries to put or insert an item that he isn't holding, Inform prints a refusal message; Democratic Process ★★★ and Sand ★★★★ offer ways instead to have the player first pick up the relevant items. (The former applies to single items the player is trying to place; the latter expands coverage to work even if the player uses a command affecting multiple objects.)

Taking also happens as a result of other commands. Such takes can be made unnecessary by turning off the "carrying requirements rule" under particular circumstances, or presented differently using the implicitly taking activity.

Examples

16.
Changing the response when the player tries to take something that is scenery.
When the player picks something up which he hasn't already examined, the object is described.
198.
TAKE expanded to give responses such as "You take the book from the shelf." or "You pick up the toy from the ground."
224.
Using the enclosure relation to let the player drop things which he only indirectly carries.
86.
Make PUT and INSERT commands automatically take objects if the player is not holding them.
202.
Croft ★★★
Adding special reporting and handling for objects dropped when the player is on a supporter, and special entering rules for moving from one supporter to another.
379.
Lollipop Guild ★★★
Overriding the rules to allow the player to show something to another character without first taking it.
87.
Sand ★★★★
Extend PUT and INSERT handling to cases where multiple objects are intended at once.

RB §6.9 Going, Pushing Things in Directions

Going is the most complex of actions after looking (or perhaps including looking): the success of every movement depends on the direction the player goes; the room he starts from; the room he intends to reach; whether there are any doors intervening (and, if so, whether these are closed or locked); whether he is traveling by vehicle; and whether he is pushing anything in front of him. When he gets there, the description he sees is itself generated by a looking command.

Pushing something in a direction is really a sort of going. The command >PUSH WHEELBARROW WEST first checks certain qualifying rules: by default, only things defined as pushable between rooms may be pushed, and they may be pushed only in horizontal directions (not UP or DOWN) – though these rules can be overridden, as we see in Zorb ★★★. If the player's pushing attempt passes these criteria, the action is translated automatically into a going action, with all the usual checks about whether that direction leads anywhere, whether a door is in the way, and so on. The converted action afterward can be caught with such rules as

Instead of going to the Alpine Meadow with the wheelbarrow:
   say "You don't want to crush the delicate blooms."
Instead of going north with the handcart:
   say "The headwind is so stiff that you are unable to make much northerly progress at all while encumbered by the handcart."

Since the two actions are internally being handled as one, both are discussed here.

It is very common for players to make a mistake and type the wrong direction command, or even to misunderstand the room description and not recognize all the possible exits. Bumping into Walls ★★★ helpfully adds a facility so that when the player tries to go in the wrong direction, the story lists the correct possibilities, as in

From here, the viable exits are to the south, the east and the west.

Assuming that travel succeeds, another useful technique is to provide some sense of the journey between locations, especially if they are remote from one another or the player has to do something unusual to get from one to the other. Up and Up ★★ adds a short description of travel when we approach a new room, before the room description is printed; Veronica , conversely, adds a comment when the player leaves a region of the map. The Second Oldest Problem intervenes and kills a player who tries to travel from one dark room to another. Mattress King embellishes the description that automatically results from PUSH MATTRESS WEST, adding a line that describes the player pushing the object before describing the new room approached.

We may also want to add a brief comment when we arrive in a new room, after the room description is printed. One trivial way to do this is to append the line to the room's main description, conditionally, like this:

The Hammock Emporium is a room. "This is Cousin Ed's shop, the big dream he left accounting to pursue. You can't help gawking at the Luxury Leather Space Hammock, made of genuine red buffalo skins[if unvisited]. [paragraph break]So this is why Grampa makes all those 'lying down on the job' jokes every Thanksgiving[end if].".

But often we want our first-glance comment to come after some items in the room are described; and for this effect, we would use the "first look rule" defined in Saint Eligius .

If these methods are not enough, the looking action has an action-specific variable called "the room-describing action", which records whether this particular instance of looking comes about because the player typed LOOK or because the player traveled to a new location. We can consult this variable if we want to make looking work differently after going, as for instance here:

Check looking when the room-describing action is the going action:
   say "You are temporarily too blinded to see." instead.

Another category of examples treat how we handle the movement commands themselves. The eight compass directions, with UP and DOWN, IN and OUT, are used as standard in most interactive fiction, but they are not the only possible way of navigating, and strike many newcomers to the genre as counter-intuitive, since when strolling around in real life most of us rarely think about our travel in terms of compass orientation. Misadventure allows the player to GO TO a named room, instead, and calculates the best route to reach the destination; Safari Guide ★★ builds on this by letting the player make the whole trip in a single move, automatically opening any doors that stand in his way en route.

In the same spirit of interpreting the player's intentions sensibly, Provenance Unknown ★★★ modifies the pushing command so that if the player pushes the top object in a stack of objects towards a direction, Inform attempts to move the bottom item instead. This is convenient if, for instance, we have a heavy television on a movable cart and want PUSH TELEVISION WEST to work just as well as PUSH CART WEST.

We also sometimes want to respond sensibly to terse movement commands or ones that rely on some knowledge of where the player has already been. Polarity ★★★ provides a GO BACK command, allowing the player to retreat in the direction from which he came, while Minimal Movement understands LEAVE, GO, and so on as OUT, in the absence of other information. Owen's Law ★★★ takes this further, calculating from the best routes on a map how to make OUT mean "move towards the exit of this indoor room", and IN mean "proceed further into the interior". Wonderland ★★ assigns altitudes to all rooms and works out the local best meaning of UP and DOWN accordingly.

See Also

Map for how to create other kinds of new direction.
Varying What Is Read for further divisions of the standard compass, such as north-northwest.
Ships, Trains and Elevators for ship-board directions.
Bicycles, Cars and Boats for common vehicles in which to travel the map.

Examples

100.
An effect that occurs only when the player leaves a region entirely.
Adding extra phrasing to the action to PUSH something in a direction.
Adapting the going action so that something special can happen when going from a dark room to another dark room.
306.
A going by name command which does respect movement rules, and accepts names of rooms as commands.
Supplying a default direction for "go", so that "leave", "go", etc., are always interpreted as "out".
Adding a first look rule that comments on locations when we visit them for the first time, inserting text after objects are listed but before any "every turn" rules might occur.
6.
Up and Up ★★
Adding a short message as the player approaches a room, before the room description itself appears.
256.
Wonderland ★★
Hiking Mount Rainier, with attention to which locations are higher and which lower than the present location.
307.
The same functionality, but making the player continue to move until he reaches his destination or a barrier, handling all openable doors on the way.
102.
Offering the player a list of valid directions if he tries to go in a direction that leads nowhere.
103.
Polarity ★★★
A "go back" command that keeps track of the direction from which the player came, and sends him back.
107.
Allowing something like PUSH TELEVISION EAST to push the cart on which the television rests.
108.
Zorb ★★★
Replacing the message the player receives when attempting to push something that isn't pushable, and also to remove the restriction that objects cannot be pushed up or down.
179.
Owen's Law ★★★
OUT always means "move to an outdoors room, or else to a room with more exits than this one has"; IN always means the opposite.

RB §6.10 Entering and Exiting, Sitting and Standing

Under ordinary circumstances, Inform does not keep track of the player's posture, nor of his exact location in a room. Lies implements a room in which the player can lie in different positions on the floor, getting different views as a result.

Our other examples are all modifications of the way Inform handles player movement to make better default guesses at what he wants to do: Anchorite adds a GET DOWN and DOWN command that work when the player is on a supporter, to accompany GET UP, GET OFF, and GET OUT (already understood). Get Axe makes the player get out of a portable container before attempting to lift it – a consideration that comes up relatively rarely, but that might pertain to inflatable rafts, beanbag chairs, and other lightweight but capacious pieces of furniture.

See Also

Position Within Rooms for a box the player can push around the room and stand on in different locations.
The Human Body for letting the player sit, stand, or lie down systematically on furniture or on the floor.
Furniture for various objects on which the player can sit or stand.

Examples

206.
Changing the check rules to try automatically leaving a container before attempting to take it. (And arranging things so that other people will do likewise.)
290.
By default, Inform understands GET OFF, GET UP, or GET OUT when the player is sitting or standing on an enterable object. We might also want to add GET DOWN and DOWN as exit commands, though.
310.
Lies
Commands to allow the player to lie down in three different ways.

RB §6.11 Waiting, Sleeping

The standard WAIT command makes time pass at the same rate that it would anyway – one minute per turn. In a story where events happen at specific times of day, though, we might want to give the player more control. Nine AM Appointment shows how to give the player a WAIT 10 MINUTES command, while Delayed Gratification ★★ lets him WAIT UNTIL a specific time of day.

Ordinarily, Inform also refuses to allow the player to SLEEP and WAKE UP: the commands exist, but have no effect. Change of Basis ★★ lets the player put himself into a sleep state in which he cannot do anything. A somewhat more interesting expansion on this idea would be to let the player sleep and have dreams; there are no examples specifically of dream states, but we might consult the examples on scenes about how to disrupt one environment and move the player to another, entirely new one.

See Also

Scene Changes for ways to move the player to a new environment such as a dream state.

Examples

A WAIT [number] MINUTES command which advances through an arbitrary number of turns.
47.
Implementing sleeping and wakeful states.
A WAIT UNTIL [time] command which advances until the game clock reaches the correct hour.

RB §6.12 Other Built-In Actions

Many other actions are themselves very simply implemented and provide only a shell for us to expand on according to the needs of a particular story. Many of these are discussed at more length in sections on various kinds of props and objects; in particular:

See Also

Modifying Existing Commands for ways to override automatic takes or restrictions on what the player must be able to hold or touch.
Sounds for LISTEN.
Barter and Exchange for GIVE and SHOW.
Combat and Death for ATTACK.
Saying Simple Things for ASK, TELL, and ANSWER.
Food for TASTE and EAT.
Liquids for DRINK.
Clothing for WEAR and TAKE OFF.
Bags, Bottles, Boxes and Safes for OPEN, CLOSE, LOCK, and UNLOCK as applied to containers.
Doors, Staircases, and Bridges for OPEN, CLOSE, LOCK, and UNLOCK as applied to doors.
Furniture for things the player can ENTER and GET OUT of.
Money for BUY.
Fire for BURN.
Glass and Other Damage-Prone Substances for CUT.

RB §6.13 Magic Words

Many fantasy games incorporate the idea of magic words that can be spoken. In implementing these, we want to be a bit flexible and accept a range of input regardless of whether the player explicitly speaks the command aloud: XYZZY, SAY XYZZY, or perhaps even CAST XYZZY. The inventively named Xyzzy demonstrates how we might define such a command.

If we want to go even further and to allow the player also to use quotation marks, as in SAY "XYZZY", we may want to include Punctuation Removal by Emily Short, which allows for quotation marks to be stripped out of the player's input before it is understood.

Example

287.
XYZZY
Basics of adding a new command reviewed, for the case of the simple magic word XYZZY.

RB §6.14 Remembering, Converting and Combining Actions

Sometimes we want Inform to apply a player's action to a different target than the one specified: for instance, directing all (or almost all) commands from the doorknob to the door of which it is a part. Fine Laid demonstrates how to do this. Along the same lines, Lucy shows how to direct a player's conversation action to apply to a new conversation topic.

We can also record a series of actions performed by the player or by another character.

Cactus Will Outlive Us All demonstrates characters each of whom reacts to a very specific provocation; I Didn't Come All The Way From Great Portland Street implements a game show in which the player is not allowed ever to repeat an action he has already performed; and Leopard-skin implements a maze which the player can escape only by performing a specific sequence of actions.

Anteaters ★★ provides a peculiar gizmo that can remember actions performed in its presence and force the player to reiterate them.

Examples

88.
Making writing that can be separately examined from the paper on which it appears, but which directs all other actions to the paper.
92.
Lucy
Redirecting a question about one topic to ask about another.
For every character besides the player, there is an action that will cause that character to wither right up and die.
429.
A maze that the player can escape if he performs an exact sequence of actions.
In this fiendishly difficult puzzle, which may perhaps owe some inspiration to a certain BBC Radio panel game (1967-), a list is used as a set of actions to help enforce the rule that the player must keep going for ten turns without hesitation, repetition, or deviating from the subject on the card.
222.
Anteaters ★★
The player carries a gizmo that is able to record actions performed by the player, then force him to repeat them when the gizmo is dropped. This includes storing actions that apply to topics, as in "look up anteater colonies in the guide".

RB §6.15 Actions on Multiple Objects

Inform allows a handful of actions – TAKE, DROP, PUT, INSERT – to apply to more than one item at a time, so that the player can move things around easily.

The general principle is that multiple objects are allowed if the actions are likely to be successful but not interesting most of the time, and if they're things that the player could plausibly do all at once. For most actions, the use of ALL would seem weirdly indiscriminate: EAT ALL, say, describes very implausible behavior, and EXAMINE ALL would likely generate a screenful of text at once.

But this is all under our control. To create an action that uses multiples, or to allow the use of multiple objects with an already-existing action, we need to create an understand statement that uses the "[things]" token (note the plural). For instance:

Understand "give [things] to [someone]" as giving it to.

This would let the existing give action apply to multiple objects, in just the same way that "take" does. Shawn's Bad Day demonstrates how we might allow EXAMINE ALL to print descriptions of every visible item.

Alternatively, we could generate a new action:

Understand "give [things] to [someone]" as multiply-giving it to. Multiply-giving it to is an action applying to one carried thing and one thing.

(In theory the language here should perhaps be "several carried things" – but Inform is still going to process multiply-giving item by item, unless we redirect it. More about this in a moment.)

When handling an action that uses the "[things]" token, the parser makes a list of every item to which it is going to apply the action: this is called the multiple objects list. The multiple objects list can be the result of a vague request (GET ALL) or a specific one involving identical multiples (GET PENNIES, GET THREE APPLES) or a very specific one involving unique, named nouns (GET GERBIL, APPLE, AND POMEGRANATE).

We can manipulate what Inform includes in "ALL" in sentences like TAKE ALL with the "deciding whether all includes…" activity; for instance

Rule for deciding whether all includes scenery: it does not.

prevents TAKE ALL from applying to things that can't be moved anyway, avoiding lots of lines like

tree: That's hardly portable.
swing set: That's hardly portable.

A slightly tedious technical note: the multiple objects list is not strictly a list in the standard Inform sense, because it is used so frequently in parsing that it would be cumbersome to handle it with the more flexible but less efficient structure used for lists. However, if we want to manipulate the multiple objects list as though it were an ordinary list – that is, sort it, rotate it, truncate it, remove entries from it, etc – we may do so by creating a list like this:

let L be the multiple object list.

and later after making L conform to our desires:

alter the multiple object list to L.

Inform next repeatedly runs the action rulebook for the action generated, using each item from the multiple object list as "noun" in turn (or as "second noun", if that's where the [things] token appeared in the understand line). Since it is possible to alter the multiple object list before the "generate action rule" portion of the turn sequence consults the rulebooks, we can also affect the order in which the player's matched objects are handled; see Formicidae ★★. We should not attempt to change the multiple object list after this point, because this is likely to introduce bugs.

Each time Inform tries the action on a new noun, it prefixes the action-attempt with the name of the item it's currently working on. This is where we get such output as "frog eyeballs:" and "newt toes:" in long lists like

frog eyeballs: Taken.
newt toes: Taken.

These names are generated by the "announce items from multiple object lists rule" in the action-handling rules; Escape from the Seraglio ★★ shows how to alter them. In the context of this rule, the thing we are currently printing the name of can be called "the current item from the multiple object list".

Suppressing names of objects entirely, while occasionally tempting, may have unintended consequences, especially if some of the attempted actions are prevented by check rules that themselves print things. It is safest to suppress the multiple object names in the case where we already know that the action will succeed wherever it is attempted (more often for observational actions like examining than for manipulative actions like taking, or where we mean to completely override default handling).

Given that our hypothetical "multiply-giving" applies to each given object in turn, it might seem to be useless to create "multiply-giving" as an action different from "giving" – but the convenience is that manipulating the multiple object list makes it possible to group behavior artificially. The trick here is that, on the first pass of the multiply-giving rulebook, we look at the entire multiple object list, perform actions, print output, and set a flag saying that the action has been handled. The flag tells Inform not to do or print anything for any of the subsequent passes through that action rulebook; thus we artificially create a situation where, instead of performing an action on each object in turn, Inform acts once on the entire group. That allows us to assess the cumulative qualities of the group and have the action respond differently than it might when assessing each item individually.

The Facts Were These ★★ demonstrates how we might write an action for GIVE THREE DOLLARS TO MAN or GIVE PIE AND HAT TO MAN where the man would only accept the collective gift when its total proved satisfactory.

Western Art History 305 ★★ demonstrates how we might allow EXAMINE, which doesn't normally permit multiple objects, to take them, but to give vaguer responses to a mass examination than an individual one.

See Also

Examining for groups of objects that have a collective description different from their individual descriptions, and for commands that search multiple things at once.
Dispensers and Supplies of Small Objects for ways to let the player pick up a number of identical items from a dispenser or supply.

Examples

Allowing the player to EXAMINE ALL.
Reordering multiple objects for dramatic effect.
Allowing EXAMINE to see multiple objects with a single command.
Replacing the usual response to TAKE ALL so that instead of output such as "grapes: Taken. orange: Taken.", Inform produces variable responses in place of "grapes:".
427.
Formicidae ★★
Manipulating the order in which items are handled after TAKE ALL.
Creating a variant GIVE action that lets the player give multiple objects simultaneously with commands like GIVE ALL TO ATTENDANT or GIVE THREE DOLLARS TO ATTENDANT or GIVE PIE AND HAT TO ATTENDANT. The attendant accepts the gifts only if their total combined value matches some minimum amount.

RB §6.16 Alternate Default Messages

Often we will want to replace the text produced by Inform by default: this includes quite a wide range of text, much of which either describes the success of a command or explains why the action failed.

Inform provides the Responses system to enable default messages like "You can't go that way" to be changed, and this is capable of making large-scale changes. This is especially useful if we want to give the viewpoint character a distinctive voice and set of mannerisms.

RB §6.17 Clarification and Correction

Some commands and some objects raise special challenges when it comes to working out the player's intention.

Sometimes this can be done with good rules about the assumptions Inform should make. Alpaca Farm demonstrates a USE command, always a challenge because USE can mean very different actions with different items.

There are also times when we need to ask the player for more information. Apples demonstrates how sensibly to use properties to disambiguate between similar objects, while Walls and Noses ★★★ rephrases the disambiguation question when special objects are involved: examining one of the walls of the room will make the story ask "In which direction?" and EXAMINE NOSE will lead to "Whose nose do you mean, Frederica's, Betty's, Wilma's or your own?"

At other times, the player types something that is wrong in a predictable way: for instance, we might want to remove all the "with…" phrases from commands like

HIT DOOR WITH FIST
KICK DRAGON WITH FOOT
LOOK WEST WITH EYES

and merely parse the remainder of the command. (That last command may be unlikely, but novice players do quite often type commands that refer unnecessarily to body parts.) Cave-troll ★★★ demonstrates how.

WXPQ demonstrates how to modify the error message the parser gives in response to a command it doesn't understand; this particular example focuses on the "That noun doesn't make sense in this context" message that arises from using the "[any thing]" or "[any room]" tokens, but the techniques could be adapted to handling other parser errors as well.

For catching typing errors, Cedric Knight's extension Mistype may also be of use: it provides an automatic typo-correction function that the player can turn on or off.

Examples

289.
A generic USE action which behaves sensibly with a range of different objects.
368.
Apples
Prompting the player on how to disambiguate otherwise similar objects.
380.
WXPQ
Creating a more sensible parser error than "that noun did not make sense in this context".
370.
Walls and Noses ★★★
Responding to "EXAMINE WALL" with "In which direction?", and to "EXAMINE NOSE" with "Whose nose do you mean, Frederica's, Betty's, Wilma's or your own?"
423.
Cave-troll ★★★
Determining that the command the player typed is invalid, editing it, and re-examining it to see whether it now reads correctly.

RB §6.18 Alternatives To Standard Parsing

Very occasionally, for out-of-the-ordinary games, we want to make major changes to the way that Inform ordinarily understands commands.

Cloves ★★ shows how we might read adverbs in the player's command: adverbs are challenging because they can legitimately appear anywhere in a command structure, so must be found and accounted for before the rest of the command is understood.

Fragment of a Greek Tragedy ★★ goes further, substituting a keyword-recognition parser for the usual structure of commands and objects.

Less drastically, menus of numbered options can temporarily replace or augment standard commands. Down in Oodville ★★ demonstrates how to add a list of transporter destinations from which the player may choose by numeral.

See Also

Traits Determined By the Player for ways to ask the player a question at the beginning of play.
Saying Simple Things for a way to ask the player a yes-no question any time during play.

Examples

304.
Offering the player a choice of numbered options at certain times, without otherwise interfering with his ability to give regular commands.
373.
Cloves ★★
Accepting adverbs anywhere in a command, registering what the player typed but then cutting them out before interpreting the command.
Responding to the player's input based on keywords only, and overriding the original parser entirely.