appendices/c.rst

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