« back to all changes in this revision
Viewing changes to info/inform-8
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Bazaar Package Importer
- Author(s): Mark Baker
- Date: 2004-03-29 23:52:44 UTC
- Revision ID: james.westby@ubuntu.com-20040329235244-fox1z1yv7d6vojoo
Tags: upstream-6.30
Import upstream version 6.30
- files added:
- config
- contrib
- demos
- html
- html/answers1
- html/answers2
- html/icons
- include
- info
- lib
- src
- tutor
added
removed
info/inform-8
1
This is Info file inform.info, produced by Makeinfo-1.64 from the input
2
file inform.texi.
3
4
This is the Inform Designer's Manual, third edition, 4 September 1996,
5
as updated 16 May 1997. It was converted to Info by Christopher J.
6
Madsen <ac608@yfn.ysu.edu>.
7
8
Copyright 1996,1997 Graham Nelson and Christopher J. Madsen
9
10
Permission is granted to make and distribute copies of this manual
11
provided that:
12
(a) distributed copies are not substantially different from those
13
archived by the author,
14
(b) this and other copyright messages are always retained in full, and
15
(c) no profit is involved.
16
17
18
File: inform, Node: Scope, Next: Helping the Parser, Prev: Grammar Tokens, Up: Describing and Parsing
19
20
Scope and what you can see
21
==========================
22
23
He cannot see beyond his own nose. Even the fingers he
24
outstretches from it to the world are (as I shall suggest) often
25
invisible to him.
26
27
-- Max Beerbohm (1872-1956), of George Bernard Shaw
28
29
Wherefore are these things hid?
30
31
-- William Shakespeare (1564-1616), Twelfth Night
32
33
Time to say what "in scope" means. This definition is one of the most
34
important rules of play, because it decides what the player is allowed
35
to refer to. You can investigate this in practice by compiling any game
36
with the debugging suite of verbs included and typing "scope" in
37
different places: but here are the rules in full. The following are in
38
scope:
39
40
the player's immediate possessions;
41
the 12 compass directions;
42
if there is light (*note Light and Dark::.), the objects in the same
43
`enclosure' as the player;
44
if not, any objects in the thedark object;
45
if the player is inside a dark container, then that container.
46
47
The `enclosure' of the player is usually the current location.
48
Formally, it's the outermost object containing the player which remains
49
visible -- for instance, if the player is in a transparent cabinet in a
50
closed, huge cupboard in the Stores Room, then the enclosure is the
51
huge cupboard. (Thus items in the huge cupboard are in scope, subject
52
to the remaining rules, but other items in the Stores Room are not.)
53
54
In addition, if an object is in scope then its immediate possessions
55
are in scope, *if* it is `see-through', which means that:
56
57
the object has supporter, *or*
58
the object has transparent, *or*
59
the object is an open container.
60
61
In addition, if an object is in scope then anything which it "adds to
62
scope" is also in scope.
63
64
!! The player's possessions are in scope in a dark room -- so the
65
player can still turn his lamp on. On the other hand, a player who
66
puts the lamp on the ground and turns it off then loses the ability to
67
turn it back on again, because it is out of scope. This can be changed;
68
see below.
69
70
!! Compass directions make sense as things. The player can always type
71
something like "attack the south wall" and the before rule for the room
72
could trap the action Attack s_obj to make something unusual happen, if
73
this is desired.
74
75
!! The parser applies scope rules to all actors, not just the player.
76
Thus "dwarf, drop sword" will be accepted if the dwarf can see it, even
77
if the player can't.
78
79
!! The concealed attribute only hides objects from room descriptions,
80
and doesn't remove them from scope. If you want things to be both
81
concealed and unreferrable-to, put them somewhere else! Or give them
82
an uncooperative parse_name routine.
83
84
!!!! Actually, the above definition is not quite right, because the
85
compass directions are not in scope when the player asks for a plural
86
number of things, like "take all the knives"; this makes some of the
87
parser's plural algorithms run faster. Also, for a `multiexcept'
88
token, the other object is not in scope; and for a `multiinside' token,
89
only objects in the other object are in scope. This makes "take
90
everything from the cupboard" work in the natural way.
91
92
Two library routines are provided to enable you to see what's in scope
93
and what isn't. The first, TestScope(obj, actor), simply returns true
94
or false according to whether or not obj is in scope. The second is
95
LoopOverScope(routine, actor) and calls the given routine for each
96
object in scope. In each case the actor given is optional; if it's
97
omitted, scope is worked out for the player as usual.
98
99
Exercise 79
100
-----------
101
102
Implement the debugging suite's "scope" verb, which lists all the
103
objects currently in scope.
104
105
*Note Answer 79::
106
107
Exercise 80
108
-----------
109
110
Write a "megalook" verb, which looks around and examines everything
111
nearby.
112
113
*Note Answer 80::
114
115
Formally, scope determines what you can talk about, which usually
116
means what you can see. But what can you touch? Suppose a locked
117
chest is inside a sealed glass cabinet. The Inform parser will allow
118
the command "unlock chest with key" and generate the appropriate
119
action, Unlock chest key, because the chest is in scope, so the command
120
at least makes sense.
121
122
But it's impossible to carry out, because the player can't reach
123
through the solid glass. So the library's routine for handling the
124
Unlock action needs to enforce this. The library does this using a
125
stricter rule called "touchability". The rule is that you can touch
126
anything in scope unless there's a closed container between you and it.
127
This applies either if you're in the container, or if it is.
128
129
Some purely visual actions don't require touchability -- Examine or
130
LookUnder, for instance. But most actions are tactile, and so will
131
many actions created by designers. If you want to make your own action
132
routines enforce touchability, you can call the library routine
133
ObjectIsUntouchable(obj). This either returns false if there's no
134
problem in touching obj, or returns true and prints a suitable message
135
(such as "The solid glass cabinet is in the way."). Thus, the first
136
line of many of the library's action routines is:
137
138
if (ObjectIsUntouchable(noun)) return;
139
140
You can also call ObjectIsUntouchable(obj, true) to simply return true
141
or false, and print nothing, if you'd rather provide your own failure
142
message.
143
144
The rest of this section is about how to change the scope rules. As
145
usual with Inform, you can change them globally, but it's more
146
efficient and safer to work locally. To take a typical example: how do
147
we allow the player to ask questions like the traditional "what is a
148
grue"? The "grue" part ought to be parsed as if it were a noun, so that
149
we could distinguish between, say, a "garden grue" and a "wild grue".
150
So it isn't good enough to look only at a single word. Here is one
151
solution:
152
153
Object questions "qs";
154
[ QuerySub; print_ret (string) noun.description;
155
];
156
[ Topic i;
157
switch(scope_stage)
158
{ 1: rfalse;
159
2: objectloop (i in questions) PlaceInScope(i); rtrue;
160
3: "At the moment, even the simplest questions confuse you.";
161
}
162
];
163
164
where the actual questions at any time are the current children of the
165
questions object, like so:
166
167
Object q1 "long count" questions
168
with name "long" "count",
169
description "The Long Count is the great Mayan cycle of time,
170
which began in 3114 BC and will finish with the world's end
171
in 2012 AD.";
172
173
and we also have a grammar line:
174
175
Verb "what"
176
* "is" scope=Topic -> Query
177
* "was" scope=Topic -> Query;
178
179
Note that the questions and q1 objects are out of the game for every
180
other purpose. The name "qs" doesn't matter, as it will never appear;
181
the individual questions are named so that the parser might be able to
182
say "Which do you mean, the long count or the short count?" if the
183
player asked "what is the count".
184
185
When the parser reaches `scope=Topic', it calls the Topic routine
186
with the variable scope_stage set to 1. The routine should return 1
187
(true) if it is prepared to allow multiple objects to be accepted here,
188
and 0 (false) otherwise: as we don't want "what is everything" to list
189
all the questions and answers in the game, we return false.
190
191
A little later on in its machinations, the parser again calls Topic
192
with scope_stage now set to 2. Topic is now obliged to tell the parser
193
which objects are to be in scope. It can call two parser routines to
194
do this.
195
196
ScopeWithin(object)
197
198
puts everything inside the object into scope, though not the object
199
itself;
200
201
PlaceInScope(object)
202
203
puts just a single object into scope. It is perfectly legal to declare
204
something in scope that "would have been in scope anyway": or even
205
something which is in a different room altogether from the actor
206
concerned, say at the other end of a telephone line. Our scope routine
207
Topic should then return
208
209
0. (false) to carry on with the usual scope rules, so that everything
210
that would usually be in scope still is, or
211
212
1. (true) to tell the parser not to put any more objects into scope.
213
214
So at scope_stage 2 it is quite permissible to do nothing but return
215
false, whereupon the usual rules apply. Topic returns true because it
216
wants only question topics to be in scope, not question topics together
217
with the usual miscellany near the player.
218
219
This is enough to deal with "what is the long count". If on the
220
other hand the player typed "what is the lgon cnout", the error message
221
which the parser would usually produce ("You can't see any such thing")
222
would be unsatisfactory. So if parsing failed at this token, then
223
Topic is called at scope_stage 3 to print out a suitable error message.
224
It must provide one.
225
226
!! Note that ScopeWithin(object) extends the scope down through its
227
possessions according to the usual rules, i.e., depending on their
228
transparency, whether they're containers and so on. The definition of
229
Topic above shows how to put just the direct possessions into scope.
230
231
Exercise 81
232
-----------
233
234
Write a token which puts everything in scope, so that you could have
235
a debugging "purloin" verb which could take anything, regardless of
236
where it was and the rules applying to it.
237
238
*Note Answer 81::
239
240
Changing the global definition of scope should be done cautiously
241
(there may be unanticipated side effects); bear in mind that scope
242
decisions need to be taken often -- every time an object token is
243
parsed, so perhaps five to ten times in every game turn -- and hence
244
moderately quickly. The global definition can be tampered with by
245
providing the entry point
246
247
InScope(actor)
248
249
where the actor is usually the player, but not always. If the routine
250
decides that a particular object should be in scope for the actor, it
251
should execute PlaceInScope and ScopeWithin just as above, and return
252
true or false, as if it were at scope_stage 2. Thus, it is vital to
253
return false in circumstances when you don't want to intervene.
254
255
!! The token `scope=<Routine>' takes precedence over InScope, which
256
will only be reached if the routine returns false to signify `carry on'.
257
258
!!!! There are seven reasons why InScope might be being called; the
259
scope_reason variable is set to the current one:
260
261
PARSING_REASON
262
The usual one. Note that action_to_be holds NULL in the early
263
stages (before the verb has been decided) and later on the action
264
which would result from a successful match.
265
266
TALKING_REASON
267
Working out which objects are in scope for being spoken to (see
268
the end of *Note Living Creatures:: for exercises using this).
269
270
EACHTURN_REASON
271
When running each_turn routines for anything nearby, at the end of
272
each turn.
273
274
REACT_BEFORE_REASON
275
When running react_before.
276
277
REACT_AFTER_REASON
278
When running react_after.
279
280
TESTSCOPE_REASON
281
When performing a TestScope.
282
283
LOOPOVERSCOPE_REASON
284
When performing a LoopOverScope.
285
286
Here are some examples. Firstly, as promised, how to change the rule
287
that "things you've just dropped disappear in the dark":
288
289
[ InScope person i;
290
if (person==player && location==thedark)
291
objectloop (i near player)
292
if (i has moved)
293
PlaceInScope(i);
294
rfalse;
295
];
296
297
With this routine added, the objects in the dark room the player is in
298
are in scope only if they have moved (that is, have been held by the
299
player in the past); and even then, are in scope only to the player.
300
301
!!!! Exercise 82
302
----------------
303
304
Construct a long room divided by a glass window. Room descriptions
305
on either side should describe what's in view on the other; the window
306
should be lookable-through; objects on the far side should be in scope,
307
but not manipulable; and everything should cope well if one side is in
308
darkness.
309
310
*Note Answer 82::
311
312
!!!! Exercise 83
313
----------------
314
315
Code the following puzzle. In an initially dark room there is a
316
light switch. Provided you've seen the switch at some time in the
317
past, you can turn it on and off -- but before you've ever seen it, you
318
can't. Inside the room is nothing you can see, but you can hear a
319
dwarf breathing. If you tell the dwarf to turn the light on, he will.
320
321
*Note Answer 83::
322
323
As mentioned in the definition above, each object has the ability to
324
drag other objects into scope whenever it is in scope. This is
325
especially useful for giving objects component parts: e.g., giving a
326
washing-machine a temperature dial. (The dial can't be a child object
327
because that would throw it in with the clothes: and it ought to be
328
attached to the machine in case the machine is moved from place to
329
place.) For this purpose, the property add_to_scope may contain a list
330
of objects to add.
331
332
!! Alternatively, it may contain a routine. This routine can then call
333
AddToScope(x) to put any object x into scope. It may not, however,
334
call ScopeWithin or any other scoping routines.
335
336
!!!! Scope addition does `not' occur for an object moved into scope by
337
an explicit call to PlaceInScope, since this must allow complete
338
freedom in scope selections. But it does happen when objects are moved
339
in scope by calls to ScopeWithin(domain).
340
341
Exercise 84
342
-----------
343
344
(From the tiny example game `A Nasal Twinge'.) Give the player a
345
nose, which is always in scope and can be held, reducing the player's
346
carrying capacity.
347
348
*Note Answer 84::
349
350
Exercise 85
351
-----------
352
353
(Likewise.) Create a portable sterilising machine, with a "go"
354
button, a top which things can be put on and an inside to hold objects
355
for sterilisation. (Thus it is a container, a supporter and a
356
possessor of sub-objects all at once.)
357
358
*Note Answer 85::
359
360
!!!! Exercise 86
361
----------------
362
363
Create a red sticky label which the player can affix to any object
364
in the game. (Hint: use InScope, not add_to_scope.)
365
366
*Note Answer 86::
367
368
References
369
----------
370
371
* `Balances' uses `scope = <routine>' tokens for legible spells and
372
memorised spells.
373
374
* See also the exercises at the end of *Note Living Creatures:: for
375
further scope trickery.
376
377
378
File: inform, Node: Helping the Parser, Prev: Scope, Up: Describing and Parsing
379
380
Helping the parser out of trouble
381
=================================
382
383
!! Once you begin programming the parser on a large scale, you soon
384
reach the point where the parser's ordinary error messages no longer
385
appear sensible. The ParserError entry point can change the rules even
386
at this last hurdle: it takes one argument, the error type, and should
387
return true to tell the parser to shut up, because a better error
388
message has already been printed, or false, to tell the parser to print
389
its usual message. The error types are all defined as constants:
390
391
STUCK_PE I didn't understand that sentence.
392
UPTO_PE I only understood you as far as...
393
NUMBER_PE I didn't understand that number.
394
CANTSEE_PE You can't see any such thing.
395
TOOLIT_PE You seem to have said too little!
396
NOTHELD_PE You aren't holding that!
397
MULTI_PE You can't use multiple objects with that verb.
398
MMULTI_PE You can only use multiple objects once on a line.
399
VAGUE_PE I'm not sure what `it' refers to.
400
EXCEPT_PE You excepted something not included anyway!
401
ANIMA_PE You can only do that to something animate.
402
VERB_PE That's not a verb I recognise.
403
SCENERY_PE That's not something you need to refer to...
404
ITGONE_PE You can't see `it' (the whatever) at the moment.
405
JUNKAFTER_PE I didn't understand the way that finished.
406
TOOFEW_PE Only five of those are available.
407
NOTHING_PE Nothing to do!
408
ASKSCOPE_PE whatever the scope routine prints
409
410
Each unsuccessful grammar line ends in one of these conditions. A
411
verb may have many lines of grammar; so by the time the parser wants to
412
print an error, all of them must have failed. The error message it
413
prints is the most `interesting' one: meaning, lowest down this list.
414
415
!! The VAGUE_PE and ITGONE_PE apply to all pronouns (in English, "it",
416
"him", "her" and "them"). The variable vague_word contains the
417
dictionary address of which is involved ('it', 'him', etc.).
418
419
You can find out the current setting of a pronoun using the
420
library's PronounValue routine: for instance, PronounValue('it') would
421
give the object which "it" currently refers to (possibly nothing).
422
Similarly SetPronoun('it', magic_ruby) would set "it" to mean the magic
423
ruby object. (When something like a magic ruby suddenly appears in the
424
middle of a turn, players will habitually call it "it".) A better way
425
to adjust the pronouns is to call PronounNotice(magic_ruby), which sets
426
whatever pronouns are appropriate. That is, it works out if the object
427
is a thing or a person, of what number and gender, which pronouns apply
428
to it in the parser's current language, and so on. In code predating
429
Inform 6.1 you may see variables called itobj, himobj and herobj
430
holding the English pronoun values: these still work properly, but
431
please use the modern system in new games.
432
433
!! The Inform parser resolves ambiguous inputs with a complicated
434
algorithm based on practical experience. However, it can't have any
435
expertise with newly-created verbs: here is how to provide it. If you
436
define a routine
437
438
ChooseObjects(object, code)
439
440
then it's called in two circumstances. If code is 0 or 1, the parser
441
is considering including the given object in an "all": 0 means the
442
parser has decided against, 1 means it has decided in favour. The
443
routine should reply
444
445
0 (or false) to say ``carry on'';
446
1 to force the object to be included; or
447
2 to force the object to be excluded.
448
449
It may want to decide using verb_word (the variable storing the current
450
verb word, e.g., 'take') and action_to_be, which is the action which
451
would happen if the current line of grammar were successfully matched.
452
453
The other circumstance is when code is 2. This means the parser is
454
sorting through a list of items (those in scope which best matched the
455
input), trying to decide which single one is most likely to have been
456
intended. If it can't choose a best one, it will give up and ask the
457
player. ChooseObjects should then return a number from 0 to 9 (0 being
458
the default) to give the object a score for how appropriate it is.
459
460
For instance, some designers would prefer "take all" not to attempt
461
to take scenery objects (which Inform, and the parsers in most of the
462
Infocom games, will do). Let us code this, and also teach the parser
463
that edible things are more likely to be eaten than inedible ones:
464
465
[ ChooseObjects obj code;
466
if (code<2) { if (obj has scenery) return 2; rfalse; }
467
if (action_to_be==##Eat && obj has edible) return 3;
468
if (obj hasnt scenery) return 2;
469
return 1;
470
];
471
472
Scenery is now excluded from "all" lists; and is further penalised in
473
that non-scenery objects are always preferred over scenery, all else
474
being equal. Most objects score 2 but edible things in the context of
475
eating score 3, so "eat black" will now always choose a Black Forest
476
gateau in preference to a black rod with a rusty iron star on the end.
477
478
!! Exercise 87
479
--------------
480
481
Allow "lock" and "unlock" to infer their second objects without
482
being told, if there's an obvious choice (because the player's only
483
carrying one key), but to issue a disambiguation question otherwise.
484
(Use Extend, not ChooseObjects.)
485
486
*Note Answer 87::
487
488
References
489
----------
490
491
* See `Balances' for a usage of ParserError.
492
493
494
File: inform, Node: Testing and Hacking, Next: Appendix, Prev: Describing and Parsing, Up: Top
495
496
Testing and Hacking
497
*******************
498
499
* Menu:
500
501
* Debugging:: Debugging verbs and tracing
502
* Run-Time Limitations:: Limitations on the run-time format
503
* Boxes:: Boxes, menus and drawings
504
* Assembly Language:: Descending into assembly language
505
506
507
File: inform, Node: Debugging, Next: Run-Time Limitations, Prev: Testing and Hacking, Up: Testing and Hacking
508
509
Debugging verbs and tracing
510
===========================
511
512
If builders built buildings the way programmers write programs,
513
the first woodpecker that came along would destroy civilisation.
514
515
-- old computing adage
516
517
Infocom claimed to have fixed nearly 2000 bugs in the course of writing
518
`Sorcerer', which is a relatively simple game today. Adventure games are
519
exhausting programs to test and debug because of the huge number of
520
states they can get into, many of which did not occur to the author.
521
(For instance, if the player solves the "last" puzzle first, do the
522
other puzzles still work properly? Are they still fair?) The main
523
source of error is simply the designer not noticing that some states
524
are possible. The Inform library can't help with this, but it does
525
contain features to help the tester to quickly reproduce states (by
526
moving objects around freely, for instance) and to see what the current
527
state actually is (by displaying the tree of objects, for instance).
528
529
Inform provides a small suite of debugging verbs, which will be
530
added to any game compiled with the -D switch. If you prefer, you can
531
include them manually by writing
532
533
Constant DEBUG;
534
535
DEBUG somewhere in the program before the library files are included.
536
(Just in case you forget having done this, the letter D appears in the
537
game banner to stop you releasing such a version by accident.)
538
539
You then get the following verbs, which can be used at any time in
540
play:
541
542
showobj <anything>
543
purloin <anything>
544
abstract <anything> to <anything>
545
tree tree <anything>
546
scope scope <anything>
547
showverb <verb>
548
goto <number> gonear <anything>
549
actions actions on actions off
550
routines routines on routines off
551
messages messages on messages off
552
timers timers on timers off
553
trace trace on trace off trace <1 to 5>
554
recording recording on recording off
555
replay
556
random
557
558
"showobj" is very informative about the current state of an object.
559
You can "purloin" any item or items in your game at any time, wherever
560
you are. This clears concealed for anything it takes, if necessary.
561
You can likewise "abstract" any item to any other item (meaning: move
562
it to the other item). To get a listing of the objects in the game and
563
how they contain each other, use "tree", and to see the possessions of
564
one of them alone, use "tree <that>". The command "scope" prints a
565
list of all the objects currently in scope, and can optionally be given
566
the name of someone else you want a list of the scope for (e.g., "scope
567
pirate"). "showverb" will display the grammar being used when the
568
given verb is parsed. Finally, you can go anywhere, but since rooms
569
don't have names understood by the parser, you have to give either the
570
object number, which you can find out from the "tree" listing, or the
571
name of some object in the room you want to go to (this is what
572
"gonear" does).
573
574
Turning on "actions" gives a trace of all the actions which take
575
place in the game (the parser's, the library's or yours); turning on
576
"routines" traces every object routine (such as before or life) that is
577
ever called, except for short_name (as this would look chaotic,
578
especially on the status line). It also describes all messages sent in
579
the game, which is why it can also be written as "messages". Turning
580
on "timers" shows the state of all active timers and daemons each turn.
581
582
The commands you type can be transcribed to a file with the
583
"recording" verb, and run back through with the "replay" verb. (This
584
may not work under some implementations of the ITF interpreter.) If
585
you're going to use such recordings, you will need to fix the random
586
number generator, and the "random" verb should render this
587
deterministic: i.e., after any two uses of "random", the same stream of
588
random numbers results. Random number generation is poor on some
589
machines: you may want to Replace the random-number generator in
590
software instead.
591
592
A source-level debugger for Inform, called Infix, has been planned for
593
some years, and may possibly be coming to fruition soon.
594
595
!! For the benefit of such tools, Inform (if compiling with the -k
596
option set) produces a file of "debugging information"
597
(cross-references of the game file with the source code), and anyone
598
interested in writing an Inform utility program may want to know the
599
format of this file: see the Technical Manual for details.
600
601
On most interpreters, though, run-time crashes can be mysterious, since
602
the interpreters were written on the assumption that they would only
603
ever play Infocom game files (which are largely error-free). A Standard
604
interpreter is better here and will usually tell you why and where the
605
problem is; given a game file address you can work back to the problem
606
point in the source either with Mark Howell's txd (disassembler) or by
607
running Inform with the assembler trace option on.
608
609
Here are all the ways I know to crash an interpreter at run-time
610
(with high-level Inform code, that is; if you insist on using assembly
611
language or the indirect function you're raising the stakes), arranged
612
in decreasing order of likelihood:
613
614
* Writing to a property which an object hasn't got;
615
616
* Dividing by zero, possibly by calling random(0);
617
618
* Giving a string or numerical value for a property which can only
619
legally hold a routine, such as before, after or life;
620
621
* Applying parent, child or children to the nothing object;
622
623
* Using print object on the nothing object, or for some object which
624
doesn't exist (use print (name), print (the) etc., instead as
625
these are safeguarded);
626
627
* Using print (string) or print (address) to print from an address
628
outside the memory map of the game file, or an address at which no
629
string is present (this will result in random text appearing,
630
possibly including unprintable characters, which might crash the
631
terminal);
632
633
* Running out of stack space in a recursive loop.
634
635
!! There are times when it's hard to work out what the parser is up to
636
and why (actually, most times are like this). The parser is written in
637
levels, the lower levels of which are murky indeed. Most of the
638
interesting things happen in the middle levels, and these are the ones
639
for which tracing is available. The levels which can be traced are:
640
641
Level 1 Grammar lines
642
Level 2 Individual tokens
643
Level 3 Object list parsing
644
Level 4 Resolving ambiguities and making choices of object(s)
645
Level 5 Comparing text against an individual object
646
647
"trace" or "trace on" give only level 1 tracing. Be warned: "trace
648
five" can produce reams of text when you try anything at all
649
complicated: but you do sometimes want to see it, to get a list of
650
exactly everything that is in scope and when. There are two levels
651
lower than that but they're too busy doing dull spade-work to waste
652
time on looking at parser_trace. There's also a level 0, but it
653
consists mostly of making arrangements for level 1, and isn't very
654
interesting.
655
656
!!!! Finally, though this is a drastic measure, you can always compile
657
your game -g (`debugging code') which gives a listing of every routine
658
ever called and their parameters. This produces an enormous melee of
659
output. More usefully you can declare a routine with an asterisk * as
660
its first local variable, which produces such tracing only for that one
661
routine. For example,
662
663
[ ParseNoun * obj n m;
664
665
results in the game printing out lines like
666
667
[ParseName, obj=26, n=0, m=0]
668
669
every time the routine is called.
670
671
References
672
----------
673
674
* A simple debugging verb called "xdeterm" is defined in the DEBUG
675
version of `Advent', to make the game deterministic (i.e., not
676
dependant on what the random number generator produces).
677
678
679
File: inform, Node: Run-Time Limitations, Next: Boxes, Prev: Debugging, Up: Testing and Hacking
680
681
Limitations on the run-time format
682
==================================
683
684
How wide the limits stand
685
Between a splendid and an happy land.
686
687
-- Oliver Goldsmith (1728-1774), The Deserted Village
688
689
The Infocom run-time format is well-designed, and has three major
690
advantages: it is compact, widely portable and can be quickly executed.
691
Nevertheless, like any rigidly defined format it imposes limitations.
692
These are not by any means pressing. Inform itself has a flexible
693
enough memory-management system not to impose artificial limits on
694
numbers of objects and the like.
695
696
Games can be compiled to several "versions" of the run-time format.
697
Unless told otherwise Inform compiled to what used to be called
698
Advanced games (version 5). It can still compile Standard games
699
(version 3) but doing so imposes genuine restrictions, and there is
700
little point any more. Stepping up to the new version 8, on the other
701
hand, allows much larger games to be compiled. Other versions exist but
702
are not useful to present-day game designers, so the real decision is
703
V5 versus V8.
704
705
Memory
706
This is the only serious restriction. The maximum size of a game
707
(in K) is given by:
708
V3 V4 V5 V6 V7 V8
709
128 256 256 512 320 512
710
Because games are encoded in a very compressed form, and because
711
the centralised library of Inform is efficient in terms of not
712
duplicating code, even 128K allows for a game at least half as
713
large again as a typical old-style Infocom game. The default
714
format (V5) will hold a game as large and complex as the final
715
edition of `Curses', substantially bigger than any Infocom game,
716
with room to spare. V6, the late Infocom graphical format, should
717
be avoided for text games, as it is much more difficult to
718
interpret. The V8 format allows quite gargantuan games (one could
719
implement, say, a merging of the `Zork' and `Enchanter' trilogies
720
in it) and is recommended as the standard size for games too big
721
to fit in V5.
722
723
Grammar
724
The number of verbs is limited only by memory. Each can have up
725
to 20 grammar lines (one can recompile Inform with
726
MAX_LINES_PER_VERB defined to a higher setting to increase this)
727
and a line contains at most 6 tokens. (Using general parsing
728
routines will prevent either restriction from biting.)
729
730
Vocabulary
731
There is no theoretical limit. Typical games have vocabularies of
732
between 1000 and 2000 words, but doubling that would pose no
733
problem.
734
735
Dictionary resolution
736
Dictionary words are truncated to their first 9 letters (except
737
that non-alphabetic characters, such as hyphens, count as 2
738
"letters" for this purpose). They must begin with an alphabetic
739
character and upper and lower case letters are considered equal.
740
(In V3, the truncation is to 6 letters.)
741
742
Attributes, properties, names
743
48 attributes and 63 common properties are available, and each
744
property can hold 64 bytes of data. Hence, for example, an object
745
can have up to 32 names. These restrictions are harmless in
746
practice: except in V3, where the numbers in question are 32, 31, 8
747
and 4, which begins to bite. Note that the number of different
748
individual properties is unlimited.
749
750
Special effects
751
V3 games cannot have special effects such as bold face and
752
underlining. (See the next two sections.)
753
754
Objects
755
Limited only by memory: except in V3, where the limit is 255.
756
757
Memory management
758
The Z-machine does not allow dynamic allocation or freeing of
759
memory: one must statically define an array to a suitable maximum
760
size and live within it. This restriction greatly increases the
761
portability of the format, and the designer's confidence that the
762
game's behaviour is genuinely independent of the machine it's
763
running on: memory allocation at run-time is a fraught process on
764
many machines.
765
766
Global variables
767
There can only be 240 of these, and the Inform compiler uses 5 as
768
scratch space, while the library uses slightly over 100; but since
769
a typical game uses only a dozen of its own, code being almost
770
always object-oriented, the restriction is never felt. An
771
unlimited number of Array statements is permitted and array
772
entries do not, of course, count towards the 240.
773
774
"Undo"
775
No "undo" verb is available in V3.
776
777
Function calls
778
A function can be called with at most 7 arguments. (Or, in V3 and
779
V4, at most 3.)
780
781
Recursion and stack usage
782
The limit on this is rather technical (see the Z-Machine Standards
783
Document). Roughly speaking, recursion is permitted to a depth of
784
90 routines in almost all circumstances (and often much deeper).
785
Direct usage of the stack via assembly language must be modest.
786
787
!! If memory does become short, there is a standard mechanism for
788
saving about 8-10% of the memory. Inform does not usually trouble to,
789
since there's very seldom the need, and it makes the compiler run about
790
10% slower. What you need to do is define abbreviations and then run
791
the compiler in its "economy" mode (using the switch -e). For
792
instance, the directive
793
794
Abbreviate " the ";
795
796
(placed before any text appears) will cause the string " the " to be
797
internally stored as a single `letter', saving memory every time it
798
occurs (about 2500 times in `Curses', for instance). You can have up
799
to 64 abbreviations. When choosing abbreviations, avoid proper nouns
800
and instead pick on short combinations of a space and common two- or
801
three-letter blocks. Good choices include " the ", "The", ", ", "and",
802
"you", " a ", "ing", " to". You can even get Inform to work out by
803
itself what a good stock of abbreviations would be: but be warned, this
804
makes the compiler run about 29000% slower.
805
806
807
File: inform, Node: Boxes, Next: Assembly Language, Prev: Run-Time Limitations, Up: Testing and Hacking
808
809
Boxes, menus and drawings
810
=========================
811
812
Yes, all right, I won't do the menu... I don't think you realise
813
how long it takes to do the menu, but no, it doesn't matter, I'll
814
hang the picture now. If the menus are late for lunch it doesn't
815
matter, the guests can all come and look at the picture till they
816
are ready, right?
817
818
-- John Cleese and Connie Booth, Fawlty Towers
819
820
One harmless effect, though not very special, is to ask the player a
821
yes/no question. To do this, print up the question and then call the
822
library routine YesOrNo, which returns true/false accordingly.
823
824
The status line is perhaps the most distinctive feature of Infocom
825
games in play. This is the (usually highlighted) bar across the top of
826
the screen. Usually, the game automatically prints the current game
827
location, and either the time or the score and number of turns taken.
828
It has the score/turns format unless the directive
829
830
Statusline time;
831
832
has been written in the program, in which case the game's 24-hour clock
833
is displayed.
834
835
!! If you want to change this, just Replace the parser's private
836
DrawStatusLine routine. This requires a little assembly language: see
837
the next section for numerous examples.
838
839
About character graphic drawings: on some machines, text will by default
840
be displayed in a proportional font (i.e., one in which the width of a
841
letter depends on what it is, so that for example an `i' will be
842
narrower than an `m'). If you want to display a diagram made up of
843
letters, such as a map, the spacing may then be wrong. The statement
844
font off ensures that any fancy font is switched off and that a
845
fixed-pitch one is being used: after this, font on restores the usual
846
state.
847
848
*Warning:* Don't turn the font on and off in the middle of a line;
849
this doesn't look right on some machines.
850
851
!! When trying to produce a character-graphics drawing, you sometimes
852
want to produce the \ character, one of the four "escape characters"
853
which can't normally be included in text. A double @ sign followed by
854
a number includes the character with that ASCII code; thus:
855
856
@@64 produces the literal character @
857
@@92 produces \ @@94 produces ^
858
@@126 produces ~
859
860
!!!! Some interpreters are capable of much better character graphics
861
(those equipped to run the Infocom game `Beyond Zork', for instance).
862
There is a way to find out if this feature is provided and to make use
863
of it: see the Z-Machine Standards Document.
864
865
!!!! A single @ sign is also an escape character. It must be followed
866
by a 2-digit decimal number between 0 and 31 (for instance, @05). What
867
this prints is the n-th `variable string'. This feature is not as
868
useful as it looks, since the only legal values for such a variable
869
string are strings declared in advance by a LowString directive. The
870
String statement then sets the n-th variable string. For details and
871
an example, see the answer to the east-west reversal exercise in *Note
872
Places::.
873
874
A distinctive feature of later Infocom games was their use of epigrams.
875
The assembly language required to produce this effect is easy but a
876
nuisance, so there is an Inform statement to do it, box. For example,
877
878
box "I might repeat to myself, slowly and soothingly,"
879
"a list of quotations beautiful from minds profound;"
880
"if I can remember any of the damn things."
881
""
882
"-- Dorothy Parker";
883
884
Note that a list of one or more lines is given (without intervening
885
commas) and that a blank line is given by a null string. Remember that
886
the text cannot be too wide or it will look awful on a small screen.
887
Inform will automatically insert the boxed text into the game
888
transcript, if one is being made. The author takes the view that this
889
device is amusing for irrelevant quotations but irritating when it
890
conveys vital information (such as "Beware of the Dog"). Also, some
891
people might be running your game on a laptop with a vertically
892
challenged screen, so it is polite to provide a "quotes off" verb.
893
894
A snag with printing boxes is that if you do it in the middle of a
895
turn then it will probably scroll half-off the screen by the time the
896
game finishes printing for the turn. The right time to do so is just
897
after the prompt (usually >) is printed, when the screen will definitely
898
scroll no more. You could use the Prompt: slot in LibraryMessages to
899
achieve this, but a more convenient way is to put your box-printing
900
into the entry point AfterPrompt (called at this time each turn).
901
902
Exercise 88
903
-----------
904
905
Implement a routine Quote(n) which will arrange for the n-th
906
quotation (where 0 <= n <= 49) to be displayed at the end of this turn,
907
provided it hasn't been quoted before.
908
909
*Note Answer 88::
910
911
Sometimes one would like to provide a menu of text options (for
912
instance, when producing instructions which have several topics, or
913
when giving clues). This can be done with the DoMenu routine, which
914
imitates the traditional "Invisiclues" style. By setting pretty_flag=0
915
you can make a simple text version instead; a good idea for machines
916
with very small screens. Here is a typical call to DoMenu:
917
918
DoMenu("There is information provided on the following:^
919
^ Instructions for playing
920
^ The history of this game
921
^ Credits^",
922
HelpMenu, HelpInfo);
923
924
Note the layout, and especially the carriage returns. The second and
925
third arguments are themselves routines. (Actually the first argument
926
can also be a routine to print a string instead of the string itself,
927
which might be useful for adaptive hints.) The HelpMenu routine is
928
supposed to look at the variable menu_item. In the case when this is
929
zero, it should return the number of entries in the menu (3 in the
930
example). In any case it should set item_name to the title for the
931
page of information for that item; and item_width to half its length in
932
characters (this is used to centre titles on the screen). In the case
933
of item 0, the title should be that for the whole menu.
934
935
The second routine, HelpInfo above, should simply look at menu_item
936
(1 to 3 above) and print the text for that selection. After this
937
returns, normally the game prints "Press [Space] to return to menu" but
938
if the value 2 is returned it doesn't wait, and if the value 3 is
939
returned it automatically quits the menu as if Q had been pressed.
940
This is useful for juggling submenus about.
941
942
Menu items can safely launch whole new menus, and it is easy to make
943
a tree of these (which will be needed when it comes to providing hints
944
across any size of game).
945
946
Exercise 89
947
-----------
948
949
Code an "Invisiclues"-style sequence of hints for a puzzle, revealed
950
one at a time, as a menu item.
951
952
*Note Answer 89::
953
954
Finally, you can change the text style. The statement for this is
955
style and its effects are loosely modelled on the VT100 (design of
956
terminal). The style can be style roman, style bold, style reverse or
957
style underline. Again, poor terminals may not be able to display
958
these, so you shouldn't hide crucial information in them.
959
960
References
961
----------
962
963
* `Advent' contains a menu much like that above.
964
965
* The "Infoclues" utility program translates UHS format hints (a
966
standard, easy to read and write layout) into an Inform file of
967
calls to DoMenu which can simply be included into a game; this
968
saves a good deal of trouble.
969
970
971
File: inform, Node: Assembly Language, Prev: Boxes, Up: Testing and Hacking
972
973
Descending into assembly language
974
=================================
975
976
!!!!!! Some dirty tricks require bypassing all of Inform's higher levels
977
to program the Z-machine directly with assembly language. There is an
978
element of danger in this, in that some combinations of unusual opcodes
979
might look ugly on some incomplete or wrongly-written interpreters: so
980
if you're doing anything complicated, test it as widely as possible.
981
982
The best-researched and most reliable interpreters available by far are
983
Mark Howell's Zip and Stefan Jokisch's Frotz: they are also faster than
984
their only serious rival, the InfoTaskForce, a historically important
985
work which is fairly thorough (and should give little trouble in
986
practice) but which was written when the format was a little less well
987
understood. In some ports, ITF gets rarer screen effects wrong, and it
988
lacks an "undo" feature, so the Inform "undo" verb won't work under ITF.
989
(The other two publically-available interpreters are pinfocom and zterp,
990
but these are unable to run Advanced games. In the last resort,
991
sometimes it's possible to use one of Infocom's own supplied
992
interpreters with a different game from that it came with; but only
993
sometimes, as they may have inconvenient filenames `wired into them'.)
994
995
Interpreters conforming to the Z-Machine Standard, usually but not
996
always derived from Frotz or Zip, are reliable and widely available.
997
But remember that one source of unportability is inevitable. Your game
998
may be running on a screen which is anything from a 64 characters by 9
999
pocket organiser LCD display, up to a 132 by 48 window on a 21-inch
1000
monitor.
1001
1002
Anyone wanting to really push the outer limits (say, by implementing
1003
Space Invaders or NetHack) will need to refer to The Z-Machine
1004
Standards Document. This is much more detailed (the definition of
1005
aread alone runs for two pages) and covers the whole range of assembly
1006
language. However, this section does document all those features which
1007
can't be better obtained with higher-level code.
1008
1009
Lines of assembly language must begin with an @ character and then the
1010
name of the "opcode" (i.e., assembly language statement). A number of
1011
arguments, or "operands" follow (how many depends on the opcode): these
1012
may be any Inform constants, local or global variables or the stack
1013
pointer sp, but may not be compound expressions. sp does not behave
1014
like a variable: writing a value to it pushes that value onto the
1015
stack, whereas reading the value of it (for instance, by giving it as
1016
an operand) pulls the top value off the stack. Don't use sp unless you
1017
have to. After the operands, some opcodes require a variable (or sp)
1018
to write a result into. The opcodes documented in this section are as
1019
follows:
1020
1021
@split_window lines
1022
@set_window window
1023
@set_cursor line column
1024
@buffer_mode flag
1025
@erase_window window
1026
@set_colour foreground background
1027
@aread text parse time function <result>
1028
@read_char 1 time function <result>
1029
@tokenise text parse dictionary
1030
@encode_text ascii-text length from coded-text
1031
@output_stream number table
1032
@input_stream number
1033
@catch <result>
1034
@throw value stack-frame
1035
@save buffer length filename <result>
1036
@restore buffer length filename <result>
1037
1038
@split_window lines
1039
1040
Splits off an upper-level window of the given number of lines in height
1041
from the main screen. This upper window usually holds the status line
1042
and can be resized at any time: nothing visible happens until the
1043
window is printed to. Warning: make the upper window tall enough to
1044
include all the lines you want to write to it, as it should not be
1045
allowed to scroll.
1046
1047
@set_window window
1048
1049
The text part of the screen (the lower window) is "window 0", the
1050
status line (the upper one) is window 1; this opcode selects which one
1051
text is to be printed into. Each window has a "cursor position" at
1052
which text is being printed, though it can only be set for the upper
1053
window. Printing on the upper window overlies printing on the lower,
1054
is always done in a fixed-pitch font and does not appear in a printed
1055
transcript of the game. Note that before printing to the upper window,
1056
it is wise to use @buffer_mode to turn off word-breaking.
1057
1058
@set_cursor line column
1059
1060
Places the cursor inside the upper window, where (1,1) is the top left
1061
character.
1062
1063
@buffer_mode flag
1064
1065
This turns on (flag=1) or off (flag=0) word-breaking for the current
1066
window (that is, the practice of printing new-lines only at the ends of
1067
words, so that text is neatly formatted). It is wise to turn off
1068
word-breaking while printing to the upper window.
1069
1070
@erase_window window
1071
1072
This opcode is unfortunately incorrectly implemented on some
1073
interpreters and so it can't safely be used to erase individual
1074
windows. However, it can be used with window=-1, and then clears the
1075
entire screen. Don't do this in reverse video mode, as a bad
1076
interpreter may (incorrectly) wipe the entire screen in reversed
1077
colours.
1078
1079
@set_colour foreground background
1080
1081
If coloured text is available, set text to be
1082
foreground-against-background. The colour numbers are borrowed from
1083
the IBM PC:
1084
1085
2 = black, 3 = red, 4 = green, 5 = yellow,
1086
6 = blue, 7 = magenta, 8 = cyan, 9 = white
1087
0 = the current setting, 1 = the default.
1088
1089
On many machines coloured text is not available: the opcode will then
1090
do nothing.
1091
1092
@aread text parse time function <result>
1093
1094
The keyboard can be read in remarkably flexible ways. This opcode
1095
reads a line of text from the keyboard, writing it into the text string
1096
array and `tokenising' it into a word stream, with details stored in
1097
the parse string array (unless this is zero, in which case no
1098
tokenisation happens). (See the end of *Note Grammar Tokens:: for the
1099
format of text and parse.) While it is doing this, it calls
1100
function(time) every time tenths of a second while the user is thinking:
1101
the process ends if ever this function returns true. <result> is to be
1102
a variable, but the value written in it is only meaningful if you're
1103
using a "terminating characters table". Thus (by Replaceing the
1104
Keyboard routine in the library files) you could, say, move around all
1105
the characters every ten seconds of real time. Warning: not every
1106
interpreter supports this real-time feature, and most of those that do
1107
count in seconds instead of tenths of seconds.
1108
1109
@read_char 1 time function <result>
1110
1111
results in the ASCII value of a single keypress. Once again, the
1112
function is called every time tenths of a second and may stop this
1113
process early. Function keys return special values from 129 onwards,
1114
in the order: cursor up, down, left, right, function key f1, ..., f12,
1115
keypad digit 0, ..., 9. The first operand must be 1 (used by Infocom
1116
as a device number to identify the keyboard).
1117
1118
@tokenise text parse dictionary
1119
1120
This takes the text in the text buffer (in the format produced by aread)
1121
and tokenises it (i.e. breaks it up into words, finds their addresses
1122
in the dictionary) into the parse buffer in the usual way but using the
1123
given dictionary instead of the game's usual one. (See the Z-Machine
1124
Standards Document for the dictionary format.)
1125
1126
@encode_text ascii-text length from coded-text
1127
1128
Translates an ASCII word to the internal (Z-encoded) text format
1129
suitable for use in a @tokenise dictionary. The text begins at from in
1130
the ascii-text and is length characters long, which should contain the
1131
right length value (though in fact the interpreter translates the word
1132
as far as a 0 terminator). The result is 6 bytes long and usually
1133
represents between 1 and 9 letters.
1134
1135
@output_stream number table
1136
1137
Text can be output to a variety of different `streams', possibly
1138
simultaneously. If number is 0 this does nothing. +n switches stream
1139
n on, -n switches it off. The output streams are: 1 (the screen), 2
1140
(the game transcript), 3 (memory) and 4 (script of player's commands).
1141
The table can be omitted except for stream 3, when it's a table array
1142
holding the text printed; printing to this stream is never word-broken,
1143
whatever the state of @buffer_mode.
1144
1145
@input_stream number
1146
1147
Switches the `input stream' (the source of the player's commands). 0
1148
is the keyboard, and 1 a command file (the idea is that a list of
1149
commands produced by output_stream 4 can be fed back in again).
1150
1151
@catch <result>
1152
1153
The opposite of throw, catch preserves the "stack frame" of the current
1154
routine: meaning, roughly, the current position of which routine is
1155
being run and which ones have called it so far.
1156
1157
@throw value stack-frame
1158
1159
This causes the program to execute a return with value, but as if it
1160
were returning from the routine which was running when the stack-frame
1161
was caught (see catch). Any routines which were called in the mean
1162
time and haven't returned yet (because each one called the next) are
1163
forgotten about. This is useful to get the program out of large
1164
recursive tangles in a hurry.
1165
1166
@save buffer length filename <result>
1167
1168
Saves the byte array buffer (of size length) to a file, whose (default)
1169
name is given in the filename (a string array). Afterwards, result
1170
holds 1 on success, 0 on failure.
1171
1172
@restore buffer length filename <result>
1173
1174
Loads in the byte array buffer (of size length) from a file, whose
1175
(default) name is given in the filename (a string array). Afterwards,
1176
result holds the number of bytes successfully read.
1177
1178
*Warning:* Some of these features may not work well on obsolete
1179
interpreters which do not adhere to the Z-Machine Standard. Standard
1180
interpreters are widely available, but if seriously worried you can
1181
test whether your game is running on a good interpreter:
1182
1183
if (standard_interpreter == 0)
1184
{ print "This game must be played on an interpreter obeying the
1185
Z-Machine Standard.^";
1186
@quit;
1187
}
1188
1189
Exercise 90
1190
-----------
1191
1192
In a role-playing game campaign, you might want several scenarios,
1193
each implemented as a separate Inform game. How could the character
1194
from one be saved and loaded into another?
1195
1196
*Note Answer 90::
1197
1198
!! Exercise 91
1199
--------------
1200
1201
Design a title page for `Ruins', displaying a more or less apposite
1202
quotation and waiting for a key to be pressed.
1203
1204
*Note Answer 91::
1205
1206
!! Exercise 92
1207
--------------
1208
1209
Change the status line so that it has the usual score/moves
1210
appearance except when a variable invisible_status is set, when it's
1211
invisible.
1212
1213
*Note Answer 92::
1214
1215
!! Exercise 93
1216
--------------
1217
1218
Alter the `Advent' example game to display the number of treasures
1219
found instead of the score and turns on the status line.
1220
1221
*Note Answer 93::
1222
1223
!! Exercise 94
1224
--------------
1225
1226
(From code by Joachim Baumann.) Put a compass rose on the status
1227
line, displaying the directions in which the room can be left.
1228
1229
*Note Answer 94::
1230
1231
!!!! Exercise 95
1232
----------------
1233
1234
(Cf. `Trinity'.) Make the status line consist only of the name of
1235
the current location, centred in the top line of the screen.
1236
1237
*Note Answer 95::
1238
1239
!!!! Exercise 96
1240
----------------
1241
1242
Implement an Inform version of the standard `C' routine printf,
1243
taking the form
1244
1245
printf(format, arg1, ...)
1246
1247
to print out the format string but with escape sequences like %d
1248
replaced by the arguments (printed in various ways). For example,
1249
1250
printf("The score is %e out of %e.", score, MAX_SCORE);
1251
1252
should print something like "The score is five out of ten."
1253
1254
*Note Answer 96::
1255
1256
References
1257
----------
1258
1259
* The assembly-language connoisseur will appreciate `Freefall' by
1260
Andrew Plotkin and `Robots' by Torbjorn Andersson, although the
1261
present lack of on-line hints make these difficult games to win.
Loggerhead is a web-based interface for Breezy
Version: 2.0.1