~ubuntu-branches/ubuntu/vivid/inform/vivid

« back to all changes in this revision

Viewing changes to inform-6.31.1/manual/s6.html

  • Committer: Bazaar Package Importer
  • Author(s): Jan Christoph Nordholz
  • Date: 2008-05-26 22:09:44 UTC
  • mfrom: (2.1.1 lenny)
  • Revision ID: james.westby@ubuntu.com-20080526220944-ba7phz0d1k4vo7wx
Tags: 6.31.1+dfsg-1
* Remove a considerable number of files from the package
  due to unacceptable licensing terms.
* Repair library symlinks.

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 
2
<html>
 
3
<head>
 
4
<title>DM4 &#167;6: Actions and reactions</title>
 
5
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
 
6
<link rel="stylesheet" type="text/css" href="dm4.css">
 
7
</head>
 
8
<body>
 
9
<p class="navbar">
 
10
 <a href="index.html">home</a> /
 
11
 <a href="contents.html">contents</a> /
 
12
 <a href="ch2.html" title="Chapter II: Introduction to Designing">chapter II</a> /
 
13
 <a href="s5.html" title="&#167;5: Introducing messages and classes">prev</a> /
 
14
 <a href="s7.html" title="&#167;7: Infix and the debugging verbs">next</a> /
 
15
 <a href="dm4index.html">index</a>
 
16
</p>
 
17
<div class="page">
 
18
<a id="p97" name="p97"></a>
 
19
<h2>&#167;6 &nbsp; Actions and reactions</h2>
 
20
 
 
21
<blockquote>Only the actions of the just<br>
 
22
Smell sweet and blossom in their dust.<br>
 
23
&#8212; James Shirley (1594&#8211;1666),<br>
 
24
<span style="color:white">&#8212;</span> <i>The Contention of Ajax and Ulysses</i>
 
25
</blockquote>
 
26
 
 
27
<blockquote>[Greek is] a language obsessed with action, and with 
 
28
the joy of seeing action multiply from action, action marching 
 
29
relentlessly ahead and with yet more actions filing in from either 
 
30
side to fall into neat step at the rear, in a long straight rank 
 
31
of cause and effect, to what will be inevitable, the only possible end.<br>
 
32
&#8212; Donna Tartt, <i>The Secret History</i></blockquote>
 
33
 
 
34
<p class="normal"><span class="atleft"><img src="dm4-097_1.jpg" alt=""></span>
 
35
Inform is a language obsessed with actions. An
 
36
&#8216;action&#8217; is an attempt to perform one simple task: for 
 
37
instance,</p>
 
38
 
 
39
<p class="lynxonly"></p>
 
40
<pre class="code">Inv    Take sword    Insert gold_coin cloth_bag</pre>
 
41
 
 
42
<p class="normal">are all examples. Here the actual actions are 
 
43
<code>Inv</code> (inventory), <code>Take</code> and <code>Insert</code>.
 
44
An action has none, one or two objects supplied with it (or, in a few 
 
45
special cases, some numerical information rather than objects). It also 
 
46
has an &#8220;actor&#8221;, the person who is to perform the action, usually 
 
47
the player. Most actions are triggered off by the game's parser, whose 
 
48
job can be summed up as reducing the player's keyboard commands to 
 
49
actions: &#8220;take my hat off&#8221;, &#8220;remove bowler&#8221; 
 
50
or &#8220;togli il cappello&#8221; (if in an Italian game) might all 
 
51
cause the same action. Some keyboard commands, like &#8220;drop 
 
52
all&#8221;, cause the parser to fire off whole sequences of actions: 
 
53
others, like &#8220;empty the sack into the umbrella stand&#8221;, 
 
54
cause only a single action but one which may trigger off an avalanche
 
55
of other actions as it takes place.</p>
 
56
 
 
57
<p class="indent">An action is only an attempt to do something: it may 
 
58
not succeed. Firstly, a <code>before</code> rule might interfere, 
 
59
as we have seen already. Secondly, the action might not even be very 
 
60
sensible. The parser will happily generate the action <code>Eat 
 
61
iron_girder</code> if the player asked to do so in good English. In 
 
62
this case, even if no <code>before</code> rule interferes, the normal 
 
63
game rules will ensure that the girder is not consumed.</p>
 
64
 
 
65
<p class="indent">Actions can also be generated by your own code, and 
 
