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