Source: http://inform-fiction.org/manual/html/s6.html
Timestamp: 2019-04-21 04:31:24+00:00

Document:
[Greek is] a language obsessed with action, and with the joy of seeing action multiply from action, action marching relentlessly ahead and with yet more actions filing in from either side to fall into neat step at the rear, in a long straight rank of cause and effect, to what will be inevitable, the only possible end.
are all examples. Here the actual actions are Inv (inventory), Take and Insert. An action has none, one or two objects supplied with it (or, in a few special cases, some numerical information rather than objects). It also has an “actor”, the person who is to perform the action, usually the player. Most actions are triggered off by the game's parser, whose job can be summed up as reducing the player's keyboard commands to actions: “take my hat off”, “remove bowler” or “togli il cappello” (if in an Italian game) might all cause the same action. Some keyboard commands, like “drop all”, cause the parser to fire off whole sequences of actions: others, like “empty the sack into the umbrella stand”, cause only a single action but one which may trigger off an avalanche of other actions as it takes place.
An action is only an attempt to do something: it may not succeed. Firstly, a before rule might interfere, as we have seen already. Secondly, the action might not even be very sensible. The parser will happily generate the action Eat iron_girder if the player asked to do so in good English. In this case, even if no before rule interferes, the normal game rules will ensure that the girder is not consumed.
The toffee apple sticks to your hand!
which is at least consistent.
The statement <Examine self> causes the action Examine low_mist to be triggered off immediately, after which whatever was going on at the time resumes. In this case, the action Smell low_mist resumes, but since we immediately return true the action is stopped dead.
If a player types “search steps”, the parser will produce the action Search steps and this rule will come into play: it will generate the action Enter steps instead, and return true to stop the original Search action from going any further. The net effect is that one action has been diverted into another.
tests to see if the current action is a Look.
▲ Why have ## at all, why not just write Look? Partly because this way the reader of the source code can see at a glance that an action type is being referred to, but also because the name might be used for something else. For instance there's a variable called score (holding the current game score), quite different from the action type ##Score.
▲▲ For a few actions, the ‘noun’ (or the ‘second noun’) is actually a number (for instance, “set timer to 20” would probably end up with noun being timer and second being 20). Occasionally one needs to be sure of the difference, e.g., to tell if second is holding a number or an object. It's then useful to know that there are two more primitive variables, inp1 and inp2, parallel to noun and second and usually equal to them – but equal to 1 to indicate “some numerical value, not an object”.
The library supports about 120 different actions and most large games will add some more of their own. The full list, given in Table 6, is initially daunting, but for any given object most of the actions are irrelevant. For instance, if you only want to prevent an object from entering the player's possession, you need only block the Take action, unless the object is initially in something or on something, in which case you need to block Remove as well. In the author's game ‘Curses’, one exceptional object (Austin, the cat) contains rules concerning 15 different actions, but the average is more like two or three action-rules per object.
Group 1 contains ‘meta’ actions for controlling the game, like Score and Save, which are treated quite differently from other actions as they do not happen in the “model world”.
Actions in group 2 normally do something to change the state of the model world, or else to print important information about it. Take (“pick up”) and Inv (“inventory”) are examples of each. Such actions will affect any object which doesn't block them with a before rule.
Finally, group 3 actions are the ones which normally do nothing but print a polite refusal, like Pull (“it is fixed in place”), or a bland response, like Listen (“you hear nothing unexpected”). Such actions will never affect any object which doesn't positively react with a before rule.
▲ Some of the group 2 actions can be ignored by the programmer because they are really only keyboard shorthands for the player. For example, <Empty rucksack table> means “empty the contents of the rucksack onto the table” and is automatically broken down into a stream of actions like <Remove fish rucksack> and <PutOn fish table>. You needn't write rules concerning Empty, only Remove and PutOn.
▲▲ Most of the library's group 2 actions are able to “run silently”. This means that if the variable keep_silent is set to true, then the actions print nothing in the event of success. The group 2 actions which can't run silently are exactly those ones whose successful operation does nothing but print: Wait, Inv, Look, Examine, Search.
Now add “(first unlocking the door with…)”, automatically trying to unlock it using either a key already known to work, or failing that, any key carried by the player which hasn't been tried in the lock before.
Such an imaginary action – usually, as in this case, a perfectly sensible action seen from the point of view of the second object involved, rather than the first – is sometimes called a “fake action”. Two things about it are fake: there's no grammar that produces ThrownAt, and there's no routine called ThrownAtSub. The important fake actions are ThrownAt, Receive and LetGo, the latter two being used for containers: see §12.
▲ If you really need to, you can declare a new fake action with the directive Fake_action ‹Action-name›;. You can then cause this action with < and > as usual.
ThrownAt would be unnecessary if Inform had an idea of before and after routines which an object could provide if it were the second noun of an action. How might this be implemented?
▲▲ Very occasionally, in the darker recesses of §18 for instance, you want “fake fake actions”, actions which are only halfway faked in that they still have action routines. Actually, these are perfectly genuine actions, but with the parser's grammar jinxed so that they can never be produced whatever the player types.
placed after the inclusion of the Grammar file. The word “blorple” can now be used as a verb. It can't take any nouns, so the parser will complain if the player types “blorple daisy”.
Object -> -> camera "wet-plate camera"
(This is going to be inside a packing case which is inside the Forest, hence the two arrows ->.) And now the action subroutine. The sodium lamp referred to will be constructed in §14.
This matches input like “photograph statuette”, because the grammar token noun tells the parser to expect the name of a visible object. See §30 and §31 for much more on grammar.
▲ To make a Group 1 action, define the verb as meta (see §30).
‘Before’, for group 2 and 3 actions. An opportunity for your code to interfere with or block altogether what might soon happen.
‘During’, for all actions. The library takes control and decides if the action makes sense according to its normal world model: for example, only an edible object may be eaten; only an object in the player's possession can be thrown at somebody, and so on. If the action is impossible, a complaint is printed and that's all. Otherwise the action is now carried out.
‘After’, for group 2 actions. An opportunity for your code to react to what has happened, after it has happened but before any text announcing it has been printed. If it chooses, your code can print and cause an entirely different outcome. If your code doesn't interfere, the library reports back to the player (with such choice phrases as “Dropped.”).
▲ Group 1 actions, like Score, have no ‘Before’ or ‘After’ stages: you can't (easily) stop them from taking place. They aren't happening in the game's world, but in the player's.
(1a) The GamePreRoutine is called, if you have written one. If it returns true, nothing else happens and the action is stopped.
(1b) The orders property of the player is called on the same terms. For more details, see §18.
(1c) And the react_before of every object in scope, which roughly means ‘in the vicinity’. For more details, see §32.
(1d) And the before of the current room.
(1e) If the action has a first noun, its before is called on the same terms.
▲ The library processes the ‘During’ stage by calling the action's subroutine: for instance, by calling TakeSub.
▲ The ‘After’ stage only applies to Group 2 actions, as all Group 3 actions have been wound up with a complaint or a bland response at the ‘During’ stage. During ‘After’ the sequence is as follows: (3a) react_after rules for every object in scope (including the player object); (3b) the room's after; (3c) the first noun's after and (3d) finally GamePostRoutine.
▲▲ To some extent you can even meddle with the ‘During’ stage, and thus even interfere with Group 1 actions, by unscrupulous use of the LibraryMessages system. See §25.
As mentioned above, the parser can generate decidedly odd actions, such as Insert camel eye_of_needle. The parser's policy is to allow any action which the player has clearly asked for at the keyboard, and it never uses knowledge about the current game position except to resolve ambiguities. For instance, “take house” in the presence of the Sydney Opera House and also a souvenir model of the same will be resolved in favour of the model. But if there is no model to cloud the issue, the parser will cheerfully generate Take Sydney_Opera_House.
Actions are only checked for sensibleness after the before stage. In many ways this is a good thing, because in adventure games the very unlikely is sometimes correct. But sometimes it needs to be remembered when writing before rules. Suppose a before rule intercepts the action of putting the mushroom in the crate, and exciting things happen as a result. Now even if the mushroom is, say, sealed up inside a glass jar, the parser will still generate the action Insert mushroom crate, and the before rule will still cut in, because the impossibility of the action hasn't yet been realised.
The upshot of this is that the exciting happening should be written not as a before but as an after rule, when it's known that the attempt to put the mushroom in the crate has already succeeded.
ObjectIsUntouchable can also be a convenience when writing action subroutines for new actions of your own.
▲▲ If you set take_flag, then a further restriction will be imposed: the item must not belong to something or someone already: specifically, it must not be in the possession of an animate or a transparent object that isn't a container or supporter. For instance, the off button on a television set can certainly be touched, but if take_flag is true, then ObjectIsUntouchable will print up “That seems to be a part of the television set.” and return true to report an obstacle.
In a game compiled with the -D for “Debugging” switch set, the “actions” verb will result in trace information being printed each time any action is generated. Try putting many things into a rucksack and asking to “empty” it for an extravagant list. •Diverted actions (using << and >>) are commonplace. They're used in about 20 places in ‘Advent’: a good example is the way “take water” is translated into a Fill bottle action. •L. Ross Raszewski's library extension "yesno.h" makes an interesting use of react_before to handle semi-rhetorical questions. For instance, suppose the player types “eat whale”, an absurd command to which the game replies “You can fit a blue whale in your mouth?” Should the player take this as a literal question and type “yes”, the designer might want to be able to reply “Oh. I should never have let you go through all those doors.” How might this be done? The trick is that, when the game's first reply is made, an invisible object is moved into play which does nothing except to react to a Yes action by making the second reply.

References: §12
 §18
 §14
 §30
 §31
 §30
 §18
 §32
 §25