66
this perfectly simulates the effect of a player typing something. For 
 
67
example, generating 
 
68
<a id="p98" name="p98"></a>
 
69
a <code>Look</code> action makes the game produce 
 
70
a room description as if the player had typed &#8220;look&#8221;. 
 
71
More subtly, suppose the air in the Pepper Room causes the player to 
 
72
sneeze each turn and drop something at random. This could be programmed 
 
73
directly, with objects being moved onto the floor by explicit move 
 
74
statements. But then suppose the game also contains a toffee apple,
 
75
which sticks to the player's hands. Suddenly the toffee apple problem 
 
76
has an unintended solution. So rather than moving the objects directly 
 
77
to the floor, the game should generate <code>Drop</code> actions, 
 
78
allowing the game's rules to be applied. The result might read:</p>
 
79
 
 
80
<p class="output">You sneeze convulsively, and lose your grip on 
 
81
the toffee apple&#8230;<br>The toffee apple sticks to your hand!</p>
 
82
 
 
83
<p class="normal">which is at least consistent.</p>
 
84
 
 
85
<p class="indent">As an example of causing actions, an odorous <code>low_mist</code> 
 
86
will soon settle over &#8216;Ruins&#8217;. It will have the description 
 
87
&#8220;The mist carries an aroma reminisicent of tortilla.&#8221; 
 
88
The alert player who reads this will immediately type &#8220;smell 
 
89
mist&#8221;, and we want to provide a better response than the game's
 
90
stock reply &#8220;You smell nothing unexpected.&#8221; An 
 
91
economical way of doing this is to somehow deflect the action <code>Smell 
 
92
low_mist</code> into the action <code>Examine low_mist</code> 
 
93
instead, so that the &#8220;aroma of tortilla&#8221; message is printed 
 
94
in this case too. Here is a suitable <code>before</code> rule to 
 
95
do that:</p>
 
96
 
 
97
<p class="lynxonly"></p>
 
98
<pre class="code">Smell: &lt;Examine self&gt;; rtrue;</pre>
 
99
 
 
100
<p class="normal">The statement &lt;Examine self&gt; causes the 
 
101
action <code>Examine low_mist</code> to be triggered off immediately, 
 
102
after which whatever was going on at the time resumes. In this case, 
 
103
the action <code>Smell low_mist</code> resumes, but since we
 
104
immediately return <code>true</code> the action is stopped dead.</p>
 
105
 
 
106
<p class="indent">Causing an action and then returning <code>true</code> is 
 
107
so useful that it has an abbreviation, putting the action in double 
 
108
angle-brackets. For example, the following could be added to &#8216;Ruins&#8217; 
 
109
if the designer wanted to make the stone-cut steps more enticing:</p>
 
110
 
 
111
<p class="lynxonly"></p>
 
112
<pre class="code">
 
113
before [;
 
114
    Search: &lt;&lt;Enter self&gt;&gt;;
 
115
],
 
116
</pre>
 
117
 
 
118
<p class="normal">If a player types &#8220;search steps&#8221;, the 
 
119
parser will produce the action <code>Search steps</code> and 
 
120
this rule will come into play: it will generate the action <code>Enter 
 
121
steps</code> instead, and return <code>true</code> to stop the original 
 
122
<code>Search</code> action from going any further. The net effect is 
 
123
that one action has been diverted into another.</p>
 
124
 
 
125
<a id="p99" name="p99"></a>
 
126
<p class="dotbreak">� � � � �</p>
 
127
 
 
128
<p class="normal">At any given time, just one action is under way, 
 
129
though others may be waiting to resume when the current one has finished. 
 
130
The current action is always stored in the four variables</p>
 
131
 
 
132
<p class="lynxonly"></p>
 
133
<pre class="code">actor    action    noun    second</pre>
 
134
 
 
135
<p class="normal"><code>actor</code>, <code>noun</code> and 
 
136
<code>second</code> hold the objects involved, or the special value 
 
137
<code>nothing</code> if they aren't involved at all. (There's always 
 
138
an <code>actor</code>, and for the time being it will always be equal 
 
139
to <code>player</code>.) <code>action</code> holds the kind of action. 
 
140
Its possible values can be referred to in the program using the 
 
141
<code>##</code> notation: for example</p>
 
142
 
 
143
<p class="lynxonly"></p>
 
