Consolidated Multiple Actions by John Clemens


Section: Basic behavior

Normally, when the player issues a command such as "take knife and fork" or "drop all", Inform prints a series of messages, one for each object, preceded by the object name. This often results of a series of default messages, which we might rather see grouped into a single message. Consolidated Multiple Actions combines the reports of such multiple actions into a single message when the actions have standard results. The default behavior requires no additional work beyond including the extension.

Before printing any reports, the actions are tested and divided into three categories. "Standard" action results are those which succeed and print nothing when run silently, i.e., they print text only in report rules (parenthetical and bracketed output, such as "(first taking the...)" and debugging messages are ignored here). "Failed" action results are those which fail. "Noteworthy" action results are ones which either succeed but print text other than in a report rule (e.g., they use an "after" rule), or are explicitly marked as noteworthy. This can override standard and failed results. An action result can be marked as noteworthy by using the phrase:

indicate noteworthy consolidation

This can be used anywhere in the rulebooks for the action except the "report" rules (which are not consulted during testing).

After the action results are determined, a single report message is printed for all of the objects which had standard results. Then the failed actions are run sequentially, with the usual reporting, followed by the noteworthy actions. By default, the object name is printed before failed action results (as in the ordinary behavior), but is omitted before noteworthy action results.

There is one use option: "Use strict action consolidation checking" will require that nothing at all be printed (not even parenthetical messages) in order for an action result to be considered standard. Finally, when using the "actions" debugging commands, messages will be printed showing the results of the consolidation tests.

Section: New rules and rulebooks

The extension adds a new rulebook, the multiple action processing rules, which is run after Inform has determined that there are multiple objects but before the action is run on them. Actions can take multiple objects if they have grammar lines including the "[things]" token; the standard library allows this for the actions of taking, dropping, removing from, putting on, and inserting into. This rulebook contains one rule, "the consolidate multiple actions rule", which consolidates and reports the standard action results as described above. Other rules may be added to this rulebook for additional processing of multiple objects (such as reordering the multiple object list). After this rulebook finishes, the action is applied to the objects remaining in the multiple objects list in the normal fashion.

The consolidate multiple objects rule creates two lists of objects: "the consolidated objects list" which contains those objects whose reports have been consolidated, and "the noteworthy objects list" which contains those objects whose action results are noteworthy. These may be consulted for use in further customization.

The results of an action are categorized by a second rulebook, the action consolidation results rules. This rulebook has three possible outcomes: standard, failed, and noteworthy. New rules may be added here to change the default determination of which actions are standard.

Section: New activities

The extension introduces three new activities:

* Reporting consolidated actions: This activity prints the action report message for the consolidated objects. Any action which can take multiple objects needs to have a reporting consolidated actions rule or nothing will be printed for standard results. Rules are provided for the built-in actions which allow multiple nouns. Actions by NPCs are also consolidated and need reporting rules; these should have the preamble:

Rule for reporting consolidated actions when asking someone to try (the action)

since multiple actions by an NPC will only be generated in response to the player issuing a command to the NPC.

The text substitution "[consolidated objects]" may be used in such report rules to list the objects whose reports are being consolidated; this will invoke the "printing consolidated objects" activity.

We should be careful not to write a rule like "Rule for reporting consolidated actions when taking the plate", since only the last object in the consolidated objects list will match here. Instead, we should phrase the rule as "Rule for reporting consolidated actions when taking and the plate is listed in the consolidated objects list".

* Printing consolidated objects: This activity prints the actual list of the objects whose reports are consolidated. The default behavior of this activity makes use of Inform's list writing functions so that the "grouping together" activity may be applied to it. The following phrase may be used to print out a list using these abilities:

list the elements of (L - a list of objects)... (options);

This phrase can take all of the same phrase options as "list the contents of" (as well as the option "with capitalized first article"). For convenience, the most common two uses of this phrase can be invoked with:

say the grouped (L - a list of objects)
say The capitalized grouped (L - a list of objects)

* Announcing a multiple occurrence of something: This activity prints the message which precedes an action for an object which has not been consolidated. By default, this prints the objects name followed by a colon for failed actions, and nothing for noteworthy actions. The variable

