7 .. image:: /images/picN.png
14 obody understands the phrase *errare humanum est* quite in the same way
15 as a programmer does. Computers are highly efficient machines capable of
16 wondrous calculations, but they lack imagination and insist that every
17 single item thrown at them must be presented according to certain rules
18 previously defined. You can't negotiate with a computer; you either bow
19 in submission or bite the dust.
21 Inform behaves no differently. If you make a typing or syntax mistake,
22 the compiler will send you back to revise your work. "It was just a
23 lousy comma!" you cry in disgust. The compiler remains silent. It has
24 nothing to gain by argument, because it’s always right. So you go and
25 change the lousy comma. No harm done except perhaps to your pride.
27 Errors that are found during compilation may be tedious to correct, but
28 are usually easy to find; after all, the compiler tries politely to
29 point out what and where the mistake was. Trouble begins after you've
30 managed to satisfy all of the compiler's complaints. You are rewarded by
31 a clean screen, devoid of a list of errors, and you are offered -- a
34 A new file has appeared in your folder. A story file. Yes, *the* game.
35 You quickly open your favourite interpreter and begin to play -- only to
36 discover the dark side of errors, the bugs. Bugs come in all shapes,
37 colours and sizes: big, small, stupid, absurd, minor, disturbing,
38 nerve-wracking and catastrophic. They are often unpredictable: they
39 regale our eyes with surprising, unexpected behaviour. They defy logic:
40 I can TAKE the key, and the game even says "Taken", but the key remains
41 in the same place and won't appear in my inventory. Or: opening the door
42 while wearing the fur coat causes a programming error and a cryptic
43 message "tried to find the attribute of nothing". And many, many others.
45 When designing a game you try to take into consideration the states that
46 your objects will find themselves in, but any medium-sized game has such
47 a number of objects and actions that it's almost impossible to think of
48 all the possible variations, permutations and possibilities.
50 Debugging consists in finding run-time errors, and then correcting them.
51 Pretty easy, you might think, but no. Detection of such errors is not
52 straightforward, since they tend to manifest themselves only under
53 precise circumstances. Then you have to investigate your code to find
54 out what is causing them. And then, if you discover the offending lines,
55 you must make the appropriate changes. (There is also the case when you
56 can't find the mistake. Don't worry, it's there somewhere. Persistence
57 always pays off in the end.)
59 To help you out in this daunting task, Inform has a stock of special
60 actions: the debugging verbs. They become available at run-time when the
61 source file is compiled in :term:`Debug mode` (:option:`-D` switch). When
62 you are ready to release your game, you’ll have to recompile, switching off
63 Debug to avoid allowing the players to benefit from the debugging verbs.
64 We'll cover briefly a few of these actions, and tell you what they do.
69 The only way to test a game is to play it. As you make progress writing
70 code, the game grows complicated, and it becomes really tiresome to
71 repeat all the commands every time you play. Not unusually, when you fix
72 the behaviour of some object, you are also affecting the behaviour of
73 other objects or actions, so it's a good idea to test everything now and
74 then; you have to make sure that your recent changes and fixes didn't
75 spoil something that previously worked fine.
77 The RECORDING command (RECORDING ON and RECORDING OFF) saves the
78 commands that you type as you play into a text file (you'll probably be
79 prompted for a file name). When you add a new section to the game, you
80 can play to that point, type RECORDING ON to capture (in another file)
81 the commands which exercise that section, and then later use your editor
82 to append those new commands to the existing list.
84 The REPLAY command runs the text file created by RECORDING, playing all
85 the stored commands in one go. This way you can very quickly check
86 whether everything is working as it should.
88 You can open the file of commands with any text editor program and
89 modify the contents as need arises: for instance, if you want to delete
90 some commands no longer necessary because of a change to the game, or if
91 you forgot to test some particular object and you need to add new
94 This technique (the use of recorded lists of commands) is, and we can't
95 emphasise it too strongly, one of the most useful testing features for a
102 Some debugging verbs offer information about the current state of things.
106 This action lists all the objects in the game and how they contain
107 each other. You can discover the possessions of just one object by
108 typing TREE *object*. All the objects that you have defined in the
109 source file are turned into numbers by Inform when it compiles the
110 story file; this command also lists those internal
111 :samp:`{obj_id}` numbers.
115 Displays information about the *object*, the attributes it currently
116 has and the value of its properties. The *object* can be anywhere,
117 not necessarily in scope. For instance, in "Heidi":
119 .. code-block:: transcript
122 Object "bird's nest" (29) in "yourself"
123 has container moved open workflag
124 with name 'bird's' 'nest' 'twigs' 'moss',
125 description "The nest is carefully woven of twigs and moss." (19230),
129 Displays the grammar of the *verb*, just like a standard ``Verb``
130 definition. This comes in handy when you have tampered with ``Extend``
131 and are not sure about the final results of your machinations. An
132 example from "William Tell":
134 .. code-block:: transcript
137 Verb 'feed' 'give' 'offer' 'pay'
138 * held 'to' creature -> Give
139 * creature held -> Give reverse
140 * 'over' held 'to' creature -> Give
141 * 'homage' 'to' noun -> Salute
143 The first lines reproduce the verb definition as it's written in the
144 library. The last line, however, is the direct consequence of our
147 .. code-block:: inform
150 * 'homage' 'to' noun -> Salute;
154 Lists all of the objects currently in scope (in general terms, visible
155 to the player character). More powerfully, you can type SCOPE *object*
156 to discover which objects are in scope for the named *object*. This
157 feature becomes useful when you have NPCs capable of tampering with
161 What on earth is going on?
162 ==========================
164 There comes the time when some actions don't produce the desired effects
165 and you don't know why. The following debugging verbs offer information
166 about what the interpreter is up to, which might enable you to identify
167 the moment when things started to go awry.
169 ACTIONS (or ACTIONS ON ) and ACTIONS OFF
171 Gives information about all the actions going on. Some actions get
172 redirected to others, and this becomes at times a source of mischief
173 and mystery; here you get a clue what's happening. For example, take
174 this transcript from "William Tell":
176 .. code-block:: transcript
178 Further along the street
179 People are still pushing and shoving their way from the southern gate towards
180 the town square, just a little further north. You recognise the owner of a fruit
183 Helga pauses from sorting potatoes to give you a cheery wave.
186 [ Action Search with noun 35 (fruit and vegetable stall) ]
187 [ Action Examine with noun 35 (fruit and vegetable stall) (from < > statement) ]
188 It's really only a small table, with a big heap of potatoes, some carrots and
189 turnips, and a few apples.
192 CHANGES (or CHANGES ON ) and CHANGES OFF
194 Tracks object movements, and changes to properties and attributes:
196 .. code-block:: transcript
199 There is less of a crush in the middle of the square; most people prefer to
200 keep as far away as possible from the pole which towers here, topped with that
201 absurd ceremonial hat. A group of soldiers stands nearby, watching everyone who
205 [Setting Middle of the square.warnings_count to 1]
206 A soldier bars your way.
208 "Oi, you, lofty; forgot yer manners, didn't you? How's about a nice salute for
212 [Setting Middle of the square.warnings_count to 2]
214 "I know you, Tell, yer a troublemaker, ain't you? Well, we don't want no bovver
215 here, so just be a good boy and salute the friggin' hat. Do it now: I ain't
216 gonna ask you again..."
219 [Setting hat on a pole.has_been_saluted to 1]
220 You salute the hat on the pole.
222 "Why, thank you, sir," sneers the soldier.
225 [Setting Middle of the square.warnings_count to 0]
226 [Setting hat on a pole.has_been_saluted to 0]
227 [Moving yourself to South side of the square]
230 TIMERS (or TIMERS ON ) and TIMERS OFF
232 This verb shows you the state of all active timers and daemons at the
233 end of each turn. We haven't mentioned timers -- similar to daemons --
234 in this guide; you might perhaps use one to explode a bomb ten turns
235 after lighting its fuse.
237 TRACE (or TRACE ON ), TRACE *number* and TRACE OFF
239 If you turn on this powerful verb, you'll be able to follow the activity
240 of the :term:`parser` -- that part of the library which tries to make
241 sense of what the player types -- and this will indeed be a wonderful
242 moment of gratitude that someone else took the trouble of writing
243 it. Since the parser does so many things, you can decide the level of
244 detail about the displayed information with the *number* parameter, which
245 can go from 1 (minimum info) to 5 (maximum info). By default, TRACE ON
246 and TRACE with no number sets level 1. Trace level 1 shows the grammar
247 line that the parser is thinking about, while level 2 shows each
248 individual token on each grammar line that it tries. The information
249 displayed with higher levels may become quite hacky, and you are advised
250 to use this feature only if nothing else helps.
257 This action lets you teleport to the room where the *object* is. This
258 is useful when, for example, certain parts of the map are closed
259 until the player character solves some puzzle, or if the game map is
260 divided in different areas. If the room you want to visit has no
261 objects, you can use...
265 Teleports you to the room with that internal *number*. Since rooms
266 usually have no name, you'll have to discover the internal number of
267 the room object (with the command TREE, for instance).
271 .. Generated by autoindex
273 pair: scenery; library attribute
274 pair: static; library attribute
276 PURLOIN works exactly as TAKE , with the nice addition that it doesn't
277 matter where the object is: in another room, inside a locked
278 container, in the claws of the bloodthirsty dragon. More dangerously,
279 it doesn't matter if the object is takeable, so you may purloin
280 :attr:`static` or :attr:`scenery` objects. PURLOIN is useful in a variety of
281 situations, basically when you want to test a particular feature of
282 the game that requires the player character to have some objects
283 handy. Instead of tediously collecting them, you may simply PURLOIN
284 them. Be careful: it's unwise to PURLOIN objects not meant to be
285 taken, as the game's behaviour may become unpredictable.
287 ABSTRACT *object* TO *object*
289 .. Generated by autoindex
291 pair: animate; library attribute
292 pair: container; library attribute
293 pair: supporter; library attribute
295 This verb enables you to move the first *object* to the second
296 *object*. As with PURLOIN , both objects can be anywhere in the game.
297 Bear in mind that the second object should logically be a
298 :attr:`container`, a :attr:`supporter` , or something :attr:`animate`.
301 Infix: the harlot's prerogative
302 ===============================
304 The basic debugging verbs are fairly versatile, easy to use, and don't
305 consume a lot of memory. Occasionally though, you'll meet a bug which you
306 simply can't catch using regular techniques, and that’s when you might want
307 to investigate the Infix debugger. You'll need to compile using the
308 :option:`-X` switch, and you'll then be able to monitor and modify almost
309 all of your game’s data and objects. For instance, you can use ";" to
310 inspect -- and change -- a variable:
312 .. code-block:: transcript
315 Benny's offers the FINEST selection of pastries and sandwiches. Customers clog
316 the counter, where Benny himself manages to serve, cook and charge without
317 missing a step. At the north side of the cafe you can see a red door connecting
326 *** You have been SHAMEFULLY defeated ***
328 In that game you scored 0 out of a possible 2, in 2 turns.
330 It's often quite maddening to realise that some variable is still
331 :const:`false` because the Chalk puzzle didn't work properly, and that you
332 can't test the Cheese puzzle until the variable becomes :const:`true`. Rather
333 than quit, fix the Chalk, recompile, play back to the current position
334 and only *then* tackle the Cheese, how much easier to just change the
335 variable in mid-stream, and carry right on.
337 You can use ``;WATCH`` to monitor an object; you'll see it receive
338 messages and you'll be told when its property and attribute values
341 .. code-block:: transcript
344 ; Watching object "Middle of the square" (43).
347 [Moving yourself to Middle of the square]
348 [Moving local people to Middle of the square]
349 [Moving Gessler's soldiers to Middle of the square]
350 [Moving your son to Middle of the square]
353 There is less of a crush in the middle of the square; most people prefer to
354 keep as far away as possible from the pole which towers here, topped with that
355 absurd ceremonial hat. A group of soldiers stands nearby, watching everyone who
357 [Giving Middle of the square visited]
360 [ "Middle of the square".before() ]
361 [ mid_square.before() ]
362 [Setting Middle of the square.warnings_count to 1]
363 A soldier bars your way.
365 "Oi, you, lofty; forgot yer manners, didn't you? How's about a nice salute for
369 [ "Middle of the square".before() ]
370 [ mid_square.before() ]
371 [Setting Middle of the square.warnings_count to 2]
373 "I know you, Tell, yer a troublemaker, ain't you? Well, we don't want no bovver
374 here, so just be a good boy and salute the friggin' hat. Do it now: I ain't
375 gonna ask you again..."
378 [ "Middle of the square".before() ]
379 [ mid_square.before() ]
380 [Setting Middle of the square.warnings_count to 3]
382 "OK, Herr Tell, now you're in real trouble.
387 "Herr" above is italicized. Was that a mistake in the original text?
389 Update: I don't think so. In 08.rst, lines 465 and 516, "Herr" is
390 explicitly underlined (which probably appears italicized on output).
392 Infix is quite complex -- there are more commands than those we have
393 shown you -- so while it's good to have available, it's not really a
394 tool for novices. If you do use it, be careful: you get a lot of runtime
395 power, and may easily screw up the state of the game. Remember, however,
396 that the changes affect only the current story file while it’s running;
397 to make permanent amendments, you still need to edit the source file.
399 You won't need it often, but Infix can sometimes provide quick answers
405 Your game will still have some undetected bugs despite all your efforts
406 to clean it up. This is normal, even for experienced designers; don't
407 feel discouraged or demoralised. You might find it reassuring to know
408 that our own example games in this guide -- which certainly don't
409 qualify as "complex programming" -- were far from perfect at the First
410 Edition. We blush at the following report from an extremely diligent
413 I found these things when playing “Captain Fate”:
415 * player is able to wear clothes over the costume,
417 * player can change into costume in the dark unlocked bathroom without
420 * player can drop clothes in the dark unlocked bathroom. Try REMOVE
421 CLOTHES. X SELF. REMOVE COSTUME. INV -- X SELF says that you
422 are wearing the costume, but the inventory does not reflect this.
424 The Second Edition fixed those problems, and quite a few more besides.
425 "That's it;" we thought, "after all this time, our example games are
426 sure to be squeaky clean." In our dreams... Another diligent play-tester
429 While reading I took notes of some mistakes and inconsistencies:
431 * BENNY, GIVE KEY TO CUSTOMERS and BENNY, GIVE KEY will
432 make Benny give the key to the player. The same goes for coffee.
434 * Benny will force the player back into the cafe even when the key is
435 dropped in the café, or put on the counter (in Benny's plain sight!).
437 Of course, the code we've offered you in *this* edition takes care of
438 those embarrassing issues, but it might very well happen that a few more
439 undetected absurdities pop up from now on.
441 .. Generated by autoindex
445 The final stage of debugging must happen elsewhere, at the hands of some
446 wilful, headstrong and determined beta-testers; these are the people
447 who, if you’re lucky, will methodically tear your game to shreds and
448 make extensive reports of things that don't work reliably, things that
449 don't work as smoothly as they might, things that ought to work but
450 don't, things that never even crossed your mind (like, uh, dropping the
451 costume in the dark). Once you think your game is finished -- in that it
452 does all that you think it should, and you've run out of ideas on how
453 else to test it -- look for a few beta-testers; three or four is good.
454 The IF community offers some beta-testing resources, or you can always
455 ask in RAIF for kind souls willing to have a go at your game. Remember
458 * **Expect no mercy**. Although it hurts, a merciless approach is what you
459 need at this time; much better to discover your errors and oversights
460 now, before you release the game more widely. And don't forget to
461 acknowledge your testers' assistance somewhere within the game.
463 * **Never say never**. If your testers suggest that the game should
464 respond better to an attempted action, don't automatically respond with
465 "No one's going to try that!" They already have, and will again -- be
466 grateful for your testers' devious minds and twisted psyches. Although a
467 normal player won't try *all* of those oddball things, every player is
468 bound to try at least *one*, and their enjoyment will be greater, the
469 reality enhanced, if the game "understands".
471 * **Ask for more**. Don't treat your testers simply as validators of your
472 programming skills, but rather as reviewers of your storytelling
473 abilities. Encourage them to comment on how well the pieces fit together,
474 and to make suggestions -- small or radical -- for improvement; don't
475 necessarily reject good ideas just because implementing them "will take
476 too long". For example: "the scene in the Tower of London doesn't somehow
477 seem to belong in an Arabian Nights game", or "having to solve three
478 puzzles in a row just to discover the plate of sheep's eyes is a little
479 over the top", or "this five-room trek across the desert really is a bit
480 dull; perhaps you could add a quicksand or something to liven it up?", or
481 "the character of the eunuch in the harem seems to be lacking in
482 something". That is, view the testers collectively not as simple
483 spell-checkers, but rather as collaborative editors on your latest novel.