144
<pre class="code">if (action == ##Look) ...</pre>
 
145
 
 
146
<p class="normal">tests to see if the current <code>action</code> is a 
 
147
<code>Look</code>.</p>
 
148
 
 
149
<p class="aside"><span class="warning">&#9650;</span>
 
150
Why have <code>##</code> at all, why not just write <code>Look</code>? 
 
151
Partly because this way the reader of the source code can see at a 
 
152
glance that an action type is being referred to, but also because 
 
153
the name might be used for something else. For instance there's a 
 
154
variable called <code>score</code> (holding the current game score), 
 
155
quite different from the action type <code>##Score</code>.</p>
 
156
 
 
157
<p class="aside"><span class="warning">&#9650;&#9650;</span>
 
158
For a few actions, the &#8216;noun&#8217; (or the &#8216;second 
 
159
noun&#8217;) is actually a number (for instance, &#8220;set timer to 
 
160
20&#8221; would probably end up with <code>noun</code> being <code>timer</code> and <code>second</code>
 
161
being 20). Occasionally one needs to be sure of the difference, e.g., 
 
162
to tell if <code>second</code> is holding a number or an object. It's then useful 
 
163
to know that there are two more primitive variables, <code>inp1</code> and <code>inp2</code>, 
 
164
parallel to <code>noun</code> and <code>second</code> and usually equal to them &#8211; but equal 
 
165
to 1 to indicate &#8220;some numerical value, not an object&#8221;.</p>
 
166
 
 
167
<p class="dotbreak">� � � � �</p>
 
168
 
 
169
<p class="normal">The library supports about 120 different actions 
 
170
and most large games will add some more of their own. The full list, 
 
171
given in <a href="tables.html#tbl6a">Table 6</a>, is initially daunting,
 
172
but for any given object most of the actions are irrelevant. For 
 
173
instance, if you only want to prevent an object from entering the 
 
174
player's possession, you need only block the <code>Take</code> action, 
 
175
unless the object is initially in something or on something, in which 
 
176
case you need to block <code>Remove</code> as well. In the author's 
 
177
game &#8216;Curses&#8217;, one exceptional object (Austin, the cat) 
 
178
contains rules concerning 15 different actions, but the average is 
 
179
more like two or three action-rules per object.</p>
 
180
 
 
181
<p class="indent">The list of actions is divided into three groups, 
 
182
called Group 1, Group 2 and Group 3:</p>
 
183
 
 
184
<a id="p100" name="p100"></a>
 
185
<ol>
 
186
<li>Group 1 contains &#8216;meta&#8217; actions for controlling 
 
187
the game, like <code>Score</code> and <code>Save</code>, which are 
 
188
treated quite differently from other actions as they do not
 
189
happen in the &#8220;model world&#8221;.</li>
 
190
<li>Actions in group 2 normally do something to change the state of 
 
191
the model world, or else to print important information about it. 
 