the number of multiple actions so far this turn

can be used to tell how many such actions have occurred in order to vary such messages.

Section: Handling the pronoun "them"

After printing the consolidated objects, these objects are stored in a list called "the stored consolidated objects" so that they may be referred to in input using the pronoun "them". This pronoun is also used by Inform to refer to plural-named objects, and so will be updated in the normal fashion (in which case it will no longer refer to the last list of consolidated objects). The usual testing command "pronouns" can be used to determine what the current interpretation is. It may be desirable to try to update this list when printing a list of objects in other places, but since there is no uniformly desirable behavior this task is left to authors. This may be done using the phrase:

set pronouns from (L - a list of objects)

and we can test whether "them" currently refers to a list of objects with:

if them refers to a list...

This feature is somewhat experimental, and authors who wish to disable it can do so by adding the lines:

The update the pronoun them to consolidated objects rule is not listed in any rulebook.
The replace them by stored consolidated objects rule is not listed in any rulebook.

Section: Change Log

Version 3 was updated for compatibility with 6L38 by Emily Short, and the examples somewhat revised to demonstrate adaptive text behavior.

Example: * Clutter - Illustrating the basic functionality, grouping of objects, and some nicer output for non-standard results.

We can use the grouping together activity when printing consolidated objects just as we can when listing contents, as illustrated with the Scrabble pieces below. We can also add a new rule for announcing a multiple occurrence to vary the reporting of failed and noteworthy results.

Notice also the difference between a Report rule and an After rule for taking. The Report rule for the glass ("You carefully pick up the glass.") fires only when it's taken by itself, whereas thanks to its After rule, the cat will always be reported as struggling no matter how many objects we're picking up.

"Clutter"

Include Consolidated Multiple Actions by John Clemens.

The Cluttered Office is a room.

The trash can is an open fixed in place container in the cluttered office.
A desk is here. It is fixed in place. A glass and a plate are on the desk.
Report taking the glass: say "[We] carefully [pick] up the glass."; rule succeeds.
A cat is here. After taking the cat, say "The cat [struggle], but [we] [manage] to pick it up."
The hot potato is here. Instead of taking the hot potato: indicate noteworthy consolidation; say "[We] [burn] [our] hand on the potato, and [let] go immediately."

Some flowers are here.

Bob is a man in the cluttered office. Persuasion rule: persuasion succeeds.

A book is a kind of thing. 5 books are in the cluttered office.

A Scrabble piece is a kind of thing. The X, the Y and the Z are Scrabble pieces in the cluttered office. Understand "tile" as a Scrabble piece. Understand "tiles" as the plural of Scrabble piece.
Before printing consolidated objects: group Scrabble pieces together.
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 while not printing consolidated objects, say " from a Scrabble set".

To fail is a verb. To struggle is a verb. To manage is a verb. To burn is a verb. To let is a verb.

Rule for announcing a multiple occurrence of something (called object in question) when taking or removing:
     if the number of multiple actions so far this turn is greater than 1, say conditional paragraph break;
     if the object in question is not listed in the noteworthy objects list:
         if number of multiple actions so far this turn is:
             -- 1: say "[We] [are] unable to take";
             -- 2: say "[We] further [cannot] take";
             -- 3: say "[We] also [fail] to obtain";
             -- otherwise: say "And";
         say " [the object in question]: [run paragraph on]".

Test me with "take all / drop all / Bob, take glass and plate / Bob, put them on the desk / remove all from desk/ put them in trash can / take glass / drop glass / take glass and plate / drop them / take flowers / drop them".

Example: ** Orderly Announcement - Another way of naming collections of objects when reporting actions, to allow naming them in input as well.

We can use the "grouping together" activity to rename a collection when reporting consolidated actions, but we may also want to recognize the collection names in input. For this we can use a somewhat more complicated approach; the technique used here is not very sophisticated and will only recognize the exact name of the collection.

"Orderly Announcement"

Include Consolidated Multiple Actions by John Clemens.

The Kitchen is a room.

A utensil is a kind of thing. The knife, the fork, and the spoon are utensils in the kitchen.

A glove is a kind of thing. A glove is always wearable. Understand "glove" as a glove. The left glove and the right glove are gloves in the kitchen.

