1 ===============================
2 William Tell: the early years
3 ===============================
9 | *M was a miser, and hoarded up gold;*
10 | *N was a nobleman, gallant and bold.*
14 .. image:: /images/picM.png
21 oving along swiftly, we'll define the first two rooms and populate them
22 with assorted townspeople and street furniture, we'll equip Wilhelm with
23 his trusty bow and quiver of arrows, and we'll introduce Helga the friendly
29 This is the street room, the location where the game starts::
31 Room street "A street in Altdorf"
33 print "The narrow street runs north towards the town square.
34 Local folk are pouring into the town through the gate to the
35 south, shouting greetings, offering produce for sale,
36 exchanging news, enquiring with exaggerated disbelief about
37 the prices of the goods displayed by merchants whose stalls
38 make progress even more difficult.^";
39 if (self hasnt visited)
40 print "^~Stay close to me, son,~ you say,
41 ~or you'll get lost among all these people.~^";
45 "The crowd, pressing north towards the square,
46 makes that impossible.";
48 We're using our new ``Room`` class, so there's no need for a ``light``
49 attribute. The ``n_to`` and ``s_to`` properties, whose values are an
50 internal ID and a string respectively, are techniques we've used before.
51 The only innovation is that the ``description`` property has an embedded
54 The first thing in that routine is a ``print`` statement, displaying
55 details of the street surroundings. If that was all that we wanted to do,
56 we could have supplied those details by making the ``description`` value a
57 string; that is, these two examples behave identically::
60 print "The narrow street runs north towards the town square.
61 Local folk are pouring into the town through the gate to the
62 south, shouting greetings, offering produce for sale,
63 exchanging news, enquiring with exaggerated disbelief about
64 the prices of the goods displayed by merchants whose stalls
65 make progress even more difficult.^";
69 "The narrow street runs north towards the town square.
70 Local folk are pouring into the town through the gate to the
71 south, shouting greetings, offering produce for sale,
72 exchanging news, enquiring with exaggerated disbelief about
73 the prices of the goods displayed by merchants whose stalls
74 make progress even more difficult.",
76 However, that *isn't* all that we want to do. Having presented the basic
77 description, we're going to display that little line of dialogue, where
78 Wilhelm tells his son to be careful. And we want to do that only once, the
79 very first time that the street's description is displayed. If the player
80 types LOOK a few times, or moves north and then returns south to the
81 street, we're happy to see the surroundings described -- but we don't want
82 that dialogue again. This is the pair of statements that makes it happen::
84 if (self hasnt visited)
85 print "^~Stay close to me, son,~ you say,
86 ~or you'll get lost among all these people.~^";
88 The line of dialogue is produced by the ``print`` statement, the ``print``
89 statement is controlled by the ``if`` statement, and the ``if`` statement
90 is performing the test ``self hasnt visited``. In detail:
92 * ``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 * ``self``, which we met in the previous chapter, is that useful variable
105 which, within an object, always refers to that object. Since we're using
106 it in the middle of the ``street`` object, that's what it refers to.
108 So, putting it all together, ``self hasnt visited`` is true (and therefore
109 the ``print`` statement is executed) only while the ``street`` object has
110 *not* got a ``visited`` attribute. Because the interpreter automatically
111 gives rooms a ``visited`` attribute as soon as the player has been there
112 once, this test will be true only for one turn. Therefore, the line of
113 dialogue will be displayed only once: the first time the player visits the
114 street, at the very start of the game.
116 Although the primary importance of ``self`` is within class definitions, it
117 can also be convenient to use it simply within an object. Why didn't we
120 if (street hasnt visited)
121 print "^~Stay close to me, son,~ you say,
122 ~or you'll get lost among all these people.~^";
124 It's true that the effect is identical, but there are a couple of good
125 reasons for using ``self``. One: it's an aid to understanding your code
126 days or weeks after writing it.
128 If you read the line ``if (street hasnt visited)``, you need to think for a
129 moment about which object is being tested; oh, it's this one. When you
130 read ``if (self hasnt visited)``, you immediately *know* which object we're
133 Another reason is auto-plagiarism. Many times you'll find that a chunk of
134 code is useful in different situations (say, you want to repeat the
135 mechanics of the street description in another room). Rather than writing
136 everything from scratch, you'll typically use copy-and-paste to repeat the
137 routine, and then all you have to do is compose the appropriate descriptive
138 strings for the new room. If you've used ``self``, the line ``if (self
139 hasnt visited)`` is still good; if you've written instead ``if (street
140 hasnt visited)``, you'll have to change that as well. Worse, if you
141 *forget* to change it, the game will still work -- but not in the way you'd
142 intended, and the resulting bug will be quite difficult to track down.
147 The street's description mentions various items -- the gate, the people,
148 etc. -- which ought to exist within the game (albeit only in minimal form)
149 to sustain the illusion of hustle and bustle. Our ``Prop`` class is ideal
152 Prop "south gate" street
153 with name 'south' 'southern' 'wooden' 'gate',
154 description "The large wooden gate in the town walls is wide open.";
156 Prop "assorted stalls"
157 with name 'assorted' 'stalls',
158 description "Food, clothing, mountain gear; the usual stuff.",
159 found_in street below_square,
163 with name 'goods' 'produce' 'food' 'clothing' 'mountain' 'gear' 'stuff',
164 description "Nothing special catches your eye.",
165 found_in street below_square,
169 with name 'merchant' 'merchants' 'trader' 'traders',
171 "A few crooks, but mostly decent traders touting their wares
172 with raucous overstatement.",
173 found_in street below_square,
174 has animate pluralname;
177 with name 'people' 'folk' 'local' 'crowd',
178 description "Mountain folk, just like yourself.",
179 found_in [; return true; ],
180 has animate pluralname;
184 Because these objects are not referenced by other objects, we haven't
185 bothered to given them internal :samp:`{obj_ids}` (though we could have;
186 it wouldn't make any difference). However, we *have* provided
187 :samp:`{external_names}`, because these are used by the ``Prop`` class's
188 ``print_ret ... (the) self`` statement.
190 You'll see a couple of new attributes: ``animate`` marks an object as being
191 "alive", while ``pluralname`` specifies that its external name is plural
192 rather than singular. The interpreter uses these attributes to ensure that
193 messages about such objects are grammatical and appropriate (for example,
194 it will now refer to "some merchants" rather than "a merchants"). Because
195 the library handles so many situations automatically, it's hard to be sure
196 exactly what messages players may trigger; the best approach is to play
197 safe and always give an object the relevant set of attributes, even when,
198 as here, they probably won't be needed.
200 You'll also see a new ``found_in`` property, which specifies the rooms --
201 and only the rooms; ``found_in`` shouldn't be used to place objects inside
202 containers or supporters -- where this object is to appear. The stalls,
203 for example, can be EXAMINEd both in the street and below the square, so we
204 *could* have created a ``Prop`` object in each room::
206 Prop "assorted stalls" street
207 with name 'assorted' 'stalls',
208 description "Food, clothing, mountain gear; the usual stuff.",
211 Prop "assorted stalls" below_square
212 with name 'assorted' 'stalls',
213 description "Food, clothing, mountain gear; the usual stuff.",
216 but ``found_in`` does the same job more neatly -- there's only one object,
217 but it appears in both the ``street`` and ``below_square`` rooms while the
218 player's there. The local people are even more ubiquitous. In this case
219 the ``found_in`` value is an embedded routine rather than a list of rooms;
220 such a routine would generally test the value of the current location and
221 ``return true`` if it wants to be present here, or ``false`` if not. Since
222 we'd like the local people *always* to be present, in every room, we
223 ``return true`` without bothering to examine ``location``. It's as though
224 we'd written any of these, but simpler and less error prone::
227 with name 'people' 'folk' 'local' 'crowd',
228 description "Mountain folk, just like yourself.",
229 found_in street below_square south_square mid_square north_square
231 has animate pluralname;
234 with name 'people' 'folk' 'local' 'crowd',
235 description "Mountain folk, just like yourself.",
237 if (location == street || location == below_square ||
238 location == south_square || location == mid_square ||
239 location == north_square || location == marketplace)
243 has animate pluralname;
246 with name 'people' 'folk' 'local' 'crowd',
247 description "Mountain folk, just like yourself.",
249 if (location == street or below_square or south_square or
250 mid_square or north_square or marketplace) return true;
253 has animate pluralname;
255 In the second example, you'll see the ``||`` operator, to be read as "or",
256 which we mentioned near the end of "Heidi"; it combines the various
257 :samp:`location == {some_room}` comparisons so that the ``if`` statement is
258 true if *any* of those individual tests is true. And in the third example
259 we introduce the ``or`` keyword, which is a more succinct way of achieving
260 exactly the same result.
262 The player's possessions
263 ========================
265 Since our ``Initialise`` routine has already mentioned them, we might as
266 well define Wilhelm's bow and arrows::
270 description "Your trusty yew bow, strung with flax.",
273 print_ret "You're never without your trusty bow.";
277 Object quiver "quiver"
280 "Made of goatskin, it usually hangs over your left shoulder.",
283 print_ret "But it was a present from Hedwig, your wife.";
285 has container open clothing;
287 Both of these are straightforward objects, with the ``Drop``, ``Give`` and
288 ``ThrowAt`` actions being intercepted to ensure that Wilhelm is never
289 without them. The ``clothing`` attribute makes its first appearance,
290 marking both the quiver and the bow as capable of being worn (as the result
291 of a WEAR BOW command, for instance); you'll remember that our
292 ``Initialise`` routine goes on to add a ``worn`` attribute to the quiver.
294 An empty quiver is pretty useless, so here's the class used to define
295 Wilhelm's stock of arrows. This class has some unusual features::
298 with name 'arrow' 'arrows//p',
301 description "Just like all your other arrows -- sharp and true.",
304 print_ret "Your arrows are sharp, and you guard them carefully.";
307 The classes we've created so far -- ``Room``, ``Prop`` and ``Furniture`` --
308 are intended for objects which behave the same but are otherwise clearly
309 separate. For example, a table, a bed and a wardrobe would generally have
310 their own individual characteristics -- a name, a description, maybe some
311 specialised properties -- while still inheriting the general behaviour of
312 ``Furniture`` objects. The arrows aren't like this: not only do they
313 behave the same, but also they are indistinguishable one from another.
314 We're trying for this effect:
316 .. code-block:: transcript
320 a quiver (being worn)
324 where the interpreter lumps together our stock of three arrows, rather than
325 listing them individually in this clumsy fashion:
327 .. code-block:: transcript
331 a quiver (being worn)
337 The interpreter will do this for us if our objects are "indistinguishable",
338 best achieved by making them members of a class which includes both
339 ``name`` and ``plural`` properties. We define the actual arrows very
342 Arrow "arrow" quiver;
343 Arrow "arrow" quiver;
344 Arrow "arrow" quiver;
346 and you can see that we provide only two pieces of information for each
347 ``Arrow`` object: an external name in double quotes ("arrow" in each case)
348 which the interpreter uses when referring to the object, and an initial
349 location (in the quiver). That's all: no block of properties, no set of
350 attributes, and no internal identifier, because we never need to refer to
351 the individual ``Arrow`` objects within the game.
353 The name property of the class definition has an odd-looking dictionary
356 name 'arrow' 'arrows//p',
358 The word ``'arrow'`` refers to a single arrow. So also would the word
359 ``'arrows'``, unless we specifically tell the interpreter that it's a
360 plural reference. That ``//p`` marks ``'arrows'`` as being a potential
361 reference to more than one object at once, thus enabling players to type
362 TAKE ARROWS and thereby pick up as many arrows as happened to be available
363 (without it, TAKE ARROWS would have picked up one at random).
365 There are two other properties not seen previously::
370 The ``article`` property lets you define the object's indefinite article --
371 usually something like "a", "an" or "some" -- instead of letting the
372 library assign one automatically. It's a belt-and-braces (OK,
373 belt-and-suspenders) precaution: because "arrow" starts with a vowel, we
374 need to display "an arrow" not "a arrow". Most interpreters automatically
375 get this right, but just to be on the safe side, we explicitly define the
376 appropriate word. And the ``plural`` property defines the word to be used
377 when lumping several of these objects together, as in the "three arrows"
378 inventory listing. The interpreter can't just automatically slap an "s" on
379 the end; the plural of "slice of cake", for example, isn't "slice of
382 Moving further along the street
383 ===============================
385 As Wilhelm moves north towards the square, he comes to this room::
387 Room below_square "Further along the street"
389 "People are still pushing and shoving their way from the southern
390 gate towards the town square, just a little further north.
391 You recognise the owner of a fruit and vegetable stall.",
395 No surprises there, nor in most of the supporting scenery objects. ::
397 Furniture stall "fruit and vegetable stall" below_square
398 with name 'fruit' 'veg' 'vegetable' 'stall' 'table',
400 "It's really only a small table, with a big heap of potatoes,
401 some carrots and turnips, and a few apples.",
402 before [; Search: <<Examine self>>; ],
405 Prop "potatoes" below_square
406 with name 'potato' 'potatoes' 'spuds',
408 "Must be a particularly early variety... by some 300 years!",
411 Prop "fruit and vegetables" below_square
412 with name 'carrot' 'carrots' 'turnip' 'turnips' 'apples' 'vegetables',
413 description "Fine locally grown produce.",
416 The only new thing here is the ``before`` property of the fruit'n'veg
417 stall. The stall's description -- lots of items on a table -- may suggest
418 to players that they can SEARCH through the produce, maybe finding a lucky
419 beetroot or something else interesting. No such luck -- and we might as
420 well trap the attempt.
422 Having intercepted a ``Search`` action, our plan is to respond with the
423 stall's description, as though the player has typed EXAMINE THE STALL.
424 There isn't an easy way for us to stealthily slide those literal words into
425 the interpreter, but we *can* simulate the effect which they'd cause: an
426 action of ``Examine`` applied to the object stall. This rather cryptic
427 statement does the job::
431 Having diverted the ``Search`` action into an ``Examine`` action, we must
432 tell the interpreter that it doesn't need to do anything else, because
433 we've handled the action ourselves. We've done that before -- using
434 ``return true`` -- and so a first stab at the ``before`` action looks like
437 before [; Search: <Examine stall>; return true; ],
439 The two-statement sequence ``<...>; return true`` is so common that there's
440 a single statement shortcut: ``<<...>>``. Also, for exactly the same
441 reason as before, our code is clearer if we use ``self`` instead of
442 ``stall``. So this is how the property finally stands::
444 before [; Search: <<Examine self>>; ],
446 A couple of final observations before we leave this topic. The example
447 here is of an action (``Examine``) applied to an object (``self``, though
448 ``stall`` or ``noun`` would also work at this point). You can also use the
449 ``<...>`` and ``<<...>>`` statements for actions which affect no objects::
453 (representing the command LOOK), or which affect two. For example, the
454 command PUT THE BIRD IN THE NEST can be simulated with this statement::
456 <<Insert bird nest>>;
461 One of the trickiest aspects of designing a good game is to provide
462 satisfying interaction with other characters. It's hard enough to code
463 inanimate objects which provoke appropriate responses to whatever actions
464 the player character (PC) might attempt. That all gets much worse once
465 those "other objects" are living creatures -- non-player characters (NPCs)
466 -- with, supposedly, minds of their own. A good NPC might move around
467 independently, perform actions with a purpose, initiate conversations,
468 respond to what you say and do (and even to what you *don't* say or do); it
469 can be a real nightmare.
471 But not here: we've kept our three NPCs -- Helga, Walter and the vogt -- as
472 simple as possible. Nevertheless, we can establish some fundamental
473 principles; here's the class upon which we base our NPCs::
477 Answer,Ask,Order,Tell:
478 print_ret "Just use T[ALK] [TO ", (the) self, "].";
482 The most important thing here is the ``animate`` attribute -- that's what
483 defines an object as an NPC, and causes the interpreter to treat it a
484 little differently -- for example, TAKE HELGA results in "I don't suppose
485 Helga would care for that".
487 The ``animate`` attribute also brings into play nine extra actions which
488 can be applied only to animate objects: ``Answer``, ``Ask``, ``Order`` and
489 ``Tell`` are all associated with speech, and ``Attack``, ``Kiss``,
490 ``Show``, ``ThrowAt`` and ``WakeOther`` are associated with non-verbal
491 interaction. Additionally, a new ``life`` property -- very similar to
492 ``before`` -- can be defined to intercept them. Here we use it to trap
493 speech-related commands such as ASK HELGA ABOUT APPLE and TELL WALTER ABOUT
494 BABIES, telling players that in this game we've implemented only a simpler
495 TALK verb (which we describe in "Verbs, verbs, verbs" on page 111).
497 Based on the NPC class we've created, here's Helga::
499 NPC stallholder "Helga" below_square
500 with name 'stallholder' 'greengrocer' 'monger' 'shopkeeper' 'merchant'
501 'owner' 'Helga' 'dress' 'scarf' 'headscarf',
503 "Helga is a plump, cheerful woman,
504 concealed beneath a shapeless dress and a spotted headscarf.",
506 print "Helga pauses from sorting potatoes
507 to give you a cheery wave.^";
508 if (location hasnt visited) {
509 move apple to player;
510 print "^~Hello, Wilhelm, it's a fine day for trade! Is this
511 young Walter? My, how he's grown. Here's an apple for him
512 -- tell him to mind that scabby part, but the rest's good
513 enough. How's Frau Tell? Give her my best wishes.~^";
516 times_spoken_to 0, ! for counting the conversation topics
519 self.times_spoken_to = self.times_spoken_to + 1;
520 switch (self.times_spoken_to) {
521 1: score = score + 1;
522 print_ret "You warmly thank Helga for the apple.";
523 2: print_ret "~See you again soon.~";
530 The new attributes are ``female`` -- because we want the interpreter to
531 refer to Helga with the appropriate pronouns -- and ``proper``. The latter
532 signifies that this object's external name is a proper noun, and so
533 references to it should not be preceded by "a" or "the": you wouldn't want
534 to display "You can see a Helga here" or "I don't suppose the Helga would
535 care for that". You may notice the library variable ``score`` being
536 incremented. This variable holds the number of points that the player has
537 scored; when it changes like this, the interpreter tells the player that
538 "Your score has just gone up by one point".
540 There are also ``life`` and ``times_spoken_to`` properties (which we'll
541 talk about in "William Tell: the end is nigh" on page 103) and an
542 ``initial`` property.
544 ``initial`` is used when the interpreter is describing a room and listing
545 the objects initial you can see there. If we *didn't* define it, you'd get
548 .. code-block:: transcript
550 Further along the street
551 People are still pushing and shoving their way from the southern gate towards
552 the town square, just a little further north. You recognise the owner of a fruit
555 You can see Helga here.
559 but we want to introduce Helga in a more interactive manner, and that's
560 what the ``initial`` property is for: it replaces the standard "You can see
561 *object* here" with a tailored message of your own design. The value of an
562 ``initial`` property can be either a string which is to be displayed or, as
563 here, an embedded routine. This one is pretty similar to the
564 ``description`` property that we defined for the street: something that's
565 *always* printed (Helga pauses...) and something that's printed only on the
566 first occasion ("Hello, Wilhelm, it's a fine day... "):
568 .. code-block:: transcript
570 Further along the street
571 People are still pushing and shoving their way from the southern gate towards
572 the town square, just a little further north. You recognise the owner of a fruit
575 Helga pauses from sorting potatoes to give you a cheery wave.
577 "Hello, Wilhelm, it's a fine day for trade! Is this young Walter? My, how he's
578 grown. Here's an apple for him -- tell him to mind that scabby part, but the
579 rest's good enough. How's Frau Tell? Give her my best wishes."
583 But it's not quite the same as the street's description routine. First, we
584 need a slightly different ``if`` test: ``self hasnt visited`` works fine
585 for a room object, but this routine is part of an object *in* a room;
586 instead we could use either ``below_square hasnt visited`` or (better)
587 ``location hasnt visited`` -- since ``location`` is the library variable
588 that refers to the room where the player currently is. And second, some
589 curly braces ``{...}`` have appeared: why?
591 On Wilhelm's first visit to this room, we need to do two things:
593 * ensure that Wilhelm is in possession of an apple, because that's
596 * display Helga's cheery greeting.
598 The ``move`` statement does the first of those, and the ``print`` statement
599 does the second. And both statements need to be controlled by the ``if``
600 statement. So far, we've used an ``if`` statement twice, in both cases to
601 control a single following statement. ::
603 if (nest in branch) deadflag = 2;
605 if (self hasnt visited)
606 print "^~Stay close to me, son,~ you say,
607 ~or you'll get lost among all these people.~^";
609 That's what an ``if`` does -- it controls whether the following statement
610 is executed or not. So how can we control two statements at once? Well,
611 we *could* write two ``if`` statements::
613 if (location hasnt visited)
614 move apple to player;
615 if (location hasnt visited)
616 print "^~Hello, Wilhelm, it's a fine day for trade! Is this
617 young Walter? My, how he's grown. Here's an apple for him
618 -- tell him to mind that scabby part, but the rest's good
619 enough. How's Frau Tell? Give her my best wishes.~^";
621 but that's unbearably clumsy; instead, we use the braces to group the
622 ``move`` and ``print`` statement into a **statement block** (sometimes
623 known as a code block) which counts as a single statement for the purposes
624 of control by the ``if`` statement. ::
626 if (location hasnt visited) {
627 move apple to player;
628 print "^~Hello, Wilhelm, it's a fine day for trade! Is this
629 young Walter? My, how he's grown. Here's an apple for him
630 -- tell him to mind that scabby part, but the rest's good
631 enough. How's Frau Tell? Give her my best wishes.~^";
634 A statement block can contain one, two, ten, a hundred statements; it
635 doesn't matter -- they're all treated as one unit by ``if`` (and by
636 ``objectloop``, which we meet later, and by ``do``, ``for`` and ``while``,
637 all of them loop statements that we don't encounter in this guide).
641 The exact positioning of the braces is a matter of personal choice. We
650 but other designers have their own preferences, including::
671 Although we've not yet needed to use it, now would probably be a good time
672 to mention the ``else`` extension to the ``if`` statement. Sometimes we
673 want to execute one statement block if a certain condition is true, and a
674 different statement block if it's not true. Again, we *could* write two
677 if (location has visited) {
682 if (location hasnt visited) {
688 but that's hardly an elegant approach; an ``else`` clause does the job more
691 if (location has visited) {
702 We've done a lot of scene-setting, but the real action is still to come.
703 Next, it's time to define the town square, and create a confrontation
704 between Wilhelm and the vogt's soldiers. (But first, see again
705 "Compile-as-you-go" on page 233 if you're typing in the game as you read
projects / ibg.git / blob