192
<code>Take</code> (&#8220;pick up&#8221;) and <code>Inv</code> 
 
193
(&#8220;inventory&#8221;) are examples of each. Such actions will 
 
194
affect any object which doesn't block them with a <code>before</code> 
 
195
rule.</li>
 
196
<li>Finally, group 3 actions are the ones which normally do nothing 
 
197
but print a polite refusal, like <code>Pull</code> (&#8220;it is 
 
198
fixed in place&#8221;), or a bland response, like <code>Listen</code> 
 
199
(&#8220;you hear nothing unexpected&#8221;). Such actions will never 
 
200
affect any object which doesn't positively react with a <code>before</code> 
 
201
rule.</li>
 
202
</ol>
 
203
 
 
204
<p class="aside"><span class="warning">&#9650;</span>
 
205
Some of the group 2 actions can be ignored by the programmer because 
 
206
they are really only keyboard shorthands for the player. For example, 
 
207
<code>&lt;Empty rucksack table&gt;</code> means &#8220;empty the 
 
208
contents of the rucksack onto the table&#8221; and is automatically
 
209
broken down into a stream of actions like <code>&lt;Remove fish 
 
210
rucksack&gt;</code> and <code>&lt;PutOn fish table&gt;</code>. 
 
211
You needn't write rules concerning <code>Empty</code>, only 
 
212
<code>Remove</code> and <code>PutOn</code>.</p>
 
213
 
 
214
<p class="aside"><span class="warning">&#9650;&#9650;</span>
 
215
Most of the library's group 2 actions are able to &#8220;run silently&#8221;. 
 
216
This means that if the variable <code>keep_silent</code> is set to 
 
217
<code>true</code>, then the actions print nothing in the event of 
 
218
success. The group 2 actions which can't run silently are exactly 
 
219
those ones whose successful operation does nothing but print: 
 
220
<code>Wait</code>, <code>Inv</code>, <code>Look</code>, 
 
221
<code>Examine</code>, <code>Search</code>.</p>
 
222
 
 
223
<a name="ex3"></a>
 
224
<p class="aside"><span class="warning"><b>&#8226;</b>&#9650;
 
225
<b><a href="sa6.html#ans3">EXERCISE 3</a></b></span><br>
 
226
&#8220;The door-handle of my room&#8230; was different from all other 
 
227
door-handles in the world, inasmuch as it seemed to open of its own 
 
228
accord and without my having to turn it, so unconscious had its 
 
229
manipulation become&#8230;&#8221; (Marcel Proust). Use silent-running
 
230
actions to make an unconsciously manipulated door: if the player tries 
 
231
to pass through when it's closed, print &#8220;(first opening 
 
232
the door)&#8221; and do so. (You need to know some of 
 
233
<a href="s13.html">&#167;13</a>, the section on doors, to answer 
 
234
this.)</p>
 
235
 
 
236
<a name="ex4"></a>
 
237
<p class="aside"><span class="warning"><b>&#8226;</b>&#9650;&#9650;
 
238
<b><a href="sa6.html#ans4">EXERCISE 4</a></b></span><br>
 
239
Now add &#8220;(first unlocking the door with&#8230;)&#8221;, 
 
240
automatically trying to unlock it using either a key already known 
 
241
to work, or failing that, any key carried by the player which hasn't 
 
242
been tried in the lock before.</p>
 
243
 
 
244
<p class="dotbreak">� � � � �</p>
 
245
 
 
246
<p class="aside"><span class="warning">&#9650;</span>
 
247
Some actions happen even though they don't arise <em>directly</em> 
 
248
from anything the player has typed. For instance, an action called 
 
249
<code>ThrownAt</code> is listed under group 3 in 
 
250
<a href="tables.html#tbl6c">Table 6</a>. It's a side-effect of the ordinary 
 
251
<code>ThrowAt</code> action: if the player types &#8220;throw rock 
 
252
at dalek&#8221;, the parser generates the action <code>ThrowAt 
 
253
rock dalek</code>. As usual the rock is sent a <code>before</code> 
 
254
message asking if it objects to being thrown at a Dalek. Since 
 
255
the Dalek may also have an opinion on the matter, another <code>before</code> 
 
256
message is sent to the Dalek, but 
 
257
<a id="p101" name="p101"></a>
 
258
this time with the action 
 
259
<code>ThrownAt</code>. A dartboard can thus distinguish between being
 
260
thrown, and having things thrown at it:</p>
 
261
 
 
262
<p class="lynxonly"></p>
 
263
<pre class="code">
 
264
before [;
 
265
    ThrowAt: &quot;Haven't you got that the wrong way round?&quot;;
 
266
    ThrownAt:
 
267
        if (noun==dart) {
 
268
            move dart to self;
 
269
            if (random(31)==1)
 
270
                print (string) random(&quot;Outer bull&quot;, &quot;Bullseye&quot;);
 
271
            else {
 
272
                print (string) random(&quot;Single&quot;, &quot;Double&quot;, &quot;Triple&quot;);
 
273
                print &quot; &quot;, (number) random(20);
 
274
            }
 
275
            &quot;!&quot;;
 
276
        }
 
277
        move noun to location;
 
278
        print_ret (The) noun, &quot; bounces back off the board.&quot;;
 
279
],
 
280
</pre>
 
281
 
 
282
<p class="aside">Such an imaginary action &#8211; usually, as in this 
 
283
case, a perfectly sensible action seen from the point of view of 
 
284
the second object involved, rather than the first &#8211; is sometimes
 
285
called a &#8220;fake action&#8221;. Two things about it are fake: 
 
286
there's no grammar that produces <code>ThrownAt</code>, and there's 
 
287
no routine called <code>ThrownAtSub</code>. The important fake actions 
 
288
are <code>ThrownAt</code>, <code>Receive</code> and <code>LetGo</code>, 
 
289
the latter two being used for containers: see 
 
290
<a href="s12.html">&#167;12</a>.</p>
 
291
 
 
292
<p class="aside"><span class="warning">&#9650;</span>
 
293
If you really need to, you can declare a new fake action with the 
 
294
directive <code>Fake_action</code> &#8249;<span class="token">Action-name</span>&#8250;<code>;</code>. 
 
295
You can then cause this action with <code>&lt;</code> and 
 
296
<code>&gt;</code> as usual.</p>
 
297
 
 
298
<a name="ex5"></a>
 
299
<p class="aside"><span class="warning"><b>&#8226;</b>&#9650;&#9650;
 
300
<b><a href="sa6.html#ans5">EXERCISE 5</a></b></span><br>
 
301
<code>ThrownAt</code> would be unnecessary if Inform had an idea 
 
302
of <code>before</code> and <code>after</code> routines which an 
 
303
object could provide if it were the second noun of an action. How 
 
304
might this be implemented?</p>
 
305
 
 
306
<p class="aside"><span class="warning">&#9650;&#9650;</span>
 
307
Very occasionally, in the darker recesses of 
 
308
<a href="s18.html">&#167;18</a> for instance, you want &#8220;fake 
 
309
fake actions&#8221;, actions which are only halfway faked in that 
 
310
they still have action routines. Actually, these are perfectly 
 
311
genuine actions, but with the parser's grammar jinxed so that they 
 
312
can never be produced whatever the player types.</p>
 
313
 
 
314
<p class="dotbreak">� � � � �</p>
 
315
 
 
316
<p class="normal">The standard stock of actions is easily added to. 
 
317
Two things are necessary to create a new action: first one must provide 
 
318
a routine to make it happen. For instance:</p>
 
319
 
 
320
<p class="lynxonly"></p>
 
321
<pre class="code">
 
322
[ BlorpleSub;
 
323
  &quot;You speak the magic word ~Blorple~. Nothing happens.&quot;;
 
324
];
 
325
</pre>
 
326
 
 
327
<a id="p102" name="p102"></a>
 
328
<p class="normal">Every action has to have a &#8220;subroutine&#8221; 
 
329
like this, the name of which is always the name of the action with 
 
330
<code>Sub</code> appended. Secondly, one must add grammar so that 
 
331
<code>Blorple</code> can actually be called for. Far more about grammar 
 
332
in <a href="ch4.html">Chapter IV</a>: for now we add the simplest 
 
333
of all grammar lines, a directive</p>
 
334
 
 
335
<p class="lynxonly"></p>
 
336
<pre class="code">Verb 'blorple' * -&gt; Blorple;</pre>
 
337
 
 
338
<p class="normal">placed after the inclusion of the <code>Grammar</code> 
 
339
file. The word &#8220;blorple&#8221; can now be used as a verb. It 
 
340
can't take any nouns, so the parser will complain if the player
 
341
types &#8220;blorple daisy&#8221;.</p>
 
342
 
 
343
<p class="indent"><code>Blorple</code> is now a typical Group 3 action. 
 
344
<code>before</code> rules can be written for it, and it can be 
 
345
triggered off by a statement like</p>
 
346
 
 
347
<p class="lynxonly"></p>
 
348
<pre class="code">&lt;Blorple&gt;;</pre>
 
349
 
 
350
<p class="indent">The unusual action in &#8216;Ruins&#8217;, 
 
351
<code>Photograph</code>, needs to be a Group 2 action, since it actually 
 
352
does something, and objects need to be able to react with <code>after</code> 
 
353
rules. (Indeed, the definition of the <code>Treasure</code> class 
 
354
in the previous section contains just such an <code>after</code> rule.) 
 
355
A photographer needs a camera:</p>
 
356
 
 
357
<p class="lynxonly"></p>
 
358
<pre class="code">
 
359
Object -&gt; -&gt; camera &quot;wet-plate camera&quot;
 
360
  with name 'wet-plate' 'plate' 'wet' 'camera',
 
361
       description
 
362
          &quot;A cumbersome, sturdy, stubborn wooden-framed wet plate
 
363
          model: like all archaeologists, you have a love-hate
 
364
          relationship with your camera.&quot;;
 
365
</pre>
 
366
 
 
367
<p class="normal">(This is going to be inside a packing case which is 
 
368
inside the Forest, hence the two arrows <code>-&gt;</code>.) And now the action 
 
369
subroutine. The sodium lamp referred to will be constructed in 
 
370
<a href="s14.html">&#167;14</a>.</p>
 
371
 
 
372
<p class="lynxonly"></p>
 
373
<pre class="code">
 
374
[ PhotographSub;
 
375
  if (camera notin player) &quot;Not without the use of your camera.&quot;;
 
376
  if (noun == player) &quot;Best not. You haven't shaved since Mexico.&quot;;
 
377
  if (children(player) &gt; 1)
 
378
     &quot;Photography is a cumbersome business, needing the use of both
 
379
      hands. You'll have to put everything else down.&quot;;
 
380
  if (location == Forest) &quot;In this rain-soaked forest, best not.&quot;;
 
381
  if (location == thedark) &quot;It is far too dark.&quot;;
 
382
  if (AfterRoutines()) return;
 
383
 &quot;You set up the elephantine, large-format, wet-plate camera, adjust
 
384
  the sodium lamp and make a patient exposure of &quot;, (the) noun, &quot;.&quot;;
 
385
];
 
386
</pre>
 
387
 
 
388
<a id="p103" name="p103"></a>
 
389
<p class="normal">What makes this a Group 2 action is that, if the action 
 
390
successfully takes place, then the library routine <code>AfterRoutines</code> 
 
391
is called. This routine takes care of all the standard rules to do with 
 
392
<code>after</code> (see below), and returns <code>true</code> if any 
 
393
object involved has dealt with the action and printed something already. 
 
394
(Failing that, the message &#8220;You set up&#8230;&#8221; will be 
 
395
printed.) Finally, some grammar for the parser:</p>
 
396
 
 
397
<p class="lynxonly"></p>
 
398
<pre class="code">Verb 'photograph' * noun -&gt; Photograph;</pre>
 
399
 
 
400
<p class="normal">This matches input like &#8220;photograph statuette&#8221;, 
 
401
because the grammar token <code>noun</code> tells the parser to expect 
 
402
the name of a visible object. See <a href="s30.html">&#167;30</a> and 
 
403
<a href="s31.html">&#167;31</a> for much more on grammar.</p>
 
404
 
 
405
<p class="aside"><span class="warning">&#9650;</span>
 
406
To make a Group 1 action, define the verb as <code>meta</code> 
 
407
(see <a href="s30.html">&#167;30</a>).</p>
 
408
 
 
409
<p class="dotbreak">� � � � �</p>
 
410
 
 
411
<p class="normal">Actions are processed in a simple way, but one which 
 
412
involves many little stages. There are three main stages:</p>
 
413
 
 
414
<ol>
 
415
<li>&#8216;Before&#8217;, for group 2 and 3 actions. An opportunity 
 
416
for your code to interfere with or block altogether what might soon 
 
417
happen.</li>
 
418
<li>&#8216;During&#8217;, for all actions. The library takes control 
 
419
and decides if the action makes sense according to its normal world 
 
420
model: for example, only an <code>edible</code> object may be eaten; 
 
421
only an object in the player's possession can be thrown at somebody, 
 
422
and so on. If the action is impossible, a complaint is printed and 
 
423
that's all. Otherwise the action is now carried out.</li>
 
424
<li>&#8216;After&#8217;, for group 2 actions. An opportunity for 
 
425
your code to react to what has happened, after it has happened but 
 
426
before any text announcing it has been printed. If it chooses, your 
 
427
code can print and cause an entirely different outcome. If your code 
 
428
doesn't interfere, the library reports back to the player (with such 
 
429
choice phrases as &#8220;Dropped.&#8221;).</li>
 
430
</ol>
 
431
 
 
432
<p class="aside"><span class="warning">&#9650;</span>
 
433
Group 1 actions, like <code>Score</code>, have no &#8216;Before&#8217; 
 
434
or &#8216;After&#8217; stages: you can't (easily) stop them from 
 
435
taking place. They aren't happening in the game's world, but in the
 
436
player's.</p>
 
437
 
 
438
<p class="aside"><span class="warning">&#9650;</span>
 
439
The &#8216;Before&#8217; stage consults your code in five ways, and 
 
440
occasionally it's useful to know in what order:</p>
 
441
 
 
442
<ul style="list-style-type:none">
 
443
<li>(1a) &nbsp; The <code>GamePreRoutine</code> is called, if you have written 
 
444
one. If it returns <code>true</code>, nothing else happens and the 
 
445
action is stopped.</li>
 
446
<li>(1b) &nbsp; The <code>orders</code> property of the player is called 
 
447
on the same terms. For more details, see <a href="s18.html">&#167;18</a>.</li>
 
448
<li>(1c) &nbsp; And the <code>react_before</code> of every object in scope, 
 
449
which roughly means &#8216;in the vicinity&#8217;. For more details, 
 
450
see <a href="s32.html">&#167;32</a>.</li>
 
451
<li><a id="p104" name="p104"></a>(1d) &nbsp; And the <code>before</code> of the current room.</li>
 
452
<li>(1e) &nbsp; If the action has a first noun, its <code>before</code> 
 
453
is called on the same terms.</li>
 
454
</ul>
 
455
 
 
456
<p class="aside"><span class="warning">&#9650;</span>
 
457
The library processes the &#8216;During&#8217; stage by calling the 
 
458
action's subroutine: for instance, by calling <code>TakeSub</code>.</p>
 
459
 
 
460
<p class="aside"><span class="warning">&#9650;</span>
 
461
The &#8216;After&#8217; stage only applies to Group 2 actions, as 
 
462
all Group 3 actions have been wound up with a complaint or a bland 
 
463
response at the &#8216;During&#8217; stage. During &#8216;After&#8217;
 
464
the sequence is as follows: (3a) <code>react_after</code> rules for 
 
465
every object in scope (including the player object); (3b) the room's 
 
466
<code>after</code>; (3c) the first noun's <code>after</code> and 
 
467
(3d) finally <code>GamePostRoutine</code>.</p>
 
468
 
 
469
<p class="aside"><span class="warning">&#9650;&#9650;</span>
 
470
To some extent you can even meddle with the &#8216;During&#8217; 
 
471
stage, and thus even interfere with Group 1 actions, by unscrupulous 
 
472
use of the <code>LibraryMessages</code> system. See 
 
473
<a href="s25.html">&#167;25</a>.</p>
 
474
 
 
475
<p class="dotbreak">� � � � �</p>
 
476
 
 
477
<p class="normal">As mentioned above, the parser can generate decidedly 
 
478
odd actions, such as <code>Insert camel eye_of_needle</code>. The 
 
479
parser's policy is to allow any action which the player has clearly 
 
480
asked for at the keyboard, and it never uses knowledge about the 
 
481
current game position except to resolve ambiguities. For instance, 
 
482
&#8220;take house&#8221; in the presence of the Sydney Opera House 
 
483
and also a souvenir model of the same will be resolved in favour of 
 
484
the model. But if there is no model to cloud the issue, the parser 
 
485
will cheerfully generate <code>Take Sydney_Opera_House</code>.</p>
 
486
 
 
487
<p class="indent">Actions are only checked for sensibleness
 
488
<em>after</em> the <code>before</code> stage. In many ways this is 
 
489
a good thing, because in adventure games the very unlikely is sometimes 
 
490
correct. But sometimes it needs to be remembered when writing 
 
491
<code>before</code> rules. Suppose a <code>before</code> rule 
 
492
intercepts the action of putting the mushroom in the crate, and 
 
493
exciting things happen as a result. Now even if the mushroom is, say, 
 
494
sealed up inside a glass jar, the parser will still generate the
 
495
action <code>Insert mushroom crate</code>, and the <code>before</code> rule 
 
496
will still cut in, because the impossibility of the action hasn't yet 
 
497
been realised.</p>
 
498
 
 
499
<p class="indent">The upshot of this is that the exciting happening 
 
500
should be written not as a <code>before</code> but as an <code>after</code> 
 
501
rule, when it's known that the attempt to put the mushroom in the crate 
 
502
has already succeeded.</p>
 
503
 
 
504
<p class="aside"><span class="warning">&#9650;</span>
 
505
That's fine if it's a Group 2 action you're working with. But consider 
 
506
the following scenario: a siren has a cord which needs to be pulled to 
 
507
sound the alarm. But the siren can be behind glass, and is on the 
 
508
other side of a barred cage in which the player is imprisoned. 
 
509
You need to write a rule for <code>Pull cord</code>, but you can't 
 
510
place this among the cord's <code>after</code> rules because <code>Pull</code> 
 
511
is a group 3 action and there isn't any &#8220;after&#8221;: so it has 
 
512
to be a <code>before</code> rule. Probably it's best to write your 
 
513
own code by hand to check 
 
514
<a id="p105" name="p105"></a>
 
515
that the cord is reachable. But an alternative 
 
516
is to call the library's routine:</p>
 
517
 
 
518
<p class="lynxonly"></p>
 
519
<pre class="code">ObjectIsUntouchable(item, silent_flag, take_flag)</pre>
 
520
 
 
521
<p class="aside">This determines whether or not the player can touch 
 
522
<code>item</code>, returning <code>true</code> if there is some 
 
523
obstruction. If <code>silent_flag</code> is <code>true</code>, or 
 
524
if there's no obstruction anyway, nothing will be printed. Otherwise 
 
525
a suitable message will be printed up, such as &#8220;The barred cage 
 
526
isn't open.&#8221; So a safe way to write the cord's <code>before</code> 
 
527
rule would be:</p>
 
528
 
 
529
<p class="lynxonly"></p>
 
530
<pre class="code">
 
531
before [;
 
532
    Pull: if (ObjectIsUntouchable(self)) rtrue;
 
533
          &quot;~Vwoorp! Vwoorp!~&quot;;
 
534
],
 
535
</pre>
 
536
 
 
537
<p class="aside"><code>ObjectIsUntouchable</code> can also be a convenience 
 
538
when writing action subroutines for new actions of your own.</p>
 
539
 
 
540
<p class="aside"><span class="warning">&#9650;&#9650;</span>
 
541
If you set <code>take_flag</code>, then a further restriction will be 
 
542
imposed: the <code>item</code> must not belong to something or someone 
 
543
already: specifically, it must not be in the possession of an <code>animate</code> 
 
544
or a <code>transparent</code> object that isn't a <code>container</code> 
 
545
or <code>supporter</code>. For instance, the off button on a television 
 
546
set can certainly be touched, but if <code>take_flag</code> is <code>true</code>, 
 
547
then <code>ObjectIsUntouchable</code> will print up &#8220;That seems 
 
548
to be a part of the television set.&#8221; and return <code>true</code> 
 
549
to report an obstacle.</p>
 
550
 
 
551
<p class="aside"><span class="warning"><b>&#8226;</b> <b>REFERENCES</b></span><br>
 
552
In a game compiled with the <code>-D</code> for &#8220;Debugging&#8221; 
 
553
switch set, the &#8220;actions&#8221; verb will result in trace information 
 
554
being printed each time any action is generated. Try putting many things 
 
555
into a rucksack and asking to &#8220;empty&#8221; it for an extravagant 
 
556
list. &nbsp;
 
557
<span class="warning"><b>&#8226;</b></span>Diverted actions (using <code>&lt;&lt;</code> 
 
558
and <code>&gt;&gt;</code>) are commonplace. They're used in about 20 
 
559
places in &#8216;Advent&#8217;: a good example is the way &#8220;take 
 
560
water&#8221; is translated into a <code>Fill bottle</code> action. &nbsp;
 
561
<span class="warning"><b>&#8226;</b></span>L. Ross Raszewski's library 
 
562
extension <tt>&quot;yesno.h&quot;</tt> makes an interesting use of 
 
563
<code>react_before</code> to handle semi-rhetorical questions. For 
 
564
instance, suppose the player types &#8220;eat whale&#8221;, an absurd 
 
565
command to which the game replies &#8220;You can fit a blue whale in 
 
566
your mouth?&#8221; Should the player take this as a literal question 
 
567
and type &#8220;yes&#8221;, the designer might want to be able to reply 
 
568
&#8220;Oh. I should never have let you go through all those doors.&#8221; 
 
569
How might this be done? The trick is that, when the game's first reply
 
570
is made, an invisible object is moved into play which does nothing except 
 
571
to react to a <code>Yes</code> action by making the second reply.</p>
 
572
 
 
573
</div>
 
574
<p class="navbar">
 
575
 <a href="index.html">home</a> /
 
576
 <a href="contents.html">contents</a> /
 
577
 <a href="ch2.html" title="Chapter II: Introduction to Designing">chapter II</a> /
 
578
 <a href="s5.html" title="&#167;5: Introducing messages and classes">prev</a> /
 
579
 <a href="s7.html" title="&#167;7: Infix and the debugging verbs">next</a> /
 
580
 <a href="dm4index.html">index</a>
 
581
</p>
 
582
</body>
 
583
</html>
 
584