See Memory and Knowledge for more about the any token and the concept of scope to control what the player may refer to in a commandInform 7 Home Page / Documentation
§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
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
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
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:
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
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
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
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 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
