appendices/c.rst

   1 .. raw:: latex
   2
   3    \newpage
   4
   5 ======================================
   6  Appendix C -- "William Tell" story
   7 ======================================
   8
   9
  10 .. only:: html
  11
  12   .. image:: /images/picW.png
  13      :align: left
  14
  15 .. raw:: latex
  16
  17     \dropcap{w}
  18
  19 illiam Tell, our second game, is also very straightforward. See "William
  20 Tell: a tale is born" on page 69, "William Tell: the early years" on
  21 page 79, "William Tell: in his prime" on page 91 and "William Tell: the
  22 end is nigh" on page 103.
  23
  24 Transcript of play
  25 ==================
  26
  27 .. literalinclude:: /examples/Tell.txt
  28    :language: transcript
  29
  30 Game source code
  31 ================
  32
  33 .. literalinclude:: /examples/Tell.inf
  34    :language: inform6
  35
  36 Compile-as-you-go
  37 =================
  38
  39 Your understanding of how the "William Tell" game works will be
  40 considerably enhanced if you type in the code for yourself as you read
  41 through the guide. However, it takes us four chapters to describe the
  42 game, which isn't complete and playable until the end of Chapter 9. Even
  43 if you make no mistakes in your typing, the game won't compile without
  44 errors before that point, because of references in earlier chapters to
  45 objects which aren't presented until later chapters (for example,
  46 Chapter 6 mentions the ``bow`` and ``quiver`` objects, but we don't
  47 define them until Chapter 7). This is a bit of a nuisance, because as a
  48 general rule we advise you to compile frequently -- more or less after
  49 every change you make to a game -- in order to detect syntax and
  50 spelling mistakes as soon as possible.
  51
  52 Fortunately, there's a fairly easy way round the difficulty, though it
  53 involves a little bit of cheating. The trick is temporarily to add
  54 minimal definitions -- often called "stubs" -- of the objects whose full
  55 definitions have yet to be provided.
  56
  57 For example, if you try to compile the game in the state that it's
  58 reached by the end of Chapter 6, you’ll get this::
  59
  60         Tell.inf(16): Warning: Class "Room" declared but not used
  61         Tell.inf(19): Warning: Class "Prop" declared but not used
  62         Tell.inf(27): Warning: Class "Furniture" declared but not used
  63         Tell.inf(44): Error: No such constant as "street"
  64         Tell.inf(46): Error: No such constant as "bow"
  65         Tell.inf(47): Error: No such constant as "quiver"
  66         Compiled with 3 errors and 3 warnings
  67
  68 However, by adding these lines to the end of your game file::
  69
  70         ! ===============================================================
  71         ! TEMPORARY DEFINITIONS NEEDED TO COMPILE AT THE END OF CHAPTER 6
  72
  73         Room    street;
  74         Object  bow;
  75         Object  quiver;
  76
  77 a compilation should now give only this::
  78
  79         Tell.inf(19): Warning: Class "Prop" declared but not used
  80         Tell.inf(27): Warning: Class "Furniture" declared but not used
  81         Compiled with 2 warnings
  82
  83 That's a lot better. It's not worth worrying about those warnings, since
  84 it's easy to understand where they come from; anyway, they'll go away
  85 shortly. More important, there are no errors, which means that you've
  86 probably not made any major typing mistakes. It also means that the
  87 compiler has created a story file, so you can try "playing" the game. If
  88 you do, though, you'll get this::
  89
  90         William Tell
  91         A simple Inform example
  92         by Roger Firth and Sonja Kesserich.
  93         Release 3 / Serial number 040804 / Inform v6.30 Library 6/11 SD
  94
  95         (street)
  96         ** Library error 11 (27,0) **
  97         ** The room "(street)" has no "description" property **
  98         >
  99
 100 Whoops! We've fallen foul of Inform's rule saying that every room must
 101 have a ``description`` property, to be displayed by the interpreter when
 102 you enter that room. Our ``street`` stub hasn't got a ``description``,
 103 so although the game compiles successfully, it still causes an error to
 104 be reported at run-time.
 105
 106 The best way round this is to extend the definition of our ``Room``
 107 class, thus::
 108
 109         Class  Room
 110           with description "UNDER CONSTRUCTION",
 111           has  light;
 112
 113 By doing this, we ensure that *every* room has a description of some
 114 form; normally we'd override this default value with something
 115 meaningful -- "The narrow street runs north towards the town square..."
 116 and so on -- by including a ``description`` property in the object's
 117 definition. However, in a stub object used only for testing, a default
 118 description is sufficient (and less trouble)::
 119
 120         William Tell
 121         A simple Inform example
 122         by Roger Firth and Sonja Kesserich.
 123         Release 3 / Serial number 040804 / Inform v6.30 Library 6/11 SD
 124
 125         (street)
 126         UNDER CONSTRUCTION
 127
 128         >INVENTORY
 129         You are carrying:
 130           a (quiver) (being worn)
 131           a (bow)
 132
 133         >EXAMINE QUIVER
 134         You can't see any such thing.
 135
 136         >
 137
 138 You'll notice a couple of interesting points. Because we didn't supply
 139 external names with our ``street`` , ``bow`` and ``quiver`` stubs, the
 140 compiler has provided some for us -- ``(street)`` , ``(bow)`` and
 141 ``(quiver)`` -- simply by adding parentheses around the internal IDs
 142 which we used. And, because our ``bow`` and ``quiver`` stubs have no
 143 ``name`` properties, we can't actually refer to those objects when
 144 playing the game. Neither of these points would be acceptable in a
 145 finished game, but for testing purposes at this early stage -- they'll
 146 do.
 147
 148 So far, we've seen how the addition of three temporary object
 149 definitions enables us to compile the incomplete game, in its state at
 150 the end of Chapter 6. But once we reach the end of Chapter 7, things
 151 have moved on, and we now need a different set of stub objects. For a
 152 test compilation at this point, remove the previous set of stubs, and
 153 instead add these -- ``south_square`` and ``apple`` objects, and a dummy
 154 action handler to satisfy the ``Talk`` action in Helga’s life property::
 155
 156         ! ===============================================================
 157         ! TEMPORARY DEFINITIONS NEEDED TO COMPILE AT THE END OF CHAPTER 7
 158
 159         Room    south_square;
 160         Object  apple;
 161
 162         [ TalkSub; ];
 163
 164 Similarly, at the end of Chapter 8, replace the previous stubs by these
 165 if you wish to check that the game compiles::
 166
 167         ! ===============================================================
 168         ! TEMPORARY DEFINITIONS NEEDED TO COMPILE AT THE END OF CHAPTER 8
 169         Room    marketplace;
 170         Object  apple;
 171         NPC     son;
 172
 173         [ TalkSub; ];
 174         [ FireAtSub; ];
 175         [ SaluteSub; ];
 176
 177 Finally, by the end of Chapter 9 the game is complete, so you can delete
 178 the stubs altogether.
 179
 180 Used with care, this technique of creating a few minimal stub objects
 181 can be convenient -- it enables you to "sketch" a portion of your game
 182 in outline form, and to compile and test the game in that state, without
 183 needing to create complete object definitions. However, you've got very
 184 little interaction with your stubs, so don't create too many of them.
 185 And of course, never forget to flesh out the stubs into full definitions
 186 as soon as you can.