Before listing contents:
     group gloves together;
     group utensils together.

Before grouping together gloves:
     say "a pair of gloves (";
After grouping together gloves:
     say ")".

Before grouping together utensils:
     if the listing group size is 3:
         say "a place setting (";
     else:
         say "some utensils (".
After grouping together utensils:
     say ")".

A collection is a kind of thing. A collection has a list of objects called components.

The pair of gloves is a collection. The components of the pair of gloves is { left glove, right glove }.

The place setting is a collection. The components of the place setting is { knife, fork, spoon }.

To decide if (L1 - list of objects) is a subset of (L2 - list of objects):
     repeat with x running through L1:
         if x is not listed in L2, no;
     yes.

Before printing consolidated objects:
     repeat with group running through collections:
         let L be the components of group;
         if L is a subset of the consolidated objects list:
             repeat with x running through L:
                 remove x from the consolidated objects list, if present;
             add group to the consolidated objects list.

After reading a command:
     repeat with group running through collections:
         let N be text;
         let Y be text;
         let N be the player's command;
         let Y be "[components of group]";
         while N matches the regular expression "[group]":
             replace the regular expression "(.*)[group](.*)" in N with "\1[Y]\2";
         change the text of the player's command to N.

Test me with "take all / drop place setting / take knife and fork / drop all".

Example: *** Burn, Baby, Burn - Adding a new action which allows multiple nouns.

We can add a new action which allows multiple nouns (or extend an already existing action) using the "[things]" token. In addition to the usual check, carry out, and report rules, we also need to add a rule for reporting consolidated actions for the new action (and a rule for reporting actions by others, if NPCs can be commanded to perform the action). Here we add a "burning it with" action.

Note that we would not want to use the strict action consolidation checking option here because of a possible "(first taking the lighter)" message.

Since the action typically fails in one way, we can also add a new multiple action processing rule to consolidate the failed action reports as well.

And just for fun, we vary the printing of the consolidated objects list a bit.

"Burn, Baby, Burn"

Include Consolidated Multiple Actions by John Clemens.

The Abandoned Warehouse is a room.

The player carries a lighter.

Flammability is a kind of value. The flammabilities are flammable and non-flammable. A thing has a flammability. The flammability of a thing is usually non-flammable. Understand the flammability property as describing a thing.

A book, a newspaper, some dried flowers, and a bra are flammable things in the warehouse.
A safe, a bottle of water, and a fire-resistant flag are here.

Understand the command "burn" as something new.

To refuse is a verb. To burst is a verb.

Understand "burn [things] with [something]" or "burn [things]" as burning it with. Burning it with is an action applying to one thing and one carried thing.
Rule for supplying a missing second noun while burning with: now the second noun is the lighter.
Check burning the player with: instead say "[We] [are not] eager to hurt [ourselves]."
Check burning lighter with: instead say "The lighter [are] designed to burn fluid without the rest of the casing being consumed."
Check burning it with: if the second noun is not the lighter, instead say "[The second noun] [are] not a suitable fire-starter."
Check burning it with: if the noun is not flammable, instead say "[The noun] [refuse] to catch fire."
Carry out burning it with: remove the noun from play.
Report burning it with: say "[The noun] [burst] into flames and [are] soon gone."

Rule for reporting consolidated actions when burning with: say "[The capitalized grouped consolidated objects list] burst[s] into flames and [are] soon gone."

A multiple action processing rule for burning with (this is the consolidate inflammables rule):
     let L be the multiple object list;
     if the number of entries of L is at least 1:
         say "[The capitalized grouped L] [refuse] to catch fire.";
         truncate L to 0 entries;
         alter the multiple object list to L.

The consolidate inflammables rule is listed after the consolidate multiple actions rule in the multiple action processing rulebook.

Rule for printing consolidated objects when not burning with:
     if the number of entries of the consolidated objects list is at least 3, say "a bunch of things[if the lighter is listed in the consolidated objects list], including [the lighter]";
     otherwise say the grouped consolidated objects list.

Test me with "take all / i / drop all / burn me with lighter / burn lighter with lighter / burn newspaper / burn flowers with lighter / burn everything!".