1 ===============================
2 William Tell: the early years
3 ===============================
9 | |CENTER| *M was a miser, and hoarded up gold;*
10 | |CENTER| *N was a nobleman, gallant and bold.*
14 .. image:: /images/picM.png
17 |M|\oving along swiftly, we'll define the first two rooms and populate them
18 with assorted townspeople and street furniture, we'll equip Wilhelm with
19 his trusty bow and quiver of arrows, and we'll introduce Helga the friendly
25 This is the street room, the location where the game starts::
27 Room street "A street in Altdorf"
29 print "The narrow street runs north towards the town square.
30 Local folk are pouring into the town through the gate to the
31 south, shouting greetings, offering produce for sale,
32 exchanging news, enquiring with exaggerated disbelief about
33 the prices of the goods displayed by merchants whose stalls
34 make progress even more difficult.^";
35 if (self hasnt visited)
36 print "^~Stay close to me, son,~ you say,
37 ~or you'll get lost among all these people.~^";
41 "The crowd, pressing north towards the square,
42 makes that impossible.";
44 We're using our new ``Room`` class, so there's no need for a :attr:`light`
45 attribute. The :prop:`n_to` and :prop:`s_to` properties, whose values are
46 an internal ID and a string respectively, are techniques we've used before.
47 The only innovation is that the :prop:`description` property has an
48 embedded routine as its value.
50 The first thing in that routine is a ``print`` statement, displaying
51 details of the street surroundings. If that was all that we wanted to do,
52 we could have supplied those details by making the :prop:`description`
53 value a string; that is, these two examples behave identically::
56 print "The narrow street runs north towards the town square.
57 Local folk are pouring into the town through the gate to the
58 south, shouting greetings, offering produce for sale,
59 exchanging news, enquiring with exaggerated disbelief about
60 the prices of the goods displayed by merchants whose stalls
61 make progress even more difficult.^";
65 "The narrow street runs north towards the town square.
66 Local folk are pouring into the town through the gate to the
67 south, shouting greetings, offering produce for sale,
68 exchanging news, enquiring with exaggerated disbelief about
69 the prices of the goods displayed by merchants whose stalls
70 make progress even more difficult.",
72 However, that *isn't* all that we want to do. Having presented the basic
73 description, we're going to display that little line of dialogue, where
74 Wilhelm tells his son to be careful. And we want to do that only once, the
75 very first time that the street's description is displayed. If the player
76 types LOOK a few times, or moves north and then returns south to the
77 street, we're happy to see the surroundings described -- but we don't want
78 that dialogue again. This is the pair of statements that makes it happen::
80 if (self hasnt visited)
81 print "^~Stay close to me, son,~ you say,
82 ~or you'll get lost among all these people.~^";
84 The line of dialogue is produced by the ``print`` statement, the ``print``
85 statement is controlled by the ``if`` statement, and the ``if`` statement
86 is performing the test ``self hasnt visited``. In detail:
88 .. Generated by autoindex
90 pair: visited; library attribute
92 * :attr:`visited` is an attribute, but not one that you'd normally give to an
93 object yourself. It's automatically applied to a room object by the
94 interpreter, but only after that room has been visited for the first
97 * ``hasnt`` (and ``has``) are available for testing whether a given
98 attribute is currently set for a given object. :samp:`{X} has {Y}` is
99 true if object :samp:`{X}` currently has attribute :samp:`{Y}`, false if
100 it doesn't. To make the test in reverse, :samp:`{X} hasnt {Y}` is true
101 if object :samp:`{X}` currently does not have attribute :samp:`{Y}`,
104 .. Generated by autoindex
106 pair: self; library variable
108 * :var:`self`, which we met in the previous chapter, is that useful variable
109 which, within an object, always refers to that object. Since we're using
110 it in the middle of the ``street`` object, that's what it refers to.
112 So, putting it all together, ``self hasnt visited`` is true (and therefore
113 the ``print`` statement is executed) only while the ``street`` object has
114 *not* got a :attr:`visited` attribute. Because the interpreter
115 automatically gives rooms a :attr:`visited` attribute as soon as the player
116 has been there once, this test will be true only for one turn. Therefore,
117 the line of dialogue will be displayed only once: the first time the player
118 visits the street, at the very start of the game.
120 Although the primary importance of :var:`self` is within class definitions,
121 it can also be convenient to use it simply within an object. Why didn't we
124 if (street hasnt visited)
125 print "^~Stay close to me, son,~ you say,
126 ~or you'll get lost among all these people.~^";
128 It's true that the effect is identical, but there are a couple of good
129 reasons for using :var:`self`. One: it's an aid to understanding your code
130 days or weeks after writing it.
132 If you read the line ``if (street hasnt visited)``, you need to think for a
133 moment about which object is being tested; oh, it's this one. When you
134 read ``if (self hasnt visited)``, you immediately *know* which object we're
137 Another reason is auto-plagiarism. Many times you'll find that a chunk of
138 code is useful in different situations (say, you want to repeat the
139 mechanics of the street description in another room). Rather than writing
140 everything from scratch, you'll typically use copy-and-paste to repeat the
141 routine, and then all you have to do is compose the appropriate descriptive
142 strings for the new room. If you've used :var:`self`, the line ``if (self
143 hasnt visited)`` is still good; if you've written instead ``if (street
144 hasnt visited)``, you'll have to change that as well. Worse, if you
145 *forget* to change it, the game will still work -- but not in the way you'd
146 intended, and the resulting bug will be quite difficult to track down.
153 The street's description mentions various items -- the gate, the people,
154 etc. -- which ought to exist within the game (albeit only in minimal form)
155 to sustain the illusion of hustle and bustle. Our ``Prop`` class is ideal
158 Prop "south gate" street
159 with name 'south' 'southern' 'wooden' 'gate',
160 description "The large wooden gate in the town walls is wide open.";
162 Prop "assorted stalls"
163 with name 'assorted' 'stalls',
164 description "Food, clothing, mountain gear; the usual stuff.",
165 found_in street below_square,
169 with name 'goods' 'produce' 'food' 'clothing' 'mountain' 'gear' 'stuff',
170 description "Nothing special catches your eye.",
171 found_in street below_square,
175 with name 'merchant' 'merchants' 'trader' 'traders',
177 "A few crooks, but mostly decent traders touting their wares
178 with raucous overstatement.",
179 found_in street below_square,
180 has animate pluralname;
183 with name 'people' 'folk' 'local' 'crowd',
184 description "Mountain folk, just like yourself.",
185 found_in [; return true; ],
186 has animate pluralname;
190 Because these objects are not referenced by other objects, we haven't
191 bothered to given them internal :samp:`{obj_ids}` (though we could have;
192 it wouldn't make any difference). However, we *have* provided
193 :samp:`{external_names}`, because these are used by the ``Prop`` class's
194 ``print_ret ... (the) self`` statement.
196 .. Generated by autoindex
198 pair: pluralname; library attribute
200 You'll see a couple of new attributes: :attr:`animate` marks an object as
201 being "alive", while :attr:`pluralname` specifies that its external name is
202 plural rather than singular. The interpreter uses these attributes to
203 ensure that messages about such objects are grammatical and appropriate
204 (for example, it will now refer to "some merchants" rather than "a
205 merchants"). Because the library handles so many situations automatically,
206 it's hard to be sure exactly what messages players may trigger; the best
207 approach is to play safe and always give an object the relevant set of
208 attributes, even when, as here, they probably won't be needed.
210 .. Generated by autoindex
212 pair: found_in; library property
214 You'll also see a new :prop:`found_in` property, which specifies the rooms
215 -- and only the rooms; :prop:`found_in` shouldn't be used to place objects
216 inside containers or supporters -- where this object is to appear. The
217 stalls, for example, can be EXAMINEd both in the street and below the
218 square, so we *could* have created a ``Prop`` object in each room::
220 Prop "assorted stalls" street
221 with name 'assorted' 'stalls',
222 description "Food, clothing, mountain gear; the usual stuff.",
225 Prop "assorted stalls" below_square
226 with name 'assorted' 'stalls',
227 description "Food, clothing, mountain gear; the usual stuff.",
230 but :prop:`found_in` does the same job more neatly -- there's only one
231 object, but it appears in both the ``street`` and ``below_square`` rooms
232 while the player's there. The local people are even more ubiquitous. In
233 this case the :prop:`found_in` value is an embedded routine rather than a
234 list of rooms; such a routine would generally test the value of the current
235 location and ``return true`` if it wants to be present here, or
236 :const:`false` if not. Since we'd like the local people *always* to be
237 present, in every room, we ``return true`` without bothering to examine
238 :var:`location`. It's as though we'd written any of these, but simpler and
242 with name 'people' 'folk' 'local' 'crowd',
243 description "Mountain folk, just like yourself.",
244 found_in street below_square south_square mid_square north_square
246 has animate pluralname;
249 with name 'people' 'folk' 'local' 'crowd',
250 description "Mountain folk, just like yourself.",
252 if (location == street || location == below_square ||
253 location == south_square || location == mid_square ||
254 location == north_square || location == marketplace)
258 has animate pluralname;
261 with name 'people' 'folk' 'local' 'crowd',
262 description "Mountain folk, just like yourself.",
264 if (location == street or below_square or south_square or
265 mid_square or north_square or marketplace) return true;
268 has animate pluralname;
270 In the second example, you'll see the ``||`` operator, to be read as "or",
271 which we mentioned near the end of "Heidi"; it combines the various
272 :samp:`location == {some_room}` comparisons so that the ``if`` statement is
273 true if *any* of those individual tests is true. And in the third example
274 we introduce the ``or`` keyword, which is a more succinct way of achieving
275 exactly the same result.
279 The player's possessions
280 ========================
282 Since our ``Initialise`` routine has already mentioned them, we might as
283 well define Wilhelm's bow and arrows::
287 description "Your trusty yew bow, strung with flax.",
290 print_ret "You're never without your trusty bow.";
294 Object quiver "quiver"
297 "Made of goatskin, it usually hangs over your left shoulder.",
300 print_ret "But it was a present from Hedwig, your wife.";
302 has container open clothing;
304 Both of these are straightforward objects, with the :act:`Drop`,
305 :act:`Give` and :act:`ThrowAt` actions being intercepted to ensure that
306 Wilhelm is never without them. The :attr:`clothing` attribute makes its
307 first appearance, marking both the quiver and the bow as capable of being
308 worn (as the result of a WEAR BOW command, for instance); you'll remember
309 that our ``Initialise`` routine goes on to add a :attr:`worn` attribute to
312 An empty quiver is pretty useless, so here's the class used to define
313 Wilhelm's stock of arrows. This class has some unusual features::
316 with name 'arrow' 'arrows//p',
319 description "Just like all your other arrows -- sharp and true.",
322 print_ret "Your arrows are sharp, and you guard them carefully.";
325 The classes we've created so far -- ``Room``, ``Prop`` and ``Furniture`` --
326 are intended for objects which behave the same but are otherwise clearly
327 separate. For example, a table, a bed and a wardrobe would generally have
328 their own individual characteristics -- a name, a description, maybe some
329 specialised properties -- while still inheriting the general behaviour of
330 ``Furniture`` objects. The arrows aren't like this: not only do they
331 behave the same, but also they are indistinguishable one from another.
332 We're trying for this effect:
334 .. code-block:: transcript
338 a quiver (being worn)
342 where the interpreter lumps together our stock of three arrows, rather than
343 listing them individually in this clumsy fashion:
345 .. code-block:: transcript
349 a quiver (being worn)
355 The interpreter will do this for us if our objects are "indistinguishable",
356 best achieved by making them members of a class which includes both
357 :prop:`name` and :prop:`plural` properties. We define the actual arrows
358 very simply, like this::
360 Arrow "arrow" quiver;
361 Arrow "arrow" quiver;
362 Arrow "arrow" quiver;
364 and you can see that we provide only two pieces of information for each
365 ``Arrow`` object: an external name in double quotes ("arrow" in each case)
366 which the interpreter uses when referring to the object, and an initial
367 location (in the quiver). That's all: no block of properties, no set of
368 attributes, and no internal identifier, because we never need to refer to
369 the individual ``Arrow`` objects within the game.
371 The name property of the class definition has an odd-looking dictionary
374 name 'arrow' 'arrows//p',
376 The word ``'arrow'`` refers to a single arrow. So also would the word
377 ``'arrows'``, unless we specifically tell the interpreter that it's a
378 plural reference. That ``//p`` marks ``'arrows'`` as being a potential
379 reference to more than one object at once, thus enabling players to type
380 TAKE ARROWS and thereby pick up as many arrows as happened to be available
381 (without it, TAKE ARROWS would have picked up one at random).
383 There are two other properties not seen previously::
388 The :prop:`article` property lets you define the object's indefinite
389 article -- usually something like "a", "an" or "some" -- instead of letting
390 the library assign one automatically. It's a belt-and-braces (OK,
391 belt-and-suspenders) precaution: because "arrow" starts with a vowel, we
392 need to display "an arrow" not "a arrow". Most interpreters automatically
393 get this right, but just to be on the safe side, we explicitly define the
394 appropriate word. And the :prop:`plural` property defines the word to be
395 used when lumping several of these objects together, as in the "three
396 arrows" inventory listing. The interpreter can't just automatically slap
397 an "s" on the end; the plural of "slice of cake", for example, isn't "slice
400 Moving further along the street
401 ===============================
403 As Wilhelm moves north towards the square, he comes to this room::
405 Room below_square "Further along the street"
407 "People are still pushing and shoving their way from the southern
408 gate towards the town square, just a little further north.
409 You recognise the owner of a fruit and vegetable stall.",
413 No surprises there, nor in most of the supporting scenery objects. ::
415 Furniture stall "fruit and vegetable stall" below_square
416 with name 'fruit' 'veg' 'vegetable' 'stall' 'table',
418 "It's really only a small table, with a big heap of potatoes,
419 some carrots and turnips, and a few apples.",
420 before [; Search: <<Examine self>>; ],
423 Prop "potatoes" below_square
424 with name 'potato' 'potatoes' 'spuds',
426 "Must be a particularly early variety... by some 300 years!",
429 Prop "fruit and vegetables" below_square
430 with name 'carrot' 'carrots' 'turnip' 'turnips' 'apples' 'vegetables',
431 description "Fine locally grown produce.",
434 .. Generated by autoindex
436 pair: before; library property
438 The only new thing here is the :prop:`before` property of the fruit'n'veg
439 stall. The stall's description -- lots of items on a table -- may suggest
440 to players that they can SEARCH through the produce, maybe finding a lucky
441 beetroot or something else interesting. No such luck -- and we might as
442 well trap the attempt.
444 .. Generated by autoindex
446 pair: Examine; library action
447 pair: Search; library action
449 Having intercepted a :act:`Search` action, our plan is to respond with the
450 stall's description, as though the player has typed EXAMINE THE STALL.
451 There isn't an easy way for us to stealthily slide those literal words into
452 the interpreter, but we *can* simulate the effect which they'd cause: an
453 action of :act:`Examine` applied to the object stall. This rather cryptic
454 statement does the job::
458 Having diverted the :act:`Search` action into an :act:`Examine` action, we
459 must tell the interpreter that it doesn't need to do anything else, because
460 we've handled the action ourselves. We've done that before -- using
461 ``return true`` -- and so a first stab at the :prop:`before` action looks
464 before [; Search: <Examine stall>; return true; ],
466 .. Generated by autoindex
468 pair: self; library variable
470 The two-statement sequence ``<...>; return true`` is so common that there's
471 a single statement shortcut: ``<<...>>``. Also, for exactly the same
472 reason as before, our code is clearer if we use :var:`self` instead of
473 ``stall``. So this is how the property finally stands::
475 before [; Search: <<Examine self>>; ],
477 A couple of final observations before we leave this topic. The example
478 here is of an action (:act:`Examine`) applied to an object (:var:`self`,
479 though ``stall`` or :var:`noun` would also work at this point). You can
480 also use the ``<...>`` and ``<<...>>`` statements for actions which affect
485 (representing the command LOOK), or which affect two. For example, the
486 command PUT THE BIRD IN THE NEST can be simulated with this statement::
488 <<Insert bird nest>>;
493 .. Generated by autoindex
497 One of the trickiest aspects of designing a good game is to provide
498 satisfying interaction with other characters. It's hard enough to code
499 inanimate objects which provoke appropriate responses to whatever actions
500 the player character (PC) might attempt. That all gets much worse once
501 those "other objects" are living creatures -- non-player characters (NPCs)
502 -- with, supposedly, minds of their own. A good NPC might move around
503 independently, perform actions with a purpose, initiate conversations,
504 respond to what you say and do (and even to what you *don't* say or do); it
505 can be a real nightmare.
507 But not here: we've kept our three NPCs -- Helga, Walter and the vogt -- as
508 simple as possible. Nevertheless, we can establish some fundamental
509 principles; here's the class upon which we base our NPCs::
513 Answer,Ask,Order,Tell:
514 print_ret "Just use T[ALK] [TO ", (the) self, "].";
518 The most important thing here is the :attr:`animate` attribute -- that's
519 what defines an object as an NPC, and causes the interpreter to treat it a
520 little differently -- for example, TAKE HELGA results in "I don't suppose
521 Helga would care for that".
523 .. Generated by autoindex
525 pair: Ask; library action
526 pair: Attack; library action
527 pair: Kiss; library action
528 pair: Order; library action
529 pair: Show; library action
530 pair: Tell; library action
531 pair: ThrowAt; library action
532 pair: WakeOther; library action
533 pair: life; library property
535 The :attr:`animate` attribute also brings into play nine extra actions
536 which can be applied only to animate objects: :act:`Answer`, :act:`Ask`,
537 :act:`Order` and :act:`Tell` are all associated with speech, and
538 :act:`Attack`, :act:`Kiss`, :act:`Show`, :act:`ThrowAt` and
539 :act:`WakeOther` are associated with non-verbal interaction. Additionally,
540 a new :prop:`life` property -- very similar to :prop:`before` -- can be
541 defined to intercept them. Here we use it to trap speech-related commands
542 such as ASK HELGA ABOUT APPLE and TELL WALTER ABOUT BABIES, telling players
543 that in this game we've implemented only a simpler TALK verb (which we
544 describe in :ref:`verbs`).
546 Based on the NPC class we've created, here's Helga::
548 NPC stallholder "Helga" below_square
549 with name 'stallholder' 'greengrocer' 'monger' 'shopkeeper' 'merchant'
550 'owner' 'Helga' 'dress' 'scarf' 'headscarf',
552 "Helga is a plump, cheerful woman,
553 concealed beneath a shapeless dress and a spotted headscarf.",
555 print "Helga pauses from sorting potatoes
556 to give you a cheery wave.^";
557 if (location hasnt visited) {
558 move apple to player;
559 print "^~Hello, Wilhelm, it's a fine day for trade! Is this
560 young Walter? My, how he's grown. Here's an apple for him
561 -- tell him to mind that scabby part, but the rest's good
562 enough. How's Frau Tell? Give her my best wishes.~^";
565 times_spoken_to 0, ! for counting the conversation topics
568 self.times_spoken_to = self.times_spoken_to + 1;
569 switch (self.times_spoken_to) {
570 1: score = score + 1;
571 print_ret "You warmly thank Helga for the apple.";
572 2: print_ret "~See you again soon.~";
579 The new attributes are :attr:`female` -- because we want the interpreter to
580 refer to Helga with the appropriate pronouns -- and :attr:`proper`. The
581 latter signifies that this object's external name is a proper noun, and so
582 references to it should not be preceded by "a" or "the": you wouldn't want
583 to display "You can see a Helga here" or "I don't suppose the Helga would
584 care for that". You may notice the library variable :var:`score` being
585 incremented. This variable holds the number of points that the player has
586 scored; when it changes like this, the interpreter tells the player that
587 "Your score has just gone up by one point".
589 .. Generated by autoindex
591 pair: initial; library property
592 pair: times_spoken_to; library property
594 There are also :prop:`life` and :prop:`times_spoken_to` properties (which
595 we'll talk about in :doc:`09`) and an :prop:`initial` property.
597 :prop:`initial` is used when the interpreter is describing a room and listing
598 the objects initial you can see there. If we *didn't* define it, you'd get
601 .. code-block:: transcript
603 Further along the street
604 People are still pushing and shoving their way from the southern gate towards
605 the town square, just a little further north. You recognise the owner of a fruit
608 You can see Helga here.
612 but we want to introduce Helga in a more interactive manner, and that's
613 what the :prop:`initial` property is for: it replaces the standard "You can see
614 *object* here" with a tailored message of your own design. The value of an
615 :prop:`initial` property can be either a string which is to be displayed or, as
616 here, an embedded routine. This one is pretty similar to the
617 :prop:`description` property that we defined for the street: something that's
618 *always* printed (Helga pauses...) and something that's printed only on the
619 first occasion ("Hello, Wilhelm, it's a fine day... "):
621 .. code-block:: transcript
623 Further along the street
624 People are still pushing and shoving their way from the southern gate towards
625 the town square, just a little further north. You recognise the owner of a fruit
628 Helga pauses from sorting potatoes to give you a cheery wave.
630 "Hello, Wilhelm, it's a fine day for trade! Is this young Walter? My, how he's
631 grown. Here's an apple for him -- tell him to mind that scabby part, but the
632 rest's good enough. How's Frau Tell? Give her my best wishes."
636 But it's not quite the same as the street's description routine. First, we
637 need a slightly different ``if`` test: ``self hasnt visited`` works fine
638 for a room object, but this routine is part of an object *in* a room;
639 instead we could use either ``below_square hasnt visited`` or (better)
640 ``location hasnt visited`` -- since :var:`location` is the library variable
641 that refers to the room where the player currently is. And second, some
642 curly braces ``{...}`` have appeared: why?
644 On Wilhelm's first visit to this room, we need to do two things:
646 * ensure that Wilhelm is in possession of an apple, because that's
649 * display Helga's cheery greeting.
651 The ``move`` statement does the first of those, and the ``print`` statement
652 does the second. And both statements need to be controlled by the ``if``
653 statement. So far, we've used an ``if`` statement twice, in both cases to
654 control a single following statement. ::
656 if (nest in branch) deadflag = 2;
658 if (self hasnt visited)
659 print "^~Stay close to me, son,~ you say,
660 ~or you'll get lost among all these people.~^";
662 That's what an ``if`` does -- it controls whether the following statement
663 is executed or not. So how can we control two statements at once? Well,
664 we *could* write two ``if`` statements::
666 if (location hasnt visited)
667 move apple to player;
668 if (location hasnt visited)
669 print "^~Hello, Wilhelm, it's a fine day for trade! Is this
670 young Walter? My, how he's grown. Here's an apple for him
671 -- tell him to mind that scabby part, but the rest's good
672 enough. How's Frau Tell? Give her my best wishes.~^";
674 but that's unbearably clumsy; instead, we use the braces to group the
675 ``move`` and ``print`` statement into a :term:`statement block` (sometimes
676 known as a code block) which counts as a single statement for the purposes
677 of control by the ``if`` statement. ::
679 if (location hasnt visited) {
680 move apple to player;
681 print "^~Hello, Wilhelm, it's a fine day for trade! Is this
682 young Walter? My, how he's grown. Here's an apple for him
683 -- tell him to mind that scabby part, but the rest's good
684 enough. How's Frau Tell? Give her my best wishes.~^";
687 A statement block can contain one, two, ten, a hundred statements; it
688 doesn't matter -- they're all treated as one unit by ``if`` (and by
689 ``objectloop``, which we meet later, and by ``do``, ``for`` and ``while``,
690 all of them loop statements that we don't encounter in this guide).
694 The exact positioning of the braces is a matter of personal choice. We
703 but other designers have their own preferences, including::
724 Although we've not yet needed to use it, now would probably be a good time
725 to mention the ``else`` extension to the ``if`` statement. Sometimes we
726 want to execute one statement block if a certain condition is true, and a
727 different statement block if it's not true. Again, we *could* write two
730 if (location has visited) {
735 if (location hasnt visited) {
741 but that's hardly an elegant approach; an ``else`` clause does the job more
744 if (location has visited) {
755 We've done a lot of scene-setting, but the real action is still to come.
756 Next, it's time to define the town square, and create a confrontation
757 between Wilhelm and the vogt's soldiers. (But first, see again
758 :ref:`compile-as-you-go` if you're typing in the game as you read through