18. Activities

Writing with Inform

WI §18.1 What are activities?

It is poor form to define with negatives, but the first thing to say about activities is that they are not actions. This needs saying because Inform often seems to treat them as if they are, by allowing us to write rules like so:

Before printing the name of a woman, say "Ms ".

With this rule in place, someone called "Daphne" will always be described as "Ms Daphne", and so on. The language looks as if we were imposing a rule on an action called "printing the name of", but there is no such action: instead, it is an "activity". To spell out the difference:

An action is a simulated task for the fictional protagonist.
An activity is a real task for the computer program doing the simulation.

Activities allow us to influence or change some of the standard habits of Inform, using rules as flexible and powerful as those applicable to actions, though activities are in several ways simpler and easier.

Example

What are activities good for? Controlling output when we want the same action to be able to produce very flexible text depending on the state of the world – in this case, making highly variable room description and object description text.

WI §18.2 How activities work

All activities start, continue for a while and then finish: however, no activity ever runs on for more than a single turn. Several activities can be going on at the same time. For instance, suppose the following is printed as part of the description of a grocery:

You can see a banana, an apple and a star-fruit here.

At the moment when Inform prints "apple", two activities are under way: "listing contents of the Grocery", and "printing the name of the apple". The sequence of events was in fact:

say "You can see "
start listing contents of the Grocery
   say "a "
   start printing the name of the banana
      say "banana"
   finish printing the name of the banana
   say ", an "
   start printing the name of the apple
      say "apple"
   finish printing the name of the apple
   say " and a "
   start printing the name of the star-fruit
      say "star-fruit"
   finish printing the name of the star-fruit
finish listing contents of the Grocery
say " here."

The golden rule is: if activity B starts during activity A, it must also finish during activity A.

If we ever need to find out, we can always test:

if the printing the name activity is going on, ...
if the printing the name activity is not going on, ...

but as we shall see, it's usually simpler to attach "while printing the name" provisos to rules.

WI §18.3 Rules applied to activities

The activity "printing the name of something" is the process of printing up the name of something on screen: ordinarily, this means saying the text in its "printed name" property.

As with actions, rules can be attached to activities which change or augment what would normally happen. In fact the situation is simpler, because (unlike an action) an activity almost always finishes, so we almost always do reach its "after" stage. There are also only three rulebooks attached to an activity, as compared with the six affecting an action.

The three rulebooks for printing the name are called "before printing the name", "for printing the name" and "after printing the name", and this is the general pattern. What happens is:

1. All "before printing the name of" rules are considered;
2. The most specific, applicable "rule for printing the name of" is considered;
3. All "after printing the name of" rules are considered.

Whereas an action's later stages never take place if an early stage ends unexpectedly, an activity always goes through all three of its stages. Invoking the word "instead" in a before rule for an action will terminate not only the before rules but the whole action: the same thing for an activity will only terminate the before rules, and the for and after rules will take place as usual.

The actual task is usually carried out by one single rule tucked into the back of the "for…" rulebook: it is the rule for printing the name of whatever is concerned, hence the name. Inform's standard activities are all of this pattern: they start out with no "before" or "after" rules, and just one "for" rule.

Why the part about an activity only "almost always" finishing? One reason is that the story might end during it; but another is that it's possible, though uncommon, to abandon an activity partway. Very few of the activities supplied with Inform ever do this, and those that do are noted in the sections which follow.

WI §18.4 While clauses

Rules applied to actions can become baroque ("after going through a door in the presence of an animal when -" and so on and so forth), but activities are again simpler: they only have one possible clause attached, which is called "while". For instance, the following would provide a fairly sledgehammer hint that the sack should not lightly be thrown away:

The sack is a player's holdall. The sack is carried. Rule for printing the name of the sack while the sack is not carried: say "your abandoned sack".

Any condition can be given after the "while", and we can also specify that another activity has to be going on. Thus:

Rule for printing the name of the lemon sherbet while listing contents: say "curious sort of lemon sherbet sweet".

This nicely distinguishes between contexts where it's appropriate to be more verbose, and where it isn't. Thus:

You can see a teaspoon and a curious sort of lemon sherbet sweet here.
> TAKE ALL
teaspoon: Taken.
lemon sherbet: Taken.

WI §18.5 New activities

Activities are all about influencing the standard mechanisms which Inform uses, so it might at first seem that there is no need to create new activities: but on further reflection, quite a lot of the writing of interactive fiction involves creating new and systematic ways to do things, and as soon as we have a general rule, we will want to have exceptions. Inform therefore allows us to create our own activities, giving us ways to influence the operation of our own mechanisms.

There are two kinds of activity: those which relate to a specific value (usually an object but not necessarily), and those which do not. Here are some examples of activities being created:

Assaying is an activity.
Analysing something is an activity.
Announcing something is an activity on numbers.

Inform looks for the clue "something" (or "of something") after the activity's name to see if it will work on a value: so analysing and announcing will do, but assaying won't. If we don't specify a kind, Inform assumes the value will be an object, as if we had written:

Analysing something is an activity on objects.

As always in Inform, the names of activities are themselves values.

"assaying activity" has kind activity on nothing
"analysing activity" has kind activity on objects
"announcing activity" has kind activity on numbers

Creating an activity is like creating an action: it automatically makes new rulebooks – "before analysing", "for analysing" and "after analysing" – but they start out empty, so the activity does nothing yet. Just as it does for rulebooks, Inform defines the adjectives "empty" and "non-empty" for activities to test this state:

if the analysing activity is empty, ...

will be true only when all three of its rulebooks are empty.

A newly created activity never happens unless we take steps to make it do so. We can make an activity happen at any time by writing phrases like so:

carry out the (activity) activity

This phrase carries out the given activity, which must be one not applying to any value. Example:

carry out the assaying activity;
carry out the (activity on values) activity with (value)

This phrase carries out the given activity, which must apply to a kind of value matching the one supplied. Example:

carry out the analysing activity with the pitchblende;
carry out the announcing activity with the score;

To make the activity do something useful, we need to put a rule into its "for" rulebook:

Rule for announcing a number (called N): say "Ladies and gentlemen, [N]."
The last for assaying rule:
   say "Professionally, you cast an eye around mineral deposits nearby, noticing [list of rocks in the location]."

"The last" is a technicality about rulebooks (see the next chapter) which, put briefly, guarantees that this rule comes last among all possible "for assaying" rules. This is good form because the whole point of an activity is to make it easy for further rules to interfere – so we deliberately hang back to last place, giving precedence to anybody else who wants it.

The "for" rulebook is one where rules stop the activity, by default, when they take effect – in the same way that the "instead" rules stop actions by default. If this causes problems, we can use:

continue the activity

This phrase should be used only in rules in activity rulebooks. It causes the current rule to end, but without result, so that the activity continues rather than stopping as a result of the rule. This is useful for rulebooks (like the "for" rulebook of an activity) where the default is that a rule does stop the activity.

Activities are more useful than they first appear. Every new one provides a context which other activities can observe. We could, for instance, define

Rule for printing the name of a rock while assaying: ...

so that during assays more technical names are used.

Examples

335.
An Encyclopedia set which treats volumes in the same place as a single object, but can also be split up.
336.
Aftershock ★★★
Modifying the rules for examining a device so that all devices have some specific behavior when switched on, which is described at various times.
337.
Crusoe ★★★
Adding a "printing the description of something" activity.

WI §18.6 Activity variables

Just as actions can have variables, which are created when the action starts and disappear when it finishes, so activities can also have variables. They are visible to the rules for that activity, and nowhere else. (If the activity should happen a second time within its first run, that second occurrence gets its own copy of the variable, leaving the original untouched.)

Typically it will be useful to set a variable to some default value at the "before" stage, calculate some interesting value for it in the "for" stage, and make use of the outcome during the "after" stage. For instance:

Analysing something is an activity. The analysing activity has a text called first impression. Instead of examining something (called the sample), carry out the analysing activity with the sample.
Before analysing: now the first impression is "unremarkable".
Rule for analysing someone: now the first impression is "living tissue".
After analysing something (called the sample):
   say "Your professional opinion of [the sample] is that it is
      [first impression]."

WI §18.7 Beginning and ending activities manually

If we have declared a new activity, like "analysing", the normal way to make it happen would be to write

carry out the analysing activity with the pitchblende;

which goes through the whole machinery of rules – before, for, after – and then resumes, the activity having started, taken place and come to an end.

But there are times when it is not convenient to write a suitable "for …" rule, or where we need more control, and do not wish to hand the whole business over to a single phrase. For such times we are allowed to write:

begin the (activity) activity

This phrase causes the named activity to become active, and runs its "before" rulebook. The activity must be one which applies to nothing. Example:

begin the assaying activity;

In all cases a matching "end the … activity" or else "abandon the … activity" phrase must be reached.

begin the (activity on values) activity with (value)

This phrase causes the named activity to become active, and runs its "before" rulebook. The activity must be one which applies to a value of a matching kind. Example:

begin the analysing activity with the pitchblende;

In all cases a matching "end the … activity with …" or else "abandon the … activity with…" phrase must be reached.

And when we are done:

end the (activity) activity

This phrase runs the "after" rulebook of the activity and then causes it to become inactive. The activity must be one which applies to nothing. Example:

end the assaying activity;

This must only happen to match an earlier "begin the … activity" phrase.

end the (activity on values) activity with (value)

This phrase runs the "after" rulebook of the activity and then causes it to become inactive. The activity must be one which applies to a value of a matching kind. Example:

end the analysing activity with the pitchblende;

This must only happen to match an earlier "begin the … activity with…" phrase.

So the usual structure is like so:

begin the analysing activity with the pitchblende;
...
end the analysing activity with the pitchblende;

This time the activity is ongoing throughout as many phrases as we care to write between the "begin" and "end". The before rules are considered at the time of the "begin …" phrase; the after rules at the "end …".

What, then, of the "for" rules? In the above setup, they would simply be ignored. But we can make them effectual thus

begin the analysing activity with the pitchblende;
...
if handling the analysing activity with the pitchblende:
   ...
...
end the analysing activity with the pitchblende;

We place the activity's normal behaviour inside the "if"; the condition, "if handling…", is true only if no rule has intervened. This means that we (or other authors using our activity) can create their own for rules to substitute here. If we elsewhere write

Rule for handling the analysing activity with the pitchblende when the player is not sober:
   say "You can't seem to focus."

that rule will intervene and take the place of whatever we have placed inside the condition.

if handling (activity) activity:

This should be used only where the given activity has been started with "begin …" and will be finished with "end …". It runs the "for" rules for the activity, and then comes out true if none of those for rules intervened in the handling of that activity. (The activity must be one which doesn't apply to any value.)

if handling (activity on values) activity with (value):

This should be used only where the given activity has been started with "begin …" and will be finished with "end …". It runs the "for" rules for the activity, and then comes out true if none of those for rules intervened in the handling of that activity. (The given value must be the one it is being applied to.)

It is also legal to force an early end to an activity with:

abandon the (activity) activity

This phrase ends an activity at once (without consulting any further rulebooks, including its "after" rulebook). It can only be used with an activity which has had its "begin" but not yet its "end" phrase; it is a drastic remedy best taken only if it is clear that circumstances have changed so that the activity now seems inappropriate. It must not be used during one of the rules for the activity: it can only be used between the begin and for stages, or between the for and end stages.

abandon the assaying activity;
abandon the (activity on values) activity with (value)

This phrase ends an activity at once (without consulting any further rulebooks, including its "after" rulebook). It can only be used with an activity which has had its "begin" but not yet its "end" phrase; it is a drastic remedy best taken only if it is clear that circumstances have changed so that the activity now seems inappropriate. It must not be used during one of the rules for the activity: it can only be used between the begin and for stages, or between the for and end stages.

abandon the analysing activity with the pitchblende;

We need to follow three golden rules: all activities must end, they must never last longer than a turn, and if activity B starts during activity A then it must also finish during activity A. We must also be careful to make sure that if an activity applies to something, then it begins and ends with the same something (the pitchblende, in the above example).

WI §18.8 Introduction to the list of built-in activities

Activities tend to be about process, rather than outcome. Many of the things Inform does – printing up lists of items, reading commands from the keyboard, and so on – are done as activities, because that way the process can be nudged a little. Too many works of interactive fiction betray their mechanical nature by making it visible that the general machinery being used does not quite seem natural for this or that situation. Activities enable us to add the many graceful touches which avoid that: which contribute nothing to a work, and also everything.

The rest of this chapter covers every activity built in to Inform, with one section for each. It is intended primarily for reference, but may be worth skimming through at a first reading, to give a sense of the possibilities.

WI §18.9 Deciding the concealed possessions of something

1. When it happens. Frequently – whenever Inform needs to check whether something is visible or not. Nothing should be printed, and the activity needs to run quickly, so it should not (for instance) calculate best routes through complicated maps before getting an answer.

2. The default behaviour. There is no concealment. The ordinary rules still apply, though: the contents of a closed opaque container are invisible because there is a barrier in the way which cannot be seen through, even though nobody is "concealing" anything.

3. Examples. To repeat a number of brief examples given at the end of Chapter 3, where this activity made an early appearance:

Rule for deciding the concealed possessions of the Cloaked Villain: if the particular possession is the sable cloak, no; otherwise yes.
The coin is in the Roman Villa. The face and inscription are parts of the coin. Rule for deciding the concealed possessions of the coin: if the coin is carried, no; otherwise yes.

The value "particular possession" is the one whose concealment is in question, of course. We can ignore this if someone is invariably secretive:

Rule for deciding the concealed possessions of the furtive ghost: yes.

In general a rule for deciding the concealed possessions of something will decide "yes" if finishes without making a decision, but it's better style to write such a rule in such a way that it always makes a decision.

Example

338.
Clark Gable in a pin-striped suit and a pink thong.

WI §18.10 Printing the name of something

1. When it happens. Whenever the name of a thing or room is printed, either as part of text visible to the player, or sometimes internally in order to determine something about that name.

2. The default behaviour. For items other than the current player, the "printed name" property is printed out; but for the current player, "you" or "yourself" is printed. (That doesn't necessarily mean that the "printed name" of the player is never used. Suppose there are two people, Alice and Bob, and the narrative switches between them: when Alice is the player, she appears as "yourself" but Bob is "Bob"; but when Bob is the player, he is "yourself" and Alice is "Alice".)

3. Examples. (a) A pen which is described differently in inventories:

Rule for printing the name of the pen while taking inventory: say "useful pen".

"Taking inventory" is a condition which is true if that's the current action and not otherwise, so the effect is that the pen is called "a useful pen" only in inventory listings. "While looking" is a similarly useful one.

(b) Italicising the names of novels:

A novel is a kind of thing. Dr Zhivago and Persuasion are novels. Before printing the name of a novel, say "[italic type]". After printing the name of a novel, say "[roman type]".

(c) Telling the time:

After printing the name of the wrist watch while taking inventory: say " (time: [the time of day])".

(d) Merging containers with their contents:

Rule for printing the name of the bottle while not inserting or removing:
   if the bottle contains sand, say "bottle of sand";
   otherwise say "empty bottle";
   omit contents in listing.

This example makes use of a special phrase:

omit contents in listing

This phrase changes the form of an inventory listing, room description, etc., so that it will simply list "a bottle of sand" or "an empty bottle", rather than "a bottle (in which is sand)" or "a bottle (which is empty)". It should be used only when the listing is imminent, and does not have permanent effect.

The clause about not inserting or removing is to prevent messages like "You put the sand in the bottle of sand.", where it's confusing to refer to the bottle as anything other than "the bottle".

Examples

A box of baking soda whose name changes to "completely ineffective baking soda" when it is in a container with something that smells funny.
Bottles with removable stoppers: when the stopper is in the bottle, the bottle is functionally closed, but the stopper can also be removed and used elsewhere. Descriptions of the bottle reflect its state intelligently.
341.
Using name-printing rules to keep track of whether the player knows about objects, and also to highlight things he might want to follow up.

WI §18.11 Printing the plural name of something

1. When it happens. Only when a group of identical items is present in the same place, and are being described jointly with text like "You can see five gold rings here." The activity happens after "five" and before "here." (See the activity "printing a number of something" if the whole phrase needs to be altered.)

2. The default behaviour. The plural name – in this case "gold rings" – is printed out.

3. Examples. (a) Suppose we want to emphasise how nice it is to have more than one gold ring:

Rule for printing the plural name of a gold ring: say "gleaming gold rings".

(b) If the number needs changing as well, it's necessary to use the "printing a number of something" activity instead.

Example

Letters which are described differently as a group, depending on whether the player has read none, some, or all of them, and on whether they are alike or unlike.

WI §18.12 Printing a number of something

1. When it happens. Only when a group of identical items is present in the same place, and are being described jointly with text like "You can see five gold rings here." The activity prints the "five gold rings" part. The variable "listing group size" contains the number, which in this example would be 5, and is always at least 2.

2. The default behaviour. The number of items is printed, in words ("five") and then the "printing the plural name" activity is run ("gold rings").

3. Examples. (a) Using this activity is for perfectionists, because the normal behaviour is almost always fine. Still:

Rule for printing a number of blocks when the listing group size is 3: say "all three blocks".

(b) Or perhaps:

Rule for printing a number of ants: say "altogether [listing group size in words] ants".

(c) If the only part needing variation is the plural name, it's simpler and tidier to use the "printing the plural name of something" activity instead.

Example

343.
Replacing precise numbers with "some" or other quantifiers when too many objects are clustered together for the player to count at a glance.

WI §18.13 Listing contents of something

1. When it happens. When taking inventory, the list is produced by the activity "listing contents of yourself"; when looking, a list of items which do not deserve their own paragraphs is produced by "listing contents of" the location.

And when it doesn't happen. (a) If the Storage Room contains a sideboard and an open shoe box, then "listing contents of the Storage Room" is used to produce the part of the room description mentioning sideboard and box. But if the box in turn contains a pair of brogues, then "listing contents of the shoe box" is not used to say that part. So this works:

Rule for printing the name of the brogues while listing contents of a room: ...

But this won't affect room descriptions:

Rule for printing the name of the brogues while listing contents of the shoe box: ...

(b) The activity also doesn't happen when, for instance, "[a list of animals]" is printed, because that isn't a list of the contents of any room or location.

2. The default behaviour. The list is printed out.

3. Examples. (a) We have already seen that it can be elegant to elaborate on a description in the context of a list. Here we add "discarded" to a sweet wrapper which is found on the ground.

Rule for printing the name of the wrapper while listing contents of a room: say "discarded sweet wrapper".

(b) Lists can be considerably shortened and tidied up if similar items are grouped together. We do this by specifying what should be grouped together before listing contents, using the special phrase "group … together":

Utensil is a kind of thing. The knife, the fork and the spoon are utensils. Before listing contents: group utensils together as "utensils".

The result will be, say, "two utensils (knife and spoon)", if both are found in the same place.

(c) We can less obtrusively group items together like so:

Before listing contents while taking inventory: group utensils together.

Three special phrases exist for this kind of list organisation:

group (description of objects) together

This phrase causes the objects described to be listed together in a single item as part of an inventory or room description. The effect is temporary, and the phrase should only be used when this list is imminent. Example:

Utensil is a kind of thing. The knife, the fork and the spoon are utensils. Before listing contents: group utensils together.

This might produce the list item "fork and spoon".

group (description of objects) together giving articles

This phrase causes the objects described to be listed together in a single item as part of an inventory or room description, but giving each individual item its indefinite article. The effect is temporary, and the phrase should only be used when this list is imminent. Example:

Utensil is a kind of thing. The knife, the fork and the spoon are utensils. Before listing contents: group utensils together giving articles.

This might produce the list item "a fork and a spoon".

group (description of objects) together as (text)

This phrase causes the objects described to be listed together in a single item as part of an inventory or room description, summarised with the given text. The effect is temporary, and the phrase should only be used when this list is imminent. Example:

Utensil is a kind of thing. The knife, the fork and the spoon are utensils. Before listing contents: group utensils together as "utensils".

This might produce the list item "two utensils (fork and spoon)".

Example

344.
Calling an onion "a single yellow onion" when (and only when) it is being listed as the sole content of a room or container.

WI §18.14 Grouping together something

1. When it happens. Only while listing contents, and only when a collection of items to be grouped together is reached. This in turn happens only if a "before listing contents" rule has chosen it (see previous section). The first item in the group is the one to which the activity formally applies.

The variable "listing group size" usually gives the number of items grouped together in this way, but care is needed if the "something" covers multiple groups, because then this will all be working on a list of groups, not of items. For example, in a "grouping together things" rule, where "things" is such a broad description that it can apply to multiple kinds of thing all appearing in the list, the list-maker is likely to set "listing group size" to the number of groups. If the list contains five men and six women, for example, "listing group size" might be 2 rather than 11.

2. The default behaviour. The items grouped together are printed in an English phrase, such as "egg, chicken and farmer". In particular, they are not split onto separate lines even if the rest of the list is. (See previous section.)

3. Examples. (a) Here are Scrabble pieces which are described as "the tile W from a Scrabble set" or similar outside of lists, but which, when they turn up together in lists, are rolled together into "the tiles A, B and D from a Scrabble set".

A Scrabble piece is a kind of thing. The X, the Y and the Z are Scrabble pieces.
Before listing contents: group Scrabble pieces together.
Before printing the name of a Scrabble piece while not grouping together, say "tile ". After printing the name of a Scrabble piece while not grouping together, say " from a Scrabble set".
Before grouping together Scrabble pieces, say "the tiles ". After grouping together Scrabble pieces, say " from a Scrabble set".

(b) Maybe we only want an abbreviated form when there are five or more tiles in one place:

A Scrabble piece is a kind of thing. The X, the W, the F, the Y and the Z are Scrabble pieces in the Lounge.
Before listing contents: group Scrabble pieces together.
Before grouping together Scrabble pieces when the listing group size is greater than 4:
   say "some [listing group size in words] tiles (".
After grouping together Scrabble pieces when the listing group size is greater than 4:
   say ") from a Scrabble set".

(c) We can throw out all pretence at listing and say whatever we like, in fact:

Before listing contents while taking inventory: group utensils together. Rule for grouping together utensils: say "the usual utensils".

WI §18.15 Issuing the response text of something

1. When it happens. When Inform prints a text marked with a response letter (A), (B), (C), …, in a rule making use of them. For example, in this rule:

Carry out taking inventory (this is the print empty inventory rule):
   if the first thing held by the player is nothing,
      say "[We] [are] carrying nothing." (A) instead.

Or, less directly,

let R be the print empty inventory rule response (A);
say "To be frank: [text of R].";

2. The default behaviour. To print the current textual value of the response, making any substitutions in the ordinary way.

3. Examples. This activity is not the best way to amend responses or make them dynamic; the whole idea of responses is that they can be changed just as if they were text variables. This activity should be used only if it's important to amend blocks of responses in some systematic way.

(a) With that said, some interesting effects can be achieved. This is a way to see which responses are being printed, for example:

Before issuing the response text of a response (called R): say "[R]: ".

whence:

>WAIT
standard report waiting rule response (A): Time passes.

(b) And this intercepts the activity in order to re-run it in each of the six viewpoints. (Note the way a variable is used to prevent the rule from applying to all of those re-runs as well.)

The response inhibition is initially false.
Rule for issuing the response text of a response (called R) when the response inhibition is false:
   now the response inhibition is true;
   let the current viewpoint be the story viewpoint;
   repeat with P running through narrative viewpoints:
      now the story viewpoint is P;
      say "[P]: [text of R][command clarification break]";
   now the story viewpoint is the current viewpoint;
   now the response inhibition is false.

With that in place,

>EAST
first person singular: I can't go that way.
second person singular: You can't go that way.
third person singular: He can't go that way.
first person plural: We can't go that way.
second person plural: You can't go that way.
third person plural: They can't go that way.

Example

345.
Parser messages that are delivered with a speech impediment.

WI §18.16 Printing room description details of something

1. When it happens. When an item is listed in the miscellaneous collection of items present in a room (the ones which do not deserve their own paragraphs): this is normally the last paragraph of a room description.

2. The default behaviour. A bracketed piece of extra information is added for certain items such as containers:

You can also see Po and a cage (empty) here.

The " (empty)" (note initial space) was added by this activity. (Note that this activity is not responsible for describing further items visible because of the item in question: that is, it does not print the text such as "(in which is a notepad)" which would appear if there were contents. If we want to remove such text, we should use "omit contents in listing": see the activity "for printing the name of something".)

3. Examples. (a) To get rid of such addenda entirely, try:

Rule for printing room description details: stop.

(b) To add a new form of addendum:

Rule for printing room description details of a person:
   say " (at last, someone to talk to)" instead.

If both examples (a) and (b) are in place at once, we might now read:

You can also see Po (at last, someone to talk to) and a cage here.

Example

A magnet which picks up nearby metal objects, and describes itself appropriately in room descriptions and inventory listings, but otherwise goes by its ordinary name.

WI §18.17 Printing inventory details of something

1. When it happens. When an item is listed in an inventory of items carried by the player.

2. The default behaviour. A bracketed piece of extra information is added for certain items such as containers:

a flaming branch (providing light)

The " (providing light)" (note initial space) was added by this activity.

3. Examples. (a) To get rid of such addenda entirely, try:

Rule for printing inventory details: stop.

(b) To add a new form of addendum:

Rule for printing inventory details of something edible:
   say " (yummy!)[run paragraph on]".

WI §18.18 Printing a refusal to act in the dark

1. When it happens. When an action which requires light is tried, and the visibility rules decide that not enough light is present.

2. The default behaviour. To print "It is pitch dark, and you can't see a thing."

3. Examples. (a) This might do for some twilit, penumbral room:

Rule for printing a refusal to act in the dark: if we are examining something, say "It's not totally dark here, perhaps, but certainly too dim for close-up examination of anything." instead.

Example

347.
Zorn of Zorna ★★★
Light levels vary depending on the number of candles the player has lit, and this determines whether or not he is able to examine detailed objects successfully.

WI §18.19 Printing the announcement of darkness

1. When it happens. Inform frequently calculates to see if the player is in light or darkness: this activity happens on the change from light to darkness.

2. The default behaviour. To print "It is now pitch dark in here!".

3. Examples. (a) The most obvious use is to change the text:

Rule for printing the announcement of darkness: say "Ooh-er! It's now very nearly pitch dark in here." instead.

(b) But we could also use this activity for sneakier purposes, silently moving things around:

Before printing the announcement of darkness: now all of the gremlins are in the kitchen.

(c) A special description for occasions when the player has climbed into a container and shut it (so that the darkness is the result of his own actions, rather than some external circumstance):

Rule for printing the announcement of darkness when closing a container which contains the player:
   say "Congratulations: now you can't see a thing." instead.

WI §18.20 Printing the announcement of light

1. When it happens. Inform frequently calculates to see if the player is in light or darkness: this activity happens on the change from darkness to light.

2. The default behaviour. To try the looking action, which usually prints up a room description.

3. Examples. (a) Perhaps the player is initially too disoriented to look around in any coherent way:

Rule for printing the announcement of light in the Dazzling Temple: say "You are almost blinded by the suffusion of white light, and have spots before your eyes." instead.

WI §18.21 Printing the name of a dark room

1. When it happens. When looking in darkness, or writing the (default) status line in darkness.

2. The default behaviour. To print "Darkness".

3. Examples. (a) One might modify the darkness with some adjective:

Before printing the name of a dark room, say "Near ".

(Note that this activity does not come in different forms for different dark rooms: the wording is fixed at "printing the name of a dark room", and we are not allowed to substitute particular dark rooms or assign a "(called …)" onto the mention of the dark room.)

WI §18.22 Printing the description of a dark room

1. When it happens. When looking in darkness.

2. The default behaviour. To print "It is pitch dark, and you can't see a thing."

3. Examples. (a) A simple variation of wording:

Rule for printing the description of a dark room: say "Your eyes can barely make anything out." instead.

(b) More stylishly,

Rule for printing the description of a dark room: try listening instead.

which produces, for instance,

Darkness
You hear nothing unexpected.

(Note that this activity does not come in different forms for different dark rooms: the wording is fixed at "printing the description of a dark room", and we are not allowed to substitute particular dark rooms or assign a "(called …)" onto the mention of the dark room.)

Examples

348.
Changing the way dark rooms are described to avoid the standard Inform phrasing.
349.
Four Stars 1 ★★★
An elaboration of the idea that when light is absent, the player should be given a description of what he can smell and hear, instead.

WI §18.23 Constructing the status line

1. When it happens. Just before input is accepted from the keyboard, Inform constructs a "status line" at the top of the window which is normally displayed in reverse colours (white on black instead of black on white, say).

2. The default behaviour. Makes the status line up out of two pieces, the "left hand status line" and the "right hand status line". Since these can freely be changed, note that the status line is already very customisable without using rules applied to this activity.

3. Examples. (a) The most useful thing about this activity is that it allows us to vary descriptions in the status line. This is especially helpful to abbreviate unduly long room names, which might not otherwise fit:

The Temple Of A Thousand Mightily Peeved Deities is a room. Rule for printing the name of the Temple while constructing the status line: say "Temple".

(b) Again, it's usually not necessary to apply activity rules to this, but occasionally amusing effects are possible if we do:

The blindfold is wearable and carried. Rule for constructing the status line while the blindfold is worn: do nothing.

Examples

350.
A status line that lists the available exits from the current location.
351.
A status line that lists the available exits from the current location, changing the names of these exits depending on whether the room has been visited or not.

WI §18.24 Writing a paragraph about

1. When it happens. Just before writing a paragraph about some item in a room description.

2. The default behaviour. Is to do nothing. However, if a rule is supplied which prints something up, then this replaces the paragraph which would otherwise have been printed. Moreover, any items whose names are said in the course of this rule – for instance, by being listed – are then excluded from the remainder of the room description, because they are considered as having been described sufficiently already.

Warning: because we often want a "for" rule for this activity to make some calculation and then possibly choose to do nothing (see the example "Otranto"), Inform suppresses the usual paragraph not when a "for" rule took effect but when it detected a paragraph having been printed. This can get confused if a text substitution affecting paragraph breaks, say "[line break]", is within the final "say" of a "for writing a paragraph about" rule.

3. Examples. (a) This is a neat way to wrap several things together into the same paragraph:

Rule for writing a paragraph about Mr Wickham:
   say "Mr Wickham looks speculatively at [list of women in the location]."

because now "Mr Wickham looks speculatively at Velma and Daphne" will now prevent the appearance of the subsequent text "You can also see Velma and Daphne."

Inform keeps track of which objects have already been named with an either/or property called "mentioned", which it assigns whenever the name of an object has been automatically printed. So in this case, Velma and Daphne are now mentioned. Note "automatically printed", though: if the text printed had just been "Mr Wickham looks speculatively at Velma and Daphne", rather than the text-substitution list used above, then Inform would not know that Velma and Daphne have been described.

If we ever need to override this – say, we want to list all the women but make sure that Velma gets another paragraph anyway – we could change Velma to unmentioned again after the listing.

Examples

352.
Emphasizing the reflective quality of shiny objects whenever they are described in the presence of the torch.
353.
Emma ★★
Social dynamics in which groups of people form and circulate during a party.
Uses "writing a paragraph about" to make person and object descriptions that vary considerably depending on what else is going on in the room, including some randomized NPC interactions with objects or with each other.

WI §18.25 Listing nondescript items of something

1. When it happens. This activity prints up the also-ran paragraph at the end of a room description. These are nondescript items because they don't merit paragraphs of their own: if, as sometimes happens, there are none in the room, then no such paragraph is printed and this activity does not happen. (So to add a further paragraph to a room description, a simpler "after looking" rule should be used, not an "after listing nondescript items" rule.)

2. The default behaviour. The paragraph ordinarily reads as "You can also see a cask and a clock." or similar. Before the activity begins, those objects which are nondescript – in this case the cask and the clock – are given the property of being "marked for listing".

If it turns out that nothing is marked for listing, because of before rules like the one in the example below, then nothing is printed and the activity is abandoned, so that the rules for and after are never reached.

3. Examples. (a) Promoting something out of the nondescript category, by unmarking it.

Before listing nondescript items:
   if the watch is marked for listing:
      say "The watch catches your eye.";
      now the watch is not marked for listing.

(b) Changing the normal phrasing of the paragraph. Note that we can also change the listing style; the one below is the default.

Rule for listing nondescript items of the Distressingly Messy Room:
   say "Strewn carelessly on the floor";
   list the contents of the Distressingly Messy Room, as a sentence,
      tersely, listing marked items only, prefacing with is/are,
      including contents and giving brief inventory information;
   say "."

Examples

A simple way to allow objects in certain places to be described in the room description body text rather than in paragraphs following the room description.
356.
Happy Hour ★★
Listing visible characters as a group, then giving some followup details in the same paragraph about specific ones.
A systematic way to allow objects in certain places to be described in the room description body text rather than in paragraphs following the room description, and to control whether supporters list their contents or not.

WI §18.26 Printing the locale description of something

1. When it happens. A "locale description" is Inform jargon for the part of a room description which catalogues the visible items in the room. When looking, Inform will normally print the description of the room itself, followed by a locale description for the room. But if the player is in a cage in the room, there will be two locale descriptions: one for the room, then another for the cage. This activity is used to write the locale description for a single domain, and the "something" can be either a room, an enterable container, or an enterable supporter.

2. The default behaviour. Is quite complicated, and is written up in full in the typeset form of the Standard Rules downloadable from the Inform website. Briefly, though: we first run the "choosing notable locale objects" activity to find out what ought to be mentioned here. That assembles a list of things to mention, sorted into priority order. Items with priority 1 go first, then those with priority 2, and so on. The "printing a locale paragraph" activity is run for each, and in practice that usually hands the job over to "writing a paragraph about". Sometimes a paragraph will indeed be written, but not always. Sometimes there is nothing interesting to say, and an item is left until a final, single paragraph which gathers up the leftovers ("You can also see a scarlet fish, a harmonium and a kite here."), the printing of which is done by the "listing nondescript items of" activity. As soon as any item picks up the either/or property "mentioned", by having its name printed, it is struck out so that it will not appear subsequently, whatever its priority.

3. Examples. As general advice: if the effect wanted can be got using "writing a paragraph about" and "listing nondescript items of" alone, use those; if it's necessary to meddle further, use "choosing notable locale objects" and "printing a locale paragraph" to alter the normal processes; use the all-powerful "printing the locale description" activity only when the whole process needs to be altered, not the item-by-item workings.

(a) In the Very Misty Moorlands, nothing on the ground can ordinarily be seen through the swirling mist, so the locale description is suppressed entirely:

Rule for printing the locale description of the Very Misty Moorlands:
   say "Mist coils around your feet, thick as a blanket. You cannot even see the ground you walk upon." instead.
Report taking something in the Very Misty Moorlands:
   say "You grope blindly in the mist and pick up [the noun]." instead.

(b) Here we take the chance to insert an additional paragraph into the locale description. This does relate to an item which might be described later, but where the player doesn't know that:

The Horological Workshop is a room. The marble table is fixed in place in the Workshop.
The parcel is a closed opaque container on the marble table. The alarm clock is a device in the parcel. The alarm clock is switched on.
Before printing the locale description of a room (called the locale):
   if the locale encloses the alarm clock and the alarm clock is switched on, say "A faint ticking noise can be heard."

Example

358.
A debugging rule useful for checking the priorities of objects about to be listed.

WI §18.27 Choosing notable locale objects for something

1. When it happens. See "printing the locale description". This activity is expected to decide which items ought to be mentioned in a locale description for a given room, enterable container or enterable supporter, and to give each item a priority, which is a number ranging upwards from 1 (which is the top priority). The lower the priority number, the earlier the mention, or at least, the earlier the opportunity to be mentioned: it's up to other activities whether to give it a paragraph of its own or not. This activity only makes something a candidate, and decides what order the candidates will be tried in.

2. The default behaviour. By default, this activity contains only the "standard notable locale objects rule". This chooses exactly those items directly contained by the locale, assigning all of them priority 5. Note that this includes scenery, and other probably unwanted items – those will be excluded later.

3. Examples. (a) In the Misty Moorlands, only large items on the ground are visible through the mist:

A thing can be large or small. A thing is usually small. The stepladder is a large thing in the Misty Moorlands.
Rule for choosing notable locale objects for the Misty Moorlands:
   repeat with item running through large things in the Misty Moorlands:
      set the locale priority of the item to 5.
Report taking a small thing in the Misty Moorlands:
   say "You grope blindly in the mist and pick up [the noun]." instead.

Note the special phrase

set the locale priority of the item to 5;

which should be used only in rules for locale activities. It makes the given item a candidate and sets its priority. (Setting the priority to 0 forces an item not to be a candidate, and can thus undo the effect of previous rules.)

It's best to avoid situations where an item has a locale priority which is higher than that of something it is on top of, or inside, since this can result in an oddly-worded description.

Examples

359.
An object that is only visible and manipulable when a bright light fixture is on.
360.
Casino Banale ★★★
Creating room descriptions and object descriptions that change as the player learns new facts and pieces things together.

WI §18.28 Printing a locale paragraph about

1. When it happens. See "printing the locale description". By this point, the locale description process has identified a number of items as candidates to be described, and worked out a priority order. This activity is then called for each candidate in turn, starting with the highest priority items and working downwards. It can either print some text or not, and can either mark the item as "mentioned" or not: if it does, then the item won't appear subsequently in the locale description. If the activity does nothing, the item becomes "nondescript" and falls through into the final "You can also see…" paragraph, unless another rule mentions it in the mean time.

2. The default behaviour. Is provided by a sequence of seven rules:

(1) The "don't mention player's supporter in room descriptions rule" excludes anything the player is directly or indirectly standing on or, less frequently, in. The header of the room description has probably already said something like "Boudoir (on the four-poster bed)", so the player can't be unaware of this item.
(2) The "don't mention scenery in room descriptions rule" excludes scenery.
(3) The "don't mention undescribed items in room descriptions rule" excludes the player object. (It's redundant to say "You can also see yourself here.") At present nothing else in i7 is "undescribed" in this sense.
(4) The "set pronouns from items in room descriptions rule" adjusts the meaning of pronouns like IT and HER to pick up items mentioned. Thus if a room description ends "Mme Tourmalet glares at you.", then HER would be adjusted to mean Mme Tourmalet.
(5) The "offer items to writing a paragraph about rule" gives the "writing a paragraph about" activity a chance to intervene. We detect whether it does intervene or not by looking to see if it has printed any text.
(6) The "use initial appearance in room descriptions rule" prints the "initial appearance" property of an item which has never been handled as a paragraph, if it has one.
(7) The "describe what's on scenery supporters in room descriptions rule" is somewhat controversial. It prints text such as "On the mantelpiece is a piece of chalk." for items which, like the mantelpiece, are scenery mentioned - we assume - in the main room description. (It is assumed that scenery supporters make their contents more prominently visible than scenery containers, which we do not announce the contents of.)

3. Examples. If all that's required is to supply an interesting paragraph of room description about something then it's always better to use the "writing a paragraph about" activity, not this one. This activity should only be used when the mechanism itself needs to be adjusted.

(a) The following excludes doors from room descriptions:

For printing a locale paragraph about a door (called the item)
   (this is the don't mention doors in room descriptions rule):
   set the locale priority of the item to 0;
   continue the activity.

(It's usually a good idea to "continue the activity" at the end of rules for this activity, since usually they all need to take effect for a happy outcome to the process. Here it doesn't really matter, since we were trying to stop anything from happening about the door, but it doesn't do any harm either.)

(b) Here's how to abolish what may be the most contentious rule in the whole Standard Rules:

The describe what's on scenery supporters in room descriptions rule is not listed in any rulebook.

Examples

361.
Kiwi
Creating a raised supporter kind whose contents the player can't see or take from the ground.
362.
Copper River ★★★
Manipulating room descriptions so that only interesting items are mentioned, while objects that are present but not currently useful to the player are ignored.

WI §18.29 Deciding the scope of something

1. When it happens. "Scope" is a term of art in interactive fiction programming: it means the collection of things which can be interacted with at any given moment, which depends on who you are and where you are. Commands typed by the player will only be allowed to go forward into actions if the things they refer to are "in scope". Inform also needs to determine scope at other times, too: for instance, when deciding whether a rule conditional on being "in the presence of" something is valid. It is a bad idea to say anything during this activity.

2. The default behaviour. Is complicated: see the Inform Designer's Manual, 4th edition, page 227. Briefly, the scope for someone consists of everything in the same place as them, unless it is dark.

3. Examples. (a) We very rarely want to forbid the player to refer to things close at hand, but often want to allow references to distant ones. For instance, a mirage of something which is not present at all:

After deciding the scope of the player while the location is the Shrine:
   place the holy grail in scope.

Two different phrases enable us to place unusual items in scope:

place (object) in scope

This phrase should only be used in rules for the "deciding the scope of…" activity. It places the given object in scope, making it accessible to the player's commands, regardless of where it is in the model world. Examples:

place the distant volcano in scope;
place the lacquered box in scope, but not its contents;

Ordinarily if something is placed in scope, then so are its parts and (in the case of a supporter or a transparent or open container) its contents; using the "but not its contents" option we can place just the box itself in scope.

place the/-- contents of (object) in scope

This phrase should only be used in rules for the "deciding the scope of…" activity. It places the things inside or on top of the given object in scope, making them accessible to the player's commands, but it does nothing to place the object itself in scope. (It might of course be in scope anyway, and if it is then this phrase won't remove it.) Example:

place the contents of the lacquered box in scope;
place the contents of the Marbled Steps in scope;

Note that the object in question can be a room, as in this second example.

(b) Another useful device is to be able to see, but not touch, another room:

The Cloakroom is a room. "This is just a cloakroom, but through a vague, misty mirror-window you can make out the Beyond." After looking in the Cloakroom, say "In the mirror you can see [list of things in the Beyond]."
After deciding the scope of the player while the location is the Cloakroom: place the Beyond in scope.
The Beyond is a room. Johnny Depp is a man in the Beyond.

(This must, however, also be a mirage, as at time of writing Mr Depp is alive and as well as can be expected following the reviews of "Charlie and the Chocolate Factory".) Note that "place the Ballroom in scope" doesn't just allow the player to talk about the dancers, the chamber musicians and so forth, also allows, say, "EXAMINE BALLROOM". To get one but not the other, use "place the contents of the Ballroom in scope" or "place the Ballroom in scope, but not its contents".

(c) In darkness, the scope of someone is ordinarily restricted to his or her possessions (and body), but we can override that:

After deciding the scope of the player while in darkness: place the location in scope.

4. A note about actions. This activity takes place during the process of understanding the player's command, when the action that will take place is not fully known. So if the player types "TAKE SHOEBOX", this activity would happen when SHOEBOX is being examined for meaning. Inform knows the action it would be taking if the current line of command grammar were to be accepted, but it does not yet know to what objects that command would be applied. That means attaching a proviso like "… while taking a container" to a rule for this activity will cause the rule to have no effect – whereas "… while taking" would be fine.

Examples

363.
Peeled
Two different approaches to adjusting what the player can interact with, compared.
364.
Using "deciding the scope" to change the content of lists such as "the list of audible things which can be touched by the player".
365.
A portable magic telescope which allows the player to view items in another room of his choice.
366.
A simple open landscape where the player can see between rooms and will automatically move to touch things in distant rooms.
367.
Stately Gardens ★★★
An open landscape where the player can see landmarks in nearby areas, with somewhat more complex room descriptions than the previous example, and in which we also account for size differences between things seen at a distance.

WI §18.30 Clarifying the parser's choice of something

1. When it happens. When the player has typed an ambiguous noun reference, and Inform has made a decision about what was meant, and it matters what this decision is. (If the decision is between three identical gold coins, say, then it doesn't matter, and this activity does not take place.) There are a couple of limitations on this: the activity applies only to the first noun, and only if it's an object. So for a command like SELECT BLUE, where BLUE is a noun referring to a colour value, say, this activity isn't used. But the simple case where the activity does play a part is nevertheless very useful.

2. The default behaviour. Text in brackets such as "(the laminated mahogany box)" is printed, on its own line.

3. Examples. (a) In the following, asking to TAKE TOWER results in the parser choosing the souvenir model (because of the "does the player mean…" rule making the alternative unlikely), and then explaining itself by saying "(The little one, obviously.)" instead of "(the souvenir model Eiffel Tower)".

The Champs du Mars is a room. The great Eiffel Tower is here. "The great Tower stands high over you." The souvenir model Eiffel Tower is here. "Comparatively tiny is the souvenir version." The great Eiffel Tower is fixed in place. Does the player mean taking the great Eiffel Tower: it is very unlikely.
Rule for clarifying the parser's choice of the model tower: say "(The little one, obviously.)"

4. A note about actions. This activity takes place during the process of understanding the player's command, when the action that will take place is not fully known. So if the player types "TAKE SHOEBOX", this activity would happen when SHOEBOX is being examined for meaning. Inform knows that the action will be taking, but nothing else. That means attaching a proviso like "… while taking a container" to a rule for this activity will cause the rule to have no effect – whereas "… while taking" would be fine.

WI §18.31 Asking which do you mean

1. When it happens. When the player has typed an ambiguous noun reference, and Inform has not been able to decide what was meant.

2. The default behaviour. A question such as "Which do you mean, the laminated mahogany box or the boom box?" is printed. (This activity shapes the question: it is not responsible for parsing the answer. It would be very mysterious to write rules for this activity such that nothing is printed, because the player would then have no idea what to type.)

3. Examples. The question is harder to print than may first appear, since one must not simply list the options, but also take into account collections of plural objects ("Which do you mean, the gold-tipped pen or a gold coin?"). It is probably better not to try to rewrite this.

(a) But we can place notes before or after: here is a verbose explanation for beginners to IF.

Before asking which do you mean: say "Okay, so I'm going to have to ask a question now: you've typed something ambiguous, and I don't know which noun you're referring to."
After asking which do you mean: say "(Just type a word or two to give me more information.)"

(b) We can also use this activity as a context for other activities. For instance:

The Champs du Mars is a room. The great Eiffel Tower is here. "The great Tower stands high over you." The souvenir model Eiffel Tower is here. "Comparatively tiny is the souvenir version." The great Eiffel Tower is fixed in place. Understand "actual" as the great Tower.
Rule for printing the name of the great Tower while asking which do you mean: say "actual Tower". Rule for printing the name of the souvenir tower while asking which do you mean: say "souvenir".

causes TAKE TOWER (for instance) to produce a nice tidy question in reply: "Which do you mean, the actual Tower or the souvenir?"

4. A note about actions. This activity takes place during the process of understanding the player's command, when the action that will take place is not fully known. So if the player types "TAKE SHOEBOX", this activity would happen when SHOEBOX is being examined for meaning. Inform knows that the action will be taking, but nothing else. That means attaching a proviso like "… while taking a container" to a rule for this activity will cause the rule to have no effect – whereas "… while taking" would be fine.

Examples

368.
Apples
Prompting the player on how to disambiguate otherwise similar objects.
369.
Allowing the player to create models of anything in the game world; parsing the name "model [thing]" or even just "[thing]" to refer to these newly-created models; asking "which do you mean, the model [thing] or the actual [thing]" when there is ambiguity.
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?"

WI §18.32 Supplying a missing noun/second noun

1. When it happens. (Two different activities here, but identical except for applying to different nouns.) This happens when an Understand sentence fails to supply a noun for an action which requires one. For example, in the sentence 'Understand "seize" as taking.' – the "taking" action is incompletely specified, because it requires a noun, and there's no noun in the command to be understood.

Note that this is not what happens if it's the player who fails to supply the noun. That is, suppose the player types a half-finished command like TAKE, which can't be matched against (for example) 'Understand "take [things]" as taking.' because the player didn't name any thing(s). Typically a story will reply to such a command with a question asking for clarification, but sometimes it makes guesses about what was meant. The "supplying a missing noun" activity plays no part in this guesswork, and can't influence it: that's the task of the "does the player mean" rulebook.

Suppose we do have the first of these cases, then. "Supplying a missing noun" takes place to remedy the problem. It can either:

(i) Set a noun, printing text like "(presumably the black bag)" if it wants, in which case the action goes forward, though it is still subject to the full rules on accessibility exactly as any other action would be; or

(ii) Make no choice, in which case no action takes place and the player's command is rejected. If the activity printed nothing, Inform will produce a generic reply to the player that "You must supply a noun.".

2. The default behaviour. In the default grammar for Inform, only three such half-finished actions are ever Understood. One is "going" with no direction, for which this activity simply prints a refusal. The other two are the two undirected senses, "smelling" and "listening". In each case, the "supplying a missing noun" activity sets the noun to the current location: so, for instance, typing the bare command "listen" might generate the action "listening to the Shoreline".

3. Examples. (a) This is the definition Inform uses to make "listen" work as outlined above:

Rule for supplying a missing noun while listening (this is the ambient sound rule):
   now the noun is the location.

(b) It can be elegant to allow second nouns to be dropped with habitual actions, or where the choice is obvious:

Understand "unlock [something]" as unlocking it with.
Rule for supplying a missing second noun while unlocking:
   if the skeleton key is carried, now the second noun is the skeleton key;
   otherwise say "You will have to specify what to unlock [the noun] with."

Note that, in order for our activity to succeed, we do need to supply a grammar line allowing the player to try "unlocking it with" using only one noun. Otherwise, the command "unlock something" will still produce the question "What do you want to unlock the door with?"

Examples

Supplying missing nouns and second nouns for other characters besides the player.
Supplying a default direction for "go", so that "leave", "go", etc., are always interpreted as "out".

WI §18.33 Reading a command

1. When it happens. When reading a command from the keyboard.

2. The default behaviour. Print the prompt text; wait for the player to type something and press return. Reject an entirely blank line, and treat a command beginning "oops" as a correction to the previous one. This is a fairly complicated business, so it is probably best not to change the "for" rules for this activity: "before", and especially "after", are another matter. (Note, however, that if Inform does reject a blank line and ask for another then this all happens inside the "for" rules: no "after" occurs after the blank line, nor does a "before" happen before the second attempt by the player. It is all a single round of the activity, not two.)

3. Examples. (a) To lead absolute beginners in gently:

Before reading a command while the turn count is 1, say "(This is your chance to say what the protagonist should do next. After the '>', try typing 'take inventory'.)"

(b) The following responds politely but firmly if the player tries to type "please look", say, instead of just "look":

After reading a command:
   if the player's command includes "please":
      say "Please do not say please.";
      reject the player's command.

To explain. Fragments of what the player has typed are called snippets: "the player's command" is the entire thing. We can test if a snippet matches a given pattern like so:

if (snippet) matches (topic):

This condition is true if the given snippet exactly matches the specification. Example:

if the player's command matches "room [number]", ...

will be true if the command is ROOM 101, but not if it's EXPLORE ROOM 7.

if (snippet) does not match (topic):

This condition is true if the given snippet does not exactly match the specification.

if (snippet) includes (topic):

This condition is true if the given snippet includes words matching the specification, either at the beginning, in the middle, or at the end. Example:

if the player's command includes "room [number]", ...

will be true if the command is ROOM 101, EXPLORE ROOM 7, or ROOM 22 AHOY, but not if it's VISIT ROOM GAMMA 7.

if (snippet) does not include (topic):

This condition is true if the given snippet does not include any run of words which matches the specification.

Lastly, we took drastic action with another new phrase:

reject the player's command

This phrase should be used only in rules for the "reading a command" activity. It tells Inform not to bother analysing the text further, but to go back to the keyboard. (No time passes; no turn elapses; nothing happens in the simulated world.)

(c) An improved version takes commands like "please drop the coin" and strips "please" from them, but then allows them to proceed normally:

After reading a command:
   if the player's command includes "please":
      say "(Quelle politesse! But no need to say please.)";
      cut the matched text.

"Matched text" is a snippet containing the words which matched against the pattern in the most recent "includes" condition, so in this case it contains just the single word "please". Two phrases allow snippets to be altered:

replace (snippet) with (text)

This phrase should be used only in "after" rules for the "reading a command" activity; it replaces the snippet of command, usually the "matched text" found immediately before, with the given text. Example:

if the player's command includes "room [number]":
   replace the matched text with "office".
cut (snippet)

This phrase should be used only in "after" rules for the "reading a command" activity; it removes the snippet of command. Example:

if the player's command includes "or else":
   cut the matched text.

Note that "replace" and "cut" can only be used in "after reading a command" rules: not when an action has been chosen and has gone ahead into its rulebooks. Once the "reading a command" activity has finished, the command is final.

(d) To make the word "grab" an abbreviation for "take all":

After reading a command:
   if the player's command matches "grab", replace the player's command with "take all".

("Snippet" is actually a kind of value, so we could say "Ah, you typed '[the player's command]'!" or some such if we liked. But in practice only three snippets are likely to be useful: the two mentioned above, "player's command" and "matched text", and the "topic understood", used when matching the "[text]" token in command grammar.)

(e) Finally, we can make still more detailed alterations to the text of the command using the techniques presented in the Advanced Text chapter. For instance:

change the text of the player's command to (text)

This phrase should be used only in "after" rules for the "reading a command" activity; it replaces the current command text entirely. Example:

After reading a command:
   let T be "[the player's command]";
   replace the regular expression "\p" in T with "";
   change the text of the player's command to T.

This converts the player's command to text, which is then manipulated by searching for any punctuation mark and replacing it with blank text (that is, deleted), and then put back again as the new command.

Examples

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.
Creating additional compass directions between those that already exist (for instance, NNW) – and dealing with an awkwardness that arises when the player tries to type "north-northwest". The example demonstrates a way around the nine-character limit on parsed words.
376.
A character who responds to keywords in the player's instructions and remarks, even if there are other words included.

WI §18.34 Implicitly taking something

1. When it happens. When an action is tried which requires the actor (normally the player, of course) to be carrying something, but which is not in fact carried by that person. For instance, if the player types WEAR OVERCOAT in reference to a Moroccan overcoat currently draped over a chair.

2. The default behaviour. To print text such as "(first taking the Moroccan overcoat)" and then silently try taking the object in question (the overcoat). If the take succeeds, the silence means that nothing else is printed: if it fails, it will say why.

No matter what rules are written for this activity, it is impossible to use it to allow the action to go ahead even without the item. The activity allows us to change how, or if, an implicit take will happen, but not to change the consequences of failure. (To do that, we would need to say that "The carrying requirements rule does nothing", but this kind of unstitching of the action machinery needs to be done with caution.)

3. Examples. (a) Forbidding implicit takes for certain dangerous items. (This seems especially fair if taking such items might cause death: the player will not wish to be killed on the strength only of our guess as to what he might be intending to do.)

Rule for implicitly taking the curare:
   say "Ordinarily you'd pick up the curare in order to be able to do that, but this seems like a good moment for caution." instead.

(b) Changing the way the implicit action is reported for the player:

Rule for implicitly taking something (called target):
   try silently taking the target;
   if the player carries the target, say "You appropriate [the target] first, of course. [run paragraph on]"

(c) Combining implicit takes when the noun and second noun must both be carried:

Rule for implicitly taking the noun when the second noun is a thing and the second noun is not carried by the player:
   try silently taking the noun;
   try silently taking the second noun;
   say "(first taking both [the noun] and [the second noun])[line break]"

(d) Making another character reply amusingly:

Rule for implicitly taking something which is carried by the player when the person asked is Clark:
   say "'I don't see how I'm supposed to do that when you're holding [the noun],' remarks Clark sulkily." instead.

(e) Causing implicit takes which wouldn't otherwise happen. Suppose we have a photographing action, and there are very small flowers which can't conveniently be snapped without being first picked. We then want an implicit take to occur, even though we wouldn't want this for other sorts of photography. So:

Check an actor photographing a flower:
   if the actor is not carrying the noun:
      carry out the implicitly taking activity with the noun;
      if the actor is not carrying the noun, stop the action.

Note that if the activity doesn't succeed in taking the item, it's expected to print some text explaining this, which is why we don't need to say anything further.

Examples

Making implicit takes add a minute to the clock, just as though the player had typed TAKE THING explicitly.
378.
Providing a pizza buffet from which the player can take as many pieces as he wants.
379.
Lollipop Guild ★★★
Overriding the rules to allow the player to show something to another character without first taking it.

WI §18.35 Printing a parser error

1. When it happens. The parser is the part of the run-time software, included in all works produced by Inform, which tries to match the player's command against the grammar provided by the work. When it is unable to make a valid match, the parser prints an error to the player: for instance,

> BIFURCATE TREE
That's not a verb I recognise.

There are more than twenty possible messages. The one which the parser wants to say is stored in the variable "latest parser error", which has the convenient kind "command parser error". This has the following possible values:

didn't understand error
only understood as far as error
didn't understand that number error
can't see any such thing error
said too little error
aren't holding that error
can't use multiple objects error
can only use multiple objects error
not sure what it refers to error
excepted something not included error
can only do that to something animate error
not a verb I recognise error
not something you need to refer to error
can't see it at the moment error
didn't understand the way that finished error
not enough of those available error
nothing to do error
referred to a determination of scope error
I beg your pardon error
noun did not make sense in that context error
can't again the addressee error
comma can't begin error
can't see whom to talk to error
can't talk to inanimate things error
didn't understand addressee's last name error

2. The default behaviour. Prints the message in question.

3. Examples. (a) Perhaps for newcomers:

After printing a parser error:
   say "If you are new to interactive fiction, you may like to try typing HELP."

(b) Or to give the parser a certain amount of character:

Rule for printing a parser error when the latest parser error is the I beg your pardon error:
   say "What's that? Speak up, speak up." instead.
Rule for printing a parser error:
   say "That's a rum thing to say, and no mistake." instead.

(c) This can be helpful for seeing what's going on:

Rule for printing a parser error:
   say "The [latest parser error] happened.";
   continue the activity.

Examples

380.
WXPQ
Creating a more sensible parser error than "that noun did not make sense in this context".
381.
Xot ★★★
Storing an invalid command to be repeated as text later in the game.

WI §18.36 Deciding whether all includes

1. When it happens. When parsing a command such as "take all", where the player uses "all" to signify everything within reach.

2. The default behaviour. The actual method used is complicated, as "all" is not as simple as it seems – "take all" would not include the player's own body, for instance, or the crescent moon. The point of this activity is to allow the normal method to be changed for given objects, or given kinds of object.

3. Examples. (a) Removing scenery from "all" (but see (4) below):

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

The phrases "it does" and "it does not" make a decision.

(b) Ensuring that a given thing, which might otherwise be excluded, is included:

Rule for deciding whether all includes the oval roof: it does.

4. The Standard Rules already uses this. Note that the Standard Rules already stocks this activity with several rules:

exclude scenery from take all rule
exclude people from take all rule
exclude fixed in place things from take all rule

5. A note about actions. This activity takes place during the process of understanding the player's command, when the action that will take place is not fully known. So if the player types "TAKE SHOEBOX", this activity would happen when SHOEBOX is being examined for meaning. Inform knows that the action will be taking, but nothing else. That means attaching a proviso like "… while taking a container" to a rule for this activity will cause the rule to have no effect – whereas "… while taking" would be fine.

WI §18.37 Printing the banner text

1. When it happens. The banner is the bibliographic masthead text, which typically looks something like this:

Relations
An Interactive Fiction by Emily Short
Release 1 / Serial number 050630 / Inform 7 build 2U98 (i6/v6.30 lib 6/10N) SD

(The serial and build numbers are those applying when the story file was last made: these ones are from the mid-2000s.) The banner is printed at the start of play, and when the player types "version" at the command line, and when say "[banner text]" occurs.

say "[the/-- banner text]"

This text substitution expands to the banner text giving bibliographic details of the current story file, rather like the opening credits of a movie, or the title page of a book.

2. The default behaviour. Prints the text above, giving the title, the headline, the author, the release number, the date of compilation (that's the serial number: YYMMDD), and version numbers of the Inform components used to put the story together.

3. Examples. (a) Adding a line to the banner:

After printing the banner text, say "DRM authentication code: 13S-451-2034u75y65u%%a1248."

(b) Simplifying the banner:

Rule for printing the banner text: say "Welcome." instead.

Example

382.
Delaying the banner for later.

WI §18.38 Printing the player's obituary

1. When it happens. The obituary is the text "*** You have died ***" or similar, sometimes followed by a final score, if the appropriate use option ("Use scoring.") is in force.

2. The default behaviour. Printing the aforementioned text, then the final score, and reducing the status line to a largely blank state.

3. Examples. Here's one way to add to the verdict of history:

After printing the player's obituary: say "And you visited [number of visited rooms] place[s]."

Examples

Completely replacing the endgame text and stopping the game without giving the player a chance to restart or restore.
384.
Not mentioning UNDO in the final set of options.
385.
Adding a feature to the final question after victory, so that the player can choose to reveal notes about items in the game.

WI §18.39 Amusing a victorious player

1. When it happens. When the player chooses "AMUSING" from the short menu of choices after a story has been won. Traditionally, this is where the author gets to point out quirky by-ways of the story, or make some final acknowledgements, or simply salute the player's perseverance. Note that the AMUSING option is only offered when the story has ended finally, and that it is only offered if there is at least one rule present in the "for amusing a victorious player" rulebook.

2. The default behaviour. None. The "for amusing a victorious player" rulebook is empty by default, and no amusement is available.

3. Examples. The format would be like so:

Rule for amusing a victorious player: say "Hmm. You're easily amused."

Example

386.
Xerxes ★★
Offering the player a menu of things to read after winning the game.

WI §18.40 Starting the virtual machine

1. When it happens. This activity is provided solely as a "hook" for any low-level tasks which need to be performed when the virtual computer which runs Inform story files is starting up. This happens much earlier than "when play begins" rules, and should be used only as a last resort.

It should be remembered that Inform can produce story files for several different virtual computers. On some of these, it will not be safe to print any text during this activity, as the windows which would display such text do not yet exist.

2. The default behaviour. None.

3. Examples. No detailed examples will be given here, but the activity might be used (for instance) to set styles for the Glulx windows shortly to be brought into existence.

Example

387.
Emptying the status line during the first screen of the game.