Inform 7 Home Page / Documentation

Chapter 6: Commands

§6.1. Designing New Commands; §6.2. Writing New Commands; §6.3. Modifying Existing Commands; §6.4. Looking; §6.5. Examining; §6.6. Looking Under and Hiding; §6.7. Inventory; §6.8. Taking, Dropping, Inserting and Putting; §6.9. Going, Pushing Things in Directions; §6.10. Entering and Exiting, Sitting and Standing; §6.11. Waiting, Sleeping; §6.12. Other Built-In Actions; §6.13. Magic Words; §6.14. Remembering, Converting and Combining Actions; §6.15. Actions on Multiple Objects; §6.16. Alternate Default Messages; §6.17. Clarification and Correction; §6.18. Alternatives To Standard Parsing

arrow-up-left.png Contents of The Inform Recipe Book
arrow-left.png Chapter 5: The Viewpoint Character
arrow-right.png Chapter 7: Other Characters
arrow-down-right.png Indexes of the examples

§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


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:


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)

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?)

arrow-up.png Start of Chapter 6: Commands
arrow-left.png Back to Chapter 5: The Viewpoint Character: §5.6. Viewpoint
arrow-right.png Onward to §6.2. Writing New Commands